> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/machine-connectivity/cnc-machine-tools/connecting-mtconnect-machines-via-shdr.md).

# Connecting MTConnect Machines via SHDR

This guide shows you how to read data from an MTConnect adapter using the Connectware [SHDR connector](/2-4-2/connectors/shop-floor-connectors/shdr.md) and map it into an ISA-95 style MQTT topic hierarchy. In more detail, the following topics are covered:

* Understanding the MTConnect adapter and agent architecture and where Connectware fits in
* Identifying the data item keys of your adapter
* Creating the [service commissioning file](/2-4-2/data-flows/service-commissioning-files.md)
* Mapping data items into an ISA-95 style MQTT topic hierarchy
* Verifying data in the [Data Explorer](/2-4-2/monitoring/data-explorer.md)

A complete example file is available at the end of this guide.

## Prerequisites

To follow this guide, you will need the following:

* A running instance of Cybus Connectware.
* A machine with a running MTConnect adapter that is reachable over TCP from Connectware. Many CNC controllers ship with an MTConnect adapter, or the machine vendor provides one. For testing without a machine, you can use one of the simulator adapters from the [MTConnect GitHub organization](https://github.com/mtconnect).
* Access to the [Admin UI](/2-4-2/access/admin-ui.md) with sufficient [user permissions](/2-4-2/access/user-management.md).
* Basic knowledge of MQTT and the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), and [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md)).

## About MTConnect and SHDR

[MTConnect](https://www.mtconnect.org) is a read-only standard for machine tool data. A typical MTConnect setup consists of two components:

* **Adapter**: Runs on or near the machine, translates the proprietary controller data into a standardized data stream, and pushes it to the agent.
* **Agent**: Buffers the data of one or more adapters and serves it to applications over HTTP.

The protocol between adapter and agent is Simple Hierarchical Data Representation (SHDR): a plain text stream over TCP in which each line carries a timestamp followed by pipe-delimited key-value pairs. Adapters listen on TCP port 7878 by default. A typical stream looks like this:

{% code lineNumbers="true" %}

```
2026-07-16T09:30:00.000000Z|avail|AVAILABLE
2026-07-16T09:30:00.128000Z|execution|ACTIVE|mode|AUTOMATIC
2026-07-16T09:30:00.354000Z|Xact|-1.1761|part_count|112
```

{% endcode %}

The Connectware SHDR connector takes the place of the MTConnect agent: it connects directly to the TCP stream of the adapter and parses the key-value pairs into individual endpoints. If your machine already has an MTConnect adapter, you can stream its data into Connectware without operating an agent in between. Because SHDR is read-only, all endpoints are subscriptions. You cannot write data to the machine.

## Identifying Data Item Keys

Each SHDR endpoint addresses one data item by its key. The key may be one of the following properties of the data item in the MTConnect information model of your equipment, checked in this order: Source, name, or id.

The key names in this guide follow the conventions of the MTConnect reference adapters. Your adapter may use different names, so check the data items in the documentation or device model of your adapter. Typical data items look like this:

| Key          | MTConnect data item    | Endpoint type |
| ------------ | ---------------------- | ------------- |
| `avail`      | Availability           | `event`       |
| `execution`  | Execution              | `event`       |
| `mode`       | ControllerMode         | `event`       |
| `part_count` | PartCount              | `event`       |
| `Xact`       | X axis actual position | `sample`      |
| `temp_cond`  | Temperature condition  | `condition`   |

If the MTConnect information model of your equipment is not available, subscribe to the special key `raw` to receive the complete unparsed SHDR stream and observe the data over time. Every key that appears in the stream can be addressed as an endpoint.

## Writing the Service Commissioning File

The service commissioning file contains all connection and mapping details. Do not worry about copying the snippets together into one file, the complete example file is available at the end of this guide.

### Description and Metadata

These sections contain general information about the service commissioning file. Only the metadata name is required.

{% code lineNumbers="true" %}

```yaml
description: >
  Service commissioning file that reads machine data from an MTConnect
  adapter via SHDR and maps it into an ISA-95 style MQTT topic hierarchy
  (Example)

metadata:
  name: MTConnect SHDR Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0
```

{% endcode %}

### Parameters and Definitions

We define the network address of the MTConnect adapter as parameters, so you can set them when you install the service. The default port of an MTConnect adapter is 7878.

The MQTT topics in this guide follow an ISA-95 style equipment hierarchy (`<enterprise>/<site>/<area>/<line>/<cell>`). We define the prefix once in the `definitions` section and reuse it in every mapping with `!sub`.

{% code lineNumbers="true" %}

```yaml
parameters:
  adapterHost:
    description: Hostname or IP address of the MTConnect adapter
    type: string
    default: 192.168.1.100

  adapterPort:
    description: TCP port of the MTConnect adapter
    type: integer
    default: 7878

definitions:
  MQTT_TOPIC_PREFIX: enterprise/hamburg/machining/line-1/cnc-01
```

{% endcode %}

### Cybus::Connection

The connection resource establishes the TCP connection to the adapter. The `connectionStrategy` object controls how Connectware retries failed connection attempts with increasing delays. For all connection properties, see [SHDR Connection Properties](/2-4-2/connectors/shop-floor-connectors/shdr/shdrconnection.md).

{% code lineNumbers="true" %}

```yaml
resources:
  shdrConnection:
    type: Cybus::Connection
    properties:
      protocol: Shdr
      targetState: connected
      connection:
        host: !ref adapterHost
        port: !ref adapterPort
        connectionStrategy:
          initialDelay: 1000
          maxDelay: 30000
          incrementFactor: 2
```

{% endcode %}

### Cybus::Endpoint

Each endpoint subscribes to one data item of the adapter stream, identified by its `key`. The `type` property must match the category of the data item in the MTConnect information model and determines the output format. The following values are supported: `sample`, `event`, `condition`, `message`, and `alarm`. For details, see [SHDR Endpoint Properties](/2-4-2/connectors/shop-floor-connectors/shdr/shdrendpoint.md).

{% code lineNumbers="true" %}

```yaml
availability:
  type: Cybus::Endpoint
  properties:
    protocol: Shdr
    connection: !ref shdrConnection
    subscribe:
      key: avail
      type: event

execution:
  type: Cybus::Endpoint
  properties:
    protocol: Shdr
    connection: !ref shdrConnection
    subscribe:
      key: execution
      type: event

partCount:
  type: Cybus::Endpoint
  properties:
    protocol: Shdr
    connection: !ref shdrConnection
    subscribe:
      key: part_count
      type: event

xAxisPosition:
  type: Cybus::Endpoint
  properties:
    protocol: Shdr
    connection: !ref shdrConnection
    subscribe:
      key: Xact
      type: sample

temperatureCondition:
  type: Cybus::Endpoint
  properties:
    protocol: Shdr
    connection: !ref shdrConnection
    subscribe:
      key: temp_cond
      type: condition

raw:
  type: Cybus::Endpoint
  properties:
    protocol: Shdr
    connection: !ref shdrConnection
    subscribe:
      key: raw
      type: sample
```

{% endcode %}

The `raw` endpoint subscribes to the complete unparsed SHDR stream. Use it to discover the data item keys of your adapter and remove it once you know the keys.

### Cybus::Mapping

The mapping publishes each endpoint on a topic of the ISA-95 hierarchy. Because SHDR is read-only, all mappings point from an endpoint to a topic.

{% code lineNumbers="true" %}

```yaml
mapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref availability
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/availability'
      - subscribe:
          endpoint: !ref execution
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/execution'
      - subscribe:
          endpoint: !ref partCount
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/part-count'
      - subscribe:
          endpoint: !ref xAxisPosition
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/axes/x/position'
      - subscribe:
          endpoint: !ref temperatureCondition
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/conditions/temperature'
      - subscribe:
          endpoint: !ref raw
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/raw'
```

{% endcode %}

With this mapping, the availability of the machine is published on the topic `enterprise/hamburg/machining/line-1/cnc-01/availability`, and every other data item follows the same pattern.

## Installing the Service Commissioning File

1. Install the service commissioning file. See [Installing Services](/2-4-2/data-flows/services/managing/installing.md).
2. Enable the service. See [Enabling Services](/2-4-2/data-flows/services/managing/enabling.md).

**Result:** The service is enabled. Connectware establishes the TCP connection to the MTConnect adapter and publishes the subscribed data items on the mapped topics.

## Verifying the Data

Open the [Data Explorer](/2-4-2/monitoring/data-explorer.md) and subscribe to `enterprise/hamburg/machining/line-1/cnc-01/#`. As soon as the adapter reports data, messages appear on the mapped topics.

Endpoints of type `sample` and `event` publish a JSON object with the keys `timestamp` and `value`:

{% code lineNumbers="true" %}

```json
{
  "timestamp": 1784194200354,
  "value": "ACTIVE"
}
```

{% endcode %}

Endpoints of type `condition` publish a structured value that contains the condition level and details:

{% code lineNumbers="true" %}

```json
{
  "timestamp": 1784194200354,
  "value": {
    "level": "WARNING",
    "nativeCode": "OTEMP",
    "nativeSeverity": "1",
    "qualifier": "HIGH",
    "text": "Spindle temperature high"
  }
}
```

{% endcode %}

For the output format of the `message` and `alarm` types, see the [SHDR connector reference](/2-4-2/connectors/shop-floor-connectors/shdr.md#output-format).

If no data arrives, check the connection state on the service details page in the Admin UI. If the connection does not reach the **Connected** state, verify that the adapter host and port are reachable from Connectware. If the connection is established but a topic stays empty, subscribe to the `raw` topic and check whether your adapter uses a different key for that data item.

## Service Commissioning File Example

{% file src="/files/ecTbxfjlEMhNLuZ0MOWw" %}

{% code title="mtconnect-shdr-example.yml" lineNumbers="true" expandable="true" %}

```yaml
---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: support@cybus.io
# ----------------------------------------------------------------------------
# Connecting MTConnect Machines via SHDR (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file that reads machine data from an MTConnect
  adapter via SHDR and maps it into an ISA-95 style MQTT topic hierarchy
  (Example)

metadata:
  name: MTConnect SHDR Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  adapterHost:
    description: Hostname or IP address of the MTConnect adapter
    type: string
    default: 192.168.1.100

  adapterPort:
    description: TCP port of the MTConnect adapter
    type: integer
    default: 7878

definitions:
  # ISA-95 style topic prefix: <enterprise>/<site>/<area>/<line>/<cell>
  MQTT_TOPIC_PREFIX: enterprise/hamburg/machining/line-1/cnc-01

resources:
  # Connection to the MTConnect adapter (SHDR over TCP)
  shdrConnection:
    type: Cybus::Connection
    properties:
      protocol: Shdr
      targetState: connected
      connection:
        host: !ref adapterHost
        port: !ref adapterPort
        connectionStrategy:
          initialDelay: 1000
          maxDelay: 30000
          incrementFactor: 2

  # The data item keys below follow the conventions of the MTConnect
  # reference adapters. Check the data items of your adapter and adjust
  # the keys accordingly.
  availability:
    type: Cybus::Endpoint
    properties:
      protocol: Shdr
      connection: !ref shdrConnection
      subscribe:
        key: avail
        type: event

  execution:
    type: Cybus::Endpoint
    properties:
      protocol: Shdr
      connection: !ref shdrConnection
      subscribe:
        key: execution
        type: event

  partCount:
    type: Cybus::Endpoint
    properties:
      protocol: Shdr
      connection: !ref shdrConnection
      subscribe:
        key: part_count
        type: event

  xAxisPosition:
    type: Cybus::Endpoint
    properties:
      protocol: Shdr
      connection: !ref shdrConnection
      subscribe:
        key: Xact
        type: sample

  temperatureCondition:
    type: Cybus::Endpoint
    properties:
      protocol: Shdr
      connection: !ref shdrConnection
      subscribe:
        key: temp_cond
        type: condition

  # Subscribes to the complete unparsed SHDR stream. Useful to discover
  # the data item keys of an adapter. Remove it once you know the keys.
  raw:
    type: Cybus::Endpoint
    properties:
      protocol: Shdr
      connection: !ref shdrConnection
      subscribe:
        key: raw
        type: sample

  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref availability
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/availability'
        - subscribe:
            endpoint: !ref execution
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/execution'
        - subscribe:
            endpoint: !ref partCount
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/part-count'
        - subscribe:
            endpoint: !ref xAxisPosition
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/axes/x/position'
        - subscribe:
            endpoint: !ref temperatureCondition
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/conditions/temperature'
        - subscribe:
            endpoint: !ref raw
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/raw'
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-2/guides/machine-connectivity/cnc-machine-tools/connecting-mtconnect-machines-via-shdr.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.