Mousefood - embedded-graphics backend for Ratatui!

Important

Currently works only with std-enabled targets, such as Espressif's ESP32 MCU series. Support for "bare-metal" (no_std) targets is planned, but it requires upstream changes - ratatui #1750.

Quickstart

Add mousefood as a dependency:

cargo add mousefood

Exemplary setup:

use mousefood::prelude::*;

fn main() -> Result<(), std::io::Error> {
    // Any embedded_graphics DrawTarget
    let mut display = MyDrawTarget::new();
    
    let backend = EmbeddedBackend::new(&mut display, EmbeddedBackendConfig::default());
    let mut terminal = Terminal::new(backend)?;

    loop {
        terminal.draw(...)?;
    }
}

Special characters

Embedded-graphics includes bitmap fonts that have a very limited set of characters to save space (ASCII, ISO 8859 or JIS X0201). This makes it impossible to draw most of Ratatui's widgets, which heavily use box-drawing glyphs, Braille, and other special characters.

Mousefood by default uses embedded-graphics-unicodefonts, which provides embedded-graphics fonts with a much larger set of characters.

Alternatives

In order to save space and speed up rendering, the fonts feature can be disabled by turning off the default crate features. ibm437 is a good alternative that includes some drawing characters, but is not as large as embedded-graphics-unicodefonts.

Simulator

Mousefood can be run in a simulator (requires SDL2 to be installed). The simulator mode can be enabled using the simulator feature and utilizes the embedded-graphics-simulator crate.

Run simulator example:

git clone https://github.com/j-g00da/mousefood.git
cd mousefood
cargo run --example=simulator --features=simulator

Exemplary setup using simulator:

use mousefood::prelude::*;
use mousefood::embedded_graphics::geometry;
use mousefood::simulator::SimulatorDisplay;

fn main() -> Result<(), std::io::Error> {
    let mut display = SimulatorDisplay::<Bgr565>::new(geometry::Size::new(128, 64));
    let backend: EmbeddedBackend<SimulatorDisplay<_>, _>
        = EmbeddedBackend::new(&mut display);
    let mut terminal = Terminal::new(backend)?;

    loop {
        terminal.draw(...)?;
    }
}

EPD support

Support for EPD (e-ink displays) produced by WeAct Studio (weact-studio-epd driver) can be enabled using epd-weact feature. This driver requires some additional configuration:

use mousefood::prelude::*;
use weact_studio_epd::graphics::Display290BlackWhite;
use weact_studio_epd::WeActStudio290BlackWhiteDriver;

// Configure SPI
// (...)

let mut driver = WeActStudio290BlackWhiteDriver::new(spi_interface, busy, rst, delay);
let mut display = Display290BlackWhite::new();

driver.init().unwrap();

let config = EmbeddedBackendConfig {
    flush_callback: Box::new(move |d| { driver.full_update(d).unwrap(); }),
    ..Default::default()
};
let backend = EmbeddedBackend::new(&mut display, config);

Support for epd_waveshare driver is planned in the future.

Performance and hardware support

Flash memory on most embedded devices is very limited. Additionally, to achieve high frame rate when using the fonts feature, it is recommended to use opt-level = 3, which can make the resulting binary even larger.

Mousefood is hardware-agnostic, but requires a std-enabled target. Successfully tested on:

• esp32 (base model, 4MB flash)
• esp32c6 (16MB flash)

Docs

Full API docs are available on docs.rs.

License

Mousefood is dual-licensed under Apache 2.0 and MIT terms.