Diagrama de Ladder Logic

Sobre diagramas de ladder logic

Ladder logic é a linguagem de programação gráfica usada para descrever programas de controle em Controladores Lógicos Programáveis (CLPs) — os computadores industriais que executam automação de fábricas, sistemas de climatização, linhas de esteira e equipamentos de processo em todo o mundo. O nome vem da aparência do diagrama: dois trilhos verticais de alimentação conectados por rungs horizontais, cada rung expressando uma regra de condição-para-ação. Eletricistas e engenheiros de controle o adotaram porque espelha os esquemas de contatos de relés que já conheciam.

O Schematex segue a IEC 61131-3:2013, o padrão internacional para linguagens de programação de CLP, com convenções de nomes de endereço de tag Allen-Bradley (Rockwell) comuns na prática industrial norte-americana. Esta página documenta o que o parser aceita atualmente.

1. Seu primeiro diagrama ladder

O menor programa ladder útil: um rung, dois contatos, uma bobina.

Quatro regras cobrem 80% do uso:

1. Comece com ladder, opcionalmente seguido de um título entre aspas.
2. Cada rung começa com rung N "comentário opcional": em sua própria linha. Os dois-pontos finais são opcionais.
3. Os elementos são listados um por linha, recuados abaixo do rung — da esquerda para a direita significa série (lógica AND).
4. Um bloco parallel: / branch: introduz lógica OR. Cada branch contém sua própria lista de elementos.

Comentários podem começar com #, // ou Mermaid-style %% em sua própria linha.

2. Contatos

Os contatos representam condições de entrada — eles passam energia quando o bit associado corresponde ao tipo de contato.

Sintaxe:

XIC(tag)
XIC(tag, "address")
XIC(tag, "address", name="Description")
XIC(tag, address="address", name="Description")

• tag — obrigatório. O nome da tag do CLP (exibido abaixo do símbolo de contato).
• "address" — segundo argumento posicional opcional. O endereço de E/S (ex.: "IN 1.0", "BIT 3.1").
• name="…" — argumento chave-valor opcional. Descrição legível por humanos (exibida acima do símbolo).

3. Bobinas

As bobinas representam ações de saída — elas atuam em um bit de tag quando o rung tem fluxo de energia.

Sintaxe: idêntica aos contatos — OTE(tag), OTE(tag, "address"), OTE(tag, "address", name="…").

OTL e OTU são usados em pares para construir flip-flops Set/Reset. O último rung a escrever prevalece.

4. Blocos de função

Os blocos de função realizam operações de timer, contador, matemática e comparação. Eles aparecem inline em um rung e têm parâmetros de palavra-chave após o argumento de tag obrigatório.

4.1 Timers

TON(timer_tag, PT=5000)

A tag do timer armazena o tempo decorrido. O bit Q do timer (saída done) é acessado pelo nome da tag em contatos downstream.

4.2 Contadores

CTU(cycle_counter, PV=100)

4.3 Matemática

ADD(result_tag, IN1=setpoint, IN2=offset)
MOV(dest_tag, IN1=source_tag)

4.4 Comparações

EQU(compare_tag, IN1=speed_actual, IN2=speed_setpoint)

5. Branches paralelos

Um bloco parallel: introduz lógica OR — o rung tem energia se qualquer branch conduzir. Cada branch é um sub-bloco branch: com seus elementos recuados abaixo.

parallel:
  branch:
    XIC(LOCAL_START)
  branch:
    XIC(REMOTE_START)

Os branches em um parallel: são avaliados simultaneamente. O bloco fecha quando o recuo retorna ao nível anterior ao parallel:.

Regras:

• parallel: deve aparecer dentro de um rung.
• branch: deve aparecer dentro de um parallel: — usá-lo sozinho gera LadderParseError.
• Cada branch contém um ou mais elementos.
• Elementos após o bloco parallel: são em série com ele (lógica AND).

6. Rótulos e comentários

• Título: ladder "Motor Control" — apenas na primeira linha, string entre aspas.
• Número do rung: inteiro obrigatório após rung.
• Comentário do rung: string opcional entre aspas após o número do rung, antes do dois-pontos opcional: rung 3 "Run indicator": ou rung 3 "Run indicator".
• Tag: primeiro argumento dentro dos parênteses — exibido abaixo do símbolo.
• Endereço: segundo argumento posicional (entre aspas): XIC(START_PB, "IN 1.0").
• Name: argumento de palavra-chave name="…" — descrição legível por humanos exibida acima do símbolo.
• Comentários de linha: #, // ou %% no início de uma linha (após espaços em branco iniciais). Os mesmos marcadores também iniciam comentários ao final de linha.

7. Palavras reservadas e escape

Reservadas no início de linha (sem distinção de maiúsculas): ladder, rung, parallel:, branch:.

Nomes de elementos são todos ASCII maiúsculos: XIC, XIO, ONS, OSF, OTE, OTL, OTU, OTN, TON, TOFF, TP, CTU, CTD, CTUD, ADD, SUB, MUL, DIV, MOV, EQU, NEQ, GRT, LES, GEQ, LEQ.

