Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Introduction

The following description reveals the specification for the ADS/AMS protocol via TCP/IP. Thereby it´s possible to realise own implementations of ADS/AMS, e.g for other operating systems than windows, or for not supported programming languages.

The communication implements via TCP/IP, Port 48898 (0xBF02). The principle operating sequence of the communication is described in the documentation TwinCAT ADS under 'ADS Introduction'.


AMS/TCP Packet

TwinCAT ADS/AMS - Specification

Structure AMS/TCP Packet

Data array | Size | Description
AMS/TCP Header | 6 bytes | contains the length of the data packet.
AMS Header | 32 bytes | The AMS/TCP-Header contains the addresses of the transmitter and receiver. In addition the AMS error code , the ADS command Id and some other information.
ADS Data | n bytes | The ADS data range contains the parameter of the single ADS commands. The structure of the data array depends on the ADS command. Some ADS commands require no additional data.


AMS/TCP Header

Data array | Size | Description
reserved | 2 bytes | These bytes must be set to 0.
Length | 4 bytes | This array contains the length of the data packet. It consists of the AMS-Header and the enclosed ADS data. The unit is bytes.


AMS Header

Data array | Size | Description
AMSNetId Target | 6 bytes | This is the AMSNetId of the station, for which the packet is intended. Remarks see below.
AMSPort Target | 2 bytes | This is the AMSPort of the station, for which the packet is intended.
AMSNetId Source | 6 bytes | This contains the AMSNetId of the station, from which the packet was sent.
AMSPort Source | 2 bytes | This contains the AMSPort of the station, from which the packet was sent.
Command Id | 2 bytes | see below.
State Flags | 2 bytes | see below.
Data Length | 4 bytes | Size of the data range. The unit is byte.
Error Code | 4 bytes | AMS error number. See ADS Return Codes.
Invoke Id | 4 bytes | Free usable 32 bit array. Usually this array serves to send an Id. This Id makes is possible to assign a received response to a request, which was sent before.
Data | n bytes | Data range. The data range contains the parameter of the considering ADS commands.

AMS Net Id

The AMSNetId consists of 6 bytes and addresses the transmitter or receiver. One possible AMSNetId would be e.g.. 172.16.17.10.1.1. The storage arrangement in this example is as follows:

The AMSNetId is purely logical and has usually no relation to the IP address. The AMSNetId is configurated at the target system. At the PC for this the TwinCAT System Control is used. If you use other hardware, see the considering documentation for notes about settings of the AMS NetId.

Command Id

Cmd | Description
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

Other commands are not defined or are used internally. Therefore the Command Id is only allowed to contain the above enumerated values!

State Flags

Flag | Description
0x0001 | 0: Request / 1: Response
0x0004 | ADS command

The first bit marks, whether it´s a request or response. The third bit must be set to 1, to exchange data with ADS commands. The other bits are not defined or were used for other internal purposes.

Therefore the other bits must be set to 0!

Flag | Description
0x000x | TCP Protocol
0x004x | UDP Protocol

Bit number 7 marks, if it should be transfered with TCP or UDP.


ADS Commands

TwinCAT ADS/AMS - Specification

Command Overview

Command | Description
ADS Read Device Info | Reads the name and the version number of the ADS device.
ADS Read | With ADS Read data can be read from an ADS device
ADS Write | With ADS Write data can be written to an ADS device.
ADS Read State | Reads the ADS status and the device status of an ADS device.
ADS Write Control | Changes the ADS status and the device status of an ADS device.
ADS Add Device Notification | A notification is created in an ADS device.
ADS Delete Device Notification | One before defined notification is deleted in an ADS device.
ADS Device Notification | Data will carry forward independently from an ADS device to a Client
ADS Read Write | With ADS Read Write data will be written to an ADS device. Additionally, data can be read from the ADS device.


ADS Read Device Info

Reads the name and the version number of the ADS device.

Request

No additional data required

Response

Data array | Size | Description
Result | 4 bytes | ADS error number.
Major Version | 1 byte | Major version number
Minor Version | 1 byte | Minor version number
Version Build | 2 bytes | Build number
Device Name | 16 bytes | Name of ADS device


ADS Read

With ADS Read data can be read from an ADS device. The data are addressed by the Index Group and the Index Offset

Request

Data array | Size | Description
Index Group | 4 bytes | Index Group of the data which should be read.
Index Offset | 4 bytes | Index Offset of the data which should be read.
Length | 4 bytes | Length of the data (in bytes) which should be read.

Response

Data array | Size | Description
Result | 4 bytes | ADS error number
Length | 4 bytes | Length of data which are supplied back.
Data | n bytes | Data which are supplied back.


ADS Write

With ADS Write data can be written to an ADS device. The data are addressed by the Index Group and the Index Offset

Request

Data array | Size | Description
Index Group | 4 bytes | Index Group in which the data should be written
Index Offset | 4 bytes | Index Offset, in which the data should be written
Length | 4 bytes | Length of data in bytes which are written
Data | n bytes | Data which are written in the ADS device.

Response

Data array | Size | Description
Result | 4 bytes | ADS error number


ADS Read State

Reads the ADS status and the device status of an ADS device.

Request

No additional data required

Response

