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.


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

sudo tedge config set c8y.url example.cumulocity.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 we issue tedge connect c8y without any configuration following 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. This is done by uploading the certificate of the signee. You can upload root certificate via Cumulocity UI or with tedge cert upload as described below.

Note: This command takes parameter user, this is due to upload mechanism to Cumulocity cloud which uses username and password for authentication.

After issuing this command you are going to be prompted for a password. Users usernames and passwords are not stored in configuration due to security.

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

where:

username -> user in Cumulocity with permissions to upload new certificates


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

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

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

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.

Next steps

  1. How to use mqtt pub/sub?