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:
- Check your available assets:
- Install asset:
- If there were no issues during the installation you should receive a message on the $SYS/Coreflux/Command/Output:
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.
- Save 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) :
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:
Stop asset
- Stop asset: