# Mousefood for Ratatui: A no-std embedded display backend

> Mousefood connects Ratatui widgets with embedded-graphics displays in no-std Rust firmware. It suits developers targeting small OLED, LCD, and selected e-paper panels, but hardware drivers and feature configuration remain the application's responsibility.

**ratatui/mousefood** — Build embedded applications with Ratatui! 🧀

- Repository: https://github.com/ratatui/mousefood
- Website: https://ratatui.rs/ecosystem/mousefood/
- Stars: 1,344 · Forks: 43
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ratatui-mousefood

## Why Mousefood exists for embedded Rust interfaces

Mousefood addresses the gap between Ratatui's terminal-style interface and displays used in embedded systems. Ratatui supplies widgets, layout, text, borders, and cursor behavior. embedded-graphics supplies a drawing model for small panels. Mousefood provides the backend between them, allowing firmware to render Ratatui content through embedded-graphics without depending on a conventional terminal or requiring `std`.

The project is intended for Rust developers building firmware for constrained devices. Its examples cover ESP32 boards, STM32 hardware, RP2040, Waveshare e-paper, LilyGO e-paper, and WeAct Studio EPD devices. This makes Mousefood more relevant to hardware-oriented applications than to programs that only need a terminal interface on a desktop.

Mousefood is not a universal display driver. The README uses `MockDisplay` in the quickstart and comments that a real driver such as ILI9341, ST7735, or SSD1306 can replace it. The application still has to configure the display controller, communication bus, pins, and driver-specific operations. The repository examples provide concrete references for several targets, but Mousefood should be evaluated as a rendering bridge rather than a complete hardware setup package.

## How EmbeddedBackend connects Ratatui to embedded-graphics

The main integration point is `EmbeddedBackend`. The quickstart creates a mutable display, constructs the backend with `EmbeddedBackend::new`, and passes that backend to Ratatui's `Terminal`. Ratatui performs its widget and layout work, while Mousefood translates the resulting drawing operations into embedded-graphics calls on the supplied display.

The mutable reference matters because rendering writes into the display target through the backend's draw interface. In the quickstart, the color type is selected through `MockDisplay<Rgb888>`. A hardware integration can select the pixel color type required by its display driver, but the README does not claim that every embedded display accepts `Rgb888`.

`EmbeddedBackendConfig` controls presentation and optional behavior. `ColorTheme` maps Ratatui colors to concrete pixel values. The default theme is the ANSI palette, while `ColorTheme::ansi()` and `ColorTheme::tokyo_night()` are documented as built-in themes. A custom theme can override individual fields while inheriting the remaining ANSI values with `ColorTheme::ansi()`.

Font configuration is also held by `EmbeddedBackendConfig`. By default, Mousefood uses `embedded-graphics-unicodefonts`, which provides a larger character set than the small bitmap fonts commonly bundled with embedded-graphics. That larger coverage matters because Ratatui widgets commonly use box-drawing glyphs, Braille patterns, and other characters that limited ASCII, ISO 8859, or JIS X0201 fonts may not contain.

## Font coverage, visual weights, and the default feature trade-off

The default font choice favors compatibility with Ratatui's text and widget set. Disabling default crate features removes the `fonts` feature, which can reduce storage use and rendering overhead according to the README. The trade-off is character coverage. The README names `ibm437` as an alternative because it includes some drawing characters, but it is not as large as `embedded-graphics-unicodefonts`.

This is a meaningful design decision for firmware. A display application may work with ordinary text under one font and fail when a widget introduces a border or block character that the selected font cannot encode. Disabling `fonts` therefore requires checking the actual widgets and characters used by the application, not only measuring the crate's binary footprint.

Bold and italic text modifiers are supported, but the required font data must be supplied through `EmbeddedBackendConfig`. The regular font is the fallback when the other styles are absent. All supplied fonts must have the same size, so callers cannot mix an arbitrary bold font into a regular font configuration without respecting that constraint.

