Documentation
Every page here is a repository's own, rendered as one site. Start with the tutorial; reach for the reference when you know the shape.
Start here
- OverviewA small declarative UI framework for e-ink firmware: you describe what a screen looks like and how it changes, and xpui measures, routes input and paints.
- OrientationRead this before exploring any of the ten repositories.
- Your first screenFrom an empty file to a screen running in a window.
- A second screentutorial.md took you from an empty file to one working screen.
The framework
- ReferenceThe whole of the public API, by area.
- How a frame runsThree conversations, each one way; then what actually happens between them, in order; then what the crate holds.
- The host contractxpui draws nothing by itself.
- Writing a backendYou have hardware nobody here supports and you want a screen on it.
- Writing a widgetA widget is any type that implements View.
- Testing a screen without a screenFour layers.
The components
- OverviewThe eight themed components xpui asks a backend to paint — a list, a dialog, a slider, a progress bar, a header, a sub-header, a button-hint bar and a scroll indicator — painted from drawing primitives alone.
- The components, and what they paint fromxpui deliberately has no opinion about what a list row looks like.
The boards
- OverviewSeven devices — six e-ink panels and one LCD — as data: panel size, orientation, key row, refresh time, and the body in tenths of a millimetre.
- The seven boardsWhat each vendor crate describes, which of the seven have been run, and how a screen reaches each panel.
- Adding a boardYou have a device nobody here describes, and you want your screens laid out for it.
- xpui-boards-coreThe vocabulary a device is described in.
- xpui-boards-pimoroniPimoroni's RP2040 boards, described for xpui.
- xpui-boards-seeedSeeed's Sticky, described for xpui.
- xpui-boards-xteinkXteink's e-readers, described for xpui.
The backends
embedded-graphics
- xpui-embedded-graphicsAn xpui backend that draws through any embedded-graphics DrawTarget — which is most of the embedded Rust display ecosystem: e-paper panels, SSD1306 and friends, colour TFTs, and the desktop simulator.
- Hardware notesWhat running the embedded-graphics backend on real panels established, kept here so the code can state the conclusion in a sentence.
- Screenshot testsWhat this backend can prove about pixels, on a laptop, with no panel.
FreeInkUI
- xpui-fuiAn xpui backend that draws through FreeInkUI.
- The FreeInkUI shimxpuifui.cpp implements the C ABI in xpuifui.h against the FreeInk SDK's UI library.
- Adding the shimcpp/xpuifui.cpp implements the C ABI in cpp/xpuifui.h against the FreeInk SDK's UI library.
- FreeInkUI coveragexpui asks a backend for eight pieces of themed furniture.
Proving a backend
The simulator
The gallery
- OverviewTen captures on seven boards, and the suite that proves the framework paints the same thing on all of them.
- The seven-board conformance suite--board changes the panel size, the chrome sized for it, and the window scale — and nothing else.
- The screensExample screens built on xpui, in a window, and the library both firmwares flash.
- The tutorial crateThe screen the framework's tutorial builds, finished and running.
On hardware
- The RP2040 firmwareTwo firmware binaries that flash the gallery to a Pimoroni board: the same screens the simulator runs, the same crate, and no device-specific code in them at all.
- Your first screen on a boardYou have a Badger 2040 — 296×128 of monochrome e-ink, five buttons, 2 MB of flash, no touchscreen.
- Working on the RP2040Everything past a first flash: what the keys do, why this crate is its own workspace, where the memory goes, which pin is which, what the release profile keeps, why one loop serves both boards, and what running it proved.
- The ESP32 firmwareThe gallery as ESP32 firmware: two boards on two architectures, running the same screens the desktop simulator opens and the RP2040 binaries flash.
- Your first screen on an ESP32You have an Xteink X3 — 528×792 of e-ink at 257 ppi, four keys along the bottom and a page key on each edge, an ESP32-C3, no touchscreen.
- ESP32 hardware notesTwo boards on two architectures, and what is known about running the gallery on them.
In C++
- OverviewThe C++ side of the boundary: an application that already owns its screen stack, hosting xpui screens over a C ABI.
- Rust screens in a C++ firmwareYou have a C++ firmware.
- The boundaryThe C ABI between a C++ application and its Rust screens: which symbols cross, in which direction, who defines each, what the desktop host was modelled on, and what proves the two sides agree.
- xpui-cpp-abiThe two ABI boundaries this repository owns, checked on every run.
- xpui-cpp-hostThe worked example of a C++ application hosting xpui screens: a desktop window over SDL2, a screen stack the C++ owns, and three Rust screens on it.
- The PlatformIO firmwarecpphost proves the C ABI on a desktop, with CMake.