Esp32 E-reader

[!WARNING]
Although tested by myself, this project was fully coded by AI without human review of the code itself, use at your own risk.

Inspired by Paul Lagier, but his code was only for the Heltec V1 e-ink board, so i took the idea and expanded it to other models with my own twist.

Supported models

Install from the browser: https://daafip.github.io/esp32-ereader/ (Chrome or Edge, reader on USB; leave "Erase everything" unticked to keep your settings).

Firmware available at the releases or build yourself pixi run fw-build. Flash with platform io, esptools or pixi run fw-flash

Board	Flash over USB (at 0x0)	Update over Wi-Fi	Tested?
LilyGo T5-2.13	t5-reader-x.x.x.bin	t5-reader-x.x.x-ota.bin	Yes
LilyGo T5-4.7" S3	t5-47-reader-x.x.x.bin	t5-47-reader-x.x.x-ota.bin	NO - let me know!
M5Stack M5PaperS3	m5papers3-reader-x.x.x.bin	m5papers3-reader-x.x.x-ota.bin	NO - let me know!
M5Stack M5Paper	m5paper-reader-x.x.x.bin	m5paper-reader-x.x.x-ota.bin	NO - let me know!
FireBeetle 2 ESP32-C6 + Waveshare 7.5" (home-built)	firebeetle-75-reader-x.x.x.bin	firebeetle-75-reader-x.x.x-ota.bin	Not with a card yet
the same without a microSD card	firebeetle-75-flash-reader-x.x.x.bin	over USB only	Yes

The 4.7" boards and the M5 boards have not run this firmware yet: see docs/checkpoints.md for what to check. The 7.5" build is a FireBeetle 2 ESP32-C6 with a Waveshare 7.5" HAT, three buttons and a microSD breakout, readable in portrait or landscape: docs/hardware-firebeetle-75.md. Without a card it keeps about 170 pages in its flash (firebeetle-75-flash-reader-x.x.x.bin, updates over USB only).

How it works

Books are typeset ahead of time into 1-bit page images (.t5b), so the reader only copies pages to the screen. Drop an EPUB or TXT on the reader's Wi-Fi page and your phone does the typesetting (font, size, margins, hyphenation), or convert on a PC with pixi run prep book.epub. More in docs/usage.md; hardware notes in docs/hardware.md, docs/hardware-t5-47.md and docs/hardware-m5paper.md.

Also on board: chapters, bookmarks, search (on the phone, jumping the reader to a hit), library folders, reading statistics, a lock, sleep screens (book, cover, your own pictures, a square picture beside the book, or the page itself), a status bar that can shrink or hide, OpenDyslexic and bionic reading, English and Dutch menus, and settings, home Wi-Fi and factory reset from the phone.

Android app: switch between the reader and ESPHome

The FireBeetle 7.5" can run ESPHome too (a Home Assistant dashboard, say). The Android app fw-switch-x.x.x.apk from the releases puts either firmware on it over a USB-C OTG cable, no PC needed: choose the two firmware files once (the reader's firebeetle-75-flash-reader-x.x.x.bin and ESPHome's factory image), then tap Install. It resets the board into download mode itself (or asks for BOOT + RST when it sleeps), writes only what changed, checks it and restarts the board. Android 10 or later, on a phone with USB OTG; build it yourself with pixi run android-build. Releases signed with the project's key are also in its own F-Droid repository, https://daafip.github.io/esp32-ereader/fdroid/repo (the release notes give the link with the key's fingerprint), so F-Droid keeps the app up to date. How it works, its limits, and how to keep the books in the flash across switches: docs/firmware-switcher.md.

References

Hardware and display drivers:

• bb_epaper (GPL-3.0) by Larry Bank: SPI e-paper driver and the drawing/font code for every board
• FastEPD (Apache-2.0) by Larry Bank: parallel e-paper driver for the T5-4.7" and the M5PaperS3
• LilyGo T5 e-paper series and LilyGo-EPD47: pinouts and schematics of the LilyGo boards
• M5Unified and M5GFX: pinouts and power handling of the M5 boards, and the IT8951 protocol used for the M5Paper
• DFRobot FireBeetle 2 ESP32-C6 and Waveshare e-Paper Driver HAT: the board and HAT of the 7.5" build

Firmware build and flashing:

• pioarduino: PlatformIO platform for Arduino-ESP32 3.x
• esptool-js (Apache-2.0) by Espressif: the browser installer
• esptool-js: flashing from the browser
• QR Code generator (MIT) by Project Nayuki: the Wi-Fi QR codes
• esptool (GPL-2.0-or-later) by Espressif: the ROM loader protocol and reset sequences the Android app speaks, ported from its source

Book conversion:

• Pillow, EbookLib, fontTools
• Pyphen: hyphenation patterns (also exported for the in-browser converter)
• Fonts: Ubuntu (default), and Literata, Atkinson Hyperlegible and Merriweather from Google Fonts (SIL OFL), OpenDyslexic by Abbie Gonzalez (SIL OFL)

Tooling: pixi runs everything (pixi run --list).

License

GPL-3.0-or-later, see LICENSE. The firmware links bb_epaper (GPL-3.0-or-later), so the firmware images are under the GPL as well.

Third-party parts keep their own licences:

• FastEPD: Apache-2.0 (downloaded at build time; firmware/src/fastepd_panel.cpp contains its waveform table)
• QR Code generator, vendored in firmware/lib/qrcodegen: MIT
• Fonts: Ubuntu Font Licence 1.0 (Ubuntu; also the bitmap UI fonts in firmware/include/fonts) and SIL OFL 1.1 (Literata, Atkinson Hyperlegible, Merriweather, OpenDyslexic; OpenDyslexic is shipped unmodified, as its Reserved Font Name requires)
• Hyphenation patterns from Pyphen: their own licences

The reader serves the full font licences and the pattern notices at /licenses.txt on its Wi-Fi page.