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

3KB

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