pi: GPIO-controlled theme switch

- apt dependencies (RPI.GPIO somehow needs to be installed from apt to work & re-establish uv venv with --system-site-packages
- GPIO 20 triggers mode switching (can link to a photodiode or just switch)

pi/backend/README.md

@@ -8,8 +8,12 @@ Python GPS and Arduino telemetry service for Smart Serow. Connects to `gpsd` and
 # Install uv if you haven't
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Install dependencies
+# Install system dependencies (GPIO)
+sudo apt install python3-rpi.gpio
+
+# Create venv with access to system packages, then sync
 cd pi/backend
+uv venv --system-site-packages
 uv sync
 ```
 
@@ -106,8 +110,43 @@ arduino = ArduinoService(port="/dev/ttyACM0", baudrate=115200)
 
 - **GPS**: If `gpsdclient` isn't installed or gpsd isn't running, generates fake GPS data
 - **Arduino**: If `pyserial` isn't installed or serial port unavailable, generates fake telemetry
+- **GPIO**: If `RPi.GPIO` isn't available, runs in mock mode (always returns default state)
 
-Both services run in stub mode for UI testing without hardware.
+All services run in stub mode for UI testing without hardware.
+
+## GPIO Setup
+
+The `gpio_service.py` handles physical switch inputs (e.g., theme toggle on GPIO20).
+
+### Known Quirks
+
+**Use apt-installed RPi.GPIO, not pip:**
+```bash
+sudo apt install python3-rpi.gpio
+```
+
+The pip version (`RPi.GPIO`) requires compilation with `python3-dev` headers. The apt package is pre-compiled and Just Works. The venv must be created with `--system-site-packages` to see it.
+
+**gpiozero doesn't work (TODO):**
+
+`gpiozero` is the "modern" GPIO library but has issues in this setup:
+- Requires a pin factory backend (`lgpio`, `rpigpio`, `pigpio`, or `native`)
+- `lgpio`/`rpi-lgpio` via pip needs `swig` to compile
+- `native` backend breaks under gevent monkey-patching (`select.epoll` missing)
+- May revisit if we need gpiozero-specific features
+
+**Software pull-up/down conflicts with external resistors:**
+
+If using an external pull-down resistor (especially high values like 1MΩ), disable the software pull:
+```python
+GPIO.setup(pin, GPIO.IN, pull_up_down=GPIO.PUD_OFF)
+```
+
+The Pi's internal pull-down (~50kΩ) will overpower high-value external resistors, causing unexpected voltage divider behavior.
+
+**Debouncing:**
+
+Physical switches/connectors need debouncing. Current implementation requires 15 consecutive identical readings (~750ms at 20Hz) before accepting a state change. Tune `required_consecutive` in `gpio_service.py` as needed.
 
 ## Deploy