Enhanced device management with thin-edge.io 0.5

Published in

thin-edge.io

7 min readJan 24, 2022

Enhancements include device hierarchy in data, extensible device capabilities declaration, log file uploading, and cloud mapper extensions

With the latest release of thin-edge.io we have reached another significant milestone. The new features provide an increased level of sophistication in monitoring and controlling IoT devices:

Inclusion of device hierarchy in telemetry data
Extensible device capability declaration
Triggering device restart locally and remotely
Uploading software management log files
Extensions of the Cumulocity IoT reference mapper

thin-edge.io Community Meetup #2 | Feb 3, 16:00 CET

Inclusion of device hierarchy in telemetry data

thin-edge.io has supported sending telemetry data to many cloud IoT platforms from release 0.1. However, there are instances where the telemetry data needs to be identified as originating from a particular location in the device hierarchy, typically either gateway or a sensor endpoint. As the monitoring of telemetry data sent from end points is one of the most requested features, we are happy to introduce device hierarchy support in thin-edge.io 0.5.

For this quick tutorial we start with thin-edge.io already having connected your parent device (e.g., gateway) to Cumulocity IoT. To do this, please refer to our user guide and complete until `tedge connect c8y`.

Make sure that your device appears in your Cumulocity IoT tenant. Also, it’s good to check if tedge-mapper-c8y service is up. Run this command to check the status:

$ sudo systemctl status tedge-mapper-c8y.service

Now that all preparation is done, we need to assign an ID to the child device, which must be unique for your Cumulocity IoT tenant. Here, let us use “child_device_blog_0.5” as a child device ID.

Next use thin-edge.io to publish a message onto the topic tedge/measurements/child_device_blog_0.5 with the payload {“temperature”: 23}.

$ sudo tedge mqtt pub ‘tedge/measurements/child_device_blog_0.5’ ‘{“temperature”: 23}’

Then, check your device on Cumulocity IoT. You can see “Child devices” tab and the child device “child_device_blog_0.5” has been created.

Also, you can find “temperature” “23” is recorded from “Measurements” tab of the child device.

The payload format is thin-edge.io JSON, the same as the case of sending telemetry data to a parent device. To get know more about the payload format, look at our guide.

Extensible device capabilities declaration

Earlier releases of thin-edge.io supported commands (or operations) in a rudimentary manner. In release 0.5 we introduced a flexible way of declaring the capabilities of a device, so they can be reported to IoT platforms.

Taking Cumulocity IoT as an example, this means the device can now report its supported capabilities (like the ability to handle restarts, software updates) to Cumulocity IoT, which in the case of Cumulocity IoT leads to appropriate device management features to be available in the device management application.

The supported operations can be configured as file names located under /etc/tedge/operations/c8y and will be reported by the Cumulocity IoT mapper (tedge-mapper-c8y) to the corresponding tenant:

$ ls -l /etc/tedge/operations/c8y/
total 0
-rw-rw-r — 1 tedge 0 Dec 8 21:14 c8y_LogfileRequest
-rw-rw-r — 1 tedge 0 Dec 8 21:14 c8y_Restart
-rw-rw-r — 1 tedge tedge 0 Dec 8 21:14 c8y_SoftwareUpdate

In this example, c8y_LogfileRequest, c8y_Restart, and c8y_SoftwareUpdate will be reported to Cumulocity IoT at the start of tedge-mapper-c8y. That means, that information will be sent after you run `tedge connect c8y`.

To add a new supported operation, simply create a new empty file with the file name of the supported operation. Note that this file should be owned by tedge user and group, and file permission should be at least 644.

Let’s add a new supported operation “c8y_Command” to the demo device. Run this command.

$ sudo -u tedge touch /etc/tedge/operations/c8y/c8y_Command

Now you see that the new file is added to /etc/tedge/operations/c8y/.

