feat(mqtt): add docs for tedge data/inventory topic

Signed-off-by: Reuben Miller <[email protected]>
thin-edge · Sep 22, 2023 · ff0a810 · ff0a810
1 parent 09b7d30
commit ff0a810
Show file tree

Hide file tree

Showing 4 changed files with 341 additions and 0 deletions.
diff --git a/docs/src/references/mappers/c8y-mapper.md b/docs/src/references/mappers/c8y-mapper.md
@@ -568,6 +568,305 @@ c8y/alarm/alarms/create
 
 </div>
 
+### Data
+
+The data telemetry type can be used to store additional information about the device/child/service. Such information could included; operation system name/version, communication statistics, device status, or any other information that is not suited to measurements, events or alarms.
+
+#### Data - Main device
+
+A device's digital twin model can be updated by publishing to a specific topic.
+
+The type part of the topic is used to group the data so it is easier for components to subscribe to relevant parts.
+
+<div class="code-indent-left">
+
+**Thin Edge (input)**
+
+```text title="Topic (retain=true)"
+te/device/main///data/device_OS
+```
+
+```json5 title="Payload"
+{
+  "family": "Debian",
+  "version": "11"
+}
+```
+
+</div>
+
+<div class="code-indent-right">
+
+**Cumulocity IoT (output)**
+
+```text title="Topic"
+c8y/inventory/managedObjects/update/<main-device-id>
+```
+
+```json5 title="Payload"
+{
+  "device_OS": {
+    "family": "Debian",
+    "version": "11"
+  }
+}
+```
+
+</div>
+
+
+#### Data - root
+
+Data can be added on the root level by leaving the type value in topic blank but still using a trailing slash.
+
+Some property names are forbidden and will be ignored if they are included in the payload. This is to avoid setting the property values from two different sources.
+
+* `name`
+* `type`
+
+Note: The payload should be restricted to the following data types:
+
+* string
+* boolean
+* number
+
+For complex data types like arrays and objects, these data types should be published to the typed topics.
+
+<div class="code-indent-left">
+
+**Thin Edge (input)**
+
+```text title="Topic (retain=true)"
+te/device/main///data/
+```
+
+```json5 title="Payload"
+{
+  "subtype": "my-custom-type"
+}
+```
+
+</div>
+
+<div class="code-indent-right">
+
+**Cumulocity IoT (output)**
+
+```text title="Topic"
+c8y/inventory/managedObjects/update/<main-device-id>
+```
+
+```json5 title="Payload"
+{
+  "subtype": "my-custom-type"
+}
+```
+
+</div>
+
+#### Data - Child Device
+
+<div class="code-indent-left">
+
+**Thin Edge (input)**
+
+```text title="Topic (retain=true)"
+te/device/child01///data/device_OS
+```
+
+```json5 title="Payload"
+{
+  "family": "Debian",
+  "version": "11"
+}
+```
+
+</div>
+
+<div class="code-indent-right">
+
+**Cumulocity IoT (output)**
+
+```text title="Topic"
+c8y/inventory/managedObjects/update/<main-device-id>:device:child01
+```
+
+```json5 title="Payload"
+{
+  "device_OS": {
+    "family": "Debian",
+    "version": "11"
+  }
+}
+```
+
+</div>
+
+#### Data - Service on Main Device
+
+<div class="code-indent-left">
+
+**Thin Edge (input)**
+
+```text title="Topic (retain=true)"
+te/device/main/service/tedge-agent/data/runtime_stats
+```
+
+```json5 title="Payload"
+{
+  "memory": 3024,
+  "uptime": 86400
+}
+```
+
+</div>
+
+<div class="code-indent-right">
+
+**Cumulocity IoT (output)**
+
+```text title="Topic"
+c8y/inventory/managedObjects/update/<main-device-id>:device:main:service:tedge-agent
+```
+
+```json5 title="Payload"
+{
+  "runtime_stats": {
+    "memory": 3.3,
+    "uptime": 86400
+  }
+}
+```
+
+</div>
+
+
+#### Data - Service on Child Device
+
+<div class="code-indent-left">
+
+**Thin Edge (input)**
+
+```text title="Topic (retain=true)"
+te/device/child01/service/tedge-agent/data/runtime_stats
+```
+
+```json5 title="Payload"
+{
+  "memory": 3.3,
+  "uptime": 86400
+}
+```
+
+</div>
+
+<div class="code-indent-right">
+
+**Cumulocity IoT (output)**
+
+```text title="Topic"
+c8y/inventory/managedObjects/update/<main-device-id>:device:child01:service:tedge-agent
+```
+
+```json5 title="Payload"
+{
+  "runtime_stats": {
+    "memory": 3.3,
+    "uptime": 86400
+  }
+}
+```
+
+</div>
+
+
+#### Data - Deleting a fragment
+
+<div class="code-indent-left">
+
+**Thin Edge (input)**
+
+```text title="Topic (retain=true)"
+te/device/child01/service/tedge-agent/data/runtime_stats
+```
+
+```json5 title="Payload"
+<<empty>>
+```
+
+</div>
+
+<div class="code-indent-right">
+
+**Cumulocity IoT (output)**
+
+```text title="Topic"
+c8y/inventory/managedObjects/update/<main-device-id>:device:child01:service:tedge-agent
+```
+
+```json5 title="Payload"
+{
+  "runtime_stats": null
+}
+```
+
+</div>
+
+
+#### Data - Deleting a root fragment
+
+When deleting the root fragments on the `/data/` topic, the mapper will have to keep track of the previously published value before the delete request is published. All the properties should have their values set to `null` and included in the published.
+
+For the example mapping, it assumes that the following message was already published before the deletion message was received.
+
+```text title="Topic (retain=true)"
+te/device/child01/service/tedge-agent/data/
+```
+
+```json5 title="Payload"
+<<empty>>
+{
+  "subtype": "foo",
+  "other": "bar"
+}
+```
+
+<div class="code-indent-left">
+
+**Thin Edge (input)**
+
+```text title="Topic (retain=true)"
+te/device/child01/service/tedge-agent/data/
+```
+
+```json5 title="Payload"
+<<empty>>
+{
+  "subtype": null,
+  "other": null
+}
+```
+
+</div>
+
+<div class="code-indent-right">
+
+**Cumulocity IoT (output)**
+
+```text title="Topic"
+c8y/inventory/managedObjects/update/<main-device-id>:device:child01:service:tedge-agent
+```
+
+```json5 title="Payload"
+{
+  "subtype": null,
+  "other": null
+}
+```
+
+</div>
+
+
 ## Operations/Commands
 
 Operations from Cumulocity are mapped to their equivalent commands in Thin Edge format.

diff --git a/docs/src/references/mqtt-api.md b/docs/src/references/mqtt-api.md
@@ -435,6 +435,7 @@ so that it can process them.
 |Measurements|`te/<identifier>/m/<measurement-type>`|
 |Events|`te/<identifier>/e/<event-type>`|
 |Alarms|`te/<identifier>/a/<alarm-type>`|
+|Data|`te/<identifier>/data/<data-type>`|
 
 ### Examples: With default device/service topic semantics
 

diff --git a/tests/RobotFramework/tests/cumulocity/telemetry/child_device_telemetry.robot b/tests/RobotFramework/tests/cumulocity/telemetry/child_device_telemetry.robot
@@ -70,6 +70,27 @@ Child devices support sending inventory data via c8y topic
     Should Be Equal    ${mo["custom"]["fragment"]}    yes
 
 
+Child devices support sending inventory data via tedge topic with type
+    Execute Command    tedge mqtt pub "te/device/${CHILD_SN}///data/device_OS" '{"family":"Debian","version":11,"complex":[1,"2",3],"object":{"foo":"bar"}}'
+    Cumulocity.Set Device    ${CHILD_SN}
+    ${mo}=    Device Should Have Fragments    device_OS
+    Should Be Equal    ${mo["device_OS"]["family"]}    Debian
+    Should Be Equal As Integers    ${mo["device_OS"]["version"]}    11
+
+    Should Be Equal As Integers    ${mo["device_OS"]["complex"][0]}    1
+    Should Be Equal As Strings    ${mo["device_OS"]["complex"][1]}    2
+    Should Be Equal As Integers    ${mo["device_OS"]["complex"][2]}    3
+    Should Be Equal    ${mo["device_OS"]["object"]["foo"]}    bar
+
+
+Child devices supports sending inventory data via tedge topic to root fragments
+    Execute Command    tedge mqtt pub "te/device/${CHILD_SN}///data/" '{"subtype":"LinuxDeviceA","type":"ShouldBeIgnored"}'
+    Cumulocity.Set Device    ${CHILD_SN}
+    ${mo}=    Device Should Have Fragments    subtype
+    Should Be Equal    ${mo["subtype"]}    LinuxDeviceA
+    Should Be Equal    ${mo["type"]}    thin-edge.io
+
+
 Child device supports sending custom child device measurements directly to c8y
     Execute Command    tedge mqtt pub "c8y/measurement/measurements/create" '{"time":"2023-03-20T08:03:56.940907Z","externalSource":{"externalId":"${CHILD_SN}","type":"c8y_Serial"},"environment":{"temperature":{"value":29.9,"unit":"°C"}},"type":"10min_average","meta":{"sensorLocation":"Brisbane, Australia"}}'
     Cumulocity.Set Device    ${CHILD_SN}

diff --git a/tests/RobotFramework/tests/cumulocity/telemetry/thin-edge_device_telemetry.robot b/tests/RobotFramework/tests/cumulocity/telemetry/thin-edge_device_telemetry.robot
@@ -130,6 +130,26 @@ Thin-edge device support sending inventory data via c8y topic
     Should Be Equal    ${mo["subType"]}    customType
 
 
+Thin-edge device support sending inventory data via tedge topic
+    Execute Command    tedge mqtt pub "te/device/main///data/device_OS" '{"family":"Debian","version":11,"complex":[1,"2",3],"object":{"foo":"bar"}}'
+    Cumulocity.Set Device    ${DEVICE_SN}
+    ${mo}=    Device Should Have Fragments    device_OS
+    Should Be Equal    ${mo["device_OS"]["family"]}    Debian
+    Should Be Equal As Integers    ${mo["device_OS"]["version"]}    11
+
+    Should Be Equal As Integers    ${mo["device_OS"]["complex"][0]}    1
+    Should Be Equal As Strings    ${mo["device_OS"]["complex"][1]}    2
+    Should Be Equal As Integers    ${mo["device_OS"]["complex"][2]}    3
+    Should Be Equal    ${mo["device_OS"]["object"]["foo"]}    bar
+
+
+Thin-edge device supports sending inventory data via tedge topic to root fragments
+    Execute Command    tedge mqtt pub "te/device/main///data/" '{"subtype":"LinuxDeviceA","type":"ShouldBeIgnored"}'
+    Cumulocity.Set Device    ${DEVICE_SN}
+    ${mo}=    Device Should Have Fragments    subtype
+    Should Be Equal    ${mo["subtype"]}    LinuxDeviceA
+    Should Be Equal    ${mo["type"]}    thin-edge.io
+
 *** Keywords ***
 
 Custom Setup