MarigoldOS

MarigoldOS is a lightweight, open-source firmware for the Xteink X4 and X3 e-readers.

If you'd like to explore the OS without flashing a device, try the emulator in your browser — the firmware's app and rendering code compiled to WebAssembly, with a simulated e-ink display and a selection of public-domain books.

Features

Reading

• EPUB 2 & 3 — native table of contents for each (EPUB 3 nav, NCX fallback)
• Reader typefaces — Literata and Merriweather, plus an optional custom typeface slot from the SD card
• Whole-book pagination cache — a book parses once and reopens in tens of milliseconds
• Fast page turns — 473 ms end-to-end, within ~50 ms of the panel's rated floor

Library & sync

• Streamed catalog — library size isn't bounded by RAM
• Local Wi-Fi shelf — upload, list, and delete books from your browser
• Zero-config onboarding — with no stored credentials, the reader raises an open hotspot with a captive portal and an on-screen QR code

Try it

• Browser emulator — the real render code in WebAssembly, no device needed

Development

Prerequisites: install Rust with rustup, then install the firmware target and release-image tool:

rustup target add riscv32imc-unknown-none-elf
cargo install espflash

tools/cargo.sh run -p fw --release                              # build, flash, serial monitor
tools/cargo.sh test -p app-core -p proto --target aarch64-apple-darwin
cargo run --manifest-path tools/emulator/Cargo.toml --target aarch64-apple-darwin \
  --no-default-features -- --scenario fixtures/scenarios --check fixtures/golden
tools/bench/bench.py channel-stress --host                       # host bench

Only flashing needs the device on USB; the app logic, parsers, renderer, and emulator all build and test on a plain host. The stable toolchain is configured in rust-toolchain.toml.

Hardware-facing bench runs live in tools/bench. Use short page-turn and sleep-sync runs before trusting flashed builds after display, input, sleep, reader rendering, SD/cache, or progress-write changes; use longer soak/storage runs before risky merges or releases.

Flashing

cargo run flashes over USB for development. To install without a toolchain — from a built image, or onto a unit that shipped with USB flashing disabled — tagged releases publish the app/SD images and docs/FLASHING.md covers the paths: web flasher, SD card, and the in-app update from the card.

Credits

• Literata and Merriweather (both OFL) for the reading typefaces
• The OpenX4 community SDK for panel addressing behavior
• Crosspoint Reader for the community reverse-engineering behind X3 device support

License

MIT