Skip to content

Modbus RTU Example

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

Connecting a Modbus RTU Device

Connect the device

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

    Note

    If your machine is a Windows system running with the Windows Subsystem for Linux (WSL 2), you will have to do extra setup as described in the Microsoft documentation to make the USB device accessible to your WSL 2 environment.

  2. 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

  3. 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

Change the Owner of the Device

For security reasons, user permissions should be changed. These are defined in /etc/edgexpert/docker-compose.yml. The default permissions used by Edge Xpert are as below:

device-modbus:
  ...
  user: 2002:2001  # UID:GID

The owner should be modified for the specified group. Use the following command:

sudo chown :2001 /dev/ttyUSB0

Or change the permissions for multiple files 

sudo chown :2001 /dev/tty*

Note

The owner will be reset after a system reboot. To expedite this process, we can add this command to a startup script. Using Raspberry Pi as an example, add the script to /etc/rc.local. This will be run by the Raspberry Pi at startup.

Note

Some systems, such as Windows WSL 2 running with Ubuntu-20.04, the default ownership of /dev/ttyUSB0 may not allow group users to access: 

$ ls -l /dev/ttyUSB0
crw------- 1 root dialout 188, 0 Mar  4 13:41 /dev/ttyUSB0
For such cases, you will have to change both the owner and the group of /dev/ttyUSB0: 
sudo chown 2002:2001 /dev/ttyUSB0

Mount the Device Path to the Docker Container

Modify the docker-compose.yml file to mount the device path to the device-modbus. There are two ways to mount the device path:

  1. Using devices:

    device-modbus:
  ...
  devices:
    - /dev/ttyUSB0

  2. Or using volumes and device_cgroup_rules:

    device-modbus:
  ...
  volumes:
    ...
    - /dev:/dev
  device_cgroup_rules:
    - 'c 188:* rw'

    The rule provides the device-modbus with information on 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

Start the Modbus Device Service

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

edgexpert up device-modbus

Device Onboarding

Once the Modbus Device Service has been started, Modbus devices can be onboarded 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.

  1. Ensure the Edge Xpert Manager UI is started, for example: 

    edgexpert up xpert-manager

  2. Open a browser and go to localhost:9090. The default username and password is admin.

  3. 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

  4. 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

  1. 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"

  2. 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.

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

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

Using the example above, this could be: 

http://localhost:59901/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.

Note

59901 is the default port for the Modbus device service

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.

Back to top