A running MTConnect agent exposes its device model, observations, and assets over two transports: HTTP (the canonical MTConnect REST protocol) and MQTT (the cppagent-parity broker / relay shape). This page covers both—the endpoints + topics a consumer connects to, the polling vs streaming patterns, and the parsing primitives the library ships for .NET consumers.
This page assumes the agent is up and serving (see Run), and picks up at "the agent is running; how do I read from it?"
HTTP: the MTConnect REST Protocol
The HTTP server module (http-server) exposes four canonical endpoints under the configured port (default 5000).
| Path | Purpose | Typical use |
|---|---|---|
/probe | Returns <MTConnectDevices>—the full device model the agent loaded. | Discovery; the consumer reads this once at startup to learn the available DataItems. |
/current | Returns <MTConnectStreams> with the most-recent observation per DataItem. | Snapshot of the live state. |
/sample | Returns <MTConnectStreams> with every observation in a sequence range. | Time-series replay; pagination via the nextSequence cursor in the response Header. |
/asset/<assetId> | Returns <MTConnectAssets> carrying one asset. | Asset retrieval by ID. The /assets endpoint (no ID) returns every active asset. |
Each path also accepts a device-scoped prefix:
/MyDevice/probe, /MyDevice/current, /MyDevice/sample.
The prefix narrows the response to one device's tree.
Polling
A polling consumer hits /current on its own schedule:
curl -s 'http://agent.local:5000/Mill-1/current'
The response is <MTConnectStreams>; each <ComponentStream> carries the most-recent observation per DataItem.
Polling is simplest and tolerates network drops gracefully—every poll is independent.
Streaming
The /sample endpoint supports HTTP long-polling: a request with interval=<ms>&heartbeat=<ms> keeps the connection open and pushes a fresh <MTConnectStreams> chunk every interval milliseconds while the agent has new observations to send.
curl -N 'http://agent.local:5000/sample?from=12345&interval=100&heartbeat=10000'
The server emits an HTTP multipart/x-mixed-replace stream; each part is one <MTConnectStreams> envelope.
Disconnects are detected via the heartbeat (the agent sends a heartbeat chunk every heartbeat ms when no observations are pending); a consumer that misses a heartbeat reconnects from the last seen nextSequence.
The MTConnect Standard caps the maximum interval to keep slow consumers from monopolizing the connection.
The current agent honors the spec minimum / maximum at Part 1.0—HTTP protocol on docs.mtconnect.org (see Compliance by Version: Wire Formats).
Spec Version Negotiation
A version= query parameter pins the envelope shape:
curl -s 'http://agent.local:5000/probe?version=2.5'
Without version=, the agent serves its defaultVersion (from agent.config.yaml, defaulting to MTConnectVersions.Max).
The version pin determines which DataItems / Asset types / Component types are pruned out of the response—the library walks each entity's MinimumVersion / MaximumVersion and emits only what the requested version supports.
Content-Type Negotiation
The default content type is application/xml. The agent also serves JSON when the consumer requests it:
Accept header | Wire format | Codec |
|---|---|---|
application/xml (or no Accept) | XML | MTConnect.Formatters.Xml.XmlResponseDocumentFormatter |
application/json | Legacy JSON v1 | MTConnect.Formatters.JsonResponseDocumentFormatter |
The JSON v2 (cppagent-parity) codec is selected via the documentFormat: key on the HTTP server module config rather than through HTTP content negotiation; see Configure Modules: HTTP Server for the per-module accept: mapping.
.NET HTTP Client
For a .NET consumer, the MTConnectHttpClient family handles polling, long-polling, sequence-cursor management, and codec dispatch:
using MTConnect.Clients;
using MTConnect.Observations;
var client = new MTConnectHttpClient("http://agent.local:5000");
client.CurrentReceived += (sender, doc) =>
{
foreach (var device in doc.Streams)
foreach (var component in device.ComponentStreams)
foreach (var observation in component.Observations)
Console.WriteLine($"{component.Name}.{observation.DataItemId} = {observation.GetValue(ValueKeys.Result)}");
};
client.Start();
CurrentReceived fires once on stream initialization—Start() drives the /sample long-poll, not periodic /current polling.
For periodic snapshots, call GetCurrent() directly on a timer; for the streaming case, subscribe to SampleReceived.
The client also exposes the post-probe device model.
DeviceReceived fires once per parsed device for every /probe response, carrying the fully wired IDevice instance with its DataItems' Container and Device back-pointers set.
The Devices property returns a read-only snapshot of every device the most recent probe yielded, keyed by UUID; entries are replaced wholesale on each probe and devices the agent no longer advertises are evicted at the start of the next probe.
Both surfaces were added per issue #176.
The client handles reconnects on the consumer's behalf; the ConnectionError event fires on transport failures and the client backs off and retries.
Parsing or dispatch failures surface through InternalError.
A DeviceReceived handler that throws is isolated: the exception is routed through InternalError and the cache fill plus the rest of the per-device fan-out continue normally.
MQTT: the cppagent-Parity Broker and Relay Tree
When the agent runs an mqtt-broker module or relays through mqtt-relay, every observation is published to an MQTT topic in the cppagent JSON v2 MQTT shape.
Two topic layouts are published in parallel: the document-server layout (whole-envelope publishes keyed by device) from MTConnect.MTConnectMqttDocumentServer, and the entity-server layout (per-data-item, per-asset publishes) from MTConnect.Clients.MTConnectMqttEntityServer.
Document-server topics (envelope payloads, one publish per device):
| Topic | Payload | Retained |
|---|---|---|
MTConnect/Probe/<deviceUuid> | <MTConnectDevices> envelope for one device | Yes—late subscribers immediately receive the device model. |
MTConnect/Current/<deviceUuid> | <MTConnectStreams> snapshot for one device | Yes—late subscribers receive the most-recent state. |
MTConnect/Sample/<deviceUuid> | <MTConnectStreams> delta since the last publish | No—pure event stream. |
MTConnect/Asset/<deviceUuid>/<assetId> | Asset payload for one asset | Yes—late subscribers receive every active asset. |
Entity-server topics (per-data-item, per-asset payloads):
| Topic | Payload |
|---|---|
MTConnect/Devices/<deviceUuid>/Device | Single-device document payload. |
MTConnect/Devices/<deviceUuid>/Observations/<dataItemId> | One observation in JSON v2 shape. |
MTConnect/Devices/<deviceUuid>/Assets/<assetId> | One asset in JSON v2 shape. |
The <prefix>/ segment (MTConnect/ above) is configurable via the mqtt-broker / mqtt-relay topicPrefix: key.
Subscribe with mosquitto_sub
mosquitto_sub -h broker.local -t 'MTConnect/#' -v
Every message the agent publishes flows through. For a single device's per-data-item stream:
mosquitto_sub -h broker.local -t 'MTConnect/Devices/Mill-1/Observations/#' -v
.NET MQTT Consumer
The MTConnectMqttClient class is the consumer-side counterpart of the broker module.
It subscribes to the topic tree, parses each message through the JSON v2 codec, and surfaces typed observations via events:
using MTConnect.Clients;
using MTConnect.Observations;
var client = new MTConnectMqttClient("broker.local", 1883);
client.ObservationReceived += (sender, observation) =>
{
Console.WriteLine($"{observation.DeviceUuid}/{observation.DataItemId} = {observation.GetValue(ValueKeys.Result)}");
};
client.Start();
See Write a JSON-MQTT Consumer for an end-to-end consumer including reconnect handling.
Python MQTT Consumer
For a non-.NET consumer, the JSON v2 payload is plain JSON that parses with any standard library:
import json
import paho.mqtt.client as mqtt
def on_message(client, userdata, msg):
payload = json.loads(msg.payload)
# MTConnect/Devices/+/Observations/<dataItemId> delivers one observation per message.
# The topic tail names the data-item; the payload carries the JSON v2 observation body.
data_item_id = msg.topic.rsplit('/', 1)[-1]
print(data_item_id, payload)
client = mqtt.Client()
client.on_message = on_message
client.connect("broker.local", 1883)
client.subscribe("MTConnect/Devices/+/Observations/#")
client.loop_forever()
The JSON v2 cppagent MQTT page documents the exact payload shape for each topic.
Picking Polling vs Streaming vs MQTT
The three patterns trade off in predictable ways:
- Polling
/currenton a timer: simplest. Loses observations between polls. Use when a snapshot every N seconds is enough. - Long-poll
/sample: lossless across polls (thenextSequencecursor advances through every observation in the agent's buffer). Holds one TCP connection per consumer; good for one or two consumers, costly for many. - MQTT subscription: lossless and fan-out-friendly. The broker handles the connection multiplexing. Adds an MQTT broker to the deployment. Use when several consumers need the same stream, or when the consumer is firewall-restricted from reaching the agent directly.
Spec Source of Record
The HTTP REST protocol is documented at Part_1.0 REST API (the MTConnect Standard's normative prose).
The library's compliance posture is tracked under Compliance by Version: Wire Formats.
The JSON v2 MQTT shape is the cppagent reference implementation's broker output—see the Known Divergences page for current parity gaps.
See Also
- Configure an Agent—the agent's HTTP / MQTT module configuration.
- Configure an Adapter—adapter-side configuration for SHDR-chain consumers tracing back to the equipment.
- Run—starting the agent the consumer connects to.
- Operate—observability and operational signals on the agent side.
- Write a JSON-MQTT Consumer—end-to-end MQTT consumer walkthrough.
- XML—the canonical wire format.
- JSON-CPPAGENT (v2)—the JSON v2 wire format.
- JSON-CPPAGENT-MQTT—the MQTT topic + payload shape.