An e-reader application for the Lilygo T5 E-Paper S3 Pro (ESP32-S3, 9.7" ED047TC1 e-paper display). Reads EPUB files embedded directly in firmware at compile time.
| Component | Detail |
|---|---|
| MCU | ESP32-S3 |
| Display | 9.7" ED047TC1 (960×540, 4-bit grayscale) |
| Touch | GT911 capacitive touchscreen |
| Battery | BQ27220 fuel gauge, BQ25896 charger |
Install the ESP Rust toolchain via espup:
cargo install espup
espup installInstall the flash/monitor tool:
cargo install espflashActivate the ESP environment (run once per shell session, or add to your shell profile):
. ~/export-esp.shThe default Cargo target is xtensa-esp32s3-none-elf. Use the esp-build / esp-run aliases which include the required -Z build-std=alloc,core flag:
# Build only
cargo esp-build --example ereader_ui
# Build and flash to device (opens serial monitor after flashing)
cargo esp-run --example ereader_uicargo esp-run --example ereader_uiThe active book is embedded at compile time in examples/ereader_ui.rs:
const EPUB_DATA: &[u8] = include_bytes!("sherlock_holmes.epub");Replace the filename with any EPUB placed in the examples/ directory, then rebuild and reflash.
The font is set in src/font.rs:
static FONT_DATA: &[u8] = include_bytes!("../fonts/NoticiaText-Regular.ttf");Available fonts in fonts/:
- Alegreya (Regular / Italic / Bold)
- AtkinsonHyperlegible (Regular / Italic / Bold)
- CrimsonPro (Regular / Italic / Bold)
- Georgia
- Literata (Regular / Italic / Bold)
- NoticiaText (Regular / Italic / Bold) ← current
- Vollkorn (Regular / Italic / Bold)
The example ereader_ui supports a desktop SDL2 simulator or the real device.
Prerequisites — install SDL2 (only needed once):
brew install sdl2 # macOS
sudo apt install libsdl2-dev # Debian/UbuntuBuild either example with cargo sim-build, or build-and-run with cargo sim-run:
cargo sim-build --example ereader_ui
cargo sim-run --example ereader_ui
cargo sim-run --example ereader_uiereader_ui supports a desktop simulator via SDL2. It opens a portrait 540×960 window and lets you navigate the book with the keyboard.
Run:
cargo sim-run --example ereader_uiKeyboard controls:
| Key | Action |
|---|---|
| Right arrow / Space / N | Next page (or next chapter) |
| Left arrow / Backspace / P | Previous page (or previous chapter) |
| Close window / Q | Quit |
The sim-run alias expands to run --no-default-features --features simulator --target aarch64-apple-darwin (sim-build is the same but with build instead of run). Adjust the target triple in .cargo/config.toml if you are on a non-Apple-Silicon machine (see table below).
ereader_ui is a UI prototype built with iris-ui. It opens a 540×960 portrait window and renders a full e-reader UI backed by Sherlock Holmes (sherlock_holmes.epub). Content is rendered with Noticia Text TrueType. Click the on-screen buttons or use keyboard shortcuts to navigate.
Run:
cargo sim-run --example ereader_uiKeyboard controls:
| Key | Action |
|---|---|
| Right arrow / Space | Next page (or next chapter) |
| Left arrow / Backspace | Previous page (or previous chapter) |
| Close window | Quit |
On-device features (ESP32-S3):
| Feature | Detail |
|---|---|
| BOOT button (GPIO0) | Previous page / previous chapter |
| Side button (GPIO38) | Next page / next chapter |
| Face button (GT911 key, circle below screen) | Next page / next chapter |
| Fast paging | Hold any paging button for 1 s to enter fast-scroll mode; pages advance one at a time initially, then five at a time after 5 s; release to jump |
| Light sleep | Backlight off after 60 s of inactivity; wakes instantly on any button press |
| Deep sleep | Full ESP32-S3 deep sleep after 60 min of inactivity, or immediately via the "Sleep Now" button in Settings; reading position saved to RTC fast memory |
| Wake from deep sleep | Press BOOT button; position and settings restored from RTC (no flash read) |
| NVS persistence | Book, font size, backlight, orientation, and reading position saved to flash NVS; restored on any boot including hard reset |
epub_test exercises the EPUB, layout, and reader modules without any display hardware. It can run on your development machine:
cargo run --example epub_test --no-default-features --target aarch64-apple-darwinAdjust the target triple for your machine:
| Machine | Target triple |
|---|---|
| Apple Silicon Mac | aarch64-apple-darwin |
| Intel Mac | x86_64-apple-darwin |
| Linux x86-64 | x86_64-unknown-linux-gnu |
src/
epub.rs — ZIP/EPUB parser, spine extraction, HTML-to-plaintext stripping
layout.rs — Word-wrap and pagination engine
reader.rs — Stateful reader (current page, relayout on font-size change)
font.rs — TTF rasterizer (fontdue) with Gray4 blending
driver/ — ESP32-S3 display (ED047TC1), touch (GT911), RMT/DMA drivers
examples/
ereader_ui.rs — Main application binary
fonts/ — Embedded TTF/OTF font files
| Feature | Default | Description |
|---|---|---|
esp |
yes | Enables all ESP32-S3 hardware dependencies. Disable with --no-default-features for local/native builds. |
Defined in partitions.csv. Sequential-storage is used for persisting reading position, font size, orientation, and backlight level across deep-sleep cycles.
Run the simulator with the debug-inspector feature enabled then you can connect to http://127.0.0.1:3000/ to see it.
cargo sim-run --example ereader_ui --features=debug-inspect