:Modbus drivers

Overview

Modbus is a widely used communications protocol at the application layer. Alibaba Cloud provides Modbus drivers for you to connect devices. Modbus drivers allow you to connect devices that use Modbus RTU and Modbus TCP protocols.

You can directly connect Modbus drivers to Modbus devices. The following figure shows the direct connection.

You can also use gateways to connect Modbus drivers to Modbus devices. The following figure shows the gateway-based connection.

Modbus drivers provide the following features: read input status, read input registers, read and write coil status, and read and write holding registers.

Link IoT Edge offers Modbus drivers for C and Python. It also offers various Modbus drivers for C based on the gateway CPU architecture. You can use the Link IoT Edge console to deploy Modbus drivers to gateways. You can also download Modbus driver code from the console and modify the code based on your business requirements.

This topic provides an example on how to use Modbus drivers.

Prerequisites

An edge instance is created and a gateway is connected to Link IoT Edge. For more information, see Set up environments.

Step 1: Assign a driver

1. Log on to the Link IoT Edge console.
2. In the left-side navigation pane, click Edge Instances. On the Edge Instances page, find the edge instance that you want to use and click View in the Actions column.
3. On the Instance Details page, click the Devices & Drivers tab and click the + icon next to All Drivers.
4. In the Assign Driver panel, select Official Drivers from the drop-down list. Find the Modbus driver that you want to use based on the gateway CPU architecture and click Assign in the Actions column. Then, click Close.
   Note

   • Modbus drivers for C can be used only in Link IoT Edge V1.8.4 and later.
   • Modbus drivers for Python can be used only in Link IoT Edge Pro Edition.

   

Step 2: Configure the driver

1. On the Devices & Drivers tab, click the assigned Modbus driver and click Driver Configurations next to Devices.
2. In the Driver Configurations panel, click Add Channel.
   Channels connect gateways to physical devices.
3. Set the parameters as required and click OK.

   Parameter	Description
   Channel Name	The name of the channel. The channel name must be unique for the gateway that the channel connects. The name must be 1 to 30 characters in length and can contain letters, digits, and underscores (_).
   Transmission Mode	The transmission mode. Valid values: RTU and TCP.
   If you select RTU, you must set the following parameters:
   Serial Port	The serial port. Examples: /dev/ttyUSB0 and /dev/ttyUSB1. The value must be 1 to 64 characters in length and can contain letters, digits, forward slashes (/), and underscores (_).
   Baud Rate	The number of symbols that are transferred every second. Select an option from the drop-down list.
   Data Bit	The number of bits that are contained in a group of data. Select an option from the drop-down list.
   Parity Bit	The parity check settings. Valid values: No Parity Check, Odd Parity Check, and Even Parity Check.
   Stop Bit	The last bit of a package. Select an option from the drop-down list.
   If you select TCP, you must set the following parameters:
   IP Address	The IP address of the Modbus device. Enter an address in the dotted decimal notation format.
   Port Number	The port number of the Modbus device. Enter an integer that ranges from 1 to 65535.

4. Optional. On the right side of Devices, click Container Configurations. On the Container Configurations page, configure the container for the driver based on the parameters that are described in the following table. Click Save.
   Note You can configure the container only when the Instance Type parameter of the edge instance is set to Pro Edition.

   Parameter	Description
   Host Mode	Specifies whether to isolate the container network from the host network. Valid values: Yes: The container network is the same as the host network. No: The container network is isolated from the host network. If you select this option, you must set the Network Port Mapping parameter.
   Network Port Mapping	The mappings between host network ports and container network ports. This parameter is available only when you set the Host Mode parameter to No. The network where the function runs is isolated from the host network. You can map the listening port of the function in the container to a host network port. This allows client programs on various hosts to access the services that are provided by the function. You can specify a maximum of 10 entries. For example, the fc-http-server function runs in a host container, and provides services by using Port 80. The client programs on other hosts cannot access the fc-http-server function by accessing Port 80 on the current host. To enable the client programs on other hosts to access the fc-http-server function, you must map Port 80 in the container where the function runs to a host network port, such as Port 8080. Then, the client programs on other hosts can access IP address:port 8080 on the host network, and use the services provided by the fc-http-server function.
   Privilege Mode	Specifies whether to enable the privilege mode. Root users of containers can access host services only as regular users. If you need to change the system time or run the mount command in containers, you must be granted the required root permissions. In this scenario, you must enable the privilege mode for the containers. Note If you enable the privilege mode, applications and programs in the containers are granted the host root permissions, and all the host devices are mapped to the containers. Therefore, you do not need to set the Device Mapping parameter.
   Device Mapping	The device mappings. This parameter is available only when you set the Privilege Mode parameter to No. The network where the device management system resides is isolated from the host network. To enable a function to access a host device such as a serial port, you must map the device to the container where the function runs. You can specify a maximum of 10 entries.
   Volume Mapping	The volume mappings. The network where the file system resides is isolated from the host network. To enable a function to access a host file, you must map the file to the container where the function runs. You can specify a maximum of 10 entries.

Step 3: Assign a sub-device

1. In the Devices section, click Assign Sub-device. In the Assign Sub-device panel, assign a sub-device to the edge instance.
   You can select an existing Modbus device or create a sub-device. To create a sub-device, proceed with the following steps.

   Note If you want to select an existing Modbus device, the product to which the device belongs must be connected to a gateway by using the Modbus protocol. For more information, see Create a product.
2. In the Assign Sub-device panel, click Add Sub-device.
   
3. In the Add Device dialog box, click Create Product and create a product to which the new Modbus device belongs.
   
4. In the Create Product dialog box, set the parameters as required and click OK.

   Table 1. Parameter description

   Parameter	Description
   Product Name	The name of the product. The product name must be unique within the current Alibaba Cloud account. The name must be 4 to 30 characters in length and can contain letters, digits, underscores (_), hyphens (-), at signs (@), and parentheses ().
   Gateway Connection Protocol	The communications protocol. You must set this parameter to Modbus.
   Authentication Mode	The authentication method. Select an authentication method that is suitable for your devices. For more information, see Authenticate devices.
   Product Description	The description of the product. This parameter is optional.

5. In the Add Device dialog box, the Product parameter is automatically set to the name of the product that you created. Click Configure and define the product features.
   Note You can configure Modbus products by using the Modbus debugging tool. For more information, see Modbus debugging tool. Before you use the debugging tool, you must first create a device and assign the device to the edge instance.

   

   After you click Configure, you are navigated to the Define Feature tab of the Product Details page in the IoT Platform console. Click Edit Draft. On the Edit Draft page, click Add Self-defined Feature.

   
6. In the Add Self-defined Feature dialog box, set the parameters as required to define a property. For more information, see Add a TSL feature.
   In this step, click Add Extended Information. In the Add Extended Information dialog box, set the parameters as required to add extended information, as shown in the following figure. After the configuration is complete, the property information is transferred to the specified register. The Modbus driver requests data from devices based on the specified properties and converts the received Modbus data into Thing Specification Language (TSL) data.

   The following table describes the parameters about extended information. For more information, see the description of the Extended Information parameter in the Add a TSL feature topic.

   Parameter	Description
   Operation Type	The operation type that is indicated by the function code. Note Description of operation types Coil Status: You can use only the 0x01 function code to perform a read operation. If you want to perform a write operation on a single coil at a time, you can use the 0x05 function code. If you want to perform a write operation on multiple coils at a time, you can use the 0x0F function code. Holding Registers: You can use only the 0x03 function code to perform a read operation. If you want to perform a write operation on a single register at a time, you can use the 0x06 function code. If you want to perform a write operation on multiple registers at a time, you can use the 0x10 function code. If you use the 0x06 function code to perform a write operation, the Original Data Type parameter can be set only to int16 or uint16. If you select other data types, an error occurs when property data is reported. If you use the 0x10 function code to perform a write operation, all values of the Original Data Type parameter are available. Discrete Input: You can use only the 0x02 function code to perform a read operation. Write operations are not supported. Input Registers: You can use only the 0x04 function code to perform a read operation. Write operations are not supported. For information about the specifications of the Modbus protocol, see GB/T 19582.1-2008, GB/T 19582.2-2008, and GB/T 19582.3-2008.
   Register Address	The IP address of the register. You must enter a hexadecimal IP address that starts with 0x. You must specify the IP address of the register based on your device property. For example, if the device temperature is indicated by 1 in the IP address, you can set this parameter to 0x1.
   Original Data Type	The data type of the raw data. For example, the data type of the temperature is floating point.
   Value Range	The range of values that are obtained after the raw data is processed based on the zoom factor. The data that falls outside the range of values is discarded.
   Switch High Byte and Low Byte in Register	Specifies whether to swap the first 8 bits and the last 8 bits of the 16-bit data in the register. In this example, set this parameter to true.
   Switch Register Bits Sequence	Specifies whether to swap the bits of the original 32-bit data. In this example, set this parameter to false.
   Zoom Factor	The zoom factor. For example, if the collected value is 100 and the actual value is 10, set this parameter to 0.1. If the collected value is 100 and the actual value is 1000, set this parameter to 10.
   Data Report	The trigger of reporting data. Valid values: At Specific Time: After you select At Specific Time, data is collected and reported at the collection interval that is specified by the Data Collection Interval (ms) parameter for the sub-device in Step 9. Report Changes: The report is triggered if the collected data changes.

7. Go back to the Instance Details page and create the Modbus device.
   
8. Assign the created Modbus device to the edge instance.
9. On the Devices & Drivers tab, find the assigned Modbus device and click Device Configurations in the Actions column. In the Device Configurations dialog box, set the parameters as required to connect the Modbus device to the Modbus driver.
   

   Table 2. Parameter description

   Parameter	Description
   Associated Channel	The channel that connects the device to the Modbus driver. In this example, select the channel that is created in Step 2 of Configure the driver.
   Device Station Number	The station number of the Modbus device, which is unique for each channel.
   Data Collection Interval (ms)	The interval at which data is collected. Modbus is a communications protocol with half-duplex transmission. Gateways send requests to collect data from devices. Therefore, you must specify the data collection interval. Unit: milliseconds. Note If 60 milliseconds is required to collect the data of each property, the total time that is required to collect the data of all properties is calculated based on the following formula: Total required time = Time required to collect the data of each property (60 ms) × Number of properties for the channel If the channel connects 10 Modbus devices and each device has 10 properties, the total required time is 6,000 ms: 60 ms × 10 × 10 = 6,000 ms. To make sure that data is reported as expected, you must set the data collection interval greater than or equal to 6,000 ms.

Step 4: Deploy the edge instance

1. Optional. Before you deploy the edge instance, you can use the debugging tool to check whether the gateway connects to the Modbus device as expected. You can also check whether the TSL model of the product to which the Modbus device belongs is correctly configured. For more information, see Modbus debugging tool.
2. On the Instance Details page, click Deploy in the upper-right corner to deploy the edge instance.

FAQ

Do Modbus drivers send data to the cloud based on the device dimension or the properties dimension?

Modbus drivers collect and send data to the cloud based on the device dimension in each data collection cycle. For example, if a Modbus device has 100 properties and the data collection interval is 5 seconds, the Modbus driver sends one message about the device to the cloud every 5 seconds.