How-to recipes

Install thin-edge.io

Installation with get-thin-edge_io.sh script

There are two options for installing thin-edge.io. The easy way is to use the installation script with this command:

curl -fsSL https://raw.githubusercontent.com/thin-edge/thin-edge.io/main/get-thin-edge_io.sh | sudo sh -s 0.2.0

You can execute this command on your device and it will do all required steps for an initial setup.

If you prefer to have a little more control over the installation or the script did not work for you, follow the Manual installation.

Manual installation

To install the thin-edge package it is required to use curl to download the package and dpkg to install it.

Dependency installation

thin-edge.io has a single dependency on mosquitto which is used for southbound and northbound communication. Southbound, devices can publish measurements. Northbound, the gateway may relay messages to the cloud. mosquitto can be installed with your package manager. For apt the command may look like the following:

apt install mosquitto

Info: Some operating systems may require you to use sudo to install packages.

sudo apt install mosquitto

thin-edge.io installation

When all dependencies are in place you can proceed with the installation of thin-edge.io cli and thin-edge.io mapper service.

Package download

The thin-edge.io package is in the thin-edge.io repository on GitHub.

To download the package from the GitHub repository use the following command (use the desired version):

curl -LJO https://github.com/thin-edge/thin-edge.io/releases/download/<package>_<version>_<arch>.deb

where version is the thin-edge.io version in x.x.x format and arch is the architecture type (amd64, armhf).

Example:

curl -LJO https://github.com/thin-edge/thin-edge.io/releases/download/0.1.0/tedge_0.1.0_armhf.deb

and for mapper:

curl -LJO https://github.com/thin-edge/thin-edge.io/releases/download/0.1.0/tedge_mapper_0.1.0_armhf.deb
Package installation

Now that you have downloaded the package you can proceed with the installation. First install the CLI tool tedge.

Info: Some operating systems may require you to use sudo to install packages and therefore all following commands may need sudo.

To install tedge use the following command:

dpkg -i tedge_<version>_<arch>.deb

Example:

dpkg -i tedge_0.1.0_armhf.deb

To install mapper for thin-edge.io use:

dpkg -i tedge_mapper_<version>_<arch>.deb

Example:

dpkg -i tedge_mapper_0.1.0_armhf.deb
Add your user to the tedge-users group

During the installation process a tedge-users group is automatically created to ease the administration of who can use the sudo tedge command on the device. The tedge command needs to be run using sudo. Unless all the users are granted sudo privileges, you must add a user to the tedge-users group for that user to be able to use tedge.

Run this command to add a user to the group.

sudo adduser <user> tedge-users

Create a self-signed certificate

To create a new certificate you can use the thin-edge.io command tedge cert create:

sudo tedge cert create --device-id alpha

Info: tedge cert requires sudo privilege. This command provides no output on success.

The command sudo tedge cert create will create a certificate in a default location (/etc/tedge/device-certs/). To use a custom location, refer to tedge config.

Now you should have a certificate in the /etc/tedge/device-certs/ directory. Verify with the following command:

$ ls /etc/tedge/device-certs/
/etc/tedge/device-certs/tedge-certificate.pem

Errors

Certificate creation fails due to invalid device ID

If the device ID contains unsupported characters, tedge cert create will fail with the below error:

Error: failed to create a test certificate for the device +.

Caused by:
    0: DeviceID Error
    1: The string '"+"' contains characters which cannot be used in a name [use only A-Z, a-z, 0-9, ' = ( ) , - . ? % * _ ! @]
Certificate already exists in the given location

If the certificate already exists you may see the following error:

Error: failed to create a test certificate for the device alpha.

Caused by:
    A certificate already exists and would be overwritten.
            Existing file: "/etc/tedge/device-certs/tedge-certificate.pem"
            Run `tedge cert remove` first to generate a new certificate.

Warning: Removing a certificate can break the bridge and more seriously delete a certificate that was a CA-signed certificate.

Follow the instruction in the error message to remove the existing certificate and execute tedge cert remove:

sudo tedge cert remove

and try tedge cert create once again.

Connect to a cloud endpoint

Connect to Cumulocity IoT

To create a northbound connection, you must establish a local bridge. To achieve this, use the tedge CLI and the commands described below.

Info: tedge connect requires sudo privilege.

Configure the required parameters for thin-edge.io with tedge config set:

sudo tedge config set c8y.url example.cumulocity.com.com

Tip: If you you are unsure which parameters are required for the command to work, run the command and it will tell you which parameters are missing. For example, if you execute tedge connect c8y without any configuration, the following piece of advice will be given:

$ tedge connect c8y`
...
Error: failed to execute `tedge connect`.

Caused by:
    Required configuration item is not provided 'c8y.url', run 'tedge config set c8y.url <value>' to add it to config.

This message explains which configuration parameter is missing and how to add it to configuration. In this case we are told to run tedge config set c8y.url <value>.

The next step is to have the device certificate trusted by Cumulocity IoT. This is done by uploading the certificate of the signee. You can upload the root certificate via Cumulocity IoT UI or with tedge cert upload as described below.

Info: This command takes the parameter user. This is due to the upload mechanism to the Cumulocity IoT cloud which uses username and password for authentication.

After issuing this command you are going to be prompted for a password. Usernames and passwords are not stored in the configuration for security reasons.

$ sudo tedge cert upload c8y –-user <username>
Password:

where username is the user in Cumulocity IoT with permissions to upload new certificates.

To create the bridge, use tedge connect:

$ 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. Received expected response message, connection check is successful.

Errors

Connection already established

If a connection has already been established, the following error may appear:

$ sudo tedge connect c8y
Checking if systemd is available.

Checking if configuration for requested bridge already exists.

Error: failed to create bridge to connect Cumulocity IoT cloud.

Caused by:
    Connection is already established. To remove existing connection use 'tedge disconnect c8y' and try again.

To remove the existing connection and create a new one, follow the advice from the shell prompt and execute tedge disconnect c8y:

$ sudo tedge disconnect c8y
Removing Cumulocity bridge.

Applying changes to mosquitto.

Cumulocity Bridge successfully disconnected!

Stopping tedge-mapper service.

Disabling tedge-mapper service.

tedge-mapper service successfully stopped and disabled!

Info: tedge disconnect c8y also stops and disables the tedge-mapper service if it is installed on the device.

Now you can execute tedge connect c8y to create a new bridge.

Connection check failure

Sample output of tedge connect when this error occurs:

$ 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. ... 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. ... No response.
Warning: Bridge has been configured, but Cumulocity connection check failed.

This error may be caused by some of the following reasons:

File permissions

Sample output:

$ 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.

Error: failed to create bridge to connect Cumulocity IoT cloud.

Caused by:
    0: File Error. Check permissions for /etc/tedge/mosquitto-conf/tedge-mosquitto.conf.
    1: failed to persist temporary file: Permission denied (os error 13)
    2: Permission denied (os error 13)

tedge connect cannot access the location to create the bridge configuration (/etc/tedge/mosquitto-conf). Check the permissions for the directory and adjust it to allow tedge connect to access it.

Example of incorrect permissions:

$ ls -l /etc/tedge
dr--r--r-- 2 tedge     tedge     4096 Mar 30 15:40 mosquitto-conf

You should give it the permission 755:

$ ls -l /etc/tedge
drwxr-xr-x 2 tedge     tedge     4096 Mar 30 15:40 mosquitto-conf

mosquitto and systemd check fails

Sample output:

$ 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.

Error: failed to create bridge to connect Cumulocity cloud.

Caused by:
    Service mosquitto not found. Install mosquitto to use this command.

The mosquitto server has not been installed on the system but it is required to run this command. Refer to How to install thin-edge.io to install mosquitto and try again.

Use the tedge mqtt module

The thin-edge.io CLI provides a convenient way to debug and aid the development process.

Publish

The tedge mqtt pub command can be used to publish MQTT messages on a topic to the local mosquitto server.

Example:

tedge mqtt pub 'tedge/measurements' '{ "temperature": 21.3 }'

tedge mqtt pub supports the setting of QoS for MQTT messages:

tedge mqtt pub 'tedge/measurements' '{ "temperature": 21.3 }' --qos 2

Subscribe

The tedge mqtt sub command can be used to ease the debugging of MQTT communication on the local bridge. You can subscribe to the topic of your choice:

tedge mqtt sub tedge/errors

Or you can subscribe to any topic on the server using the wildcard (#) topic:

tedge mqtt sub '#'

Now use tedge mqtt pub 'tedge/measurements' '{ "temperature": 21.3 }' to publish a message on the tedge/measurements topic with payload { "temperature": 21.3 }.

All messages from the sub-command are printed to stdout and can be captured to a file if needed:

tedge mqtt sub '#' > filename.mqtt

The wildcard (#) topic is used by the MQTT protocol as a wildcard and will listen on all topics.

Test the connection to the cloud

We provide a way of testing the connection from your device to a cloud provider. You can call this connection check function by:

sudo tedge connect <cloud> --test

It returns exit code 0 if the connection check is successful and 1 otherwise.

This test is already performed as part of the tedge connect <cloud> command.

What does the test do?

The connection test sends a message to the cloud and waits for a response. The subsequent sections explain the cloud-specific behaviour.

For Cumulocity IoT

The test publishes a SmartREST 2.0 static template message for device creation 100 to the topic c8y/s/us. If the device-twin is already created in your Cumulocity IoT account, the device is supposed to receive 41,100,Device already existing on the error topic c8y/s/e.

So, the test subscribes to the c8y/s/e topic and if it receives the expected message on the topic, the test is marked successful.

The connection test sends a maximum of two SmartREST 2.0 100 requests. This is because the first 100 request can be considered a successful device creation request if the device-twin does not exist in Cumulocity IoT yet.

For Azure IoT Hub

The test subscribes to the topic az/twin/res/. Then, it publishes an empty string to the topic az/twin/GET/?$rid=1.

If the connection check receives a message containing 200 (status success), the test is marked successful.

The connection test sends the empty string only once.

Configure the local port

Configuring a mosquitto port in Thin Edge is a three step process.

Step 1: Disconnect the Thin Edge device

The Thin Edge device has to be disconnected from the cloud using the tedge command:

tedge disconnect c8y/az

Step 2: Set and verify the new MQTT port

Set the MQTT port with a desired port using the tedge command:

tedge config set mqtt.port 1024

This will make sure that all of the MQTT clients use the newer port that has been set.

Verify the port configured/set

Use the below command to check if the port has been set properly.

tedge config get mqtt.port

This prints out the port that has been set.

Step 3: Connect the Thin Edge device to cloud

Use the tedge command below to connect to the desired cloud. This will force all the services (mosquitto, tedge-mappers) to use the newly set port.

tedge connect c8y

##or

tedge connect az

Info: Steps 1 and 2 can be followed in any order.

Update to use default port

To use the default port (1883), the MQTT port has to be unset using the tedge command:

tedge config unset mqtt.port

Once the port is reverted to default, step 1 and step 3 must be followed to use the default port.

Error case

The example below shows that you cannot set the string value for the port number.

tedge config set mqtt.port '"1234"'

Error: failed to set the configuration key: mqtt.port with value: "1234".

Caused by:
    Conversion from String failed

Updating the mqtt port in collectd & for collectd-mapper

Update the collectd.conf with the new port in <Plugin mqtt>. Restart the collectd service:

sudo systemctl restart collectd.service

After changing the MQTT port and connecting to cloud using tedge connect c8y/az (steps 1-3), the collectd-mapper has to be restarted to use the newly set port.

Restart the collectd-mapper service:

sudo systemctl restart collectd-mapper.service

Device monitoring troubleshooting

To install and configure monitoring on your device, see Monitor your device with collectd.

Is collectd running? 

sudo systemctl status collectd

If not, launch collectd:

sudo systemctl start collectd

Is collectd publishing MQTT messages? 

tedge mqtt sub 'collectd/#'

If no metrics are collected, check the MQTT configuration.

Is the Thin Edge collectd-mapper running? 

sudo systemctl status collectd-mapper

If not, launch collectd:

sudo systemctl start collectd-mapper

Are the collectd metrics published in Thin Edge JSON format? 

tedge mqtt sub 'tedge/measurements'

Are the collectd metrics published to Cumulocity IoT? 

tedge mqtt sub 'c8y/#'

If not see connect your device to Cumulocity IoT.

Are the collectd metrics published to Azure IoT? 

tedge mqtt sub 'az/#'

If not see connect your device to Azure IoT.

Add a self-signed certificate to the trusted certificates list

Overview

If the server you are trying to connect thin-edge.io to is presenting a certificate with a root that is not currently trusted, you can add the server’s root certificate to the list of trusted root certificates. For the most part the store will be filled with certificates from your TLS/SSL provider, but if you want to use self-signed certificates you may need to update your local certificate store. Below are instructions on how to add a new CA certificate and update the certificate store.

Info: The instructions provided are for supported OSes and may not apply to the flavour you are running. If you need help with another OS, consult the appropriate documentation.

Ubuntu and Raspberry Pi OS

If you do not have the ca-certificates package installed on your system, install it with your package manager:

sudo apt install ca-certificates

To add a self-signed certificate to the trusted certificate repository on the thin-edge.io system:

Create a /usr/local/share/ca-certificates/ directory if it does not exist in your file system:

sudo mkdir /usr/local/share/ca-certificates/

The directory should be owned by root:root and have 755 permissions set for it. The certificates files should be 644.

Copy your root certificate (in PEM format with .crt extension) to the created directory:

sudo cp <full_path_to_the_certificate> /usr/local/share/ca-certificates/

Install the certificates:

$ sudo update-ca-certificates
Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

To check if the certificate was correctly installed:

sudo ls /etc/ssl/certs | grep <certificate_name>

Additionally you can check the correctness of the installed certificate:

sudo cat /etc/ssl/certs/ca-certificates.crt | grep -f <full_path_to_the_certificate>