Module led2d 

A device abstraction for rectangular NeoPixel-style (WS2812) LED panel displays. For 1-dimensional LED strips, see the led_strip module.

This page provides the primary documentation and examples for programming LED panels. The device abstraction supports text, graphics, and animation.

After reading the examples below, see also:

• led2d! — Macro to generate an LED-panel struct type (includes syntax details). See Led2dGenerated for a sample of a generated type.
• Led2dGenerated — Sample struct type generated by the led2d! macro, showing all methods and constants.
• LedLayout — Compile-type description of panel geometry and wiring, including dimensions (with examples)
• Frame2d — 2D pixel array used for general graphics (includes examples)
• led_strips! — Alternative macro to share a PIO resource with other panels or LED strips (includes examples)

Example: Write Text

In this example, we render text on a 12×4 panel. Here, the generated struct type is named Led12x4.

use device_envoy::{Result, led2d, led2d::layout::LedLayout, led2d::Led2dFont, led_strip::colors};

// Tells us how the LED strip is wired up in the panel
// in this case, a common snake-like pattern.
const LED_LAYOUT_12X4: LedLayout<48, 12, 4> = LedLayout::serpentine_column_major();

// Generate a type named `Led12x4`.
led2d! {
    Led12x4 {
        pin: PIN_3,                          // GPIO pin for LED data signal
        led_layout: LED_LAYOUT_12X4,         // LED layout mapping (defines dimensions)
        font: Led2dFont::Font3x4Trim,        // Font variant
    }
}

async fn example(spawner: Spawner) -> Result<Infallible> {
    let p = init(Default::default());

    // Create a device abstraction for the LED panel.
    // Behind the scenes, this creates a channel & background task to manage the display.
    let led12x4 = Led12x4::new(p.PIN_3, p.PIO0, p.DMA_CH0, spawner)?;

    // Write text to the display with per-character colors.
    let colors = [colors::CYAN, colors::RED, colors::YELLOW];
    // Each character takes the next color; when we run out, we start over.
    led12x4.write_text("Rust", &colors).await?;

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

Example: Animated Text on a Rotated Panel

This example animates text on a rotated 12×8 panel built from two stacked 12×4 panels.

use device_envoy::{Result, led2d, led2d::layout::LedLayout, led2d::Frame2d, led2d::Led2dFont, led_strip::{Current, Gamma, colors}};
use embassy_time::Duration;

// Our panel is two 12x4 panels stacked vertically and then rotated clockwise.
const LED_LAYOUT_12X4: LedLayout<48, 12, 4> = LedLayout::serpentine_column_major();
const LED_LAYOUT_12X8: LedLayout<96, 12, 8> = LED_LAYOUT_12X4.combine_v(LED_LAYOUT_12X4);
const LED_LAYOUT_12X8_ROTATED: LedLayout<96, 8, 12> = LED_LAYOUT_12X8.rotate_cw();

// Generate a type named `Led12x8Animated`.
led2d! {
    pub(self) Led12x8Animated {               // Can provide a visibility modifier
        pin: PIN_4,                           // GPIO pin for LED data signal
        led_layout: LED_LAYOUT_12X8_ROTATED,  // Two 12×4 panels stacked and rotated
        font: Led2dFont::Font4x6Trim,         // Use a 4x6 pixel font without the usual 1 pixel padding
        pio: PIO1,                            // PIO resource, default is PIO0
        dma: DMA_CH1,                         // DMA resource, default is DMA_CH0
        max_current: Current::Milliamps(300), // Power budget, default is 250 mA.
        gamma: Gamma::Linear,                 // Color correction curve, default is Gamma::Srgb
        max_frames: 2,                        // maximum animation frames, default is 16
    }
}

async fn example(spawner: Spawner) -> Result<Infallible> {
    let p = init(Default::default());

   // Create a device abstraction for the rotated LED panel.
    let led_12x8_animated = Led12x8Animated::new(p.PIN_4, p.PIO1, p.DMA_CH1, spawner)?;

    // Write "Go" into an in-memory frame buffer.
    let mut frame_0 = Frame2d::new();
    // Empty text colors array defaults to white.
    led_12x8_animated.write_text_to_frame("Go", &[], &mut frame_0)?;

    // Write "Go" into a second frame buffer with custom colors and on the 2nd line.
    let mut frame_1 = Frame2d::new();
    // "/n" starts a new line. Text does not wrap but rather clips.
    led_12x8_animated.write_text_to_frame(
        "\nGo",
        &[colors::HOT_PINK, colors::LIME],
        &mut frame_1,
    )?;

    // Animate between the two frames indefinitely.
    let frame_duration = Duration::from_secs(1);
    led_12x8_animated
        .animate([(frame_0, frame_duration), (frame_1, frame_duration)])?;

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

Re-exports

pub use layout::LedLayout;

Modules

layout

Module containing LedLayout, the struct for compile-time description of panel geometry and wiring.

led2d_generated

Module containing Led2dGenerated, the sample struct type generated by the led2d! macro.

Macros

led2dNon-host

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

Structs

Frame2d

2D pixel array used for general graphics on LED panels (includes examples).

Point

Re-exported from the embedded-graphics crate.

Size

Re-exported from the embedded-graphics crate.

Enums

Led2dFont

Fonts available for use with led2d module panels.