# Beckhoff ADS

> Beckhoff TwinCAT-Steuerungen über ADS/AMS anbinden - die AMS-Route, der Port der Laufzeit, Symbolpfade und Leselängen.

Der Treiber **Beckhoff ADS** spricht mit Beckhoff TwinCAT-Steuerungen über ADS, das
Automatisierungsprotokoll von TwinCAT, getragen von AMS-Routen. Sie adressieren Werte über
ihren Symbolpfad im Programm der Steuerung, was Sie tippen, ist also das, was das
TwinCAT-Projekt erklärt. Legen Sie im [Connector](connector) ein Gerät unter dem Treiber
Beckhoff ADS an; der Bereich zeigt nur die Felder, die dieses Protokoll verwendet.

## Verbindung {#connection}

| Feld | Bedeutung | Standard |
| --- | --- | --- |
| **Hostadresse** | IP-Adresse der Steuerung. Ihre AMS Net Id wird aus dieser Adresse als `{ip}.1.1` abgeleitet. Solange **AMS Net Id der Steuerung** sie nicht nennt, ist die AMS Net Id der Steuerung diese Adresse gefolgt von `.1.1`; ein Name wird zuerst zu seiner IPv4-Adresse aufgelöst. | leer |
| **Port** | Der AMS-Port der Ziellaufzeit: 851 ist die erste Laufzeit der Steuerung unter TwinCAT 3, und weitere Laufzeiten von TwinCAT 3 zählen von dort aufwärts (852, 853, …). Ein leeres Feld zeigt 851 grau, und diese Laufzeit wird verwendet; ein mit 0 gespeichertes Gerät liest sich genauso. | 851 |
| **Lokale IP (AMS)** | Die eigene IP-Adresse dieser Station, aus der ihre AMS Net Id als `{ip}.1.1` abgeleitet wird. Sie muss zu der AMS-Route passen, die an der Steuerung eingerichtet ist. Ein leeres Feld verwendet die Adresse dieser Station in dem Netz, das die Steuerung erreicht, und zeigt sie grau an; ein im Feld eingetragener Wert wird stattdessen verwendet. | leer |
| **AMS Net Id der Steuerung** | Die eigene AMS Net Id der Steuerung, für eine Steuerung, deren Id nicht ihre IP-Adresse gefolgt von `.1.1` ist: sechs Zahlen von 0 bis 255, durch Punkte getrennt, wie TwinCAT XAE sie unter **SYSTEM > Routes**, Registerkarte **NetId Management**, **Target NetId** zeigt. Ein leeres Feld verwendet die IPv4-Adresse des Hosts gefolgt von `.1.1` und zeigt sie grau an. Ein Wert, der keine AMS Net Id ist, lässt das Gerät getrennt und sagt, was einzutragen ist. | leer |
| **Abfrageintervall (ms)** | Lesetakt für das ganze Gerät, für Tags, die ihn nicht selbst festlegen. | 1.000 |

Die Kopfzeile des Geräts zeigt den zusammengesetzten Endpunkt, zum Beispiel
`ads://192.168.0.1:192.168.0.50:851` (lokale IP, IP der Steuerung, AMS-Port). Jedes Tag
darf sein eigenes **Abfrageintervall (ms)** setzen; der Wert 0 an einem Tag fällt auf das
Intervall des Geräts zurück.

