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.


ADS introduction

The Automation Device Specification (ADS) describes a device-independent and fieldbus-independent interface governing the type of access to ADS devices.

Device concept

The TwinCAT system architecture allows the individual modules of the software (e.g. TwinCAT PLC, TwinCAT NC, ...) to be treated as independent devices: For every task there is a software module ("Server" or "Client").

The messages between these objects are exchanged through a consistent ADS interface by the "message router". This manages and distributes all the messages in the system and over the TCP/IP connections. TwinCAT message routers exist on every TwinCAT PC and on every Beckhoff BCxxxx Bus Controller.

This allows all TwinCAT server and client programs to exchange commands and data.

Device definition

An object that has implemented the ADS interface (thus being accessible via ADS) and that offers "server services", is known as an ADS device. The detailed meaning of an ADS service is specific to each ADS device, and is described in the relevant ADS device documentation:

  • ADS PLC device documentation
  • ADS NC device documentation
  • ADS CAM (cam controller) device documentation

ADS libraries

In order to allow participation in ADS communication (as an ADS client or, possibly, as an ADS server) the following software objects are made available:

  • "TcSystem.lib" PLC library
    can be used in the TwinCAT PLC.
  • ADS-DLL
    for use under e.g. C/C++, Delphi, etc.
  • ADS.NET component
    for use under e.g. VB.NET, C#, Delphi.NET, Delphi Prism etc.
  • ADS-OCX (ActiveX-Control)
    for use under e.g. Visual Basic, C++, Delphi, etc.
  • ADS-Script-DLL
    for use under e.g. VBScript, JScript, etc.
  • ADS-WebService
    ADS services via HTTP for use under e.g. Visual C#, Delphi.NET, etc.
  • ADS-Java-DLL


ADS device identification

The unique identification of ADS devices is implemented with the aid of two identifiers:

  • AdsPortNr
  • AdsAmsNetId

(Note: In terms of a telecommunications analogy, the AdsAmsNetId corresponds to the "STD code" and the ADS-PortNr to the "subscriber number ".)

ADS-Port

The ADS devices in a TwinCAT message router are uniquely identified by a number referred to as the ADS-PortNr. For ADS devices this has a fixed specification, whereas pure ADS client applications (e.g. a visualisation system) are allocated a variable ADS port number when they first access the message router.

The following ADS port numbers are already assigned:

ADS-PortNr | ADS device description
100 | Logger (only NT-Log)
110 | Eventlogger
300 | IO
301 | additional Task 1
302 | additional Task 2
500 | NC
801 | PLC RuntimeSystem 1
811 | PLC RuntimeSystem 2
821 | PLC RuntimeSystem 3
831 | PLC RuntimeSystem 4
900 | Camshaft controller
10000 | System Service
14000 | Scope

ADS-AmsNetId

It is not only possible to exchange data between TwinCAT modules on one PC, it is even possible to do so by ADS methods between multiple TwinCAT PC's on the network.

Every PC on the network can be uniquely identified by a TCP/IP address, such as "172.1.2.16". The AdsAmsNetId is an extension of the TCP/IP address and identifies a TwinCAT message router, e.g. "172.1.2.16.1.1". TwinCAT message routers exist on every TwinCAT PC, and on every Beckhoff BCxxxx bus controller (e.g. BC3100, BC8100, BC9000, ...).

Configuration:

The ADS-AmsNetId of a TwinCAT-PC can be set in the TwinCAT system service: A menu appears after the system service icon has been selected. By selecting "Properties" you reach the "TwinCAT System Properties" dialogue.

After the "AMS router" page has been selected, the desired identifier can be read or modified in the "AMS Net Id" field. By default, the TwinCAT installation constructs the AMSNetId from the TCP/IP address of the PC with an extension of ".1.1" (as if it were a "sub-net mask" for field busses, target bus controllers,..).

The AMSNetId can in fact be freely chosen.

When the services of an ADS device in the network are called on, its message router, or, more precisely, its AMSNetId, must be known. This is achieved through insertion of the target PC, as a result of which TwinCAT can establish the connection between the TCP/IP address of the target PC and the AMSNetId of the target message router address.


Setting Up an ADS Remote Connection

In order to create an AMS connection between a number (n) of computers, these computers need to be fitted with network cards. The network must be set up under Windows NT. If the computer is being operated in a LAN network, then it is possible to obtain the TCP/IP address of the computer via the DHCP server. If, for instance, the remote connection is being used to service equipment that is in operation, then it is recommended that a fixed TCP/IP address be assigned.

Assigning a fixed address also prevents the event display being filled up with the following error message: 'DHCP could not obtain a lease for the IP address for the card with network address 00E0F40FC80F. The following error occurred: The time limit for the semaphore was reached.'.

The network connection between the n computers should be tested using the command "ping <PCI/IP- address of the target computer>". If the network test is successful, it is possible to begin the settings in TwinCAT. The remote computers must first be made known to one another.

Entries necessary for this purpose are made under TwinCAT+-> Properties +-> AMS Router.

The AMS Net ID is composed of the TCP/IP of the local computer plus the suffix ".1.1". The AMS Net ID is based on the TCP/IP address, but the relationship is not entirely fixed.

Add should be pressed in order to include a remote computer in the connection.

It is possible to enter the parameters manually in his window, or to select them using Browse. This procedure is repeated n-1 times. Take care to see that the data in the window for adding a remote connection agree with the data for the remote computer. The host computer is added in the same way at the remote computer.

When the settings have been entered, they are confirmed with the Return key. The n computers can be restarted at this point.

In PLC Control, under Online +-> Select target system, one of the n computers can be selected as the PLC platform for the current PLC project.


Cookbook "How to implement an ADS client"

• 0. Overview
• 1. Get started and open/connect to ADS router
• 2. Which variables available
• 3. Get handles of variables
• 4. Cyclic collection of life data
• 5. Release handles
• 6. Close ADS channel
• 7. In case of ADS error

0. Overview

Always good to start with overview
Following samples are based on C++, however they work identically for C#

See device concept

1. Get started and open/connect to ADS router

Overview C++ samples

The easy (but not recommended way) to read data: Read flag synchronously from the PLC by absolute adress information
See sample

Disadvantage: If PLC code or PLC variable declaration is changing the ADS-client will not notice this in any case.
WE HIGHLY RECOMMEND to work on handles of variables (see Agenda 3)

2. Which variables available

By compiling PLC code the PLC-Editor "PLC-Control" creates an XML-based export file <projectname.tpy> containing all information about symbols (variables) and their properties (datatype etc).
At HMI design time this file can be imported to Scada editor to configure mapping between variable and HMI-object.

We are preparing sample code to parse typ on demand, will be available here

3. Get handles of variables

ADS-List-command: Get/Release multiple handles with one ADS call
Instead looping through a routine to get handles we recommend, to save protocol transport time by requesting multiple handles with one single ADS call
See sample C++

NOTE:
Devices with previous TwinCAT-versions might not support this call (ADS returncode “Service not supported”). In this case collect handles one by one.

4. Cyclic collection of life data

ADS Sum Command : Read

Works also for write direction
The Sub-IndexGroup should always be 0xF005 in combination with the Sub-IndexOffset filled with the handle of variable.

See sample C++

5. Release handles

ADS-List-command: Get/Release multiple handles with one ADS call
Instead looping through a routine to release handles we recommend, to save protocol transport time by releasing multiple handles with one single ADS call

See sample C++

NOTE:
Devices with previous TwinCAT-versions might not support this call (ADS returncode “Service not supported”) In this case release handles one by one.

6. Close ADS channel

Always close ADS channel PortClose() – be aware to release handles before !

7. In case of ADS error

Alsways good to take care on return codes
See ADS return codes

In case of return code “Invalid handle” somebody downloaded a new PLC code or restarted the TwinCAT machine.
Release existing handles and request new handles, after this continue collection data.

ADS-Monitor is helpfully tool for diagnostic - public available
Download


ADS Return Codes

Error codes: 0x000..., 0x500..., 0x700..., 0x1000..., 0x274C...

Global Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x0 | 0 | no error |  |
0x1 | 1 | Internal error |  |
0x2 | 2 | No Rtime |  |
0x3 | 3 | Allocation locked memory error |  |
0x4 | 4 | Insert mailbox error | No ADS mailbox was available to process this message. | Reduce the number of ADS calls (e.g ADS-Sum commands or Max Delay Parameter)
0x5 | 5 | Wrong receive HMSG |  |
0x6 | 6 | target port not found | ADS Server not started |
0x7 | 7 | target machine not found | Missing ADS routes |
0x8 | 8 | Unknown command ID |  |
0x9 | 9 | Bad task ID |  |
0xA | 10 | No IO |  |
0xB | 11 | Unknown ADS command |  |
0xC | 12 | Win 32 error |  |
0xD | 13 | Port not connected |  |
0xE | 14 | Invalid ADS length |  |
0xF | 15 | Invalid ADS Net ID |  |
0x10 | 16 | Low Installation level |  |
0x11 | 17 | No debug available |  |
0x12 | 18 | Port disabled |  |
0x13 | 19 | Port already connected |  |
0x14 | 20 | ADS Sync Win32 error |  |
0x15 | 21 | ADS Sync Timeout |  |
0x16 | 22 | ADS Sync AMS error |  |
0x17 | 23 | ADS Sync no index map |  |
0x18 | 24 | Invalid ADS port |  |
0x19 | 25 | No memory |  |
0x1A | 26 | TCP send error |  |
0x1B | 27 | Host unreachable |  |
0x1C | 28 | Invalid AMS fragment |  |

Router Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x500 | 1280 | ROUTERERR_NOLOCKEDMEMORY | No locked memory can be allocated |
0x501 | 1281 | ROUTERERR_RESIZEMEMORY | The size of the router memory could not be changed |
0x502 | 1282 | ROUTERERR_MAILBOXFULL | The mailbox has reached the maximum number of possible messages. The current sent message was rejected | Check the connection between the communication partners
0x503 | 1283 | ROUTERERR_DEBUGBOXFULL | The mailbox has reached the maximum number of possible messages. The sent message will not be displayed in the debug monitor | Check the connection to the debug monitor
0x504 | 1284 | ROUTERERR_UNKNOWNPORTTYPE | The port type is unknown |
0x505 | 1285 | ROUTERERR_NOTINITIALIZED | Router is not initialised |
0x506 | 1286 | ROUTERERR_PORTALREADYINUSE | The desired port number is already assigned |
0x507 | 1287 | ROUTERERR_NOTREGISTERED | Port not registered |
0x508 | 1288 | ROUTERERR_NOMOREQUEUES | The maximum number of Ports reached |
0x509 | 1289 | ROUTERERR_INVALIDPORT | The port is invalid. |
0x50A | 1290 | ROUTERERR_NOTACTIVATED | TwinCAT Router not active |
0x50B | 1291 | ROUTERERR_FRAGMENTBOXFULL |  |
0x50C | 1292 | ROUTERERR_FRAGMENTTIMEOUT |  |
0x50D | 1293 | ROUTERERR_TOBEREMOVED |  |

General ADS Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x700 | 1792 | error class <device error> |  |
0x701 | 1793 | Service is not supported by server |  |
0x702 | 1794 | invalid index group |  |
0x703 | 1795 | invalid index offset |  |
0x704 | 1796 | reading/writing not permitted |  |
0x705 | 1797 | parameter size not correct |  |
0x706 | 1798 | invalid parameter value(s) |  |
0x707 | 1799 | device is not in a ready state |  |
0x708 | 1800 | device is busy |  |
0x709 | 1801 | invalid context (must be in Windows) |  |
0x70A | 1802 | out of memory |  |
0x70B | 1803 | invalid parameter value(s) |  |
0x70C | 1804 | not found (files, ...) |  |
0x70D | 1805 | syntax error in command or file |  |
0x70E | 1806 | objects do not match |  |
0x70F | 1807 | object already exists |  |
0x710 | 1808 | symbol not found |  |
0x711 | 1809 | symbol version invalid | Onlinechange | Release handle and get a new one
0x712 | 1810 | server is in invalid state |  |
0x713 | 1811 | AdsTransMode not supported |  |
0x714 | 1812 | Notification handle is invalid | Onlinechange | Release handle and get a new one
0x715 | 1813 | Notification client not registered |  |
0x716 | 1814 | no more notification handles |  |
0x717 | 1815 | size for watch too big |  |
0x718 | 1816 | device not initialized |  |
0x719 | 1817 | device has a timeout |  |
0x71A | 1818 | query interface failed |  |
0x71B | 1819 | wrong interface required |  |
0x71C | 1820 | class ID is invalid |  |
0x71D | 1821 | object ID is invalid |  |
0x71E | 1822 | request is pending |  |
0x71F | 1823 | request is aborted |  |
0x720 | 1824 | signal warning |  |
0x721 | 1825 | invalid array index |  |
0x722 | 1826 | symbol not active | Onlinechange | Release handle and get a new one
0x723 | 1827 | access denied |  |
0x724 | 1828 | missing license |  | Activate license for TwinCAT 3 function
0x72c | 1836 | exception occured during system start |  | Check each device transistions
0x740 | 1856 | Error class <client error> |  |
0x741 | 1857 | invalid parameter at service |  |
0x742 | 1858 | polling list is empty |  |
0x743 | 1859 | var connection already in use |  |
0x744 | 1860 | invoke ID in use |  |
0x745 | 1861 | timeout elapsed |  | Check ADS routes of sender and receiver and your firewall setting
0x746 | 1862 | error in win32 subsystem |  |
0x747 | 1863 | Invalid client timeout value |  |
0x748 | 1864 | ads-port not opened |  |
0x750 | 1872 | internal error in ads sync |  |
0x751 | 1873 | hash table overflow |  |
0x752 | 1874 | key not found in hash |  |
0x753 | 1875 | no more symbols in cache |  |
0x754 | 1876 | invalid response received |  |
0x755 | 1877 | sync port is locked |  |

