Modbus RTU

The Modbus RTU Device Service example demonstrates onboarding a ICP DAS M-7055 device.

Connecting a Modbus RTU Device

Connect the device

Connect the device to your machine (for example, a laptop or gateway) via RS485/USB adaptor and power on.

Execute the following command to confirm the connection to your RS485/USB adaptor:

$ dmesg | grep tty
...
...
[18006.167625] usb 1-1: FTDI USB Serial Device converter now attached to ttyUSB0

Once you have confirmed that the USB has attached to ttyUSB0, check whether the device path exists:
```
$ ls -l /dev/ttyUSB0
crw-rw---- 1 root dialout 188, 0 Mar  4 13:41 /dev/ttyUSB0
```

Authorize Serial Path for container

DockerPodman

Create a local docker-compose file to override the default Edge Xpert image and its settings, then we can mount the device path to the device-modbus with specified linux group dialout. There are two ways to mount the device path:

Using devices
```
version: '3.7'
services:
device-modbus:
devices:
  - /dev/ttyUSB0
```
You can download the docker-compose sample file from here.

Using volumes and device_cgroup_rules to override the existing settings

version: '3.7'
services:
device-modbus:
group_add:
  - dialout
volumes:
  - /dev:/dev
device_cgroup_rules:
  - 'c 188:* rw'

The rule provides the device-modbus with information of the device. See the following breakdown:

c: the character device
188: major number of the device (188=USB)
*: minor number of the device
rw: read and write permissions

Override the setting of device-modbus

version: '3.7'

services:
  device-modbus:
    user: root:root
    # The option --security-opt label=disable disables SELinux separation for the container.
    security_opt:
      - label:disable
    devices:
      - /dev/ttyUSB0

Grand the permission of /dev/ttyUSB0
```
sudo chmod 666 /dev/ttyUSB0
```

Start the Modbus Device Service

To start the Modbus Device Service, enter the following command:

edgexpert up device-modbus

Note

The initial output from edgexpert up should state "Overriding configuration with local docker-compose.yml" for docker-compose override mechanism.

Device Onboarding

Once the Modbus Device Service has been started, Modbus devices can be connected to Edge Xpert using either the Edge Xpert Manager UI or through Edge Xpert REST API commands. Instructions on how to use both methods are described below.

Device Onboarding with the Edge Xpert Manager UI

Note

Please refer to the Edge Xpert Manager UI Device Management capability for full details.

Ensure the Edge Xpert Manager UI is started, for example:
```
edgexpert up xpert-manager
```
Open a browser and go to localhost:9090. The default username and password is admin.
Using the device profile upload capability, upload the provided Modbus example device profile at /usr/share/edgexpert/examples/device-services/modbus/digital-io-device/ICPDAS-M7055.yml
Onboard the Modbus device using the device onboarding capability. The following values can be used to provision the device described above:

Field	Example Value	Description	Required
Name	ICPDAS-M7055	The unique name used to identify the device	Required
Description	Modbus RTU device	Any additional information about the device	Optional
Label	Modbus RTU	Any additional information about the device	Optional
Address	/dev/ttyUSB0	The serial connection to use	Required
Baud Rate	9600	The baud rate for the device, the rate at which information is transferred	Required
Data bits	8	Bits per byte, the Modbus RTU requires the use of all 8 bits in each character / byte that forms the message	Required
Parity	None	Sets the parity for the device, which is used for error checking. Options are 'E' for Even, 'O' for Odd, or 'N' for None	Required
Stop bits	1	Indicates how many bits are present in a frame. Options are 1 or 2	Required
Unit Identifier	1	The Modbus station or slave identifier	Required
Device Profile	ICPDAS-M7055	The name of the device profile uploaded above	Required
Device Service	device-modbus	The name of the appropriate device service	Required
Auto Events	Interval: 5s OnChange: false ResourceName: DO	Automated events to retrieve the data at specific frequencies Note: If OnChange is set to true, values will only be pushed if a change in value has occurred during the specified interval. If set to false, values will be sent on the specified interval regardless of if there has been a change	Optional

Device Onboarding with the Edge Xpert REST API

Info

If Edge Xpert is running in secure mode, you will need to replace localhost in the URL with the IP address for the service. See CLI Service Ports for details.

Upload the provided Modbus example device profile:

curl http://localhost:59881/api/v2/deviceprofile/uploadfile -F "file=@/usr/share/edgexpert/examples/device-services/modbus/digital-io-device/ICPDAS-M7055.yml"

Onboard the device using similar values as explained above:

curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \
  -d '[
        {
          "apiVersion": "v2",
          "device": {
            "name": "ICPDAS-M7055",
            "description":"Modbus RTU Device",
            "labels":[
              "Modbus RTU"
            ],
            "adminState": "UNLOCKED",
            "operatingState": "UP",
            "protocols": {
              "modbus-rtu": {
                "Address": "/dev/ttyUSB0",
                "BaudRate": "9600",
                "DataBits": "8",
                "Parity": "N",
                "StopBits":"1",
                "UnitID": "1"
              }
            },
            "serviceName": "device-modbus",
            "protocolName":"modbus-rtu",
            "profileName": "ICPDAS-M7055",
            "autoEvents": [
              {
                "interval": "5s",
                "onChange": false,
                "sourceName": "DO"
              }
            ]
          }
        }
      ]'

Device Data Flow

Once the device is onboarded to Edge Xpert, data flow between the Device Service and the connected device can be verified in a number of ways.

The Edge Xpert Manager UI supports Read and Write functionality for each device. Readings can also be viewed and queried within the Edge Xpert Manager UI Data Center.

Alternatively, you can read and write data with cURL commands or through REST API applications, such as Postman.

Info

If Edge Xpert is running in secure mode, you will need to replace localhost in the URL with the IP address for the service. See [CLI Service Ports][16] for details.

Both the GET and PUT requests can be made to the following address:

curl http://localhost:59882/api/v2/device/name/{deviceName}/{commandName}

Using the example above, this could be:

curl http://localhost:59882/api/v2/device/name/ICPDAS-M7055/DO

See the Core Command Microservice for more information on this. A list of available API commands can be found under EdgeXpert API.

Any data collected by the Device Service can then be treated like all other Edge Xpert sensor data. The data readings can be exported for data processing in a number of other applications and services. See the Supporting Services and Application Services documentation for more details.