From ba65e498564eb8ec3f3232cf2c5b128931ab6b24 Mon Sep 17 00:00:00 2001 From: j2 Date: Sat, 10 Oct 2026 18:05:01 -0500 Subject: [PATCH] reorganize --- .github/workflows/ci.yml | 6 +++ .gitignore | 3 +- Makefile | 31 ++++++++++++++ README.md | 14 +++---- T-Display-S3-Pro | 1 - TODO.md | 38 ------------------ .../epub_to_chapters.py | 0 .../examples}/rsvp-timing-sample.epub | Bin .../examples}/sample.txt | 0 .../requirements.txt | 0 {tests => book-processing/tests}/__init__.py | 0 .../tests}/test_epub_to_chapters.py | 0 .../board}/t-display-s3-pro.json | 0 {include => firmware/include}/Board.h | 0 {include => firmware/include}/Config.h | 0 {include => firmware/include}/Library.h | 0 {include => firmware/include}/Reader.h | 0 {include => firmware/include}/Settings.h | 0 {include => firmware/include}/tft_setup.h | 0 partitions.csv => firmware/partitions.csv | 0 platformio.ini => firmware/platformio.ini | 0 {src => firmware/src}/Board.cpp | 0 {src => firmware/src}/Library.cpp | 0 {src => firmware/src}/Reader.cpp | 0 {src => firmware/src}/Settings.cpp | 0 {src => firmware/src}/main.cpp | 0 26 files changed, 46 insertions(+), 47 deletions(-) create mode 100644 Makefile delete mode 160000 T-Display-S3-Pro rename epub_to_chapters.py => book-processing/epub_to_chapters.py (100%) rename {examples => book-processing/examples}/rsvp-timing-sample.epub (100%) rename {examples => book-processing/examples}/sample.txt (100%) rename requirements.txt => book-processing/requirements.txt (100%) rename {tests => book-processing/tests}/__init__.py (100%) rename {tests => book-processing/tests}/test_epub_to_chapters.py (100%) rename {board => firmware/board}/t-display-s3-pro.json (100%) rename {include => firmware/include}/Board.h (100%) rename {include => firmware/include}/Config.h (100%) rename {include => firmware/include}/Library.h (100%) rename {include => firmware/include}/Reader.h (100%) rename {include => firmware/include}/Settings.h (100%) rename {include => firmware/include}/tft_setup.h (100%) rename partitions.csv => firmware/partitions.csv (100%) rename platformio.ini => firmware/platformio.ini (100%) rename {src => firmware/src}/Board.cpp (100%) rename {src => firmware/src}/Library.cpp (100%) rename {src => firmware/src}/Reader.cpp (100%) rename {src => firmware/src}/Settings.cpp (100%) rename {src => firmware/src}/main.cpp (100%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 458734e..804cea4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,6 +7,9 @@ on: jobs: converter: runs-on: ubuntu-latest + defaults: + run: + working-directory: book-processing steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 @@ -18,6 +21,9 @@ jobs: firmware: runs-on: ubuntu-latest + defaults: + run: + working-directory: firmware steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 diff --git a/.gitignore b/.gitignore index f279553..cc97458 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ *.map # Python bytecode, test output, and coverage reports. +.venv/ __pycache__/ *.py[cod] .pytest_cache/ @@ -16,7 +17,7 @@ htmlcov/ # Generated reader content and local source books. chapters/ *.epub -!examples/rsvp-timing-sample.epub +!book-processing/examples/rsvp-timing-sample.epub # Filesystem metadata that may appear when preparing an SD card. .DS_Store diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..505b765 --- /dev/null +++ b/Makefile @@ -0,0 +1,31 @@ +PYTHON ?= python3 +PIO ?= pio +UPLOAD_PORT ?= +VENV := .venv +DEPS_STAMP := $(VENV)/.requirements-installed + +.DEFAULT_GOAL := all +.PHONY: all deps test convert build flash + +all: test convert build + +deps: $(DEPS_STAMP) + +$(DEPS_STAMP): book-processing/requirements.txt + $(PYTHON) -m venv $(VENV) + $(VENV)/bin/python -m pip install -r $< + touch $@ + +test: deps + . $(VENV)/bin/activate && cd book-processing && python -m unittest discover -v + +convert: deps + @output_dir=$$(mktemp -d /tmp/tds3p-timing-sample.XXXXXX); \ + echo "Converting sample EPUB into $$output_dir"; \ + . $(VENV)/bin/activate && cd book-processing && python epub_to_chapters.py examples/rsvp-timing-sample.epub "$$output_dir" + +build: + cd firmware && $(PIO) run + +flash: + cd firmware && $(PIO) run -t upload $(if $(UPLOAD_PORT),--upload-port $(UPLOAD_PORT)) diff --git a/README.md b/README.md index 85b0979..ad433c6 100644 --- a/README.md +++ b/README.md @@ -101,15 +101,15 @@ Chapter 2 Generate this layout from an EPUB with the included converter: ```bash -./.venv/bin/python -m pip install -r requirements.txt -./.venv/bin/python epub_to_chapters.py book.epub "Example Book" +./.venv/bin/python -m pip install -r book-processing/requirements.txt +./.venv/bin/python book-processing/epub_to_chapters.py book.epub "Example Book" ``` For a quick end-to-end check, the repository includes a two-chapter sample with EPUB styles, punctuation, and repeated invented names: ```bash -./.venv/bin/python epub_to_chapters.py examples/rsvp-timing-sample.epub "Timing Sample" +./.venv/bin/python book-processing/epub_to_chapters.py book-processing/examples/rsvp-timing-sample.epub "Timing Sample" ``` The output directory must be empty unless `--overwrite` is supplied. Copy the @@ -141,7 +141,7 @@ bold records select matching reader-font variants; the device never performs dictionary or SD-card lookups while advancing words. The converter requires the desktop-only `english-words` and `wordfreq` -packages listed in `requirements.txt`; the reader does not need either +packages listed in `book-processing/requirements.txt`; the reader does not need either dependency. Reconvert a book to create v2 sidecars with unfamiliar-word timing. Existing v1 style-only sidecars remain readable but do not contain timing metadata. @@ -150,10 +150,10 @@ Eject the card safely and insert it in the board before powering the board. ## 3. Build the firmware -Open a terminal in this project directory: +Open a terminal in the `firmware` directory: ```bash -cd /path/to/tds3p-rsvp-reader +cd /path/to/tds3p-rsvp-reader/firmware pio run ``` @@ -163,7 +163,7 @@ 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 defaults to the v1.1 16-step backlight driver. If your board is the original -v1.0 hardware, add this line under `build_flags` in `platformio.ini` before +v1.0 hardware, add this line under `build_flags` in `firmware/platformio.ini` before building: ```ini diff --git a/T-Display-S3-Pro b/T-Display-S3-Pro deleted file mode 160000 index bef8db7..0000000 --- a/T-Display-S3-Pro +++ /dev/null @@ -1 +0,0 @@ -Subproject commit bef8db74e847f1e89a10cb3877f3b3a8544857d6 diff --git a/TODO.md b/TODO.md index 18be71f..531b34d 100644 --- a/TODO.md +++ b/TODO.md @@ -1,11 +1,5 @@ # TODO -## Bookmarks and per-book progress - -Paragraph-level resume restores the last reading position. Add named bookmarks -and a compact recent-books/progress list so readers can return to several -places in a book without overwriting their normal resume point. - ## Reading profiles Add selectable reading profiles for punctuation and paragraph pause lengths, @@ -34,38 +28,6 @@ record only when it already exists for style/timing metadata or when an entity assignment requires one. Add a persisted reader setting to toggle coloring without requiring reconversion. -## Converter preflight and safe section splitting - -Add a `--check` mode that reports section word counts, section and sidecar -sizes, filename issues, and unsupported characters without writing output. -Offer optional splitting at paragraph boundaries for sections that exceed the -device's 150,000-word or 1 MiB file limits. - -## Memory-limit hardware validation - -Stress-test the 150,000-word and 1 MiB section/sidecar limits on real hardware, -record PSRAM headroom, and lower the supported limit if token indexing or -sidecar metadata leaves insufficient memory for reliable reading. Include -adversarial short-word and dense-sidecar inputs, not just ordinary prose. - -## Reading continuity preference - -Keep the current default of pausing on every chapter title, but add an optional -auto-continue mode for readers who want uninterrupted reading across sections. - -## RSVP orientation point - -Offer an optional focal-letter/orientation-point treatment that subtly marks a -consistent letter within each displayed word. Keep the current centered plain -word rendering as the default and make the feature work with italic and bold -fonts. - -## Library diagnostics and import validation - -Add a device diagnostics screen for SD-card, TOC, missing-section, sidecar, -and memory-limit errors. Extend converter preflight to report the same issues, -including oversized tokens, before a book is copied to the card. - ## Add anti-aliased reader fonts The current reader uses TFT_eSPI's bitmap FreeSans, FreeSerif, and FreeMono diff --git a/epub_to_chapters.py b/book-processing/epub_to_chapters.py similarity index 100% rename from epub_to_chapters.py rename to book-processing/epub_to_chapters.py diff --git a/examples/rsvp-timing-sample.epub b/book-processing/examples/rsvp-timing-sample.epub similarity index 100% rename from examples/rsvp-timing-sample.epub rename to book-processing/examples/rsvp-timing-sample.epub diff --git a/examples/sample.txt b/book-processing/examples/sample.txt similarity index 100% rename from examples/sample.txt rename to book-processing/examples/sample.txt diff --git a/requirements.txt b/book-processing/requirements.txt similarity index 100% rename from requirements.txt rename to book-processing/requirements.txt diff --git a/tests/__init__.py b/book-processing/tests/__init__.py similarity index 100% rename from tests/__init__.py rename to book-processing/tests/__init__.py diff --git a/tests/test_epub_to_chapters.py b/book-processing/tests/test_epub_to_chapters.py similarity index 100% rename from tests/test_epub_to_chapters.py rename to book-processing/tests/test_epub_to_chapters.py diff --git a/board/t-display-s3-pro.json b/firmware/board/t-display-s3-pro.json similarity index 100% rename from board/t-display-s3-pro.json rename to firmware/board/t-display-s3-pro.json diff --git a/include/Board.h b/firmware/include/Board.h similarity index 100% rename from include/Board.h rename to firmware/include/Board.h diff --git a/include/Config.h b/firmware/include/Config.h similarity index 100% rename from include/Config.h rename to firmware/include/Config.h diff --git a/include/Library.h b/firmware/include/Library.h similarity index 100% rename from include/Library.h rename to firmware/include/Library.h diff --git a/include/Reader.h b/firmware/include/Reader.h similarity index 100% rename from include/Reader.h rename to firmware/include/Reader.h diff --git a/include/Settings.h b/firmware/include/Settings.h similarity index 100% rename from include/Settings.h rename to firmware/include/Settings.h diff --git a/include/tft_setup.h b/firmware/include/tft_setup.h similarity index 100% rename from include/tft_setup.h rename to firmware/include/tft_setup.h diff --git a/partitions.csv b/firmware/partitions.csv similarity index 100% rename from partitions.csv rename to firmware/partitions.csv diff --git a/platformio.ini b/firmware/platformio.ini similarity index 100% rename from platformio.ini rename to firmware/platformio.ini diff --git a/src/Board.cpp b/firmware/src/Board.cpp similarity index 100% rename from src/Board.cpp rename to firmware/src/Board.cpp diff --git a/src/Library.cpp b/firmware/src/Library.cpp similarity index 100% rename from src/Library.cpp rename to firmware/src/Library.cpp diff --git a/src/Reader.cpp b/firmware/src/Reader.cpp similarity index 100% rename from src/Reader.cpp rename to firmware/src/Reader.cpp diff --git a/src/Settings.cpp b/firmware/src/Settings.cpp similarity index 100% rename from src/Settings.cpp rename to firmware/src/Settings.cpp diff --git a/src/main.cpp b/firmware/src/main.cpp similarity index 100% rename from src/main.cpp rename to firmware/src/main.cpp