Modbus

The following parameters are used to configure TCP connection for the slave:

• Host - hostname or IP address of the Modbus server.
• Port - port of the Modbus server for connection.
• Method - type of a framer, either Socket or RTU.

The following parameters are used to configure UDP connection for the slave:

• Host - hostname or IP address of the Modbus server.
• Port - port of the Modbus server for connection.
• Method - type of a framer, either Socket or RTU.

The following parameters are used to configure serial connection for the slave:

• Port - port of the Modbus server for connection.
• Method - type of a framer, either ASCII or RTU.
• Baudrate - The baud rate to use for the serial device.
• Bytesize - The number of bits in a byte of serial data. This can be one of 5, 6, 7, or 8.
• Stopbits - The number of bits sent after each character in a message to indicate the end of the byte.
• Parity - The type of checksum to use to verify data integrity. This can be one of the following: (E)ven, (O)dd, (N)one.

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

We are interested in register 1, which contains the relay state value (off/on). To read the value of this register, we need to add this register as attribute/telemetry in the device configuration. To do this, follow these steps:

1. Go to “Entities” → “Gateways” in the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created Modbus connector and click on the “Master Connections” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Getting Started guide or Connection settings and Data mapping sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for.

   

4. Scroll down to the “Attributes or Time series” section and click on the “Pencil” icon to edit the attributes and telemetry.

   

5. Click on the “Add attribute” or “Add telemetry” button. In our case, we will add relay time series, so fill in the “Key” field with relay, select the “Type” as bits, select “Function code” field as “01 - Read Coils”, select “Bit target type” as “Boolean”, and in the “Address” field enter 1. This is the address of the Modbus register we want to read.

   

6. Remember to save your changes by clicking the “Apply” button.

   

Now we can check if the attribute/telemetry works. Go to “Entities” → “Devices” → select a created device → “Last telemetry” tab and check the value of the relay telemetry. It should be false since the default value of the relay is off.

Full configuration for Modbus connector for the example above will look like this:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "method": "socket",
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "connectAttemptTimeMs": 500,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 30000,
        "type": "tcp",
        "attributes": [],
        "timeseries": [
          {
            "tag": "relay",
            "type": "bits",
            "address": 1,
            "objectsCount": 1,
            "functionCode": 1,
            "bitTargetType": "bool"
          }
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

A fairly common practice when using Modbus devices is when the values we get from registers need to be multiplied by a certain number to get the correct value. For example, if we read the power from a register and the value in the register is 2534, and we need to get 253400 watts, then we need to multiply the value by 100. To implement this in the device configuration, we can use the “Multiplier” field in the attributes and telemetry settings. To read the register value with a multiplier, follow these steps:

1. Go to “Entities” → “Gateways” in the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created Modbus connector and click on the “Master Connections” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Getting Started guide or Connection settings and Data mapping sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for.

   

4. Scroll down to the “Attributes or Time series” section and click on the “Pencil” icon to edit the attributes and telemetry.

   

5. Click on the “Add attribute” or “Add telemetry” button. In our case, we will add power time series, so fill in the “Key” field with power, select the “Type” as 16int, select “Function code” field as “03 - Read Holding Registers”, in the “Address” field enter 2, enable “Modifier” toggle, select “Multiplier” as “Type” and enter 10 in “Value” field.

   

6. Remember to save your changes by clicking the “Apply” button.

   

Now we can check if the telemetry with the multiplier works. Go to “Entities” → “Devices” → select a created device → “Last telemetry” tab and check the value of the power telemetry.

Full configuration for Modbus connector for the example above will look like this:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "method": "socket",
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "connectAttemptTimeMs": 500,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 30000,
        "type": "tcp",
        "attributes": [],
        "timeseries": [
          {
            "tag": "power",
            "type": "16int",
            "address": 2,
            "objectsCount": 1,
            "functionCode": 3,
            "multiplier": 10
          }
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

A fairly common practice when using Modbus devices is when the values we get from registers need to be divided by a certain number to get the correct value. For example, if we read the temperature from a register and the value in the register is 2534, and we need to get 25.34 degrees, then we need to divide the value by 100. To implement this in the device configuration, we can use the “Divider” field in the attributes and telemetry settings. To read the register value with a divider, follow these steps:

1. Go to “Entities” → “Gateways” in the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created Modbus connector and click on the “Master Connections” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Getting Started guide or Connection settings and Data mapping sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for.

   

4. Scroll down to the “Attributes or Time series” section and click on the “Pencil” icon to edit the attributes and telemetry.

   

5. Click on the “Add attribute” or “Add telemetry” button. In our case, we will add temperature time series, so fill in the “Key” field with temperature, select the “Type” as 16int, select “Function code” field as “03 - Read Holding Registers”, in the “Address” field enter 0, enable “Modifier” toggle, select “Divider” as “Type” and enter 10 in “Value” field.

   

6. Remember to save your changes by clicking the “Apply” button.

   

Now we can check if the telemetry with the divider works. Go to “Entities” → “Devices” → select a created device → “Last telemetry” tab and check the value of the temperature telemetry.

Full configuration for Modbus connector for the example above will look like this:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "method": "socket",
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "timeout": 35,
        "byteOrder": "BIG",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "connectAttemptTimeMs": 500,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 30000,
        "type": "tcp",
        "attributes": [],
        "timeseries": [
          {
            "tag": "temperature",
            "type": "16int",
            "address": 0,
            "objectsCount": 1,
            "functionCode": 3,
            "divider": 10
          }
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

Can be configured in advanced configuration mode only.

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

For optimizing the number of requests sent to the Modbus server, you can use the Batch reading feature available in the advanced configuration mode. This feature allows reading multiple registers in a single request, which can significantly reduce the load on the Modbus server and improve performance.

Let’s look at an example of how to properly configure batch reading to read the temperature, humidity, power, and pressure registers from the Modbus server.

From the table above, we can see that all the required registers are of the same type (16int) and have the same function code (03 - Read Holding Registers). This means that we can group them into a single batch read request. We need to read registers from address 0 to address 3, so our address range will be 0-3. Also, you need to use, for examples ${address} variable in the tag field to uniquely identify each register within the batch read. In our case, we will use the following expression for the tag field: ${unitId}.${type}.${address} (you can find more information about variables in the corresponding section of the documentation).

Copy and paste the following configuration into the Modbus connector advanced configuration mode:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "type": "tcp",
        "method": "socket",
        "timeout": 35,
        "byteOrder": "BIG",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "sendDataOnlyOnChange": true,
        "connectAttemptTimeMs": 5000,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 300000,
        "attributes": [],
        "timeseries": [
          {
            "tag": "${unitId}.${type}.${address}",
            "type": "16int",
            "functionCode": 3,
            "objectsCount": 1,
            "address": "0-3",
            "divider": 10
          }
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

After saving the changes and starting the connector, you see that the corresponding telemetry is being updated correctly:

Can be configured in advanced configuration mode only.

Modbus devices can have registers that represent enumerated values, for example operational modes, status codes, or error states. To make these values more understandable, you can map them to human-readable strings using the enum mapping feature in ThingsBoard IoT Gateway Modbus connector. This feature works for all register types and can be used in both uplink data (attributes and time series) and uplink RPC to Device calls. Let’s explore how to set up enum mapping in your Modbus connector configuration.

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

We are interested in mapping the Operational Mode and Relay registers to human-readable strings. The Operational Mode register can have the following values:

• 1: Normal Mode
• 2: Service Mode
• 3: Calibration Mode

And the Relay register can have the following values:

• 0: OFF
• 1: ON

To set up enum mapping for these registers, you need to define the variants parameter in the configuration for each register. This parameter is an object where each key represents a possible register value, and the corresponding value is the human-readable string that describes that register value.

Copy and paste the following configuration into the Modbus connector advanced configuration mode:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "method": "socket",
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "timeout": 35,
        "byteOrder": "BIG",
        "wordOrder": "BIG",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "connectAttemptTimeMs": 500,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 1000,
        "type": "tcp",
        "attributes": [],
        "timeseries": [
          {
            "tag": "operational_mode",
            "type": "16int",
            "address": 4,
            "objectsCount": 1,
            "functionCode": 3,
            "variants": {
              "1": "Normal Mode",
              "2": "Service Mode",
              "3": "Calibration Mode"
            }
          },
          {
            "tag": "relay",
            "type": "bits",
            "address": 1,
            "objectsCount": 1,
            "functionCode": 1,
            "bitTargetType": "int",
            "variants": {
              "0": "OFF",
              "1": "ON"
            }
          }
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

After applying this configuration, the operational_mode and relay registers will be mapped to their respective human-readable strings in uplink data. This makes it easier to interpret the data received from the Modbus device:

Attribute updates allow you to update register values in the Modbus server. You can add new attribute updates in the “Attribute updates” section of the device configuration page.

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

We are interested in register “1”, we added this register as a telemetry parameter with the key relay. We used telemetry so that later it would be convenient for us to see if the value we changed using the attribute update has changed. You, also, can add this telemetry datapoint to the device configuration or use the reserved get method to check the value of the node.

Let’s add an attribute update to our configuration. For this purpose, follow these steps:

1. Go to “Entities” → “Gateways” in the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created Modbus connector and click on the “Master Connections” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Getting Started guide or Connection settings and Data mapping sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for.

   

4. Scroll down to the “Attribute updates” section and click on the “Pencil” icon to edit the attribute updates.

   

5. Click on the “Add attribute update” button. In our case, we will add relay attribute update, so the “Key” field, enter relay, select the “Type” as bits, “Function code” as “05 - Write Single Coil”, fill in the “Objects count” field with 1, select “Bit target type” as “Boolean” and in the “Address” field enter “1”.

   

6. Remember to save your changes by clicking the “Apply” button.

   

Now we can check if the attribute update works. Go to “Entities” → “Devices” → select a created device → “Attributes” tab → select “Shared attributes” → click on the ”+” icon and add relay attribute with type “Boolean” set it to “True”.

Now, let’s check the value of the relay register. In the selected device, go to the “Last telemetry” tab and check the value of the relay telemetry. It should be true since we set the shared attribute to true.

Try to change the value of the relay shared attribute to false. After a few seconds, you should see that the relay telemetry value has changed to false, which means that the attribute update worked correctly.

Full configuration for Modbus connector for the examples above will look like this:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "method": "socket",
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "connectAttemptTimeMs": 500,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 30000,
        "type": "tcp",
        "attributes": [],
        "timeseries": [
          {
            "tag": "relay",
            "type": "bits",
            "address": 1,
            "objectsCount": 1,
            "functionCode": 1,
            "bitTargetType": "bool"
          }
        ],
        "attributeUpdates": [
          {
            "tag": "relay",
            "type": "bits",
            "address": 1,
            "objectsCount": 1,
            "functionCode": 5,
            "bitTargetType": "bool"
          }
        ],
        "rpc": []
      }
    ]
  }
}

RPC to Device allows sending RPC commands to the device that is connected to ThingsBoard directly or via Gateway.

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

We are interested to get temperature value from our demo device using RPC to Device. To call this method, first, we need to configure the Modbus connector to support RPC calls. For this purpose, follow these steps:

1. Go to “Entities” → “Gateways” in the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created Modbus connector and click on the “Master Connections” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Getting Started guide or Connection settings and Data mapping sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for.

   

4. Scroll down to the “RPC requests” section and click on the “Pencil” icon to edit the RPC methods.

   

5. Click on the “Add request” button. Fill in the “Method” field with getTemperature, select the “Type” as “16int”, “Function code” as “03 - Read Multiple Holding Registers”, fill in the “Objects count” field with 1, and in the “Address” field enter “0”.

   

6. Remember to save your changes by clicking the “Apply” button.

   

We are done with configuration, so let’s check how to call the method. In the RPC Debug Terminal widget, run the following command:

getTemperature

Response:

Full configuration for Modbus connector for the example above will look like this:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "method": "socket",
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "connectAttemptTimeMs": 500,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 30000,
        "type": "tcp",
        "attributes": [],
        "timeseries": [
          {
            "tag": "some_key",
            "type": "16int",
            "address": 0,
            "objectsCount": 1,
            "functionCode": 3
          }
        ],
        "attributeUpdates": [],
        "rpc": [
          {
            "tag": "getTemperature",
            "type": "16int",
            "address": 0,
            "objectsCount": 1,
            "functionCode": 3
          }
        ]
      }
    ]
  }
}

