After upgrading our edge gateway from aziotc 1.2 to 1.4, MQTT messages from downstream devices are no longer being forwarded to IoT Hub. The gateway shows as connected in the portal, but telemetry from leaf devices never arrives at the cloud. I suspect the MQTT route configuration changed between versions, but the documentation doesn’t clearly outline what needs to be updated.
MQTT topic: devices/{device-id}/messages/events/
Status: Messages received by gateway, not forwarded
Gateway logs: No routing errors shown
Gateway-to-IoT Hub connectivity seems fine for the gateway’s own telemetry. Has anyone successfully migrated aziotc gateway-mgmt module configurations across versions?
I ran into this during our upgrade last month. The issue is that aziotc 1.4 requires explicit route definitions for downstream MQTT traffic. The old implicit routing was deprecated. You need to add a route in the edgeHub module configuration that maps downstream device messages to the upstream IoT Hub endpoint. Without this route, messages are received but dropped because there’s no forwarding rule.
Let me provide the complete solution covering all three focus areas that changed between aziotc versions:
MQTT Route Configuration:
The aziotc 1.4 upgrade requires explicit MQTT routing configuration. Add this to your gateway’s config.toml:
[mqtt_bridge]
enabled = true
upstream_topic = "$upstream/#"
downstream_topic_prefix = "devices/"
Then update your IoT Edge deployment manifest to include the routing rule in edgeHub:
{
"routes": {
"leafToIoTHub": "FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream",
"leafDeviceToIoTHub": "FROM /messages/* INTO $upstream"
}
}
The key change is that 1.4 no longer has implicit routing for downstream MQTT messages - you must define explicit routes.
Gateway-to-IoT Hub Connectivity:
Your gateway’s own telemetry works because it uses the direct IoT Hub connection. Downstream devices go through the gateway’s MQTT broker, which requires the MQTT bridge to forward messages upstream. Verify your gateway module configuration includes:
[aziot]
hostname = "your-gateway.local"
parent_hostname = "your-iothub.azure-devices.net"
The parent_hostname setting is new in 1.4 and critical for proper upstream message routing. Without it, the MQTT bridge doesn’t know where to forward downstream messages.
aziotc Version Compatibility:
Version 1.4 introduced breaking changes in the gateway-mgmt module:
-
Authentication Protocol: Downstream devices must now include the gateway hostname in their connection string:
`HostName=iothub.azure-devices.net;DeviceId=leaf-device;GatewayHostName=gateway.local;SharedAccessKey=…
-
MQTT Topic Structure: The topic format changed slightly. Ensure downstream devices publish to:
devices/{deviceId}/messages/events/ (note the trailing slash is now required)
-
Certificate Validation: 1.4 enforces stricter certificate validation. If you’re using custom CA certificates, ensure the gateway’s certificate chain is properly configured in `/etc/aziot/certificates/
-
Module Communication: The gateway-mgmt module now requires explicit permissions in the deployment manifest:
{
"modulesContent": {
"$edgeHub": {
"properties.desired.mqttBroker": {
"authorizations": [
{
"identities": ["{{iotHub}}/devices/{{deviceId}}/modules/{{moduleId}}"],
"allow": [{"operations": ["mqtt:publish", "mqtt:subscribe"]}]
}
]
}
}
}
}
Migration Steps:
- Update config.toml with mqtt_bridge section
- Modify deployment manifest with explicit routes
- Update downstream device connection strings to include GatewayHostName
- Restart aziot-edged service: `sudo systemctl restart aziot-edged
- Verify with:
sudo iotedge logs edgeHub - you should see “Route registered: leafToIoTHub”
After these changes, downstream MQTT messages should flow correctly through the gateway to IoT Hub. The version compatibility issues are primarily around the explicit configuration requirements that were previously handled implicitly.
I found the config.toml file but there’s no [mqtt_bridge] section at all. Should I add it manually, or is there a migration tool? Also, what’s the correct syntax for the route definition in edgeHub?
You need to add the section manually. Here’s the basic structure:
[mqtt_bridge]
enabled = true
upstream_topic = "$upstream/messages/events/"
downstream_topic = "devices/+/messages/events/"
The ‘+’ is a wildcard for device IDs. But you also need to update your edgeHub routes to actually forward these messages. Check the deployment manifest for the routing configuration.
Don’t forget about the authentication changes too. aziotc 1.4 is stricter about downstream device authentication. Make sure your leaf devices are using the gateway’s connection string correctly and that the device identity includes the gateway hostname.