Skip to content

Commit

Permalink
fixup! Update thin-edge-json documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@didier-wenzek
didier-wenzek committed Jul 6, 2023
1 parent 0dbbbf9 commit 6faa9de
Showing 1 changed file with 41 additions and 43 deletions.
84 changes: 41 additions & 43 deletions docs/src/understand/thin-edge-json.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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": {
Expand Down Expand Up @@ -179,23 +177,23 @@ 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"
}
}
}'
```

|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

Expand All @@ -206,22 +204,22 @@ 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"
}
}
}'
```

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

0 comments on commit 6faa9de

Please sign in to comment.