# Overview

> Open source .NET libraries and applications for MTConnect: an Agent, an Adapter, and client libraries that support MTConnect v1.0 through v2.7.

URL: https://www.trakhound.com/docs/mtconnect-net

MTConnect.NET is an open source set of .NET libraries and applications that implement the [MTConnect Standard](https://www.mtconnect.org/) 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:

Diagram: SHDR adapters and HTTP adapters send data to the MTConnect.NET Agent. Inside the Agent, the input pipeline adds Observations to the sequence buffer, which answers Probe, Current, Sample, and Asset requests, and the Agent's modules serve them as XML documents, JSON-CPPAGENT v2 documents, and MQTT relay topics. Dashboards read XML, bridges read JSON-CPPAGENT, and historians subscribe to the MQTT topics.

## Explore the Docs

[Getting Started Install the Agent, configure a Device, and read its data in three steps.](https://www.trakhound.com/docs/mtconnect-net/getting-started) [Configure an Agent Every setting in agent.config.yaml, and the Devices.xml device model.](https://www.trakhound.com/docs/mtconnect-net/configure/agent-config) [Agent Modules HTTP, MQTT, and SHDR, and the Fanuc, Haas, and Tormach adapters.](https://www.trakhound.com/docs/mtconnect-net/modules) [Write an Agent Build an Agent into your own application with the NuGet packages.](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-an-agent) [Connect a Consumer Read data from an Agent over HTTP and MQTT, in .NET or Python.](https://www.trakhound.com/docs/mtconnect-net/configure/consumer) [Troubleshooting Common errors, and the fixes that work.](https://www.trakhound.com/docs/mtconnect-net/troubleshooting)

## 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](https://www.trakhound.com/docs/mtconnect-net/configure/install): the Agent and Adapter applications, the Docker image, and the NuGet packages, with notes for each target framework.
- [Configure an Agent](https://www.trakhound.com/docs/mtconnect-net/configure/agent-config): every key in `agent.config.yaml`, `Devices.xml`, module configuration, and logging.
- [Configure an Adapter](https://www.trakhound.com/docs/mtconnect-net/configure/adapter-config): SHDR and HTTP adapter configuration, ports, data sources, and queue and interval adapters.
- [Configure Modules](https://www.trakhound.com/docs/mtconnect-net/configure/module-config): the configuration keys of every included module.
- [Run](https://www.trakhound.com/docs/mtconnect-net/configure/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](https://www.trakhound.com/docs/mtconnect-net/configure/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](https://www.trakhound.com/docs/mtconnect-net/configure/operate): logs, metrics, recovering from errors, and backing up the Agent's storage.
- [Integrations](https://www.trakhound.com/docs/mtconnect-net/configure/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:

| Concept | Description |
| --- | --- |
| **[Device](https://www.trakhound.com/docs/mtconnect-net/concepts/devices)** | The 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`. |
| **[Component](https://www.trakhound.com/docs/mtconnect-net/concepts/devices#components)** | A 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`. |
| **[DataItem](https://www.trakhound.com/docs/mtconnect-net/concepts/data-items)** | A 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`. |
| **[Observation](https://www.trakhound.com/docs/mtconnect-net/concepts/data-items#observations)** | A value of a DataItem at a point in time, with a `sequence` number and a `timestamp`. `SampleObservation`, `EventObservation`, and `ConditionObservation` in `MTConnect.Observations`. |
| **[Asset](https://www.trakhound.com/docs/mtconnect-net/concepts/assets)** | Something 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](https://www.trakhound.com/docs/mtconnect-net/concepts/relationships) link Components and DataItems to each other, and [Agent Validation Events](https://www.trakhound.com/docs/mtconnect-net/concepts/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:

- [Write an Agent](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-an-agent): build a Device model in code, add Observations, and serve `/probe`, `/current`, and `/sample`, or [embed an Agent](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-an-agent#embedded-agent) in your own application.
- [Write an Adapter](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-an-adapter): choose the `ShdrAdapter` type that matches how your data arrives, and send values to an Agent.
- [Write an Agent Module](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-a-module): send the Agent's data to a destination the included modules don't cover.
- [Configure the MQTT Relay](https://www.trakhound.com/docs/mtconnect-net/cookbook/configure-mqtt-relay) and [Write a JSON-MQTT Consumer](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-a-json-mqtt-consumer): publish an Agent's data to a broker, and read it in .NET or Python.
- [Migrate between MTConnect Versions](https://www.trakhound.com/docs/mtconnect-net/cookbook/migrate-versions) and [Upgrade to v7](https://www.trakhound.com/docs/mtconnect-net/migration/v7-validation-result).

## Examples

The [`examples/`](https://github.com/TrakHound/MTConnect.NET/tree/master/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](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-an-agent#embedded-agent).
- **[HTTP Client](https://www.trakhound.com/docs/mtconnect-net/examples/client-http)** (`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](https://www.trakhound.com/docs/mtconnect-net/cookbook/write-a-json-mqtt-consumer#use-the-built-in-mqtt-client).
- **[SHDR Client](https://www.trakhound.com/docs/mtconnect-net/examples/client-shdr)** (`examples/MTConnect.NET-Client-SHDR`): connects to an SHDR adapter and prints each line it sends.

```sh
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.

- [Compliance by Version](https://www.trakhound.com/docs/mtconnect-net/compliance/per-version-matrix): the supported versions and wire formats, and how each is validated.
- [Known Divergences](https://www.trakhound.com/docs/mtconnect-net/compliance/known-divergences): where the SysML model, XSDs, prose, and cppagent disagree, which one MTConnect.NET follows, and the tickets filed upstream.
- For contributors, the [compliance test harness](https://github.com/TrakHound/MTConnect.NET/blob/master/contributing/compliance/test-harness.md) and the [cross-references to the Standard](https://github.com/TrakHound/MTConnect.NET/blob/master/contributing/compliance/spec-cross-references.md) are in the repository.

## Command Line

- [Agent](https://www.trakhound.com/docs/mtconnect-net/cli/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](https://www.trakhound.com/docs/mtconnect-net/cli/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/`](https://github.com/TrakHound/MTConnect.NET/tree/master/contributing).

## Reference

The [Configuration Schema](https://www.trakhound.com/docs/mtconnect-net/reference/configuration), [HTTP API](https://www.trakhound.com/docs/mtconnect-net/reference/http-api), [Environment Variables](https://www.trakhound.com/docs/mtconnect-net/reference/environment-variables), and [CLI Reference](https://www.trakhound.com/docs/mtconnect-net/reference/cli) 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](https://www.nuget.org/profiles/TrakHound) links to its source and README.

> MTConnect.NET is open source under the MIT License. The source code, issues, and releases are on [GitHub](https://github.com/TrakHound/MTConnect.NET).
