tds3p-rsvp-reader/README.md

# T-Display S3 Pro RSVP Reader

An offline-first RSVP reader for the LilyGO T-Display S3 Pro. It renders one
white word on a black, landscape display and never starts Wi-Fi or Bluetooth.

## What you need

- A LilyGO T-Display S3 Pro and a **USB-C data cable**. A charge-only cable
  cannot upload firmware.
- A computer with internet access for the first build, Python 3, and a terminal.
- A microSD card formatted as FAT32. The reader uses this as its book library.
- This repository, cloned or downloaded to your computer.

The first build downloads the ESP32 toolchain and display library. The reader
does not need network access after it has been flashed.

## 1. Install PlatformIO Core

PlatformIO Core is the command-line build and upload tool used by this project.
Install it in your normal user account; do not use `sudo`.

### macOS or Linux

Confirm Python 3 is available:

```bash
python3 --version
```

Then use PlatformIO's installer:

```bash
curl -fsSL -o get-platformio.py https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py
python3 get-platformio.py
```

The installer puts `pio` at `~/.platformio/penv/bin/pio`. Add that directory to
your shell `PATH`, or use the full path in every command below. For the current
shell only:

```bash
export PATH="$HOME/.platformio/penv/bin:$PATH"
pio --version
```

On Linux, if the serial device appears but uploads fail with a permission error,
add your user to the serial-device group and then sign out and back in:

```bash
sudo usermod -a -G dialout "$USER"
```

### Windows

Install Python 3, then follow PlatformIO's official installer instructions.
After installation, open a new PowerShell window and confirm:

```powershell
pio --version
```

PlatformIO's installer documentation is the authoritative reference for all
operating systems: <https://docs.platformio.org/en/latest/core/installation/methods/installer-script.html>.

## 2. Prepare a book card

1. Format the microSD card as **FAT32**.
2. Create a directory named `books` at the card's root.
3. Create one folder per book inside `books`. Each book folder needs a
   `TOC.txt`, UTF-8 text files for its sections, and matching `.rsvp` sidecars
   generated by the converter.

`TOC.txt` controls both section order and title-card text. Each non-empty line
names a section and its file is that name plus `.txt`.

The resulting card must look like this:

```text
microSD root/
└── books/
    └── Example Book/
        ├── TOC.txt
        ├── Dedication.txt
        ├── Dedication.rsvp
        ├── Chapter 1.txt
        ├── Chapter 1.rsvp
        ├── Chapter 2.txt
        └── Chapter 2.rsvp
```

For the example above, `TOC.txt` contains:

```text
Dedication
Chapter 1
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"
```

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"
```

The output directory must be empty unless `--overwrite` is supplied. Copy the
resulting `Example Book` directory into `/books` on the card. A
section and its `.rsvp` sidecar may each be up to 1 MiB. The converter writes
`CONVERSION_REPORT.txt` in the book directory. It records any unsupported
non-ASCII characters left after
normalizing common punctuation, ligatures, accents, whitespace, fractions, and
ornamental breaks. Review that report before copying the book: transliterate or
replace reported characters deliberately, or defer the book until a
Unicode-capable font is available. The included display font is best for
printable ASCII.

The converter also writes a compact `<section>.rsvp` file alongside every
section. Its versioned, delta-encoded records preserve italic and bold EPUB
markup—including semantic tags, CSS classes, and inline CSS—and reading-timing
metadata. The fingerprint covers the source `.txt` bytes, before the device
applies display-only punctuation normalization. During conversion, the
desktop-only English dictionary marks each word not in that dictionary. The
first ten appearances of each marked word in
the book, plus its first appearance in every section, use a 3× delay. Later
appearances use a 2× delay. The reader uses the strongest applicable delay, so
sentence and paragraph pauses are never compounded with unfamiliar-word
timing. 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; the device never performs
dictionary or SD-card lookups while advancing words.

The converter requires the desktop-only `english-words` package listed in
`requirements.txt`; the reader does not need this 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.

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:

```bash
cd /path/to/tds3p-rsvp-reader
pio run
```

On the first run, PlatformIO downloads the pinned ESP32 platform, compiler,
and the TFT_eSPI, SensorLib, and XPowersLib dependencies. 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
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
building:

```ini
  -DTDS3P_V1_0
```

## 4. Connect and identify the board

1. Connect the board directly to the computer with the USB-C data cable.
2. Give the operating system a few seconds to enumerate it.
3. List serial ports:

```bash
pio device list
```

Typical ports are `/dev/ttyACM0` or `/dev/ttyUSB0` on Linux, `/dev/cu.usbmodem*`
on macOS, and `COM3` on Windows. Note the port belonging to the board.

## 5. Upload and start the reader

Let PlatformIO select the port automatically:

```bash
pio run -t upload
```

If it selects the wrong port or does not find one, supply it explicitly:

```bash
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 current section title and is
**paused**. If it shows `NO BOOKS`, check that the card is inserted, FAT32, and
contains at least one `/books/<book>/TOC.txt` with a listed section file.

If the board is not detected or an upload repeatedly fails, force download mode:

1. Hold **BOOT** (the lower-left button, GPIO0).
2. While holding BOOT, press and release **RESET** (upper-left).
3. Release BOOT.
4. Run the upload command again.

## 6. Read

| Control | Reading view | Menu or picker |
| --- | --- | --- |
| 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.

The default is 300 WPM. While paused, the backlight dims after 20 seconds,
switches off after one minute, and the ESP32 deep-sleeps after ten minutes.
GPIO12 wakes it.

## Resume and power behavior

The reader saves the selected section, paragraph-level position, 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 the saved paragraph. It validates
the saved section against its `TOC.txt` before opening it, then falls back to
the first available book if the card has changed.

When continuous reading reaches the end of a section, it opens the next
section's title card and pauses. Press the touch-edge Home button to begin that
section.

The physical power switch only disconnects the battery. USB power is sufficient
for development and flashing. The reader intentionally has no Wi-Fi, Bluetooth,
cloud account, or synchronization feature.

## Troubleshooting

- **No serial port:** use another USB-C cable; many included cables only charge.
- **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/<book>`, 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
  PlatformIO can download the required packages.

## Limits of the first MVP

- It reads sections up to 1 MiB from `/books/<book>/<section>.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.
- The v1.1 backlight driver is the default. Define `TDS3P_V1_0` in
  `build_flags` for an original v1.0 board.