Crate device_envoy_esp

Expand description

§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.

Animated 96-LED strip example (APNG)

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

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

Animated LED panel Go Go example

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.

Modules§

audio_player: A device abstraction for playing audio clips over I²S hardware, with runtime sequencing, volume control, and compression.
button: A device abstraction for buttons with debouncing and press duration detection.
clock_sync: A device abstraction that combines NTP time synchronization with a local clock.
docs: Documentation-only pages for this crate.
flash_block: A device abstraction for type-safe persistent storage in flash memory.
init_and_start: Shared startup helpers for Embassy runtime and common ESP peripherals.
ir: A device abstraction for infrared receivers using the NEC protocol.
lcd_text: A device abstraction for HD44780-compatible character LCDs (e.g., 16x2, 20x2, 20x4).
led: A device abstraction for a single digital LED with animation support.
led4: A device abstraction for a 4-digit, 7-segment LED display for text with optional animation and blinking.
led2d: A device abstraction for rectangular NeoPixel-style (WS2812) LED panel displays. For 1-dimensional LED strips, see the led_strip module.
led_strip: A device abstraction for 1-dimensional NeoPixel-style (WS2812) LED strips. For 2-dimensional panels, see the led2d module.
rfid: A device abstraction for RFID readers using the MFRC522 chip.
servo: A device abstraction for hobby servos on ESP LEDC PWM.
wifi_auto: A device abstraction that connects ESP devices with Wi-Fi to the Internet and, when needed, creates a temporary Wi-Fi network to enter credentials.

Enums§

Error

Type Aliases§

Result