From 9e706307272bd7567309cc694cb80158079c627d Mon Sep 17 00:00:00 2001 From: pelgraine <140762863+pelgraine@users.noreply.github.com> Date: Mon, 9 Feb 2026 09:25:57 +1100 Subject: [PATCH] Updated ereader guide now that we've got epub conversion functionality --- TXT & EPUB Reader Guide.md | 117 +++++++++++++++++++++++++++++++++++++ TXT Reader Guide.md | 47 --------------- 2 files changed, 117 insertions(+), 47 deletions(-) create mode 100644 TXT & EPUB Reader Guide.md delete mode 100644 TXT Reader Guide.md diff --git a/TXT & EPUB Reader Guide.md b/TXT & EPUB Reader Guide.md new file mode 100644 index 00000000..cc3ada12 --- /dev/null +++ b/TXT & EPUB Reader Guide.md @@ -0,0 +1,117 @@ +# Text & EPUB Reader Integration for Meck Firmware + +## Overview + +This adds a text reader accessible via the **R** key from the home screen. + +**Features:** +- Browse `.txt` and `.epub` files from `/books/` folder on SD card +- Automatic EPUB-to-text conversion on first open (cached for instant re-opens) +- Word-wrapped text rendering using tiny font (maximum text density) +- Page navigation with W/S/A/D keys +- Automatic reading position resume (persisted to SD card) +- Index files cached to SD for instant re-opens +- Bookmark indicator (`*`) on files with saved positions +- Compose mode (`C`) still accessible from within reader + +**Key Mapping:** +| Context | Key | Action | +|---------|-----|--------| +| Home screen | R | Open text reader | +| File list | W/S | Navigate up/down | +| File list | Enter | Open selected file | +| File list | Q | Back to home screen | +| Reading | W/A | Previous page | +| Reading | S/D/Space/Enter | Next page | +| Reading | Q | Close book → file list | +| Reading | C | Enter compose mode | + +--- + +## SD Card Setup + +Place `.txt` or `.epub` files in a `/books/` folder on the SD card root. The reader will: +- Auto-create `/books/` if it doesn't exist +- Auto-create `/.indexes/` for page index cache files +- Auto-create `/books/.epub_cache/` for converted EPUB text +- Skip macOS hidden files (`._*`, `.DS_Store`) +- Support up to 50 files + +**Index format** is compatible with the standalone reader (version 4), so if you've used the standalone reader previously, bookmarks and indexes will carry over. + +--- + +## EPUB Support + +### How It Works + +EPUB files are transparently converted to plain text on first open. The conversion pipeline is: + +1. **File list** — `scanFiles()` picks up both `.txt` and `.epub` files from `/books/` +2. **First open** — `openBook()` detects the `.epub` extension and triggers conversion: + - Shows a "Converting EPUB..." splash screen + - Extracts the ZIP structure using ESP32-S3's built-in ROM `tinfl` decompressor (no external library needed) + - Parses `META-INF/container.xml` → finds the OPF file + - Parses the OPF manifest and spine to get chapters in reading order + - Extracts each XHTML chapter, strips tags, decodes HTML entities + - Writes concatenated plain text to `/books/.epub_cache/.txt` +3. **Subsequent opens** — the cached `.txt` is found immediately and opened like any regular text file + +### Cache Structure + +``` +/books/ + MyBook.epub ← original EPUB (untouched) + SomeStory.txt ← regular text file + .epub_cache/ + MyBook.txt ← auto-generated from MyBook.epub +/.indexes/ + MyBook.txt.idx ← page index for the converted text +``` + +- The original `.epub` file is never modified +- Deleting a cached `.txt` from `.epub_cache/` forces re-conversion on next open +- Index files (`.idx`) work identically for both regular and EPUB-derived text files +- Boot scan picks up previously cached EPUB text files so they appear in the file list even before the EPUB is re-opened + +### EPUB Processing Details + +The conversion is handled by three components: + +| Component | Role | +|-----------|------| +| `EpubZipReader.h` | ZIP central directory parsing + `tinfl` decompression (supports Store and Deflate) | +| `EpubProcessor.h` | EPUB structure parsing (container.xml → OPF → spine) and XHTML tag stripping | +| `TextReaderScreen.h` | Integration: detects `.epub`, triggers conversion, redirects to cached `.txt` | + +**XHTML stripping handles:** +- Tag removal with block-element newlines (`

`, `
`, `

`, `

`–`

`, `
  • `, etc.) +- ``, `