Skip to content

Commit c440c03

Browse files
albinsureshalbinsuresh
authored
Merge pull request #3659 from albinsuresh/doc/entity-management
doc: Entity management API documentation
2 parents bcb8c1b + aebd479 commit c440c03

File tree

8 files changed

+776
-490
lines changed

8 files changed

+776
-490
lines changed

‎docs/src/operate/registration/deregister.md renamed to ‎docs/src/legacy/deregister.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Deregister entities
33
tags: [Child-Device, Registration]
44
sidebar_position: 2
5-
description: Deregister child devices and services from %%te%%
5+
description: Deregister child devices and services from %%te%% using mosquitto_sub
66
---
77

88
# Deregister entities

‎docs/src/operate/entity-management/auto-registration.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Auto-registration
3+
tags: [Child-Device, Registration]
4+
sidebar_position: 1
5+
description: Auto-register child devices and services over MQTT
6+
---
7+
8+
# Auto Registration
9+
10+
%%te%% provides an auto-registration mechanism for clients that do not want to do an explicit registration.
11+
To leverage this, they must conform to the **default topic scheme** that clearly demarcates the `device` and `service` as follows:
12+
13+
```
14+
te/device/<device_id>/service/<service_id>
15+
```
16+
17+
With auto-registration, when a measurement message is published to `te/device/rpi1001///m/cpu_usage` topic
18+
without a prior explicit registration of that entity,
19+
a `child-device` entity: `device/rpi1001//` is auto-registered as an **immediate child device** of the main device
20+
before the `cpu_usage` measurement is associated to it.
21+
22+
Similarly, publishing to `te/device/rpi1002/service/collectd/m/cpu_usage` would result in the auto-registration of
23+
both the `child-device` entity: `device/rpi1002//` and its `service` entity: `device/rpi1002/service/collectd`.
24+
25+
The auto-registered entities are persisted with the local MQTT broker by the `tedge-agent` with their auto-generated registration messages.
26+
For example, the child device `device/rpi1002//` is registered as follows:
27+
28+
```sh te2mqtt formats=v1
29+
tedge mqtt pub -r 'te/device/rpi1002//' '{
30+
"@type": "child-device",
31+
"@parent":"device/main//",
32+
"name": "rpi1002",
33+
}'
34+
```
35+
36+
Similarly, the service: `device/rpi1002/service/collectd` is registered as follows:
37+
38+
```sh te2mqtt formats=v1
39+
tedge mqtt pub -r 'te/device/rpi1002/service/collectd' '{
40+
"@type": "service",
41+
"@parent":"device/rpi1002//",
42+
"name": "collectd",
43+
}'
44+
```
45+
46+
:::note
47+
The %%te%% main device is pre-registered with the reserved default topic identifier: `device/main//`.
48+
:::
49+
50+
## Configuration
51+
52+
The auto-registration feature is turned on by default, ideal for simple fleets with only a single level of child devices,
53+
as auto-registered child devices are always linked to the main device as its immediate children.
54+
If your device fleet has a nested hierarchy of child devices spanning multiple levels, then auto-registration must be turned off,
55+
to prevent all child devices(even the nested ones) wrongly getting auto-registered as immediate children of the main device.
56+
57+
Auto-registration can be turned off with a configuration setting as follows:
58+
59+
```sh
60+
tedge config set agent.entity_store.auto_register false
61+
```
62+
63+
After this configuration change, the `tedge-agent` must be restarted for it to take effect.
64+
65+
Turning off auto-registration can be beneficial in certain other scenarios as well:
66+
- If the default topic scheme does not match your fleet, and you'd like to use your own [custom topic scheme](../../contribute/design/mqtt-topic-design.md#using-custom-identifier-schemas) for your entities (e.g: `factory1/floor1/painting/robot1`)
67+
- You still want to use the default topic scheme, but need more control over the metadata of the entities that are registered,
68+
like registering every entity with an explicit `@id` or having the entities registered with some initial twin data.
69+
70+
:::caution
71+
Combining auto-registration with explicit registration using the MQTT API is highly discouraged,
72+
as it can lead to unexpected results like nested child devices getting auto-registered as immediate child devices,
73+
or services getting registered under the wrong parent device.
74+
If explicit registration is required in a deployment where auto-registration is already enabled,
75+
using the HTTP registration API is recommended, before any telemetry data is published by those clients.
76+
:::

‎docs/src/operate/entity-management/index.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Entity Management
3+
tags: [Registration, Deregistration]
4+
sidebar_position: 11
5+
---
6+
7+
import DocCardList from '@theme/DocCardList';
8+
9+
%%te%% provides APIs to manage all the entities (child devices and services) attached to a main device.
10+
- Create/Register entities with metadata describing their role and relationship.
11+
- Read/Fetch entity metadata
12+
- Update entity metadata
13+
- Delete/Deregister entities
14+
15+
%%te%% provides two different flavors of this API, with the same core functionality but optimized for different use cases
16+
- HTTP API: For request/response interactions where actual responses drive subsequent requests (e.g. start sending telemetry data only when the registration is complete)
17+
- MQTT API: For event-driven interactions where the point is to notify and react to changes (e.g. maintain in the cloud a twin representation of the device with its services and child devices)
18+
19+
%%te%% also provides an entity [auto-registration mechanism](./auto-registration.md) that automatically registers entities
20+
on receipt of the very first message from them, without waiting for an explicit registration.
21+
This is critical for simple devices like sensors that just emits telemetry data,
22+
but does not support an entity registration logic to be programmed into them.
23+
24+
<DocCardList />

‎docs/src/operate/entity-management/mqtt_api.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: MQTT API
3+
tags: [Child-Device, Registration]
4+
sidebar_position: 1
5+
description: Register child devices and services with MQTT
6+
---
7+
8+
# MQTT API for Entity Management
9+
10+
%%te%% provides an MQTT API to manage all the entities (devices and services) attached to a main device.
11+
These interfaces let you create, update and delete entities as well as observe changes.
12+
13+
When compared to the HTTP API, the MQTT API excels at notifying subscribers in real-time about entity-related changes
14+
such as creation, updates, or deletion of child devices and services.
15+
However, unlike the HTTP API, the MQTT API doesn't provide immediate feedback on whether an operation succeeded or failed,
16+
making it less suitable for scenarios where confirmation is crucial.
17+
For example, when an entity registration is attempted by publishing the metadata payload,
18+
there is no feedback on whether the registration succeeded or not.
19+
20+
## Create a new entity {#create-entity}
21+
22+
A new entity can be registered by publishing the entity definition to the MQTT topic that contains the **entity topic identifier**.
23+
The payload must contain at least the `@type` of the entity: whether it is a `child-device` or `service`.
24+
25+
:::note
26+
The supported `@type` values are `device`, `child-device` and `service`.
27+
The `device` type is reserved for the main %%te%% device which is pre-registered when it is bootstrapped.
28+
:::
29+
30+
Other supported (optional) fields in the registration payload include:
31+
32+
- `@parent`: Topic ID of the parent entity.
33+
Required for nested child devices or services where the parent cannot be derived from the topic.
34+
- `@id`: External ID for the entity.
35+
- `@health`: Topic ID of the health endpoint service of this entity.
36+
Valid only for `child-device` entities.
37+
By default, it is the `tedge-agent` service on that device.
38+
39+
Any additional fields included in the payload are considered as initial [twin data](../../references/mqtt-api.md#twin-metadata) for that entity,
40+
and they are re-published to the corresponding twin topics.
41+
42+
### Example: Create a new child device
43+
44+
Register as a child device with the name "child0". Assign the child device to the main device (`device/main//`) and give it the topic-id of `device/child0//` which will be used to reference it in all other API calls (both for REST and MQTT).
45+
46+
```sh te2mqtt formats=v1
47+
tedge mqtt pub -r 'te/device/child0//' '{
48+
"@type": "child-device"
49+
}'
50+
```
51+
52+
### Example: Create a service under a child device
53+
54+
Register `device/child0/service/nodered` as a service of `device/child0//`:
55+
56+
```sh te2mqtt formats=v1
57+
tedge mqtt pub -r 'te/device/child0/service/nodered' '{
58+
"@type": "service"
59+
}'
60+
```
61+
62+
When the topic id of the service follows the default topic scheme (`te/device/<device_id>/service/<service_id>`),
63+
the parent of the service is derived from the topic itself (`device/child0//` in this case).
64+
If a custom topic scheme is used, then the parent is assumed to be `device/main//` by default, when not specified.
65+
66+
### Example: Create a nested child device
67+
68+
Register `device/child01//` as a child device of `device/child0//` which is specified as the `@parent`:
69+
70+
```sh te2mqtt formats=v1
71+
tedge mqtt pub -r 'te/device/child01//' '{
72+
"@type": "child-device",
73+
"@parent": "device/child0",
74+
}'
75+
```
76+
77+
When the `@parent` is not specified for a child device, it is assumed to be the main device.
78+
79+
### Example: Create a child device with an external id
80+
81+
Register `device/child01//` as a child device of the main device with a unique id: `XYZ001:child01`:
82+
83+
```sh te2mqtt formats=v1
84+
tedge mqtt pub -r 'te/device/child01//' '{
85+
"@type": "child-device",
86+
"@id": "XYZ001:child01"
87+
}'
88+
```
89+
90+
This `@id` is used to uniquely identify an entity from others.
91+
For example, the cloud mappers use this unique id to register these entities with the cloud.
92+
When an `@id` is not provided, the mappers are free to compute a unique id from their topic id, which is also unique.
93+
94+
### Example: Create a child device with initial twin data
95+
96+
Register `device/child01//` with initial twin values: `name` and `type`.
97+
98+
```sh te2mqtt formats=v1
99+
tedge mqtt pub -r 'te/device/child01//' '{
100+
"@type": "child-device",
101+
"name": "Child 01",
102+
"type": "Raspberry Pi 4"
103+
}'
104+
```
105+
106+
Unlike the reserved keys like `@type`, %%te%% does not interpret these twin keys in any special way.
107+
For example, the `type` value here captures the type of the device and has nothing to do with the entity `@type`.
108+
They are just re-published to their corresponding twin topics (`twin/name` and `twin/type`) as-is.
109+
So, the values can be any valid twin values.
110+
111+
:::warning
112+
Using the `@` prefix for such twin data keys is discouraged as this prefix is reserved by %%te%%.
113+
:::
114+
115+
## Get an entity {#get-entity}
116+
117+
Get an entity's metadata (e.g. default name and type, and parent).
118+
119+
### Example: Get a child device
120+
121+
Get the child device `device/child0//`:
122+
123+
```sh te2mqtt formats=v1
124+
tedge mqtt sub 'te/device/child0//' --count 1
125+
```
126+
127+
:::note
128+
The `--count` value of `1` is used to exit the `tedge mqtt sub` program once the metadata message is received.
129+
:::
130+
131+
### Example: Get all devices/child-devices/services
132+
133+
Fetch the metadata of all registered entities:
134+
135+
```sh te2mqtt formats=v1
136+
tedge mqtt sub 'te/+/+/+/+' --duration 1s
137+
```
138+
139+
:::note
140+
The `--duration` value of `1s` is used to exit the `tedge mqtt sub` program once all the entity metadata messages are received.
141+
If the number of entities are too high, adjust this timeout accordingly to ensure that all messages are received.
142+
:::
143+
144+
## Update an entity {#update-entity}
145+
146+
An entity definition can be updated by publishing the new entity definition, replacing the existing one.
147+
Updates are limited to the `@parent` and `@health` properties only,
148+
so other properties like `@type` and `@id` cannot be updated after the registration.
149+
150+
:::note
151+
The complete definition of the new entity must be provided in the payload
152+
unlike the [HTTP PATCH API](./http_api.md#update-entity), that accepts the specific fragments to be updated.
153+
:::note
154+
155+
### Example: Update the parent of an entity
156+
157+
Update the parent of the entity `device/child01//` by making it a child of `device/child0//`:
158+
159+
```sh te2mqtt formats=v1
160+
tedge mqtt pub -r 'te/device/child01//' '{
161+
"@type": "child-device",
162+
"@parent": "device/child0",
163+
}'
164+
```
165+
166+
## Delete an entity {#delete-entity}
167+
168+
An entity and its descendants (immediate children and nested children) can be deregistered by publishing
169+
an empty retained messages to the MQTT topic corresponding to its entity topic identifier.
170+
171+
### Example: Delete a child device
172+
173+
Remove a child device and any of its children.
174+
175+
```sh te2mqtt formats=v1
176+
tedge mqtt pub -r 'te/device/child01//' ''
177+
```
178+
179+
:::note
180+
The deregistration of descendant entities is done asynchronously by the `tedge-agent`
181+
and hence the completion time would vary based on how deep the hierarchy is.
182+
Using the [HTTP API](./http_api.md#delete-entity) is recommended for deregistration as it provides clear feedback on completion.
183+
:::

0 commit comments

Comments
 (0)