TrakHound Docs MTConnect.NET Configure Modules

Configure Modules

The settings of every Agent and Adapter module: HTTP, MQTT, SHDR, and the machine adapters.
MTConnect.NET Docs Menu

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:

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 successive Current publishes. Default: 10000 (10 s).
  • sampleInterval — milliseconds between successive Sample publishes. 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:

KeyDefault
serverlocalhost
port1883
timeout5000
reconnectInterval10000
topicPrefixMTConnect
topicStructureDocument
documentFormatjson-cppAgent
currentInterval5000
sampleInterval500
durableRelayfalse

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:

ModuleConfiguration class
http-serverMTConnect.Configurations.HttpServerModuleConfiguration
mqtt-brokerMTConnect.Configurations.MqttBrokerModuleConfiguration
mqtt-relayMTConnect.Configurations.MqttRelayModuleConfiguration
mqtt-adapterMTConnect.Configurations.MqttAdapterModuleConfiguration
shdr-adapterMTConnect.Configurations.ShdrAdapterModuleConfiguration
http-adapterMTConnect.Configurations.HttpAdapterModuleConfiguration
haas-adapterMTConnect.Configurations.HaasAdapterModuleConfiguration
fanuc-adapterMTConnect.Configurations.FanucAdapterModuleConfiguration
tormach-adapterMTConnect.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