Gateway management module fails to route MQTT messages to downstream devices after config update

IoT Microsoft Azure IoT
, , , , , , , ,
1

After updating our gateway-mgmt module configuration in aziot-24, MQTT messages from the gateway to downstream leaf devices are no longer being delivered. Commands sent from IoT Hub reach the gateway successfully, but fail to route to the target devices.

The route configuration looks valid in the deployment manifest, and downstream device mapping appears correct in the gateway’s configuration. Log analysis shows messages arriving at the gateway but no forwarding attempts. The previous configuration worked perfectly before we added two new device types to the downstream device list.

Could this be a route validation issue where the new device types aren’t properly registered, or is there something specific about MQTT topic mapping that needs adjustment?

2

You have two distinct issues that need addressing:

Route Config Validation: Your current route only handles ‘sensor’ devices. Update to handle all device types:

{
  "routes": {
    "toDownstreamSensors": "FROM /messages/* WHERE deviceType = 'sensor' INTO BrokeredEndpoint(/devices/{deviceId}/messages/devicebound)",
    "toDownstreamActuators": "FROM /messages/* WHERE deviceType = 'actuator' INTO BrokeredEndpoint(/devices/{deviceId}/messages/devicebound)"
  }
}

Or use a single route with OR condition:

{
  "routes": {
    "toDownstream": "FROM /messages/* WHERE deviceType IN ['sensor', 'actuator'] INTO BrokeredEndpoint(/devices/{deviceId}/messages/devicebound)"
  }
}

The IN operator is cleaner when handling multiple device types.

Downstream Device Mapping: Verify your gateway’s config.toml includes the new devices:

[[downstream_devices]]
device_id = "actuator01"
auth_type = "sas_key"
auth_value = "SharedAccessKey=..."

[[downstream_devices]]
device_id = "actuator02"
auth_type = "sas_key"
auth_value = "SharedAccessKey=..."

Each downstream device must be explicitly listed with valid authentication credentials.

Log Analysis: Enable detailed logging to diagnose routing failures:

iotedge logs edgeHub --tail 100

Look for:

  • “Route evaluation failed” - indicates condition problems
  • “Device not found” - mapping issue
  • “Authentication failed” - credential problems

For the new actuator devices, ensure they’re configured to connect through the gateway. On each actuator device, set the gateway hostname:

# In device connection string
HostName=iothub.azure-devices.net;DeviceId=actuator01;SharedAccessKey=...;GatewayHostName=gateway-device.local

The GatewayHostName parameter tells the device to route through your gateway instead of connecting directly to IoT Hub.

After updating routes and device mapping:

  1. Restart edgeHub: `iotedge restart edgeHub
  2. Reconnect downstream devices
  3. Monitor logs: `iotedge logs edgeHub -f
  4. Test with a command from IoT Hub to verify routing

The root cause is that your route condition didn’t account for the new device type, AND the new devices weren’t properly registered in the gateway’s downstream device list. Both must be configured correctly for message routing to work.

3

Don’t forget to verify device authentication. Run iotedge list on the gateway to see if downstream devices are showing as connected. If they’re not authenticated, messages won’t route even with correct route configuration. Check your device connection strings and gateway hostname settings on the leaf devices.

4

Good point about authentication. I checked and the new actuator devices are showing as disconnected in iotedge list. The route condition is definitely part of the issue, but there seems to be an authentication problem too.

5

That’s your problem - your route condition only matches ‘sensor’ type. You need to either create separate routes for each device type or use an OR condition: WHERE deviceType = 'sensor' OR deviceType = 'actuator'. Also check that your downstream device mapping in config.toml includes the new devices with correct authentication.

6

Here’s our route config:

{
  "routes": {
    "toDownstream": "FROM /messages/* WHERE deviceType = 'sensor' INTO BrokeredEndpoint(/devices/{deviceId}/messages/devicebound)"
  }
}

The new devices have deviceType=‘actuator’. Should I add another route or modify the condition?

7

Check your routes in the deployment manifest carefully. When you add new device types, you need to ensure the route’s condition matches the new message properties. Can you share your route configuration? Also verify that the downstream devices are actually connected to the gateway.