MQTT Output

Publish the Adapter application's data to an MQTT broker for an Agent's MQTT Adapter module.
MTConnect.NET Docs Menu
  • Module name — MTConnect MQTT adapter module (adapter-side)
  • Identifier — mqtt
  • NuGet package — MTConnect.NET-AdapterModule-MQTT
  • Source path — adapter/Modules/MTConnect.NET-AdapterModule-MQTT/

Purpose

Publishes the adapter's observation values to an MQTT broker. An MTConnect agent's mqtt-adapter module subscribes to the same broker and forwards the observations into the agent. Use this transport when the adapter and the agent sit on opposite sides of a network boundary that does not allow direct TCP connections, or when a centralized broker already mediates the deployment's data movement.

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 ModuleConfiguration (under MTConnect.Configurations in the MTConnect.NET-AdapterModule-MQTT assembly). The keys below describe the YAML map under mqtt:.

KeyTypeDefaultPermissible valuesNotes
serverstringlocalhosthostname, IP, or fully qualified domain nameThe MQTT broker's address.
portint78781-65535The MQTT broker's port. 1883 for plaintext, 8883 for TLS — the default 7878 matches the SHDR convention rather than the MQTT convention and is typically overridden.
usernamestringnullanyUsername for username + password authentication.
passwordstringnullanyPassword for username + password authentication.
clientIdstringnull (auto-generated)any MQTT client-id stringClient identifier presented to the broker.
qosint00 (at-most-once), 1 (at-least-once), 2 (exactly-once)The QoS level used on every publish.
useTlsboolfalsetrue, falseSwitches the connection to TLS (mqtts).
certificateAuthoritystringnullfilesystem pathPath to the CA certificate.
pemCertificatestringnullfilesystem pathPath to the PEM client-certificate file.
pemPrivateKeystringnullfilesystem pathPath to the PEM private-key file.
allowUntrustedCertificatesboolfalsetrue, falseDisables certificate-chain verification (development only).
connectionTimeoutint5000millisecondsConnection and read / write timeout.
reconnectIntervalint10000millisecondsDelay between reconnect attempts after a disconnect.
topicstringnullany MQTT-valid topicRoot topic the module publishes on; observation payloads land at <topic>/Observations.
deviceKeystringnulldevice name or UUIDIdentifies which Device the published observations target.
documentFormatstringjsonXML, JSON, JSON-cppAgentThe document format used for the published payloads.

Payload Shape

Payloads are gzip-compressed and published on <topic>/Observations. The default JSON shape:

[
  {
    "timestamp": "2024-05-13T23:15:01.7754921Z",
    "observations": [
      {
        "dataItemKey": "avail",
        "values": { "result": "AVAILABLE" }
      },
      {
        "dataItemKey": "estop",
        "values": { "result": "ARMED" }
      },
      {
        "dataItemKey": "system",
        "values": {
          "level": "WARNING",
          "nativeCode": "404"
        }
      }
    ]
  }
]

DATA_SET and TABLE observations use the same shape with structured values:

{
  "dataItemKey": "vars",
  "values": {
    "DATASET[E100]": "12.123",
    "DATASET[E101]": "6574"
  }
}
{
  "dataItemKey": "toolTable",
  "values": {
    "TABLE[T1][LENGTH]": "142.654",
    "TABLE[T1][DIAMETER]": "12.496"
  }
}

Wire Interaction

Data sourceA PLC, sensor, or file
mqtt output moduleIn the Adapter host
PUBLISH
MQTT brokerExternal
SUBSCRIBE
Agentmqtt-adapter module
  1. Connect
  2. Module BrokerCONNECT (clientId, optional TLS)
  3. Broker ModuleCONNACK
  4. Agent BrokerSUBSCRIBE <topic>/Observations
  5. Broker AgentSUBACK
  6. Data update
  7. Data source Adapter hostA new value
  8. Adapter host ModuleA batch of Observations
  9. Module Modulegzip and encode the payload
  10. Module BrokerPUBLISH <topic>/Observations
  11. Broker AgentPUBLISH <topic>/Observations, appended to the sequence buffer
  12. Network outage
  13. Module BrokerDisconnected
  14. Module BrokerCONNECT again every reconnectInterval ms
The Adapter and the Agent only share the broker and the topic.

Example Configuration

modules:
  - mqtt:
      server: broker.example.com
      port: 1883
      topic: MTConnect/Input
      deviceKey: M12346
      documentFormat: json

For TLS with username + password:

modules:
  - mqtt:
      server: broker.example.com
      port: 8883
      useTls: true
      username: adapter
      password: changeme
      topic: MTConnect/Input
      deviceKey: M12346

For mutual TLS (AWS IoT shape):

modules:
  - mqtt:
      server: a1b2c3d4-ats.iot.us-east-1.amazonaws.com
      port: 8883
      certificateAuthority: certs/AmazonRootCA1.pem
      pemCertificate: certs/adapter-certificate.pem.crt
      pemPrivateKey: certs/adapter-private.pem.key
      topic: MTConnect/Input
      deviceKey: M12346

Troubleshooting

  • MQTT TLS handshake failures — see MQTT TLS handshake failures.
  • Topic mismatch — the adapter's topic and the agent's mqtt-adapter topicPrefix must align. Conventionally the agent subscribes to <topic> and the adapter publishes at <topic>/Observations; verify against the agent module's subscribed topics list.
  • Compression failures — payloads are gzip-compressed; an agent that subscribes to the topic without gzip-decoding will see opaque binary. The agent's mqtt-adapter module handles gzip transparently.
  • Reconnect loops indicate broker-side rejection (bad credentials, malformed client-id, IP not allow-listed); enable verbose adapter logging to surface the CONNACK reason code.

Classes

The main classes in the MTConnect.NET-AdapterModule-MQTT package:

  • ModuleConfiguration — the adapter-side MQTT module configuration class (under MTConnect.Configurations in the MTConnect.NET-AdapterModule-MQTT assembly).
  • MTConnectAdapterModule — the base class adapter modules derive from.