Clea Framework IoT Services Architecture

This document describes the architecture of the Clea integration as implemented in the Yocto layer meta-seco-clea-os, focusing on the components in recipes-iot.

Overview

The Clea Cloud stack for IoT devices is composed of several Rust-based applications and supporting services, each packaged and managed by Yocto recipes. These components enable secure device management, telemetry, OTA updates, and cloud connectivity via Astarte and Edgehog.

Main Components

Edgehog Device Runtime
- Middleware for device management, monitoring, OTA, and container orchestration.
- Communicates with the cloud via Astarte Device SDK or Astarte Message Hub.
- See: edgehog-device-runtime
Astarte Message Hub
- D-Bus service that multiplexes messages between device services and the Astarte backend.
- Allows multiple applications to share a single Astarte connection.
- See: astarte-message-hub
Edgehog Astarte Interfaces
- Defines the Astarte interfaces used for device-cloud communication.
- See: edgehog-astarte-interfaces
Service Wrappers
For more details, see Service Wrappers.
- Examples: service-edgehog-device-runtime, [service-astarte-message-hub]https://git.seco.com/clea-os/layers/seco/meta-seco-clea-os/-/blob/scarthgap/recipes-iot/service-edgehog-device-runtime/service-astarte-message-hub.bb?ref_type=heads)

How Recipes and Services Work Together

Yocto Recipes
Each application or service is described by a Yocto recipe (.bb file). The recipe:
- Fetches source code or binaries.
- Builds the application (often using Rust and Cargo).
- Installs binaries, configuration files, and systemd unit files to the target rootfs.
How .bb files are generated for Rust projects:
For Rust-based components, we use cargo-bitbake, a tool that generates BitBake recipes directly from a Cargo project.
Run the following command inside the Rust project directory to generate a starting .bb file:
```
cargo bitbake
```
This produces a BitBake recipe tailored for the Rust crate, which can then be customized as needed for integration into the Yocto build.
Technical Details: Building Rust Applications with BitBake and Cargo
The Rust-based components (such as Edgehog Device Runtime and Astarte Message Hub) are built using the bitbake build system, which is part of Yocto.
- The recipes leverage the cargo class provided by Yocto to build Rust projects.
- During the build, BitBake executes the cargo command inside the source repository, ensuring all dependencies are fetched and the binaries are compiled for the target architecture.
- This approach allows seamless integration of Rust projects into the Yocto build pipeline, producing reproducible and cross-compiled binaries suitable for embedded devices.
Systemd Service Recipes
For each main application, a corresponding service recipe provides:
- A systemd unit file (e.g., edgehog-device-runtime.service).
- A wrapper script if needed.
- Ensures the service is enabled and started at boot.
Integration Example
- The runtime and message hub are both installed and managed as systemd services.
- The runtime can communicate directly with Astarte or via the message hub, depending on configuration.
- All services are started and monitored by systemd, as defined in the service recipes.

Architecture Diagram

flowchart TD
  subgraph Device["Device (Linux System)"]
    A1["Client Service (App, Sensor Agent)"]
    A2["Client Service (Logger, Updater)"]
    MH["Astarte Message Hub (D-Bus Service)"]
    A1 -- D-Bus --> MH
    A2 -- D-Bus --> MH
  end

  MH -- MQTT/WebSocket --> AB["Astarte Backend"]

  style Device fill:#ffeeee,stroke:#333,stroke-width:2,rx:10
  style A1 fill:#fff,stroke:#333,stroke-width:1,rx:5
  style A2 fill:#fff,stroke:#333,stroke-width:1,rx:5
  style MH fill:#bbccff,stroke:#333,stroke-width:2,rx:5
  style AB fill:#bbffbb,stroke:#333,stroke-width:2,rx:5

Legend:

Client services on the device communicate with the Message Hub via D-Bus.
The Message Hub manages a single connection to the Astarte backend (MQTT/WebSocket).
Client services do not need to implement Astarte SDK logic; they use D-Bus calls/signals.

File and Recipe Structure

recipes-iot/astarte-message-hub/:
- astarte-message-hub_0.5.4.bb: Builds and installs the message hub daemon.
- files/: Contains systemd unit files and scripts.
recipes-iot/edgehog-device-runtime/:
- edgehog-device-runtime_0.8.1.bb: Builds and installs the device runtime.
- edgehog-astarte-interfaces_0.8.0.bb: Installs Astarte interface definitions.
recipes-iot/service-edgehog-device-runtime/:
- service-edgehog-device-runtime.bb: Installs and enables the runtime as a systemd service.
- service-astarte-message-hub.bb: Installs and enables the message hub as a systemd service.

Summary Table

Component	Recipe/Service Name	Role
Edgehog Device Runtime	`edgehog-device-runtime`	Device management middleware
Astarte Message Hub	`astarte-message-hub`	D-Bus to Astarte bridge
Edgehog Astarte Interfaces	`edgehog-astarte-interfaces`	Astarte interface definitions
Runtime Service Wrapper	`service-edgehog-device-runtime`	Systemd service for runtime
Message Hub Service Wrapper	`service-astarte-message-hub`	Systemd service for message hub

Overview​

Main Components​

How Recipes and Services Work Together​

Architecture Diagram​

File and Recipe Structure​

Summary Table​

References​