# Modbus RTU

> Modbus por um barramento serial, com a linha física modelada explicitamente e compartilhada pelos dispositivos endereçados por unidade.

O driver Modbus RTU conversa com dispositivos Modbus num barramento serial: RS-485 ou
RS-232, alcançado por uma porta COM física, um adaptador USB ou uma porta virtual ou
redirecionada. Como o barramento é fisicamente compartilhado, a topologia é
**Driver → Linha → Dispositivo → Tag**: a **linha** é dona de tudo que é elétrico (porta,
baud, formato, tempos), e cada **dispositivo** nela é dono apenas do seu endereço de
unidade, da sua leitura cíclica e das suas tags.

## Linha serial {#serial-line}

| Campo | Significado | Padrão |
| --- | --- | --- |
| **Nome** | Nome amigável do barramento. Editável a qualquer momento. | obrigatório |
| **Porta serial** | A porta do sistema operacional, por exemplo `COM3`. O campo é texto livre (portas físicas, virtuais e redirecionadas funcionam todas) e a seta ao lado dele oferece as portas que o Windows detecta no momento (com um **Atualizar** para adaptadores conectados a quente); a lista detectada é uma conveniência, nunca uma lista de permissão. | `COM1` |
| **Velocidade em baud** | Taxa de bits compartilhada por todo dispositivo do barramento. | 9600 |
| **Modo de transmissão** | Como cada dispositivo do barramento enquadra suas mensagens: **RTU**, quadros binários verificados por um CRC, ou **ASCII**, quadros escritos como texto de um dois-pontos até a quebra de linha e verificados por um LRC, que equipamentos antigos falam. Um barramento fala um só modo, por isso ele é da linha. | RTU |
| **Formato serial** | Escolha fechada entre `8N1`, `8N2`, `8E1`, `8E2`, `8O1`, `8O2`, e numa linha ASCII também `7N2`, `7E1`, `7E2`, `7O1`: o dígito são os bits de dados, a letra é a paridade (`N` nenhuma, `E` par, `O` ímpar), o último dígito são os bits de parada. Um quadro RTU precisa de 8 bits de dados, então uma linha RTU só oferece os formatos de 8 bits; um formato de 7 bits que sobrou de uma linha ASCII aparece vazio e é recusado até que outro seja escolhido. Outras larguras, paridade mark/space e 1,5 bit de parada não são suportados. | `8E1` |
| **Timeout de resposta (ms)** | Espera máxima pela resposta de uma unidade, de 100 a 60.000. Timeouts maiores acomodam equipamento lento, mas tornam mais demorado identificar unidades ausentes e concluir a descoberta. | 1000 |
| **Intervalo mínimo entre transações (ms)** | Ritmo de compatibilidade para a linha inteira, de 0 a 1000. Zero mantém só o silêncio automático do protocolo; um valor positivo pode elevá-lo, nunca reduzi-lo. | 0 |

Numa linha ASCII o silêncio descrito a seguir não se aplica: um quadro ASCII termina na quebra de linha, então o silêncio automático mostra 0 ms e o **Intervalo mínimo entre transações (ms)** é a única pausa entre quadros, como o cartão diz logo abaixo dele: "Quadros ASCII terminam com uma quebra de linha, então a linha não acrescenta silêncio próprio: este intervalo é a única pausa entre quadros." O modo de transmissão é uma configuração física, travada junto com a porta, a velocidade, o formato e o timeout de resposta enquanto a linha está habilitada; o endereço de runtime de um dispositivo numa linha ASCII termina em `/ascii`.

O próprio protocolo exige silêncio entre quadros, e a linha sempre o impõe:
em 19.200 baud ou abaixo, o silêncio automático é de 3,5 tempos de caractere, calculados
a partir do formato configurado; acima de 19.200 baud, é o 1,75 ms fixo que a
especificação recomenda. O silêncio efetivo é o **maior** entre esse piso
automático e o intervalo configurado, nunca a soma dos dois, e o painel
mostra os dois valores. Elevar o intervalo desacelera deliberadamente toda unidade da
linha; ele é um recurso de compatibilidade, não um conserto para fiação, terminação,
aterramento ou ruído.

Uma linha nova nasce **desabilitada**, para que as definições físicas dela possam ser
configuradas primeiro. Cada porta física pertence a no máximo uma linha, comparada sem
diferenciar maiúsculas de minúsculas e mesmo enquanto as linhas estão desabilitadas. O
nome e o intervalo entre transações continuam editáveis enquanto a linha roda (uma edição
de tempo vale sem ciclar a porta); a porta, o baud, o formato e o timeout de resposta
ficam travados enquanto a linha está habilitada: desabilite-a e salve primeiro.
Desabilitar uma linha interrompe a comunicação de todos os dispositivos dela sem alterar
as escolhas individuais de Habilitado deles.

A linha reporta o transporte físico separadamente dos dispositivos dela: **Desligado**,
**Ocioso** (nenhum dispositivo habilitado), **Conectando**, **Conectado** ou **Falha de
porta**, com um diagnóstico. Excluir uma linha vazia remove só a linha; excluir uma
que contém dispositivos pede confirmação explícita e exclui também esses dispositivos
e as tags deles.

## Dispositivo {#device}

