🚀 MTConnect C++ Agent

A modern and extensible C++ implementation of the MTConnect standard, designed to reliably collect machine data from diverse industrial devices and expose it in a consistent, structured format. The agent normalizes raw device signals, ensures compliance with the MTConnect standard, and makes the data accessible to client applications such as MES systems, monitoring dashboards, analytics platforms, or custom integrations.

The agent supports multiple industrial communication models (SHDR, JSON, MQTT), multiple devices, secure network transport, and pluggable data transformation logic, making it suitable for both small installations and large-scale production environments.

📑 Table of Contents

Overview
Key Features
Architecture
Quick Start
Building From Source
Basic Configuration
Advanced Configuration
Sample Outputs
Directory Structure
Troubleshooting
Contributing
Version History
Useful Links
License

🧭 Overview

The MTConnect Agent acts as the intermediary between raw machine data and higher-level software systems that require structured, contextualized insights. It transforms messy, vendor-specific machine signals into clean, semantic MTConnect XML/JSON outputs. The agent follows a one-way, read-only information model, meaning it never sends instructions back to machines—making it safe and easy to integrate into existing manufacturing setups.

By handling multiple adapters, buffering high-frequency data, supporting secure communication, and offering real-time streaming capabilities, the agent is suitable for both small machine shops and enterprise-level Industry 4.0 deployments.

⭐ Key Features

🔌 Wide Input Support

SHDR adapters for CNC interoperability
MQTT ingestion for IoT environments
- Native JSON input for modern sensors and custom connectors
- Customizable JSON handling for propriatary models

🌐 Flexible Output Options

REST HTTP server for /probe, /current, /sample, and /assets APIs
WebSocket streaming for real-time dashboards
TLS support for secure communication
MQTT output using flattended or hierarchial topics

🧠 Extensibility

Ruby-based scripting for custom transformation pipelines
Modular components allowing custom inputs and outputs
XML Namespace support for extended functionality

⚙️ Industrial-Grade Infrastructure

High-performance store-and-forward buffering of data
Cross-platform support (Windows, Linux, and MacOS)
Low-overhead runtime for embedded or resource-constrained machines

🧱 Architecture

The agent transforms heterogeneous raw machine signals into structured, queryable MTConnect data streams. This architecture ensures consistent data modeling regardless of vendor or device type.

              ┌─────────────────────────┐
              │      Client Layer       │
              │  MES, Dashboards, Apps  │
              └──────────┬──────────────┘
                         │
            HTTP / WebSockets / TLS / MQTT
                         │
               ┌─────────┴───────────┐
               │   MTConnect Agent   │
               │   (C++ Reference)   │
               └─────┬────────┬──────┘
                     │        │
        Normalization &    Buffering
                     │
      ┌──────────────┴─────────────────┐
      │                                │
   SHDR Adapters                     MQTT Broker
      │                                │
Raw Machine Signals         Sensor/Device Messages

This architecture is designed to be modular, allowing organizations to gradually expand their MTConnect ecosystem without reconfiguring existing systems.

⚡ Quick Start

There are 2 ways to start using the CPP agent:

Using Pre-Built Binaries

This section helps developers get up and running with the agent in minutes.

1. Downloading Pre-Built Binaries

Pre-built binaries for Windows and Linux platforms are available on the Releases page.

2. Instructions for using Windows Binaries

Download the latest .zip release for Windows.
Extract the contents to a desired location.

3. Create a Minimal Configuration

Devices = Devices.xml
Port = 5000

Adapters {
  MyCNC {
    Host = localhost
    Port = 7878
  }
}

4. Run the Agent

C> agent.exe run agent.cfg

5. Verify Output

http://localhost:5000/probe
http://localhost:5000/current
http://localhost:5000/sample

Building From Source

Building from source requires cloning the repo and then using Docker commands.

To see the full process, check out the Wiki Page for Building From Source.

🔧 Basic Configuration

The agent is controlled via two primary files:

1. Devices.xml

Defines the machine structure, including components and DataItems. This file gives meaning to raw data received by adapters.

