Shdr

Shdr is the underlying protocol of MTConnect, which implements the communication between an MTConnect Adapter and MTConnect Agent.

In situation where no MTConnect Agent is available, you can directly hook into this communication. The protocol is readonly and reports all process data of machines including conditions, alarms and events.

Important

For addressing data in Shdr, you first need to know the keys of the data items. These may be one of the following (in this order): Source, name, id of the item in the MTConnect Information Model of your equipment.

To learn about the available keys on your equipment without the MTConnect Information Model being available, subscribe to raw data and observe the data over time.

Commissioning file specifics

A typical commissioning file for the SHDR protocol looks like this:

Download: shdr-example.yml

 1# ----------------------------------------------------------------------------#
 2# Commissioning File
 3# ----------------------------------------------------------------------------#
 4# Copyright: Cybus GmbH (2020)
 5# Contact: support@cybus.io
 6# ----------------------------------------------------------------------------#
 7description: >
 8  Shdr sample commissioning file
 9
10metadata:
11  name: Shdr simulator
12  icon: https://www.cybus.io/wp-content/themes/cybus/img/product-slide-img.png
13  provider: cybus
14  homepage: https://www.cybus.io
15  version: 1.0.0
16
17parameters:
18  IP_Address:
19    type: string
20    default: 192.168.0.1
21  Port:
22    type: integer
23    default: 7878
24  initialReconnectDelay:
25    type: integer
26    default: 1000
27  maxReconnectDelay:
28    type: integer
29    default: 30000
30  factorReconnectDelay:
31    type: integer
32    default: 2
33
34
35definitions:
36  MQTT_TOPIC_PREFIX: io/cybus/shdr
37
38resources:
39  shdrConnection:
40    type: Cybus::Connection
41    properties:
42      protocol: Shdr
43      connection:
44        host: !ref IP_Address
45        port: !ref Port
46        connectionStrategy:
47          initialDelay: !ref initialReconnectDelay
48          maxDelay: !ref maxReconnectDelay
49          incrementFactor: !ref factorReconnectDelay
50
51  raw:
52    type: Cybus::Endpoint
53    properties:
54      protocol: Shdr
55      connection: !ref shdrConnection
56      subscribe:
57        key: raw
58        type: sample
59
60  xact:
61    type: Cybus::Endpoint
62    properties:
63      protocol: Shdr
64      connection: !ref shdrConnection
65      subscribe:
66        key: Xact
67        type: sample
68
69  temperature:
70    type: Cybus::Endpoint
71    properties:
72      protocol: Shdr
73      connection: !ref shdrConnection
74      subscribe:
75        key: temp_cond
76        type: condition
77
78  mapping:
79    type: Cybus::Mapping
80    properties:
81      mappings:
82        - subscribe:
83            endpoint: !ref raw
84          publish:
85            topic: !sub '${MQTT_TOPIC_PREFIX}/raw'
86        - subscribe:
87            endpoint: !ref xact
88          publish:
89            topic: !sub '${MQTT_TOPIC_PREFIX}/xAct'
90        - subscribe:
91            endpoint: !ref temperature
92          publish:
93            topic: !sub '${MQTT_TOPIC_PREFIX}/tempCondition'

Connection Properties

host (string, required)

Hostname or IP address of the Shdr device

Default: ""

Example: "example.org"

port (integer, required)

Port of the Shdr device

Default: 7878

Example: 7878

connectionStrategy (object)

If a connection attempt fails, retries will be performed with increasing delay (waiting time) in between. The following parameters control how these delays behave.

Properties of the connectionStrategy object:

initialDelay (integer)

Delay (waiting time) of the first connection retry (in milliseconds). For subsequent retries, the delay will be increased according to the parameter incrementFactor which has a default value of 2.

Default: 1000

Additional restrictions:

  • Minimum: 1000

maxDelay (integer)

Maximum delay (waiting time) to wait until the next retry (in milliseconds). The delay (waiting time) for any subsequent connection retry will not be larger than this value. Must be strictly greater than initialDelay.

Default: 30000

incrementFactor (integer)

The factor used to increment initialDelay up to maxDelay. For example if initialDelay is set to 1000 and maxDelay to 5000 the values for the delay would be 1000, 2000, 4000, 5000.

Default: 2

Additional restrictions:

  • Minimum: 2

Endpoint Properties

key (string, required)

Key of the data item in the information flow. May be Source, name or id of the MTConnect Item

Example: "Xact"

type (string, enum, required)

Any valid topic name addressing a single data-point

This element must be one of the following enum values:

  • sample

  • event

  • condition

  • message

  • alarm

Default: "sample"

Example: "sample"

Output Format

If data is read from SHDR the output will be provided as JSON object

type: sample, event

{
  "timestamp": "<msSinceEpoch>",
  "value": "<value>"
}

type: condition

{
  "timestamp": "<msSinceEpoch>",
  "value": {
    "level": "<level>",
    "nativeCode": "<nativeCode>",
    "nativeSeverity": "<nativeSeverity>",
    "qualifier": "<qualifier>",
    "text": "<text>"
  }
}

type: message

{
  "timestamp": "<msSinceEpoch>",
  "value": {
    "nativeCode": "<nativeCode>",
    "text": "<text>"
  }
}

type: alarm

{
  "timestamp": "<msSinceEpoch>",
  "value": {
    "code": "<code>",
    "nativeCode": "<nativeCode>",
    "severity": "<severity>",
    "state": "<state>"
  }
}