SHDR Adapter

Connect to SHDR adapters and add the lines they send to the Agent as Observations.
MTConnect.NET Docs Menu
  • Module name — MTConnect SHDR Adapter agent module
  • Identifier — shdr-adapter
  • NuGet package — MTConnect.NET-AgentModule-ShdrAdapter
  • Source path — agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/

Purpose

Opens a TCP connection to an SHDR-protocol adapter (typically a piece of equipment exposing the SHDR protocol over a port) and feeds the received observations into the agent. SHDR is the original MTConnect ingestion protocol — line-oriented, pipe-delimited, optimized for streaming small observations from a PLC. This module is the most common adapter-side ingestion path in MTConnect deployments.

Configuration Schema

The module's configuration class is ShdrAdapterModuleConfiguration (it derives from ShdrAdapterClientConfiguration, which derives from ShdrClientConfiguration). The keys below describe the YAML map under shdr-adapter:.

KeyTypeDefaultPermissible valuesNotes
deviceKeystringnulldevice name or UUIDMatches the Device@name or Device@uuid in Devices.xml the inbound observations target.
hostnamestringlocalhosthostname or IP addressThe remote SHDR adapter's address.
portint78781-65535The remote SHDR adapter's TCP port.
heartbeatint10000millisecondsInterval at which the module sends * PING keep-alive frames.
connectionTimeoutint5000millisecondsSilence threshold (for legacy adapters that do not support heartbeats) before disconnect. Ignored when heartbeats are present.
reconnectIntervalint10000millisecondsDelay between reconnect attempts after a disconnect.
allowShdrDeviceboolfalsetrue, falseWhen true, a * device frame from the adapter is accepted as a device-model update.
availableOnConnectionboolfalsetrue, falseFor devices that do not emit their own availability event, setting this true sets Availability = AVAILABLE when the TCP connection comes up.
convertUnitsbooltruetrue, falseWhether the agent converts the adapter's values to the DataItem's declared units. Set false if the adapter has already converted.
ignoreObservationCasebooltruetrue, falseWhether the agent ignores case when matching incoming string observations against the DataItem's enumerated values.
ignoreTimestampsboolfalsetrue, falseWhen true, the agent stamps the observation with its own clock instead of trusting the adapter's timestamp. Corrects adapter clock drift at the cost of network-latency error.
outputConnectionInformationbooltruetrue, falseEmits the adapter's host / port as an observation.
ignoreHeartbeatOnChangebooltruetrue, falseWhen true, the heartbeat PING is suppressed if any data has been received within the heartbeat window.

Wire Interaction

SHDR adapterSends pipe-delimited lines
TCP
shdr-adapter moduleConnects to the adapter
AgentSequence buffer
  1. Connect
  2. Module SHDR adapterTCP connect to <hostname>:<port>
  3. SHDR adapter ModuleConnection accepted
  4. Module AgentAddObservation(avail, AVAILABLE), when availableOnConnection = true
  5. Every heartbeat ms
  6. Module SHDR adapter* PING
  7. SHDR adapter Module* PONG <heartbeat-ms>
  8. Data
  9. SHDR adapter Module2024-05-13T12:00:00Z|avail|AVAILABLE
  10. Module AgentAddObservation(deviceKey, avail, AVAILABLE), appended to the sequence buffer
  11. SHDR adapter Module2024-05-13T12:00:01Z|estop|ARMED
  12. Module AgentAddObservation(deviceKey, estop, ARMED)
  13. Connection drop
  14. Module SHDR adapterDisconnected
  15. Module SHDR adapterTCP connect again every reconnectInterval ms
The Agent connects to the adapter, not the other way around.

Example Configuration

modules:
  - shdr-adapter:
      deviceKey: M12346
      hostname: 192.168.1.50
      port: 7878
      heartbeat: 10000
      reconnectInterval: 10000
      availableOnConnection: true
      ignoreTimestamps: false
      convertUnits: true

For a legacy SHDR adapter that does not respond to PING:

modules:
  - shdr-adapter:
      deviceKey: M12346
      hostname: 192.168.1.50
      port: 7878
      connectionTimeout: 5000
      ignoreHeartbeatOnChange: false
      heartbeat: 0

For multiple adapters, declare the module several times — each entry connects to a different remote adapter:

modules:
  - shdr-adapter:
      deviceKey: M12346
      hostname: 192.168.1.50
      port: 7878
  - shdr-adapter:
      deviceKey: M67890
      hostname: 192.168.1.51
      port: 7878

Troubleshooting

  • Empty name attributes on probe DataItems — see Empty name attributes on probe DataItems. The SHDR protocol does not transmit DataItem metadata; the name attribute must exist in the agent's Devices.xml.
  • Asset count emitted as a scalar EVENT instead of DATA_SET — see Asset count emitted as scalar.
  • Clock drift — set ignoreTimestamps: true if the adapter's system clock cannot be kept in sync.
  • Heartbeat tuning — set heartbeat: 0 to disable heartbeats entirely and rely on connectionTimeout only. This is rarely the right choice but is required for adapters that mis-handle PING.
  • deviceKey mismatch drops observations silently; verify against /probe output before declaring the deployment working.

Classes

The main classes in the MTConnect.NET-AgentModule-ShdrAdapter package:

  • ShdrAdapterModuleConfiguration — the module's configuration class.
  • ShdrAdapterClientConfiguration — the base SHDR adapter-client configuration shape.
  • ShdrClientConfiguration — the SHDR client configuration shape.