Azure IoT Modbus Gateway Testing

Two Azure Edge Platforms, Two Different Answers

Before writing a line of configuration, figure out which Azure edge stack you're actually targeting, because the two current options diverge sharply on Modbus support:

If you're maintaining an existing IoT Hub deployment or starting a straightforward gateway project without a hard requirement to be on IoT Operations, the iot-edge-modbus module remains the fastest path and is what the rest of this guide focuses on first. If you're building new on IoT Operations, skip ahead to the IoT Operations section — the module described below won't plug into it.

The iot-edge-modbus Module

iot-edge-modbus is an IoT Edge module, source published under the Azure GitHub organization, that polls Modbus TCP or RTU slaves on a schedule and publishes the collected values as IoT Hub messages through the IoT Edge runtime's routing. You deploy it like any IoT Edge module — either by searching the Azure Marketplace for the "Modbus TCP Module by Microsoft" from your IoT Hub's device deployment blade (which auto-wires the IoT Hub routes for you), or by adding it directly to a deployment manifest if you're managing deployments as JSON/CI artifacts.

Once deployed, all the actual behavior — which device to poll, which registers, how often — is controlled through the module's desired properties (its module twin), which you can push through the Azure portal, the Azure CLI, or IoT Hub's device twin APIs.

Configuring SlaveConfigs and Operations

The module's configuration is a JSON object built around SlaveConfigs, keyed by an arbitrary slave name:

{
  "PublishInterval": "5000",
  "SlaveConfigs": {
    "Slave01": {
      "SlaveConnection": "192.168.1.50",
      "RetryCount": "10",
      "RetryInterval": "50",
      "Operations": {
        "Op01": {
          "PollingInterval": "1000",
          "UnitId": "1",
          "StartAddress": "40001",
          "Count": "10",
          "DisplayName": "Line1_HoldingRegs",
          "CorrelationId": "hr-block-1"
        },
        "Op02": {
          "PollingInterval": "2000",
          "UnitId": "1",
          "StartAddress": "30001",
          "Count": "4",
          "DisplayName": "Line1_InputRegs",
          "CorrelationId": "ir-block-1"
        }
      }
    }
  }
}

Key fields:

As with any Modbus integration, watch the addressing convention: StartAddress values here follow the Modicon-style documented register numbering in some sample configs (e.g. 40001 for the first holding register) while the underlying wire read is zero-based — always confirm which convention a given deployment expects against a register you can independently verify, rather than assuming.

PollingInterval vs. PublishInterval

These two settings are easy to conflate but control different things. PollingInterval is set per operation and controls how often the module actually reads that register block off the wire. PublishInterval is set once, module-wide, and controls how often the module batches whatever it has collected since the last publish and sends it to IoT Hub as a message.

They're deliberately decoupled: you might poll a fast-changing analog value every 500ms internally for local accuracy, but only publish to the cloud every 5 or 10 seconds to control IoT Hub message volume and ingestion cost. Get this backwards — publishing faster than you poll, or polling far faster than you ever publish — and you either waste cloud messages on unchanged data or throw away resolution you paid the polling cost for. Size both deliberately against your actual data-freshness requirement, not just the module's defaults.

Azure IoT Operations: No Native Modbus Connector

If you're building on Azure IoT Operations — Microsoft's newer, Arc-enabled edge platform built around Kubernetes and a local MQTT broker rather than classic IoT Hub device connections — the picture changes. As of 2026, Azure IoT Operations ships a first-party connector for OPC UA and native MQTT support through its built-in broker, but it has no equivalent first-party Modbus connector.

That leaves two realistic options for getting Modbus data into an IoT Operations deployment:

• A third-party MQTT-capable edge component that speaks Modbus — HiveMQ Edge is a commonly cited example, positioned specifically as a protocol-translation layer that can poll Modbus and publish onward to an MQTT broker, including the one IoT Operations uses.
• A custom bridge you build and run as its own edge workload — a service (Python with pymodbus, or any language with a Modbus client library and an MQTT client) that polls Modbus registers directly and publishes to the local MQTT broker in whatever topic/payload structure your IoT Operations pipeline expects downstream.

Neither option is a drop-in replacement for the old iot-edge-modbus module's "deploy and configure JSON" simplicity — both require more integration work up front. If your project has flexibility on which Azure edge platform to target and Modbus is a primary protocol, that's a real factor worth weighing before committing to IoT Operations over classic IoT Hub + IoT Edge.

Building a Custom Bridge Instead

Whether you're targeting IoT Operations' MQTT broker or you just need logic the prebuilt module doesn't offer (unit conversion, conditional publishing, combining Modbus data with a second data source before sending), a custom bridge is usually a Modbus client library plus an Azure connectivity SDK, wired together in a poll loop:

# Minimal structure — poll Modbus, publish to Azure
from pymodbus.client import ModbusTcpClient
from azure.iot.device import IoTHubDeviceClient, Message
import json, time

modbus = ModbusTcpClient('192.168.1.50', port=502)
azure = IoTHubDeviceClient.create_from_connection_string(CONN_STR)
azure.connect()

while True:
    result = modbus.read_holding_registers(address=0, count=10, slave=1)
    if not result.isError():
        payload = {"line1_holding_regs": result.registers}
        azure.send_message(Message(json.dumps(payload)))
    time.sleep(5)

This is the same shape whether the target is classic IoT Hub (via the Azure IoT device SDK, shown above) or an IoT Operations MQTT broker (swap the Azure IoT Hub client for a standard MQTT client pointed at the broker's endpoint and topic structure). The Modbus half of the code — connecting, reading registers, handling exceptions — doesn't change based on which Azure platform receives the data.

Common Errors and Fixes

Testing Against a Simulator Before Real Hardware

Point SlaveConnection at a Modbus TCP slave simulator's IP and port instead of a real device, whether you're testing the prebuilt module or a custom bridge:

IoT Edge Device (Modbus module or custom bridge)  →  TCP 502  →  Modbus Slave Simulator
[deployed to a test device or VM]                                      [ModbusSimulator on a bench machine]

Configure ModbusSimulator to run as a Modbus TCP slave on the address and port your configuration points to, and preload registers with distinctive, non-zero test values. Then work through the checks that are hard to safely reproduce against live equipment:

• Addressing verification: confirm each Operation's StartAddress reads the register you intended, catching the 1-based/zero-based offset before it reaches production
• End-to-end confirmation: watch messages arrive at IoT Hub with Azure IoT Explorer or az iot hub monitor-events, and confirm DisplayName tags and values match the simulator's preloaded data
• Timing validation: change a simulator register value and time how long it takes to appear at IoT Hub, confirming PollingInterval and PublishInterval combine to the latency your project actually needs
• Failure handling: stop the simulator mid-poll and confirm the module's RetryCount/RetryInterval behave as configured rather than crashing the module, then restart the simulator and confirm recovery
• Multi-slave/UnitId checks: if polling through a gateway with multiple UnitIds, configure the simulator to respond on more than one unit address and confirm each Operation reads the correct one

Doing this on a bench before deploying to a real IoT Edge gateway at a live site catches configuration mistakes — wrong addresses, misconfigured retries, a PublishInterval that's silently too long — while they cost a five-minute redeploy, not a site visit. It's also the only practical way to test failure handling (a device going offline mid-poll) on demand, since forcing that condition against production equipment usually isn't an option.

Download ModbusSimulator to Test Your Azure IoT Gateway →

Frequently Asked Questions