MQTT Relay

Publish the Agent's Devices, Observations, and Assets to an external MQTT broker.
MTConnect.NET Docs Menu
  • Module name — MTConnect MQTT Relay agent module
  • Identifier — mqtt-relay
  • NuGet package — MTConnect.NET-AgentModule-MqttRelay
  • Source path — agent/Modules/MTConnect.NET-AgentModule-MqttRelay/

Purpose

Publishes the agent's documents (Probe / Current / Sample / Asset) to an external MQTT broker. Use this module when consumers should connect to a centralized broker (AWS IoT, HiveMQ, Mosquitto, etc.) rather than directly to the agent process. The module connects to the broker as an MQTT client, reconnects on disconnect, and (optionally) persists unsent observations to disk so a network outage does not drop history.

Configuration Schema

The module's configuration class is MqttRelayModuleConfiguration. The keys below describe the YAML map under mqtt-relay:.

KeyTypeDefaultPermissible valuesNotes
serverstringlocalhosthostname, IP, or fully qualified domain nameThe hostname of the external MQTT broker.
portint18831-65535The broker's MQTT port. 8883 is conventional for TLS.
timeoutint5000millisecondsConnection and read / write timeout.
reconnectIntervalint10000millisecondsDelay between reconnect attempts after a disconnect.
usernamestringnullanyUsername for username + password authentication.
passwordstringnullanyPassword for username + password authentication.
useTlsboolfalsetrue, falseSwitches the connection to TLS (mqtts).
clientIdstringnull (auto-generated)any MQTT client-id stringClient identifier presented to the broker.
cleanSessionboolfalsetrue, falseSets the MQTT clean-session flag.
qosint00 (at-most-once), 1 (at-least-once), 2 (exactly-once)The QoS level used on every publish.
tlsmapnullsee the HTTP server's tls schemaTLS settings (client certificate, CA chain, mutual-TLS toggle).
topicPrefixstringMTConnectany MQTT-valid topic prefixRoot of the topic tree the module publishes on.
topicStructureenumDocumentDocument, EntitySelects per-document publication or per-DataItem publication.
documentFormatstringjson-cppAgentXML, JSON, JSON-cppAgentThe document format used for the published payloads.
indentOutputboolfalsetrue, falseIndents the payload for readability.
currentIntervalint5000millisecondsThe interval at which Current envelopes are republished.
sampleIntervalint500millisecondsThe interval at which Sample envelopes are republished.
durableRelayboolfalsetrue, falseWhen true, the module persists unsent observations to disk and replays them after a reconnect, so observations from a broker outage are not lost.

Wire Interaction

AgentCurrent and Sample documents
mqtt-relay moduleOptional durable spool on disk
PUBLISH
MQTT brokerExternal
MQTT consumerSubscribes to topics
  1. Connect
  2. Relay BrokerCONNECT (client ID, optional TLS handshake)
  3. Broker RelayCONNACK
  4. Consumer BrokerSUBSCRIBE MTConnect/Current/+
  5. Every currentInterval ms
  6. Agent RelayThe Current document
  7. Relay DiskWrite the payload to the spool, when durableRelay = true
  8. Relay BrokerPUBLISH MTConnect/Current/<uuid>
  9. Broker ConsumerPUBLISH MTConnect/Current/<uuid>
  10. Network outage
  11. Relay BrokerDisconnected
  12. Relay BrokerCONNECT again every reconnectInterval ms
  13. Broker RelayCONNACK
  14. Relay BrokerWhen durableRelay = true: read the spooled payloads from disk and publish the backlog
Without durableRelay, documents produced during an outage aren't published.

Example Configuration

modules:
  - mqtt-relay:
      server: broker.example.com
      port: 1883
      topicPrefix: enterprise/site/area/line/cell/MTConnect
      topicStructure: Document
      documentFormat: json-cppagent
      currentInterval: 5000
      sampleInterval: 500
      reconnectInterval: 10000
      qos: 1
      durableRelay: true

For AWS IoT (mutual-TLS over port 8883):

modules:
  - mqtt-relay:
      server: a1b2c3d4e5f6g7-ats.iot.us-east-1.amazonaws.com
      port: 8883
      clientId: mtconnect-agent-01
      tls:
        pem:
          certificateAuthority: certs/AmazonRootCA1.pem
          certificatePath: certs/agent-certificate.pem.crt
          privateKeyPath: certs/agent-private.pem.key
      documentFormat: json-cppagent
      currentInterval: 5000
      sampleInterval: 500
      topicPrefix: enterprise/site/area/line/cell/MTConnect

For HiveMQ Cloud (username + password over TLS):

modules:
  - mqtt-relay:
      server: a1b2c3d4e5f6.s1.eu.hivemq.cloud
      port: 8883
      username: mtconnect
      password: changeme
      useTls: true
      documentFormat: json-cppagent
      currentInterval: 5000
      sampleInterval: 500
      topicPrefix: enterprise/site/area/line/cell/MTConnect

Troubleshooting

  • MQTT TLS handshake failures — see MQTT TLS handshake failures. The most common cause is a CA path that the agent cannot read or that does not chain to the broker's certificate.
  • Reconnect loops — when the broker rejects the connection (bad credentials, malformed client-id, IP not allow-listed), the module retries every reconnectInterval ms. Lower the interval during diagnostic runs so the error appears more frequently in the log.
  • durableRelay backlog growth — disk usage scales with the broker outage window. Monitor the spool directory and provision enough disk for the longest expected outage.
  • AWS IoT, HiveMQ, and AWS Greengrass setups are on the Integrations page.

Classes

The main classes in the MTConnect.NET-AgentModule-MqttRelay package:

  • MqttRelayModuleConfiguration — the module's configuration class.
  • MqttTopicStructure — the Document / Entity enum.
  • IMTConnectMqttDocumentServerConfiguration — the configuration interface this module implements.
  • TlsConfiguration — the TLS configuration schema.