j2
/
tds3p-rsvp-reader
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
tds3p-rsvp-reader/README.md

6.5 KiB
Raw Blame History

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:

python3 --version

Then use PlatformIO's installer:

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:

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:

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:

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. Copy UTF-8 plain-text files ending in .txt into it. Copy examples/sample.txt for the first test.

The resulting card must look like this:

microSD root/
└── books/
    ├── sample.txt
    └── another-book.txt

Only files directly in /books are discovered in this MVP. A book may be up to 1.5 MiB. The included display font is best for printable ASCII; accented or non-Latin scripts need a future Unicode-font upgrade.

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:

cd /path/to/tds3p-rsvp-reader
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 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:

  -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:
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:

pio run -t upload

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

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 paused. If it shows NO BOOKS, check that the card is inserted, FAT32, and has at least one /books/*.txt 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 Paused Playing
BOOT / GPIO0 Play or pause Play or pause
Upper-right / GPIO12 Previous paragraph Lower WPM
Lower-right / GPIO16 Next paragraph Higher WPM

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

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 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, and copy a .txt file directly into that folder. Confirm the card is fully seated.
  • 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 up to 1.5 MiB per book and discovers .txt files directly in /books (no nested folders).
  • 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.