This recipe builds a consumer that subscribes to an MTConnect agent's MQTT relay output, parses the JSON-CPPAGENT-MQTT payloads, and surfaces the observations. By the end you have:
- A dotnet console application connecting to an MQTT broker.
- Subscription to the relay's per-Device topics.
- Parsing of the JSON envelope into typed
IObservationinstances. - A Python alternative for non-dotnet consumers.
1. Set Up the .NET Consumer
dotnet new console -o MyConsumer
cd MyConsumer
dotnet add package MQTTnet
dotnet add package MTConnect.NET-JSON-cppagent
The MQTTnet package is the MQTT client;
MTConnect.NET-JSON-cppagent is the codec that parses JSON-CPPAGENT envelopes into the library's type system.
2. Connect and Subscribe
using MQTTnet;
using MQTTnet.Client;
using System.Text;
var factory = new MqttFactory();
var client = factory.CreateMqttClient();
var options = new MqttClientOptionsBuilder()
.WithTcpServer("broker.example.com", 1883)
.WithCredentials("consumer-01", "<secret>")
.WithClientId("consumer-01")
.WithCleanSession(false)
.Build();
await client.ConnectAsync(options);
// Subscribe to every Sample envelope from every Device.
await client.SubscribeAsync(
new MqttTopicFilterBuilder()
.WithTopic("MTConnect/Document/Sample/+")
.WithAtLeastOnceQoS()
.Build());
// Also subscribe to Current envelopes for the bootstrap snapshot.
await client.SubscribeAsync(
new MqttTopicFilterBuilder()
.WithTopic("MTConnect/Document/Current/+")
.WithAtLeastOnceQoS()
.Build());
Console.WriteLine("Connected; awaiting payloads. Ctrl-C to exit.");
3. Parse the Payload
The relay publishes JSON-CPPAGENT-MQTT (a JSON-CPPAGENT envelope wrapped for MQTT delivery).
The library's JsonMqttResponseDocumentFormatter parses it into typed IStreamsResponseDocument, IDevicesResponseDocument, and IAssetsResponseDocument instances:
using MTConnect.Formatters;
using MTConnect.Observations;
using System.IO;
var formatter = new JsonMqttResponseDocumentFormatter();
client.ApplicationMessageReceivedAsync += async e =>
{
var payload = e.ApplicationMessage.PayloadSegment.ToArray();
var topic = e.ApplicationMessage.Topic;
if (topic.StartsWith("MTConnect/Document/Sample/") ||
topic.StartsWith("MTConnect/Document/Current/"))
{
using var stream = new MemoryStream(payload);
var result = formatter.CreateStreamsResponseDocument(stream);
var streams = result.Content;
if (streams is null) return;
foreach (var deviceStream in streams.Streams)
{
foreach (var componentStream in deviceStream.ComponentStreams)
{
foreach (var obs in componentStream.Observations)
{
Console.WriteLine(
$"{deviceStream.Uuid} {obs.DataItemId} = {obs.GetValue(ValueKeys.Result)} @ {obs.Timestamp:O}");
}
}
}
}
await Task.CompletedTask;
};
A Sample payload contains the delta since the last publish — observations that happened in the last sampleInterval ms.
A Current payload contains the most-recent observation per DataItem at publish time.
4. Watch for Asset Changes
Assets arrive on a separate topic. Subscribe and parse:
await client.SubscribeAsync(
new MqttTopicFilterBuilder()
.WithTopic("MTConnect/Document/Asset/+/+")
.Build());
// In the message handler:
if (topic.StartsWith("MTConnect/Document/Asset/"))
{
using var stream = new MemoryStream(payload);
var assets = formatter.CreateAssetsResponseDocument(stream).Content;
foreach (var asset in assets.Assets)
{
Console.WriteLine($"Asset {asset.AssetId} type={asset.Type} removed={asset.Removed}");
}
}
5. Filter by Device or DataItem
The single-plus wildcards in the topic patterns scope subscription. For one specific Device:
MTConnect/Document/Sample/mill-01
For one specific DataItem in Entity-structured mode (topicStructure:
Entity, which publishes under <topicPrefix>/Devices/<deviceUuid>/Observations/<dataItemId>):
MTConnect/Devices/mill-01/Observations/x-pos-actual
A consumer that wants every observation from every Device subscribes:
MTConnect/Devices/+/Observations/#
The broker handles the wildcard expansion; the consumer sees only matching topics.
MQTT wildcards match whole topic levels only (mill-+ is not a valid filter), so narrower matching on part of a Device or DataItem ID belongs in the message handler.
6. Reconnect Handling
MQTT clients drop connections on network blips.
MQTTnet handles reconnect with a managed client wrapper, which ships in the separate MQTTnet.Extensions.ManagedClient package (dotnet add package MQTTnet.Extensions.ManagedClient):
var managed = factory.CreateManagedMqttClient();
await managed.StartAsync(new ManagedMqttClientOptionsBuilder()
.WithClientOptions(options)
.WithAutoReconnectDelay(TimeSpan.FromSeconds(5))
.Build());
await managed.SubscribeAsync(/* topics ... */);
The managed client reconnects automatically and re-establishes subscriptions.
Pair it with cleanSession: false on the relay so the broker delivers messages that were published while the consumer was disconnected.
7. Python Consumer
For non-dotnet integrations, the same payloads parse cleanly in Python:
import paho.mqtt.client as mqtt
import json
def on_connect(client, userdata, flags, rc):
print(f"Connected; rc={rc}")
client.subscribe("MTConnect/Document/Sample/+")
client.subscribe("MTConnect/Document/Current/+")
def on_message(client, userdata, msg):
payload = json.loads(msg.payload)
streams = payload.get("MTConnectStreams", {})
for device_stream in streams.get("Streams", {}).get("DeviceStream", []):
for component_stream in device_stream.get("ComponentStream", []):
for category in ("Samples", "Events", "Condition"):
items = component_stream.get(category, [])
for obs in items:
# obs is a single-key wrapper: {"AvailabilityType": {...}}
for type_name, body in obs.items():
data_item_id = body.get("dataItemId")
value = body.get("Value") or body.get("value")
ts = body.get("timestamp")
print(f"{device_stream['uuid']} {data_item_id} = {value} @ {ts}")
client = mqtt.Client(client_id="consumer-py")
client.username_pw_set("consumer-01", "<secret>")
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.example.com", 1883, 60)
client.loop_forever()
The JSON-CPPAGENT shape — each observation wrapped in {"<type>": {...}} — is unambiguous to parse; the outer key names the spec type, the inner body carries dataItemId, timestamp, value / Value, and any DATA_SET / TABLE entries.
8. Bridging into a Database
A consumer that bridges observations into a time-series database queues them and bulk-inserts:
using System.Threading.Channels;
var queue = Channel.CreateBounded<IObservation>(10_000);
client.ApplicationMessageReceivedAsync += async e =>
{
using var stream = new MemoryStream(e.ApplicationMessage.PayloadSegment.ToArray());
var streams = formatter.CreateStreamsResponseDocument(stream).Content;
foreach (var ds in streams.Streams)
foreach (var cs in ds.ComponentStreams)
foreach (var obs in cs.Observations)
await queue.Writer.WriteAsync(obs);
};
_ = Task.Run(async () =>
{
var batch = new List<IObservation>(500);
await foreach (var obs in queue.Reader.ReadAllAsync())
{
batch.Add(obs);
if (batch.Count >= 500)
{
await InsertBatch(batch);
batch.Clear();
}
}
});
For InfluxDB specifically, see the InfluxDB integration page for the line-protocol mapping.
Use the Built-In MQTT Client
Steps 2–6 wire MQTTnet and the formatter together by hand.
The MTConnect.NET-MQTT package ships MTConnectMqttClient, which does the subscribing, topic dispatch, and JSON-CPPAGENT-MQTT parsing for you and raises typed events.
The runnable sample in examples/MTConnect.NET-Client-MQTT/ uses it:
dotnet add package MTConnect.NET-MQTT
using MTConnect.Clients;
using MTConnect.Configurations;
var config = new MTConnectMqttClientConfiguration();
config.Server = "localhost";
config.Port = 1883;
config.TopicPrefix = "MTConnect/Document"; // must match the relay's topicPrefix
var client = new MTConnectMqttClient(config);
client.ClientStarted += (s, args) => Console.WriteLine("Client Started");
client.DeviceReceived += (s, device) =>
Console.WriteLine($"Device Received : {device.Uuid} : {device.Name}");
client.ObservationReceived += (s, observation) =>
Console.WriteLine($"Observation Received : {observation.DataItemId} : {string.Join(";", observation.Values.Select(o => o.Value))}");
client.AssetReceived += (s, asset) =>
Console.WriteLine($"Asset Received : {asset.AssetId}");
client.Start();
There is also a shorthand constructor, new MTConnectMqttClient("localhost", 1883, topicPrefix: "MTConnect/Document").
Besides the per-entity events, the client raises whole-document events (ProbeReceived, CurrentReceived, SampleReceived, AssetsReceived) for consumers that want the envelope rather than individual observations.
The client subscribes to the Document-structured topic tree under TopicPrefix:
<topicPrefix>/Probe/<deviceUuid>
<topicPrefix>/Current/<deviceUuid>
<topicPrefix>/Sample/<deviceUuid>
<topicPrefix>/Asset/<deviceUuid>/<assetId>
Set config.DeviceUuid to scope the subscription to one Device; leave it empty to receive every Device.
Two things to line up with the publishing agent:
- Topic structure —
MTConnectMqttClientonly understandstopicStructure: Document(themqtt-relayandmqtt-brokermodules both default to it). FortopicStructure: Entity, use the raw MQTTnet approach from steps 2–5, orMTConnectMqttExpandedClient, which reads the per-entityMTConnect/Devices/...tree. - Document format — the client decodes payloads as
json-cppagent-mqttby default, so setdocumentFormat: JSON-CPPAGENT-MQTTon the publishing module.
Pick the MQTT client over polling the agent's HTTP /sample endpoint when the agent already publishes to a broker (cheaper fan-out to many consumers), when a firewall allows outbound MQTT but not inbound HTTP to the agent, or when you want push delivery without long-polling.
Where to Next
- Configure the MQTT Relay — the agent side that publishes the messages this consumer reads.
- JSON-CPPAGENT-MQTT — payload shape reference.
- MQTT relay module and MQTT broker module — the two agent modules that publish to MQTT.
- MQTT Protocol — the canonical topic tree and message-shape catalogue.
MTConnect.NET-JSON-cppagent— the package withJsonMqttResponseDocumentFormatter.- InfluxDB — turn this consumer into a bridge.