Version: 4.0.0

ADS Source

The Tributech ADS Source allows to connect to an Beckhoff ADS Server and receive or write values to the ADS Server. The Source acts like a ADS Client in a docker environment and enables the forwarding of the data to a Tributech Agent stream.

The Tributech ADS Source provides control over the single symbol paths:

Which symbol path to receive
How and when to receive a value from the symbol
What kind of datatype should be received from the symbol
When should a symbol be written to (Optional)

We generally provide two different ways to configure the Tributech ADS Source read operations for each symbol path individually:

Cyclic Reading - The symbol path will be read in a defined interval
On Change - The symbol path will be read when the value of the symbol has been changed

Setup

The Tributech ADS Source image can be started without any dependencies but will not be functional without a valid Twin Configuration or MessageBroker connect to the Tributech Agent. The TwinConfiguration can be provided via the Tributech Node (recommended) or MessageBroker (see Source Integration). The ADS Source will automatically connect to the Tributech Agent if the Tributech Agent is running and correct MessageBroker settings are set.

In the following part we will describe the setup of a Tributech ADS Source.

Setup the docker-compose.yml file by creating a docker-compose.yml file with the following content (adjustments required):

docker-compose.yml
version: '3.6'

services:
  source-ads:
    restart: unless-stopped
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-source-ads:${SOURCE_TAG:-latest}
    depends_on:
      - mosquitto-server-mqtt
      - tributech-agent
    environment:
      - MqttOptions__MQTTHost=mosquitto-server-ads
      - Logging__LogLevel__Default=Debug
      - Logging__LogLevel__ADSRouter=Error
    networks:
      ads-net:
        ipv4_address: 172.24.1.5
    logging:
      driver: "json-file"
      options:
        max-size: "2m"
        max-file: "5"

  tributech-agent:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-agent:${AGENT_TAG:-latest}
    depends_on:
      - mosquitto-server
    environment:
      - Logging__LogLevel__Default=Information
      - MqttOptions__MQTTHost=mosquitto-server
      - EdgeDeviceOptions__AgentID=${AGENT_ID:?"The Tributech Agent requires a GUID"}
      - EdgeDeviceOptions__NodeUrl=${NODE_URL:?"The Tributech Node Url is required"}
      - EnrollmentOptions__EnrollmentCertBase64=${ENROLLMENT_CERT_BASE64:?"The base64 encoded Enrollment Cert is required"}
      - EnrollmentOptions__EnrollmentKeyBase64=${ENROLLMENT_KEY_BASE64:?"The base64 encoded Enrollment Key is required"}
    networks:
      ads-net:
        ipv4_address: 172.24.1.7
    ports:
      - "5000:8080" # enable access to agent REST-API (e.g. for configuration with Agent-Companion)
    volumes:
      - ./volumes/ads/agent:/app/data # volume mapping for permanent storage of keys and datatwin file
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "2m"
        max-file: "5"

  mosquitto-server:
    image: eclipse-mosquitto:${MQTT_TAG:-1.6}
    restart: unless-stopped
    networks:
      ads-net:
         ipv4_address: 172.24.1.3

networks:
  ads-net:
    ipam:
      config:
        - subnet: 172.24.1.0/24

Adjust the setting for the Tribtech Agent to your environment, sample value:

env specific settings
tributech-agent:
    ...
    environment:
      ...
      - EdgeDeviceOptions__AgentID=00000000-0000-0000-0000-000000000007
      - EdgeDeviceOptions__NodeUrl=https://my-environment.tributech-node.com
      - EnrollmentOptions__EnrollmentCertBase64=LS0tLS1C...ZDdqb29rcUV
      - EnrollmentOptions__EnrollmentKeyBase64=AKS0tLS1C...ZDdqb29rcDE

Configuration

After setting up the Tributech ADS Source we need to activate it in the Tributech Node (see Agent Management) and configure the TwinConfiguration.

**"Configure Agent**

We can now add by right clicking the Device Edge entry a new Beckhoff TwinCat ADS Source.

**"Add ADS Source**

In order to connect to the ADS Server we need to configure the ADS Server settings. The following table contains the description for each setting for our MockClient. The table contents can also be found here: MockServer.

**"Config ADS Source**

Description for the settings:

Setting	Description
Server AMS Net Id	AMS Net Id of the PLC ADS Server
ADS Server Port	Port of the PLC ADS Server
ADS Server IP Address	IP-Address of the PLC ADS Server (needed for whitelist)
Client AMS Net Id	AMS Net Id of the ADS Source
InProcess Router Port	Should always be 48898, only needs to be changed if the network configuration changes
Read Cycle Default Interval	Default read interval value for all cyclic streams, will only be overruled if defined in the stream itself
Configuration writing Cycle	Write function cycle time to write values to the server (used for every parameter)

We can save the settings by clicking on the SAVE IN WORKSPACE button in the bottom right corner and add a new ADS Stream by right clicking on the ADS Source entry:

**"Add ADS Source stream**

The following screenshot contains the information for each setting for the ADS Stream path for a type LREAL (double), that will be read every 10sec from the MockServer:

**"Add ADS Stream config**

We can save the settings by clicking on the SAVE IN WORKSPACE button in the bottom right corner and continue adding every symbol path we want to read from the ADS Server.

After all symbol paths have been configured, we can apply the configuration to the Tributech Agent by clicking on the APPLY CONFIGURATION button in the top right corner.

Without the MockServer Setup or a real ADS Server we will not receive any data on the Tributech Node.

We can now see the value of the symbol path in the Beckhoff TwinCat ADS Stream:

**"Add MQTT Stream data**

Value Change Options

The basic handling of Value Change Options (VCO) can be found in Source Integration. This section contains the concrete handling of the Step (Delta) for the simulated source. The following list contains the description for each supported ADSDataType where X represents the value for Step (Delta):

INT, UINT, WORD, SINT, DINT, UDINT, DWORD, REAL, LREAL: defines the minimum difference between values to be submitted, the change is always compared to the last successful submitted value, e.g. if X= 3 if the values 1, 2, 5, 8, 10, 11, 14 are received by the Tributech Source only 1, 5, 8, 11, 14 will be submitted.
USINT, BYTE: will only be submitted if the value of the first byte of the current value is bigger or equal than the previous value
BOOL: will only be submitted if the current and last submitted value are not equal
STRING: will only be submitted if the current and last submitted value are not equal

Providing Data

If a Beckhoff ADS Server is used as a source, no specific settings are required, only the settings described in Configuration. If no Beckhoff ADS Server is available the Tributech ADS Source can use a Tributech ADS Mock to provide data to the Tributech ADS Source.

Mock Server

The Mock Server is an application based on the Beckhoff.TwinCAT.Ads.Server to generate a ADS Server with a symbol paths. The Mock Server can be started by downloading the docker-compose.override.yml file into the same folder as the Tributech ADS source.

docker-compose.override.yml
version: "3.6"

services:
 mock-server-ads:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-source-ads-mock:${SOURCE_TAG:-latest}
    restart: unless-stopped
    environment:
     - ASPNETCORE_ENVIRONMENT=Development
     - ASPNETCORE_URLS=http://+:5000
     - AdsSettings__ServerName=MockADS
     - AdsSettings__ServerPort=851
     - AdsSettings__NeedsRouter=true
     - ServerStructureSettings__InitValues__0__Value=2200215101
     - ServerStructureSettings__InitValues__0__Path=Settings.stConfigFile.sSerialNumber
     - AmsRouter__Name=MockServerRouter
     - AmsRouter__NetId=172.24.1.6.1.1
     - AmsRouter__RemoteConnections__0__Name=TestClient
     - AmsRouter__RemoteConnections__0__NetId=172.24.1.5.1.1
     - AmsRouter__RemoteConnections__0__Address=172.24.1.5
     - ValueGeneratorSettings__Enabled=true
     - ValueGeneratorSettings__ChangeAllValuesEveryInterval=true
    #ports:
      # - "127.0.0.1:5000:5000" # SwaggerUI
      # - "127.0.0.1:48898:48898" # TCP Router Port
      # - "127.0.0.1:48899:49999/udp" # UDP Router Port
    networks:
      ads-net:
         ipv4_address: 172.24.1.6

The Mock Server needs access to the same docker network as the Tributech ADS Source, therefore the IP addresses and environment variables need to be adjusted if they are not identical to our provided docker-compose.yml file (see Setup). After starting the Mock Server the configuration has to be pushed to the ADS Source again. To accomplish this go back to the Tributech ADS Source configuration window in the Tributech Node and click again on the APPLY CONFIGURATION button again. The ADS Source will now generate data points.

The following table contains the description for each available symbol path of the Mock Server:

Path	TypeName
GVL_Cloudtest.bValue	BOOL
GVL_Cloudtest.byValue	BYTE
GVL_Cloudtest.iValue	INT
GVL_Cloudtest.uiValue	UINT
GVL_Cloudtest.siValue	SINT
GVL_Cloudtest.usiValue	USINT
GVL_Cloudtest.dwValue	DWORD
GVL_Cloudtest.diValue	DINT
GVL_Cloudtest.udiValue	UDINT
GVL_Cloudtest.rValue	REAL
GVL_Cloudtest.lrValue	LREAL
GVL_Cloudtest.s50Value	STRING(50)
GVL_Cloudtest.s201Value	STRING(201)
GVL_Cloudtest.ws80Value	WSTRING(80)

Setup​

Configuration​

Value Change Options​

Providing Data​

Mock Server​

Setup

Configuration

Value Change Options

Providing Data

Mock Server