New thin-edge.io 0.6 with support for alarms and events, certified by Cumulocity IoT

We’re happy to announce the new thin-edge.io 0.6 version with added support for two new data types named alarms and events, on top of the measurements data support that we had already. In addition to that, we’ve also extended our init system support beyond systemd with out-of-the-box support for BSD and OpenRC that can be extended to any other init system as well. Last but not the least, thin-edge.io is now a Cumulocity IoT cloud certified agent.

Now, let’s dive deep into each of these enhancements in detail.

Data model enhancements

Based on your feedback to support data types beyond numerical value measurements, we’ve added support for not only one but two new data types: events and alarms.

Events

Events on thin-edge.io can be used to trigger signals when some event happens in the system. For example, a person entering a room or someone logging into a machine can all be represented as events. An event can be triggered on thin-edge.io by sending an MQTT message in Thin Edge JSON format to tedge/events/<type> MQTT topics. Every event is uniquely identified by its type mentioned in the MQTT topic.

For example, a login_event can be triggered from thin-edge.io by publishing any valid JSON payload to tedge/events/login_event topic as follows:

{
    "text": "A user just logged in",
    "time": "2021-01-01T05:30:45+00:00",
    "username": "albin",
    "as_admin": false,
    "user": {
        "name": "Albin",
        "id": 9786
    }
}

The payload doesn’t have any mandatory fields and can include any valid JSON data. But, the text and time fields are considered special based on the cloud that you're connected to. For example, when connected to Cumulocity IoT cloud, these fields are used as the Cumulocity IoT event's text and timestamp respectively.

To illustrate how this works, the event shown above can be sent from a thin-edge.io device connected to Cumulocity IoT cloud with the following command:

tedge mqtt pub tedge/events/login_event '{ "text": "A user just logged in", "time": "2021-01-01T05:30:45+00:00", "username": "albin", "as_admin": false, "user": {"id": 9876, "name": "Albin"} }'

Here is how the event will appear in the Cumulocity IoT device events dashboard:

For more information on this feature refer to our official documentation here.

Alarms

Alarms on thin-edge.io can be used to create alerts, represent state changes, etc. For example, an alarm can be raised when a certain measurement value breaches some threshold (like high temperature) or when an unexpected event occurs in the system (like a sensor failure). A raised alarm needs to be cleared explicitly by a human or automated system once some action is taken in response to that alarm.

An alarm is raised by sending an MQTT message in Thin Edge JSON format to tedge/alarms/<severity>/<type> MQTT topics. Every alarm is uniquely identified by its type and severity. That is, for a given alarm type, alarms of varying severities are treated as independent alarms and hence, must be acted upon separately.

For example, a high temperature alarm of critical severity can be raised by publishing the following Thin Edge JSON payload to tedge/alarms/critical/temperature_high topic as a retained message:

{
    "text": "Temperature is very high",
    "time": "2021-01-01T05:30:45+00:00"
}

Unlike event payload, the alarm payload is not as open, but only supports these text and time fields with both being optional. When connected to Cumulocity IoT cloud, these fields are used as the Cumulocity IoT alarm's text and timestamp respectively.

To illustrate how this works, the alarm shown above can be sent from a thin-edge.io device connected to Cumulocity IoT cloud with the following command:

tedge mqtt pub tedge/alarms/critical/temperature_high '{ "text": "Temperature is very high", "time": "2021-01-01T05:30:45+00:00" }'

Here is how this temperature alarm will appear in the Cumulocity IoT device alarms dashboard:

For more information on this feature refer to our official documentation here.

Support for init systems beyond systemd

Support for any init system other than systemd was another major addition in this release. Out-of-the-box support exists for BSD and OpenRC systems in addition to systemd. But, it can easily be extended to any other init system with some minimal configuration.

All you have to do is to create a simple toml file at /etc/tedge/system.toml with some content as follows:

[init]
name = "OpenRC"
is_available = ["/sbin/rc-service", "-l"]
restart = ["/sbin/rc-service", "{}", "restart"]
stop =  ["/sbin/rc-service", "{}", "stop"]
enable =  ["/sbin/rc-update", "add", "{}"]
disable =  ["/sbin/rc-update", "delete", "{}"]
is_active = ["/sbin/rc-service", "{}", "status"]

This is the system.toml file for supporting openrc

Each line represents the service actions that thin-edge.io uses to interact with external services, with the key representing the action and the value containing the command to be executed to perform that action. The {} placeholder will be replaced by the appropriate service name by thin-edge.io. For example, the mosquitto service will be restarted on an OpenRC system using the /sbin/rc-service mosquitto restart command.

For more information on this feature refer to our official documentation here.

Cumulocity IoT certified device agent

Using this new 0.6 version, you can self-certify your thin-edge.io device integration for Cumulocity IoT cloud. All you have to do is to create a simple JSON file at /etc/tedge/device/inventory.json as root user, with some basic device information as follows:

{
  "c8y_RequiredAvailability": {
      "responseInterval": 5
  },
  "c8y_Firmware": {
      "name": "raspberrypi-bootloader",
      "version": "1.20140107-1",
      "url": "31aab9856861b1a587e2094690c2f6e272712cb1"
  },
  "c8y_Hardware": {
      "model": "BCM2708",
      "revision": "000e",
      "serialNumber": "00000000e2f5ad4d"
  }
}

Once this file is created, you can connect your device to the Cumulocity IoT cloud, run the certification process and view your device certification results, like shown below: