device-envoy-esp

Build ESP32 applications with composable device abstractions.

device-envoy-esp is an embedded Rust library built on Embassy and esp-hal. It organizes hardware around device abstractions so application code can use small, focused APIs instead of managing low-level coordination directly.

Currently targeting ESP32-C6 and ESP32-S3 in device-envoy-esp, and Raspberry Pi Pico 1 and Pico 2 (ARM cores) in device-envoy-rp.

Start From a Template

Want a minimal starting project?

• device-envoy-esp-blinky on GitHub

Status

⚠️ Alpha / Experimental

The API is actively evolving and may change without compatibility guarantees.

Features

• LED Strips & Panels - NeoPixel-style (WS2812) LED arrays with 2D text rendering, animation, embedded-graphics support. Provides efficient options for power limiting and color correction.
• WiFi - Connect to the Internet with automatic credentials management. On boot, opens a web form if WiFi credentials aren't saved, then connects seamlessly to a stored network.
• Audio Player - Play audio clips over I²S hardware with runtime sequencing, volume control, and compression.
• Button Input - Button handling with debouncing
• Servo Control - Servo positioning and animation
• Flash Storage - Type-safe, on-board persistent storage
• LCD Display - Text display (HD44780)
• IR Remote - Remote control decoder (NEC protocol)
• RFID Reader - Card detection and reading (MFRC522)
• Clock Sync - Network time synchronization utilities
• LED4 Display - 4-digit, 7-segment LED display control with optional animation and blinking
• Single LED - Single LED control with animation support

Forum

• Using Embassy to build applications
  A place to talk about writing embedded applications with Embassy: sharing code, asking practical questions, and learning what works in practice.
  Not limited to Pico or ESP boards, or to device-envoy.

Videos and Articles

• device-envoy: Making Embedded Fun with Rust, Embassy, and Composable Device Abstractions -- versions: article or video
• How Rust & Embassy Shine on Embedded Devices by Carl M. Kadie and Brad Gibson.
• More Rust articles

Thanks

Special thanks to Brad Gibson, organizer of the Seattle Rust User Group. He introduced me to Rust programming on microcontrollers, suggested the term device abstraction, and encouraged thinking in terms of shared traits across controller families. Those conversations helped set the goals for device-envoy.

Examples & Demos

The project includes examples (single-device tests) in examples/ showing integration patterns:

Example: animated LED strip

This example cycles a 96-LED strip through red, green, and blue frames.

It shows how device-envoy generates a struct (device abstraction) for an LED strip and then animates a sequence of frames.

# #![no_std]
# #![no_main]
# use esp_backtrace as _;
# use core::convert::Infallible;
use device_envoy_esp::{Result, init_and_start, led_strip, led_strip::{LedStrip as _, Frame1d, colors}};
use embassy_time::Duration;

led_strip! {
    LedStripAnimated {
        pin: GPIO18,
        len: 96,
    }
}

async fn example(spawner: embassy_executor::Spawner) -> Result<Infallible> {
    init_and_start!(p, rmt80: rmt80, mode: rmt_mode::Blocking);
    let led_strip_animated = LedStripAnimated::new(p.GPIO18, rmt80.channel0, spawner)?;

    // Create a sequence of frames and durations and then animate them (looping, until replaced).
    let frame_duration = Duration::from_millis(300);
    led_strip_animated.animate([
        (Frame1d::filled(colors::RED), frame_duration),
        (Frame1d::filled(colors::GREEN), frame_duration),
        (Frame1d::filled(colors::BLUE), frame_duration),
    ]);

    core::future::pending().await // run forever
}

For complete, runnable examples (including wiring and setup), see the examples/ directory.

• Basic LED Examples: Simple on/off control with blinky pattern
• LED Strip Examples: Simple animations, color control, text rendering
• LED Panel Examples: 12×8, 16×16, and multi-panel configurations with graphics

• Button Examples: Debouncing and state handling
• Servo Examples: Position sweeps and animation playback
• WiFi Examples: WiFi setup, time sync, DNS
• Flash Examples: Configuration persistence and data reset

See the examples/ directory for complete runnable code.

Building & Running

• If you just want to use this library, start from the template project: device-envoy-esp-blinky.
• If you want to edit this project, see the Development Guide.

Glossary

Resources commonly used in device-envoy-esp:

• RMT (Remote Control Transceiver): ESP32-C6: 4 channels. ESP32-S3: 8 channels.
• LEDC (LED PWM Controller): ESP32-C6: 4 timers, 6 channels. ESP32-S3: 4 timers, 8 channels.
• DMA (Direct Memory Access): ESP32-C6: 3 channels (DMA_CH0-DMA_CH2). ESP32-S3: 5 channels (DMA_CH0-DMA_CH4).
• I2S (Inter-IC Sound): ESP32-C6: 1 controller (I2S0). ESP32-S3: 2 controllers (I2S0, I2S1).
• I2C (Inter-Integrated Circuit): ESP32-C6: 2 controllers. ESP32-S3: 2 controllers.
• SPI (Serial Peripheral Interface): ESP32-C6: 2 peripherals. ESP32-S3: 3 peripherals.

Policy on AI-assisted development and contributions

The use of AI tools is permitted for development and contributions to this repository. AI may be used as a productivity aid for drafting, exploration, and refactoring.

All code and documentation contributed to this repository must be reviewed, edited, and validated by a human contributor. AI tools are not a substitute for design judgment, testing, or responsibility for correctness.

AGENTS.md contains the general instructions and constraints given to AI tools used during development of this repository.

License

Licensed under either:

• MIT license (see the repository root LICENSE-MIT file)
• Apache License, Version 2.0 (see the repository root LICENSE-APACHE file)

at your option.