Skip to main content

Edgehog Device Runtime

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

Overview​

Edgehog Device Runtime communicates with the Device Manager backend via Data Orchestrator 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 Data Orchestrator 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).
  • Data Orchestrator instance: You must have access to a working Data Orchestrator 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 Data Orchestrator​

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

Astarte Device SDK​

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

Astarte Message Hub​

  • A local service that multiplexes device messages to Data Orchestrator
  • 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:

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 Data Orchestrator realm
  • Set up session timeout and activity tracking

Diagram:

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 Data Orchestrator

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​