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

Endpoint Properties

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 }

Service Commissioning File Example

2KB

ads-example.yml

ads-example.yml

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