This recipe configures the mqtt-relay module — the agent's outbound publisher that pushes observations and assets to an external MQTT broker.
By the end you have:
- The agent publishing to a broker every 500 ms (Samples) and 5 s (Current).
- A subscriber receiving the published payloads in JSON-CPPAGENT-MQTT format.
- TLS enabled on the broker connection.
- A durable-relay configuration that buffers and replays on reconnect.
1. The Minimal Config
In agent.config.yaml:
modules:
- mqtt-relay:
server: broker.example.com
port: 1883
topicPrefix: MTConnect/Document
topicStructure: Document
documentFormat: JSON-CPPAGENT-MQTT
currentInterval: 5000
sampleInterval: 500
That is the smallest config that works. The relay publishes to four topics per Device:
MTConnect/Document/Probe/<deviceUuid>— fullMTConnectDevicesenvelope, on model change.MTConnect/Document/Current/<deviceUuid>— fullMTConnectStreamsCurrentenvelope, everycurrentIntervalms.MTConnect/Document/Sample/<deviceUuid>— fullMTConnectStreamsSampleenvelope (delta since last publish), everysampleIntervalms.MTConnect/Document/Asset/<deviceUuid>/<assetId>— fullMTConnectAssetsenvelope, on asset change.
2. The Topology
mqtt-relay moduleThe relay decouples the agent from its consumers. Consumers come and go; the broker absorbs the publish-subscribe semantics.
3. Document Structure vs Entity Structure
Two topicStructure: values:
Document— full envelope per topic. Consumers parseMTConnectStreams/MTConnectDevices/MTConnectAssetsenvelopes.Entity— one entity per topic. Topics are<prefix>/Observations/<deviceUuid>/<dataItemId>,<prefix>/Devices/<deviceUuid>,<prefix>/Assets/<deviceUuid>/<assetId>. The payload is a single entity.
Document is the cppagent-MQTT parity shape; Entity is the library's per-observation shape that some downstream consumers (Kafka bridges, time-series databases) find easier to ingest.
Switch to Entity by setting topicStructure:
Entity and (optionally) documentFormat:
JSON to use the library's JSON v1 codec instead of JSON-CPPAGENT.
4. TLS-Enabled Relay
For broker-side TLS, set useTls: true and configure the tls: block:
modules:
- mqtt-relay:
server: broker.example.com
port: 8883
useTls: true
tls:
pem:
certificateAuthority: /etc/mtconnect/ca.crt
certificatePath: /etc/mtconnect/agent.crt
privateKeyPath: /etc/mtconnect/agent.key
privateKeyPassword: <secret>
topicPrefix: MTConnect/Document
topicStructure: Document
documentFormat: JSON-CPPAGENT-MQTT
currentInterval: 5000
sampleInterval: 500
The pem: block declares a PEM-encoded certificate chain. Two alternates:
pfx:— a PKCS#12 bundle path + password (Windows-friendly).- Omit both — the agent picks up the platform certificate store's roots; useful for brokers using a public CA-signed certificate.
See MQTT TLS Handshake Failures when the handshake fails.
5. Authenticated Relay
Brokers commonly require username/password authentication:
modules:
- mqtt-relay:
server: broker.example.com
port: 1883
username: agent-01
password: <secret>
clientId: agent-01-relay
cleanSession: false # preserve session across reconnects.
qos: 1 # at-least-once delivery.
topicPrefix: MTConnect/Document
topicStructure: Document
documentFormat: JSON-CPPAGENT-MQTT
Production deployments typically:
- Use a per-agent
clientIdso the broker can distinguish multiple agents. - Set
cleanSession: falseso the broker preserves the agent's subscription state across reconnects. - Use
qos: 1(at-least-once) —qos: 0drops on reconnect;qos: 2(exactly-once) adds a four-way handshake the agent rarely needs.
6. Durable Relay
The durableRelay: flag buffers outbound messages while the broker is unreachable and replays them on reconnect:
modules:
- mqtt-relay:
server: broker.example.com
port: 1883
durableRelay: true
currentInterval: 5000
sampleInterval: 500
When durableRelay: true, every Observation that enters the agent's buffer also enters a per-relay outbound queue.
On reconnect, the relay drains the queue in sequence order before resuming live publishes.
This is the right setting for cases where a consumer must not miss data; the trade-off is bounded memory growth during long disconnects.
7. The Subscriber Side
A mosquitto_sub subscribing to the relay:
mosquitto_sub -h broker.example.com -p 1883 -t 'MTConnect/Document/+/+' -v
The -t glob matches any depth-2 sub-topic under MTConnect/Document/. Sample output for one published Current envelope:
MTConnect/Document/Current/mill-01 {"MTConnectStreams":{"Header":{...},"Streams":{...}}}
A dotnet subscriber using MQTTnet:
using MQTTnet;
using MQTTnet.Client;
using System.Text;
var factory = new MqttFactory();
var client = factory.CreateMqttClient();
await client.ConnectAsync(new MqttClientOptionsBuilder()
.WithTcpServer("broker.example.com", 1883)
.Build());
await client.SubscribeAsync(
new MqttTopicFilterBuilder().WithTopic("MTConnect/Document/Current/+").Build());
client.ApplicationMessageReceivedAsync += async e =>
{
var json = Encoding.UTF8.GetString(e.ApplicationMessage.PayloadSegment);
Console.WriteLine($"{e.ApplicationMessage.Topic} : {json[..Math.Min(json.Length, 80)]}...");
await Task.CompletedTask;
};
await Task.Delay(Timeout.Infinite);
The payload parses as a standard MTConnectStreams JSON envelope; pass it to your in-process parser of choice.
See Write a JSON-MQTT Consumer for a complete consumer.
8. Tuning the Intervals
currentInterval and sampleInterval are the two knobs that govern bandwidth:
| Knob | Default | Effect |
|---|---|---|
currentInterval | 5000 (5 s) | Frequency of full Current envelopes. |
sampleInterval | 500 (500 ms) | Frequency of delta Sample envelopes. |
A high-frequency CNC monitoring deployment runs sampleInterval: 100 for sub-second tool-position updates.
A low-bandwidth deployment over cellular runs sampleInterval: 5000 and currentInterval: 60000 to minimize transmits.
The Current envelope is large (the full per-DataItem snapshot); the Sample envelope is small (only observations since the last publish).
9. Availability Topic
The agent publishes a retained Availability message on connect / disconnect, so subscribers know whether the relay is live:
- Topic:
<topicPrefix>/Probe/Availability - Payload on connect:
AVAILABLE - Payload on disconnect (LWT):
UNAVAILABLE
The retained-message + LWT pattern lets a subscriber that connects after the agent went offline still see the UNAVAILABLE state instead of waiting for the next publish.
Where to Next
- Write a JSON-MQTT Consumer — the consumer side, with parsing code.
- Configure modules: MQTT relay — the full key reference.
- JSON-CPPAGENT-MQTT — the on-the-wire payload shape.
- MQTT TLS Handshake Failures — TLS connection diagnostics.