IDs de tag — devem corresponder a [A-Z][A-Z0-9_]* (o parser reconhece [A-Z][A-Z0-9_]* como prefixo de nome de elemento). Tags em minúsculas são aceitas dentro dos parênteses.

Strings entre aspas em argumentos de endereço ou name devem usar aspas duplas "…".

8. Erros comuns

9. Gramática (EBNF)

document      = header NEWLINE rung+

header        = "ladder" ( WS quoted-string )? NEWLINE
quoted-string = '"' any-char-but-quote* '"'

rung          = "rung" WS integer ( WS quoted-string )? ":"? NEWLINE
                  element+

element       = contact-line
              | coil-line
              | fb-line
              | parallel-block

contact-line  = contact-type "(" tag ( "," arg )* ")" NEWLINE
contact-type  = "XIC" | "XIO" | "ONS" | "OSF"

coil-line     = coil-type "(" tag ( "," arg )* ")" NEWLINE
coil-type     = "OTE" | "OTL" | "OTU" | "OTN" | "RES"

fb-line       = fb-type "(" tag ( "," arg )* ")" NEWLINE
fb-type       = "TON" | "TOFF" | "TP"
              | "CTU" | "CTD" | "CTUD"
              | "ADD" | "SUB" | "MUL" | "DIV" | "MOV"
              | "EQU" | "NEQ" | "GRT" | "LES" | "GEQ" | "LEQ"

arg           = quoted-string             // posicional (address)
              | key "=" quoted-string     // keyword (ex.: name="…")
              | key "=" number            // keyword (ex.: PT=5000)

parallel-block = INDENT≥2 "parallel:" NEWLINE
                   ( INDENT branch-block )+

branch-block   = "branch:" NEWLINE
                   ( INDENT element )+

tag           = [A-Za-z][A-Za-z0-9_]*
key           = [A-Za-z][A-Za-z0-9_]*
integer       = [0-9]+
number        = [0-9]+ ( "." [0-9]+ )?
comment       = ( "#" | "//" | "%%" ) any NEWLINE

Fonte autoritativa: src/diagrams/ladder/parser.ts. Se houver divergência com o parser, o parser prevalece — abra uma issue.

10. Conformidade com o padrão

A ladder logic do Schematex segue a IEC 61131-3:2013 Parte 3 para a linguagem Ladder Diagram e usa convenções de nome-endereço-tag Allen-Bradley (Rockwell) comuns na prática de CLP norte-americana.

O que está implementado hoje:

• ✅ Quatro tipos de contato: XIC (NA), XIO (NF), ONS (borda de subida), OSF (borda de descida)
• ✅ Cinco tipos de bobina: OTE (saída), OTL (latch/set), OTU (unlatch/reset), OTN (negar), RES (reset de contador/timer)
• ✅ Três blocos de função timer: TON, TOFF, TP com parâmetro PT= em milissegundos
• ✅ Três blocos de função contador: CTU, CTD, CTUD com parâmetro PV= inteiro
• ✅ Blocos de função matemática: ADD, SUB, MUL, DIV, MOV
• ✅ Blocos de função de comparação: EQU, NEQ, GRT, LES, GEQ, LEQ
• ✅ Blocos paralelos / branch para lógica OR
• ✅ Anotações de tag, address e name per convenções Allen-Bradley Studio 5000
• ⏳ Timer retentivo (RTO) — no padrão; ainda não no parser
• ⏳ Instruções Jump (JMP) / Label (LBL)
• ⏳ Zona Master Control Reset (MCR)
• ⏳ Instruções imediatas de E/S (IIN, IOT)
• ⏳ Elementos de Structured Text ou Function Block Diagram embutidos em rungs

Referências:

• IEC 61131-3:2013 — Programmable controllers, Part 3: Programming languages
• NEMA ICS 1-2009 — General Standards for Industrial Control and Systems
• Rockwell Automation Studio 5000 Logix Designer — Ladder Diagram Programming Manual

11. Exemplos relacionados

12. Roadmap

Planejado — ainda não parseável. Não use esses recursos em DSL gerado hoje; o parser irá rejeitá-los ou ignorá-los.

• Retentive Timer On (RTO) — timer que mantém o tempo decorrido durante perda de energia; requer um contato de reset separado.
• Jump (JMP) / Label (LBL) — ramifica para um rung rotulado para pular lógica condicionalmente; usado em programas grandes para desempenho.
• Zona Master Control Reset (MCR) — uma zona delimitada que desenergiza todas as saídas não retentivas quando a entrada MCR é falsa.
• Structured text em rungs — avaliação de expressão inline (ex.: CALC(result = a * b + c)).
• E/S imediata (IIN / IOT) — força o ciclo de E/S no meio do programa para controle de tempo crítico.

Acompanhe as issues do GitHub se precisar de algum desses recursos mais cedo.