The configuration pattern below shows the documented selection of `MONO_6X13`, `MONO_6X13_BOLD`, and `MONO_6X13_ITALIC`. The display remains `MockDisplay<Rgb888>` because the example is not tied to a particular controller.

## Installing Mousefood and rendering a first Ratatui frame

The README's first step is to add the crate with Cargo. This adds `mousefood` to the current Rust project's dependencies.

```bash
cargo add mousefood
```

A minimal host-side or desktop-side check can use the README's `MockDisplay` setup. The program creates the backend, creates a Ratatui `Terminal`, and draws a bordered paragraph into the frame.

```rust
use mousefood::embedded_graphics::{mock_display::MockDisplay, pixelcolor::Rgb888};
use mousefood::prelude::*;
use ratatui::widgets::{Block, Paragraph};
use ratatui::{Frame, Terminal};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut display = MockDisplay::<Rgb888>::new();
    let backend = EmbeddedBackend::new(&mut display, EmbeddedBackendConfig::default());
    let mut terminal = Terminal::new(backend)?;
    terminal.draw(draw)?;
    Ok(())
}
```

The `draw` callback renders the title and message. The example is suitable as an integration shape, not as a finished firmware target, because `MockDisplay` stores output in memory rather than driving a panel.

```rust
fn draw(frame: &mut Frame) {
    let block = Block::bordered().title("Mousefood");
    let paragraph = Paragraph::new("Hello from Mousefood!").block(block);
    frame.render_widget(paragraph, frame.area());
}
```

The repository also documents a graphical simulator using `embedded-graphics-simulator`. Clone the repository, enter the example directory, and run it with Cargo.

```bash
git clone https://github.com/ratatui/mousefood.git
cd mousefood/examples/simulator
cargo run
```

This should open the simulator example described by the README. It is the documented route for inspecting Mousefood output without connecting the named hardware examples.

## Color themes, cursor styles, and optional blink processing

Mousefood separates basic cursor rendering from optional blinking. `CursorStyle` can be `Inverse`, `Underline`, `Outline`, or `Japanese`. Inverse is the default, but it requires the `framebuffer` feature and falls back to underline without that feature. Cursor blinking and Ratatui text blink modifiers require the `blink` feature. When `blink` is absent, blink modifiers are ignored and the cursor remains visible.

Blink is optional because it adds computation and memory use. Enabling it requires a Cargo feature declaration:

```toml
[dependencies]
mousefood = { version = "*", features = ["blink"] }
```

The documented timing configuration uses `fps`, `BlinkTiming`, `blinks_per_sec`, and `duty_percent`. The example assigns `30` to `fps`, one blink per second with a 15 percent duty cycle for slow blinking, and three blinks per second with a 50 percent duty cycle for fast blinking.

```rust,ignore
let config = EmbeddedBackendConfig {
    #[cfg(feature = "blink")]
    blink: BlinkConfig {
        fps: 30,
        slow: BlinkTiming { blinks_per_sec: 1, duty_percent: 15 },
        fast: BlinkTiming { blinks_per_sec: 3, duty_percent: 50 },
    },
    ..Default::default()
};
```

Color mapping is also explicit. The documented custom theme replaces the background, foreground, and yellow values while inheriting the rest of the ANSI palette. This is useful when panel color interpretation or firmware display calibration differs from terminal colors, although the README does not describe automatic panel calibration.

## E-paper support depends on driver-specific flushing

Mousefood's e-paper support is feature-gated and driver-specific. The README documents an `epd-weact` feature for displays produced by WeAct Studio through the `weact-studio-epd` driver. It says that this driver requires extra configuration and directs developers to that crate's documentation, including the same `flush_callback` pattern used by the example.

The repository layout includes several e-paper examples, including Waveshare, LilyGO, RP2040, and WeAct Studio targets. These examples are stronger evidence of intended hardware paths than a general promise that Mousefood supports every e-paper controller. E-paper also changes the update model compared with ordinary framebuffer displays. A caller cannot assume that every Ratatui terminal draw becomes an immediate physical panel update.

