TrakHound Docs MTConnect.NET Write an Adapter

Write an Adapter

Build an adapter in code that sends values from a CSV log, TCP feed, or PLC to an Agent over SHDR.
MTConnect.NET Docs Menu

This recipe walks through building an MTConnect adapter in code — the upstream half of the data flow that ships values from a custom source (a CSV log, a TCP feed, a PLC) into an MTConnect agent over SHDR.

By the end you have:

  • A class implementing IAdapter that emits SHDR lines on TCP port 7878.
  • A test client that connects to the adapter and prints the lines.
  • A pattern for wiring the adapter into the agent's shdr-adapter module.

1. Set Up the Project

dotnet new console -o MyAdapter
cd MyAdapter
dotnet add package MTConnect.NET-SHDR

The MTConnect.NET-SHDR package contains the SHDR codec — parser, writer, heartbeat state machine.

2. Build a Minimal Adapter

The library's ShdrAdapter class implements an SHDR TCP server. Instantiate it with a device key and a port:

using MTConnect.Shdr;

var adapter = new ShdrAdapter(deviceKey: "mill-01", port: 7878);
adapter.Start();

Console.WriteLine("SHDR adapter listening on port 7878 for device mill-01");

The adapter is now accepting connections. Any consumer that opens a TCP socket to localhost:7878 joins the broadcast list.

3. Push Observations

Each observation is fed into the adapter through the Add family of methods:

using MTConnect.Shdr;
using MTConnect.Devices;

// EVENT — discrete state.
adapter.AddDataItem(new ShdrDataItem("avail", "AVAILABLE"));
adapter.AddDataItem(new ShdrDataItem("ctrl-mode", "AUTOMATIC"));

// SAMPLE — numeric value.
adapter.AddDataItem(new ShdrDataItem("x-pos-actual", 12.345m));

// CONDITION — a fault.
adapter.AddCondition(new ShdrCondition("ctrl-system",
    ConditionLevel.FAULT,
    nativeCode: "E1024",
    qualifier: "HIGH",
    message: "Spindle over-temperature"));

The AddDataItem call adds the observation to the adapter's outgoing buffer and broadcasts an SHDR line to every connected consumer. The line shape is <timestamp>|<dataItemKey>|<value>, formatted per Part_5.0 of the MTConnect Standard (docs.mtconnect.org).

4. Drive a Real Data Source

A typical adapter polls a vendor data source and emits observations on each poll. The pattern:

using System.Net.Http;
using MTConnect.Shdr;

var adapter = new ShdrAdapter("mill-01", 7878);
adapter.Start();

var http = new HttpClient();

while (true)
{
    // Pretend this is the PLC's HTTP API.
    var json = await http.GetStringAsync("http://192.168.1.100/status");
    var status = ParseStatus(json);

    adapter.AddDataItem(new ShdrDataItem("avail", status.Available ? "AVAILABLE" : "UNAVAILABLE"));
    adapter.AddDataItem(new ShdrDataItem("ctrl-mode", status.Mode));
    adapter.AddDataItem(new ShdrDataItem("x-pos-actual", status.AxisX));

    await Task.Delay(500);
}

The 500 ms poll interval is the adapter's own pace; the SHDR consumer sees the lines as they emit. Adjust by data source.

5. Test the Adapter Standalone

In another terminal:

nc localhost 7878

You should see:

2025-01-01T12:34:56.789Z|avail|AVAILABLE
2025-01-01T12:34:56.890Z|ctrl-mode|AUTOMATIC
2025-01-01T12:34:56.890Z|x-pos-actual|12.345
* PING

The * PING line is the adapter's heartbeat, sent every Heartbeat ms (default 10 000). A connected consumer responds with * PONG <heartbeat-ms> to confirm liveness.

6. Wire the Adapter into an Agent

On the agent side, configure a shdr-adapter module that points at the adapter's TCP socket:

modules:
- shdr-adapter:
    deviceKey: mill-01
    hostname: localhost
    port: 7878
    heartbeat: 1000
    reconnectInterval: 1000
    connectionTimeout: 1000

The agent's shdr-adapter module connects to localhost:7878, consumes the SHDR lines, looks up each dataItemKey against the Device's model (Device.GetDataItemByKey checks Id, then Name, then Source.DataItemId, then Source.Value), and writes the resulting Observation into the agent's buffer.

A flow diagram:

  1. Adding data
  2. PLC ShdrAdapterVendor API response, read by your code
  3. ShdrAdapter (port 7878) shdr-adapter moduleAn SHDR line
  4. shdr-adapter moduleResolves the dataItemKey through the Device model
  5. shdr-adapter module Agent bufferAddObservation
  6. Reading data
  7. Consumer HTTP serverGET /current
  8. HTTP server Agent bufferThe latest Observation of each DataItem
  9. Agent buffer HTTP serverObservations
  10. HTTP server ConsumerAn MTConnectStreams document
The Adapter and the Agent only share SHDR lines, so they can run on different computers.

7. Handle Disconnect / Reconnect

The ShdrAdapter class manages reconnect / heartbeat / buffer state internally:

  • When the consumer disconnects, the adapter drops the connection and listens for a new one.
  • When the consumer fails to send a * PONG within the heartbeat window, the adapter closes the connection.
  • On reconnect, the adapter does NOT replay lines emitted while disconnected — the consumer asks the agent for /sample?from=<lastSeen> to fill the gap, and the agent answers from its buffer.

The adapter side does not buffer for replay because the data source (a PLC, a sensor) is the source of truth: the agent re-asks the data source on reconnect, not the adapter. This matches the SHDR spec's lifecycle in Part_5.0 Network.

8. Production Patterns

For production deployments:

  • Run the adapter as a service: use MTConnect.NET-Services to host it as a Windows service or systemd unit.
  • Persist the source-side queue: if the data source is reliable but the adapter-to-agent link is flaky, queue at the data-source side (PLC's log, message queue) and play forward.
  • Use MQTT instead of SHDR: for cross-network deployments, swap the SHDR output for an MQTT publish to a persistent broker. See Configure the MQTT Relay.
  • Validate the data source's encoding: SHDR is plain text; ensure the source's character encoding is UTF-8 to avoid byte-mangling on the wire.

Where to Next