MQTT Adapter

Subscribe to an external MQTT broker and add the messages to the Agent as Observations.
MTConnect.NET Docs Menu
  • Module name — MTConnect MQTT Adapter agent module
  • Identifier — mqtt-adapter
  • NuGet package — MTConnect.NET-AgentModule-MqttAdapter
  • Source path — agent/Modules/MTConnect.NET-AgentModule-MqttAdapter/

Purpose

Subscribes to an external MQTT broker and feeds the received observations, assets, and device payloads into the agent. This is the agent-side counterpart to the MQTT output adapter module — together they form an MQTT-mediated bridge between a remote adapter and the agent.

Module status

This module is under development and may be deprecated in a future release. Please send feedback or report issues on GitHub.

Configuration Schema

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

KeyTypeDefaultPermissible valuesNotes
serverstringlocalhosthostname, IP, or fully qualified domain nameThe hostname of the MQTT broker to subscribe to.
portint18831-65535The broker's MQTT port.
timeoutint5000millisecondsConnection and read / write timeout.
reconnectIntervalint10000millisecondsDelay between reconnect attempts after a disconnect.
usernamestringnullanyUsername for username + password authentication.
passwordstringnullanyPassword for username + password authentication.
clientIdstringnull (auto-generated)any MQTT client-id stringClient identifier presented to the broker.
cleanSessionbooltruetrue, falseSets the MQTT clean-session flag.
qosint10 (at-most-once), 1 (at-least-once), 2 (exactly-once)The QoS level requested on subscriptions.
useTlsboolfalsetrue, falseSwitches the connection to TLS (mqtts).
certificateAuthoritystringnullfilesystem pathPath to the CA certificate file.
pemCertificatestringnullfilesystem pathPath to the PEM client-certificate file.
pemPrivateKeystringnullfilesystem pathPath to the PEM private-key file.
allowUntrustedCertificatesboolfalsetrue, falseDisables certificate-chain verification (development only).
topicPrefixstringnullany MQTT-valid topic prefixThe topic prefix the module subscribes to.
deviceKeystringnulldevice name or UUIDIdentifies which Device in Devices.xml the incoming payloads target.
documentFormatstringjsonXML, JSON, JSON-cppAgentThe document format the broker payloads are encoded in.

Subscribed Topics

With topicPrefix: input, the module subscribes to:

  • input/observations — observation payloads.
  • input/assets — asset payloads.
  • input/device — device-model payloads.

Wire Interaction

Remote producerPublishes to the broker
PUBLISH
MQTT brokerExternal
SUBSCRIBE
mqtt-adapter moduleAdds to the Agent
AgentSequence buffer
  1. Connect
  2. Adapter BrokerCONNECT (client ID, optional TLS handshake)
  3. Broker AdapterCONNACK
  4. Adapter BrokerSUBSCRIBE <topicPrefix>/observations, <topicPrefix>/assets, <topicPrefix>/device
  5. Broker AdapterSUBACK
  6. Observations
  7. Producer BrokerPUBLISH <topicPrefix>/observations
  8. Broker AdapterPUBLISH <topicPrefix>/observations
  9. Adapter AgentAddObservations(deviceKey, ...), appended to the sequence buffer
  10. Assets
  11. Producer BrokerPUBLISH <topicPrefix>/assets
  12. Broker AdapterPUBLISH <topicPrefix>/assets
  13. Adapter AgentAddAsset(deviceKey, ...)
The producer and the Agent never connect to each other: the broker sits between them.

Example Configuration

modules:
  - mqtt-adapter:
      server: broker.example.com
      port: 1883
      topicPrefix: input
      deviceKey: M12346
      qos: 1
      cleanSession: true
      reconnectInterval: 10000
      documentFormat: json

For a TLS-secured broker with mutual TLS:

modules:
  - mqtt-adapter:
      server: broker.example.com
      port: 8883
      useTls: true
      certificateAuthority: /etc/mtconnect/certs/rootCA.pem
      pemCertificate: /etc/mtconnect/certs/agent.pem
      pemPrivateKey: /etc/mtconnect/certs/agent.key
      topicPrefix: input
      deviceKey: M12346

Troubleshooting

  • MQTT TLS handshake failures — see MQTT TLS handshake failures.
  • deviceKey mismatch — the value must match a Device@name or Device@uuid in the agent's Devices.xml. A mismatch causes the agent to drop the inbound observations silently; verify with the /probe endpoint that the device is present.
  • Payload-format mismatch — documentFormat must match the encoding the remote producer publishes. The remote can be the MQTT output adapter module, which publishes JSON.

Classes

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

  • MqttAdapterModuleConfiguration — the module's configuration class.
  • MTConnectMqttClientConfiguration — the base MQTT client configuration shape.