ADS

ADS stands for Automation Device Specification. It is a device-independent and fieldbus-independent interface to devices manufactured by Beckhoff Automation.

This protocol implementation allows the communication to such devices and provides the user the ability to create endpoints for reading, writing and subscribe for changes on the data provided by them.

Below you can see configuration parameters and examples on how to build a commissioning file for this protocol.

Connection Properties

localAddress (string, required)

The local address of the client

Example: "192.168.7.20.1.1"

localPort (integer, required)

The local TCP port used to communicate to the device.

Example: 32750

host (string, required)

The device address. It can be an IP address or a hostname.

Example: "192.168.2.114"

routerTcpPort (integer)

The ADS Router TCP port

Default: 48898

Example: 48898

port (integer, required)

AMS port of the ADS device. This is not the TCP port used but the setting usually known as PortNr.; the actual TCP port is adsRouterTcpPort.

Example: 851

netId (string, required)

AMS Net ID of the ADS device.

Example: "192.168.2.114.1.1"

timeoutDelay (integer)

Time (milliseconds) after connecting to the router or waiting for command response is canceled due to timeout

Default: 2000

connectionCheckEnabled (boolean)

If true, the connection will be regularly checked for existing connectivity in the time interval as defined in the parameter connectionCheckInterval. Otherwise no additional connectivity check is run.

Default: true

connectionCheckInterval (integer)

How often to check the connection (in milliseconds)

Default: 5000

connectionDownDelay (integer)

How much time should pass without response to mark the connection down (in milliseconds)

Default: 25000

connectionStrategy (object)

If a connection attempt fails, retries will be performed with increasing delay (waiting time) in between. The following parameters control how these delays behave.

Properties of the connectionStrategy object:

initialDelay (integer)

Delay (waiting time) of the first connection retry (in milliseconds). For subsequent retries, the delay will be increased according to the parameter incrementFactor which has a default value of 2.

Default: 1000

Additional restrictions:

  • Minimum: 1000

maxDelay (integer)

Maximum delay (waiting time) to wait until the next retry (in milliseconds). The delay (waiting time) for any subsequent connection retry will not be larger than this value. Must be strictly greater than initialDelay.

Default: 30000

incrementFactor (integer)

The factor used to increment initialDelay up to maxDelay. For example if initialDelay is set to 1000 and maxDelay to 5000 the values for the delay would be 1000, 2000, 4000, 5000.

Default: 2

Additional restrictions:

  • Minimum: 2

Endpoint Properties

symbolName (string, required)

The name of the variable to read/write/subscribe

Example: "Main.byByte[4]"

interval (integer)

Only for subscribe: The time interval between subsequent reads, in milliseconds. The value is received cyclically from the PLC at this interval. The smallest possible theoretical value is the cycle time of the PLC. If the interval is set to zero, the value is read at every PLC cycle. However, when setting the time interval to a small value, the MQTT broker of the Connectware might not be able to handle the resulting high data rate and data loss might occur, hence small time intervals must be handled with care. (The maximum value of 429 seconds is caused by the data type limit of this field within the ADS protocol.)

Default: 1000

Additional restrictions:

  • Maximum: 429496

onChange (boolean)

Only for subscribe: How subscriptions should report the variable values. If true, a value is sent only when it changed. If false, the value is sent on each time interval.

Default: false

dataType (string, enum)

Convert the ADS value to this specified type. Types are available in Big Endian (BE) variants or Little Endian (LE).

This element must be one of the following enum values:

  • raw

  • string

  • boolean

  • doubleBE

  • doubleLE

  • floatBE

  • floatLE

  • int8

  • int16BE

  • int16LE

  • int32BE

  • int32LE

  • bigInt64BE

  • bigInt64LE

  • uint16BE

  • uint16LE

  • uint32BE

  • uint32LE

  • bigUInt64BE

  • bigUInt64LE

Default: "raw"

Examples: "floatLE", "string"

