TrakHound Docs MTConnect.NET Write a JSON-MQTT Consumer

Write a JSON-MQTT Consumer

Subscribe to the MQTT Relay's topics and read the JSON-CPPAGENT-MQTT messages in .NET or Python.
MTConnect.NET Docs Menu

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 IObservation instances.
  • 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 — MTConnectMqttClient only understands topicStructure: Document (the mqtt-relay and mqtt-broker modules both default to it). For topicStructure: Entity, use the raw MQTTnet approach from steps 2–5, or MTConnectMqttExpandedClient, which reads the per-entity MTConnect/Devices/... tree.
  • Document format — the client decodes payloads as json-cppagent-mqtt by default, so set documentFormat: JSON-CPPAGENT-MQTT on 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