thin-edge.io

Imported from thin-edge/thin-edge.io (AGENTS.md). Install upstream with npx skills add thin-edge/thin-edge.io. Copyright stays with the author.

AGENTS.md

This file provides guidance for AI coding agents working with code in this repository.

Project Overview

thin-edge.io is an open-source, cloud-agnostic edge framework for resource-constrained IoT devices. It's written in Rust and provides device management, telemetry, and multi-cloud connectivity (AWS, Azure, Cumulocity) for industrial IoT applications.

Key characteristics:

• Actor-based architecture using async Rust with tokio
• MQTT as the primary inter-process communication mechanism
• Plugin system for extensibility
• Designed for resource-constrained devices (low RAM, embedded Linux)
• Minimum Rust version: 1.92

Common Commands

Building

# Build all components (creates binaries and packages)
just release

# Build for specific target (cross-compilation supported automatically)
just release TARGET

# Example targets:
# - x86_64-unknown-linux-musl
# - aarch64-unknown-linux-musl
# - armv7-unknown-linux-musleabihf

Testing

# Run all unit and doc tests
just test

# Run only unit tests
just test-unit

# Run specific test
cargo nextest run --status-level fail --all-features test_name

# Run doc tests only
just test-docs

# Run integration tests (builds first, then runs Robot Framework tests)
just integration-test

# Run specific integration test suite
just integration-test --test PATTERN

Code Quality

# Format code (includes Rust, TOML, and Robot Framework tests)
just format

# Check formatting without modifying files
just format-check

# Run linting (clippy + dependency checks)
just check

# Check for specific target
just check TARGET

# Check dependencies (licenses, security advisories)
just check-dependencies

Development Setup

# One-time setup: install required tools and configure git hooks
just install-tools

# The prepare-dev command adds a git pre-commit hook that automatically
# adds the required "Signed-off-by" trailer to commits (required by CLA)
just prepare-dev

# Setup integration test environment (one-time setup)
just setup-integration-test

Architecture

High-Level Design

thin-edge.io uses a distributed actor-based architecture where components communicate via:

1. Local MQTT broker - primary IPC mechanism on localhost:1883
2. Actor message passing - type-safe async channels within processes

Core concepts:

• Actors: Independent, concurrent units that process messages
• Runtime: Manages actor lifecycle, graceful shutdown, and crash handling
• Message boxes: Type-safe channels connecting actors
• Builders: Declarative actor composition with compile-time guarantees

Directory Structure

crates/
├── core/               # Essential components (always included)
│   ├── tedge/          # Main CLI binary (multicall pattern)
│   ├── tedge_actors/   # Actor framework (minimal dependencies)
│   ├── tedge_mapper/   # Cloud data translation engine
│   ├── tedge_agent/    # Cloud-agnostic operations handler
│   ├── tedge_api/      # Domain models and APIs
│   ├── plugin_sm/      # Plugin manager for software operations
│   ├── tedge_write/    # File writing utility
│   └── tedge_watchdog/ # Process monitoring
├── common/             # Utility libraries
│   ├── mqtt_channel/   # MQTT client wrapper
│   ├── tedge_config/   # Configuration definition
│   ├── download/       # HTTP file download utilities
│   ├── upload/         # HTTP file upload utilities
│   └── ...
├── extensions/         # Extensions of tedge_mapper and tedge_agent
│   ├── *_mapper_ext/   # Cloud provider mappers (c8y, aws, az)
│   ├── tedge_mqtt_ext/ # MQTT actor
│   ├── tedge_flows/    # JavaScript flow engine (QuickJS)
│   ├── tedge_*_ext/    # Various actor extensions
│   └── ...
└── tests/              # Shared testing utilities

plugins/                # Plugin binaries (separate processes)
├── tedge_apt_plugin/   # Package management (apt)
├── c8y_*_plugin/       # Cumulocity-specific plugins
└── tedge_file_*_plugin/# File operations plugins

tests/RobotFramework/   # End-to-end system tests

Main Binaries

The project builds a multicall binary that acts as different executables based on its name or command:

1. tedge - Main CLI tool

   • Entry point: crates/core/tedge/src/main.rs
   • Commands: tedge run, tedge config, tedge cert, etc.
   • Can spawn mapper, agent, and other components

2. tedge-mapper - Cloud protocol translator

   • Runs as: tedge run mapper [c8y|aws|az|collectd]
   • Translates between thin-edge.io data model and cloud-specific formats
   • Each cloud provider has its own mapper implementation

3. tedge-agent - Device operations handler

   • Runs as: tedge run agent
   • Handles: software management, device restart, config management and log uploads out of the box using built-in workflows
   • Supports plugins to extend built-in operations
   • Extensible to support other custom operations as well via custom workflows

MQTT Topic Hierarchy

te/device/main//                      # Main device topic prefix and registration topic
te/device/child01//                   # Child device topic prefix and registration topic
te/device/main/service/tedge-agent    # Service topic prefix and registration topic
te/device/main///m/temperature/+      # Telemetry (outbound)
te/device/main///cmd/restart/+        # Commands (inbound)
te/device/main///status/health/+      # Status (outbound)

# Cloud-specific topics are handled by mappers
c8y/...                               # Cumulocity topics
aws/...                               # AWS IoT topics
az/...                                # Azure IoT topics

Mappers: Cloud Integration Layer

Mappers translate between thin-edge.io's cloud-agnostic data model and cloud provider-specific formats.

Data flow:

Device → te/* topics → Mapper → Cloud-specific topics → MQTT Bridge → Cloud
Cloud → MQTT Bridge  → Mapper → te/* topics → Agent/Services

Mapper implementations:

• c8y_mapper_ext: Cumulocity IoT (most feature-complete)
• aws_mapper_ext: AWS IoT Core (flows-based)
• az_mapper_ext: Azure IoT Hub (flows-based)
• collectd_ext: Collectd metrics integration

Key mapper features:

• Bidirectional translation (cloud ↔ device)
• Flow-based transformations (JavaScript rules via QuickJS)
• File upload/download coordination
• Health monitoring and auto-reconnection
• Operation state management

Plugins: Process Isolation for Operations

Plugins are separate executables (not dynamically loaded libraries) that handle specific operations.

Plugin execution model:

1. Agent receives operation via MQTT
2. Agent selects plugin based on operation type
3. Agent spawns plugin as child process with CLI args
4. Plugin executes (uses system commands, modifies files, etc.)
5. Plugin writes logs to files
6. Agent reads logs and publishes status to MQTT

Built-in plugins:

• tedge-apt-plugin: System package management
• tedge-file-config-plugin: Configuration file management
• tedge-file-log-plugin: Log file uploads
• c8y-firmware-plugin: Firmware updates
• c8y-remote-access-plugin: Remote SSH/VNC access

Plugin benefits:

• Process isolation (crash safety)
• Language flexibility (can be shell scripts)
• Independent versioning

Code Style and Conventions

General Guidelines

Refer to @CODING_GUIDELINES.md

Actor Development Patterns

Use the .agent/skills/add-actor skill while creating new actors.

Testing

Test Organization

• Unit tests: In the same file as code or in tests.rs module
• Integration tests: crates/tests/ directory
• End-to-end tests: tests/RobotFramework/ (Python-based)

Testing Actor-Based Code

When testing actors:

• Use message boxes directly to inject test messages
• Use tokio::time::timeout() to prevent hanging tests
• Mock external dependencies (MQTT, HTTP, file system)
• Test crash recovery and error paths

Robot Framework Tests

Integration tests use Robot Framework with custom device adapters:

• Local adapter: Tests against localhost
• Docker adapter: Tests in containers
• SSH adapter: Tests on remote devices

Setup requires .env file with cloud credentials (see tests/RobotFramework/devdata/env.template).

Use the .agent/skills/add-integration-test skill while creating new tests.

Git Workflow and Commits

Commit Requirements

MANDATORY for all commits:

• Include Signed-off-by trailer (use git commit -s)
• Follow conventional commits for commit messages
• Conventional commits protocol is defined at https://www.conventionalcommits.org/en/v1.0.0/

Pull Request Guidelines

• One issue per PR - keep scope focused
• Do NOT use GitHub auto-close keywords (Fixes #123) - testers close issues manually
• Use git commit --fixup=<sha> for review feedback
• Squash fixup commits before merging (git rebase -i --autosquash main)
• At least one maintainer approval required
• Merging via bors-ng bot - prevents merge skew

License and Dependencies

• All code is Apache 2.0 licensed
• License linting via cargo-deny (run with just check-dependencies)
• Dependencies must be compatible with Apache 2.0
• Keep dependencies synchronized across workspace crates

Rust Conventions

• Error handling: Use #[derive(Debug, thiserror::Error)] with #[from] and #[error(transparent)] for error type composition
• Workspace deps: All crates use { workspace = true } for version, edition, and license; lints centralized with [lints] workspace = true
• Safety: #![forbid(unsafe_code)] in all crates
• Release profile: opt-level = "z", LTO enabled, symbol stripping (optimized for embedded)

Markdown style

When writing or editing Markdown documents, use semantic line breaks: start a new line after each sentence, and optionally break long sentences at clause boundaries (after commas, semicolons, colons, or dashes).

When editing existing documents that don't use semantic line breaks, apply them only to the lines you add or modify. Do not reformat the rest of the document.

Troubleshooting

Build Issues

• Cross-compilation fails: Install cargo-zigbuild for better cross-compilation support
• Linker errors on musl: Check that you're using the correct musl toolchain
• Dependency conflicts: Run cargo update and cargo tree to debug

Test Issues

• Integration tests fail: Ensure .env file is configured with valid cloud credentials
• Robot Framework not found: Run just setup-integration-test
• Tests hang: Check that local MQTT broker (rumqttd) is running and port 1883 is available

Additional Resources

• Documentation: docs/ directory
• Design documents: design/ directory
  • thin-edge-actors-design.md - Actor framework architecture
  • thin-edge-core.md - Core component design
• Vision and goals: vision.md
• Contributing guide: CONTRIBUTING.md
• Coding guidelines: CODING_GUIDELINES.md