Adapter

The commands and options of the Adapter application (mtconnect.net-adapter), as a terminal application or a service.
MTConnect.NET Docs Menu

MTConnect-Adapter is the standalone adapter host. It loads an adapter.config.yaml (or adapter.config.json) configuration file, builds an MTConnectAdapter per configured output module, wires the configured DataSource into the input side, and pumps observations downstream to one or more MTConnect agents.

The CLI surface is defined by MTConnectAdapterApplication.Run(args) in adapter/MTConnect.NET-Applications-Adapter/MTConnectAdapterApplication.cs. The shipped mtconnect.net-adapter binary in adapter/MTConnect.NET-Adapter/ is a thin entry point that constructs a DataSource and calls Run(args, true) on the application class. Embedders that build their own adapter from MTConnect.NET-Applications-Adapter get the same CLI surface.

Synopsis

mtconnect.net-adapter [help|install|install-start|start|stop|remove|debug|run|run-service] [configuration_file]

If no command is given, the adapter runs in run mode (foreground, info-level logging). If no configuration file is given, the adapter looks for adapter.config.yaml in the executable's directory, copying adapter.config.default.yaml into place if it does not exist.

Commands

CommandDescription
helpPrint usage information and exit.
runRun the adapter in the foreground at info-level logging. Default when no command is supplied. Blocks until killed.
debugRun the adapter in the foreground at debug-level logging on the console target.
run-serviceRun the adapter as a Windows service (non-blocking). On non-Windows operating systems the adapter logs that the command is unsupported and exits.
installInstall the adapter as a Windows service. Windows only. Stops and removes any existing service of the same name first.
install-startInstall the adapter as a Windows service and start it immediately. Windows only.
startStart the previously installed Windows service. Windows only.
stopStop the Windows service. Windows only.
removeStop and remove the Windows service. Windows only.

Unlike the agent CLI, the adapter does not have a trace command and does not have a reset command (the adapter does not own a persistent buffer in the way the agent does).

Arguments

ArgumentDescription
configuration_filePath to the adapter configuration file. Absolute or relative to the executable's directory. If omitted, the adapter looks for adapter.config.yaml in the executable's directory and copies adapter.config.default.yaml into place if it does not exist.

Example Invocations

Run in the foreground against an explicit config file:

./mtconnect.net-adapter run /etc/mtconnect/adapter.config.yaml

Run with debug-level console logging while bringing up a new data source:

./mtconnect.net-adapter debug

Install the adapter as a Windows service and start it:

.\mtconnect.net-adapter.exe install-start C:\ProgramData\MTConnect\adapter.config.yaml

Run from source against the default config during development:

dotnet run --project adapter/MTConnect.NET-Adapter -- debug

Configuration File

The adapter reads YAML by default (CamelCase keys). Default filenames live alongside the adapter binary:

FileRole
adapter.config.yamlActive configuration.
adapter.config.jsonAlternative active configuration, JSON format.
adapter.config.default.yamlShipped default. Copied to adapter.config.yaml on first run if the active file does not exist.
NLog.configNLog configuration shipped alongside the adapter binary.

The active configuration is reloaded when monitorConfigurationFiles: true is set (the default) and the file is edited at runtime, with a minimum gap of configurationFileRestartInterval seconds between restarts.

Top-Level Keys

Backed by AdapterApplicationConfiguration in libraries/MTConnect.NET-Common/Configurations/.

Key (YAML)TypeDefaultDescription
changeTokenstringnew GUID per saveInternal token regenerated when the adapter rewrites the file.
idstringa random 6-character string per fresh configUnique identifier for this adapter instance. Used when the adapter participates in a topology with several siblings.
deviceKeystringnullName or UUID of the MTConnect device the adapter is producing observations for. Must match the device's name= or uuid= in the downstream agent's Devices.xml.
readIntervalint (ms)100Interval at which the configured DataSource is polled for new values.
writeIntervalint (ms)100Interval at which queued observations are flushed to the downstream agent.
filterDuplicatesbooltrueWhen true, observations whose value equals the previous observation for the same data item are dropped at the adapter (the agent does the same on its end, but the early filter saves wire bytes).
outputTimestampsbooltrueWhen true, the adapter prepends a timestamp to every emitted SHDR line. Set to false only if the downstream agent is configured with ignoreTimestamps: true and you want the agent's clock to win.
enableBufferboolfalseWhen true, the adapter queues observations between writeInterval ticks rather than sending each one as it arrives. Send-on-flush gives consistent batching at the cost of up to writeInterval ms of latency per observation.
serviceNamestringnull (falls back to a per-platform default)Windows-service short name. Lets multiple adapters coexist on one machine.
serviceAutoStartbooltrueWindows-service start type. true = Automatic, false = Manual.
monitorConfigurationFilesbooltrueRestart the adapter when adapter.config.yaml changes on disk.
configurationFileRestartIntervalint (seconds)2Minimum gap between auto-restarts triggered by the file watcher.
enginemap{}Free-form key/value pairs forwarded to the DataSource for source-specific configuration (e.g. a serial port name, a host address, an OPC UA endpoint). Accessed by the data source via GetEngineProperty(name).
moduleslist of single-key maps[]Each entry instantiates one adapter output module. See Modules for the per-module schema.

Module List Shape

modules is a YAML sequence where each element is a single-key map keyed by the module name. Each module's value object is the module's per-instance configuration.

modules:
  - shdr:
      port: 7878
  - mqtt:
      server: localhost
      port: 1883

The two adapter output modules shipped today are:

  • shdr — the SHDR socket server. Backed by MTConnect.NET-AdapterModule-SHDR. The downstream agent connects on port via a shdr-adapter module. See Modules for the full SHDR key set.
  • mqtt — the MQTT publisher. Backed by MTConnect.NET-AdapterModule-MQTT. Publishes observations to server:port on the configured topic tree. See Modules for the full MQTT key set.

Multiple instances of the same module are allowed; each entry is a distinct module instance.

Engine Block — Data-Source-Specific Settings

The engine map is free-form. Whatever keys you write there become accessible to the DataSource implementation via configuration.GetEngineProperty("keyName"). The shipped DataSource in adapter/MTConnect.NET-Adapter/DataSource.cs is a stub — embedders override it. Examples:

engine:
  serialPort: COM3
  baudRate: 115200
  parity: None
engine:
  opcUaEndpoint: opc.tcp://192.168.1.50:4840
  username: mtconnect

Sample Shipped Default

The default config shipped at adapter/MTConnect.NET-Adapter/adapter.config.default.yaml wires an SHDR module on port 7878 and an MQTT module on localhost:1883 for the device OKUMA-Lathe:

id: PatrickAdapter
deviceKey: OKUMA-Lathe

modules:
  - shdr:
      port: 7878
  - mqtt:
      server: localhost
      port: 1883

Edit deviceKey, the SHDR port, and the MQTT endpoint to match your topology before pointing the adapter at a real data source.

NLog Configuration

Logging is routed through NLog. The shipped NLog.config defines the following named loggers:

Logger nameUsed for
application-loggerApplication-level events: config load, service install / start / stop, fatal errors.
adapter-loggerAdapter-pump events: data-source reads, observation flushes.
moduleModule-loaded, module-start, module-stop, and module-side log events.

To raise the console target to debug-level on a single run, use the debug command. To raise it permanently, edit NLog.config.

Exit Behavior

  • run, debug block forever; Ctrl+C / SIGINT triggers a graceful shutdown that flushes pending observations and runs every module's Stop() hook.
  • run-service returns control to the service controller; lifecycle is managed by Windows.
  • install, install-start, start, stop, remove, help complete and exit.

See Also

  • Configure & Use → Configure an adapter — annotated end-to-end adapter.config.yaml walkthrough plus data-source bring-up.
  • Configure & Use → Run — local-dev, Windows-service, and systemd-unit deployment.
  • Modules — per-module configuration schemas referenced by the modules: list.
  • MTConnect.NET-Applications-Adapter — the NuGet package with the classes behind the CLI: MTConnect.Applications.MTConnectAdapterApplication (the CLI itself), MTConnect.Configurations.AdapterApplicationConfiguration (the configuration the YAML deserializes into), and MTConnect.Adapters.MTConnectAdapter (the inner adapter that runs WriteObservations / WriteAssets / WriteDevices).
  • Agent CLI — the sibling agent host that consumes the adapter's output.