| Campo | Significado | Padrão |
| --- | --- | --- |
| **Linha serial** | Fixa: um dispositivo é criado sob a linha dele e herda a tupla física, mostrada somente leitura no painel. Adicione o dispositivo sob a linha pretendida. | a linha sob a qual ele é adicionado |
| **Unit ID** | O endereço Modbus do dispositivo no barramento, de 1 a 247, único dentro da linha (dispositivos desabilitados incluídos). | 1 |
| **Intervalo de leitura (ms)** | Taxa de leitura padrão para as tags que não a sobrepõem. | 1000 |

O endereço interno do runtime é
`modbus+rtu://<line-id>/<port>/<baud>/<format>/<timeout>/<unitId>/<interval>`:
ele carrega a identidade estável da linha e as definições físicas completas, nunca o
nome amigável dela.

## Comportamento da linha compartilhada {#shared-line-behavior}

O driver abre **uma sessão serial por linha** e serializa toda requisição
de todo dispositivo por um único despachante, então leituras e escritas nunca se
sobrepõem no barramento. Uma escrita pendente toma a próxima vez livre com prioridade
limitada: escritas são atendidas rápido, mas escrever sem parar não consegue matar a
leitura cíclica de fome. Os timeouts de cada unidade são isolados, com recuo
progressivo, então um dispositivo silencioso desacelera só a si mesmo. Uma exceção
Modbus com CRC válido é um erro por requisição naquela tag: a linha continua saudável.
Só uma falha física de entrada e saída (a porta sumindo, o adaptador desconectado)
invalida a sessão compartilhada e inicia uma reabertura coordenada para a linha inteira.
O último dispositivo liberado fecha a porta.

## Endereçamento da tag {#tag-addressing}

O endereçamento de tag é idêntico ao do [Modbus TCP](driver-modbus-tcp): uma **Classe do
registrador** (Bobina (0xxxx), Entrada discreta (1xxxx), Registrador de entrada (3xxxx),
Registrador de retenção (4xxxx), derivada por padrão do tipo e do acesso da tag), um **Número do registrador** em base 0, uma
**Quantidade (registradores, vazio = automático)** automática (Boolean, Int16 e UInt16 1
registrador, Int32 e Float 2, String 4; a caixa é desenhada só em tags String, porque toda
outra largura é fixa) e as duas caixas de ordem: **Byte mais significativo primeiro (MSB first,
big-endian)** para a ordem dos bytes e **Palavra mais significativa primeiro (palavra alta
primeiro)** para a ordem das palavras (desenhada só nos tipos de dois registradores, Int32
e Float), ambas ligadas por padrão. O cartão Origem termina com **Endereço no manual**, o
endereço da tag como o manual do equipamento o imprime (o registrador de entrada 0 é 30001). Os tipos de valor suportados são os mesmos seis
(Boolean, Int16, UInt16, Int32, Float e String): Int16 e UInt16 leem um único registrador
de 16 bits, com ou sem sinal, e só a ordem de bytes se aplica a eles (a caixa da ordem de palavras não é desenhada). Os códigos de função
de leitura e escrita e os arranjos de barramento estão documentados na página
[Modbus TCP](driver-modbus-tcp) e valem aqui sem mudança.

## Descoberta {#discovery}

A descoberta sonda uma faixa de unit ids por uma linha existente e vive no painel daquela
linha:

| Campo | Significado | Padrão |
| --- | --- | --- |
| **Unit id inicial** | Primeiro unit id a sondar, de 1 a 247. | 1 |
| **Unit id final** | Último unit id, crescente a partir do inicial. | 32 |

Numa linha ASCII a sondagem é a mesma requisição num quadro ASCII, e o LRC ocupa o lugar do CRC: uma exceção com LRC válido prova que há uma unidade presente, e um quadro com LRC inválido não prova nada.

A varredura recarrega as definições físicas salvas da linha, abre a porta uma vez e
sonda a faixa **sequencialmente** com a Read Basic Device Identification
(função 43/14), ritmando cada sondagem com o silêncio entre quadros efetivo da linha.
Ela nunca tenta combinações de definições e nunca lê registradores. Uma
exceção Modbus com CRC válido prova que uma unidade está presente sem afirmar a
identidade dela; um timeout ou um quadro inválido não prova.

Uma linha em uso nunca é interrompida nem chaveada automaticamente: desabilite-a
antes de varrer e reabilite-a você mesmo depois. Cancelar fecha a sessão
serial e deixa os resultados já mostrados como candidatos transitórios
até você adicioná-los explicitamente. Um unit id já configurado é marcado como
tal e abre o dispositivo existente em vez de criar uma duplicata; os resultados
não carregam tags: os registradores são configurados depois do **Adicionar**.

A descoberta e a configuração da linha compartilham uma reserva de falha imediata por
porta física, então uma varredura e uma mudança de definições não podem brigar pela porta:
quem perde é avisado de qual operação a está segurando.

## Limites que vale conhecer {#limits-worth-knowing}

- Os seis tipos de valor são todo o vocabulário do codec de barramento; outras larguras
  de inteiro e Double não são oferecidos.
- A vazão é uma propriedade do barramento: todo dispositivo da linha compartilha um
  único fluxo de requisições, ritmado pelo silêncio entre quadros efetivo, então muitos
  dispositivos ou um intervalo elevado alongam todo ciclo de leitura.