$ ls –ltr
total 0
-rw-r — r — 1 tedge tedge 0 Jan 5 10:15 c8y_SoftwareUpdate
-rw-r — r — 1 tedge tedge 0 Jan 5 10:15 c8y_Restart
-rw-r — r — 1 tedge tedge 0 Jan 5 10:15 c8y_LogfileRequest
-rw-rw-r — 1 tedge tedge 0 Jan 7 11:11 c8y_Command

Restart the tedge-mapper-c8y service if a device is already connected to Cumulocity IoT by the following command. If you didn’t run `tedge connect c8y` before, first run `sudo tedge connect c8y` instead of restarting the tedge-mapper-c8y service.

$ sudo systemctl restart tedge-mapper-c8y.service

All preparation in the device side is done! Let’s check your Cumulocity IoT tenant and the device. You will find “Shell” tab newly as we declared “c8y_Command” as a supported operation.

If you want to remove some supported operation, we can also do it by removing a file. Let’s remove the “c8y_Command” from the device supported operations.

Remove the file by running:

$ sudo rm /etc/tedge/operations/c8y/c8y_Command

Then restart the tedge-mapper-c8y service again.

$ sudo systemctl restart tedge-mapper-c8y.service

That’s all what you need. Let’s check the Cumulocity IoT. There was “Shell” between “Service monitoring” and “Identity”, however, now the “Shell” is gone because we removed “c8y_Command” from the supported operations.

Triggering device restart locally and remotely

In the 0.5 release, thin-edge.io allows you to restart a device from your cloud IoT platform or another authorized local process in the device.

Case 1: Execute a device restart from Cumulocity IoT

We start with your parent device already connected to Cumulocity IoT using thin-edge.io. If not, please refer to our user guide and complete until `tedge connect c8y`. Make sure that your device appears in your Cumulocity IoT tenant.

Make sure that tedge-agent.service and tedge-mapper-sm-c8y.service are running. You can check using systemctl.

$ sudo systemctl status tedge-mapper-sm-c8y.service
$ sudo systemctl status tedge-agent.service

The preparation on thin-edge.io side is done. Go to “Control” tab and click “More” and “Restart device” in the top right of the Cumulocity IoT Device Management app.

This will trigger Cumulocity IoT to send a restart operation to the thin-edge.io device, and after the device reboot, the operation will be marked SUCCESSFUL.

Case 2: Execute a device restart from a local process

thin-edge.io also now allows authorised device processes to trigger a device restart. To do this the local processes just need to publish a message to the local MQTT bus. Please note that tedge-agent.service should be running.

Publish a JSON message with only “id” field onto the topic tedge/commands/req/control/restart. For example,

$ sudo tedge mqtt pub ‘tedge/commands/req/control/restart’ ‘{“id”: “1234”}’

After this command, the device starts restating immediately.

Uploading software management log files

When attempting to perform a software update you may have encountered a failed operation. Perhaps with the error message “1 error, see device log file /var/log/tedge/agent/software-update-2022–01–07T10:45:34Z.log”. One option to diagnose this error is remotely access your device and check the log file. However, being able to review the log file contents remotely from an IoT platform would be far more efficient. This is exactly why from release 0.5 we allow you to see the software management logs from your cloud IoT platform, initially Cumulocity IoT!

Now let’s look at another example: In the Cumulocity IoT Device Management app click the “Log” tab and click “Request log file”.

Select the time range that includes the timestamp of your desired log file. For example, if you want to get a log ” /var/log/tedge/agent/software-update-2022–01–07T10:45:34Z.log”, you can select

From: 2022–01–06 13:40
To: 2022–01–07 13:40

This time range contains the time “2022–01–07T10:45:34Z”. Then, choose “software-management” as “Type of log”. “Filter by text” is optional. If you enter some keyword there, you’ll see lines only containing the keyword. The field “Last lines to display” is mandatory, 1000 should be enough.

Press “Request log”, then immediately you can get the log file from your device.

Also, an event is created. If you go to the ”Events” tab, you can see the corresponded event has been created.

If multiple software management log files are matched to the provided time range, the tedge-agent merges all those log files into one file and uploads the merged file to Cumulocity IoT.

The uploaded log always contains the original log file name as the first line before the log file contents.