thin-edge.io custom topic schema example

thin-edge.io-custom-topic-schema.md

Using custom topic schema with thin-edge.io (>= 0.13.0)

This is a short informal overview of how to use thin-edge.io and a custom topic schema to model different IoT use-cases.

This documentation is provided to help people understand thin-edge.io and to provide some early feedback before adding it to the official docs.

Building management system

This example explores the building management system use-case where thin-edge.io provides the communication from the cloud to a local piece of software which translates the thin-edge.io MQTT API to the required building management system API calls.

Domain	te entity type	Description
system	child-device	Custom piece of software which is responsible translating custom 3rd party API to thin-edge.io MQTT API
floor	child-device	A floor/level in a building. A floor contains multiple rooms
room	child-device	A room in located on a floor, and can have multiple services. A room can receive operations to perform some action in the room
sensor	service	A sensor which just has telemetry data (measurement, events and alarms)

Registration of entities (child devices/services)

1. Register the system which will be responsible for interfacing between the thin-edge.io MQTT API and the building management API

   tedge mqtt pub -r te/system1/// '{"@type":"child-device","type":"system","name":"system1"}'
   
   # Update custom properties on the system
   tedge mqtt pub -r te/system1////twin/subtype '"api-translator"'

2. Register a floor under the system

   tedge mqtt pub -r te/system1/floor1// '{"@type":"child-device","type":"floor","name":"floor1","@parent":"system1///"}'

3. Register room and it's capabilities

   tedge mqtt pub -r te/system1/floor1/room1/ '{"@type":"child-device","type":"room","name":"room1","@parent":"system1/floor1//"}'
   
   # Capabilities (restart operation, but this is just an example)
   #tedge mqtt pub -r te/system1/floor1/room1//cmd/restart '{}'
   #tedge mqtt pub -r te/system1/floor1/room1//cmd/software_update '{}'
   
   # Workaround due to https://github.com/thin-edge/thin-edge.io/issues/2409
   tedge mqtt pub -r te/system1/floor1/room1//twin/c8y_SupportedOperations '["c8y_Restart"]'

4. Register sensor in a room

   tedge mqtt pub -r te/system1/floor1/room1/sensor1 '{"@type":"service","type":"sensor","name":"sensor1","@parent":"system1/floor1/room1/"}'

5. Subscribe to commands for the room

   tedge mqtt sub te/system1/floor1/room1//cmd/+/+

   Example operation received from the cloud to the local te/ topic

   [te/system1/floor1/room1//cmd/restart/c8y-mapper-2023-11-03T12:08:56.985355716Z] {"status":"init"}
   

Publishing data

Telemetry data can be grouped under any entity by using the same identifier that was used in the registration step:

The following publishes data related to the sensor registered in 1 room.

tedge mqtt pub te/system1/floor1/room1/sensor1/m/temperature '{"temperature":{"min": 10.5,"max":12.0}}'
tedge mqtt pub te/system1/floor1/room1/sensor1/m/environment '{"temperature":{"avg": 10.5},"humidity": {"avg":60}}'

On the device, other components can also subscribe to the sensor measurements (or any other sensor data) via the thin-edge.io topics:

tedge mqtt sub te/system1/floor1/room1/sensor1/m/temperature