Skip to main content
Version: 1.0.1

Connecting to Cumulocity IoT

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.

The focus is here on connecting to Cumulocity IoT. See this tutorial, if you want to connect Azure IoT instead. See this tutorial, if you want to connect AWS IoT instead.

Before you try to connect your device to Cumulocity IoT, you need:

  • The url of the endpoint to connect (e.g. eu-latest.cumulocity.com).
  • 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.

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 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 /etc/ssl/certs.

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.

Connecting to Cumulocity server signed with self-signed certificate​

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
info

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'

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. Indeed, this certificate aims to authenticate that this device is actually the device with that identity.

sudo tedge cert create --device-id my-device
Output
Certificate was successfully created

You can then check the content of that certificate.

sudo tedge cert show
Output
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 tedge cert.

Make the device trusted by Cumulocity​

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 c8y command.
sudo tedge cert upload c8y --user "${C8Y_USER}"
Example
sudo tedge cert upload c8y --user "john.smith@example.com"

Common errors​

Below shows some common errors that can be experienced when trying to upload the device certificate.

401 - Unauthorized​

The 401 (Unauthorized) error means either the user and/or password is invalid for the configured Cumulocity IoT url that was set in the tedge config set c8y.url <url> command.

Check the following items to help you diagnose the root cause of the problem:

  • Check the configured c8y.url. Copy/paste the url into a Web Browser to validate that it does open the intended Cumulocity IoT tenant
  • Check your username. The user/email is case-sensitive, so make sure the user matches your configured Cumulocity IoT user
  • Check your password. Use copy/paste to enter your password as this eliminates typos
  • Check that you are not using a SSO user. SSO users are not permitted to use the REST API calls which the tedge cert upload c8y command is using. Please create a new Cumulocity IoT user via the Administration Pge

403 - Forbidden​

The 403 (Forbidden) error means that your user/password is correct however you do not have sufficient permissions to add the thin-edge.io's device certificate to the Cumulocity IoT's Trusted certificates.

Your Cumulocity IoT user MUST be assigned the Tenant Manager Global Role in order to add new trusted certificates to Cumulocity IoT. Global roles can be assigned to users via the Cumulocity IoT Administration application under Accounts → Users → <your username> → Global Roles section. Below shows a screenshot of the Tenant Manager role that your user needs to be assigned to.

User Global Roles

Alternatively, you can explicitly add one of the following permissions to your Cumulocity IoT user: ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN, however this method requires you to be familiar with the Cumulocity IoT OpenAPI.

If you are still having trouble, please check out the official Cumulocity IoT documentation.

Address is unreachable​

If you are unable to reach Cumulocity IoT, then it is likely that your device's network is not properly configured. This could be for many different reasons, however the following checks might help you spot where the mistake is:

  • Can you ping a well known DNS server?

    ping 8.8.8.8

    The exact address is not that important, it used to see if a well established/reliable IP address is reachable from your device. You may need to adjust the IP address if your ISP (Internet Service Provider) blocks it for some reason.

  • Can you reach another website?

    Using Google is helpful here, as it is generally available, though you can also choose another popular/highly available website for your test.

    curl google.com

  • Check if the configured c8y.url is reachable by using curl

    bash
    curl "https://$(tedge config get c8y.url)/tenant/loginOptions"

    If you are having problems resolving the c8y.url to an IP address, then it might be worthwhile considering manually adding a nameserver to the DNS configuration file as shown below:

    file: /etc/resolv.conf
    nameserver 8.8.8.8

Connect the device​

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
Output
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 your first telemetry data​

Sending data to Cumulocity is done using MQTT over topics prefixed with c8y. 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°C.

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 → device_id → Measurements

You should observe a "temperature measurement" graph with the new data point.

Next Steps​

You can now: