Connecting to Cumulocity

tip

User Context

You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use thin-edge.io.

Loading user context...

The user context will be persisted in your web browser's local storage.

To create northbound connection, a local bridge shall be established and this can be achieved with tedge cli. The sections below explain the steps required to establish a connection to Cumulocity.

note

tedge connect requires root privileges, so you need to run it using sudo or run the command as root.

Setting the cloud endpoint

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

sudo tedge config set c8y.url undefined

info

If you are unsure which parameters required by the command, simply run the command and it will tell you which parameters are missing.

For example, if we issue tedge connect c8y without any configuration following advice will be given:

sudo tedge connect c8y

Output

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

Making the cloud trust the device

thin-edge.io primarily uses a x509 certificate to connect to Cumulocity, therefore the certificate must be trusted by Cumulocity in order for the connection to be established.

There are a few different ways to get the device certificate to be trusted by Cumulocity, below lists a few common options.

Option 1: Using Cumulocity Certificate Authority (Preview)

The Cumulocity Certificate Authority feature is currently in the Public Preview phase and hence needs to be enabled for a specific tenant before it can be used. Please read the Certificate Management Reference Guide on how to enable this feature in Cumulocity.

Devices can be registered by using the Cumulocity Device Management UI or by using Cumulocity's REST API which is demonstrated via the usage of the command line tool, go-c8y-cli. The following sections detail the steps on how to register a device using both of these methods, however both are functionally the same as they all utilize the same Cumulocity API.

Registering a device using the Device Management UI

The following steps detail how to register a device using the Cumulocity Device Management UI Application.

1. Open the Cumulocity Device Management UI Application

2. Navigate to Devices → Registration

3. Click Register device and select General

   https://example.cumulocity.com/apps/devicemanagement/index.html#/deviceregistration

   

4. In the Register general devices dialog box, select the "Create device certificates during device registration" option

5. Fill in the following required fields and click Next

   https://example.cumulocity.com/apps/devicemanagement/index.html#/deviceregistration

   

   Field	Description
   Device ID	Device's which will be used as the Common Name in the device's certificate
   One-time password	One-time password that the device can use to download its device certificate. Maximum length of 32 characters

   tip

   Make sure you copy the one-time password as this will be required on the device.

6. Close the form

   https://example.cumulocity.com/apps/devicemanagement/index.html#/deviceregistration

   

7. On the device, run the following command to download the device's certificate (you will be prompted for the one-time password)

   sudo tedge cert download c8y --device-id "undefined"
   
   # Or provide the one-time password via the flag
   sudo tedge cert download c8y \
       --device-id "undefined" \
       --one-time-password "$DEVICE_ONE_TIME_PASSWORD"

Register a device using go-c8y-cli command

Below describes the steps to register a new device using a combination of go-c8y-cli commands and thin-edge.io.

note

go-c8y-cli simply uses the Cumulocity REST API to perform the actions, this means that you can also do the same steps by using the API directly.

1. Register the device using go-c8y-cli

   c8y deviceregistration register-ca --id "undefined"

   If you want don't want to use an auto generated one-time password then you can provide your own value via the --one-time-password flag.

   c8y deviceregistration register-ca \
       --id "undefined" \
       --one-time-password "$DEVICE_ONE_TIME_PASSWORD"

2. On the device, run the following command to download the device's certificate (you will be prompted for the one-time password)

   sudo tedge cert download c8y --device-id "undefined"
   
   # Or provide the one-time password via the flag
   sudo tedge cert download c8y \
       --device-id "undefined" \
       --one-time-password "$DEVICE_ONE_TIME_PASSWORD"
   note

   The operator has to give the same device id and one-time password twice, to the tenant and to the device. This is the proof that the device can be trusted by the tenant and the tenant by the device, provided the operator is trusted by the tenant and the device (i.e. has been granted the appropriate access privileges).

Option 2: Using self-signed certificates

For development purposes, you can use self-signed certificates which can be created on device and then uploaded to Cumulocity using thin-edge.io or using the Cumulocity UI.

The usage of the tedge cert upload command is described below.

sudo tedge cert upload c8y --user "undefined"

note

The tedge cert upload command requires the credentials of a Cumulocity user having the permissions to upload trusted certificates on the Cumulocity tenant of the device.

The user name is provided as --user <username> parameter, and the command will prompt you for this user's password. These credentials are used only for this upload and will in no case be stored on the device.

Creating an MQTT bridge between the device and the cloud

The connection from the device to the cloud is established using a so-called MQTT bridge: a permanent secured bidirectional MQTT connection that forward messages back and forth between the two end-points.

To create the bridge use the tedge connect command.

sudo tedge connect c8y

Output

connect to Cumulocity cloud.:
	device id: undefined
	cloud profile: <none>
	cloud host: undefined:8883
	auth type: Certificate
	certificate file: /etc/tedge/device-certs/tedge-certificate.pem
	cryptoki: false
	bridge: mosquitto
	service manager: systemd
	mosquitto version: 2.0.11
	proxy: Not configured
Creating device in Cumulocity cloud... ✓
Restarting mosquitto... ✓
Waiting for mosquitto to be listening for connections... ✓
Verifying device is connected to cloud... ✓
Enabling tedge-mapper-c8y... ✓
Checking Cumulocity is connected to intended tenant... ✓
Enabling tedge-agent... ✓

Errors

Connection already established

If connection has already been established following error may appear:

sudo tedge connect c8y

Output

connect to Cumulocity cloud.:
	device id: undefined
	cloud profile: <none>
	cloud host: undefined:8883
	auth type: Certificate
	certificate file: /etc/tedge/device-certs/tedge-certificate.pem
	cryptoki: false
	bridge: mosquitto
	service manager: systemd
	mosquitto version: 2.0.11
	proxy: Not configured
Error: failed to connect to Cumulocity cloud.

Caused by:
    Connection is already established. To remove the existing connection, run `tedge disconnect c8y` and try again.

To remove existing connection and create new one follow the advice and issue tedge disconnect c8y:

sudo tedge disconnect c8y

Output

Removing bridge config file... ✓
Restarting mosquitto to apply configuration... ✓
Disabling tedge-mapper-c8y... ✓

note

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

And now you can issue tedge connect c8y to create new bridge.

Connection check warning

Sample output of tedge connect when this warning occurs:

sudo tedge connect c8y

Output

ERROR: Local MQTT publish has timed out.
Warning: Bridge has been configured, but Cumulocity connection check failed.

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

• No access to Internet connection

Local bridge has been configured and is running but the connection check has failed due to no access to the northbound endpoint.

• Cumulocity tenant not available

Tenant couldn't be reached and therefore connection check has failed.

• Check bridge

Bridge configuration is correct but the connection couldn't be established to unknown reason.

You an retry the connect to the cloud by using:

sudo tedge reconnect c8y

File permissions

Connecting without sudo will result in the following error:

tedge connect c8y

Output

connect to Cumulocity cloud.:
	device id: undefined
	cloud profile: <none>
	cloud host: undefined:8883
	auth type: Certificate
	certificate file: /etc/tedge/device-certs/tedge-certificate.pem
	cryptoki: false
	bridge: mosquitto
	service manager: systemd
	mosquitto version: 2.0.11
	proxy: Not configured
Creating device in Cumulocity cloud... ✗
error: Failed to create TLS client config: Could not access /etc/tedge/device-certs/tedge-private-key.pem: Permission denied (os error 13)

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

Example of incorrect permissions:

ls -l /etc/tedge

Output

dr--r--r-- 2 tedge     tedge     4096 Mar 30 15:40 mosquitto-conf

You should give it the permission 755.

ls -l /etc/tedge

Output

drwxr-xr-x 2 tedge     tedge     4096 Mar 30 15:40 mosquitto-conf

Mosquitto and systemd check fails

Sample output:

sudo tedge connect c8y

Output

Failed to detect mosquitto version: assuming mosquitto version < 2.0.0
connect to Cumulocity cloud.:
	device id: undefined
	cloud profile: <none>
	cloud host: undefined:8883
	auth type: Certificate
	certificate file: /etc/tedge/device-certs/tedge-certificate.pem
	cryptoki: false
	bridge: mosquitto
	service manager: systemd
	proxy: Not configured
Creating device in Cumulocity cloud... ✓
Restarting mosquitto... ✗
error: Service command <"/bin/systemctl stop mosquitto"> failed with code: 5.
Cleaning up /etc/tedge/mosquitto-conf/c8y-bridge.conf due to failure... ✓

mosquitto server has not been installed on the system and it is required to run this command, refer to the install guide to install mosquitto and try again.