This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments

Azure IoT Edge Modbus Module Preview

Using this module, developers can build Azure IoT Edge solutions with Modbus TCP connectivity. The Modbus module is an Azure IoT Edge module, capable of reading data from Modbus devices and publishing data to the Azure IoT Hub via the Edge framework. Developers can modify the module tailoring to any scenario.

If you are using V1 version of IoT Edge (previously known as Azure IoT Gateway), please use V1 version of this module, all materials can be found in V1 folder.

Visit http://azure.com/iotdev to learn more about developing applications for Azure IoT.

Azure IoT Edge Compatibility

Current version of the module is targeted for the Azure IoT Edge 1.0 preview version.

Operating System Compatibility

Refer to Azure IoT Edge

Hardware Compatibility

Refer to Azure IoT Edge

HowTo Run

This section will help you download the prebuilt module image from docker hub, and run it with IoT Edge directly.

1. Setup Azure IoT Edge with compatible version on your machine.
2. Follow this to deploy a custom IoT Edge module.
3. In the Image field, enter microsoft/azureiotedge-modbus-tcp:1.0-preview.
4. You may also want to provide configuration to the module when it starts, paste the configuration in the desired property field. For more about configuration, see here.

HowTo Build

If you prefer to build your own module, use the following script. Dockerfiles are located under Docker folder, you should be able to find one for your platform. There are two Dockerfiles in each platform, the multi-stage Dockerfile-auto will automatically build source code and Docker image. The other Dockerfile requires you to build source code first and then copy binary to the image.
Note: Arm32 multi-stage build doesn't work at this moment, please build it manually.
Note: Please replace PlatForm in below scripts with the actual platform path you are trying to build.

Multi-stage build

>cd iot-edge-modbus/
>docker build -t modbusModule -f Docker/<PlatForm>/Dockerfile-auto .

Manually build

The application requires the .NET Core SDK 2.0.

>cd iot-edge-modbus/src/
>dotnet restore
>dotnet build
>dotnet publish -f netcoreapp2.0
>cd ../iot-edge-modbus/
>docker build --build-arg EXE_DIR=./src/bin/Debug/netcoreapp2.0/publish -t modbusModule -f Docker/<PlatForm>/Dockerfile .

Configuration

The Modbus module uses module twin as its configuration. Here is a sample configuration for your reference.

{
  "Interval": "1500",
  "SlaveConfigs": {
    "Slave01": {
      "SlaveConnection": "192.168.0.1",
      "HwId": "PowerMeter-0a:01:01:01:01:01",
      "Operations": {
        "Op01": {
          "UnitId": "1",
          "StartAddress": "400001",
          "Count": "2",
          "DisplayName": "Voltage"
        },
        "Op02": {
          "UnitId": "1",
          "StartAddress": "400002",
          "Count": "2",
          "DisplayName": "Current"
        }
      }
    },
    "Slave02": {
      "SlaveConnection": "192.168.0.2",
      "HwId": "PowerMeter-0a:01:01:01:01:02",
      "Operations": {
        "Op01": {
          "UnitId": "1",
          "StartAddress": "40001",
          "Count": "2",
          "DisplayName": "Voltage"
        },
        "Op02": {
          "UnitId": "1",
          "StartAddress": "40002",
          "Count": "2",
          "DisplayName": "Current"
        }
      }
    }
  }
}

Meaning of each field:

• "SlaveConfigs" <20> Contains one or more Modbus slaves' configuration. In this sample, we have "Slave01" and "Slave02" two devices:
• "Interval" <20> Interval between each push to IoT Hub in millisecond
  • "Slave01", "Slave02" - User defined names for each Modbus slave, cannot have duplicates
  • "SlaveConnection" <20> IPV4 address of the Modbus slave
  • "HwId" <20> Unique Id for each Modbus slave (user defined)
  • "Operations" <20> Contains one or more Modbus read requests. In this sample, we have "Op01" and "Op02" two read requests in both Slave01 and Slave02:
    • "UnitId" <20> The unit id to be read
    • "StartAddress" <20> The starting address of Modbus read request, currently supports both 5-digit and 6-digit format
    • "Count" <20> Number of registers/bits to be read
    • "DisplayName" <20> Alternative name for the "StartAddress" register(s)(user defined)
    • "Op01", "Op02" - User defined names for each read request, cannot have duplicates under the same "SlaveConfig"

For more about Modbus, please refer to the Wiki link.

Module Endpoints and Routing

All telemetry are sent out from modbusOutput endpoint by default. Routing is enabled by specifying rules like below.

Route to IoT Hub

{
  "modbusToIoTHub":"FROM /messages/modules/modbus/outputs/modbusOutput INTO $upstream"
}

Route to other (filter) modules

{
  "modbusToFilter":"FROM /messages/modules/modbus/outputs/modbusOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")"
}

Write to Modbus

Modbus module also has an input enpoint to receive message/commands. Currently it supports writing back to a single register/cell in a Modbus slave. The content of command must be the following format.

{
	"HwId":"PowerMeter-0a:01:01:01:01:01",
	"UId":"1",
	"Address":"40001",
	"Value":"15"
}

The command should have a property "command-type" with value "ModbusWrite". Also, routing must be enabled by specifying rule like below.

{
  "filterToModbus":"FROM /messages/modules/filtermodule/outputs/output1 INTO BrokeredEndpoint(\"/modules/modbus/inputs/input1\")"
}

Debug

There is a flag IOT_EDGE at the first line in Program.cs, which can be turn off to debug the Modbus module in console mode. Running console mode requires IoT device connection string being inserted as a environment variable named EdgeHubConnectionString, and a local configuration file iot-edge-modbus.json since module twin is not available.
Note: running in console mode means none of the IoT Edge features is available. This mode is only to debug non edge-related functions.