State & events
Typed product state, logical actions, settings, persistence contracts and runtime coordination without board-specific dependencies.
SOFTWARE
Reader logic before platform tricks.
ENKU keeps its product logic independent from the board. Parsing, pagination, Library state, reading progress and runtime transitions can be built and tested on a host; ESP-IDF is the hardware layer that connects the same model to storage, buttons, power, Wi-Fi and the e-paper panel.
CORE
Framework-neutral C++
DEVICE TARGET
ESP-IDF · ESP32-S3
CURRENT FORMAT
TXT · EPUB · FB2 working
ARCHITECTURE
Boundaries that stay useful.
The project is split by responsibility rather than by screen. Application state never owns GPIO numbers, parser DOMs or display handles; platform details remain below narrow service interfaces so the reader core stays testable and portable.
Content & pages
Normalized documents, semantic positions, pagination, Reader Engine and deterministic ReaderSession navigation.
Narrow interfaces
Storage, refresh, network and power are capabilities consumed by the application rather than hardware APIs reached from UI code.
Real hardware
ESP-IDF owns SDMMC, SSD1677 display transport, physical buttons, AXP2101, Wi-Fi and board-specific composition.
RUNTIME
A deterministic reading path.
Visible changes follow an explicit event-driven path. The authoritative state changes first; layout and rendering follow; only then is a refresh request sent to the e-paper layer. This keeps reading position independent from framebuffer state.
01Input / event
02State transition
03Reader / layout
04Render plan
05Refresh service
06E-paper
The current device runtime uses the same graph for Library focus, opening a book, page turns, sleep/wake and power-off persistence.
IMPLEMENTATION
What already exists.
The repository distinguishes implemented software from planned format support. Host-testable logic is already substantial, while physical behavior remains subject to on-device validation.
IMPLEMENTED
Reader core
TXT, EPUB and FB2 parsing, bounded/ranged source access, semantic pagination, DocumentReaderEngine, ReaderSession and open / page / back / finished lifecycle are implemented and exercised by host tests. Parser memory ceilings are centralized in one contract: 32 KiB streaming chunks, 512 KiB FB2 metadata, 4 MiB text resources and bounded ZIP directory/entry counts.
IMPLEMENTED
Library & persistence
Filtering, sorting, search, focus, import/delete flows and versioned A/B CBOR state with CRC recovery cover Library, settings, checkpoints, app context and boot-loop protection. Reader-state flushing is centralized so Back, Sleep and Power Off follow the same persistence rules, while long reading sessions save lightweight progress checkpoints every eight successful page turns.
IMPLEMENTED
Rendering boundary
A 1-bit framebuffer separates UI rendering from panel transport. Noto Sans Regular is now embedded in the firmware image and FreeType uses that same face for pagination metrics and monochrome glyph rasterization; an SD copy remains only an optional override.
IMPLEMENTED
ESP-IDF integration
The board target includes storage, SSD1677 refresh paths, button polling and logical dispatch, power, Wi-Fi and a persistent DeviceRuntime loop. BoardProfile/BoardCapabilities separate board features from the reader core. SD mount/setup failures remain recoverable, the reader font is firmware-owned, and Wi-Fi now degrades independently: network-driver failure marks connectivity as Error without blocking Library or Reading.
VALIDATION
Physical behavior
Panel quality, refresh timing, power draw, wake behavior and real-device interaction still require measurement on physical hardware. The refresh service now includes a vendor-driven anti-ghosting policy that forces a clean full refresh after five fast/partial updates.
BOOK FORMATS
Scoped without pretending.
Reader v1 now opens TXT, EPUB and FB2 through the same normalized Book Loader path. EPUB and FB2 use bounded/ranged reads and memory-aware parsing, while stale semantic checkpoints fall back safely instead of turning a changed book into an open failure.
TXTWORKING
Concrete parser, loader path, pagination and ReaderSession flow exist now.
EPUBWORKING
ZIP-backed parser, manifest/spine/navigation handling, ranged source reads, bounded memory guards and mixed-case metadata regressions are implemented.
FB2WORKING
Streaming/ranged parsing, section navigation, metadata extraction, mixed-case XML handling and stale-position recovery are implemented.
PDFDEFERRED
Explicitly outside the first reader revision so the initial architecture can stay focused.
SOURCE
The engineering record lives with the code.
The website is the readable snapshot. Architecture decisions, runtime contracts, platform bring-up notes and tests stay versioned in the repository.