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
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
# ----------------------------------------------------------------------------#
# Commissioning File
# ----------------------------------------------------------------------------#
# Copyright: Cybus GmbH (2020)
# Contact: support@cybus.io
# ----------------------------------------------------------------------------#
description: >
  Shdr sample commissioning file

metadata:
  name: Shdr simulator
  icon: https://www.cybus.io/wp-content/themes/cybus/img/product-slide-img.png
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  IP_Address:
    type: string
    default: 192.168.0.1
  Port:
    type: integer
    default: 7878
  initialReconnectDelay:
    type: integer
    default: 1000
  maxReconnectDelay:
    type: integer
    default: 30000
  factorReconnectDelay:
    type: integer
    default: 2


definitions:
  MQTT_TOPIC_PREFIX: io/cybus/shdr

resources:
  shdrConnection:
    type: Cybus::Connection
    properties:
      protocol: Shdr
      connection:
        host: !ref IP_Address
        port: !ref Port
        connectionStrategy:
          initialDelay: !ref initialReconnectDelay
          maxDelay: !ref maxReconnectDelay
          incrementFactor: !ref factorReconnectDelay

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

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

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

  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref raw
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/raw'
        - subscribe:
            endpoint: !ref xact
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/xAct'
        - subscribe:
            endpoint: !ref temperature
          publish:
            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>"
  }
}