Connecting MTConnect Machines via SHDR

How to read machine data from an MTConnect adapter with the Connectware SHDR connector and map it into an ISA-95 style MQTT topic hierarchy.

This guide shows you how to read data from an MTConnect adapter using the Connectware SHDR connector 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

• Mapping data items into an ISA-95 style MQTT topic hierarchy

• Verifying data in the Data Explorer

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.

• Access to the Admin UI with sufficient user permissions.

• Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, and endpoints).

About MTConnect and SHDR

MTConnect 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:

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

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.

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 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.

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

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.

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

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.

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

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.

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'

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. Enable the service. See Enabling Services.

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 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:

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

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

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

For the output format of the message and alarm types, see the SHDR connector reference.

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

mtconnect-shdr-example.yml

4KB

Open

mtconnect-shdr-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# 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'