client-py — Python client

The computer-side program of the Arduino ESP32 TFT Terminal. It owns all application logic and drives the board over USB, sending command lines and reading answers.

Requirements

• Python 3.11+ on Linux.
• A flashed board (see ../server-esp32s3-rtft/) connected over USB.
• Dependencies: numpy, pyserial, claude-busy-monitor.

Running

The client is on PyPI as arduino-esp32-tft-terminal:

pipx install arduino-esp32-tft-terminal   # or: uv tool install arduino-esp32-tft-terminal
arduino-esp32-tft-terminal -h             # list options and apps
arduino-esp32-tft-terminal --demo         # cycle through all apps
arduino-esp32-tft-terminal --only cube    # run a single app

Run without installing: uvx arduino-esp32-tft-terminal --demo. From this directory: make install (= uv tool install .); for development, uv pip install -e . in a venv.

Layout

Package source lives under src/arduino_esp32_tft_terminal/:

• app/ — one module + class per app (quix.py is the template).
• lib/ — board communication: serial channel, command protocol, Board, Gfx, CLI args.
• cli.py — entry point (main()); registers the apps.
• config.py — runtime configuration (also exposed as CLI flags).

Writing a new app

1. Study src/arduino_esp32_tft_terminal/app/quix.py as a template.
2. Create a new module and class.
3. Register the class in src/arduino_esp32_tft_terminal/cli.py.

Development

All make targets run from this directory (next to pyproject.toml):

• make help — list targets.
• make lint / make format — ruff check + format-check / autofix.
• make build / make install — build the wheel / install the arduino-esp32-tft-terminal command.
• make publish-quality then make publish — PyPI release (token in keyring first).

See the top-level README and ../TODO.md for the wider toolchain.