# Beckhoff ADS

> Relier des automates Beckhoff TwinCAT sur ADS/AMS : la route AMS, le port du runtime, les chemins de symbole et les longueurs de lecture.

Le pilote **Beckhoff ADS** parle à des automates Beckhoff TwinCAT sur ADS, le
protocole d'automatisation de TwinCAT porté par des routes AMS. Vous adressez les valeurs par
leur chemin de symbole dans le programme de l'automate : ce que vous tapez est donc ce que
déclare le projet TwinCAT. Ajoutez un équipement sous le pilote Beckhoff ADS dans le
[Connector](connector); le volet ne montre que les champs que ce protocole emploie.

## Connexion {#connection}

| Champ | Sens | Par défaut |
| --- | --- | --- |
| **Hôte** | L'adresse IP de l'automate. Son identifiant de réseau AMS en est déduit sous la forme `{ip}.1.1`. Sauf si **Identifiant de réseau AMS de l'automate** le nomme, l'identifiant de réseau AMS de l'automate est cette adresse suivie de `.1.1`; un nom est d'abord résolu en son adresse IPv4. | vide |
| **Port** | Le port AMS du runtime visé : 851 est le premier runtime automate de TwinCAT 3, et les runtimes TwinCAT 3 suivants comptent à partir de là (852, 853, etc.). Un champ vide affiche 851 en gris et ce runtime est employé; un équipement enregistré avec 0 se lit de la même façon. | 851 |
| **IP locale (AMS)** | L'adresse IP propre à cette station, d'où son identifiant de réseau AMS est déduit sous la forme `{ip}.1.1`. Elle doit correspondre à la route AMS configurée sur l'automate. Un champ vide emploie l'adresse de cette station sur le réseau qui atteint l'automate, qu'il affiche en gris; une valeur entrée dans le champ est employée à sa place. | vide |
| **Identifiant de réseau AMS de l'automate** | L'identifiant de réseau AMS propre à l'automate, pour un automate dont l'identifiant n'est pas son adresse IP suivie de `.1.1` : six nombres de 0 à 255 séparés par des points, tel que TwinCAT XAE le montre sous **SYSTEM > Routes**, onglet **NetId Management**, **Target NetId**. Un champ vide emploie l'adresse IPv4 de l'hôte suivie de `.1.1`, qu'il affiche en gris. Une valeur qui n'est pas un identifiant de réseau AMS laisse l'équipement déconnecté et dit quoi entrer. | vide |
| **Intervalle de scrutation (ms)** | La période de lecture de tout l'équipement, pour les tags qui ne la remplacent pas. | 1 000 |

