HTTP Adapter

Read from another MTConnect Agent over HTTP and add its Observations to this Agent.
MTConnect.NET Docs Menu
  • Module name — MTConnect HTTP Adapter agent module
  • Identifier — http-adapter
  • NuGet package — MTConnect.NET-AgentModule-HttpAdapter
  • Source path — agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/

Purpose

Reads from another MTConnect agent's REST endpoints (/probe, /current, /sample) and forwards the observations into the local agent. Use this module to aggregate observations from several upstream agents into one consolidated agent, or to bridge agents that sit on different networks. The module supports both streaming (chunked-transfer /sample) and polling (repeated /current) modes.

Configuration Schema

The module's configuration class is HttpAdapterModuleConfiguration (it derives from HttpClientConfiguration). The keys below describe the YAML map under http-adapter:.

KeyTypeDefaultPermissible valuesNotes
addressstringnullhostname or IP addressThe remote agent's address.
portint50001-65535The remote agent's HTTP / HTTPS port.
deviceKeystringnulldevice name or UUIDThe remote-agent device to read.
intervalint500millisecondsThe polling / streaming interval requested from the remote agent.
heartbeatint1000millisecondsThe heartbeat interval used to keep the streaming connection alive.
useSSLboolfalsetrue, falseSwitches the client to HTTPS.
outputConnectionInformationbooltruetrue, falseEmits host / port of the upstream agent as an observation alongside the forwarded data.
currentOnlyboolfalsetrue, falseWhen true, the module polls /current only and does not request /sample pages.
useStreamingbooltruetrue, falseWhen true, uses HTTP chunked-transfer streaming on /sample; when false, polls /sample at the configured interval.
devicesmap[string,DeviceMappingConfiguration]nullsee belowMaps remote device identifiers to local device identifiers.

devices Schema

Each entry maps a remote device to a local device. The map key is the remote-agent device identifier (Device@name or Device@uuid); the value's fields choose the corresponding local device:

KeyTypeNotes
namestringThe local device's name.
uuidstringThe local device's uuid.
idstringThe local device's id.

Set at least one of name / uuid / id; the resolver picks the first non-null in that order.

Wire Interaction

Upstream AgentAny MTConnect Agent
HTTP
http-adapter moduleMaps the upstream Devices
Local AgentAppends to its sequence buffer
  1. Start
  2. Adapter UpstreamGET /probe?device=<deviceKey>
  3. Upstream Adapter200 OK with the Devices document
  4. Adapter Local AgentRegister the Device (mapped by the devices: map)
  5. Adapter UpstreamGET /current?device=<deviceKey>
  6. Upstream Adapter200 OK with a Streams document
  7. Adapter Local AgentAddObservations(mapped deviceKey, ...), appended to the sequence buffer
  8. useStreaming = true
  9. Adapter UpstreamGET /sample?device=<deviceKey>&interval=<I>&heartbeat=<H> (chunked)
  10. Upstream AdapterEach streamed chunk of a Streams document
  11. Adapter Local AgentAddObservations(mapped deviceKey, ...) for each chunk
  12. useStreaming = false : every interval ms
  13. Adapter UpstreamGET /current?device=<deviceKey>
  14. Upstream Adapter200 OK with a Streams document
  15. Adapter Local AgentAddObservations(mapped deviceKey, ...)
Streaming keeps one request open; polling requests /current every interval.

Example Configuration

modules:
  - http-adapter:
      address: upstream-agent.example.com
      port: 5000
      deviceKey: M12346
      interval: 100
      heartbeat: 10000
      useSSL: false
      currentOnly: false
      useStreaming: true
      devices:
        M12346:
          uuid: 00000000-0000-0000-0000-00000000abcd

For HTTPS:

modules:
  - http-adapter:
      address: upstream-agent.example.com
      port: 5001
      useSSL: true
      deviceKey: M12346
      useStreaming: true

Troubleshooting

  • Schema-version mismatches — see Schema-version mismatches. If the upstream agent serves a different MTConnect version than the local agent expects, observations may fail to deserialize.
  • Heartbeat / interval tuning — the upstream agent enforces an MTConnect-spec minimum on the heartbeat and interval query parameters. The module passes the configured values through verbatim; out-of-range values produce a MTConnect.Errors.OUT_OF_RANGE response from the upstream and the module retries.
  • Device-key mismatch — deviceKey must match a device on the upstream agent. Use a browser to hit the upstream's /probe and confirm the device exists before configuring this module.
  • TLS / certificate errors under useSSL: true are surfaced as connection-level failures and retried at the module's reconnect interval.

Classes

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

  • HttpAdapterModuleConfiguration — the module's configuration class.
  • HttpClientConfiguration — the base HTTP client configuration shape.
  • DeviceMappingConfiguration — the per-device mapping entry.