# device-envoy-esp

[![GitHub](https://img.shields.io/badge/github-device--envoy-8da0cb?style=flat&labelColor=555555&logo=github)](https://github.com/CarlKCarlK/device-envoy)
[![crates.io](https://img.shields.io/crates/v/device-envoy-esp?style=flat&color=fc8d62&logo=rust)](https://crates.io/crates/device-envoy-esp)
[![docs.rs](https://img.shields.io/docsrs/device-envoy-esp?style=flat&color=66c2a5&labelColor=555555)](https://docs.rs/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`](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/), and Raspberry Pi Pico 1 and Pico 2 (ARM cores) in [`device-envoy-rp`](https://docs.rs/device-envoy-rp/latest/device_envoy_rp/).

## Start From a Template

Want a minimal starting project?

- [`device-envoy-esp-blinky` on GitHub](https://github.com/CarlKCarlK/device-envoy-esp-blinky)

## Status

⚠️ **Alpha / Experimental**

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

## Features

- **[LED Strips](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/led_strip/) & [Panels](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/led2d/)** - NeoPixel-style (WS2812) LED arrays with 2D text rendering, animation, embedded-graphics support. Provides efficient options for power limiting and color correction.
- **[WiFi](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/wifi_auto/)** - 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](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/audio_player/)** - Play audio clips over I²S hardware with runtime sequencing, volume control, and compression.
- **[Button Input](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/button/)** - Button handling with debouncing
- **[Servo Control](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/servo/)** - Servo positioning and animation
- **[Flash Storage](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/flash_block/)** - Type-safe, on-board persistent storage
- **[LCD Display](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/lcd_text/)** - Text display (HD44780)
- **[IR Remote](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/ir/)** - Remote control decoder (NEC protocol)
- **[RFID Reader](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/rfid/)** - Card detection and reading (MFRC522)
- **[Clock Sync](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/clock_sync/)** - Network time synchronization utilities
- **[LED4 Display](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/led4/)** - 4-digit, 7-segment LED display control with optional animation and blinking
- **[Single LED](https://docs.rs/device-envoy-esp/latest/device_envoy_esp/led/)** - Single LED control with animation support

## Forum

- **[Using Embassy to build applications](https://github.com/CarlKCarlK/device-envoy/discussions)**  
  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](https://medium.com/@carlmkadie/device-envoy-making-embedded-fun-31534917414b) -- versions: [article](https://medium.com/@carlmkadie/device-envoy-making-embedded-fun-31534917414b) or [video](https://www.youtube.com/watch?v=iUu6hvJLVOU)
- [How Rust & Embassy Shine on Embedded Devices](https://medium.com/@carlmkadie/how-rust-embassy-shine-on-embedded-devices-part-1-9f4911c92007) by Carl M. Kadie and Brad Gibson.
- [More Rust articles](https://medium.com/@carlmkadie)

## Thanks

Special thanks to [Brad Gibson](https://github.com/U007D/), organizer of the [Seattle Rust User Group](https://www.meetup.com/seattle-rust-meetup/). 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)](https://raw.githubusercontent.com/CarlKCarlK/device-envoy/main/docs/assets/led_strip_animated.png)

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

```rust,no_run
# #![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

![Animated LED panel Go Go example](https://raw.githubusercontent.com/CarlKCarlK/device-envoy/main/docs/assets/led2d2.png)

- **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`](https://github.com/CarlKCarlK/device-envoy-esp-blinky).
- If you want to edit this project, see the [Development Guide](docs/development_guide/index.html).

## Glossary

Resources commonly used in `device-envoy-esp`:

- **RMT** ([Remote Control Transceiver](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/rmt.html)): ESP32-C6: 4 channels. ESP32-S3: 8 channels.
- **LEDC** ([LED PWM Controller](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/ledc.html)): ESP32-C6: 4 timers, 6 channels. ESP32-S3: 4 timers, 8 channels.
- **DMA** ([Direct Memory Access](https://en.wikipedia.org/wiki/Direct_memory_access)): ESP32-C6: 3 channels (`DMA_CH0`-`DMA_CH2`). ESP32-S3: 5 channels (`DMA_CH0`-`DMA_CH4`).
- **I2S** ([Inter-IC Sound](https://en.wikipedia.org/wiki/I%C2%B2S)): ESP32-C6: 1 controller (`I2S0`). ESP32-S3: 2 controllers (`I2S0`, `I2S1`).
- **I2C** ([Inter-Integrated Circuit](https://en.wikipedia.org/wiki/I2C)): ESP32-C6: 2 controllers. ESP32-S3: 2 controllers.
- **SPI** ([Serial Peripheral Interface](https://en.wikipedia.org/wiki/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](https://github.com/CarlKCarlK/device-envoy/blob/main/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.