The `epd-weact` dependency in the workspace enables the `blocking` feature, and `epd-waveshare` appears as a separate workspace dependency. Those names identify the driver paths represented in the repository. They do not establish that feature selection alone configures pins, power states, controller timing, or partial refresh behavior.

For an e-paper product, the first integration checkpoint should therefore be the repository example matching the actual panel. Verify the driver, feature set, callback arrangement, and display color model there before writing new Ratatui layout code. The visible TUI can be developed with the simulator or `MockDisplay`, but that will not establish whether a real e-paper panel refreshes correctly.

## Limitations, alternatives, releases, and licensing

The clearest limitation is that Mousefood does not remove the hardware-integration work. It needs an embedded-graphics-compatible display or driver, a compatible pixel color representation, suitable fonts, and enough resources for the chosen configuration. Large font tables, `framebuffer`, and `blink` all have explicit storage or processing consequences. Unsupported glyphs can also become visible when a familiar Ratatui widget introduces a special character.

Mousefood is the wrong choice for a normal terminal application because Ratatui already has terminal-oriented backends and the project is designed around embedded-graphics. It is also a poor fit when the display can only be driven through a driver that Mousefood does not support. The documentation does not present a compatibility guarantee for arbitrary SPI, I2C, or parallel controllers.

A real alternative is using an embedded-graphics backend directly and drawing each element with embedded-graphics primitives and fonts. That approach avoids the Ratatui backend layer but gives up Ratatui's widget and layout model, so the application must implement more interface structure itself. Keeping Ratatui with a platform-native terminal backend is the practical alternative for desktops. Mousefood is most distinct when a shared Ratatui interface must also run on a small non-terminal display.

Mousefood is not archived, and its last push was on 2026-10-13. The listed releases include `mousefood-v0.5.2` on 2026-06-22, `mousefood-v0.5.1` on 2026-06-21, and `mousefood-v0.5.0` on 2026-03-21. The repository contains `BREAKING-CHANGES.md` and `CHANGELOG.md`, which are the first files to inspect when upgrading from an earlier version. Recent releases reduce the visible gap in release history, but the repository does not provide a blanket promise of API stability.

The workspace and crate metadata identify the license as `MIT OR Apache-2.0`, and the repository includes both `LICENSE-APACHE` and `LICENSE-MIT`. Developers must evaluate those files and their dependency licenses for the intended distribution. This is a project-specific licensing inventory, not legal advice.

## Conclusion

Adopt Mousefood when a Rust firmware project already uses Ratatui and has an embedded-graphics-compatible display. Do not choose it for a normal desktop terminal or when the target lacks a suitable driver or documented hardware configuration. Verify the display color type, font availability, required features, flush behavior, and memory budget before integration.

## FAQ

### What is Mousefood in Ratatui?

Mousefood is a no-std embedded-graphics backend for Ratatui. It translates Ratatui rendering into embedded-graphics drawing operations for small displays.

### How do I add Mousefood to a Rust project?

The README documents `cargo add mousefood`. A first integration creates an `EmbeddedBackend` around a display and passes it to Ratatui's `Terminal`.

### Does Mousefood support fonts, cursors, blinking, and e-paper?

Mousefood supports configurable fonts, four cursor styles, optional blink timing, and feature-gated support for WeAct Studio EPD displays. Some behavior depends on Cargo features, while e-paper also requires the applicable display driver and its configuration.

## Sources

- [License: Apache-2.0](https://github.com/ratatui/mousefood/blob/main/LICENSE)
- [Project website](https://ratatui.rs/ecosystem/mousefood/)
- [ratatui/mousefood on GitHub](https://github.com/ratatui/mousefood)
- [README](https://github.com/ratatui/mousefood/blob/main/README.md)
- [Releases](https://github.com/ratatui/mousefood/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ratatui-mousefood