# Beckhoff ADS

> Conecte CLPs Beckhoff TwinCAT por ADS/AMS: a rota AMS, a porta do runtime, caminhos de símbolo e comprimentos de leitura.

O driver **Beckhoff ADS** conversa com CLPs Beckhoff TwinCAT por ADS, o
protocolo de automação da TwinCAT transportado por rotas AMS. Você endereça valores pelo
caminho de símbolo deles no programa do CLP, então o que você digita é o que o projeto
TwinCAT declara. Adicione um dispositivo sob o driver Beckhoff ADS no
[Connector](connector); o painel mostra só os campos que este protocolo usa.

## Conexão {#connection}

| Campo | Significado | Padrão |
| --- | --- | --- |
| **Host ou IP** | Endereço IP do CLP. O AMS Net Id dele é derivado desse endereço como `{ip}.1.1`. A não ser que o **AMS Net Id do CLP** o indique, o AMS Net Id do CLP é esse endereço seguido de `.1.1`; um nome é resolvido antes para o endereço IPv4 dele. | vazio |
| **Porta** | A porta AMS do runtime alvo: 851 é o runtime 1 do CLP no TwinCAT 3, e os demais runtimes do TwinCAT 3 contam a partir dali (852, 853, …). Um campo vazio mostra 851 em cinza e esse runtime é usado, que é também como se lê um dispositivo salvo com 0. | 851 |
| **IP local (AMS)** | O endereço IP da própria estação, do qual o AMS Net Id dela é derivado como `{ip}.1.1`. Ele precisa bater com a rota AMS configurada no CLP. Um campo vazio usa o endereço desta estação na rede que alcança o CLP, que ele mostra em cinza; um valor digitado no campo é usado no lugar dele. | vazio |
| **AMS Net Id do CLP** | O AMS Net Id do próprio CLP, para um CLP cujo id não é o endereço IP dele seguido de `.1.1`: seis números de 0 a 255 separados por pontos, como o TwinCAT XAE o mostra em **SYSTEM > Routes**, aba **NetId Management**, **Target NetId**. Um campo vazio usa o endereço IPv4 do host seguido de `.1.1`, que ele mostra em cinza. Um valor que não é um AMS Net Id deixa o dispositivo desconectado e diz o que escrever. | vazio |
| **Intervalo de leitura (ms)** | Período de leitura de todo o dispositivo, para as tags que não o sobrepõem. | 1.000 |

O cabeçalho do dispositivo mostra o endpoint montado, por exemplo
`ads://192.168.0.1:192.168.0.50:851` (IP local, IP do CLP, porta AMS). Cada tag
pode definir o próprio **Intervalo de leitura (ms)**; um valor 0 na tag recai no
intervalo do dispositivo.

