# Receitas

> Os setpoints que uma execução escreve: um conjunto instantâneo aplicado no Início, ou um perfil temporizado de Degrau, Rampa e Patamar, cada um com o bloco de finalização que toda execução escreve ao terminar.

Uma **receita** escreve os canais graváveis do modelo. Uma receita **instantânea** é um conjunto de
setpoints aplicado uma vez, quando uma execução começa; uma receita **temporizada** é um perfil
ordenado de segmentos de Degrau, Rampa e Patamar, conduzido pelo relógio da própria execução. As
duas podem terminar num bloco de **finalização**, o estado seguro escrito sempre que a execução
termina. Toda escrita passa pelo único [funil de escrita](logic#writing-values) registrado em diário
e é gravada no arquivo da execução como executada. As receitas vivem em Process > Modelos > modelo >
Preparação > **Receitas** e exigem a permissão **Editar receitas e avaliações**.

## A pasta Receitas {#the-recipes-folder}

Selecionar a linha **Receitas** abre a página da pasta ("Valores de setpoint que um procedimento
aplica quando uma execução começa, escritos pelo funil único e registrados como foram executados.") com um
cartão por receita, por nome; clicar num cartão o abre, e o X o remove. Sem nenhuma, a página diz
"Nenhuma receita ainda. Adicione uma."

| Comando | O que faz | Fica cinza quando (situação) | Não é desenhado quando (papel) |
| --- | --- | --- | --- |
| **Receita** (barra de detalhe, com a pasta selecionada; clique direito **Adicionar receita**) | Acrescenta `Receita <n>`: Instantânea, Em caso de falha Pausar, sem setpoints. A linha entra no grupo dela, destacada e rolada até ficar à vista ali; o cartão dela a abre. | Alguma unidade tem uma execução, ou o runtime está parado. | Sem Editar receitas e avaliações. |

## A página da receita {#the-recipes-page}

O cabeçalho carrega o nome, a frase "Valores de setpoint que um procedimento aplica quando uma
execução começa, escritos pelo funil único e registrados como foram executados." e uma pílula com o tipo.
Todo campo salva sozinho, e toda edição redesenha a prévia do perfil.

### Definição {#definition}

| Campo | O que é | Valores / padrão | Efeito |
| --- | --- | --- | --- |
| **Nome** | Como a receita se chama na árvore, no seletor de Receita de um procedimento e no seletor Aplicar receita de um painel. | Texto livre; `Receita <n>` na criação. | Renomeia a linha. |
| **Tipo** | A forma da receita. | **Instantânea** (padrão): um conjunto de setpoints aplicado uma vez no Início. **Temporizada**: um perfil ordenado de Degrau / Rampa / Patamar no relógio próprio dela. | Troca a página entre as duas formas abaixo. Os setpoints e os segmentos já digitados são mantidos; só a forma que o tipo lê é desenhada. O bloco guardado não é aplicado nem reservado: uma execução escreve e trava apenas o que o tipo em vigor escreve. Um procedimento admite apenas uma receita cujo tipo caiba no modo dele. |
| **Em caso de falha** (só na temporizada) | O que o perfil faz quando uma escrita falha ou um valor de que ele precisa está ilegível. | **Pausar** (padrão), **Continuar**, **Abortar**; veja a tabela sob a forma temporizada. | A regra da receita; cada segmento pode sobrepô-la. |
| **Observações** | Texto livre para quem lê a receita. | Várias linhas; vazio por padrão. | Nada mais. |

### Valores {#values}

Setpoints e alvos são digitados como texto e convertidos para o tipo do canal quando são aplicados,
na cultura invariante:

| Tipo do canal | Literais aceitos |
| --- | --- |
| Booleano | `true`, `false`, `1`, `0` |
| Inteiro | Um número inteiro, com `.` nunca usado como separador |
| Número decimal | Um número com `.` como separador decimal (`12.5`, `1e-3`); numa estação que escreve decimais com vírgula o campo também aceita `12,5` e o guarda como `12.5` |
| Texto | Qualquer texto, como digitado |
| Data e hora | Uma data e hora de ida e volta (`2026-09-02T14:30:00+00:00`) |

Um literal que não cabe no tipo do canal nunca é escrito: a escrita é gravada como falha no arquivo
da execução e tratada pela regra de falha. Toda grade de linhas de canal desta página oferece a uma
linha apenas os canais graváveis que as outras linhas da mesma grade não tomaram, então um canal é
escrito uma vez por conjunto e uma vez por segmento; quando todo canal gravável está tomado, o botão
que acrescenta uma linha fica cinza com "Todo canal gravável já tem um setpoint aqui." (ou "… um
alvo neste segmento."), e sem nenhum canal gravável, com "Este modelo ainda não tem canais
graváveis."

## Uma receita instantânea {#an-instant-recipe}

Dois cartões independentes, cada um encabeçado por um botão **Valor de setpoint** que acrescenta uma linha no
primeiro canal gravável livre, com o valor `0`:

| Cartão | O que ele escreve |
| --- | --- |
| **Setpoints (aplicados na partida)** | Escritos uma vez, no Início, antes de a execução gravar qualquer coisa. |
| **Finalização (estado seguro)** | "Escrita sempre que a execução termina: conclusão, parada ou aborto." |

As duas grades compartilham as mesmas colunas:

| Coluna | O que é | Valores |
| --- | --- | --- |
| **Canal** | O canal gravável escrito, como `Ch<número> · <nome>`. | Canais Somente escrita e Leitura e escrita ainda não tomados nesta grade. |
| **Valor** | O literal escrito. | Veja Valores. |
| Ação de linha | **Remover** pergunta "Excluir setpoint": o nome do canal, "Isso remove o setpoint da receita." | |

## Uma receita temporizada {#a-temporal-recipe}

A forma temporizada desenha primeiro o perfil, depois os segmentos ao lado daquele escolhido neles,
e depois o bloco de finalização.

### Perfil temporizado {#temporal-profile}

O gráfico é a própria receita: uma série por canal numérico que os segmentos miram, rotulada
`<nome> [<unidade>]`, desenhada como a curva por partes que os segmentos constroem (um Degrau salta
e se mantém, uma Rampa inclina a partir do valor que chega nela, um Patamar ou um segmento sem alvo
se mantém), sobre o tempo acumulado em segundos. Um alvo num canal que não é numérico não é
desenhado. O gráfico carrega a barra de ferramentas que todo gráfico tem e pode ser aberto numa
janela própria (veja [Gráficos](view-charts)); a página do procedimento desenha o mesmo perfil sob
o estágio Aplicar dela.

### Segmentos {#segments}

A lista é encabeçada por **Segmentos**, e o botão **Segmento** dela acrescenta um Degrau de 60000 ms
sem alvos e o escolhe. Clicar numa linha a abre na coluna **Alvos do segmento**; sem nada escolhido,
a coluna diz "Selecione um segmento para editá-lo inteiro num lugar só, com os alvos até os quais
ele conduz."

| Coluna | O que é | Valores / padrão |
| --- | --- | --- |
| **Tipo** | A forma que o segmento põe no perfil; cada opção carrega aquela forma ao lado do nome dela. | **Degrau** (padrão), **Rampa**, **Patamar**. |
| **Duração (ms)** | Quanto tempo a receita fica no segmento antes de passar para o próximo. | Um número de milissegundos; 60000 na criação. O campo não aceita número negativo: a entrada é recusada, a nota diz isso embaixo do campo, e o valor anterior volta. |
| **Contagem do tempo** | Quando este segmento começa a contar o próprio tempo: depois de o equipamento ter aceitado os setpoints, ou no instante em que eles são entregues. | **Aguardar chegar ao equipamento** · **Enviar e seguir**. Um Degrau nasce aguardando, uma Rampa nasce enviando; mudar o **Tipo** do segmento repõe o valor de nascimento do tipo novo, e o que for escolhido depois disso vale. Um Patamar não escreve nada, então a célula dele fica vazia e não há o que escolher. |
| **Em caso de falha** | Se uma falha aqui segue a regra da receita ou uma própria deste segmento. | **(receita)** (padrão: herdar), **Pausar**, **Continuar**, **Abortar**. |
| **Alvos** | Até onde o segmento conduz, numa linha: `<canal> = <valor>, …`. Um Patamar não conduz nada, então ele se lê vazio. | Somente leitura; editado na coluna. |
| Ação de linha | **Remover** pergunta "Excluir segmento": `Segmento <n> · <Tipo>`, "Isso remove o segmento e os alvos dele da receita." | |

| Tipo de segmento | O que ele faz |
| --- | --- |
| **Degrau** | Escreve os alvos dele no início do segmento e depois permanece pela duração (um Degrau pode permanecer 0 ms). |
| **Rampa** | Conduz cada canal mirado linearmente do último valor comandado dele (ou do valor atual dele, quando nada foi comandado ainda) até o alvo, ao longo da duração. A rampa leva o canal entre duas leituras, então o seletor de alvo dela só oferece os canais que guardam número: um canal de texto ou de data e hora fica na lista sem poder ser escolhido, dizendo que um degrau escreve nele uma vez só. |
| **Patamar** | Segura os últimos valores comandados pela duração; não escreve nada e não carrega alvos. |

A coluna, encabeçada por `Segmento <n> · <Tipo>`, repete os mesmos campos com uma legenda e o efeito do
valor em vigor sob cada um:

| Campo | Legenda | Efeito |
| --- | --- | --- |
| **Tipo** | A forma ao lado de cada opção. | |
| **Duração (ms)** | "Quanto tempo a receita fica neste segmento antes de passar para o próximo." | "Roda por 1 min 30 s." ("tempo nenhum" para 0). |
| **Contagem do tempo** | "Quando este segmento começa a contar o próprio tempo." | "O tempo só corre depois de os setpoints chegarem ao equipamento; uma recusa ou um tempo esgotado aciona a regra de falha." ou "Envia e conta o tempo; o que o equipamento responde é apenas registrado." |
| **Em caso de falha** | "Se uma falha aqui é tratada como a receita manda, ou de outro jeito que só este segmento pede." | "Segue a receita: Pausar." ou "Este segmento passa por cima da receita: Abortar." |

A contagem do tempo é uma propriedade do segmento e de nada acima dele: não existe campo válido
para a receita inteira, porque um perfil cujos segmentos contam de jeitos diferentes é um perfil
legítimo, e uma chave só sobre tudo seria apenas um segundo lugar dizendo a mesma coisa. Também
não é um ajuste de falha. O que ela decide é o relógio; o que uma falha faz é a regra **Em caso de
falha**, abaixo. O campo nem chega a ser desenhado num Patamar.

Sob eles, **ALVOS** guarda os alvos do segmento, com um botão **Alvo** no cabeçalho da coluna que
acrescenta uma linha no primeiro canal gravável que o segmento ainda não conduz, em `0`. Num Patamar
a grade é substituída pela frase "Um patamar mantém os valores que o perfil já alcançou, então ele
não conduz alvo nenhum próprio." e o botão fica cinza, dizendo "Um patamar mantém os valores já alcançados.
Mude o tipo para conduzir um alvo aqui."; os alvos que um Patamar carrega de um tipo anterior
continuam guardados e são ignorados pela execução, pela prévia do perfil e pela folha de percurso do
mesmo jeito:

| Coluna | O que é |
| --- | --- |
| **Canal** | O canal gravável conduzido, oferecido apenas entre os canais que os outros alvos deste segmento não tomaram. |
| **Alvo** | O literal escrito (Degrau) ou alcançado (Rampa). |
| Ação de linha | **Remover** pergunta "Excluir alvo": o nome do canal, "Isso remove o alvo do segmento." |

### Em caso de falha {#on-failure}

A regra de falha se aplica a uma receita temporizada quando uma escrita é recusada ou um valor de
que ela precisa está ilegível:

| Regra | O que a execução faz |
| --- | --- |
| **Pausar** | Congela o perfil no último setpoint e espera o operador Retomar ou Abortar. O datalog continua gravando. |
| **Continuar** | Grava a falha como executada e segue em frente; o canal que falhou é pulado pelo resto do segmento. |
| **Abortar** | Escreve o bloco de finalização e encerra a execução como abortada. |

A regra responde por uma falha de que a receita **fica sabendo**, e o que a receita sabe depende de
ela ter ficado ou não para ouvir a resposta. Um problema que ela vê antes de qualquer coisa sair é
conhecimento nos dois modos; uma recusa ou um silêncio do equipamento é conhecimento só onde o
segmento esperou por ele:

| O que a receita fica sabendo, e quando | Aguardar chegar ao equipamento | Enviar e seguir |
| --- | --- | --- |
| Antes de enviar: o canal não está vinculado, o valor não cabe no tipo do canal, a tag não está no runtime, outra execução segura a tag, o dispositivo já é sabido estar desconectado | A regra se aplica. | A regra se aplica do mesmo jeito: a receita soube antes de soltar. |
| O equipamento recusa o valor no fio | A regra se aplica. | Aqui não é falha: gravado como executado com o motivo, e vai para o diário. |
| O equipamento não responde a tempo | A regra se aplica. | Aqui não é falha: gravado. |
| Um setpoint que uma escrita mais nova no mesmo alvo ultrapassou antes de ele ser enviado | Não é falha. | Não é falha. |

Um setpoint ultrapassado nunca é falha em nenhum dos modos: o valor mais novo daquele alvo é o que o
equipamento recebe, e é ele que conta. Uma rampa funciona assim de propósito, cada passo
substituindo o passo anterior que ainda não saiu da fila do dispositivo.

### Finalização (estado seguro) {#finalization-safe-state}

O mesmo cartão da receita instantânea, "Escrita sempre que a execução termina: conclusão, parada ou
aborto.", com o botão **Valor de setpoint** e a grade próprios dele.

## Onde uma receita é usada {#where-a-recipe-is-used}

| Superfície | O que ela faz com a receita |
| --- | --- |
| O estágio **Aplicar** de um procedimento | O seletor oferece toda receita do modelo; uma receita cujo tipo não cabe no modo do procedimento é listada como "`<name>` (incompatível)", desabilitada, com o motivo na dica. Um procedimento Instantâneo ou Controlado aceita uma receita instantânea ou nenhuma; um Temporizado aceita uma receita temporizada ou nenhuma, e o perfil dela precisa caber dentro da janela. A frase do estágio diz o que a escolha escreve: "Escreve 4 setpoints na partida.", "Escreve 4 setpoints na partida e 2 setpoints na saída.", "Conduz 3 segmentos ao longo de 2 min 30 s e escreve 2 setpoints na saída.", ou "Nenhum setpoint é escrito." Veja [Procedimentos](process-procedures). |
| O cartão **Comandos avulsos** de um painel | **Aplicar receita** escreve os setpoints de uma receita instantânea uma vez, fora de qualquer execução, pelo funil registrado em diário e sob uma trava de vida curta; nenhum arquivo de execução é criado, e o diário é o registro. Só receitas instantâneas são oferecidas. Veja [Painéis](process-panels#the-card-catalogue). |

## O que uma execução faz com ela {#what-a-run-does-with-it}

No Início, a execução toma posse de toda origem que a receita escreve, pela duração inteira dela,
então um Início cuja receita escreve uma origem que outra execução detém é recusado pelo nome, e
toda escrita vinda de outro lugar (um campo de dashboard, um script, um cliente OPC UA) nessas
origens é recusada enquanto a execução as detém. Um conjunto instantâneo é escrito uma vez, no
Início; um perfil temporizado é percorrido segmento a segmento no relógio da execução, e um
procedimento Temporizado sem receita ainda ganha esse relógio, para que todo membro da janela
comece, se repita e termine junto. Pausar congela o relógio e Retomar o solta; o datalog continua
gravando durante uma pausa. Toda escrita vai para o diário com a execução como origem e é gravada no
arquivo da execução como executada, então quem lê depois vê o que foi realmente escrito e quando.

Um segmento, o conjunto instantâneo e o bloco de finalização entregam **todos os setpoints deles de
uma vez**, e cada um segue dali para a fila do próprio dispositivo. Uma estação cujos quatro canais
ficam em quatro dispositivos paga por isso o dispositivo mais lento uma vez, e não a soma dos
quatro, e a própria Lógica não espera nenhum deles.

O que o segmento faz em seguida é o que a **Contagem do tempo** decide. Em **Aguardar chegar ao
equipamento**, o relógio do próprio segmento não começa enquanto cada setpoint não tiver sido aceito
pelo equipamento dele: enquanto isso acontece, a unidade se lê "Aguardando os setpoints chegarem ao
equipamento" na parede da [Operação](process-operate#the-operate-page), a duração do segmento ainda
não começou a correr, e o datalog grava o tempo todo. Em **Enviar e seguir**, o relógio começa no
instante em que os setpoints são entregues, e as respostas que chegam depois são gravadas e nada
mais.

A receita instantânea no Início e o bloco de finalização sempre aguardam, sem campo e sem escolha:
uma execução não pode começar antes de o estado inicial dela ser real, e não pode ser dada por
encerrada antes de o estado seguro dela ser. As recusas deles são gravadas como executadas e, como
sempre, nunca abortam a execução.

O bloco de finalização é escrito sempre que a execução **termina**: conclusão, Parar ou Abortar. Ele
não é escrito quando a própria aplicação é fechada no meio da execução: a execução não está
terminando, e ela é retomada pausada no segmento e no ciclo persistidos dela, na inicialização
seguinte.

## Remover receita {#remove-recipe}

**Remover receita** fica no grupo de perigo da barra de detalhe com a receita selecionada, no menu de
clique direito dela, e como o X no cartão da página da pasta. Ele pergunta antes ("Excluir receita",
"Isso remove a receita do modelo."). Todo procedimento que a aplicava esvazia a referência de Receita
dele e vira uma execução sem receita. Ele exige Editar receitas e avaliações e fica cinza sob a trava
de engenharia e o runtime parado.

## O que uma receita não faz {#what-a-recipe-does-not-do}

- Ela não lê nada e não julga nada: limites são uma [avaliação](process-evaluations).
- Ela não escreve valores por unidade. Toda unidade recebe os mesmos literais nas origens vinculadas
  dela.
- Ela nunca repete uma escrita recusada; a regra de falha é a resposta inteira.
- Uma receita temporizada não pode ser disparada como comando único; só um procedimento roda um
  perfil.
- A prévia do perfil desenha apenas canais numéricos; um alvo Booleano ou Texto é escrito, mas nunca
  desenhado.