L'en-tête de l'équipement montre l'endpoint assemblé, par exemple
`ads://192.168.0.1:192.168.0.50:851` (IP locale, IP de l'automate, port AMS). Chaque tag
peut poser son propre **Intervalle de scrutation (ms)**; une valeur de 0 sur un tag retombe sur
l'intervalle de l'équipement.

ADS ne répond qu'aux stations pour lesquelles l'automate a une route AMS :
[Préparer l'automate](#prepare-the-plc) dit quelle route ajouter et où.

## Préparer l'automate {#prepare-the-plc}

Un automate TwinCAT ne répond en ADS qu'à une station pour laquelle son routeur AMS a
une route. Sans la route, le routeur accepte la connexion sur le port TCP 48898 puis la
ferme ou ne répond jamais, et la connexion échoue même si le chemin réseau est bon.
Ajoutez une fois sur l'automate une route statique pour cette station :

| Champ de la boîte de dialogue Add Route de TwinCAT | Valeur |
| --- | --- |
| Nom : **Route Name (Target)** | Un nom quelconque; l'avis propose le nom d'ordinateur de cette station. |
| Identifiant de réseau : **AmsNetId** | L'adresse de cette station suivie de `.1.1`, ce qui correspond à ce que le pilote déduit de l'**IP locale (AMS)**. |
| Transport : **Transport Type** | Le transport `TCP_IP` |
| Adresse : **Address Info** | L'adresse de cette station, avec **IP Address** sélectionné. |
| Genre de route : **Target Route** et **Remote Route** | `Static` et `None` |

Dans TwinCAT XAE, choisissez l'automate comme système cible et ouvrez **SYSTEM > Routes**,
onglet **Static Routes**, puis Add. Sur le bureau de l'automate lui-même, l'icône
TwinCAT de la zone de notification ouvre la même liste par **Router > Edit Routes**.

L'adresse est celle de cette station sur le réseau qui atteint l'automate. Un ordinateur
à plusieurs cartes réseau a une adresse sur chacune, et la route ne vaut que pour celle
qu'elle nomme. Tant que l'**IP locale (AMS)** est vide, le pilote emploie l'adresse de la
carte par laquelle Windows atteint l'automate, que le champ affiche en gris : c'est
l'adresse que nomme la route. Une valeur entrée dans le champ est employée à sa place,
et la route doit nommer celle-là.

Quand le routeur de l'automate refuse la station faute de route, la page de l'équipement
le dit dans un avis qui prend la place de l'erreur du pilote : la route prête à ajouter
(son nom, l'identifiant de réseau AMS de cette station, son adresse et le transport,
chacun avec un bouton de copie) et l'endroit où TwinCAT l'ajoute. L'avis disparaît de
lui-même dès que l'automate répond, et le journal et l'agent lisent la même route. Un
port qui refuse la connexion ou reste muet est dit pour ce qu'il est, pas comme une
route manquante.

La station adresse l'automate par son identifiant de réseau AMS, et le routeur de
l'automate ne répond que pour le sien : un automate dont l'identifiant de réseau AMS
n'est pas celui qu'emploie la station ne répond jamais non plus, ce qui ressemble
exactement à une route manquante. Quand l'automate a déjà la route et ne répond toujours
pas, vérifiez son identifiant dans TwinCAT XAE sous **SYSTEM > Routes**, onglet **NetId
Management**, **Target NetId**, et entrez-le dans **Identifiant de réseau AMS de
l'automate**; l'avis nomme celui qu'emploie la station.

## Adressage {#addressing}

Un tag Beckhoff est adressé par deux champs de la carte Source de la valeur du tag :

| Champ | Sens | Valeurs acceptées | Par défaut |
| --- | --- | --- | --- |
| **Symbole** | Le chemin de symbole de la variable dans le programme de l'automate. Obligatoire. | texte libre, par exemple `MAIN.fValue` | vide |
| **Longueur de lecture (octets, vide = automatique)** | Combien d'octets transférer par lecture. Vide dimensionne la lecture d'après le type de donnée. | 1 et au-delà, ou vide | vide |

Le chemin de symbole est exactement ce que TwinCAT montre : les variables de programme comme
`MAIN.fValue`, les listes de variables globales comme `GVL.MachineSpeed` ou
`GVL_Settings.rSetpoint`. Le pilote résout le symbole par son nom sur l'automate
et lit ses octets bruts. Les longueurs de lecture automatiques sont :

| Type de donnée | Longueur de lecture automatique |
| --- | --- |
| Boolean | 1 octet |
| Int32 | 4 octets |
| Float | 4 octets |
| String | 16 octets |

Pour un texte de plus de 16 caractères, posez la **longueur de lecture** pour couvrir la
taille déclarée (un `STRING(80)` de TwinCAT demande 80 octets de texte). La ligne en lecture
seule **Adresse source (bus)** de la carte Source de la valeur montre l'adresse assemblée au fil de vos
modifications.

Une lecture que l'automate refuse, comme celle d'un symbole qu'il ne détient pas ou ne
laisse pas lire, laisse le tag sans valeur, et le motif du tag nomme le code d'erreur ADS
et ce qu'il signifie, par exemple `ADS error 0x710 (no symbol by that name)`. La connexion
reste ouverte et les autres tags continuent de lire; le motif disparaît à la prochaine
lecture à laquelle l'automate répond.

## Types de donnée {#data-types}

Le sélecteur de **Type de donnée** offre les quatre types que le pilote sait transporter :

| Type de donnée | Équivalent automate | Remarques |
| --- | --- | --- |
| Boolean | BOOL | 1 octet, tout ce qui n'est pas nul est vrai |
| Int32 | DINT | petit-boutiste, comme l'automate |
| Float | REAL | petit-boutiste, comme l'automate |
| String | STRING | le texte jusqu'au premier octet nul du tampon de lecture |

L'ordre des octets est le petit-boutiste propre à l'automate et il est traité automatiquement;
il n'y a pas d'option d'ordre des octets. Une lecture de texte décode le tampon renvoyé jusqu'au
premier octet nul, si bien que le remplissage derrière un texte court ne fuit jamais dans
la valeur. Les autres largeurs de TwinCAT (INT, LREAL, WORD, etc.) ne sont pas offertes :
exposez une telle variable dans le programme de l'automate sous l'un des quatre types ci-dessus
pour la lire ici.

## Écritures {#writes}

Les tags dont l'**Accès** est Lecture et écriture ou Écriture seule peuvent être écrits. Une écriture
résout le même symbole et écrit les octets de la valeur : 1 octet pour un booléen,
4 octets pour un Int32 et un Float. Une écriture de texte dépose toute la **longueur de
lecture** du tag : les octets UTF-8 du texte devant et des zéros derrière, si bien qu'un
texte plus court écrit par-dessus un plus long remplace toute la valeur et que rien de l'ancien
ne survit. Un texte qui n'entre pas dans la longueur déclarée est refusé
avec la longueur nommée dans le journal, jamais rogné à la taille. Un nouveau tag démarre
en Lecture seule.

Une écriture que l'automate refuse, comme celle d'un symbole qu'il ne laisse pas
écrire, revient refusée avec le code d'erreur ADS et ce qu'il signifie, par exemple
`ADS error 0x704 (the symbol may not be written)`, et la connexion reste ouverte.

## Découverte {#discovery}

ADS n'a pas de découverte par diffusion dans ce pilote : le Connector ne montre donc aucun
bouton Découvrir. Ajoutez l'équipement et ses symboles à la main.

## Bon à savoir {#good-to-know}

- La route AMS est la raison habituelle de l'échec d'une première connexion (la page de
  l'équipement donne alors toute la route à ajouter) : l'identifiant de
  réseau AMS de la route, sur l'automate, doit être exactement l'IP de la station suivie de
  `.1.1`.
- Le pilote demande à l'automate un handle pour chaque symbole une fois par connexion et
  rend les handles quand la connexion se ferme. Après un téléversement d'automate, un handle
  que l'automate n'accepte plus est remplacé à la lecture suivante, si bien que le tag
  continue de lire avec le nouveau programme; un symbole que le téléversement a renommé ou
  retiré laisse son tag sans valeur, avec `ADS error 0x710 (no symbol by that name)`,
  jusqu'à ce que les noms correspondent de nouveau.
- Un automate injoignable ne coûte rien au démarrage : l'équipement continue de réessayer en
  arrière-plan et ses tags lisent une mauvaise qualité jusqu'à ce que la connexion aboutisse.