From 78374d17cbe357fe01477375d302fb783efad0b2 Mon Sep 17 00:00:00 2001 From: ayush2390 Date: Mon, 8 Jun 2026 18:55:55 +0530 Subject: [PATCH 1/2] Update documentation --- Downloads/mtc/concepts/architecture.mdx | 27 ++++++ Downloads/mtc/concepts/assets.mdx | 10 +++ Downloads/mtc/concepts/data-items.mdx | 26 ++++++ .../mtc/concepts/devices-and-adapters.mdx | 30 +++++++ .../mtc/concepts/streams-and-samples.mdx | 20 +++++ Downloads/mtc/docs.json | 84 +++++++++++++++++++ Downloads/mtc/favicon.svg | 5 ++ .../mtc/getting-started/installation.mdx | 49 +++++++++++ Downloads/mtc/getting-started/quickstart.mdx | 43 ++++++++++ Downloads/mtc/index.mdx | 49 +++++++++++ Downloads/mtc/reference/changelog.mdx | 23 +++++ Downloads/mtc/reference/data-model.mdx | 6 ++ Downloads/mtc/reference/xml-schema.mdx | 13 +++ Downloads/mtc/tutorials/building-a-client.mdx | 25 ++++++ Downloads/mtc/tutorials/code-examples.mdx | 43 ++++++++++ .../mtc/tutorials/writing-an-adapter.mdx | 30 +++++++ 16 files changed, 483 insertions(+) create mode 100644 Downloads/mtc/concepts/architecture.mdx create mode 100644 Downloads/mtc/concepts/assets.mdx create mode 100644 Downloads/mtc/concepts/data-items.mdx create mode 100644 Downloads/mtc/concepts/devices-and-adapters.mdx create mode 100644 Downloads/mtc/concepts/streams-and-samples.mdx create mode 100644 Downloads/mtc/docs.json create mode 100644 Downloads/mtc/favicon.svg create mode 100644 Downloads/mtc/getting-started/installation.mdx create mode 100644 Downloads/mtc/getting-started/quickstart.mdx create mode 100644 Downloads/mtc/index.mdx create mode 100644 Downloads/mtc/reference/changelog.mdx create mode 100644 Downloads/mtc/reference/data-model.mdx create mode 100644 Downloads/mtc/reference/xml-schema.mdx create mode 100644 Downloads/mtc/tutorials/building-a-client.mdx create mode 100644 Downloads/mtc/tutorials/code-examples.mdx create mode 100644 Downloads/mtc/tutorials/writing-an-adapter.mdx diff --git a/Downloads/mtc/concepts/architecture.mdx b/Downloads/mtc/concepts/architecture.mdx new file mode 100644 index 0000000..e21d15a --- /dev/null +++ b/Downloads/mtc/concepts/architecture.mdx @@ -0,0 +1,27 @@ +--- +title: "Architecture" +description: "MTConnect uses a three-tier architecture: Device → Adapter → Agent → Client." +--- + +MTConnect uses a three-tier architecture: **Device → Adapter → Agent → Client**. + +## The Agent + +The Agent is the central hub. It accepts data from one or more adapters over TCP, buffers it in a circular buffer, and serves it to clients over HTTP. The reference implementation is the open-source [C++ Agent](https://github.com/mtconnect/cppagent). + +## Adapters (SHDR Protocol) + +Adapters connect machines to the Agent using the Simple Hierarchical Data Representation (SHDR) protocol over a TCP socket. Each line is a pipe-delimited string: + +``` +2024-01-15T10:23:45.000Z|Smode|AUTOMATIC +2024-01-15T10:23:45.001Z|S1speed|3500.0 +2024-01-15T10:23:45.001Z|path_pos|100.5|200.3|0.0 +``` + +## HTTP Endpoints + +- `GET /probe` — device structure and metadata +- `GET /current` — latest snapshot of all data items +- `GET /sample` — sequence of observations from the buffer +- `GET /assets` — retrieve assets (e.g. cutting tools) diff --git a/Downloads/mtc/concepts/assets.mdx b/Downloads/mtc/concepts/assets.mdx new file mode 100644 index 0000000..dbe150a --- /dev/null +++ b/Downloads/mtc/concepts/assets.mdx @@ -0,0 +1,10 @@ +--- +title: "Assets" +description: "MTConnect Assets are complex, mutable objects associated with a device. The most common type is CuttingTool." +--- + +MTConnect Assets are complex, mutable objects associated with a device. The most common asset type is `CuttingTool`, describing tool geometry and life cycle. + + + Browse the full CuttingTool schema at [model.mtconnect.org](https://model.mtconnect.org/). + diff --git a/Downloads/mtc/concepts/data-items.mdx b/Downloads/mtc/concepts/data-items.mdx new file mode 100644 index 0000000..8e8a820 --- /dev/null +++ b/Downloads/mtc/concepts/data-items.mdx @@ -0,0 +1,26 @@ +--- +title: "Data Items" +description: "Data Items are the atomic units of information in MTConnect. Each has a type, category, and optional subType." +--- + +Data Items are the atomic units of information in MTConnect. Each data item has a `type`, `category`, and optional `subType`. + +## Categories + +- **SAMPLE** — continuous numeric measurements (position, speed, temperature) +- **EVENT** — discrete state changes (execution mode, program name) +- **CONDITION** — fault/warning/normal states + +## Common Types + +``` +POSITION — axis or path position (SAMPLE) +VELOCITY — axis velocity (SAMPLE) +SPINDLE_SPEED — rotational speed (SAMPLE) +EXECUTION — program state (EVENT) +AVAILABILITY — device available/unavailable (EVENT) +PATH_FEEDRATE — feed rate (SAMPLE) +TEMPERATURE — thermal measurement (SAMPLE) +TOOL_ASSET_ID — active tool identifier (EVENT) +PART_COUNT — parts produced (EVENT) +``` diff --git a/Downloads/mtc/concepts/devices-and-adapters.mdx b/Downloads/mtc/concepts/devices-and-adapters.mdx new file mode 100644 index 0000000..02a28d7 --- /dev/null +++ b/Downloads/mtc/concepts/devices-and-adapters.mdx @@ -0,0 +1,30 @@ +--- +title: "Devices & Adapters" +description: "An MTConnect Device represents a physical or logical manufacturing asset described in the Device Information Model." +--- + +An MTConnect **Device** represents a physical or logical manufacturing asset. Each device is described in the Agent's Device Information Model (DIM) — an XML document served at `/probe`. + +## Device Structure + +```xml XML — Device probe response (excerpt) + + + + + + + + + + + + + + + +``` + +## Writing an Adapter + +See the [Writing an Adapter](/tutorials/writing-an-adapter) tutorial for a step-by-step walkthrough. diff --git a/Downloads/mtc/concepts/streams-and-samples.mdx b/Downloads/mtc/concepts/streams-and-samples.mdx new file mode 100644 index 0000000..6e9005b --- /dev/null +++ b/Downloads/mtc/concepts/streams-and-samples.mdx @@ -0,0 +1,20 @@ +--- +title: "Streams & Samples" +description: "The /sample endpoint streams observations from the Agent's circular buffer. Each observation has a sequence number and timestamp." +--- + +The `/sample` endpoint streams observations from the Agent's circular buffer. Each observation has a sequence number and timestamp. + +## Polling for New Data + +```python +import requests, time + +BASE = "http://localhost:5000" +last_seq = 0 + +while True: + r = requests.get(f"{BASE}/sample?from={last_seq}&count=100") + # parse XML, update last_seq from nextSequence attribute + time.sleep(0.5) +``` diff --git a/Downloads/mtc/docs.json b/Downloads/mtc/docs.json new file mode 100644 index 0000000..422d3f9 --- /dev/null +++ b/Downloads/mtc/docs.json @@ -0,0 +1,84 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "MTConnect", + "colors": { + "primary": "#1D4ED8", + "light": "#3B82F6", + "dark": "#0D2040" + }, + "favicon": "/favicon.svg", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "navbar": { + "links": [ + { "label": "Model Browser", "href": "https://model.mtconnect.org/" }, + { "label": "GitHub", "href": "https://github.com/mtconnect" }, + { "label": "Slack", "href": "https://mtconnect.slack.com/" } + ], + "primary": { + "type": "button", + "label": "MTConnect.org", + "href": "https://www.mtconnect.org" + } + }, + "navigation": { + "groups": [ + { + "group": "Getting Started", + "pages": [ + "index", + "getting-started/quickstart", + "getting-started/installation" + ] + }, + { + "group": "Core Concepts", + "pages": [ + "concepts/architecture", + "concepts/devices-and-adapters", + "concepts/data-items", + "concepts/streams-and-samples", + "concepts/assets" + ] + }, + { + "group": "Tutorials", + "pages": [ + "tutorials/writing-an-adapter", + "tutorials/building-a-client", + "tutorials/code-examples" + ] + }, + { + "group": "Reference", + "pages": [ + "reference/data-model", + "reference/xml-schema", + "reference/changelog" + ] + } + ], + "global": { + "anchors": [ + { + "anchor": "Model Browser", + "href": "https://model.mtconnect.org", + "icon": "globe" + }, + { + "anchor": "GitHub", + "href": "https://github.com/mtconnect", + "icon": "github" + } + ] + } + }, + "footer": { + "socials": { + "github": "https://github.com/mtconnect" + } + } +} diff --git a/Downloads/mtc/favicon.svg b/Downloads/mtc/favicon.svg new file mode 100644 index 0000000..d50ceed --- /dev/null +++ b/Downloads/mtc/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/Downloads/mtc/getting-started/installation.mdx b/Downloads/mtc/getting-started/installation.mdx new file mode 100644 index 0000000..56b3b1a --- /dev/null +++ b/Downloads/mtc/getting-started/installation.mdx @@ -0,0 +1,49 @@ +--- +title: "Installation" +description: "MTConnect agents can be run via Docker (recommended), built from source, or installed via OS packages." +--- + +MTConnect agents can be run via Docker (recommended), built from source, or installed via OS packages. + +## Docker (Recommended) + +```bash +docker pull mtconnect/agent:latest +docker run -p 5000:5000 mtconnect/agent:latest +``` + +## Build from Source + + + + ```bash + sudo apt install cmake libxml2-dev + git clone https://github.com/mtconnect/cppagent.git + cd cppagent && cmake -S . -B build && cmake --build build -j$(nproc) + sudo cmake --install build + ``` + + + ```bash + brew install cmake libxml2 + git clone https://github.com/mtconnect/cppagent.git + cd cppagent && cmake -S . -B build && cmake --build build + ``` + + + ```bash + # Visual Studio 2022 + git clone https://github.com/mtconnect/cppagent.git + cd cppagent + cmake -S . -B build -G "Visual Studio 17 2022" + cmake --build build --config Release + ``` + + + +## Verify + +```bash +curl http://localhost:5000/probe +# Returns MTConnect XML with device descriptions +``` diff --git a/Downloads/mtc/getting-started/quickstart.mdx b/Downloads/mtc/getting-started/quickstart.mdx new file mode 100644 index 0000000..4d829f9 --- /dev/null +++ b/Downloads/mtc/getting-started/quickstart.mdx @@ -0,0 +1,43 @@ +--- +title: "Quickstart" +description: "The fastest way to get an MTConnect Agent running. You'll have live XML data in under 5 minutes." +--- + +5 min read + +The fastest way to get an MTConnect Agent running is with Docker. You'll have live XML data in under 5 minutes. + +## 1. Run the Agent with Docker + +```bash +docker run -it --rm -p 5000:5000 \ + mtconnect/agent:latest +``` + +The agent starts with a built-in simulator device. Open your browser to verify: + +```bash +curl http://localhost:5000/probe +``` + +## 2. Your First Client (Python) + +```python +import requests +import xml.etree.ElementTree as ET + +BASE = "http://localhost:5000" + +# Discover devices +probe = requests.get(f"{BASE}/probe") +root = ET.fromstring(probe.text) +print("Connected to MTConnect Agent") + +# Read current values +current = requests.get(f"{BASE}/current") +print(current.text[:500]) +``` + + + See the [Examples page](/tutorials/code-examples) for complete working code in Python, JavaScript, and C#. + diff --git a/Downloads/mtc/index.mdx b/Downloads/mtc/index.mdx new file mode 100644 index 0000000..fac4275 --- /dev/null +++ b/Downloads/mtc/index.mdx @@ -0,0 +1,49 @@ +--- +title: "What is MTConnect?" +description: "An open, royalty-free standard that defines a semantic vocabulary for manufacturing equipment data." +--- + +
+ Stable + v2.2 +
+ +MTConnect is an open, royalty-free standard (ANSI/MTC1.4-2018) that defines a semantic vocabulary for manufacturing equipment data. It gives machines a common language so any application can read data from any compliant device — without proprietary adapters or vendor lock-in. + + + MTConnect is used on **250,000+ devices** across **50+ countries**, developed by over 500 machine builders and integrators. + + +## Key Capabilities + + + + Stream live machine data over standard HTTP + + + Agent + Adapter pattern, works with any language + + + Shared vocabulary for 1000s of data item types + + + Python, JavaScript, C# — ready to run + + + +## How It Works + +The MTConnect architecture has three layers: + +1. **Machine / Device** — CNC machines, robots, sensors generating raw data +2. **Adapter** — translates machine signals into the SHDR protocol +3. **Agent** — normalizes data and serves it over HTTP as structured XML + +Client applications call the Agent's HTTP endpoints (`/probe`, `/current`, `/sample`) to discover devices, read current values, or stream historical data. + +## Supported Versions + +- **v2.2** (current) — CuttingTool enhancements, additive manufacturing types +- **v2.1** — Component relationships, Specifications data items +- **v2.0** — Device Relationships, Interface components +- **v1.x** — Legacy, still widely deployed diff --git a/Downloads/mtc/reference/changelog.mdx b/Downloads/mtc/reference/changelog.mdx new file mode 100644 index 0000000..3b866b9 --- /dev/null +++ b/Downloads/mtc/reference/changelog.mdx @@ -0,0 +1,23 @@ +--- +title: "Changelog" +description: "MTConnect standard version history." +mode: "center" +--- + +## v2.2 — 2023 + +- CuttingTool asset enhancements +- Part tracking improvements +- New DataItem types for additive manufacturing + +## v2.1 — 2022 + +- Relationships between components +- Specifications data items +- Improved streaming performance + +## v2.0 — 2021 + +- Device Relationships +- Interface components +- Structural component types diff --git a/Downloads/mtc/reference/data-model.mdx b/Downloads/mtc/reference/data-model.mdx new file mode 100644 index 0000000..80a5b4a --- /dev/null +++ b/Downloads/mtc/reference/data-model.mdx @@ -0,0 +1,6 @@ +--- +title: "Data Model Reference" +description: "The MTConnect information model defines a semantic vocabulary for manufacturing data." +--- + +The MTConnect information model defines a semantic vocabulary for manufacturing data. Browse the complete model at [model.mtconnect.org](https://model.mtconnect.org/). diff --git a/Downloads/mtc/reference/xml-schema.mdx b/Downloads/mtc/reference/xml-schema.mdx new file mode 100644 index 0000000..cda7e91 --- /dev/null +++ b/Downloads/mtc/reference/xml-schema.mdx @@ -0,0 +1,13 @@ +--- +title: "XML Schema" +description: "MTConnect XML schemas validate documents against the standard." +--- + +MTConnect XML schemas validate documents against the standard. + +``` +https://schemas.mtconnect.org/schemas/MTConnectDevices_2.2.xsd +https://schemas.mtconnect.org/schemas/MTConnectStreams_2.2.xsd +https://schemas.mtconnect.org/schemas/MTConnectAssets_2.2.xsd +https://schemas.mtconnect.org/schemas/MTConnectError_2.2.xsd +``` diff --git a/Downloads/mtc/tutorials/building-a-client.mdx b/Downloads/mtc/tutorials/building-a-client.mdx new file mode 100644 index 0000000..ea7a18d --- /dev/null +++ b/Downloads/mtc/tutorials/building-a-client.mdx @@ -0,0 +1,25 @@ +--- +title: "Tutorial: Building a Client" +description: "An MTConnect client is any application that consumes data from an Agent via HTTP." +--- + +An MTConnect client is any application that consumes data from an Agent via HTTP. Here's a complete Python client. + +```python client.py +import requests +import xml.etree.ElementTree as ET + +BASE = "http://localhost:5000" +NS = {"m": "urn:mtconnect.org:MTConnectStreams:2.0"} + +def get_current(): + r = requests.get(f"{BASE}/current") + root = ET.fromstring(r.text) + items = root.findall(".//m:DataItem", NS) + return {item.get("dataItemId"): item.text for item in items} + +if __name__ == "__main__": + data = get_current() + for key, val in data.items(): + print(f" {key}: {val}") +``` diff --git a/Downloads/mtc/tutorials/code-examples.mdx b/Downloads/mtc/tutorials/code-examples.mdx new file mode 100644 index 0000000..af460dd --- /dev/null +++ b/Downloads/mtc/tutorials/code-examples.mdx @@ -0,0 +1,43 @@ +--- +title: "Code Examples" +description: "Complete, runnable examples in multiple languages." +--- + +Complete, runnable examples in multiple languages. + + + + ```python + import requests, xml.etree.ElementTree as ET + + r = requests.get("http://localhost:5000/current") + root = ET.fromstring(r.text) + for item in root.iter(): + if item.text and item.get("dataItemId"): + print(f"{item.get('dataItemId')}: {item.text}") + ``` + + + ```javascript + const res = await fetch('http://localhost:5000/current'); + const text = await res.text(); + const parser = new DOMParser(); + const xml = parser.parseFromString(text, 'text/xml'); + xml.querySelectorAll('[dataItemId]').forEach(el => { + console.log(el.getAttribute('dataItemId'), el.textContent); + }); + ``` + + + ```csharp + using System.Net.Http; + using System.Xml.Linq; + + var client = new HttpClient(); + var xml = await client.GetStringAsync("http://localhost:5000/current"); + var doc = XDocument.Parse(xml); + foreach (var item in doc.Descendants().Where(e => e.Attribute("dataItemId") != null)) + Console.WriteLine($"{item.Attribute("dataItemId")!.Value}: {item.Value}"); + ``` + + diff --git a/Downloads/mtc/tutorials/writing-an-adapter.mdx b/Downloads/mtc/tutorials/writing-an-adapter.mdx new file mode 100644 index 0000000..0388617 --- /dev/null +++ b/Downloads/mtc/tutorials/writing-an-adapter.mdx @@ -0,0 +1,30 @@ +--- +title: "Tutorial: Writing an Adapter" +description: "An adapter connects a machine to an MTConnect Agent using the SHDR protocol over a TCP socket." +--- + +An adapter connects a machine to an MTConnect Agent using the SHDR protocol over a TCP socket. Here's a complete Python adapter for a simulated CNC machine. + +```python simple_adapter.py +import socket, time, random, datetime + +AGENT_HOST = "localhost" +AGENT_PORT = 7878 + +def timestamp(): + return datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" + +def shdr(key, value): + return f"{timestamp()}|{key}|{value}\n" + +with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + s.connect((AGENT_HOST, AGENT_PORT)) + print(f"Connected to agent at {AGENT_HOST}:{AGENT_PORT}") + while True: + speed = round(random.uniform(2800, 3200), 1) + x_pos = round(random.uniform(-100, 100), 3) + s.sendall(shdr("S1speed", speed).encode()) + s.sendall(shdr("Xpos", x_pos).encode()) + s.sendall(shdr("Smode", "AUTOMATIC").encode()) + time.sleep(0.5) +``` From a830a96834fb516e356f0e5a14b1af3a2ede6580 Mon Sep 17 00:00:00 2001 From: Ayush Thakur Date: Tue, 9 Jun 2026 19:09:40 +0530 Subject: [PATCH 2/2] Corrected the Mtconnect github versions --- .DS_Store | Bin 0 -> 6148 bytes concepts/architecture.mdx | 28 ++++++ concepts/assets.mdx | 11 +++ concepts/data-items.mdx | 27 ++++++ concepts/devices-and-adapters.mdx | 31 +++++++ concepts/streams-and-samples.mdx | 21 +++++ docs.json | 100 ++++++++++++++++++++ favicon.svg | 5 + getting-started/installation.mdx | 50 ++++++++++ getting-started/quickstart.mdx | 44 +++++++++ index.mdx | 59 ++++++++++++ logo/logo.svg | 146 ++++++++++++++++++++++++++++++ reference/changelog.mdx | 83 +++++++++++++++++ reference/data-model.mdx | 7 ++ reference/xml-schema.mdx | 14 +++ tutorials/building-a-client.mdx | 26 ++++++ tutorials/code-examples.mdx | 44 +++++++++ tutorials/writing-an-adapter.mdx | 31 +++++++ 18 files changed, 727 insertions(+) create mode 100644 .DS_Store create mode 100644 concepts/architecture.mdx create mode 100644 concepts/assets.mdx create mode 100644 concepts/data-items.mdx create mode 100644 concepts/devices-and-adapters.mdx create mode 100644 concepts/streams-and-samples.mdx create mode 100644 docs.json create mode 100644 favicon.svg create mode 100644 getting-started/installation.mdx create mode 100644 getting-started/quickstart.mdx create mode 100644 index.mdx create mode 100644 logo/logo.svg create mode 100644 reference/changelog.mdx create mode 100644 reference/data-model.mdx create mode 100644 reference/xml-schema.mdx create mode 100644 tutorials/building-a-client.mdx create mode 100644 tutorials/code-examples.mdx create mode 100644 tutorials/writing-an-adapter.mdx diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..b355d7ba6e1feb6b56c0d2329ac71164ee31c57d GIT binary patch literal 6148 zcmeHKL2uJA6n^dsOQ;Y%fV5)-*HXF-CQV$TG7ek`f&-w^G@%5txN6dNQdOzv?Zyw_ zM{weo@OR*Qwznne;D`|TRrcpRzc02wJ9bS(qCbmviP}WuATc&?AiKi2p3{akjHd+@ z>K!pnsG$5=Dn}d9)?pQ}3jA#f@VD#Gh$LmmOW$vp$`EzDF?>bp{!oSzkxLQcN0d{S zJ|YK~zxYdrxLaei=sgW-PKjx$3)Y;*HP+`E>lTgCqXNGKy&KbgunN3qiae&M%5Ly( zRP80RB1E2`pT{Vj)ELtmqe&^oGA3D#Q=|D(8vjLHxX34F)ZfBMn&d^V_gyr$n%Ayx zJKIjnc^iC?i=Y@5v%Ei?zUHSFQl{Z~c^JM-;>DnS`-#koVUopDMM$C;A#YwKStJ*I zIm@D4aRXi9xQ;t$?<|+QdxstG;iLUk$6Frm^-$hFSgl;=&bs47E!M3t3sF*7qH2}XjMO7&TAxiZvR zDl@vY{QWFbr@lJj*=Pm6jlRvOe1mI^nodHsjQ5z9g}I>! z)jIs13Mb)fw7FHlDo|BmOFy>x{D1oE`+t>WpR58_fqzN?(L4%{_$p`4){VjOS?eLa rLt^8&wMIojW{zW3;G=j4Ng3)qE&zRlYmM;0>>mLogUzf0e^h~=k6hEg literal 0 HcmV?d00001 diff --git a/concepts/architecture.mdx b/concepts/architecture.mdx new file mode 100644 index 0000000..0fd7330 --- /dev/null +++ b/concepts/architecture.mdx @@ -0,0 +1,28 @@ +--- +title: "Architecture" +description: "MTConnect uses a three-tier architecture: Device → Adapter → Agent → Client." +icon: "diagram-project" +--- + +MTConnect uses a three-tier architecture: **Device → Adapter → Agent → Client**. + +## The Agent + +The Agent is the central hub. It accepts data from one or more adapters over TCP, buffers it in a circular buffer, and serves it to clients over HTTP. The reference implementation is the open-source [C++ Agent](https://github.com/mtconnect/cppagent). + +## Adapters (SHDR Protocol) + +Adapters connect machines to the Agent using the Simple Hierarchical Data Representation (SHDR) protocol over a TCP socket. Each line is a pipe-delimited string: + +``` +2024-01-15T10:23:45.000Z|Smode|AUTOMATIC +2024-01-15T10:23:45.001Z|S1speed|3500.0 +2024-01-15T10:23:45.001Z|path_pos|100.5|200.3|0.0 +``` + +## HTTP Endpoints + +- `GET /probe` — device structure and metadata +- `GET /current` — latest snapshot of all data items +- `GET /sample` — sequence of observations from the buffer +- `GET /assets` — retrieve assets (e.g. cutting tools) diff --git a/concepts/assets.mdx b/concepts/assets.mdx new file mode 100644 index 0000000..10bdc29 --- /dev/null +++ b/concepts/assets.mdx @@ -0,0 +1,11 @@ +--- +title: "Assets" +description: "MTConnect Assets are complex, mutable objects associated with a device. The most common type is CuttingTool." +icon: "box" +--- + +MTConnect Assets are complex, mutable objects associated with a device. The most common asset type is `CuttingTool`, describing tool geometry and life cycle. + + + Browse the full CuttingTool schema at [model.mtconnect.org](https://model.mtconnect.org/). + diff --git a/concepts/data-items.mdx b/concepts/data-items.mdx new file mode 100644 index 0000000..073d706 --- /dev/null +++ b/concepts/data-items.mdx @@ -0,0 +1,27 @@ +--- +title: "Data Items" +description: "Data Items are the atomic units of information in MTConnect. Each has a type, category, and optional subType." +icon: "database" +--- + +Data Items are the atomic units of information in MTConnect. Each data item has a `type`, `category`, and optional `subType`. + +## Categories + +- **SAMPLE** — continuous numeric measurements (position, speed, temperature) +- **EVENT** — discrete state changes (execution mode, program name) +- **CONDITION** — fault/warning/normal states + +## Common Types + +``` +POSITION — axis or path position (SAMPLE) +VELOCITY — axis velocity (SAMPLE) +SPINDLE_SPEED — rotational speed (SAMPLE) +EXECUTION — program state (EVENT) +AVAILABILITY — device available/unavailable (EVENT) +PATH_FEEDRATE — feed rate (SAMPLE) +TEMPERATURE — thermal measurement (SAMPLE) +TOOL_ASSET_ID — active tool identifier (EVENT) +PART_COUNT — parts produced (EVENT) +``` diff --git a/concepts/devices-and-adapters.mdx b/concepts/devices-and-adapters.mdx new file mode 100644 index 0000000..be1a7cb --- /dev/null +++ b/concepts/devices-and-adapters.mdx @@ -0,0 +1,31 @@ +--- +title: "Devices & Adapters" +description: "An MTConnect Device represents a physical or logical manufacturing asset described in the Device Information Model." +icon: "server" +--- + +An MTConnect **Device** represents a physical or logical manufacturing asset. Each device is described in the Agent's Device Information Model (DIM) — an XML document served at `/probe`. + +## Device Structure + +```xml XML — Device probe response (excerpt) + + + + + + + + + + + + + + + +``` + +## Writing an Adapter + +See the [Writing an Adapter](/tutorials/writing-an-adapter) tutorial for a step-by-step walkthrough. diff --git a/concepts/streams-and-samples.mdx b/concepts/streams-and-samples.mdx new file mode 100644 index 0000000..af6f8ee --- /dev/null +++ b/concepts/streams-and-samples.mdx @@ -0,0 +1,21 @@ +--- +title: "Streams & Samples" +description: "The /sample endpoint streams observations from the Agent's circular buffer." +icon: "wave-square" +--- + +The `/sample` endpoint streams observations from the Agent's circular buffer. Each observation has a sequence number and timestamp. + +## Polling for New Data + +```python +import requests, time + +BASE = "http://localhost:5000" +last_seq = 0 + +while True: + r = requests.get(f"{BASE}/sample?from={last_seq}&count=100") + # parse XML, update last_seq from nextSequence attribute + time.sleep(0.5) +``` diff --git a/docs.json b/docs.json new file mode 100644 index 0000000..d73cca2 --- /dev/null +++ b/docs.json @@ -0,0 +1,100 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "maple", + "name": "MTConnect", + "colors": { + "primary": "#1D4ED8", + "light": "#3B82F6", + "dark": "#0D2040" + }, + "favicon": "/favicon.svg", + "logo": { + "light": "/logo/logo.svg", + "dark": "/logo/logo.svg" + }, + "icons": { + "library": "lucide" + }, + "navbar": { + "links": [ + { "label": "Model Browser", "href": "https://model.mtconnect.org/" }, + { "label": "GitHub", "href": "https://github.com/mtconnect" }, + { "label": "Slack", "href": "https://mtconnect.slack.com/" } + ], + "primary": { + "type": "button", + "label": "MTConnect.org", + "href": "https://www.mtconnect.org" + } + }, + "navigation": { + "groups": [ + { + "group": "Getting Started", + "icon": "rocket", + "pages": [ + "index", + "getting-started/quickstart", + "getting-started/installation" + ] + }, + { + "group": "Core Concepts", + "icon": "book-open", + "pages": [ + "concepts/architecture", + "concepts/devices-and-adapters", + "concepts/data-items", + "concepts/streams-and-samples", + "concepts/assets" + ] + }, + { + "group": "Tutorials", + "icon": "graduation-cap", + "pages": [ + "tutorials/writing-an-adapter", + "tutorials/building-a-client", + "tutorials/code-examples" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "reference/data-model", + "reference/xml-schema", + "reference/changelog" + ] + } + ], + "global": { + "anchors": [ + { + "anchor": "Model Browser", + "href": "https://model.mtconnect.org", + "icon": "globe" + }, + { + "anchor": "GitHub", + "href": "https://github.com/mtconnect", + "icon": "github" + }, + { + "anchor": "Community Slack", + "href": "https://mtconnect.slack.com", + "icon": "slack" + } + ] + } + }, + "contextual": { + "options": ["copy", "view", "chatgpt", "claude"] + }, + "footer": { + "socials": { + "github": "https://github.com/mtconnect", + "linkedin": "https://linkedin.com/company/mtconnect" + } + } +} diff --git a/favicon.svg b/favicon.svg new file mode 100644 index 0000000..d50ceed --- /dev/null +++ b/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/getting-started/installation.mdx b/getting-started/installation.mdx new file mode 100644 index 0000000..6126ab0 --- /dev/null +++ b/getting-started/installation.mdx @@ -0,0 +1,50 @@ +--- +title: "Installation" +description: "Run via Docker (recommended), build from source, or install via OS packages." +icon: "download" +--- + +MTConnect agents can be run via Docker (recommended), built from source, or installed via OS packages. + +## Docker (Recommended) + +```bash +docker pull mtconnect/agent:latest +docker run -p 5000:5000 mtconnect/agent:latest +``` + +## Build from Source + + + + ```bash + sudo apt install cmake libxml2-dev + git clone https://github.com/mtconnect/cppagent.git + cd cppagent && cmake -S . -B build && cmake --build build -j$(nproc) + sudo cmake --install build + ``` + + + ```bash + brew install cmake libxml2 + git clone https://github.com/mtconnect/cppagent.git + cd cppagent && cmake -S . -B build && cmake --build build + ``` + + + ```bash + # Visual Studio 2022 + git clone https://github.com/mtconnect/cppagent.git + cd cppagent + cmake -S . -B build -G "Visual Studio 17 2022" + cmake --build build --config Release + ``` + + + +## Verify + +```bash +curl http://localhost:5000/probe +# Returns MTConnect XML with device descriptions +``` diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx new file mode 100644 index 0000000..94a5e1e --- /dev/null +++ b/getting-started/quickstart.mdx @@ -0,0 +1,44 @@ +--- +title: "Quickstart" +description: "The fastest way to get an MTConnect Agent running. You'll have live XML data in under 5 minutes." +icon: "rocket" +--- + +5 min read + +The fastest way to get an MTConnect Agent running is with Docker. You'll have live XML data in under 5 minutes. + +## 1. Run the Agent with Docker + +```bash +docker run -it --rm -p 5000:5000 \ + mtconnect/agent:latest +``` + +The agent starts with a built-in simulator device. Open your browser to verify: + +```bash +curl http://localhost:5000/probe +``` + +## 2. Your First Client (Python) + +```python +import requests +import xml.etree.ElementTree as ET + +BASE = "http://localhost:5000" + +# Discover devices +probe = requests.get(f"{BASE}/probe") +root = ET.fromstring(probe.text) +print("Connected to MTConnect Agent") + +# Read current values +current = requests.get(f"{BASE}/current") +print(current.text[:500]) +``` + + + See the [Examples page](/tutorials/code-examples) for complete working code in Python, JavaScript, and C#. + diff --git a/index.mdx b/index.mdx new file mode 100644 index 0000000..cb9c830 --- /dev/null +++ b/index.mdx @@ -0,0 +1,59 @@ +--- +title: "What is MTConnect?" +description: "An open, royalty-free standard (ANSI/MTC1.4-2018) that defines a semantic vocabulary for manufacturing equipment data." +--- + +
+ Stable + v2.2 +
+ +MTConnect is an open, royalty-free standard (ANSI/MTC1.4-2018) that defines a semantic vocabulary for manufacturing equipment data. It gives machines a common language so any application can read data from any compliant device — without proprietary adapters or vendor lock-in. + + + MTConnect is used on **250,000+ devices** across **50+ countries**, developed by over 500 machine builders and integrators. + + +## Key Capabilities + + + + Stream live machine data over standard HTTP + + + Agent + Adapter pattern, works with any language + + + Shared vocabulary for 1000s of data item types + + + Python, JavaScript, C# — ready to run + + + +## How It Works + +The MTConnect architecture has three layers: + +1. **Machine / Device** — CNC machines, robots, sensors generating raw data +2. **Adapter** — translates machine signals into the SHDR protocol +3. **Agent** — normalizes data and serves it over HTTP as structured XML + +Client applications call the Agent's HTTP endpoints (`/probe`, `/current`, `/sample`) to discover devices, read current values, or stream historical data. + +## Supported Versions + +- **v2.2** (current) — CuttingTool enhancements, additive manufacturing types +- **v2.1** — Component relationships, Specifications data items +- **v2.0** — Device Relationships, Interface components +- **v1.x** — Legacy, still widely deployed + +## Supported versions + +| Version | Released | Notable additions | +|---------|----------|-------------------| +| `2.7` | 2025 | Latest stable release | +| `2.2` | 2023 | CuttingTool assets v2, Part enhancements | +| `2.1` | 2022 | Relationships, Specifications | +| `2.0` | 2021 | Device Relationships, Interfaces | +| `1.8` | 2020 | Solid Model assets | \ No newline at end of file diff --git a/logo/logo.svg b/logo/logo.svg new file mode 100644 index 0000000..57cdb4a --- /dev/null +++ b/logo/logo.svg @@ -0,0 +1,146 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/reference/changelog.mdx b/reference/changelog.mdx new file mode 100644 index 0000000..593be6d --- /dev/null +++ b/reference/changelog.mdx @@ -0,0 +1,83 @@ +--- +title: "Changelog" +description: "MTConnect C++ Agent release history — first release of each major version." +icon: "clock-rotate-left" +mode: "center" +--- + + + First release of the MTConnect 2.7 agent. + + - Added support for 2.7 Assets + - Updated the Readme file for the C++ Agent + - Completed WebSocket Asset support and WebSocket testing + - Verified handling of Japanese characters + - Migrated codebase to C++ 20 + + + + First release of the MTConnect 2.6 agent. + + - Added support for version 2.6 REST error response documents + - Support for `AssetAdded` event alongside `AssetChanged` and `AssetRemoved` + - Fixed WebSocket error reporting and handling + - All error handling is backwards compatible with older error documents + + + + First release of the MTConnect 2.5 agent. + + - Support for validation of the MTConnect Streams document (`Validation = true` in config) + - Initial validation covers controlled vocabulary (enumerations); numeric types planned for future releases + - Added support for new asset models: **Pallet** and **Fixture** + - WebSockets communication support via the REST interface + - Deprecated the old MQTT Server; topics now mirror probe, current, and streams + + + + First release of the MTConnect 2.4 agent. + + - Added JSON schema for configuration files + - Fixed documentation for configuration in the README + - Added XPath to the `Mqtt2Service` to sub-select which components and data items are published + + + + First release of the MTConnect 2.3 agent. + + - Version 2.3 new **Condition ID** for Condition observations and associated activations + - Added `Sender` configuration setting (`Sender = ...`) to override the header sender value + - Added 2.3 schema files + - README updates for MQTT, SHDR, and related documentation fixes + + + + First release of the MTConnect 2.2 agent. + + - Official reference implementation of MTConnect Agent version 2.2 + - All 2.2 changes in the information model applied + - Dynamic changes to device XML configuration from adapters and upstream agents + - Swagger documentation served directly from the agent (`/swagger`) + - Updated JSON document generation + - Added hash for Assets and Devices + - Added `ImageFiles` for Configuration + - Added `ComponentConfigurationParameters` Asset + - Added UUID support for `CoordinateSystems` + - Added GitHub Actions workflows for CI/CD + + + + First release of the MTConnect 2.1 agent. + + - Added MQTT Sink support (`MqttClientId` configurable for authentication) + - Updated schema version on device XML reload + - Asset handling fixes — verified use of assets when no device or type is supplied + - Clarified `logging_level` values in documentation + + + + First release of the MTConnect 2.0 agent. + + - Added `units` and `nativeUnits` to `SolidModel` per the 2.0 specification + - Foundation for Device Relationships and Interface components introduced in the 2.0 standard + \ No newline at end of file diff --git a/reference/data-model.mdx b/reference/data-model.mdx new file mode 100644 index 0000000..72cc4a0 --- /dev/null +++ b/reference/data-model.mdx @@ -0,0 +1,7 @@ +--- +title: "Data Model Reference" +description: "The MTConnect information model defines a semantic vocabulary for manufacturing data." +icon: "table" +--- + +The MTConnect information model defines a semantic vocabulary for manufacturing data. Browse the complete model at [model.mtconnect.org](https://model.mtconnect.org/). diff --git a/reference/xml-schema.mdx b/reference/xml-schema.mdx new file mode 100644 index 0000000..5f0c9c3 --- /dev/null +++ b/reference/xml-schema.mdx @@ -0,0 +1,14 @@ +--- +title: "XML Schema" +description: "MTConnect XML schemas validate documents against the standard." +icon: "file-code" +--- + +MTConnect XML schemas validate documents against the standard. + +``` +https://schemas.mtconnect.org/schemas/MTConnectDevices_2.2.xsd +https://schemas.mtconnect.org/schemas/MTConnectStreams_2.2.xsd +https://schemas.mtconnect.org/schemas/MTConnectAssets_2.2.xsd +https://schemas.mtconnect.org/schemas/MTConnectError_2.2.xsd +``` diff --git a/tutorials/building-a-client.mdx b/tutorials/building-a-client.mdx new file mode 100644 index 0000000..c5c4809 --- /dev/null +++ b/tutorials/building-a-client.mdx @@ -0,0 +1,26 @@ +--- +title: "Tutorial: Building a Client" +description: "An MTConnect client is any application that consumes data from an Agent via HTTP." +icon: "code" +--- + +An MTConnect client is any application that consumes data from an Agent via HTTP. Here's a complete Python client. + +```python client.py +import requests +import xml.etree.ElementTree as ET + +BASE = "http://localhost:5000" +NS = {"m": "urn:mtconnect.org:MTConnectStreams:2.0"} + +def get_current(): + r = requests.get(f"{BASE}/current") + root = ET.fromstring(r.text) + items = root.findall(".//m:DataItem", NS) + return {item.get("dataItemId"): item.text for item in items} + +if __name__ == "__main__": + data = get_current() + for key, val in data.items(): + print(f" {key}: {val}") +``` diff --git a/tutorials/code-examples.mdx b/tutorials/code-examples.mdx new file mode 100644 index 0000000..770b756 --- /dev/null +++ b/tutorials/code-examples.mdx @@ -0,0 +1,44 @@ +--- +title: "Code Examples" +description: "Complete, runnable examples in multiple languages." +icon: "terminal" +--- + +Complete, runnable examples in multiple languages. + + + + ```python + import requests, xml.etree.ElementTree as ET + + r = requests.get("http://localhost:5000/current") + root = ET.fromstring(r.text) + for item in root.iter(): + if item.text and item.get("dataItemId"): + print(f"{item.get('dataItemId')}: {item.text}") + ``` + + + ```javascript + const res = await fetch('http://localhost:5000/current'); + const text = await res.text(); + const parser = new DOMParser(); + const xml = parser.parseFromString(text, 'text/xml'); + xml.querySelectorAll('[dataItemId]').forEach(el => { + console.log(el.getAttribute('dataItemId'), el.textContent); + }); + ``` + + + ```csharp + using System.Net.Http; + using System.Xml.Linq; + + var client = new HttpClient(); + var xml = await client.GetStringAsync("http://localhost:5000/current"); + var doc = XDocument.Parse(xml); + foreach (var item in doc.Descendants().Where(e => e.Attribute("dataItemId") != null)) + Console.WriteLine($"{item.Attribute("dataItemId")!.Value}: {item.Value}"); + ``` + + diff --git a/tutorials/writing-an-adapter.mdx b/tutorials/writing-an-adapter.mdx new file mode 100644 index 0000000..bfeda3f --- /dev/null +++ b/tutorials/writing-an-adapter.mdx @@ -0,0 +1,31 @@ +--- +title: "Tutorial: Writing an Adapter" +description: "An adapter connects a machine to an MTConnect Agent using the SHDR protocol over a TCP socket." +icon: "plug" +--- + +An adapter connects a machine to an MTConnect Agent using the SHDR protocol over a TCP socket. Here's a complete Python adapter for a simulated CNC machine. + +```python simple_adapter.py +import socket, time, random, datetime + +AGENT_HOST = "localhost" +AGENT_PORT = 7878 + +def timestamp(): + return datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" + +def shdr(key, value): + return f"{timestamp()}|{key}|{value}\n" + +with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + s.connect((AGENT_HOST, AGENT_PORT)) + print(f"Connected to agent at {AGENT_HOST}:{AGENT_PORT}") + while True: + speed = round(random.uniform(2800, 3200), 1) + x_pos = round(random.uniform(-100, 100), 3) + s.sendall(shdr("S1speed", speed).encode()) + s.sendall(shdr("Xpos", x_pos).encode()) + s.sendall(shdr("Smode", "AUTOMATIC").encode()) + time.sleep(0.5) +```