diff --git a/docs/src/understand/thin-edge-json.md b/docs/src/understand/thin-edge-json.md index 67bf507653a..6ae24e4b988 100644 --- a/docs/src/understand/thin-edge-json.md +++ b/docs/src/understand/thin-edge-json.md @@ -6,17 +6,15 @@ sidebar_position: 4 # Thin Edge JSON format -Thin Edge JSON is a lightweight format used in `thin-edge.io` to represent telemetry data: measurements, events and alarms. -These data are exchanged over the [MQTT bus](mqtt-bus.md) and sent by the devices and services of a agent. +Thin Edge JSON is a lightweight format used in `thin-edge.io` to represent telemetry data: +measurements, events and alarms as well as operations: software update, configuration update etc. +These data are exchanged over the [MQTT bus](mqtt-bus.md) by the devices and services. ## Sending Telemetry Data The `thin-edge.io` framework exposes some MQTT endpoints that can be used by local processes +and other devices connected over the network to exchange data between themselves as well as to get some data forwarded to the cloud. -It will essentially act like an MQTT broker against which you can write your application logic. -Other thin-edge processes can use this broker as an inter-process communication mechanism by publishing and -subscribing to various MQTT topics. -Any data can be forwarded to the connected cloud-provider as well, by publishing the data to some standard topics. ### Sending Telemetry Data to thin-edge.io @@ -26,7 +24,7 @@ to the `tedge/measurements` topic. Other processes running on the thin-edge device can subscribe to this topic to process these measurements. If the messages published to this `tedge/measurements` topic is not a well-formed Thin Edge JSON, -then that message won’t be processed by `thin-edge.io`, not even partially, +then these messages won’t be processed by `thin-edge.io`, not even partially, and an appropriate error message on why the validation failed will be published to a dedicated `tedge/errors` topic. The messages published to this topic will be highly verbose error messages and can be used for any debugging during development. You should not rely on the structure of these error messages to automate any actions as they are purely textual data @@ -50,7 +48,7 @@ Here is the complete list of topics reserved by `thin-edge.io` for its internal The `thin-edge.io` framework allows users forward telemetry data generated and published to one of the `tedge/#` MQTT topics from the thin-edge device to any IoT cloud provider that it is connected to, with the help of a *mapper* component designed for that cloud. -The responsibility of a mapper is to subscribe to the `tedge/#` topic to receive all incoming measurements, events and alarms +The responsibility of a mapper is to subscribe to the `tedge/#` topic to receive all incoming data represented in the cloud vendor neutral Thin Edge JSON format, to a format that the connected cloud understands. Refer to [Cloud Message Mapper Architecture](./tedge-mapper.md) for more details on the mapper component. @@ -67,26 +65,27 @@ or a combination of both along with some auxiliary data like the timestamp at wh ### Single-valued measurements -Simple single-valued measurements like temperature or pressure measurement with a single value can be expressed as follows: +Simple single-valued measurements like temperature or pressure can be expressed as follows: ```sh te2mqtt -tedge mqtt pub /tedge/measurements '{ +tedge mqtt pub tedge/measurements '{ "temperature": 25 }' ``` -where the key represents the measurement type, and the value represents the measurement value. -The keys can only have alphanumeric characters, and the "_" (underscore) character but must not start with an underscore. +The key represents the measurement type, and the value represents the measurement value. +The keys can only have alphanumeric characters, and the underscore (`_`) character but must not start with an underscore. The values can only be numeric. String, Boolean or other JSON object values are not allowed. ### Multi-valued measurements -A multi-valued measurement is a measurement that is comprised of multiple values. Here is the representation of a -`three_phase_current` measurement that consists of `L1`, `L2` and `L3` values, representing the current on each phase: +Like the name suggests, a multi-valued measurement is allowed to contain more than one value. +Here is the representation of a `three_phase_current` measurement that consists of `L1`, `L2` and `L3` values, +representing the current on each phase: ```sh te2mqtt -tedge mqtt pub /tedge/measurements '{ +tedge mqtt pub tedge/measurements '{ "three_phase_current": { "L1": 9.5, "L2": 10.3, @@ -95,13 +94,14 @@ tedge mqtt pub /tedge/measurements '{ }' ``` -where the key is the top-level measurement type and value is a JSON object having further key-value pairs +The key is the top-level measurement type and value is a JSON object having further key-value pairs representing each aspect of the multi-valued measurement. Only one level of nesting is allowed, meaning the values of the measurement keys at the inner level can only be numeric values. -For example, a multi-level measurement as follows is NOT valid: + +**❌ Example: Invalid measurement due to nesting > 2 levels** ```sh te2mqtt -tedge mqtt pub /tedge/measurements '{ +tedge mqtt pub tedge/measurements '{ "three_phase_current": { "phase1": { "L1": 9.5 @@ -116,14 +116,12 @@ tedge mqtt pub /tedge/measurements '{ }' ``` -because the values at the second level(`phase1`, `phase2` and `phase3`) are not numeric values. - ### Grouping measurements Multiple single-valued and multi-valued measurements can be grouped into a single Thin Edge JSON message as follows: ```sh te2mqtt -tedge mqtt pub /tedge/measurements '{ +tedge mqtt pub tedge/measurements '{ "temperature": 25, "three_phase_current": { "L1": 9.5, @@ -144,7 +142,7 @@ an explicit timestamp can be provided in the measurement message itself by addin in ISO 8601 format using `time` as the key name, as follows: ```sh te2mqtt -tedge mqtt pub /tedge/measurements '{ +tedge mqtt pub tedge/measurements '{ "time": "2020-10-15T05:30:47+00:00", "temperature": 25, "location": { @@ -179,10 +177,10 @@ For instance: - a user has started an ssh session ```sh te2mqtt -tedge mqtt pub /tedge/events/login '{ - "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": { // free 'custom fragments' +tedge mqtt pub tedge/events/login '{ + "text": "A user just logged in", + "time": "2021-01-01T05:30:45+00:00" + "someOtherCustomFragment": { "nested": { "value": "extra info" } @@ -190,12 +188,12 @@ tedge mqtt pub /tedge/events/login '{ }' ``` -|Reference | Description | -| ------------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`event-type` | a string part of the MQTT topic, that identifies the event uniquely in context of the device | -|`text` | carries a human readable event-text; must be UTF-8 encoded | -|`timestamp` | optional 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 fragments` | additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud | +| Reference | Description | +|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `event_type` | Uniquely identifies the event in the context of the device; part of the MQTT topic | +| `text` | Text description of the event; must be UTF-8 encoded | +| `timestamp` | Optional time that indicates when the event occurred, in ISO 8601 string format; when not provided, thin-edge.io uses the current system time | +| `*` | Additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud | ## Alarms @@ -206,10 +204,10 @@ For instance: - free disk space going critically low ```sh te2mqtt -tedge mqtt pub /tedge/alarms/warning/temperature_high '{ - "text": "Temperature is very high", // 'text' message of that alarm - "time": "2021-01-01T05:30:45+00:00", // optional 'timestamp' of that alarm - "someOtherCustomFragment": { // free 'custom fragments' +tedge mqtt pub tedge/alarms/warning/temperature_high '{ + "text": "Temperature is very high", + "time": "2021-01-01T05:30:45+00:00", + "someOtherCustomFragment": { "nested": { "value": "extra info" } @@ -217,11 +215,11 @@ tedge mqtt pub /tedge/alarms/warning/temperature_high '{ }' ``` -|Reference |Description| -| ------------------ | --------- | -|`alarm-type` |a string part of the MQTT topic, that identifies the alarm uniquely in context of the device| -|`severity` |a string part of the MQTT topic, that indicates the severity of the alarm; must be `critical`, `major`, `minor` or `warning`| -|`text` |carries a human readable alarm-text; must be UTF-8 encoded| -|`timestamp` |optional 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 fragments` |additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud| +| Reference | Description | +|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `alarm_type` | Uniquely identifies the alarm in the context of the device; part of the MQTT topic | +| `severity` | Severity of the alarm; must be `critical`, `major`, `minor` or `warning`; part of the MQTT topic | +| `text` | Text description of the alarm; must be UTF-8 encoded | +| `timestamp` | Optional time that indicates when the alarm has occurred, in ISO 8601 string format; when not provided, thin-edge.io uses the current system time | +| `*` | Additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud |