The very first step to enable
thin-edge.io is to 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 will then be as simple as sending data locally.
Before you try to connect your device to Cumulocity IoT, you need:
- The url of the endpoint to connect (e.g.
- Your credentials to connect Cumulocity:
- Your tenant identifier (e.g.
t00000007), a user name and password.
- None of these credentials will be stored on the device.
- These are only required once, to register the device.
- Your tenant identifier (e.g.
If not done yet, install
thin-edge.io on your device.
You can now use the
tedge command to:
- create a certificate for you device,
- make the device certificate trusted by Cumulocity,
- connect the device, and
- send your first telemetry data.
To connect the device to the Cumulocity IoT, one needs 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
$ sudo tedge config set c8y.root.cert.path /etc/ssl/certs
This will set the root certificate path of the Cumulocity IoT. In most of the Linux flavors, the certificate will be present in /etc/ssl/certs. If not found download it from here.
If the Cumulocity IoT instance that you're connecting to, is signed with a self-signed certificate(eg: Cumulocity IoT Edge instance), then the path to that server certificate must be set as the c8y.root.cert.path as follows:
$ sudo tedge config set c8y.root.cert.path /path/to/the/self-signed/certificate
Note: This is the certificate chain of the server and not the device's certificate kept at /etc/tedge/device-certs directory.
If the Cumulocity server's certificate chain file isn't available locally, it can be downloaded using a web browser or using some other third-party tools like openssl command as follows (to be adjusted based on your env):
openssl s_client -connect <hostname>:<port> < /dev/null 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'
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. 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 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 Feb 2021 17:16:52 +0000 Valid up to: Tue, 11 May 2021 17:16:52 +0000 Thumbprint: CDBF4EC17AA02829CAC4E4C86ABB82B0FE423D3E
You may notice that 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 the reference guide of
For a certificate to be trusted by Cumulocity, one needs to add the certificate of the signing authority to the list of trusted certificates. In the Cumulocity GUI, navigate to "Device Management/Management/Trusted certificates" in order to see this list for your Cumulocity tenant.
Here, the device certificate is self-signed and has to be directly trusted by Certificate. This can be done:
- either with the GUI: upload the certificate from your device (
/etc/tedge/device-certs/tedge-certificate.pem) to your tenant "Device Management/Management/Trusted certificates".
- or using the
tedge cert upload c8ycommand.
$ sudo tedge cert upload c8y --user <username>
To upload the certificate to cumulocity this user needs to have "Tenant management" admin rights. If you get an error 503 here, check the appropriate rights in cumulocity user management.
Now, you are ready to run
tedge connect c8y.
This command configures the MQTT broker:
- to establish a permanent and secure connection to the cloud,
- to forward local messages to the cloud and vice versa.
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 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. Creating the device in Cumulocity cloud. Saving configuration for requested bridge. Restarting mosquitto service. Awaiting mosquitto to start. This may take up to 5 seconds. Enabling mosquitto service on reboots. Successfully created bridge connection! Sending packets to check connection. This may take up to 2 seconds. Connection check is successful. Checking if tedge-mapper is installed. Starting tedge-mapper-c8y service. Persisting tedge-mapper-c8y on reboot. tedge-mapper-c8y service successfully started and enabled! Enabling software management. Checking if tedge-agent is installed. Starting tedge-agent service. Persisting tedge-agent on reboot. tedge-agent service successfully started and enabled!
Sending data to Cumulocity is done using MQTT over topics prefixed with
Any messages sent to one of these topics will be forwarded to Cumulocity.
The messages are expected to have a format specific to each topic.
Here, we use
tedge mqtt pub a raw Cumulocity 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, navigate to "Device Management/Devices/All devices/<your device id>/Measurements". You should observe a "temperature measurement" graph with the new data point.
You can now: