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

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 (or on GitHub: development.md).

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.