2. agent.cfg

Sets up communication ports, adapters, buffer sizes, logging, security, and optional features.

A minimal configuration looks like:

Example:

Devices = Devices.xml
Port = 5000
AllowPut = true
BufferSize = 17

⚠️ Warning: The BufferSize is specified in powers of 2. A value of 17 means $2^{17}$ = 131,072 slots.

🔧 Advanced Configuration

Overview of Advanced Features

Some capabilities of the agent require additional setup or are only needed in more complex environments. These include:

connecting multiple adapters to one or more devices
securing communication through TLS
ingesting MQTT-based data sources
applying custom logic using Ruby
enabling optional services like asset ingestion, data transforms, or extended namespaces

The following sections explain when and why you would use these features, along with short examples.

Multiple Adapters

The agent supports gathering data from multiple devices at the same time. Each device communicates using its own adapter defined by a host and port.

Use this when:

you want one agent instance to serve multiple machines,
you want to reduce infrastructure overhead,
machines are located on the same subnet or facility network.

Example:

Adapters {
  Mill1 {
    Host = 10.0.0.10
    Port = 7878
  }
  Lathe1 {
    Host = 10.0.0.20
    Port = 7879
  }
  Router {
    Host = router.local
    Port = 9000
  }
}

Each entry represents one physical machine producing SHDR output.

HTTP & TLS

HTTP is the standard protocol for MTConnect clients to retrieve data. TLS (HTTPS) is optional but recommended when:

data crosses network boundaries,
sensitive operation data must be encrypted,
compliance or security policies require secure transport.

TLS enables the agent to serve MTConnect data securely using certificates.

Example configuration:

TlsDefaults {
  PrivateKeyFile = server.key
  CertificateFile = server.crt
  VerifyClientCertificate = true
}

After configuration, the agent serves encrypted data over https://.

MQTT

The agent supports MQTT ingestion for devices or sensors that publish data to a broker instead of using SHDR.

Use MQTT when:

you have applications that already using MQTT
you want to publish data from a local broker to the cloud
you want a lightweight protocol for high-frequency data

The agent requires the broker address, topics, and connection details:

MqttService {
  Host = tcp://broker:1883
  Topics = factory/mtconnect/#
  ClientId = agent01
}

Additional message mapping rules may be needed depending on your topic structure and payload format.

Ruby Extensions

Ruby extensions allow you to customize how data is processed by the agent before it is exposed to clients. These scripts can:

normalize vendor-specific data formats,
apply mathematical transformations (e.g., unit conversions),
filter or enrich incoming data,
modify assets or samples before buffering,
implement custom logic not present in the MTConnect standard.

The agent loads Ruby scripts from the current directory:

Ruby {
  module = mymodule.rb
}

You can then write Ruby code that provides tranformation of the data in the pipeline.

SHDR (Simple Hierarchical Data Representation)

What SHDR Is

SHDR is the original MTConnect text-based protocol for transmitting machine state and data items. It streams information as timestamped key-value pairs over a plain TCP connection. It is simple, deterministic, and extremely reliable — which is why it continues to be the standard for CNC machine adapters.

Example SHDR line:

2025-05-01T10:24:31.123Z|Xpos|12.345

Why SHDR Exists

CNC controls and legacy equipment often cannot support modern protocols like MQTT or HTTP
SHDR provides a low-overhead, real-time stream that adapters can implement with minimal dependencies
It was intentionally created by MTConnect to reduce the complexity of machine data collection

When to Use SHDR

Choose SHDR if:

you are connecting to Fanuc, Mazak, Okuma, Haas, etc.
you need real-time telemetry with minimal latency and low overhead
you are using existing MTConnect adapters shipped with machine vendors

Alternatives

| Protocol | Best for | Notes | | -------- | ---------------------------------------- | ----------------------------------- | | SHDR | CNC & legacy equipment | Most common MTConnect adapter input | | MQTT | IoT sensors, PLC networks, mixed

Cppagent

Install / Use

README