Skip to main content
Version: scarthgap_2-x

Edgehog Device Runtime

Edgehog Device Runtime is a middleware written in Rust that enables remote device management via Astarte. This document serves as a developer-oriented guide for contributing to or extending the Edgehog Device Runtime.

Overview​

Edgehog Device Runtime communicates with the Edgehog backend via Astarte using either:

  • Astarte Device SDK Rust
  • Astarte Message Hub

It implements various features like OS and hardware monitoring, network status, OTA updates, battery reporting, and more, based on Astarte interfaces defined in edgehog-astarte-interfaces.

Getting Started​

Prerequisites​

Make sure you have the following installed on your development machine:

  • Rust: Use rustup to install the latest stable version.
  • Cargo: Comes bundled with Rust.
  • Git: For cloning the repository.
  • Systemd: Required for service status monitoring (Linux only).
  • Astarte instance: You must have access to a working Astarte backend.

Clone the Repository​

git clone https://github.com/edgehog-device-manager/edgehog-device-runtime.git
cd edgehog-device-runtime

Build the Project​

You can build the project in debug mode:

cargo build

For production-ready builds:

cargo build --release

To include container management support:

cargo build --features containers

Running the Runtime​

Start the runtime using:

cargo run

With custom config:

cargo run -- --config path/to/edgehog-config.toml

View help options:

cargo run -- --help

Configuration​

Edgehog Device Runtime supports multiple paths for configuration files in TOML format. The configuration file is searched in the following order:

  1. Path provided via CLI (--config <path>)
  2. $PWD/edgehog-config.toml
  3. /etc/edgehog/config.toml

Example Configuration File​

[general]
device_id = "my-device-001"
transport = "astarte-message-hub" # Options: "astarte-message-hub", "astarte-device-sdk"

[logging]
level = "info"  # Options: "debug", "info", "warn", "error"

[container]
engine = "podman"  # Options: "podman", "docker"
timeout_seconds = 30

Features Implemented​

FeatureDescription
OS InfoExtracted from /etc/os-release
Hardware InfoCPU, memory, disk, and other hardware-related metadata
System StatusCPU load, memory usage, uptime from /proc
Network InterfacesIP addresses, MAC, connection state
Battery StatusRead from ACPI or sysfs for battery presence and metrics
OTA UpdatesIntegrates with RAUC for secure image-based updates
Remote TerminalAllows admin to start terminal sessions remotely
Container ManagementManage lifecycle of containers on the target device
Runtime InfoDisplays Rust compiler version and crate version

Communication With Astarte​

Edgehog Device Runtime uses Astarte interfaces to exchange data with the backend. Interfaces define what data is collected and how it’s structured.

Astarte Device SDK​

  • Communicates directly with Astarte using MQTT and pairing tokens
  • Lightweight and suitable for devices with reliable connectivity

Astarte Message Hub​

  • A local service that multiplexes device messages to Astarte
  • Useful for running multiple services on one device with a shared connection
  • Must be installed and running on the device

OTA Updates with RAUC​

The runtime can report and trigger updates via RAUC. Configuration must include:

[ota]
backend = "rauc"

Ensure RAUC is installed and properly configured with signed bundles and active/passive slots.

Diagram:

flowchart TD
  EDR[Edgehog Device Runtime]
  RAUC[RAUC OTA Manager]
  FLASH[Flash Partitions]

  EDR -->|Triggers update| RAUC
  RAUC -->|Writes image| FLASH

  style EDR fill:#e0f7fa,stroke:#333,stroke-width:1.5,rx:8
  style RAUC fill:#fff9c4,stroke:#333,stroke-width:1.5,rx:8
  style FLASH fill:#ffe0b2,stroke:#333,stroke-width:1.5,rx:8

Remote Terminal Sessions​

The runtime exposes a secure channel for initiating terminal sessions from the cloud. It supports session logs and can be integrated with audit tools.

Security recommendations:

  • Ensure proper authentication on the Astarte realm
  • Set up session timeout and activity tracking

Diagram:

flowchart LR
  Browser[Browser]
  Astarte[Astarte Backend]
  Edgehog[Edgehog Device]

  Browser -- "Web UI/API" --> Astarte
  Astarte -- "MQTT/WebSocket" --> Edgehog
  Edgehog -- "Telemetry/Control" --> Astarte
  Astarte -- "Web UI/API" --> Browser

  style Browser fill:#e3f2fd,stroke:#333,stroke-width:1.5,rx:8
  style Astarte fill:#c8e6c9,stroke:#333,stroke-width:1.5,rx:8
  style Edgehog fill:#ffe0b2,stroke:#333,stroke-width:1.5,rx:8

Container Management (Optional)​

When built with the containers feature, Edgehog Device Runtime can:

  • Start, stop, and monitor containers
  • Pull new container images
  • Report container health to Astarte

Configure in config.toml:

[container]
engine = "podman"
timeout_seconds = 30

Supported engines:

  • Docker
  • Podman

The container interface allows remote orchestration of edge applications.

Development Tips​

Code Style​

  • Format code using cargo fmt
  • Use idiomatic Rust patterns and error handling

Testing​

Run the full test suite:

cargo test

Linting and Static Analysis​

Run Clippy to detect common Rust issues:

cargo clippy

Ensure no warnings or panics exist before submitting changes.

References​