RTime Error Codes

Hex | Dec | Description | Possible Causes
0x1000 | 4096 | RTERR_INTERNAL | Internal fatal error in the TwinCAT real-time system
0x1001 | 4097 | RTERR_BADTIMERPERIODS | Timer value not vaild
0x1002 | 4098 | RTERR_INVALIDTASKPTR | Task pointer has the invalid value ZERO
0x1003 | 4099 | RTERR_INVALIDSTACKPTR | Task stack pointer has the invalid value ZERO
0x1004 | 4100 | RTERR_PRIOEXISTS | The demand task priority is already assigned
0x1005 | 4101 | RTERR_NOMORETCB | No more free TCB (Task Control Block) available. Maximum number of TCBs is 64
0x1006 | 4102 | RTERR_NOMORESEMAS | No more free semaphores available. Maximum number of semaphores is 64
0x1007 | 4103 | RTERR_NOMOREQUEUES | No more free queue available. Maximum number of queue is 64
0x1008 | 4104 | TwinCAT reserved. |
0x1009 | 4105 | TwinCAT reserved. |
0x100A | 4106 | TwinCAT reserved. |
0x100B | 4107 | TwinCAT reserved. |
0x100C | 4108 | TwinCAT reserved. |
0x100D | 4109 | RTERR_EXTIRQALREADYDEF | An external synchronisation interrupt is already applied
0x100E | 4110 | RTERR_EXTIRQNOTDEF | No external synchronsiation interrupt applied
0x100F | 4111 | RTERR_EXTIRQINSTALLFAILED | The apply of the external synchronisation interrupt failed
0x1010 | 4112 | RTERR_IRQLNOTLESSOREQUAL | Call of a service function in the wrong context
0x1017 | 4119 | RTERR_VMXNOTSUPPORTED | Intel VT-x extension is not supported.
0x1018 | 4120 | RTERR_VMXDISABLED | Intel VT-x extension is not enabled in BIOS.
0x1019 | 4121 | RTERR_VMXCONTROLSMISSING | Missing feature in Intel VT-x extension.
0x101A | 4122 | RTERR_VMXENABLEFAILS | Enabling Intel VT-x fails.

TCP Winsock Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x274c | 10060 | A socket operation was attempted to an unreachable host | Host unreachable | Check network connection via ping
0x274d | 10061 | A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond. | Host unreachable | Check network connection via ping
0x2751 | 10065 | No connection could be made because the target machine actively refused it |  |
 |  | Further Winsock error codes: Win32 Error Codes |  |


Client-server relationship

ADS services can initially be categorised into "confirmed" and "unconfirmed" services.

ADS-Client | ADS-Server
Request -> | -> Indication
Confirmation <- | <- Response

The progress of an ADS communication begins with an ADS request, which arrives at the ADS server where it is viewed as an ADS indication.
The ADS server replies with an ADS response, which in turn is received by the ADS client as an ADS confirmation.

Messages that are sent autonomously by an ADS server (e.g. error or other status messages) are registered by the ADS client as a notification indication.

General ADS services:

The general ADS communication services are classified into

  • Asynchronous

    - the client make the ADS request to the server
    - the client continues to operate (without the ADS confirmation)
    - the server processes the ADS request, and provides the client with the result with a call-back (ADS confirmation to the client)
  • Notification

    - the client registers itself with an ADS request to the server for a specific service
    - the server provides the service to the client autonomously by call-back (ADS confirmation to the client), until the client cancels its request for the service

    - the advantage of this kind of communication is the low additional ADS protocol overhead, since cyclical ADS requests from the client program are not occurring

Specific ADS services:

Over and above the general ADS services, additional functions that encapsulate ADS communications and permit operation with, e.g., Visual Basic or Visual C++ are defined. These "specific ADS services " are implemented in ADS-OCX or in the ADS-DLL, and provide, for instance, facilities for synchronous communication, or give consideration to restrictions that might exist (in Visual Basic, for example, variable types with no leading sign).

  • Synchronous

    - the client make the ADS request to the server
    - the client thread that makes the call is suspended for the duration of the ADS communication
    - when the ADS request call returns, the result from the ADS server is already available

    - the advantage of this kind of communication is the low administrative overhead required from the client program