diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c25bc29
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# Switch Pico Controller Bridge
+
+Raspberry Pi Pico firmware that emulates a Switch Pro controller over USB and a host bridge that forwards real gamepad input over UART (with rumble round-trip).
+
+## What you get
+- **Firmware** (`switch-pico.cpp` + `switch_pro_driver.*`): acts as a wired Switch Pro. Takes controller reports over UART1 and passes rumble from the Switch back over UART.
+- **Python bridge** (`controller_uart_bridge.py`): reads SDL2 controllers on the host, sends reports over UART, and applies rumble locally. Hot‑plug friendly and cross‑platform (macOS/Windows/Linux).
+- **Optional Rust bridge** (`fast_uart_bridge/`): higher‑performance alternative if the Python bridge has rumble latency.
+- **Colour override** (`controller_color_config.h`): compile‑time RGB overrides for body/buttons/grips as seen by the Switch.
+
+## Hardware wiring (Pico)
+- UART1 pins (fixed in firmware):
+  - **TX**: GPIO4 (Pico pin 6) → RX of your USB‑serial adapter.
+  - **RX**: GPIO5 (Pico pin 7) → TX of your USB‑serial adapter.
+  - **GND**: common ground between Pico and adapter.
+- Baud rate: **1,000,000** (default). Some adapters only handle 500,000; both bridges accept a `--baud` flag.
+- Keep logic at 3.3V; do not feed 5V UART into the Pico.
+
+## Building and flashing firmware
+Prereqs: Pico SDK + CMake toolchain set up.
+```sh
+cmake -S . -B build -DSWITCH_PICO_AUTOTEST=OFF -DSWITCH_PICO_LOG=OFF
+cmake --build build -j
+```
+Flash the UF2 to the Pico (e.g., bootsel + drag-drop or `picotool load`).
+Flags:
+- `SWITCH_PICO_AUTOTEST` (default ON in some configs): disable autopilot/test replay with `OFF`.
+- `SWITCH_PICO_LOG`: enable/disable UART logging on the Pico.
+
+### Changing controller colours
+Edit `controller_color_config.h` (RGB values) and rebuild; the Switch will show the new colours on reconnect.
+
+## Python bridge (recommended)
+Works on macOS, Windows, Linux. Uses SDL2 + pyserial.
+
+### Install dependencies with uv (or pip)
+```sh
+# from repo root
+uv venv .venv
+uv pip install pyserial pysdl2
+```
+- SDL2 runtime: install via your OS package manager (macOS: `brew install sdl2`; Windows: place `SDL2.dll` on PATH or next to the script; Linux: `sudo apt install libsdl2-2.0-0` or equivalent).
+
+### Run
+```sh
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+python controller_uart_bridge.py --interactive
+```
+Options:
+- `--map index:PORT` (repeatable) to pin controller index to serial (e.g., `--map 0:/dev/cu.usbserial-0001` or `--map 0:COM5`).
+- `--ports PORTS...` or `--interactive` for auto/interactive pairing.
+- `--baud 900000` (default 900,000; use `500000` if your adapter can’t do 900K).
+- `--frequency 1000` to send at 1 kHz.
+- `--sdl-mapping path/to/gamecontrollerdb.txt` to load extra SDL mappings (defaults to `controller_db/gamecontrollerdb.txt`).
+
+Hot‑plugging: controllers and UARTs can be plugged/unplugged while running; the bridge will auto reconnect when possible.
+
+### macOS tips
+- Ensure the USB‑serial adapter shows up (use `/dev/cu.usb*` for TX).
+- Some controllers’ Guide/Home buttons are intercepted by macOS; using XInput/DInput mode or disabling Steam’s controller handling helps.
+
+### Windows tips
+- Use `COMx` for ports (e.g., `COM5`). Auto‑detect lists COM ports.
+- Ensure SDL2.dll is on PATH or alongside the script.
+
+### Linux tips
+- You may need udev permissions for `/dev/ttyUSB*`/`/dev/ttyACM*` (add user to `dialout`/`uucp` or use `udev` rules).
+
+## Rust bridge (optional)
+Note: Rust toolchain not currently present in this setup. If you install Rust + SDL2 dev libraries, an experimental Rust bridge lives in `fast_uart_bridge/`.
+
+## Troubleshooting
+- **No input on Switch**: verify UART wiring (Pico GPIO4/5), baud matches both sides, Pico flashed with current firmware, Switch sees a “Pro Controller”.
+- **Rumble lag**: increase baud to 900,000 (default) or 1,000,000 if your adapter supports it; otherwise increase `--frequency`.
+- **Constant buzzing rumble**: the bridge filters small rumble payloads; ensure baud isn’t dropping bytes. Try lowering rumble scale in `controller_uart_bridge.py` if needed.
+- **Guide/Home triggers system menu (macOS)**: try different controller mode (XInput/DInput), disable Steam overlay/controller support, or connect wired.
+- **SDL can’t see controller**: load `controller_db/gamecontrollerdb.txt` (default), add your own mapping, or try a different mode on the pad (e.g., XInput).
diff --git a/mac_controller_uart_bridge.py b/controller_uart_bridge.py
similarity index 100%
rename from mac_controller_uart_bridge.py
rename to controller_uart_bridge.py