MQTT Broker

Host an MQTT broker inside the Agent that publishes its Devices, Observations, and Assets.
MTConnect.NET Docs Menu
  • Module name — MTConnect MQTT Broker agent module
  • Identifier — mqtt-broker
  • NuGet package — MTConnect.NET-AgentModule-MqttBroker
  • Source path — agent/Modules/MTConnect.NET-AgentModule-MqttBroker/

Purpose

Hosts an embedded MQTT broker inside the agent process. The broker accepts subscriptions from consumers and publishes the agent's documents (Probe / Current / Sample / Asset) and entities (per-DataItem observations) on the topic tree rooted at topicPrefix. Use this module when consumers should connect directly to the agent over MQTT without a separate broker deployment; use the MQTT relay module when the agent should publish to an external broker instead.

Configuration Schema

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

KeyTypeDefaultPermissible valuesNotes
serverstringnull (binds to all interfaces)hostname or IP addressThe hostname or IP address the embedded broker binds to.
portint18831-65535The TCP port the embedded broker listens on. 8883 is conventional for TLS.
tlsmapnullsee the HTTP server's tls schemaTLS configuration; presence switches the listener to mqtts.
timeoutint5000millisecondsThe timeout applied to client connection and read / write operations.
initialDelayint500millisecondsDelay between module start and broker bind, giving the OS time to release the TCP port from a previous run.
restartIntervalint5000millisecondsDelay between broker-start retries after a bind failure.
qosint00 (at-most-once), 1 (at-least-once), 2 (exactly-once)The QoS level the broker publishes at.
topicPrefixstringMTConnectany MQTT-valid topic prefixRoot of the topic tree the broker publishes on.
topicStructureenumDocumentDocument, EntitySelects per-document publication (Document) or per-DataItem publication (Entity).
documentFormatstringjson-cppagentXML, JSON, JSON-cppAgentThe document format used for the published payloads.
indentOutputboolfalsetrue, falseIndents the payload for readability (raises bytes-on-wire).
currentIntervalint5000millisecondsThe interval at which Current envelopes are republished.
sampleIntervalint500millisecondsThe interval at which Sample envelopes are republished.

Topic Tree

With topicPrefix: MTConnect and topicStructure: Document, the broker publishes on:

  • MTConnect/Probe/<deviceUuid> — the Probe envelope.
  • MTConnect/Current/<deviceUuid> — the Current envelope, republished every currentInterval ms.
  • MTConnect/Sample/<deviceUuid> — the Sample envelope, republished every sampleInterval ms.
  • MTConnect/Asset/<deviceUuid>/<assetId> — per-asset payloads.

With topicStructure: Entity the broker publishes per-DataItem on MTConnect/Observations/<deviceUuid>/<componentId>/<dataItemId> instead.

Wire Interaction

AgentSequence buffer
publish
mqtt-broker moduleA broker inside the Agent
MQTT
MQTT consumerSubscribes to topics
  1. Connect
  2. Consumer BrokerCONNECT (client ID, optional TLS handshake)
  3. Broker ConsumerCONNACK
  4. Consumer BrokerSUBSCRIBE MTConnect/Current/+
  5. Broker ConsumerSUBACK
  6. Every currentInterval ms
  7. Agent BufferGetObservations(at: latest) returns the latest Observations
  8. Agent BrokerPublish the Current document
  9. Broker ConsumerPUBLISH MTConnect/Current/<uuid>
  10. Every sampleInterval ms
  11. Agent BufferGetObservations(from: lastSequence) returns a page of Observations
  12. Agent BrokerPublish the Sample document
  13. Broker ConsumerPUBLISH MTConnect/Sample/<uuid>
Consumers connect to the Agent itself, so no separate broker is needed.

Example Configuration

modules:
  - mqtt-broker:
      server: 0.0.0.0
      port: 1883
      topicPrefix: MTConnect
      topicStructure: Document
      documentFormat: json-cppagent
      indentOutput: false
      qos: 1
      currentInterval: 5000
      sampleInterval: 500
      timeout: 5000
      initialDelay: 500
      restartInterval: 5000

For TLS-secured broker access:

modules:
  - mqtt-broker:
      port: 8883
      topicPrefix: MTConnect
      tls:
        pem:
          certificatePath: /etc/mtconnect/certs/broker.pem
          privateKeyPath: /etc/mtconnect/certs/broker.key
          certificateAuthority: /etc/mtconnect/certs/rootCA.pem
        verifyClientCertificate: true

Troubleshooting

  • Bind failures — the embedded broker shares the TCP port with no other process. If the port is already in use the module retries every restartInterval ms; raise initialDelay if a previous run's socket is in TIME_WAIT.
  • MQTT TLS handshake failures — see MQTT TLS handshake failures.
  • Document format selection — json-cppagent is byte-for-byte cppagent-parity for v2 envelopes; XML is the wire format defined by the MTConnect REST protocol; JSON is the legacy v1 JSON shape.

Classes

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

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