Skip to main content
Version: 0.13.1

How to connect?

Connect to Cumulocity IoT

To create northbound connection a local bridge shall be established and this can be achieved with tedge cli and following commands:

note

tedge connect requires sudo privilege.

Setting the cloud end-point

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

sudo tedge config set c8y.url example.cumulocity.com
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

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

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.

sudo tedge cert upload c8y --user "${C8Y_USER}"
Example
sudo tedge cert upload c8y --user "john.smith@example.com"

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

Errors

Connection already established

If connection has already been established following error may appear:

sudo tedge connect c8y
Output
Checking if systemd is available.

Checking if configuration for requested bridge already exists.

Error: failed to create bridge to connect Cumulocity cloud.

Caused by:
Connection is already established. To remove existing connection use '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 Cumulocity bridge.

Applying changes to mosquitto.

Cumulocity Bridge successfully disconnected!

Stopping tedge-mapper-c8y service.

Disabling tedge-mapper-c8y service.

tedge-mapper-c8y service successfully stopped and disabled!

Stopping tedge-agent service.

Disabling tedge-agent service.

tedge-agent service successfully stopped and disabled!
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
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.

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

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!

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.

To retry start with tedge disconnect c8y removing this bridge:

sudo tedge disconnect c8y

When this is done, issue tedge connect c8y again.

File permissions

Connecting without sudo will result in the following error:

tedge connect c8y
Output
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 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 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
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.

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