Skip to content

Modbus RTU Example

The Modbus RTU Device Service example demonstrates onboarding the Modbus simulator.

Preconfiguration

Run the Modbus Simulator

  • First, execute the following command to run the modbus simulator
docker run --rm -d -e RUN_MODE=RTU -p 50103:50103 --name modbus-sim iotechsys/modbus-sim:1.0

podman run --rm -d -e RUN_MODE=RTU -p 50103:50103 --name modbus-sim iotechsys/modbus-sim:1.0
  • Second, create a virtual serial port by running the socat command to connect to the Modbus simulator

Note

Socat is a flexible, multi-purpose relay tool. Its purpose is to establish a relationship between two data sources, where each data source can be a file, a Unix socket, UDP, TCP, or standard input. Install socat by entering the following commands in the terminal: sudo apt udpate and sudo apt install socat.

sudo socat pty,link=/dev/virtualport,raw,echo=0,mode=666 tcp:172.17.0.1:50103

sudo socat pty,link=/dev/virtualport,raw,echo=0,mode=666 tcp:localhost:50103
  • Lastly, create a local docker-compose file to override the EdgeXpert’s default setting
version: '3.7'

services:
  device-modbus:
    volumes:
      - /dev/virtualport:/dev/virtualport

version: '3.7'

services:
  device-modbus:
    user: root:root
    security_opt:
      - label:disable
    volumes:
      - /dev/virtualport:/dev/virtualport

Start the Modbus Device Service

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

Note

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

edgexpert up device-modbus

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.

  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/power-submeter/DENT.Mod.PS6037.profile.yaml

  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 Power-Submeter-Device The unique name used to identify the device Required
Description Power Submeter device Any additional information about the device Optional
Label power submeter, modbus rtu Any additional information about the device Optional
Address /dev/virtualport The serial connection to use Required
Baud Rate 19200 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 Network-Power-Meter The name of the device profile uploaded above Required
Device Service device-modbus The name of the appropriate device service Required

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.

  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/power-submeter/DENT.Mod.PS6037.profile.yaml"

  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": "Power-Submeter-Device",
            "description":"Power Submeter device",
            "labels":[
              "power submeter",
              "modbus rtu"
            ],
            "adminState": "UNLOCKED",
            "operatingState": "UP",
            "protocols": {
                "modbus-rtu": {
                "Address": "/dev/virtualport",
                "BaudRate": "19200",
                "DataBits": "8",
                "Parity": "N",
                "StopBits": "1",
                "UnitID": "1"
              }
            },
            "serviceName": "device-modbus",
            "protocolName":"modbus-rtu",
            "profileName": "Network-Power-Meter"
          }
        }
      ]'

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/Power-Submeter-Device/Configuration

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.