Data array | Size | Description
Result | 4 bytes | ADS error number.
ADS State | 2 bytes | ADS status (see data type ADSSTATE of the ADS-DLL).
Device State | 2 bytes | Device status


ADS Write Control

Changes the ADS status and the device status of an ADS device. Additionally it is possible to send data to the ADS device to transfer further information. These data were not analysed from the current ADS devices (PLC, NC, ...)

Request

Data array | Size | Description
ADS State | 2 bytes | New ADS status (see data type ADSSTATE of the ADS-DLL).
Device State | 2 bytes | New device status.
Length | 4 bytes | Length of data in byte.
Data | n bytes | Additional data which are sent to the ADS device

Response

Data array | Size | Description
Result | 4 bytes | ADS error number.


ADS Add Device Notification

A notification is created in an ADS device.

Note: We recommend to announce not more then 550 notifications per device. You can increase the payload by organizing the data in structures.

Request

Data array | Size | Description
Index Group | 4 bytes | Index Group of the data, which should be sent per notification.
Index Offset | 4 bytes | Index Offset of the data, which should be sent per notification.
Length | 4 bytes | Length of data in bytes, which should be sent per notification.
Transmission Mode | 4 bytes | See description of the structure ADSTRANSMODE at the ADS-DLL.
Max Delay | 4 bytes | At the latest after this time, the ADS Device Notification is called. The unit is 1ms.
Cycle Time | 4 bytes | The ADS server checks if the value changes in this time slice. The unit is 1ms
reserved | 16bytes | Must be set to 0

Response

Data array | Size | Description
Result | 4 bytes | ADS error number
Notification Handle | 4 bytes | Handle of notification


ADS Delete Device Notification

One before defined notification is deleted in an ADS device.

Request

Data array | Size | Description
Notification Handle | 4 bytes | Handle of notification. The handle is created by the ADS command Add Device Notification

Response

Data array | Size | Description
Result | 4 bytes | ADS error number


ADS Device Notification

Data will carry forward independently from an ADS device to a Client.

Request

The data which are transfered at the Device Notification are multiple nested into one another. The Notification Stream contains an array with elements of type AdsStampHeader. This array again contains elements of type AdsNotificationSample.

AdsNotificationStream

Data array | Size | Description
Length | 4 bytes | Size of data in byte.
Stamps | 4 bytes | Number of elements of type AdsStampHeader.
AdsStampHeader | n bytes | Array with elements of type AdsStampHeader.

AdsStampHeader

Data array | Size | Description
TimeStamp | 8 bytes | The timestamp is coded after the Windos FILETIME format. I.e. the value contains the number of the nano seconds, which passed since 1.1.1601. In addition, the local time change is not considered. Thus the time stamp is present as universal Coordinated time (UTC).
Samples | 4 bytes | Number of elements of type AdsNotificationSample.
AdsNotificationSample | n bytes | Array with elements of type AdsNotificationSample.

AdsNotificationSample

Data array | Size | Description
Notification Handle | 4 Bytes | Handle of notification.
Sample Size | 4 Bytes | Size of data range in bytes.
Data | n Bytes | Data

Notice: If your handle becomes invalid, one notification without data will be send once as advice.


ADS Read Write

With ADS Read Write data will be written to an ADS device. Additionally, data can be read from the ADS device.

The data which can be read are addressed by the Index Group and the Index Offset

Request

Data array | Size | Description
Index Group | 4 bytes | Index Group, in which the data should be written.
Index Offset | 4 bytes | Index Offset, in which the data should be written
Read Length | 4 bytes | Length of data in bytes, which should be read.
Write Length | 4 bytes | Length of data in bytes, which should be written
Data | n bytes | Data which are written in the ADS device.

Response

Data array | Size | Description
Result | 4 bytes | ADS error number
Length | 4 bytes | Length of data which are supplied back.
Data | n bytes | Data which are supplied back.


TwinCAT AMS/ADS Debugger

The TwinCAT AMS/ADS Debugger records the total data traffic via the TwinCAT Message Router. This concerns as well the communication of ADS devices among each other, if they are on the same computer (e.g. the data exchange between TwinCAT NC and TwinCAT PLC, or between the TwinCAT Camshaft controller and the fieldbus). The TwinCAT AMS/ADS Debugger exists on the TwinCAT CD in the directory Unsupported Utilities.

Note:

It must be pointed out, that the TwinCAT AMS/ADS Debugger is no official product of BECKHOFF GmbH. We assume no warranty or support for their use.
Indeed we are grateful for references to errors.


Microsoft Network Monitor

The MS Netzwerk Monitor 2 can be extended by appropriate Parser-DLLs by further protocols. Such an extension-DLL for the AMS/TCP protocol is supplied with TwinCAT.
This DLL exists on the TwinCAT CD in the directory Unsupported Utilities and has to be copied in the sub directory Parsers of the MS Network Monitor .

With the help of the MS Network Monitors it´s only possible to record the communication via the Ethernet Interface. The recording with other fieldbusses (Lightbus, Profibus, ..) is not possible.

Note:

It must be pointed out, that the MS Netzwerk Monitor and the Parser-DLL are no products of BECKHOFF GmbH. We assume no warranty or support for their use.
Indeed we are grateful for references to errors.