199 lines
6.5 KiB
Markdown
199 lines
6.5 KiB
Markdown
# 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. Copy UTF-8 plain-text files ending in `.txt` into it. Copy
|
|
[`examples/sample.txt`](examples/sample.txt) for the first test.
|
|
|
|
The resulting card must look like this:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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 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.
|