Hinweise zur Dokumentation

Diese Beschreibung wendet sich ausschließlich an ausgebildetes Fachpersonal der Steuerungs- und Automatisierungstechnik, das mit den geltenden nationalen Normen vertraut ist.
Zur Installation und Inbetriebnahme der Komponenten ist die Beachtung der Dokumentation und der nachfolgenden Hinweise und Erklärungen unbedingt notwendig.
Das Fachpersonal ist verpflichtet, für jede Installation und Inbetriebnahme die zu dem Zeitpunkt veröffentlichte Dokumentation zu verwenden.

Das Fachpersonal hat sicherzustellen, dass die Anwendung bzw. der Einsatz der beschriebenen Produkte alle Sicherheitsanforderungen, einschließlich sämtlicher anwendbaren Gesetze, Vorschriften, Bestimmungen und Normen erfüllt.

Disclaimer

Diese Dokumentation wurde sorgfältig erstellt. Die beschriebenen Produkte werden jedoch ständig weiter entwickelt.
Wir behalten uns das Recht vor, die Dokumentation jederzeit und ohne Ankündigung zu überarbeiten und zu ändern.
Aus den Angaben, Abbildungen und Beschreibungen in dieser Dokumentation können keine Ansprüche auf Änderung bereits gelieferter Produkte geltend gemacht werden.

Marken

Beckhoff®, TwinCAT®, EtherCAT®, EtherCAT G®, EtherCAT G10®, EtherCAT P®, Safety over EtherCAT®, TwinSAFE®, XFC®, XTS® und XPlanar® sind eingetragene und lizenzierte Marken der Beckhoff Automation GmbH.
Die Verwendung anderer in dieser Dokumentation enthaltenen Marken oder Kennzeichen durch Dritte kann zu einer Verletzung von Rechten der Inhaber der entsprechenden Bezeichnungen führen.

Patente

Die EtherCAT Technologie ist patentrechtlich geschützt, insbesondere durch folgende Anmeldungen und Patente:
EP1590927, EP1789857, EP1456722, EP2137893, DE102015105702
mit den entsprechenden Anmeldungen und Eintragungen in verschiedenen anderen Ländern.

EtherCAT® ist eine eingetragene Marke und patentierte Technologie lizenziert durch die Beckhoff Automation GmbH, Deutschland.

Copyright

© Beckhoff Automation GmbH & Co. KG, Deutschland.
Weitergabe sowie Vervielfältigung dieses Dokuments, Verwertung und Mitteilung seines Inhalts sind verboten, soweit nicht ausdrücklich gestattet.
Zuwiderhandlungen verpflichten zu Schadenersatz. Alle Rechte für den Fall der Patent-, Gebrauchsmuster- oder Geschmacksmustereintragung vorbehalten.


Einleitung

Die folgende Beschreibung legt die Spezifikation für das ADS/AMS-Protokoll über TCP/IP offen. Hierdurch bietet sich die Möglichkeit an, eigene Implementierungen von ADS/AMS zu realisieren. Z.B. für andere Betriebssysteme als Windows oder für nicht unterstützte Programmiersprachen.

Die Kommunikation erfolgt hierbei über TCP/IP, Port 48898 (0xBF02). Der prinzipielle Ablauf der Kommunikation wird in der Dokumentation TwinCAT ADS unter 'Einführung ADS' beschrieben.


Aufbau AMS/TCP Paket

Datenfeld | Größe | Beschreibung
AMS/TCP Header | 6 Bytes | Enthält die Länge des Datenpakets.
AMS Header | 32 Bytes | Im AMS/TCP-Header sind die Adressen vom Sender und Empfänger enthalten. Außerdem der AMS-Fehler Code, die ADS-Kommando Id und einige andere Informationen.
ADS Data | n Bytes | Im ADS-Datenbereich sind die Parameter der einzelnen ADS-Kommandos abgelegt. Der Aufbau des Datenfeldes ist abhängig vom ADS-Kommando. Einige ADS-Kommandos benötigen keine zusätzlichen Daten.


AMS/TCP Header

Datenfeld | Größe | Beschreibung
reserved | 2 Bytes | Diese Bytes müssen auf 0 gesetzt werden.
Length | 4 Bytes | In diesem Feld steht die Länge des Datenpakets. Diese setzt sich zusammen aus dem AMS-Header und den angefügten ADS-Daten. Die Einheit ist Bytes.


AMS Header

