mipidsi

The mipidsi crate provides a generic display driver for TFT displays that implement the MIPI Display Command Set.

Core Components

• Display driver: Contains the primary functionality for interacting with the display.
• interface::Interface: An abstraction used to communicate with hardware via transports. Currently, it supports SPI and Parallel GPIO.
• Model trait: Each specific display model (e.g., ST7789, ILI9341) implements this trait for every color format it supports.
• Builder: A struct used to configure and instantiate specific display models, including handling different screen sizes and window addressing offsets.
• embedded-graphics-core: The crate uses this as the underlying drawing API.

Note: Despite the name, this crate does not support the MIPI Display Serial Interface (DSI) protocol; it supports displays using the MIPI Display Command Set.

In version 0.8, mipidsi updated its dependency on embedded-hal to 1.0 and changed how displays are constructed.

Use generic Builder::new instead of model-specific constructors

Model-specific constructors like Builder::ili9341_rgb565 were removed. Use Builder::new with a model instance instead.

// 0.7
use mipidsi::Builder;
let display = Builder::ili9341_rgb565(di)
  .init(&mut delay, None)?;

// 0.8
use mipidsi::{Builder, models::ILI9341Rgb565};
let display = Builder::new(ILI9341Rgb565, di)
  .init(&mut delay)?;

Use .reset_pin() instead of passing to .init()

The reset pin parameter was removed from Builder::init. Use the .reset_pin() setter on the builder instead.

// 0.7
let display = Builder::new(ili9341_rgb565, di)
  .init(&mut delay, Some(rst))?;

// 0.8
use mipidsi::{Builder, models::ILI9341Rgb565};
let display = Builder::new(ILI9341Rgb565, di)
  .reset_pin(rst)
  .init(&mut delay)?;

Builder method renaming

Methods previously prefixed with with_ (e.g., with_invert_colors) have been renamed to remove the prefix to comply with Rust API guidelines.

// 0.7
let display = Builder::new(ili9341_rgb565, di)
  .with_invert_colors(ColorInversion::Normal)
  .with_orientation(Orienation::default())
  .init(&mut delay, Some(rst))?;

// 0.8
use mipidsi::{Builder, models::ILI9341Rgb565};
let display = Builder::new(ILI9341Rgb565, di)
  .invert_colors(ColorInversion::Normal)
  .orientation(Orienation::default())
  .reset_pin(rst)
  .init(&mut delay)?;

Color Defaults

In 0.8, all models use consistent default values: no color inversion and RGB subpixel order. If your display shows incorrect colors, check the troubleshooting guide.

To cross-compile the example for a Raspberry Pi Zero W from a Mac OS host, you need musl-cross installed (available via Homebrew: brew install FiloSottile/musl-cross/musl-cross --without-x86_64 --with-arm_hf).

Follow these steps to build, strip the binary to reduce size, copy it to the Pi via SSH, and run it.

# build for rpi zero w
cargo build --release --target=arm-unknown-linux-musleabihf

# look at the size of the bin file
ls -lh target/arm-unknown-linux-musleabihf/release/spi-st7789-rpi-zero-w

# strip it
arm-linux-musleabihf-strip target/arm-unknown-linux-musleabihf/release/spi-st7789-rpi-zero-w

# look at it now ;)
ls -lh target/arm-unknown-linux-musleabihf/release/spi-st7789-rpi-zero-w

# copy over ssh
scp target/arm-unknown-linux-musleabihf/release/spi-st7789-rpi-zero-w pi@raspberrypi.local:~/

# ssh into the rpi to run it
ssh pi@raspberrypi.local

# run it
./spi-st7789-rpi-zero-w

To use a display, you must first create an Interface (such as SpiInterface) and then use the Builder to configure the specific model, pins, and initialization sequence.

Common steps include:

1. Creating an interface from a hardware peripheral (like SpiDevice), a Data/Command (DC) pin, and a buffer.
2. Using Builder::new(MODEL, interface) to start configuration.
3. Configuring optional pins like .reset_pin(rst).
4. Calling .init(&mut delay) to perform the hardware initialization sequence.

Once initialized, you can use methods like .clear(color) to manipulate the display.

// create a SpiInterface from SpiDevice, a DC pin and a buffer
let mut buffer = [0u8; 512];
let di = SpiInterface::new(spi, dc, &mut buffer);

// create the ILI9486 display driver in rgb666 color mode from the display interface and use a HW reset pin during init
let mut display = Builder::new(ILI9486Rgb666, di)
    .reset_pin(rst)
    .init(&mut delay)?;

// clear the display to black
display.clear(Rgb666::BLACK)?;

The Model trait defines the hardware capabilities and command sequences for specific display controllers (e.g., st7789, ili9341). When working with mipidsi, you interact with these models to initialize hardware, manage power states, and control display features like scrolling or tearing effects.

Key responsibilities of a Model implementation include:

• Initialization: Using init to set up the display and return the initial SetAddressMode.
• Power Management: Using sleep and wake to manage the display's power state (note that wake must be called before issuing other commands).
• Memory Access: Using write_memory_start before writing pixel data.
• Display Control: Managing address windows, vertical scrolling regions, and tearing effects.

/// Example of the Model trait requirements (conceptual)
impl Model for MyCustomModel {
    type ColorFormat = Rgb565;
    const FRAMEBUFFER_SIZE: (u16, u16) = (240, 320);

    fn init<DELAY, DI>(&mut self, di: &mut DI, delay: &mut DELAY, options: &ModelOptions) -> Result<SetAddressMode, ModelInitError<DI::Error>> 
    where DELAY: DelayNs, DI: Interface {
        // implementation
    }
    // ... other required methods
}