Tutorials

Connect your device to Cumulocity IoT

To enable thin-edge.io you first must connect your device to the cloud. This is a 10 minutes operation to be done only once. It establishes a permanent connection from your device to the cloud endpoint. This connection is secure (encrypted over TLS), and the two peers are identified by x509 certificates. Sending data to the cloud will then be as simple as sending data locally.

The focus here is on connecting to Cumulocity IoT. See Connect your device to Azure IoT, if you want to connect Azure IoT instead.

Before you connect your device to Cumulocity IoT, you need the URL of the endpoint to connect to (e.g. eu-latest.cumulocity.com) and your credentials to connect to Cumulocity IoT, which are your tenant identifier (e.g. t00000007), a username and password. None of these credentials will be stored on the device. These are only required once, to register the device.

If not done yet, install thin-edge.io on your device.

You can now use the tedge command to:

Configure the device

To connect the device to Cumulocity IoT, you need to set the URL of your Cumulocity IoT tenant and the root certificate as below.

Set the URL of your Cumulocity IoT tenant.

$ sudo tedge config set c8y.url your-tenant.cumulocity.com

Set the path to the root certificate if necessary. The default is /etc/ssl/certs.

$ sudo tedge config set c8y.root.cert.path /etc/ssl/certs

This will set the root certificate path of Cumulocity IoT. In most of the Linux flavors, the certificate will be present in /etc/ssl/certs. If not found download it from https://www.identrust.com/dst-root-ca-x3.

Create the certificate

The tedge cert create command creates a self-signed certificate which can be used for testing purpose.

A single argument is required: an identifier for the device. This identifier will be used to uniquely identify your devices among others in your cloud tenant. This identifier will also be used as the Common Name (CN) of the certificate. Indeed, this certificate aims to authenticate that this device is actually the device with that identity.

$ sudo tedge cert create --device-id my-device

You can then check the content of this certificate.

$ sudo tedge cert show
Device certificate: /etc/tedge/device-certs/tedge-certificate.pem
Subject: CN=my-device, O=Thin Edge, OU=Test Device
Issuer: CN=my-device, O=Thin Edge, OU=Test Device
Valid from: Tue, 09 Feb 2021 17:16:52 +0000
Valid up to: Tue, 11 May 2021 17:16:52 +0000
Thumbprint: CDBF4EC17AA02829CAC4E4C86ABB82B0FE423D3E

The issuer of this certificate is the device itself. This is a self-signed certificate. To use a certificate signed by your certificate authority, see Developer tools > Command Line Interface (CLI) > tedge cert command.

Make the device trusted by Cumulocity IoT

For a certificate to be trusted by Cumulocity IoT, you need to add the certificate of the signing authority to the list of trusted certificates. In the Cumulocity IoT UI, navigate to Management > Trusted certificates in the Device Management application in order to see this list for your Cumulocity IoT tenant.

Here, the device certificate is self-signed and has to be directly trusted by Cumulocity IoT. This can be done in two ways:

$ sudo tedge cert upload c8y --user <username>

Connect the device

Now, you are ready to run tedge connect c8y. This command configures the MQTT broker:

Also, if you have installed tedge_mapper, this command starts and enables the tedge-mapper-c8y systemd service. At last, it sends packets to Cumulocity IoT to check the connection. If your device is not yet registered, you will find the digital-twin created in your tenant after tedge connect c8y!

$ sudo tedge connect c8y
Checking if systemd is available.

Checking if configuration for requested bridge already exists.

Validating the bridge certificates.

Saving configuration for requested bridge.

Restarting mosquitto service.

Awaiting mosquitto to start. This may take up to 5 seconds.

Persisting mosquitto on reboot.

Successfully created bridge connection!

Checking if tedge-mapper is installed.

Starting tedge-mapper service.

Persisting tedge-mapper on reboot.

tedge-mapper service successfully started and enabled!

Sending packets to check connection. This may take up to 10 seconds.

Try 1 / 2: Sending a message to Cumulocity IoT. ... No response. If the device is new, it's normal to get no response in the first try.
Try 2 / 2: Sending a message to Cumulocity IoT. Received expected response message, connection check is successful.

Sending your first telemetry data

To send data to Cumulocity IoT use MQTT over topics prefixed with c8y. Any messages sent to one of these topics are forwarded to Cumulocity IoT. The messages must have a format specific to each topic. We use tedge mqtt pub, a raw Cumulocity IoT SmartRest message to be understood as a temperature of 20 Celsius.

$ tedge mqtt pub c8y/s/us 211,20

To check that this message has been received by Cumulocity IoT, navigate to Devices > All devices > > Measurements in the Device Management application. You should observe a “temperature measurement” graph with the new data point.

Next Steps

You can now:

Connect your device to Azure IoT

To enable thin-edge.io you first must connect your device to the cloud. This is a 10 minutes operation to be done only once. It establishes a permanent connection from your device to the cloud end-point. This connection is secure (encrypted over TLS), and the two peers are identified by x509 certificates. Sending data to the cloud is then as simple as sending data locally.

The focus is here on connecting the device to Azure IoT. See Connect your device to Cumulocity IoT, if you want to connect Cumulocity IoT instead.

Before you can connect your device to Azure IoT, you need to create an Azure IoT Hub in Azure portal as described at https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal, as well as to install thin-edge.io on your device.

You can now use the tedge command to:

Create the certificate

The tedge cert create command creates a self-signed certificate which can be used for testing purpose.

A single argument is required: an identifier for the device. This identifier will be used to uniquely identify your devices among others in your cloud tenant. This identifier will be also used as the Common Name (CN) of the certificate. This certificate aims to validate that this device is the device with that identity.

$ sudo tedge cert create --device-id my-device

Show certificate details

You can then check the content of that certificate.

$ sudo tedge cert show
Device certificate: /etc/tedge/device-certs/tedge-certificate.pem
Subject: CN=my-device, O=Thin Edge, OU=Test Device
Issuer: CN=my-device, O=Thin Edge, OU=Test Device
Valid from: Tue, 09 Mar 2021 14:10:30 +0000
Valid up to: Thu, 10 Mar 2022 14:10:30 +0000
Thumbprint: 860218AD0A996004449521E2713C28F67B5EA580

The issuer of this certificate is the device itself as this is a self-signed certificate. The thumbprint is the Sha1sum of the certificate. This is required for registering the device using the self-signed certificate on Azure IoT Hub. To use a certificate signed by your certificate authority, see Developer tools > Command Line Interface (CLI) > tedge cert command.

Register the device on Azure IoT Hub

In order for Azure to trust a device, you need to add the self-signed certificate thumbprint to the Azure IoT Hub Portal. In the Azure IoT Hub Portal, navigate to Explores > IoT Devices and click + New. This opens the window Create a device.

Here provide the configuration parameters that are required to create the device as described below:

After saving the configuration successfully, a new device has been created on the IoT Hub. You can see the new device on the IoT Hub portal by navigating to Explores > IoT Devices.

You can find more information about registering a device on the Azure IoT Hub website: https://docs.microsoft.com/en-us/azure/iot-edge/how-to-authenticate-downstream-device?view=iotedge-2018-06

Configure the device

To connect the device to the Azure IoT Hub, you need to set the URL/hostname of the IoT Hub and the root certificate of the IoT Hub as shown in the example below.

Set the URL/hostname of your Azure IoT Hub.

sudo tedge config set az.url your-iot-hub-name.azure-devices.net

You can find the URL/hostname in the Azure web portal by clicking on the overview section of your IoT Hub.

Set the path to the root certificate if necessary. The default is /etc/ssl/certs.

sudo tedge config set az.root.cert.path /etc/ssl/certs/Baltimore_CyberTrust_Root.pem

This will set the root certificate path of the Azure IoT Hub. In most Linux flavors, the certificate will be present in /etc/ssl/certs. If you cannot find it, download it from https://www.digicert.com/kb/digicert-root-certificates.htm.

Connect the device

Now, you are ready to get your device connected to Azure IoT Hub with tedge connect az. This command configures the MQTT broker:

Also, if you have installed tedge_mapper, this command starts and enables the tedge-mapper-az systemd service. At last, it sends packets to Azure IoT Hub to check the connection.

$ sudo tedge connect az

Checking if systemd is available.

Checking if configuration for requested bridge already exists.

Validating the bridge certificates.

Saving configuration for requested bridge.

Restarting mosquitto service.

Awaiting mosquitto to start. This may take up to 5 seconds.

Persisting mosquitto on reboot.

Successfully created bridge connection!

Checking if tedge-mapper is installed.

Starting tedge-mapper service.

Persisting tedge-mapper on reboot.

tedge-mapper service successfully started and enabled!

Sending packets to check connection. This may take up to 10 seconds.

Received expected response message, connection check is successful.

Sending your first telemetry data

To send data to Azure use MQTT over topics prefixed with az. Any messages sent on the topic are forwarded to Azure. The example below uses tedge mqtt pub az/messages/events/, a message to be understood as a temperature of 20 degree.

$ tedge mqtt pub az/messages/events/ '{"temperature": 20}'

To view the messages that were sent from the device to the cloud, refer to https://docs.microsoft.com/en-us/azure/iot-hub/quickstart-send-telemetry-cli#create-and-monitor-a-device.

More information about sending telemetry to Azure can be found at https://docs.microsoft.com/en-us/azure/iot-hub/quickstart-send-telemetry-dotnet.

Next Steps

You can now:

Send Thin Edge JSON data

Once your Thin Edge device is configured and connected to an IoT cloud provider, you can start sending measurements. Refer to Connect your device to Cumulocity IoT or tutorials for other cloud providers to learn how to connect your Thin Edge device to an IoT cloud provider.

This section gives an overview on how different kinds of measurements are represented in Thin Edge JSON format and how they can be sent to the connected cloud provider. For a more detailed specification of this data format, refer to Architecture > Thin Edge JSON format.

Sending measurements

A simple single-valued measurement like a temperature measurement, is represented in Thin Edge JSON as follows:

{ "temperature": 25 }

The key-value pair represents the measurement type and the numeric value of the measurement.

This measurement can be sent from the Thin Edge device to the cloud by publishing this message to the tedge/measurements MQTT topic. Processes running on the Thin Edge device can publish messages to the local MQTT broker using any MQTT client or library. In this tutorial, we’ll be using the tedge mqtt pub command line utility for demonstration purposes.

The temperature measurement described above can be sent using the tedge mqtt pub command as follows:

$ tedge mqtt pub tedge/measurements '{ "temperature": 25 }'

The first argument to the tedge mqtt pub command is the topic to which the measurements must be published. The second argument is the Thin Edge JSON representation of the measurement itself.

When connected to a cloud provider, a message mapper component for that cloud provider will be running as a daemon, listening to any measurements published to tedge/measurements. The mapper, on receipt of these Thin Edge JSON measurements, will map those measurements to their equivalent cloud provider native representation and send it to that cloud.

For example, when the device is connected to Cumulocity IoT, the Cumulocity IoT mapper component will be performing these actions. To check if these measurements have reached Cumulocity IoT, log in to your Cumulocity IoT account and navigate to Device Management > Devices > All devices > <your device id> > Measurements and check if your temperature measurement shows up in the dashboard.

Complex measurements

You can represent measurements that are far more complex than the single-valued ones described above using the Thin Edge JSON format.

A multi-valued measurement like three_phase_current that consists of L1, L2 and L3 values, representing the current on each phase, can be represented as follows:

{
  "three_phase_current": {
    "L1": 9.5,
    "L2": 10.3,
    "L3": 8.8
  }
}

Here is another complex message consisting of single-valued measurements: temperature and pressure along with a multi-valued coordinate measurement, all sharing a single timestamp captured as time.

{
  "time": "2020-10-15T05:30:47+00:00",
  "temperature": 25,
  "current": {
    "L1": 9.5,
    "L2": 10.3,
    "L3": 8.8
  },
  "pressure": 98
}

The time field is not a regular measurement like temperature or pressure but a special reserved field. Refer to the Architecture > Thin Edge JSON format for more details on the kinds of telemetry data that can be represented in Thin Edge JSON format and the reserved fields like time used in the above example.

Error detection

If the data published to the tedge/measurements topic are not valid Thin Edge JSON measurements, those won’t be sent to the cloud but instead you’ll get a feedback on the tedge/errors topic, if you subscribe to it. The error messages published to this topic will be highly verbose and may change in the future. So, use it only for debugging purposes during the development phase and it should not be used for any automation.

You can use the tedge mqtt sub command to subscribe to the error topic as follows:

$ tedge mqtt sub tedge/errors

Monitor your device with collectd

With thin-edge.io device monitoring, you can collect metrics from your device and forward these device metrics to IoT platforms in the cloud.

Using these metrics, you can monitor the health of devices and can proactively initiate actions in case the device seems to malfunction. Additionally, the metrics can be used to help the customer troubleshoot when problems with the device are reported.

Thin-edge.io uses the open source component collectd to collect the metrics from the device, see https://collectd.org/ for more information. Thin-edge.io translates the collected metrics from their native format to the Thin Edge JSON format and then into the cloud-vendor specific format.

Enabling monitoring on your device is a 3-steps process:

  1. Install collectd,
  2. Configure collectd,
  3. Enable thin-edge.io monitoring.

Install mosquitto client library

Since thin-edge.io uses the MQTT plugin of collectd, you need to install the mosquitto client library, either libmosquitto1

sudo apt-get install libmosquitto1

or mosquitto-clients

sudo apt-get install mosquitto-clients

Install collectd

Device monitoring is not enabled by default when you install thin edge. You must install and configure collectd at https://collectd.org/ first.

To install collectd, follow the collectd installation process that is specific to your device as shown at https://collectd.org/download.shtml. On a Debian or Ubuntu Linux:

sudo apt-get install collectd-core

Configure collectd

Basic collectd configuration

Thin-edge.io provides a basic collectd configuration at https://github.com/thin-edge/thin-edge.io/blob/main/configuration/contrib/collectd/collectd.conf that can be used to collect CPU, memory and disk metrics.

Copy that file to the main collectd configuration file and restart the daemon. We recommend you to keep a copy of the original configuration.

sudo cp /etc/collectd/collectd.conf /etc/collectd/collectd.conf.backup
sudo cp /etc/tedge/contrib/collectd/collectd.conf /etc/collectd/collectd.conf
sudo systemctl restart collectd

Collectd.conf

Unless you opted for the minimal test configuration provided with thin-edge you will have to update the collectd.conf configuration file at https://collectd.org/documentation/manpages/collectd.conf.5.shtml. The collectd.conf configuration file is usually located at /etc/collectd/collectd.conf.

