Modules are the agent's pluggable extension points. Each module attaches a capability — HTTP serving, MQTT publishing, SHDR ingestion — and a single agent typically runs several modules at once. This page documents every shipped module's configuration keys.
The module set:
- HTTP server —
/probe,/current,/sample,/assetendpoints. - MQTT broker — embedded MQTT broker.
- MQTT relay — outbound publisher to an external MQTT broker.
- MQTT adapter — inbound consumer from an external MQTT broker.
- SHDR adapter — inbound TCP-SHDR adapter.
- HTTP adapter — inbound HTTP-poll adapter.
- Haas adapter — reads a Haas CNC control over Ethernet or RS-232.
- Fanuc adapter — reads a Fanuc CNC using FOCAS over Ethernet.
- Tormach adapter — reads a Tormach PathPilot controller.
Every module is declared in agent.config.yaml under modules: as a single-key map.
The key is the module's name; the value is the module's config object.
HTTP Server
Hosts the MTConnect endpoints:
/probe, /current, /sample, /asset, plus optional file-serving for stylesheets and schemas.
Module key:
http-server.
Implementation:
MTConnect.NET-AgentModule-HttpServer.
Keys
- http-server:
hostname: 0.0.0.0 # interface to bind. Default: all interfaces.
port: 5000 # listen port. Default: 5000.
allowPut: false # whether /put is allowed for ingest. Default: false.
indentOutput: true # pretty-print responses. Default: false.
documentFormat: xml # default response format. xml | json | json-cppAgent
accept: # MIME-to-format dispatch.
text/xml: xml
application/json: json
application/mtconnect+json: json-cppAgent
responseCompression: # which compression encodings to advertise.
- gzip
- br
files: # static-file mounts under /styles, /schemas, etc.
- path: schemas
location: schemas
- path: styles
location: styles
tls: # optional TLS settings.
pem:
certificateAuthority: /path/to/rootCA.crt
certificatePath: /path/to/server.crt
privateKeyPath: /path/to/server.key
privateKeyPassword: <secret>
Multiple http-server instances are supported and common — one on port 5000 plain, another on port 5001 with TLS, and a third on 5002 with allowPut: true for an internal ingest endpoint.
tls
The tls: block configures TLS termination. Two shapes are supported:
pem:— PEM-encoded certificate chain and private key.pfx:— PKCS#12 bundle.
When TLS is enabled, the HTTP server accepts only HTTPS connections.
The tlsConfiguration class is shared with the MQTT modules — see MTConnect.Tls.TlsConfiguration.
MQTT Broker
Hosts an embedded MQTT broker that publishes one topic per Device / DataItem, formatted as JSON-CPPAGENT-MQTT.
Consumers connect with any MQTT client.
Module key:
mqtt-broker.
Implementation:
MTConnect.NET-AgentModule-MqttBroker.
- mqtt-broker:
port: 1883
currentInterval: 10000
sampleInterval: 500
documentFormat: JSON-CPPAGENT
topicPrefix: MTConnect/Document
topicStructure: Document # Document | Entity
tls:
pem:
certificateAuthority: /path/to/rootCA.crt
certificatePath: /path/to/server.crt
privateKeyPath: /path/to/server.key
privateKeyPassword: <secret>
Topic Structures
Document— one topic per response document. Topics are<prefix>/Probe/<deviceUuid>,<prefix>/Current/<deviceUuid>,<prefix>/Sample/<deviceUuid>,<prefix>/Asset/<deviceUuid>/<assetId>. The payload is the full envelope.Entity— one topic per Observation / Asset / Device. Topics are<prefix>/Devices/<deviceUuid>,<prefix>/Observations/<deviceUuid>/<dataItemId>,<prefix>/Assets/<deviceUuid>/<assetId>. The payload is a single entity.
The Document structure is the cppagent-MQTT parity shape; the Entity structure is the library's per-observation alternative for consumers that prefer one-topic-per-observation.
Intervals
currentInterval— milliseconds between successiveCurrentpublishes. Default:10000(10 s).sampleInterval— milliseconds between successiveSamplepublishes. Default:500.
MQTT Relay
Publishes outbound MQTT messages to an external broker.
The agent acts as a client.
Module key:
mqtt-relay.
Implementation:
MTConnect.NET-AgentModule-MqttRelay.
The configuration object is MqttRelayModuleConfiguration.
- mqtt-relay:
server: broker.example.com # MQTT broker hostname.
port: 1883 # broker port.
timeout: 5000 # connect / I/O timeout (ms).
reconnectInterval: 10000 # delay between reconnect attempts (ms).
username: agent-01 # optional broker auth.
password: <secret>
clientId: agent-01 # MQTT client id.
cleanSession: true # MQTT clean-session flag.
qos: 1 # 0 | 1 | 2.
useTls: false # whether to use TLS.
tls:
pem:
certificateAuthority: /path/to/rootCA.crt
certificatePath: /path/to/agent.crt
privateKeyPath: /path/to/agent.key
privateKeyPassword: <secret>
topicPrefix: MTConnect # topic prefix.
topicStructure: Document # Document | Entity (see MQTT broker).
documentFormat: JSON-CPPAGENT-MQTT
indentOutput: false
currentInterval: 5000 # millis between Current publishes.
sampleInterval: 500 # millis between Sample publishes.
durableRelay: true # buffer + replay on reconnect.
durableRelay
When true, the relay buffers outbound messages while disconnected and replays them on reconnect, preserving ordering. Set false to drop in-flight messages and resume only the live stream.
Default Values
The shipped defaults match what the constructor sets:
| Key | Default |
|---|---|
server | localhost |
port | 1883 |
timeout | 5000 |
reconnectInterval | 10000 |
topicPrefix | MTConnect |
topicStructure | Document |
documentFormat | json-cppAgent |
currentInterval | 5000 |
sampleInterval | 500 |
durableRelay | false |
MQTT Adapter
Subscribes to an external MQTT broker and ingests Observations from incoming messages.
Module key:
mqtt-adapter.
Implementation:
MTConnect.NET-AgentModule-MqttAdapter.
- mqtt-adapter:
deviceKey: mill-01 # the Device this adapter feeds.
server: broker.example.com
port: 1883
topic: MTConnect/Adapter/mill-01 # subscribe topic (supports + and # wildcards).
username: agent-01
password: <secret>
useTls: false
tls: { ... } # same TlsConfiguration shape as above.
The adapter expects each MQTT message to carry a JSON-CPPAGENT or JSON-v1 Observation payload (or an SHDR-formatted text line).
The documentFormat field auto-detects when omitted.
SHDR Adapter
Connects to an SHDR-output adapter over TCP and ingests SHDR lines.
Module key:
shdr-adapter.
Implementation:
MTConnect.NET-AgentModule-ShdrAdapter.
- shdr-adapter:
deviceKey: mill-01 # the Device this adapter feeds.
hostname: localhost # remote SHDR adapter host.
port: 7878 # remote SHDR adapter port.
heartbeat: 1000 # heartbeat interval (ms).
reconnectInterval: 1000 # delay between reconnect attempts (ms).
connectionTimeout: 1000 # connection timeout (ms).
Multiple instances are typical when more than one upstream adapter feeds the agent — one per Device, each on its own port.
HTTP Adapter
Polls an HTTP endpoint that returns MTConnect-shaped responses.
Module key:
http-adapter.
Implementation:
MTConnect.NET-AgentModule-HttpAdapter.
- http-adapter:
deviceKey: mill-01
url: http://upstream-agent.example.com:5000/sample
interval: 1000 # poll interval (ms).
documentFormat: xml # expected response format.
The HTTP adapter is most often used to chain agents — a regional aggregator agent polling per-cell agents — but works against any HTTP endpoint that emits the right envelope.
Haas Adapter
Reads a Haas CNC control directly over Ethernet or RS-232 using Haas Q-commands.
Module key:
haas-adapter.
Implementation:
MTConnect.NET-AgentModule-HaasAdapter.
See Haas Adapter for every key and the DataItems it reports.
- haas-adapter:
deviceKey: VF2 # the Device observations are added to (created by default).
server: 192.168.1.60 # Haas control address (Ethernet).
port: 5051 # Q-command port (Setting 143).
readInterval: 1000 # delay between read cycles (ms).
slowReadInterval: 10000 # delay between reads of timers, counters and version (ms).
units: inch # units the control reports positions in (Setting 9).
axes: [X, Y, Z] # axes to read positions for (X, Y, Z, A, B, C).
Fanuc Adapter
Reads a Fanuc CNC directly using FOCAS over Ethernet.
Module key:
fanuc-adapter.
Implementation:
MTConnect.NET-AgentModule-FanucAdapter.
The Fanuc FOCAS libraries (Fwlib64.dll / Fwlib32.dll) are not included and must be copied next to the agent.
See Fanuc Adapter for every key and the DataItems it reports.
- fanuc-adapter:
deviceKey: M1 # the Device observations are added to (created by default).
server: 192.168.1.70 # CNC address.
port: 8193 # FOCAS port.
readInterval: 1000 # delay between read cycles (ms).
workPositions: false # also report absolute (work) positions.
Tormach Adapter
Reads a Tormach PathPilot controller through the PathPilot status server (pathpilot/pathpilot_status_server.py), which runs on the controller and streams the LinuxCNC status over TCP.
Module key:
tormach-adapter.
Implementation:
MTConnect.NET-AgentModule-TormachAdapter.
See Tormach Adapter for installing the status server, every key, and the DataItems it reports.
- tormach-adapter:
deviceKey: PCNC1100 # the Device observations are added to (created by default).
server: 192.168.1.80 # PathPilot controller address.
port: 7890 # status server port.
workPositions: false # also report work coordinate positions.
Configuration Objects
Each module's YAML keys deserialize into a configuration class:
| Module | Configuration class |
|---|---|
http-server | MTConnect.Configurations.HttpServerModuleConfiguration |
mqtt-broker | MTConnect.Configurations.MqttBrokerModuleConfiguration |
mqtt-relay | MTConnect.Configurations.MqttRelayModuleConfiguration |
mqtt-adapter | MTConnect.Configurations.MqttAdapterModuleConfiguration |
shdr-adapter | MTConnect.Configurations.ShdrAdapterModuleConfiguration |
http-adapter | MTConnect.Configurations.HttpAdapterModuleConfiguration |
haas-adapter | MTConnect.Configurations.HaasAdapterModuleConfiguration |
fanuc-adapter | MTConnect.Configurations.FanucAdapterModuleConfiguration |
tormach-adapter | MTConnect.Configurations.TormachAdapterModuleConfiguration |
Programmatic configuration uses the class directly:
using MTConnect.Configurations;
var relay = new MqttRelayModuleConfiguration
{
Server = "broker.example.com",
Port = 8883,
UseTls = true,
DocumentFormat = "JSON-CPPAGENT-MQTT",
TopicPrefix = "MTConnect/Document",
CurrentInterval = 5000,
SampleInterval = 500,
DurableRelay = true,
};
Where to Next
- Configure an Agent — the agent-wide settings the modules live under.
- Configure the MQTT Relay — a full MQTT-relay walk-through.
- Write a JSON-MQTT Consumer — the consumer side.
- MQTT TLS Handshake Failures — when TLS connections fail.