diff --git a/.gitignore b/.gitignore index fbdea2e..af0ec00 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,24 @@ +# PlatformIO build output and local editor settings. .pio/ .vscode/ *.bin +*.elf +*.map +# Python bytecode, test output, and coverage reports. +__pycache__/ +*.py[cod] +.pytest_cache/ +.coverage +coverage.xml +htmlcov/ + +# Generated reader content and local source books. +chapters/ +*.epub + +# Filesystem metadata that may appear when preparing an SD card. +.DS_Store +._* +.Trash/ +System Volume Information/ diff --git a/README.md b/README.md index 8f83f75..3bad09e 100644 --- a/README.md +++ b/README.md @@ -66,21 +66,59 @@ operating systems: .rsvp` file alongside every +section. Its versioned records preserve italic and bold EPUB markup—including +semantic tags, CSS classes, and inline CSS—using delta-encoded word indexes, +and include a reserved timing-modifier field for a future reading-timing pass. +The reader validates the sidecar's fingerprint against its `.txt` file and +safely ignores it if it is missing, stale, or malformed. Valid italic and bold +records select matching reader-font variants. Eject the card safely and insert it in the board before powering the board. @@ -94,7 +132,7 @@ pio run ``` On the first run, PlatformIO downloads the pinned ESP32 platform, compiler, and -Arduino_GFX dependency. A successful build ends with `SUCCESS` and creates the +TFT_eSPI dependency. A successful build ends with `SUCCESS` and creates the firmware under `.pio/build/rsvp_reader/`. The project targets the T-Display S3 Pro's 16 MB flash and 8 MB OPI PSRAM. It @@ -136,9 +174,9 @@ pio run -t upload --upload-port /dev/ttyACM0 Replace `/dev/ttyACM0` with the port from the previous step. On Windows, for example, use `--upload-port COM3`. -After a successful upload, the display shows the first word of a book and is +After a successful upload, the display shows the current section title and is **paused**. If it shows `NO BOOKS`, check that the card is inserted, FAT32, and -has at least one `/books/*.txt` file. +contains at least one `/books//TOC.txt` with a listed section file. If the board is not detected or an upload repeatedly fails, force download mode: @@ -149,11 +187,12 @@ If the board is not detected or an upload repeatedly fails, force download mode: ## 6. Read -| Control | Paused | Playing | +| Control | Reading view | Menu or picker | | --- | --- | --- | -| BOOT / GPIO0 | Play or pause | Play or pause | -| Upper-right / GPIO12 | Previous paragraph | Lower WPM | -| Lower-right / GPIO16 | Next paragraph | Higher WPM | +| BOOT / GPIO0 | Open menu | Close/cancel without saving | +| Touch edge Home button | Play or pause | Open highlighted option / apply | +| Upper-right / GPIO12 | Previous paragraph or section | Move selection backward | +| Lower-right / GPIO16 | Next paragraph or section | Move selection forward | Do not hold BOOT while pressing RESET during normal use; that combination is the manual download mode used for recovery above. @@ -164,11 +203,12 @@ GPIO12 wakes it. ## Resume and power behavior -When the reader advances, pauses, or sleeps, it saves the exact word index and -current WPM in the ESP32's nonvolatile storage. On the next boot or wake it -opens the same book, moves to the first word of the paragraph containing that -saved index, renders it, and remains paused. This is intentional: it gives you -paragraph context before reading resumes. +The reader saves the selected section, WPM, brightness, and font settings in +the ESP32's nonvolatile storage. On the next boot or wake it opens the same +section's title card and remains paused; pressing the touch-edge Home button +begins at that section's first word. It defers full chapter-list validation +until chapter browsing is needed, so normal startup opens only the selected +chapter and its sidecar. The physical power switch only disconnects the battery. USB power is sufficient for development and flashing. The reader intentionally has no Wi-Fi, Bluetooth, @@ -180,8 +220,9 @@ cloud account, or synchronization feature. - **Upload cannot connect:** use the BOOT + RESET sequence in step 5, then retry. - **Permission denied on Linux:** complete the `dialout` group step and log out and back in. -- **`NO BOOKS`:** reformat the card FAT32, create `/books`, and copy a `.txt` - file directly into that folder. Confirm the card is fully seated. +- **`NO BOOKS`:** reformat the card FAT32, create `/books/`, and add a + `TOC.txt` plus the listed `.txt` section files. Confirm the card is fully + seated. Dot-prefixed folders such as `.Trash` are ignored. - **Black display after boot:** press GPIO12 to wake it if it has slept; otherwise reflash and check whether the v1.0 backlight build flag is needed. - **Build fails before compilation:** rerun `pio run` with internet access so @@ -189,8 +230,8 @@ cloud account, or synchronization feature. ## Limits of the first MVP -- It reads up to 1.5 MiB per book and discovers `.txt` files directly in - `/books` (no nested folders). +- It reads sections up to 1.5 MiB from `/books//
.txt`, in the + order declared by that book's `TOC.txt`. - The built-in display font is best for printable ASCII text. UTF-8 text files are accepted, but accented/non-Latin characters need a Unicode font addition before they will render correctly. diff --git a/T-Display-S3-Pro b/T-Display-S3-Pro new file mode 160000 index 0000000..bef8db7 --- /dev/null +++ b/T-Display-S3-Pro @@ -0,0 +1 @@ +Subproject commit bef8db74e847f1e89a10cb3877f3b3a8544857d6 diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..1b5d481 --- /dev/null +++ b/TODO.md @@ -0,0 +1,47 @@ +# TODO + +## Add anti-aliased reader fonts + +The current reader uses TFT_eSPI's bitmap FreeSans, FreeSerif, and FreeMono +fonts. They are compact and fast, but their edges remain jagged at large sizes. + +Use TFT_eSPI smooth-font (`.vlw`) assets for the reading view and font-setting +previews. + +1. Generate or obtain licensed `.vlw` files for sans-serif, serif, and + monospace faces at the seven supported reader sizes: 1, 1.5, 2, 2.5, 3, + 3.5, and 4. +2. Place the files in a dedicated SD-card directory, for example + `/fonts/