Every telemetry and attribute parameter has GET and SET RPC methods out of the box, so you don’t need to configure them manually.

As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

The server available at 0.0.0.0:5021. The server has the following structure:

We are interested in register 1, which is a coil register. We will use this register to set the value of the telemetry parameter. The register is of type bits, so we will use bits type for the telemetry parameter. The configuration for this telemetry will look like this:

{
    "tag": "relay",
    "type": "bits",
    "address": 1,
    "objectsCount": 1,
    "functionCode": 1,
    "bitTargetType": "bool"
}

Let’s check the value of the relay register using the reserved get method. To get the current value of relay register, run the query in RPC debug terminal:

get type=bits;functionCode=1;objectsCount=1;address=1;

Response:

{"result":{"value":false}}

So, the get method returns the current value of the relay register, and we can see that the relay is off.

To set the value of the relay register and turn it on, run the query:

set type=bits;functionCode=5;objectsCount=1;address=1;value=1;

Response:

{"result":{"value":"1"}}

And as you can see, from the screenshot below, the relay telemetry value has changed to 1:

Also, let’s check the value of the relay telemetry again: it is true now because, in the Modbus connector, booleans come from integers — 0 = false, 1 = true (any non-zero is true) — so a register value of 1 is reported as true.

get type=bits;functionCode=3;objectsCount=1;address=1;

