.. _user/protocols/ads:

******
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.

.. _user/protocols/ads_connection:
.. include:: ../protocolSchemas/AdsConnection.rst


.. _user/protocols/ads_endpoint:
.. include:: ../protocolSchemas/AdsEndpoint.rst

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:

.. code:: json

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

Which will produce a response on a ``/res`` topic:

.. code:: json

  {
    "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:

.. code:: json

  {
    "id": 1234
  }

Which will produce a response on a ``/res`` topic:

.. code:: json

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

Sample Commissioning file
=========================

Download: :download:`ads-example.yml`

.. literalinclude:: ads-example.yml
  :language: yaml
  :linenos: