How to connect a device to Clea

Overview

Clea OS simplifies the process of connecting to the broader Clea software suite, enabling seamless integration with other Clea modules. For a comprehensive understanding of Clea OS’s role within the Clea product stack, please refer to the Clea OS as part of the Clea suite and to the Clea OS Architecture page. These pages highlight how the Clea OS Thing distro is preconfigured with all necessary components to connect to Clea’s cloud services, including Clea Astarte for data orchestration and Clea Edgehog for device management. Ensure you have reviewed these resources before proceeding.

In this page, you will find detailed instructions to effectively set up a device running Clea OS to connect it to Clea Cloud. This process includes properly configuring both Clea Astarte and Clea Edgehog, using your personal credentials to modify the necessary configuration files in the OS. Following these steps ensures that your device is correctly integrated into the Clea ecosystem, enabling full utilization of the cloud services provided by Clea.

A necessary requirement is having a device with Clea OS installed and access to online instances of Clea Astarte and Clea Edgehog to connect to. Check the pages in the Get Started section to learn how to compile and flash a device from scratch with Clea OS, or download a precompiled Clea OS Things image directly from the Release page to use on a device.

Connect your Device to Clea online services

This page will guide you through the manual configuration that should be performed to connect a new device to Clea. First, this section will show you how to manually register a device to Clea Astarte, and how to configure the previously flashed device, using the credentials obtained during the registration process.

info

This kind of manual procedure to connect a new device is useful as a starting point for a demo or a trial connection. The data orchestation platform Clea Astarte also supports a fully automated registration process that is raccomanded to be used in production and is explained in the Clea Astarte documentation but not covered here in this page.

The main components already installed in Clea OS Things that allow communication with the Clea online platforms are:

• Astarte Message Hub: astarte-message-hub - A central service written in Rust for collecting and delivering messages to Astarte. Thanks to this component, which acts as an aggregator, it is possible to have multiple applications on the device communicating with Astarte, sending different data that are recognized as coming from a single device ID.
• Edgehog Device Runtime: edgehog-device-runtime - A portable middleware written in Rust that enables remote device management using Edgehog. This agent communicates to and from Astarte/Edgehog by passing data through the astarte-message-hub.

What you need in advance:

• A previously flashed board with Clea OS Things. Check the Flashing image page to know how to prepare a device.
• Astarte Dashboard URL
• Edgehog Dashboard URL
• Astarte API URL
• Astarte Realm
• Astarte Auth Token
• Edgehog Tenant Slug
• Edgehog Auth Token

Registering a Device

• Connect to Clea admin portal using the URL and admin credentials provided to you after the registration, and enter in your tenant (or create a new one).

• In the left menu, go to the “Devices” section under the "Clea Astarte" group, and click the “Register new device“ button on the bottom part of the page.

• Generate a random device ID for the device you want to register or generate it from the name and click on “Register device“.

• The action will create a "Credentials secret" which shall be seen as a token that uniquely identifies the Device to Astarte and Edgehog portals, copy and save it for later use when setting up the Astarte Message Hub on the device.

Configuring the board

Astarte Message Hub

This guide will show how to configure the Astarte Message Hub service that allows to connect multiple applications and system services using just one MQTT connection to Astarte such as the Edgehog Device Runtime application to manage the life-cycle and collect system information of the device.

• Edit the Astarte Message Hub config file using the vi editor. Run the following command in the device to open the configuration file

# vi /etc/message-hub/config.toml 

• Use the insert mode (i) to change the variable values according to the lines below:

##
# Required fields
#
realm = “<REALM>”
pairing_url = “<PAIRING_URL>”
grpc_socket_port = 50051 # Required, 0 is only a placeholder
##
# Optional fields
#
interfaces_directory = “/usr/share/edgehog/astarte-interfaces/”
# Device ID, if not provided it will be retrieved from `io.edgehog.Device` dbus-service
device_id = “<device_id>”
# Credential secret, if not provided the `pairing_token` is required
credentials_secret = “<credentials_secret>”
# Ignore SSL errors, defaults to false
astarte_ignore_ssl = false
# Path to store persistent data, defaults to “./”
store_directory = "/var/lib/edgehog/"

where credentials_secret and device_id are respectively the “Credentials secrets“ and “Device ID” created in the previous steps.

Edgehog Device Runtime

In order for the device to be correctly recognised in the Clea Edgehog, it is important that the "serial number" and "part number" information are set on the board as variables.
In particular, the <part-number> variable allow the board to be identified with a particular System Model and Hardware Type in the Clea Edgehog portal.
For a better understanding of these two concepts, you can also have a look at this Clea Edgehog documentation page.

These two information can be set for the Edgehog Device Runtime as environment variables.

• Open the Edgehog Device Runtime service configuration file

# vi /lib/systemd/system/edgehog-device-runtime.service

• Use the insert mode (i) to insert the following lines below the [Service] section:

[Service]
....
Environment="EDGEHOG_SYSTEM_SERIAL_NUMBER=<serial-number>"
Environment="EDGEHOG_SYSTEM_PART_NUMBER=<part-number>"

Restart the Astarte and Edgehog services

Once the file is correctly changed, restart the Astarte and Edgehog platform-related services via the command

# systemctl restart edgehog-device-runtime.service edgehog-hardware-id.service astarte-message-hub.service

or reboot the board to connect the Astarte Message Hub to the Astarte Cloud instance.

Display your Device on Clea Astarte Dashboard

In the Clea admin panel dashboard of your tenant, go to the Clea Astarte group in the left menu and click on "Devices" to see the list of devices registered in the tenant. Each device in the list is displayed with information about its status and the last connection event. The status is represented by a grey dot if the device has never connected to Astarte, a green dot if it is currently connected, a red dot if it is currently disconnected. The last connection event shows the date of the last connection or disconnection, if available.

Filter and select your device ID to check the status of your device and how it is configured.

Display your Device on Clea Edgehog Dashboard

In the Clea admin panel dashboard of your tenant, go to the Clea Edgehog group in the left menu and click on "Fleet" to see the list of devices registered in the tenant that enables the Clea Edgehog Device Manager functionalities to send and receive data via the Edgehog Device Runtime.

Go to the Device page and select your device ID to see the data sent by the device to the Clea Edgehog portal.

From this page it is also possible to access the functions provided by each device, such as remote terminal access (for Linux devices) and OTA update campaigns for the board's operating system or firmware.

To test an OTA Operating System update on a single device, a RAUC bundle from the Clea OS Things build needs to be uploaded to the Clea Edgehog portal for online delivery to the device.
To find out which command to use to compile a Clea OS Things OTA bundle, refer to the end of the Build section of the Build Clea OS page.