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).
• Led2d - Core trait that defines the LED panel API surface.
• Led2dGenerated - Sample generated panel type showing the constructor path.
• LedLayout - Compile-time description of panel geometry and wiring, including dimensions (with examples)
• Frame2d - 2D pixel array used for general graphics (includes examples)
• led_strip! - Underlying strip abstraction used by this panel API.

Example: Write Text

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

use device_envoy_esp::{
    Result, init_and_start, led2d,
    led2d::{Led2d as _, Led2dFont, layout::LedLayout},
    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: GPIO18,                       // GPIO pin for LED data signal
        len: 48,                           // Number of LEDs in the panel
        led_layout: LED_LAYOUT_12X4,       // LED layout mapping (defines dimensions)
        font: Led2dFont::Font3x4Trim,      // Font variant
    }
}

async fn example(spawner: embassy_executor::Spawner) -> Result<Infallible> {
    init_and_start!(p, rmt80: rmt80, mode: rmt_mode::Blocking);

    // Create a device abstraction for the LED panel.
    // Behind the scenes, this creates a channel and background task to manage the display.
    let led12x4 = Led12x4::new(p.GPIO18, rmt80.channel0, 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);

    core::future::pending().await
}

Example: Animated Text on a Rotated Panel

This example animates text on a rotated 12x8 panel built from two stacked 12x4 panels.

use device_envoy_esp::{
    Result, init_and_start, led2d,
    led2d::{Frame2d, Led2d as _, Led2dFont, layout::LedLayout},
    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_8X12_ROTATED: LedLayout<96, 8, 12> = LED_LAYOUT_12X8.rotate_cw();

// Generate a type named `Led12x8Animated`.
led2d! {
    Led12x8Animated {
        pin: GPIO18,                           // GPIO pin for LED data signal
        len: 96,                               // Number of LEDs in the panel
        led_layout: LED_LAYOUT_8X12_ROTATED,  // Two 12x4 panels stacked and rotated
        max_current: Current::Milliamps(300), // Power budget, default is 250 mA
        font: Led2dFont::Font4x6Trim,         // 4x6 font without normal padding
        gamma: Gamma::Linear,                 // Color correction curve, default is Gamma::Srgb
        max_frames: 2,                        // Maximum animation frames, default is 16
    }
}

async fn example(spawner: embassy_executor::Spawner) -> Result<Infallible> {
    init_and_start!(p, rmt80: rmt80, mode: rmt_mode::Blocking);

    // Create a device abstraction for the rotated LED panel.
    let led12x8_animated = Led12x8Animated::new(p.GPIO18, rmt80.channel0, spawner)?;

    // Write "Go" into an in-memory frame buffer.
    let mut frame_0 = Frame2d::new();
    // Empty text colors array defaults to white.
    led12x8_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.
    led12x8_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);
    led12x8_animated.animate([(frame_0, frame_duration), (frame_1, frame_duration)]);

    core::future::pending().await
}

Modules

layout

led2d_generated

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

Macros

led2d

Macro to generate an LED-panel struct type (includes syntax details). See Led2d for the shared API.

Structs

Frame2d

2D pixel array used for general graphics on LED panels.

LedLayout

Compile-time description of panel geometry and wiring, including dimensions (with examples).

Point

2D point.

Size

2D size.

Enums

Led2dFont

Fonts available for use with LED panel displays.

Traits

Led2d

Platform-agnostic LED panel device contract.

Functions

bit_matrix3x4_font

Monospace 3x4 font matching the internal BIT_MATRIX3X4 bitmap data.

render_text_to_frame

Render text into a frame using the provided font.