O ADS só responde a estações para as quais o CLP tem uma rota AMS:
[Preparar o CLP](#prepare-the-plc) diz qual rota cadastrar e onde.

## Preparar o CLP {#prepare-the-plc}

Um CLP TwinCAT só responde ADS a uma estação para a qual o roteador AMS dele tem uma
rota. Sem a rota, o roteador aceita a conexão na porta TCP 48898 e depois a fecha ou
nunca responde, e a conexão falha mesmo com o caminho de rede em ordem. Cadastre uma vez
no CLP uma rota estática para esta estação:

| Campo da caixa Add Route do TwinCAT | Valor |
| --- | --- |
| Nome: **Route Name (Target)** | Qualquer nome; o aviso sugere o nome de computador desta estação. |
| Net id: **AmsNetId** | O endereço desta estação seguido de `.1.1`, batendo com o que o driver deriva do **IP local (AMS)**. |
| Transporte: **Transport Type** | O transporte `TCP_IP` |
| Endereço: **Address Info** | O endereço desta estação, com **IP Address** selecionado. |
| Tipo de rota: **Target Route** e **Remote Route** | `Static` e `None` |

No TwinCAT XAE, escolha o CLP como sistema de destino e abra **SYSTEM > Routes**, aba
**Static Routes**, depois Add. Na área de trabalho do próprio CLP, o ícone do TwinCAT
na área de notificação abre a mesma lista por **Router > Edit Routes**.

O endereço é o desta estação na rede que alcança o CLP. Um computador com várias placas
de rede tem um endereço em cada uma, e a rota só vale para o que ela nomeia. Enquanto o
**IP local (AMS)** está vazio, o driver usa o endereço da placa pela qual o Windows
alcança o CLP, que o campo mostra em cinza: esse é o endereço que a rota nomeia. Um
valor digitado no campo é usado no lugar dele, e a rota tem que nomear esse.

Quando o roteador do CLP recusa a estação por falta da rota, a página do dispositivo diz
isso num aviso que fica no lugar do erro do driver: a rota pronta para cadastrar (o
nome, o AMS Net Id desta estação, o endereço dela e o transporte, cada um com um botão
de copiar) e onde o TwinCAT a cadastra. O aviso some sozinho assim que o CLP responde, e
o diário e o agente leem a mesma rota. Uma porta que recusa a conexão ou fica muda é
dita como o que é, não como uma rota que falta.

A estação endereça o CLP pelo AMS Net Id dele, e o roteador do CLP só responde pelo
próprio: um CLP cujo AMS Net Id não é o que a estação usa também nunca responde, o que
parece exatamente uma rota que falta. Quando o CLP já tem a rota e mesmo assim não
responde, confira o AMS Net Id dele no TwinCAT XAE em **SYSTEM > Routes**, aba **NetId
Management**, **Target NetId**, e digite-o em **AMS Net Id do CLP**; o aviso diz qual a
estação usa.

## Endereçamento {#addressing}

Uma tag Beckhoff é endereçada por dois campos no cartão Origem da tag:

| Campo | Significado | Valores aceitos | Padrão |
| --- | --- | --- | --- |
| **Símbolo** | O caminho de símbolo da variável no programa do CLP. Obrigatório. | texto livre, por exemplo `MAIN.fValue` | vazio |
| **Comprimento de leitura (bytes, vazio = automático)** | Quantos bytes transferir por leitura. Em branco, o tamanho da leitura vem do tipo de dado. | 1 ou mais, em branco | em branco |

O caminho de símbolo é exatamente o que o TwinCAT mostra: variáveis de programa como
`MAIN.fValue`, listas de variáveis globais como `GVL.MachineSpeed` ou
`GVL_Settings.rSetpoint`. O driver resolve o símbolo pelo nome no CLP
e lê os bytes brutos dele. Os comprimentos de leitura automáticos são:

| Tipo de dado | Comprimento de leitura automático |
| --- | --- |
| Boolean | 1 byte |
| Int32 | 4 bytes |
| Float | 4 bytes |
| String | 16 bytes |

Para um String com mais de 16 caracteres, defina o **Comprimento de leitura** de modo a
cobrir o tamanho declarado (um `STRING(80)` do TwinCAT precisa de 80 bytes de texto). A linha
somente leitura **Endereço de origem (barramento)** do cartão Origem mostra o endereço
montado enquanto você edita.

Uma leitura que o CLP recusa, como a de um símbolo que ele não tem ou não deixa ler,
deixa a tag sem valor, e o motivo da tag nomeia o código de erro ADS e o que ele
significa, por exemplo `ADS error 0x710 (no symbol by that name)`. A conexão continua
de pé e as outras tags seguem lendo; o motivo sai com a próxima leitura que o CLP
responder.

## Tipos de dado {#data-types}

O seletor de **Tipo de dado** oferece os quatro tipos que o driver empacota:

| Tipo de dado | Correspondente no CLP | Notas |
| --- | --- | --- |
| Boolean | BOOL | 1 byte, diferente de zero é verdadeiro |
| Int32 | DINT | little-endian, igual ao do CLP |
| Float | REAL | little-endian, igual ao do CLP |
| String | STRING | texto até o primeiro NUL do buffer de leitura |

A ordem de bytes é o little-endian do próprio CLP e é tratada automaticamente; não
existe opção de ordem de bytes. Uma leitura de String decodifica o buffer devolvido até o
primeiro terminador NUL, então o preenchimento atrás de um texto curto nunca vaza para
o valor. Outras larguras do TwinCAT (INT, LREAL, WORD, …) não são oferecidas:
exponha uma variável dessas no programa do CLP como um dos quatro tipos acima para
lê-la aqui.

## Escritas {#writes}

Tags cujo **Acesso** é Leitura e escrita ou Somente escrita podem ser escritas. Uma escrita
resolve o mesmo símbolo e escreve os bytes do valor: 1 byte em Boolean,
4 bytes em Int32 e Float. Uma escrita de String deposita o **Comprimento de leitura**
inteiro da tag: os bytes UTF-8 do texto na frente e zeros atrás deles, então um
texto mais curto escrito sobre um mais longo substitui o valor inteiro e nada do
antigo sobrevive. Um texto que não cabe no comprimento declarado é recusado
com o comprimento nomeado no diário, nunca cortado para caber. Uma tag nova nasce
como Somente leitura.

Uma escrita que o CLP recusa, como a de um símbolo que ele não deixa escrever,
volta recusada com o código de erro ADS e o que ele significa, por exemplo
`ADS error 0x704 (the symbol may not be written)`, e a conexão continua de pé.

## Descoberta {#discovery}

O ADS não tem descoberta por difusão neste driver, então o Connector não mostra botão
Descobrir. Adicione o dispositivo e os símbolos dele à mão.

## Bom saber {#good-to-know}

- A rota AMS é o motivo mais comum de uma primeira conexão falhar: o AMS
  Net Id da rota no CLP precisa ser exatamente o IP da estação mais `.1.1`, e a
  página do dispositivo dá a rota inteira a cadastrar.
- O driver pede ao CLP um handle para cada símbolo uma vez por conexão e devolve os
  handles quando a conexão fecha. Depois de uma carga no CLP, um handle que o CLP não
  aceita mais é trocado na próxima leitura, então a tag segue lendo com o programa novo;
  um símbolo que a carga renomeou ou removeu deixa a tag dele sem valor, com
  `ADS error 0x710 (no symbol by that name)`, até os nomes baterem de novo.
- Um CLP inalcançável não custa nada na inicialização: o dispositivo segue tentando em
  segundo plano e as tags dele leem qualidade ruim até a conexão acontecer.