Module led_strip 

A device abstraction for 1-dimensional NeoPixel-style (WS2812) LED strips. For 2-dimensional panels, see the led2d module.

This page provides the primary documentation and examples for programming LED strips. The device abstraction supports pixel patterns and animation on the LED strip.

After reading the examples below, see also:

• led_strip! — Macro to generate an LED strip struct type (includes syntax details). See LedStripGenerated for a sample of a generated type.
• LedStripGenerated — Sample struct type showing all methods and associated constants.
• Frame1d — 1D pixel array used to describe LED strip patterns.
• led_strips! — Alternative macro to share a PIO resource with other strips or panels (includes examples).

Example: Write a Single 1-Dimensional Frame

In this example, we set every other LED to blue and gray. Here, the generated struct type is named LedStripSimple.

use device_envoy::{Result, led_strip::{Frame1d, colors}};
use device_envoy::led_strip;

// Define LedStripSimple, a struct type for an 8-LED strip on PIN_0.
led_strip! {
    LedStripSimple {
        pin: PIN_0,  // GPIO pin for LED data
        len: 8,      // 8 LEDs
        // other inputs set to their defaults
    }
}

async fn example(spawner: embassy_executor::Spawner) -> Result<Infallible> {
    let p = embassy_rp::init(Default::default());
    // Create a LedStripSimple instance.
    let led_strip_simple = LedStripSimple::new(p.PIN_0, p.PIO0, p.DMA_CH0, spawner)?;

    // Create and write a frame with alternating blue and gray pixels.
    let mut frame = Frame1d::new();
    for pixel_index in 0..LedStripSimple::LEN {
        // Directly index into the frame buffer.
        frame[pixel_index] = [colors::BLUE, colors::GRAY][pixel_index % 2];
    }

    // Display the frame on the LED strip (until replaced).
    led_strip_simple.write_frame(frame)?;

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

Example: Animate a Sequence

This example animates a 96-LED strip through red, green, and blue frames, cycling continuously. Here, the generated struct type is named LedStripAnimated.

use device_envoy::{Result, led_strip::{Current, Frame1d, Gamma, colors}};
use device_envoy::led_strip;

// Define LedStripAnimated, a struct type for a 96-LED strip on PIN_4.
// We change some defaults including setting a 1A power budget and disabling gamma correction.
led_strip! {
    pub(self) LedStripAnimated {               // Can provide a visibility modifier
        pin: PIN_4,                            // GPIO pin for LED data
        len: 96,                               // 96 LEDs
        pio: PIO1,                             // Use PIO resource 1
        dma: DMA_CH3,                          // Use DMA channel 3
        max_current: Current::Milliamps(1000), // 1A power budget
        gamma: Gamma::Linear,                  // No color correction
        max_frames: 3,                         // Up to 3 animation frames
    }
}

async fn example(spawner: embassy_executor::Spawner) -> Result<Infallible> {
    let p = embassy_rp::init(Default::default());
    let led_strip_animated = LedStripAnimated::new(p.PIN_4, p.PIO1, p.DMA_CH3, spawner)?;

    // Create a sequence of frames and durations and then animate them (looping, until replaced).
    let frame_duration = embassy_time::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
}

Modules

colors

Module containing predefined RGB8 color constants, re-exported from the smart_leds crate.

led_strip_generated

Module containing LedStripGenerated, the sample struct type generated by the led_strip! macro.

Macros

led_stripNon-host

Macro to generate an LED-strip struct type (includes syntax details). See LedStripGenerated for a sample of a generated type.

led_stripsNon-host

Macro to generate multiple LED strip and panel struct types that share a single PIO resource (includes syntax details).

Structs

Frame1d

1D pixel array used to describe LED strip patterns.

Rgb888

8-bit-per-channel RGB color re-exported from the embedded-graphics crate.

Enums

Current

Electrical current budget configuration for LED strips.

Gamma

Gamma correction configuration for LED strips.

Traits

ToRgb8

Convert colors to RGB8 for LED strip rendering.

ToRgb888

Convert colors to Rgb888 for embedded-graphics rendering.

Type Aliases

RGB8

8-bit-per-channel RGB color re-exported from the smart_leds crate.