Struct LedMatrix

pub struct LedMatrix<SPI, const BUFFER_LENGTH: usize = 64, const DEVICE_COUNT: usize = 1> { /* private fields */ }

Available on crate feature led-matrix only.

A high-level abstraction for controlling an LED matrix display using the MAX7219 driver.

Implementations

impl<SPI, const BUFFER_LENGTH: usize, const DEVICE_COUNT: usize> LedMatrix<SPI, BUFFER_LENGTH, DEVICE_COUNT>

where SPI: SpiDevice,

pub fn from_spi(spi: SPI) -> Result<Self, Error>

Simplifies initialization by creating a new LedMatrix instance from the given SPI device and number of connected displays.

Internally, this constructs and initializes the Max7219 driver, making setup easier for typical use cases.

Arguments

• spi - The SPI device used for communication.

Returns

Returns a LedMatrix instance on success, or an error if the display count is invalid

Example

let spi = /* your SPI device */;
let mut matrix = SingleMatrix::from_spi(spi, 4).unwrap();

pub fn from_driver(driver: Max7219<SPI>) -> Result<Self, Error>

Creates a new LedMatrix instance from an existing Max7219 driver.

This method is useful if you have already created and configured a Max7219 driver manually. In most cases, it is recommended to use Self::from_spi instead, which creates the driver and matrix together in one step.

Arguments

• driver - An initialized Max7219 driver instance.

Error

Returns Err(Error::InvalidDeviceCount) if the driver’s device count does not match the generic DEVICE_COUNT parameter of this matrix type.

Warning

This method is more error-prone than Self::from_spi because it is easy to configure a driver with one device count (e.g., .with_device_count(4)) and then call from_driver on a LedMatrix type instantiated with a different generic parameter (e.g., LedMatrix<_, 1>). This mismatch will result in an error.

Example

let driver = Max7219::new(spi).with_device_count(1).expect("device count 1 should not panic");
let mut matrix = SingleMatrix::new(driver).unwrap();

pub fn driver(&mut self) -> &mut Max7219<SPI>

Provides mutable access to the underlying MAX7219 driver.

This allows users to call low-level functions directly

pub fn clear(&mut self, device_index: usize) -> Result<(), Error>

Clear a specific device

pub fn clear_all(&mut self) -> Result<(), Error>

Clear all device

pub fn write_buffer( &mut self, device_index: usize, buffer: &MatrixBuffer, ) -> Result<(), Error>

Write a complete buffer to a specific display

pub fn draw_char(&mut self, device_index: usize, ch: char) -> Result<(), Error>

Draws a single 8x8 character on the specified display device.

The character is converted into an 8-byte bitmap using a predefined font. If the character is unsupported, it will be replaced with “?” char.

Each byte in the bitmap corresponds to one row of the 8x8 LED matrix (from D0 to D7), and is written to the digit registers of the specified device_index.

Arguments

• device_index - Index of the target MAX7219 device in the daisy chain.
• c - The character to display.

Errors

Returns an error if the digit conversion fails or if SPI communication fails.

pub fn draw_char_with_font( &mut self, device_index: usize, ch: char, font: &LedFont, ) -> Result<(), Error>

Draws a single 8x8 character on the specified display device using a provided font.

This function is similar to Self::draw_char, but allows overriding the font used for rendering. The character is mapped to an 8-byte bitmap. Each byte represents a row on the matrix, with the most significant bit (bit 7) on the left and the least significant bit (bit 0) on the right.

Arguments

• device_index - Index of the MAX7219 device to write to.
• ch - The character to render on the display.
• font - The font to use for character lookup and rendering.

pub fn draw_text(&mut self, text: &str) -> Result<(), Error>

Draw a string of text on the LED matrix using the default font. Each character is displayed on one device in the daisy chain. If the string is longer than the number of devices, the extra characters are ignored.

pub fn draw_text_with_font( &mut self, text: &str, font: &LedFont, ) -> Result<(), Error>

Draw a string of text on the LED matrix using a specified font. Each character is displayed on one device in the daisy chain. If the string is longer than the number of devices, the extra characters are ignored.

pub fn scroll_text<D: DelayNs>( &mut self, delay: &mut D, text: &str, config: ScrollConfig, ) -> Result<(), Error>

Scroll the given text across the LED matrix.

This will render text using the current font and step through each frame at the delay specified by config.step_delay_ns. If config.loop_text is true, the text will repeat with config.loop_padding pixels of blank space between repetitions.

Parameters

• delay: delay provider implementing embedded_hal::delay::DelayNs.
• text: the string slice to scroll.
• config: scrolling configuration (speed, step size, looping).

Errors

Returns a MatrixError if updating the display buffer fails.

pub fn flush(&mut self) -> Result<(), Error>

Flush the internal display buffer to the actual LED matrix hardware.

This function goes row by row (0 to 7), and for each row, it builds an array of SPI operations (ops) to send to all devices in the daisy-chained display. It packs each row of pixels into a single byte for each device, then sends the data using the driver’s write_all_registers method.

Example logic (DEVICE_COUNT = 2, row = 0):

Assume self.framebuffer contains pixel bits for 2 devices (128 total):

Device 0, row 0 pixels: [1, 0, 1, 0, 1, 0, 1, 0] => 0b10101010 => 0xAA Device 1, row 0 pixels: [1, 1, 1, 1, 0, 0, 0, 0] => 0b11110000 => 0xF0

Since SPI sends left to right, we must reverse the device order in the ops array: ops[0] = (Digit0, 0xF0) // Device 1 ops[1] = (Digit0, 0xAA) // Device 0

These are sent out in one SPI write for Digit0, and similarly repeated for Digit1 through Digit7.

pub fn clear_buffer(&mut self)

Clear the internal framebuffer (sets all pixels to 0).

pub fn clear_screen(&mut self) -> Result<(), Error>

Clear screen by resetting buffer and flushing

Trait Implementations

impl<SPI, const BUFFER_LENGTH: usize, const DEVICE_COUNT: usize> DrawTarget for LedMatrix<SPI, BUFFER_LENGTH, DEVICE_COUNT>

where SPI: SpiDevice,

Available on crate feature graphics only.

type Color = BinaryColor

The pixel color type the targetted display supports.

type Error = Infallible

Error type to return when a drawing operation fails.

fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>

where I: IntoIterator<Item = Pixel<Self::Color>>,

Draw individual pixels to the display without a defined order.

fn fill_contiguous<I>( &mut self, area: &Rectangle, colors: I, ) -> Result<(), Self::Error>

where I: IntoIterator<Item = Self::Color>,

Fill a given area with an iterator providing a contiguous stream of pixel colors.

fn fill_solid( &mut self, area: &Rectangle, color: Self::Color, ) -> Result<(), Self::Error>

Fill a given area with a solid color.

fn clear(&mut self, color: Self::Color) -> Result<(), Self::Error>

Fill the entire display with a solid color.

impl<SPI, const BUFFER_LENGTH: usize, const DEVICE_COUNT: usize> OriginDimensions for LedMatrix<SPI, BUFFER_LENGTH, DEVICE_COUNT>

Available on crate feature graphics only.

fn size(&self) -> Size

Returns the size of the bounding box.