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.

Connect to the Coreflux MQTT Broker using your preferred client.
Login using your coreflux account:
```
-L myname@mydomain.com password`
```
Check your available assets:
```
-l
```
Install asset:
```
-I coreflux_ads2mqtt
```
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": []
}

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.

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}]}

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

Run asset:

-R <asset_guid>

Stop asset

Stop asset:

-S <asset_guid>

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