Modbus
Introduction
Modbus is a widely adopted industrial communication protocol designed for connecting electronic devices. It is primarily used in process automation and factory environments to enable robust and reliable data exchange between various devices. Based on a master-slave or client-server architecture, Modbus facilitates communication between devices such as programmable logic controllers (PLCs), sensors, actuators, and monitoring systems. Its simplicity and ease of implementation have made it a standard protocol in the industry, allowing seamless integration and interoperability across different devices and systems.
Modbus asset enables communication with Modbus devices, taking the role as Master device. 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 Modbus devices, facilitating a bidirectional data flow.
Features and Benefits
-
Dual Protocol Support: The connector seamlessly bridges devices operating on both Modbus TCP and RTU protocols with MQTT networks.
-
Tag-Based Messaging: Uses tags for MQTT topics, simplifying configuration and making data streams easier to understand and manage.
-
Seamless Coreflux Integration: Fits smoothly within the Coreflux ecosystem, reducing complexity and speeding up IoT solution deployment.
-
Operational Efficiency: Direct data flow from Modbus devices to MQTT brokers minimizes latency and potential points of failure, creating a cost-effective operational environment.
-
Enhanced Data Exchange: Utilizes MQTT's efficient messaging protocol for real-time data exchange, improving decision-making and system performance.
Use Cases:
-
Real-Time Monitoring and Control: OEnables direct monitoring and control of Modbus-connected machinery via MQTT-enabled dashboards, increasing productivity and reducing downtime.
-
Data Aggregation: Funnels data from various Modbus devices into a unified MQTT stream, making it easier to analyze and uncover operational insights.
-
IoT Integration: Simplifies the integration of industrial systems with IoT ecosystems for cloud analytics, remote monitoring, and predictive maintenance.
Prerequisites
Before you install and configure the asset, make sure you have the following prerequisites:
- Basic understanding of the MQTT protocol.
- Basic undertstanding of Modbus protocol.
- Coreflux account.
- Coreflux 1.3 MQTT broker.
- MQTT Client (such as MQTT Explorer).
- An Modbus device (PLC for example).
Asset installation
Using Coreflux HUB
Please refere to general docs for asset installation trough 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 and selecting the class, instance, and attribute to be manipulated, among other settings. The configuration is detailed in a JSON file, divided into three main sections: MQTT Parameters, Modbus Parameters and Tags Prameters.
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_source: 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). | No | 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) |
WithTLS | Specifies whether TLS encryption is enabled for secure communication. | No | true |
false |
Example:
{
"MQTTParameters": {
"Port": 1883,
"Address": "127.0.0.1",
"IsAnonymous": true,
"Username": "",
"Password": "",
"WithTLS": false
}
}
Modbus Parameters
The Modbus in the JSON configuration specify the setup for Modbus communication between a local system and a target device. These parameters are essential for facilitating data exchange using the Modbus protocol.
There are two different ways to connect to Modbus devices: TCP/IP and RTU.
TCP/IP Connection:
Uses Ethernet networks to connect devices, allowing for easy and flexible setup over longer distances. This method leverages standard network infrastructure, making it suitable for modern industrial environments.
Parameter | Description | Required | Example | Default Value |
---|---|---|---|---|
Interface | Defines the connection interface. The options are: 0- “SerialRTU” and 1- “TCPIP” | Yes | TCPIP |
"TCPIP" |
Port | Modbus server Port. | Yes | 502 |
502 |
IP | Modbus server IP Address. | yes | 192.168.100.200 |
127.0.0.1 |
PollingMs | Polling of registries in milliseconds | Yes | 500 |
500 |
EndianType | Order of registers Options are: 0 - LittleEndian and 1 - BigEndian | Yes | LittleEndian |
LittleEndian |
SlaveId | Unique number assigned to each Modbus device on the network | Yes | 5 |
1 |
Example:
{
"MQTTParameters": {
"Port": 1883,
"Address": "127.0.0.1",
"IsAnonymous": true,
"Username": "",
"Password": "",
"WithTLS": false
},
"ModbusParameters": {
"Interface": "TCPIP",
"Port": 502,
"IP": "192.168.100.200",
"PollingMs": 500,
"EndianType": "LittleEndian",
"SlaveId": 1
}
}
RTU Connection:
Utilizes serial communication for connecting devices, typically over RS-485 or RS-232 interfaces. This method is ideal for simple, short-distance connections and is often used in legacy systems.
Parameter | Description | Required | Example | Default Value |
---|---|---|---|---|
Interface | Defines the connection interface. The options are: 0- “SerialRTU” and 1- “TCPIP” | Yes | SerialRTU |
"TCPIP" |
SerialPort | Used in “SerialRTU” interface. | Yes | Example on Windows OS: 'COM3'. Example on Linux OS: '/dev/ttyUSB0' |
"COM3" |
PollingMs | Polling of registries in milliseconds | Yes | 500 |
500 |
Parity | Parity bit to check for errors during data transmission. | Yes | Options are: 0 - None, 1 - Odd, 2 - Even, 3 - Mark and 4 - Space. |
0 |
Retries | Number of retries | Yes | 2 |
3 |
BaudRate | Data exchange speed between devices | Yes | 5000 |
9600 |
StopBits | Number of bits to indicate the end of a data frame | Yes | Options are: 0 - None, 1 - One, 2 - Two and 3 - OnePointFive |
0 |
EndianType | Order of registers. Options are: 0 - LittleEndian and 1 - BigEndian | Yes | LittleEndian |
LittleEndian |
SlaveId | Unique number assigned to each Modbus device on the network | Yes | 5 |
1 |
Example:
{
"MQTTParameters": {
"Port": 1883,
"Address": "127.0.0.1",
"IsAnonymous": true,
"Username": "",
"Password": "",
"WithTLS": false
},
"ModbusParameters": {
"Interface": "SerialRTU",
"SerialPort": "COM3",
"PollingMs": 500,
"Retries": 2,
"BaudRate": 9600,
"StopBits": "None",
"EndianType": "LittleEndian",
"SlaveId": 1
}
}
Tags
Tags serve as the bridge between the Modbus devices variables and the MQTT topics within your system. Each Tag represents a specific connection point, linking a register element 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_source: 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 | Unique Tag identifier | Yes | outputExample |
"Random Name" |
Route | Origin and destination of data | Yes | The options are: 0 - ToSubscribers, 1 - ToOther |
0 |
Publish | Chose how data is sent. | Yes | Acceptable values are: 'Update' (0), 'Cyclic' (1), 'Once' (2) |
1 |
PublishCycle | If 'publish' = 'Cyclic', a value must be set | No | PublishCycle must be between 1 and 86400 seconds (24 hours) |
1 |
MqttTopic | Unique topic connecting with the specified Register | Yes | machine/motorStart |
"Random Topic" |
MqttRetain | Defines if the message should be retained | Yes | true or false |
false |
MqttQos | Quality of service for the MQTT topic | Yes | Options are: 0 - AtMostOnce, 1 - AtLeastOnce and 2 - ExactlyOnce. |
0 |
ModbusMemoryArea | Defines the register, coil, or input to access. See the ModbusMemoryArea Table . | Yes | 0 (Coils) |
2 |
ModbusMemoryAddress | Defines the Modbus memory address to read/write. The address is defined by the OEM and can range from 0 to 655535. | Yes | 5 |
0 |
ModbusDataType | Defines data type to read/write. See the Tag Data Types | Yes | 0 (Boolean) |
0 |
RegisterByte | Defines the register byte to read/write when using ASCII | Conditional | 0 |
0 |
ModbusRegisterBit | Define the Modbus memory address bit to read/write. From bit 0 to bit 16, when using BOOL | Conditional | 2 |
0 |
SwapByte | Changes the order of bytes within a Register (e.g., from AB to BA) | No | true |
false |
SwapWord | Changes the order of words in a double Register (e.g., from ABCD to CDAB) | No | true |
false |
Example JSON for TCP configuration:
{
"MQTTParameters": {
"Port": 1883,
"Address": "127.0.0.1",
"IsAnonymous": true,
"Username": "",
"Password": "",
"WithTLS": false
},
"ModbusParameters": {
"Interface": "TCPIP",
"Port": 502,
"IP": "192.168.100.200",
"PollingMs": 500,
"EndianType": "LittleEndian",
"SlaveId": 1
},
"Tags": [
{
"Name": "writeExample",
"Route": 0,
"MqttTopic": "machine/motorStart",
"MqttQos": 0,
"MqttRetain": false,
"ModbusMemoryArea": 3,
"ModbusMemoryAddress": 5,
"ModbusDataType": 4,
"SwapByte": true,
"SwapWord": true
},
{
"Name": "readExample",
"Route": 1,
"MqttTopic": "machine/motorStart/read",
"MqttQos": 0,
"MqttRetain": false,
"ModbusMemoryArea": 3,
"ModbusMemoryAddress": 5,
"ModbusDataType": 4,
"SwapByte": true,
"SwapWord": true
}
]
}
ModbusMemoryArea Table
The ModbusMemoryArea Table outlines the different memory areas used in Modbus communication, each identified by a specific value. These areas categorize the types of data that can be accessed or controlled within Modbus devices.
ModbusMemoryArea Value | Description |
---|---|
0 | Coils (also known as outputs, are writable and readable) |
1 | Discrete Inputs (read-only boolean values) |
2 | Input Registers (read-only numerical values) |
3 | Holding Registers (writable and readable renumerical values) |
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 - Integer Value | Description | Memory Space | Lower Bound | Upper Bound |
---|---|---|---|---|
Boolean - 0 | Set a specific Bit to: 0 (false) or 1 (true). | 1 bits | FALSE (0) | TRUE (1) |
Byte - 1 | The value to be read from or written to the AttributeIndex must be a valid byte. | 8 | 0 | 255 |
INT16 - 2 | Signed 16-bit integer. | 16 bits | -32768 | 32767 |
UINT16 - 3 | Unsigned 16-bit integer. | 16 bits | 0 | 65535 |
INT32 - 4 | Signed 32-bit integer. | 32 bits | -2147483648 | 2147483647 |
UINT32 - 5 | Unsigned 32-bit integer. | 32 bits | 0 | 4294967295 |
INT64 - 6 | Signed 64-bit integer. | 64 bits | -2^63 | 2^63-1 |
UINT64 - 7 | Unsigned 64-bit integer. | 64 bits | 0 | 2^64-1 |
Float32 - 8 | 32-bit floating point number. | 32 | -3.402823e+38 | 3.402823e+38 |
Float64 - 9 | 64-bit floating point number (double). | 64 bits | -1.7976931348623158e+308 | 1.7976931348623158e+308 |
ASCII - 10 | Will convert the AttributeIndex value to an ASCII character. | 1 bit | 0 | 255 |
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.
ℹ : 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:
ℹ : The asset asset_guid can be obtained by consulting the $SYS/Coreflux/Assets topic.
Example:
-assetConfigSave assetName {
"MQTTParameters": {
"Port": 1883,
"Address": "127.0.0.1",
"IsAnonymous": true,
"Username": "",
"Password": "",
"WithTLS": false
},
"ModbusParameters": {
"Interface": "TCPIP",
"Port": 502,
"IP": "192.168.100.200",
"PollingMs": 500,
"EndianType": "LittleEndian",
"SlaveId": 1
},
"Tags": [
{
"Name": "writeExample",
"Route": 0,
"MqttTopic": "machine/motorStart",
"MqttQos": 0,
"MqttRetain": false,
"ModbusMemoryArea": 3,
"ModbusMemoryAddress": 5,
"ModbusDataType": 4,
"SwapByte": true,
"SwapWord": true
}
]
}
- Check if the configuration was saved (optional) :
ℹ : Find more detailed information about the asset management here.
Configuration Reference
A comprehensive source for detailed information on asset parameters and their interactions.
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 to the 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.
ℹ : The asset guid can be obtained by consulting the $SYS/Coreflux/Assets topic.
Run asset
- Run asset:
Stop asset
- Stop asset:
⚠ Warning: To update the asset configuration, ensure you stop it first to avoid issues. After making the changes, restart the asset to apply the new configuration.
Logs
Logs are essential for monitoring and debugging your system. They provide insight into the operation of your assets and can help identify and resolve issues promptly.
With Coreflux HUB
On Coreflux HUB, the logs are displayed in the "Log" section of the asset configuration.
With MQTT Explorer
To display logs in MQTT Explorer, follow these steps:
- Publish the following command to the $SYS/Coreflux/Command topic:
Example1:
To display informational
logs, use:
Note : This will display the Logs "Information" of
all the assets
Example2:
To display error logs, from a specific asset, use:
Note : This will display the Logs "Error" of a
specific asset
Note: To display all three types of logs (Error, Information, and Warning), you will need to repeat this process three times, one for each log level. three times, one for each log level.