xpui-simulator

Runs an xpui app in a desktop window, so screens can be developed without hardware. Not a separate rendering backend: it is xpui-embedded-graphics over embedded-graphics-simulator's display, plus a window, an event pump and a keyboard mapping. The pixels are the ones a device would get — same backend, same components, same measurements.

Using it

[dependencies]
xpui-simulator = { git = "https://github.com/XPUI-Framework/xpui-simulator", branch = "main" }

use xpui_simulator::{Board, Panel, Simulator};

fn main() {
    // Your panel. `xpui-boards-pimoroni`, `-xteink` and `-seeed` carry
    // ready-made ones.
    let mine = Board::custom("my reader", 480, 800, false);
    Simulator::new(Panel::of(mine))
        .title("my reader")
        .run(MainMenu::new());
}

cargo run -p xpui-gallery — the seven-board gallery this window was built around — lives in xpui-gallery, not here; this crate knows no device and no screen, and opens whatever board and screen it is handed. Nothing is on crates.io yet, which is why the dependency is a git URL.

Requirements

SDL2, which embedded-graphics-simulator needs.

brew install sdl2           # macOS
apt install libsdl2-dev     # Debian/Ubuntu

Checking it

./build-and-test.sh

The checks are in xtask/ — this repository's own list, in Rust, holding nothing it does not run. There is no bare-metal lint here and there is no C++ stage: this crate opens a window, and runs on a desktop and nowhere else. ./build-and-test.sh fix formats in place first. How a change is reviewed is in docs/contributing.md.

Where next

docs/running.md	the operator's guide, in the sections below
Running the gallery	cargo run -p xpui-gallery -- --board x3, and the seven slugs it takes
Boards	Panel::of(board), and Simulator::boards(&[..]) for the cycle B walks
Keys and mouse	what every key sends, and how a click becomes a tap
Changing it while it runs	board, zoom, body, screenshot — without restarting
The device around the panel	the bezel drawn from millimetres, with clickable keys
--frames N	why the loop is testable, and how CI runs it
The mouse as a finger	a drag is a swipe, the wheel is a scroll, and where the edge gestures live
Headless	screenshots with no window, and no window at all
When it does not run	the failures people actually hit
docs/design.md	why the window redraws when nothing changed, and the other arguments behind choices the code states in one sentence
docs/contributing.md	SDL2 first, then building it, the gate, the five review steps, and how a commit is written

Where it sits

Every arrow is a dependency in a Cargo.toml, and they all point inward toward xpui, which depends on nothing at all. That is the rule the organisation is arranged around: a backend can be written without the framework knowing it exists, and a firmware reaches whatever it needs directly rather than through whoever happens to sit above it.