Important: You can enable or disable the collectd plugins of your choice. This is subject to some notable exceptions, which are listed below.

  1. MQTT must be enabled.
    • Thin-edge.io expects the collectd metrics to be published on the local MQTT bus. Hence, you must enable the MQTT write plugin of collectd at https://collectd.org/documentation/manpages/collectd.conf.5.shtml#plugin_mqtt.
    • The MQTT plugin is available on most distributions of collectd, but this is not the case on MacOS using homebrew. If you are missing the MQTT plugin, recompile collectd to include the MQTT plugin. See https://github.com/collectd/collectd for details.
    • Here is a config snippet to configure the MQTT write plugin: 
         LoadPlugin mqtt

   <Plugin mqtt>
       <Publish "tedge">
           Host "localhost"
           Port 1883
           ClientId "tedge-collectd"
       </Publish>
   </Plugin>
  2. RRDTool and CSV should be disabled.
    • The risk with these plugins is to run out of disk space on a small device.
    • With thin-edge.io the metrics collected by collectd are forwarded to the cloud, hence it makes sense to disable local storage, see https://github.com/collectd/collectd/issues/2668 for more information.
    • For that, simply comment out the following two plugins:
       #LoadPlugin rrdtool
   #LoadPlugin csv
  3. Cherry-pick the collected metrics.
    • Collectd can collect a lot of detailed metrics, and it is not always recommended to forward all of this data to the cloud.
    • Here is a config snippet that uses the match_regex plugin to select the metrics of interest, filtering out every metric emitted by the memory plugin other than the used metric:
        PreCacheChain "PreCache"

    LoadPlugin match_regex

    <Chain "PreCache">
        <Rule "memory_free_only">
            <Match "regex">
                Plugin "memory"
            </Match>
            <Match "regex">
                TypeInstance "used"
                Invert true
            </Match>
            Target "stop"
        </Rule>
    </Chain>

Enable Thin Edge monitoring

To enable monitoring on your device, you must launch the tedge-mapper-collectd daemon process.

sudo systemctl enable tedge-mapper-collectd
sudo systemctl start tedge-mapper-collectd

This process subscribes to the collectd/# topics to read the monitoring metrics published by collectd and emits the translated measurements in Thin Edge JSON format to the tedge/measurements topic. You can inspect the collected and translated metrics, by subscribing to these topics:

The metrics collected by collectd are emitted to subtopics named after the collectd plugin and the metric name:

$ tedge mqtt sub 'collectd/#'

[collectd/raspberrypi/cpu/percent-active] 1623076679.154:0.50125313283208
[collectd/raspberrypi/memory/percent-used] 1623076679.159:1.10760866126707
[collectd/raspberrypi/cpu/percent-active] 1623076680.154:0
[collectd/raspberrypi/df-root/percent_bytes-used] 1623076680.158:71.3109359741211
[collectd/raspberrypi/memory/percent-used] 1623076680.159:1.10760866126707

The `tedge-mapper-collectd translates these collectd measurements into the Thin Edge JSON format, grouping the measurements emitted by each plugin:

tedge mqtt sub 'tedge/measurements'

[tedge/measurements] {"time":"2021-06-07T15:38:59.154895598+01:00","cpu":{"percent-active":0.50251256281407},"memory":{"percent-used":1.11893578135189}}
[tedge/measurements] {"time":"2021-06-07T15:39:00.154967388+01:00","cpu":{"percent-active":0},"df-root":{"percent_bytes-used":71.3110656738281},"memory":{"percent-used":1.12107875001658}}

From there, if the device is actually connected to a cloud platform like Cumulocity IoT, these monitoring metrics will be forwarded to the cloud.

tedge mqtt sub 'c8y/#'
[c8y/measurement/measurements/create] {"type": "ThinEdgeMeasurement","time":"2021-06-07T15:40:30.155037451+01:00","cpu":{"percent-active": {"value": 0.753768844221106}},"memory":{"percent-used": {"value": 1.16587699972141}},"df-root":{"percent_bytes-used": {"value": 71.3117904663086}}}
[c8y/measurement/measurements/create] {"type": "ThinEdgeMeasurement","time":"2021-06-07T15:40:31.154898577+01:00","cpu":{"percent-active": {"value": 0.5}},"memory":{"percent-used": {"value": 1.16608109197519}}}

If your device is not connected yet see:

Trouble shooting

See Trouble shoot device monitoring.