Datenfeld | Größe | Beschreibung
AMSNetId Target | 6 Bytes | Dieses ist die AMSNetId der Station, für die das Paket bestimmt ist. Anmerkung siehe unten.
AMSPort Target | 2 Bytes | Dieses ist der AMSPort derjenigen Station, für die das Paket bestimmt ist.
AMSNetId Source | 6 Bytes | Hier steht die AMSNetId der Station, von dem aus das Paket geschickt wurde.
AMSPort Source | 2 Bytes | Hier steht der AMSPort der Station, von dem aus das Paket geschickt wurde.
Command Id | 2 Bytes | siehe unten.
State Flags | 2 Bytes | siehe unten.
Data Length | 4 Bytes | Größe des Datenbereichs. Die Einheit ist Byte.
Error Code | 4 Bytes | AMS-Fehlernummer. Siehe ADS Return Codes.
Invoke Id | 4 Bytes | Frei benutzbares 32-Bit Feld. Üblicherweise dient dieses Feld dazu eine Id zu übertragen, die es ermöglicht ein empfangenden Response einen zuvor gesendeten Request wieder zuzuordnen.
Data | n Bytes | Datenbereich. Im Datenbereich sind die Parameter der entsprechenden ADS-Kommandos enthalten.

AMS Net Id

Die AMSNetId besteht aus 6 Bytes und adressiert den Sender oder den Empfänger. Eine mögliche AMSNetId wäre z.B. 172.16.17.10.1.1. Bei diesem Beispiel ist die Speicheranordnung wie folgt:

Die AMSNetId ist rein logisch und hat in der Regel keinen Bezug zur IP-Adresse. Die AMSNetId wird am Zielsystem konfiguriert. Beim PC wird hierzu das TwinCAT System Control benutzt. Verwenden Sie andere Hardware, so finden Sie in der entsprechenden Dokumentation Hinweise zum Einstellen der AMSNetId.

Command Id

Cmd | Beschreibung
0x0000 | Invalid
0x0001 | ADS Read Device Info
0x0002 | ADS Read
0x0003 | ADS Write
0x0004 | ADS Read State
0x0005 | ADS Write Control
0x0006 | ADS Add Device Notification
0x0007 | ADS Delete Device Notification
0x0008 | ADS Device Notification
0x0009 | ADS Read Write

Andere Kommandos sind nicht definiert oder werden intern benutzt. Deshalb darf die Command Id auch nur die oben aufgezählten Werte enthalten!

State Flags

Flag | Beschreibung
0x0001 | 0: Request / 1: Response
0x0004 | ADS Kommando

Das erste Bit kennzeichnet, ob es sich um ein Request oder um ein Response handelt. Das dritte Bit muss auf 1 gesetzt werden, um Daten per ADS-Kommandos auszutauschen. Die anderen Bits sind nicht definiert oder werden zu anderen Zwecken intern benutzt. Deshalb müssen die restlichen Bits auf 0 gesetzt werden!

Flag | Beschreibung
0x000x | TCP Protokoll
0x004x | UDP Protokoll

Bit Nr. 7 kennzeichnet, ob es über TCP oder UDP Übertragen werden soll.


Kommandoübersicht

Kommando | Beschreibung
ADS Read Device Info | Liest die Bezeichnung und die Versionsnummer eines ADS-Gerätes.
ADS Read | Mit ADS Read werden Daten aus einem ADS Gerät ausgelesen.
ADS Write | Mit ADS Write werden Daten in ein ADS Gerät geschrieben.
ADS Read State | Liest den ADS-Status und den Geräte-Status eines ADS-Gerätes.
ADS Write Control | Ändert den ADS-Status und den Geräte-Status von einem ADS-Gerät.
ADS Add Device Notification | Eine Notification (Bekanntmachung) wird in einem ADS-Gerät angelegt.
ADS Delete Device Notification | Eine zuvor definierte Notification (Bekanntmachung) wird in einem ADS-Gerät gelöscht.
ADS Device Notification | Daten werden selbständig von einem ADS-Gerät zu einem Client übertragen.
ADS Read Write | Mit ADS Read Write werden Daten in ein ADS Gerät geschrieben. Zusätzlich können Daten aus dem ADS Gerät gelesen werden.


ADS Read Device Info

Liest die Bezeichnung und die Versionsnummer eines ADS-Gerätes.

Request

Es werden keine zusätzlichen Daten benötigt.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.
Major Version | 1 Byte | Major Versionsnummer.
Minor Version | 1 Byte | Minor Versionsnummer.
Version Build | 2 Bytes | Buildnummer.
Device Name | 16 Bytes | Name des ADS Gerätes.


ADS Read

Mit ADS Read werden Daten aus einem ADS Gerät ausgelesen. Adressiert werden die Daten durch die Index Group und dem Index Offset.

Request

Datenfeld | Größe | Beschreibung
Index Group | 4 Bytes | Index Group der Daten, die gelesen werden sollen.
Index Offset | 4 Bytes | Index Offset der Daten, die gelesen werden sollen.
Length | 4 Bytes | Länge der Daten in Bytes, die gelesen werden sollen.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.
Length | 4 Bytes | Länge der Daten die zurückgeliefert werden.
Data | n Bytes | Daten die zurückgeliefert werden.


ADS Write

Mit ADS Write werden Daten in ein ADS Gerät geschrieben. Adressiert werden die Daten durch die Index Group und dem Index Offset.

Request

Datenfeld | Größe | Beschreibung
Index Group | 4 Bytes | Index Group, in der die Daten geschrieben werden sollen.
Index Offset | 4 Bytes | Index Offset, in der die Daten geschrieben werden sollen.
Length | 4 Bytes | Länge der Daten in Bytes, die geschrieben werden.
Data | n Bytes | Daten die in das ADS Gerät geschrieben werden.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.


ADS Read State

Liest den ADS-Status und den Geräte-Status eines ADS-Gerätes.

Request

Es werden keine zusätzlichen Daten benötigt.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.
ADS State | 2 Bytes | ADS-Status (siehe Datentyp ADSSTATE der ADS-DLL).
Device State | 2 Bytes | Geräte-Status.


ADS Write Control

Ändert den ADS-Status und den Geräte-Status von einem ADS-Gerät.

Außer der Änderung des ADS-Status und des Geräte-Status ist es zusätzlich noch möglich, Daten zum ADS-Gerät zu schicken, um weitere Informationen zu übertragen. Bei den aktuellen ADS-Geräten (PLC, NC, ...) werden diese Daten nicht weiter ausgewertet.

Request

Datenfeld | Größe | Beschreibung
ADS State | 2 Bytes | Neuer ADS-Status (siehe Datentyp ADSSTATE der ADS-DLL).
Device State | 2 Bytes | Neuer Geräte-Status.
Length | 4 Bytes | Länge der Daten in Byte.
Data | n Bytes | Zusätzliche Daten die zum ADS-Gerät übertragen werden.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.


ADS Add Device Notification

Eine Notification (Bekanntmachung) wird in einem ADS-Gerät angelegt.

Hinweis: Wir empfehlen nicht mehr als 550 Notifications pro Gerät anzumelden. Durch die Organisation der Daten in Strukturen kann die Nutzlast pro Notication effektiv erhöht werden.

Request

Datenfeld | Größe | Beschreibung
Index Group | 4 Bytes | Index Group der Daten, die per Notification übertragen werden sollen.
Index Offset | 4 Bytes | Index Offset der Daten, die per Notification übertragen werden sollen.
Length | 4 Bytes | Länge der Daten in Bytes, die per Notification übertragen werden sollen.
Transmission Mode | 4 Bytes | Siehe Beschreibung der Struktur ADSTRANSMODE bei der ADS-DLL.
Max Delay | 4 Bytes | Spätestens nach dieser Zeit wird die ADS Device Notification aufgerufen. Die Einheit ist in ms.
Cycle Time | 4 Bytes | In diesem Zeitintervall prüft der ADS-Server, ob sich der Wert verändert hat. Die Einheit ist in ms.
reserved | 16 Bytes | Muss auf 0 gesetzt werden.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.
Notification Handle | 4 Bytes | Handle der Notification.


ADS Delete Device Notification

Eine zuvor definierte Notification (Bekanntmachung) wird in einem ADS-Gerät gelöscht.

Request

Datenfeld | Größe | Beschreibung
Notification Handle | 4 Bytes | Der Handle der Notification. Der Handle wird durch das ADS Kommando Add Device Notification erzeugt.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.


ADS Device Notification

Daten werden selbständig von einem ADS-Gerät zu einem Client übertragen.

Request

Die Daten, die bei der Device Notification übertragen werden, sind mehrfach ineinander verschachtelt. Der Notification Stream enthält ein Array mit Elementen vom Typ AdsStampHeader, welches wiederum ein Array mit Elementen vom Typ AdsNotificationSample enthält.

AdsNotificationStream

Datenfeld | Größe | Beschreibung
Length | 4 Bytes | Größe der Daten in Byte.
Stamps | 4 Bytes | Anzahl der Elemente vom Typ AdsStampHeader.
AdsStampHeader | n Bytes | Array mit Elementen vom Typ AdsStampHeader.

AdsStampHeader

Datenfeld | Größe | Beschreibung
TimeStamp | 8 Bytes | Zeitstempel. Der Zeitstempel ist nach dem Windows FILETIME-Format kodiert. D.h. der Wert enthält die Anzahl der Nanosekunden, die seit dem 1.1.1601 vergangen sind. Außerdem wird die lokale Zeitverschiebung nicht berücksichtigt. Somit liegt der Zeitstempel als Universal Coordinated Time (UTC) vor.
Samples | 4 Bytes | Anzahl der Elemente vom Typ AdsNotificationSample.
AdsNotificationSample | n Bytes | Array mit Elementen vom Typ AdsNotificationSample.

AdsNotificationSample

Datenfeld | Größe | Beschreibung
Notification Handle | 4 Bytes | Handle der Notification.
Sample Size | 4 Bytes | Größe des Datenbereichs in Byte.
Data | n Bytes | Daten.

Hinweis: Wenn der Handle ungültig geworden ist. Wird einmalig eine Notification ohne Daten als Hinweis versendet.


ADS Read Write

Mit ADS Read Write werden Daten in ein ADS Gerät geschrieben. Zusätzlich können Daten aus dem ADS Gerät gelesen werden. Adressiert werden die zu lesenden Daten durch die Index Group und dem Index Offset.

Request

Datenfeld | Größe | Beschreibung
Index Group | 4 Bytes | Index Group, in der die Daten geschrieben werden sollen.
Index Offset | 4 Bytes | Index Offset, in der die Daten geschrieben werden sollen.
Read Length | 4 Bytes | Länge der Daten in Bytes, die gelesen werden sollen.
Write Length | 4 Bytes | Länge der Daten in Bytes, die geschrieben werden.
Data | n Bytes | Daten die in das ADS Gerät geschrieben werden.

Response

Datenfeld | Größe | Beschreibung
Result | 4 Bytes | ADS Fehlernummer.
Length | 4 Bytes | Länge der Daten die zurückgeliefert werden.
Data | n Bytes | Daten die zurückgeliefert werden.


TwinCAT AMS/ADS Debugger

Der TwinCAT AMS/ADS Debugger protokolliert den gesamten Datenverkehr über den TwinCAT Message Router. Dieses betrifft auch die Kommunikation von ADS-Geräten untereinander, wenn sich diese auf den gleichen Rechner befinden. Z.B. der Datenaustausch zwischen TwinCAT NC und TwinCAT PLC oder zwischen dem TwinCAT Nockenschaltwerk und dem Feldbus. Der TwinCAT AMS/ADS Debugger befindet sich auf der TwinCAT CD im Verzeichnis Unsupported Utilities.

Hinweis:

Es muss an dieser Stelle darauf hingewiesen werden, dass der TwinCAT AMS/ADS Debugger kein offizielles Produkt der Firma Beckhoff ist, so dass wir für deren Benutzung keinerlei Gewährleistung oder Support übernehmen. Allerdings sind wir für Hinweise auf entsprechende Fehler dankbar.


Microsoft Netzwerk Monitor

Der MS Netzwerk Monitor 2 kann durch entsprechende Parser-DLL's um weitere Protokolle erweitert werden. Für das AMS/TCP-Protokoll wird solch eine Erweiterungs-DLL mit TwinCAT ausgeliefert.

Diese DLL befindet sich auf der TwinCAT CD im Verzeichnis Unsupported Utilities und muss in das Unterverzeichnis Parsers des MS Netzwerk Monitors kopiert werden.

Mit Hilfe des MS Netzwerk Monitors kann ausschließlich die Kommunikation protokolliert werden, die über die Ethernet-Schnittstelle stattfindet. Eine Aufzeichnung mit anderen Feldbussen (Lightbus, Profibus, ...) ist nicht möglich.

Hinweis:

Es muss an dieser Stelle darauf hingewiesen werden, dass der MS Netzwerk Monitor kein Produkt der Firma Beckhoff ist und somit hierfür auch kein Support übernommen werden kann. Auch ist die Parser-DLL kein offizielles Produkt, so dass wir für deren Benutzung keinerlei Gewährleistung übernehmen. Allerdings sind wir für Hinweise auf entsprechende Fehler dankbar.


TwinCAT ADS/AMS - Spezifikation

Diagnosehilfen