Skip to content

Twincat ADS Flux Asset

Introduction

TwinCAT ADS (Automation Device Specification) is a key component of the TwinCAT automation software suite developed by Beckhoff. It provides a robust and flexible communication protocol designed to facilitate high-speed data exchange between Beckhoff's PLCs, embedded controllers, and PCs.

ADS2MQTT enables communication with TwinCAT ADS devices, compatible with both TwinCAT 2 and 3 systems. It reads values from these devices and posts them to Coreflux Central, an MQTT broker. Additionally, it can receive data from Coreflux Central and relay it back to the ADS devices, facilitating a bidirectional data flow.

Features and Benefits

  • Seamless Communication: Enables seamless communication between Beckhoff PLCs and your data hub.
  • Real-time Monitoring: Allows real-time monitoring of Beckhoff PLCs.
  • Easy Integration: Easily integrate Beckhoff PLCs with your IIoT projects.
  • Auto discovery: Allows user to find all symbols on the device.
  • Router and route creation: ADS2MQTT comes with a router that makes it possible to create route from device to asset and vice versa.

Prerequisites

Before you install and configure the asset, make sure you have the following prerequisites:

  • Basic understanding of the MQTT protocol.
  • Basic undertstanding of ADS protocol.
  • Coreflux account.
  • Coreflux 1.2 MQTT broker.
  • MQTT Client (such as MQTT Explorer).
  • A Beckhoff PLC (or soft PLC).

Asset installation

Using Coreflux HUB

Please refer to the general docs for asset installation through the Coreflux HUB.

Using Coreflux HUBLESS

Asset management and control are conducted using the MQTT protocol. Commands (payload) are sent to the \(SYS/Coreflux/Command** topic. The results of these commands are published to **\)SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

  1. Connect to the Coreflux MQTT Broker using your preferred client.
  2. Login using your coreflux account:
    -L myname@mydomain.com password`
    
  3. Check your available assets:
    -l
    
  4. Install asset:
    -I coreflux_ads2mqtt
    
  5. If there were no issues during the installation you should receive a message on the $SYS/Coreflux/Command/Output:
    Your coreflux_ads2mqtt was installed with version <version> with the <asset_guid>. Let the magic begin! 
    

Asset configuration

Before using the asset, it must be properly configured. This configuration process entails adjusting various parameters that affect its functionality, the setup of the device, and how they interact with each other. This involves specifying the device's IP address, selecting which symbols to read from the device, among other settings. The configuration is detailed in a JSON file, divided into three main sections: MQTT Parameters, ADS Parameters and Tags. The instructions below will guide you through configuring each section. By the end, you will have a comprehensive example configuration that can be tailored to your specific needs.

⚠ Warning: If a parameter is not included in your asset's configuration and it is not required, a default value will be applied. Incorrect configuration may cause the asset to not work as intended.

ℹ Information: This configuration is presented using a hubless setup as an example. The key takeaway is the understanding of the parameters and their significance. If you are configuring the asset via Coreflux Hub, the same parameters and configurations apply.

MQTT Parameters

The MQTTParameters in the JSON configuration define how to connect to an MQTT broker, specifying the communication details. The Address and Port indicate the broker's network location (in this case, 127.0.0.1 on port 1883), which is where the data will be sent to or received from. The parameters also detail authentication methods and the use of TLS for secure communication. This setup determines the pathway for data exchange between the device and the MQTT broker, facilitating the monitoring or control of device operations.

Parameter Description Required Example Default Value
Port Port number on which the MQTT broker is running. Yes 1883 1883
Address IP address or hostname of the MQTT broker. Yes "127.0.0.1" "127.0.0.1"
IsAnonymous Indicates if the connection is anonymous (no username/password required). Yes true true
Username Username for authentication, if not anonymous. No "" (empty string) "" (empty string)
Password Password for authentication, if not anonymous. No "" (empty string) "" (empty string)
EnableTLS Specifies whether TLS encryption is enabled for secure communication. Yes true false

Example:

{
  "MQTTParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "EnableTLS": false
  }
}

ADS Parameters

The ADSParameters in the JSON configuration outline the setup for ADS communication between a local system and a target device. These parameters are crucial for facilitating communication using the ADS protocol. They include specifying local and target network IDs for unique identification, defining the target port for ADS requests, and setting a route name for easier management. The target device's IP address directs the flow of ADS communication. The auto-discovery feature is designed to scan the device for available symbols, displaying both the symbols and their values via MQTT. This configuration is essential for ensuring efficient data exchange and control within ADS-compliant environments. The asset also functions as an ADS router, creating routes from the asset to the device or a soft PLC. For communication to be established, there must be a route from the asset to the device and vice versa. The user can create routes using TcXaeShell software, or utilize the asset by providing TargetUser and TargetPassword parameters.

Parameter Description Required Example Default Value
LocalNetId Network ID of the local system initiating the ADS connection. Must follow the format: IP.IP.IP.IP.Port.Port, with IP segments up to 255 and Port up to 65535. Yes "192.168.1.1.851.851" N/A
LocalRouteToTarget Descriptive name for the local route to the target device. Yes "LocalToTargetRoute" N/A
LocalHostName Hostname of the local system. Yes "LocalHost" N/A
TargetNetId Network ID of the target device for communication. Must follow the format: IP.IP.IP.IP.Port.Port, with IP segments up to 255 and Port up to 65535. Yes "192.168.2.2.851.851" N/A
TargetIp IP address of the target device. Must be a valid IPv4 address (e.g., 192.168.1.1). Yes "192.168.2.2" N/A
TargetPort Port number on the target device for ADS communication. Must be between 0 and 65535. Yes 851 851
TargetRouteToLocal Descriptive name for the target device's route to the local system. Yes "TargetToLocalRoute" N/A
TargetUser Username for authentication with the target device. Yes "admin" N/A
TargetPassword Password for authentication with the target device. Yes "password" N/A
AutoDiscovery Auto discover variables on the device. No N/A false

Auto Discovery

This feature, when enabled, automates the discovery of variables on the device and facilitates the publishing of their respective values to the configured MQTT broker. It offers configurability in terms of the frequency at which variables are posted to the broker, whether the values are retained, and the Quality of Service (QoS) level.

Parameter Description Required Example Default Value
Active Activate auto discovery feature. true true false
BaseTopic Define the the base topic for each discovered variable. false true "ads/discovery"
MQTTQoS Quality of Service level for MQTT communication (0 to 2), balancing efficiency and reliability of message delivery. Yes 1 0 (AtMostOnce)
MQTTRetain Indicates if the last message published to the MQTT topic should be retained by the broker. Yes true false
Trigger Condition under which data exchange occurs (OnStart, OnChange, Cyclic), for data updates communication. Yes "Cyclic" 1 (ToBroker)
Cycle For cyclic triggers, interval in milliseconds for data updates, minimum of 10. Yes 1000 2000 (For cyclic triggers)

Example:

{
  "MQTTParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "EnableTLS": false
  },
  "ADSParameters": {
    "LocalNetId": "1.1.1.1.1.1",
    "LocalRouteToTarget": "I7DESKTOP",
    "LocalHostName": null,
    "TargetNetId": "5.99.58.57.1.1",
    "TargetIp": "192.168.100.202",
    "TargetPort": 851,
    "TargetRouteToLocal": "Asset",
    "TargetUser": "Administrator",
    "TargetPassword": "1",
    "AutoDiscovery": {
      "Active": true,
      "BaseTopic": "ads/discovery",
      "DefaultTag": {
        "MQTTQoS": 0,
        "MQTTRetain": false,
        "Trigger": 1,
        "Cycle": 2000,
      }
    }
  },
  "Tags": []
}

Tags

Tags serve as the bridge between the PLC's variables and the MQTT topics within your system. Each Tag represents a specific connection point, linking a piece of data on the PLC to a topic on the MQTT broker. Each Tag in your array of Tags encapsulates the necessary details for this data exchange, including parameters related to both the PLC device (such as the data type and trigger conditions) and the MQTT protocol (such as the topic, quality of service, and retain flag).

ℹ Information: Tags array is not required in the configuration, if it is not included in the configuration, the asset will still run.

Parameter Description Required Example Default Value
Name A unique identifier for the tag, up to 50 characters. Used to reference the tag within the system. Yes "MyTag" N/A
WriteDirection Direction of data flow (ToOther (PLC or Soft PLC) or ToBroker), indicating data direction to/from the MQTT broker. Yes "ToBroker" N/A
MQTTTopic MQTT topic for publishing or subscribing data associated with the Tag. Yes "PLC/DataUpdate" N/A
MQTTQoS Quality of Service level for MQTT communication (0 to 2), balancing efficiency and reliability of message delivery. Yes 1 0 (At most once)
MQTTRetain Indicates if the last message published to the MQTT topic should be retained by the broker. Yes true false
SymbolPath Identifies the PLC's memory address or variable associated with the tag, up to 56 characters. Yes "Main.PLCVar" N/A
Trigger Condition under which data exchange occurs (OnStart, OnChange, Cyclic), for data updates communication. Yes "Cyclic" N/A
DataType Type of data (BOOL, INT, REAL, STRING, etc. List of all data types), ensuring correct handling according to its nature. Yes "INT" N/A
Cycle For cyclic triggers, interval in milliseconds for data updates, minimum of 10. Yes 1000 1000 (For cyclic triggers)
Size Size of the data in bytes, crucial for parsing and handling the data payload. Yes 4 N/A

Example:

{
  "MQTTParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "EnableTLS": false
  },
  "ADSParameters": {
    "LocalNetId": "1.1.1.1.1.1",
    "LocalRouteToTarget": "I7DESKTOP",
    "LocalHostName": null,
    "TargetNetId": "5.99.58.57.1.1",
    "TargetIp": "192.168.100.202",
    "TargetPort": 851,
    "TargetRouteToLocal": "Asset",
    "TargetUser": "Administrator",
    "TargetPassword": "1"
  },
  "Tags": [
    {
      "DataType":"BOOL",
      "Name":"state",
      "WriteDirection":0,
      "MQTTTopic":"state/val",
      "MQTTQoS":0,
      "MQTTRetain":false,
      "SymbolPath":"GVL_Production.state",
      "Trigger":1,
      "Cycle":1000,
      "Size":1
    },
    {
      "DataType":"BOOL",
      "Name":"counter",
      "WriteDirection":0,
      "MQTTTopic":"counter/val",
      "MQTTQoS":0,
      "MQTTRetain":false,
      "SymbolPath":"GVL_Production.counter",
      "Trigger":1,
      "Cycle":1000,
      "Size":2
    }
  ]
}

Saving the configuration

Asset management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the \(SYS/Coreflux/Command** topic. The results of these commands are published to **\)SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ Information: Configuration requires the user to be logged in and have an asset installed. If these requirements are not met, please refer to the installation section.

  1. Save configuration:
    -assetConfigSave <asset_guid> <configuration>`
    

    ℹ Information: The asset asset_guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Example:

{"MQTTParameters":{"Port":1883,"Address":"127.0.0.1","IsAnonymous":true,"Username":"","Password":"","EnableTLS":false},"ADSParameters":{"LocalNetId":"1.1.1.1.1.1","LocalRouteToTarget":"I7DESKTOP","LocalHostName":null,"TargetNetId":"5.99.58.57.1.1","TargetIp":"192.168.100.202","TargetPort":851,"TargetRouteToLocal":"Asset","TargetUser":"Administrator","TargetPassword":"1"},"Tags":[{"DataType":"BOOL","Name":"state","WriteDirection":0,"MQTTTopic":"state/val","MQTTQoS":0,"MQTTRetain":false,"SymbolPath":"GVL_Production.state","Trigger":1,"Cycle":1000,"Size":1},{"DataType":"BOOL","Name":"counter","WriteDirection":0,"MQTTTopic":"counter/val","MQTTQoS":0,"MQTTRetain":false,"SymbolPath":"GVL_Production.counter","Trigger":1,"Cycle":1000,"Size":2}]}
  1. Check if the configuration was saved (optional) :
    -assetConfigLoad <asset_guid>
    

Configuration Reference

A comprehensive source for detailed information on asset parameters and their interactions.

Tag data types

This section outlines the various data types used within the system, which are named and structured to mirror the data types found in the corresponding devices. This naming convention ensures a more intuitive and direct mapping of data types from the devices to our system, facilitating easier data handling and integration. Understanding these data types is crucial for effective communication and data manipulation in the system.

Data Type Description Memory Space Lower Bound Upper Bound
BOOL Boolean value (TRUE or FALSE). 8 bits FALSE (0) TRUE (1)
BYTE, WORD, DWORD, LWORD Unsigned integers with varying sizes. 8, 16, 32, 64 bits 0 255, 65535, 4294967295, 2^64-1
SINT, USINT Signed and unsigned small integers. 8 bits -128, 0 127, 255
INT, UINT Signed and unsigned integers. 16 bits -32768, 0 32767, 65535
DINT, UDINT Double integers and unsigned double integers. 32 bits -2147483648, 0 2147483647, 4294967295
LINT, ULINT Long integers and unsigned long integers. 64 bits -2^63, 0 2^63-1, 2^64-1
REAL, LREAL Floating point and long floating point numbers. 32, 64 bits -3.402823e+38, -1.7976931348623158e+308 3.402823e+38, 1.7976931348623158e+308
STRING, WSTRING Strings of characters (ASCII or Unicode). Variable N/A N/A
TIME, LTIME Duration in milliseconds (TIME) or nanoseconds (LTIME). 32, 64 bits 0 4294967295 ms, 2^64-1 ns
DATE, DATE_AND_TIME, TIME_OF_DAY Date and/or time representations (handled internally like a UDINT or ULINT for L-variants). 32, 64 bits D#1970-1-1, DT#1970-1-1-0:0:0 D#2106-02-07, DT#2554-7-21-23:34:33.709551615
BIT Individual bits within structures or function blocks (not for standalone variables). 1 bit FALSE (0) TRUE (1)

ℹ Information: The L-prefix (e.g., LWORD, LREAL, LTIME) indicates a "long" or extended version of the data type, providing a wider range or higher precision.*

Using the asset

⚠ Warning: It is important to understand that the flow of data between the broker and the device highly depends on the configuration of both the asset and the device. In case of unexpected results, please verify the configuration and/or check the logs for any possible errors.

With Coreflux HUB

Please refer the to general docs for asset installation through the Coreflux HUB.

With Coreflux HUBLESS

Asset management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the \(SYS/Coreflux/Command** topic. The results of these commands are published to **\)SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ Information: The asset guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Run asset

  1. Run asset:
-R <asset_guid>

Stop asset

  1. Stop asset:
-S <asset_guid>