Skip to main content
Version: 0.13.1

thin-edge Data Model

The data model identifies all data send or received from/to thin-edge and its components, to interact with those. For all data it defines format and explains behaviour.

Use of MQTT

thin-edge expects the MQTT broker mosquitto to be available on the device. thin-edge uses mosquitto to consume and provide telemetry data. All telemetry data are reflected with specific MQTT topics and payload in JSON format.

thin-edge assumes mosquitto is configured in a secure manner, to avoid any inappropriate access to thin-edge topics and payload. Any malicious access to the broker can hazard thin-edge and all connected devices. Mosquitto provides a wide range of authentication and access control options. For more details see Authentication and ACL (Access Control List) in mosquitto documentation.

Telemetry Data on MQTT

All telemetry data (Measurements, Events, Alarms) are reflected with MQTT topics, where each has its specific subtopic (e.g. te/+/+/+/+/m/+, te/+/+/+/+/e/+, te/+/+/+/+/a/+ etc.).

  • each provider of a measurement, event or alarm sends the occurring data to thin-edge's MQTT broker
    • a provider can be the domain application1, other SW components / 3rd parties
  • all processes (e.g. the domain application1, other SW components / 3rd parties) on the main-device and all child-devices can consume those telemetry data from the MQTT broker
  • the cloud mapper on the main-device picks-up all telemetry data from the MQTT broker and transfers those to the cloud

The communication diagram below illustrates that behaviour.

MQTT communication flow

Telemetry Data for Child-Devices

All telemetry data provided to the MQTT bus are associated by thin-edge and all consumers with the thin-edge main-device or some child-device (see more details about child-devices in the domain model).

Therefore the child-id of the child-device is can be appended to the MQTT topic, if the message is meant for a child-device; or no child-id is appended, if the message is meant for the main-device.

MQTT topics for the main-device:

te/device/main///m/<measurement-type>
te/device/main///e/<event-type>
te/device/main///a/<alarm-type>

MQTT topics for a child-device, including the child-device's specific child-id:

te/device/<child-id>///m/<measurement-type>
te/device/<child-id>///e/<event-type>
te/device/<child-id>///a/<alarm-type>

Telemetry Data

Telemetry Data consists of measurements, events and alarms. Each is defined by a set of data-elements, each with specific behaviour.

Measurements

Measurements carry values from physical Sensors1 or a device's Domain Application1; e.g. voltage and current of an electricity meter, or current state of the manufacturing control process

MQTT topics for measurements

te/device/main///m/<measurement-type>

te/device/<child-id>///m/<measurement-type>

MQTT payload for measurements

A measurement can carry a single value, or multiple values all taken at a single point in time.

One MQTT message can contain a mixture of more than one single-value and multi-value measurements.

Example for a single-value measurement payload
{
"temperature": // 'name' of that measurement
25.3, // 'value' of that measurement
"time": "2020-10-15T05:30:47+00:00", // optional 'timestamp' of that measurement
}
Example for a multi-value measurement payload
{
"current": { // 'name' of that measurement
"L1": 9.5, // the 1st 'value' of that measurement, named as "L1"
"L2": 1.3 // the 2nd 'value' of that measurement, named as "L2"
// ...even more values can occur
},
"time": "2020-10-15T05:30:47+00:00", // optional 'timestamp' of that measurement
}
ReferenceDescription
namea string that identifies the measurement uniquely in context of the device
valuethe value that was sampled; can be named (especially in context of a multi-value measurement) or unnamed; must be an integer or floating point number
timestampoptional time that indicates when values were sampled; when not provided, thin-edge.io uses the current system time as the time of the sample; when provided must be conform to ISO 8601

Behaviour of measurements

  • thin-edge does not store any historical sampled values for measurements
  • there is no initialization value for measurements; i.e. a measurement is not visible on thin-edge before the 1st sample was sent to thin-edge
  • a measurement should never be published as MQTT retain message; That is as a single retained measurement might be consumed and processed more than once by a consuming software component (e.g. when that software component restarts and subscribes again).

Events

Events are notifications that something happened on a device's environment or software system; e.g. a sensor1 detected something like a door has been closed, or a system notification that e.g. a user has started an ssh session

MQTT topics for events

te/device/main///e/<event-type>

te/device/<child-id>///e/<event-type>

MQTT payload for events

{
// example of an event
"text": "A user just logged in", // 'text' message of that event
"time": "2021-01-01T05:30:45+00:00", // optional 'timestamp' of that event
"someOtherCustomFragment": { // optional 'custom fragments'
"nested": {
"value": "extra info"
}
}
}
ReferenceDescription
event-typea string part of the MQTT topic, that identifies the event uniquely in context of the device
textcarries a human readable event-text; must be UTF-8 encoded
timestampoptional time that indicates when the event has occurred; when not provided, thin-edge.io uses the current system time as the time of the event; when provided must be conform to ISO 8601
custom fragmentsadditional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud

Behaviour of events

  • thin-edge does not store any historical occurrences for events
  • an event should never be published as MQTT retain message; That is as a single retained event might be consumed and processed more than once by a consuming software component (e.g. when that software component restarts and subscribes again).

Alarms

Alarms are notifications about some critical behaviour of the device's environment or software system; e.g. when a temperature sensor detects a temperature went out of its valid range

MQTT topics for alarms

te/device/main///a/<alarm-type>

te/device/<child-id>///a/<alarm-type>

MQTT payload for alarms

{
// example for an alarm
"text": "Temperature is very high", // 'text' message of that alarm
"time": "2021-01-01T05:30:45+00:00", // optional 'timestamp' of that alarm
"severity": "major", // optional 'severity' of the alarm
"someOtherCustomFragment": { // optional 'custom fragments'
"nested": {
"value": "extra info"
}
}
}
ReferenceDescription
alarm-typea string part of the MQTT topic, that identifies the alarm uniquely in context of the device
severitya string part of the MQTT payload, that indicates the severity of the alarm; recommended to be critical, major, minor or warning
textcarries a human readable alarm-text; must be UTF-8 encoded
timestampoptional time that indicates when the alarm has occurred; when not provided, thin-edge.io uses the current system time as the time of the alarm; when provided must be conform to ISO 8601
custom fragmentsadditional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud

Behaviour of alarms

  • thin-edge does not store any historical occurrences for alarms
  • alarms are stateful; i.e. once raised, an alarm is active until it was explicitly cleared by the device's software or the cloud
  • all alarms shall be published as MQTT retain message to reflect the alarm's stateful behaviour in the broker; The retain messages is kept in the MQTT broker as long as the alarm is raised. When a raised alarm is gone again, an empty retain message shall be published to clear the alarm message in the broker.

Footnotes

  1. details see "Domain Model" appendix Device Domain --> 2 3 4 5