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