Skip to content

Latest commit

 

History

History
177 lines (121 loc) · 6.73 KB

connect-c8y.md

File metadata and controls

177 lines (121 loc) · 6.73 KB

Connect your device 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.

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.

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

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

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

Awaiting mosquitto to start. This may take up to 5 seconds.

Enabling mosquitto service on reboots.

Successfully created bridge connection!

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!

Sending packets to check connection. This may take up to 10 seconds.

Try 1 / 2: Sending a message to Cumulocity.
Received expected response message, connection check is successful.

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!

Starting tedge-mapper-sm-c8y service.

Persisting tedge-mapper-sm-c8y on reboot.

tedge-mapper-sm-c8y 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 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.

Next Steps

You can now: