Overview

Open source .NET libraries and applications for MTConnect: an Agent, an Adapter, and client libraries that support MTConnect v1.0 through v2.7.
MTConnect.NET Docs Menu

MTConnect.NET is an open source set of .NET libraries and applications that implement the MTConnect Standard from end to end, for MTConnect versions 1.0 through 2.7. It includes:

  • An Agent application with modules for HTTP, MQTT, and SHDR, and for reading Fanuc, Haas, and Tormach machines directly. It runs on Windows, Linux, and macOS, from an installer, a Docker image, or as a Windows Service or systemd unit.
  • An Adapter application that sends data from a PLC or another source to an Agent over SHDR or MQTT.
  • NuGet packages to build an Agent, Adapter, or client into your own application: MTConnect.NET, MTConnect.NET-Common, MTConnect.NET-HTTP, MTConnect.NET-SHDR, MTConnect.NET-MQTT, MTConnect.NET-XML, MTConnect.NET-JSON, MTConnect.NET-JSON-cppagent, MTConnect.NET-TLS, MTConnect.NET-Services, MTConnect.NET-DeviceFinder, MTConnect.NET-SysML, and the MTConnect.NET-Applications-Agents and MTConnect.NET-Applications-Adapter host packages.
  • Every type in the Standard: the classes are generated from the MTConnect SysML model, so each type added or deprecated by a version is included, with its MinimumVersion and MaximumVersion.

The libraries target .NET 9.0, .NET 8.0, .NET 7.0, .NET 6.0, .NET 5.0, .NET Core 3.1, .NET Standard 2.0, and .NET Framework 4.6.1 through 4.8.

How It Fits Together

Adapters send data from machines to the Agent, which keeps the latest Observations in its buffer and serves them to consumers in the format each one asks for:

SHDR AdapterSends lines of data from a machine
HTTP AdapterReads another MTConnect Agent
MTConnect.NET Agent
Input pipelineChecks each value against its DataItem
Sequence bufferObservations, by sequence number
RequestsProbe, Current, Sample, and Asset
ModulesHTTP server, MQTT broker, MQTT relay
Wire formats
XMLRead by dashboards
JSON-CPPAGENT v2Read by bridges
MQTT relay topicsSubscribed to by historians
Each consumer reads the format it needs; the same Observations are served in all of them.

Explore the Docs

Configure & Use

Install, configure, and run an Agent against real equipment, then connect consumers to it. The same Agent process can serve any combination of HTTP, an embedded MQTT broker, an MQTT relay to an external broker, and SHDR, MQTT, and HTTP adapters, all configured in agent.config.yaml.

  • Install: the Agent and Adapter applications, the Docker image, and the NuGet packages, with notes for each target framework.
  • Configure an Agent: every key in agent.config.yaml, Devices.xml, module configuration, and logging.
  • Configure an Adapter: SHDR and HTTP adapter configuration, ports, data sources, and queue and interval adapters.
  • Configure Modules: the configuration keys of every included module.
  • Run: in a terminal with dotnet run, in Docker with trakhound/mtconnect.net-agent, as a Windows Service, or as a systemd unit.
  • Connect a Consumer: read /probe, /current, /sample, and /asset with curl or a browser, subscribe to the MQTT topics, and parse JSON in .NET and Python.
  • Operate: logs, metrics, recovering from errors, and backing up the Agent's storage.
  • Integrations: InfluxDB, HiveMQ, AWS IoT Core, AWS Greengrass, and creating certificates with OpenSSL.

Concepts

These pages map the MTConnect Standard's core concepts to the types in MTConnect.NET. Everything the Agent configures, stores, and serializes comes down to five of them:

ConceptDescription
DeviceThe top level thing the Agent reports Observations for, such as a CNC mill, a robot, or a 3D printer. The Device class in MTConnect.Devices.
ComponentA part of a Device, nested to any depth, such as an axis, a path, a spindle, or a controller. Component and its types (Axes, Path, Spindle, Controller, and more) in MTConnect.Devices.Components.
DataItemA value a Component reports, such as a position, a temperature, or an execution state. It declares its type, subType, category (SAMPLE, EVENT, or CONDITION), units, and nativeUnits. DataItem and its types in MTConnect.Devices.DataItems.
ObservationA value of a DataItem at a point in time, with a sequence number and a timestamp. SampleObservation, EventObservation, and ConditionObservation in MTConnect.Observations.
AssetSomething a Device tracks that isn't an Observation, such as a cutting tool, a fixture, a file, raw material, or a pallet. Asset and its types in MTConnect.Assets.

Relationships link Components and DataItems to each other, and Agent Validation Events report input that fails validation.

Guides

Step-by-step recipes for the most common tasks, each ending with a check that it worked:

Examples

The examples/ directory of the repository has four console applications you can run with dotnet run:

  • Embedded Agent (examples/MTConnect.NET-Agent-Embedded): an Agent hosted in an application, which writes Observations to it directly. See Write an Agent.
  • HTTP Client (examples/MTConnect.NET-Client-HTTP): reads /probe and /current from an Agent and prints each Observation.
  • MQTT Client (examples/MTConnect.NET-Client-MQTT): subscribes to a broker that the MQTT Relay or MQTT Broker module publishes to. See Write a JSON-MQTT Consumer.
  • SHDR Client (examples/MTConnect.NET-Client-SHDR): connects to an SHDR adapter and prints each line it sends.
dotnet run --project examples/MTConnect.NET-Agent-Embedded
dotnet run --project examples/MTConnect.NET-Client-HTTP
dotnet run --project examples/MTConnect.NET-Client-MQTT
dotnet run --project examples/MTConnect.NET-Client-SHDR

Compliance

MTConnect.NET aims for complete compliance with every MTConnect version from 1.0 through 2.7. Every Streams, Devices, Assets, and Error document it writes validates against that version's XSD, and its JSON-CPPAGENT output matches the cppagent reference Agent byte for byte. The types are generated from the SysML model, which is the source of truth for each type's versions, controlled vocabularies, and constraints.

Command Line

  • Agent (mtconnect.net-agent): hosts the Agent and its modules, reads agent.config.yaml, and runs in a terminal, as a Windows Service, or as a systemd unit.
  • Adapter (mtconnect.net-adapter): sends data from a data source to one or more Agents, and reads adapter.config.yaml.

Tools for working on the repository itself (tools/test.sh, tools/dotnet.sh, the SysML importer, and the release builder) are documented for contributors in contributing/.

Reference

The Configuration Schema, HTTP API, Environment Variables, and CLI Reference pages are generated from the MTConnect.NET source, and tests in the repository check that they match the code. Each NuGet package's page on nuget.org links to its source and README.

MTConnect.NET is open source under the MIT License. The source code, issues, and releases are on GitHub.