Response:

{"result":{"value":true}}

Full configuration for Modbus connector for the examples above will look like this:

{
  "master": {
    "slaves": [
      {
        "host": "0.0.0.0",
        "port": 5021,
        "method": "socket",
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 1000,
        "connectAttemptTimeMs": 500,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 30000,
        "type": "tcp",
        "attributes": [],
        "timeseries": [
          {
            "tag": "relay",
            "type": "bits",
            "address": 1,
            "objectsCount": 1,
            "functionCode": 1,
            "bitTargetType": "bool"
          }
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

The following parameters are used to configure TCP connection for Gateway as a Slave:

• Host - hostname or IP address of the Modbus server.
• Port - port of the Modbus server for connection.
• Method - type of a framer, either Socket or RTU.
• Unit ID - ID of the current slave on Modbus.
• Device name - name of the current slave. Don’t use “Gateway” as the value of “Device name” parameter!
• Device profile - device profile of the current slave.
• Poll period (ms) - period in milliseconds for checking the attributes and telemetry.

The following parameters are used to configure UDP connection for Gateway as a Slave:

• Host - hostname or IP address of the Modbus server.
• Port - port of the Modbus server for connection.
• Method - type of a framer, either Socket or RTU.
• Unit ID - ID of the current slave on Modbus.
• Device name - name of the current slave. Don’t use “Gateway” as the value of “Device name” parameter!
• Device profile - device profile of the current slave.
• Poll period (ms) - period in milliseconds for checking the attributes and telemetry.

The following parameters are used to configure serial connection for Gateway as a Slave:

• Port - port of the Modbus server for connection.
• Method - type of application data unit, either ASCII or RTU.
• Baudrate - baud rate to use for the serial device.
• Strict - use inter-character timeout for baud rates less than or equal to 19200.
• Unit ID - ID of the current slave on Modbus.
• Device name - name of the current slave. Don’t use “Gateway” as the value of “Device name” parameter!.
• Device profile - device profile of the current slave.
• Poll period (ms) - period in milliseconds for checking the attributes and telemetry.