readSize (integer)

Only needed for read variables of type string or raw: The number of bytes to read.

Default: 1

Additional restrictions:

  • Minimum: 1

Input Format

If data is written to Beckhoff ADS it must be provided as JSON object with the following fields:

The id (optional) could be anything. It is used for correlation of the request and response.

The value (mandatory) field is the actual data that is going to be written.

If raw bytes should be written, the JSON representation of a Javascript Buffer should be used.

Note: If 64-bit integers are being used (which are unsupported in JSON but Javascript support those by the BigInt class), they should be written using a Buffer object.

The following JSON message should be sent to a /set topic:

{
  "id": 1234,
  "value": 5658473
}

Which will produce a response on a /res topic:

{
  "id": 1234,
  "timestamp": 1641819737463,
  "value": true
}

Output Format

If data is read from Beckhoff ADS, the output will be provided as a JSON object.

For a read endpoint, additionally a correlation id (id) can be set in the payload of the message request, to ensure the correct identification of responses to specific requests.

The following JSON message can be sent to a /req topic:

{
  "id": 1234
}

Which will produce a response on a /res topic:

{
  "id": 1234,
  "timestamp": 1641819737462,
  "value": 123
}

Sample Commissioning file

Download: ads-example.yml

 1description: >
 2  Sample ADS service commissioning file
 3
 4metadata:
 5  name: Sample ADS service
 6  icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom1.svg
 7  provider: cybus
 8  homepage: https://www.cybus.io
 9  version: 1.0.0
10
11parameters:
12  # The local NetId of the client. Should be unique on all clients connected to the same ADS Router.
13  adsLocalNetId:
14    type: string
15    description: The local address of the client (local AMS NetId)
16    default: 192.168.7.12.1.1
17  adsLocalPort:
18    type: integer
19    description: The local TCP port used to communicate to the device
20    default: 32000
21  adsHost:
22    type: string
23    description: The device address (IP address or hostname) of the ADS router to connect to
24    default: 192.168.2.170
25  adsRouterTcpPort:
26    type: integer
27    description: This is the TCP port of the ADS router that is being connected to
28    default: 48898
29
30  # This is not the TCP used but the setting usually known as PortNr
31  # assigned to each device in the ADS router.
32  # The actual TCP used by the ADS library is 48898.
33  adsPort:
34    type: integer
35    description: AMS Port of the ADS device. This is not the TCP port used but the setting usually known as PortNr.; the actual TCP port is adsRouterTcpPort
36    default: 851
37  adsNetId:
38    type: string
39    description: AMS Net ID of the ADS device.
40    default: 192.168.2.170.1.1
41
42resources:
43  adsConnection:
44    type: Cybus::Connection
45    properties:
46      protocol: Ads
47      connection:
48        localAddress: !ref adsLocalNetId # The local NetId of the client.
49        localPort: !ref adsLocalPort
50        host: !ref adsHost
51        routerTcpPort: !ref adsRouterTcpPort
52        port: !ref adsPort # This is not the TCP used but the setting usually known as PortNr.
53        netId: !ref adsNetId # The device NetId
54
55  adsQuery1:
56    type: Cybus::Endpoint
57    properties:
58      protocol: Ads
59      connection: !ref adsConnection
60      subscribe:
61        symbolName: 'MAIN.byByte[4]'
62        dataType: 'int8'
63        interval: 1000
64
65  adsQuery2:
66    type: Cybus::Endpoint
67    properties:
68      protocol: Ads
69      connection: !ref adsConnection
70      write:
71        symbolName: 'MAIN.byByte[4]'
72        dataType: 'int8'
73
74  mapping:
75    type: Cybus::Mapping
76    properties:
77      mappings:
78        - subscribe:
79            endpoint: !ref adsQuery1
80          publish:
81            topic: 'output-topic'
82        - subscribe:
83            topic: 'input-topic'
84          publish:
85            endpoint: !ref adsQuery2