ADS antwortet nur Stationen, für die die Steuerung eine AMS-Route hat:
[Steuerung vorbereiten](#prepare-the-plc) sagt, welche Route wo einzurichten ist.

## Steuerung vorbereiten {#prepare-the-plc}

Eine TwinCAT-Steuerung beantwortet ADS nur für eine Station, für die ihr AMS-Router
eine Route hat. Ohne die Route nimmt der Router die Verbindung auf TCP-Port 48898 an
und schließt sie dann oder antwortet nie, und die Verbindung schlägt fehl, obwohl der
Weg durch das Netz in Ordnung ist. Richten Sie an der Steuerung einmal eine statische
Route für diese Station ein:

| Feld des Dialogs Add Route von TwinCAT | Wert |
| --- | --- |
| Name: **Route Name (Target)** | Ein beliebiger Name; der Hinweis schlägt den Computernamen dieser Station vor. |
| Net Id: **AmsNetId** | Die Adresse dieser Station gefolgt von `.1.1`, passend zu dem, was der Treiber aus **Lokale IP (AMS)** ableitet. |
| Transport: **Transport Type** | Der Transport `TCP_IP` |
| Adresse: **Address Info** | Die Adresse dieser Station, mit **IP Address** ausgewählt. |
| Art der Route: **Target Route** und **Remote Route** | `Static` und `None` |

Wählen Sie in TwinCAT XAE die Steuerung als Zielsystem und öffnen Sie **SYSTEM > Routes**,
Registerkarte **Static Routes**, dann Add. Auf dem eigenen Desktop der Steuerung
öffnet das Symbol von TwinCAT im Infobereich dieselbe Liste über **Router > Edit Routes**.

Die Adresse ist die dieser Station in dem Netz, das die Steuerung erreicht. Ein Computer
mit mehreren Netzwerkkarten hat auf jeder eine Adresse, und die Route gilt nur für die,
die sie nennt. Solange **Lokale IP (AMS)** leer ist, verwendet der Treiber die Adresse der
Karte, über die Windows die Steuerung erreicht, und das Feld zeigt sie grau an: Diese
Adresse nennt die Route. Ein im Feld eingetragener Wert wird stattdessen verwendet, und
die Route muss diesen nennen.

Wenn der Router der Steuerung die Station mangels Route abweist, sagt es die Seite des
Geräts in einem Hinweis, der an der Stelle des Fehlers des Treibers steht: die Route
fertig zum Einrichten (ihr Name, die AMS Net Id dieser Station, ihre Adresse und der
Transport, jeweils mit einer Schaltfläche zum Kopieren) und wo TwinCAT sie einrichtet.
Der Hinweis verschwindet von selbst, sobald die Steuerung antwortet, und das Journal und
der Agent lesen dieselbe Route. Ein Port, der die Verbindung abweist oder stumm bleibt,
wird als das gesagt, was er ist, nicht als fehlende Route.

Die Station spricht die Steuerung über ihre AMS Net Id an, und der Router der
Steuerung antwortet nur für seine eigene: Eine Steuerung, deren AMS Net Id nicht die
ist, die die Station verwendet, antwortet ebenfalls nie, was genau wie eine fehlende
Route aussieht. Hat die Steuerung die Route schon und antwortet trotzdem nicht, prüfen
Sie ihre AMS Net Id in TwinCAT XAE unter **SYSTEM > Routes**, Registerkarte **NetId
Management**, **Target NetId**, und tragen Sie sie unter **AMS Net Id der Steuerung**
ein; der Hinweis nennt die, die die Station verwendet.

## Adressierung {#addressing}

Ein Beckhoff-Tag wird über zwei Felder auf der Karte Quelle des Tags adressiert:

| Feld | Bedeutung | Angenommene Werte | Standard |
| --- | --- | --- | --- |
| **Symbol** | Der Symbolpfad der Variablen im Programm der Steuerung. Pflichtfeld. | Freitext, z. B. `MAIN.fValue` | leer |
| **Leselänge (Bytes, leer = automatisch)** | Wie viele Bytes je Lesevorgang übertragen werden. Leer bemisst den Lesevorgang nach dem Datentyp. | 1 und aufwärts, leer | leer |

Der Symbolpfad ist genau das, was TwinCAT zeigt: Variablen eines Programms als
`MAIN.fValue`, globale Variablenlisten als `GVL.MachineSpeed` oder
`GVL_Settings.rSetpoint`. Der Treiber löst das Symbol über seinen Namen an der Steuerung
auf und liest seine rohen Bytes. Die automatischen Leselängen sind:

| Datentyp | Automatische Leselänge |
| --- | --- |
| Boolean | 1 Byte |
| Int32 | 4 Bytes |
| Float | 4 Bytes |
| String | 16 Bytes |

Für einen String, der länger als 16 Zeichen ist, setzen Sie **Leselänge** so, dass sie die
erklärte Größe abdeckt (ein TwinCAT-`STRING(80)` braucht 80 Bytes Text). Die Zeile
**Quelladresse (Bus)** auf der Karte Quelle, die nur gelesen wird, zeigt die
zusammengesetzte Adresse, während Sie tippen.

Ein Lesevorgang, den die Steuerung ablehnt, etwa auf ein Symbol, das sie nicht hat oder
nicht lesen lässt, lässt das Tag ohne Wert, und der Grund des Tags nennt den
ADS-Fehlercode und seine Bedeutung, zum Beispiel
`ADS error 0x710 (no symbol by that name)`. Die Verbindung bleibt bestehen, und die
anderen Tags lesen weiter; der Grund verschwindet mit dem nächsten Lesevorgang, den die
Steuerung beantwortet.

## Datentypen {#data-types}

Die Auswahl **Datentyp** bietet die vier Typen an, die der Treiber überträgt:

| Datentyp | Gegenstück in der Steuerung | Hinweise |
| --- | --- | --- |
| Boolean | BOOL | 1 Byte, ungleich null ist wahr |
| Int32 | DINT | Little-Endian, wie in der Steuerung |
| Float | REAL | Little-Endian, wie in der Steuerung |
| String | STRING | Text bis zum ersten NUL des Lesepuffers |

Die Byte-Reihenfolge ist das Little-Endian der Steuerung selbst und wird automatisch
behandelt; eine Wahl der Byte-Reihenfolge gibt es nicht. Ein Lesevorgang auf String
entschlüsselt den zurückgegebenen Puffer bis zum ersten NUL-Zeichen, die Auffüllung hinter
einem kurzen Text gelangt also nie in den Wert. Andere Breiten von TwinCAT (INT, LREAL,
WORD, …) werden nicht angeboten: Legen Sie eine solche Variable im Programm der Steuerung
als einen der vier Typen oben offen, um sie hier zu lesen.

## Schreiben {#writes}

Tags, deren **Zugriff** Lesen und schreiben oder Nur schreiben ist, lassen sich schreiben. Ein
Schreibvorgang löst dasselbe Symbol auf und schreibt die Bytes des Werts: 1 Byte bei
Boolean, 4 Bytes bei Int32 und Float. Ein Schreibvorgang auf String legt die ganze
**Leselänge** des Tags ab: vorn die UTF-8-Bytes des Textes und dahinter Nullen, ein
kürzerer Text über einem längeren ersetzt also den ganzen Wert, und vom alten überlebt
nichts. Ein Text, der nicht in die erklärte Länge passt, wird abgelehnt, mit der Länge
benannt im Journal, und nie auf Maß gekürzt. Ein neues Tag beginnt als Nur lesen.

Ein Schreibvorgang, den die Steuerung ablehnt, etwa auf ein Symbol, das sie nicht
beschreiben lässt, kommt abgelehnt zurück, mit dem ADS-Fehlercode und seiner Bedeutung,
zum Beispiel `ADS error 0x704 (the symbol may not be written)`, und die Verbindung
bleibt bestehen.

## Gerätesuche {#discovery}

ADS kennt in diesem Treiber keine Suche über Rundruf, der Connector zeigt also keine
Schaltfläche Suchen. Legen Sie das Gerät und seine Symbole von Hand an.

## Gut zu wissen {#good-to-know}

- Die AMS-Route ist der übliche Grund, aus dem eine erste Verbindung fehlschlägt: Die AMS
  Net Id der Route an der Steuerung muss genau die IP der Station plus `.1.1` sein, und
  die Seite des Geräts nennt die ganze einzurichtende Route.
- Der Treiber fragt die Steuerung einmal je Verbindung nach einem Handle für jedes
  Symbol und gibt die Handles zurück, wenn die Verbindung schließt. Nach einem
  Programmdownload wird ein Handle, das die Steuerung nicht mehr annimmt, beim nächsten
  Lesevorgang ersetzt, das Tag liest also mit dem neuen Programm weiter; ein Symbol, das
  der Download umbenannt oder entfernt hat, lässt sein Tag ohne Wert, mit
  `ADS error 0x710 (no symbol by that name)`, bis die Namen wieder passen.
- Eine nicht erreichbare Steuerung kostet beim Start nichts: Das Gerät versucht es im
  Hintergrund weiter, und seine Tags lesen schlechte Qualität, bis die Verbindung steht.