blinksy_esp/lib.rs
1#![no_std]
2
3//! # ESP32 Blinksy Extensions
4//!
5//! ESP32-specific extensions for the [Blinksy][blinksy] LED control library using [`esp-hal`][esp_hal].
6//!
7//! ## Features
8//!
9//! - ESP-specific driver for clockless (e.g. WS2812) LEDs, using [RMT (Remote Control Module)][RMT] peripheral
10//! - ESP-specific elapsed time helper
11//!
12//! [RMT]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/rmt.html
13//!
14//! ## Example
15//!
16//! ```rust
17//! #![no_std]
18//! #![no_main]
19//!
20//! use esp_hal as hal;
21//!
22//! use blinksy::{
23//! driver::ClocklessLed,
24//! drivers::ws2812::Ws2812Led,
25//! layout::Layout1d,
26//! layout1d,
27//! patterns::rainbow::{Rainbow, RainbowParams},
28//! ControlBuilder,
29//! };
30//! use blinksy_esp::{create_rmt_buffer, time::elapsed, Ws2812Rmt};
31//!
32//! #[hal::main]
33//! fn main() -> ! {
34//! let cpu_clock = hal::clock::CpuClock::max();
35//! let config = hal::Config::default().with_cpu_clock(cpu_clock);
36//! let p = hal::init(config);
37//!
38//! // Define the LED layout (1D strip of 300 pixels)
39//! layout1d!(Layout, 60 * 5);
40//!
41//! // Setup the WS2812 driver using RMT.
42//! let ws2812_driver = {
43//! // IMPORTANT: Change `p.GPIO16` to the GPIO pin connected to your WS2812 data line.
44//! // For example, if using GPIO2, change to `p.GPIO2`.
45//! // Ensure the chosen pin is not used for other critical functions (e.g., strapping, JTAG).
46//! let data_pin = p.GPIO16;
47//!
48//! // RMT peripheral frequency, typically 80MHz for WS2812 on ESP32.
49//! let rmt_clk_freq = hal::time::Rate::from_mhz(80);
50//!
51//! // Initialize RMT peripheral.
52//! let rmt = hal::rmt::Rmt::new(p.RMT, rmt_clk_freq).unwrap();
53//! let rmt_channel = rmt.channel0;
54//!
55//! // Create RMT buffer
56//! const NUM_LEDS: usize = Layout::PIXEL_COUNT;
57//! const CHANNELS_PER_LED: usize = <Ws2812Led as ClocklessLed>::LED_CHANNELS.channel_count(); // Usually 3 (RGB)
58//! let rmt_buffer = create_rmt_buffer!(NUM_LEDS, CHANNELS_PER_LED);
59//!
60//! Ws2812Rmt::new(rmt_channel, data_pin, rmt_buffer)
61//! };
62//!
63//! // Build the Blinky controller
64//! let mut control = ControlBuilder::new_1d()
65//! .with_layout::<Layout>()
66//! .with_pattern::<Rainbow>(RainbowParams {
67//! ..Default::default()
68//! })
69//! .with_driver(ws2812_driver)
70//! .build();
71//!
72//! control.set_brightness(0.2); // Set initial brightness (0.0 to 1.0)
73//!
74//! loop {
75//! let elapsed_in_ms = elapsed().as_millis();
76//! control.tick(elapsed_in_ms).unwrap();
77//!
78//! // Optional: Add a delay to control the update rate and reduce CPU usage.
79//! // Without an explicit delay, the loop will run as fast as possible.
80//! }
81//! }
82//! ```
83//!
84//! ## Getting started
85//!
86//! For more help to get started, see ["Getting Started"][getting-started] section in [`gledopto`][gledopto] README.
87//!
88//! [gledopto]: https://crates.io/crates/gledopto
89//! [getting-started]: https://github.com/ahdinosaur/blinksy/blob/gledopto/v0.3.1/esp/gledopto/README.md#getting-started
90
91pub mod rmt;
92pub mod time;
93
94use crate::rmt::ClocklessRmtDriver;
95use blinksy::drivers::ws2812::Ws2812Led;
96
97/// WS2812 LED driver using the ESP32 RMT peripheral.
98///
99/// This driver provides efficient, hardware-accelerated control of WS2812 LEDs.
100///
101/// # Type Parameters
102///
103/// * `Tx` - RMT transmit channel type
104/// * `BUFFER_SIZE` - Size of the RMT buffer
105pub type Ws2812Rmt<Tx, const BUFFER_SIZE: usize> = ClocklessRmtDriver<Ws2812Led, Tx, BUFFER_SIZE>;