kart-core: enable the Hori wheel under PlatformIO/CLI flashing

The bundled USBHost_t36 (v0.2) only claims Xbox One controllers whose VID/PID
are in a hardcoded table (Microsoft devices only). The Hori "Racing Wheel
Overdrive" (0F0D:0152) uses the standard Xbox One GIP interface and works once
its VID/PID is in that table — but without it JoystickController::claim() bails
and the wheel never enumerates. This is why the project previously had to flash
from the Arduino IDE (whose Teensyduino shipped a newer USBHost_t36 that knew
the wheel); every PlatformIO flash failed to see the wheel.

patch_usbhost_t36.py is a pre-build extra_scripts step that idempotently injects
the wheel's VID/PID into the framework's joystick.cpp before each build. The
Teensy can now be flashed from the CLI with the wheel working in production —
no Arduino IDE required. Verified on hardware: enum=1/type=3, axis 0 sweeps the
full ±32768 range and STEER set_cdeg tracks it proportionally to ±3000 (±30°),
streaming to the Steervo at 50 Hz (steer_link=1).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Ballistyxx

docs/traction-bringup.md

@@ -170,11 +170,21 @@ Shutdown: lift throttle → DRIVE button (disarm) → SAFE → THEN key off.
 
 ## Flashing workflow (important)
 
-- **Flash from the Arduino IDE**, not `pio … -t upload`. The CLI's auto-reboot
-  into the bootloader fails on this rig (the program button is hard to reach in
-  the enclosure), *and* — crucially — the wheel only re-enumerates on the
-  Teensy USB host after the IDE flow power-cycles it. A CLI soft-reboot leaves
-  the wheel dark.
+- **CLI flashing works** now (`pio … -t upload`, or the Teensy Loader GUI +
+  program button). The Hori wheel enumerates under the PlatformIO build because
+  **`patch_usbhost_t36.py`** (a pre-build `extra_scripts` step) injects the
+  wheel's VID/PID (`0F0D:0152`) into USBHost_t36's `JoystickController` table at
+  build time. Before that fix the bundled USBHost_t36 (v0.2) didn't know the
+  wheel, so it only worked when flashed from the Arduino IDE — whose Teensyduino
+  shipped a USBHost_t36 that already recognized it. That's why the IDE *used to*
+  be required; it no longer is.
+- **After any flash, the USB host needs a fresh connect to re-enumerate the
+  wheel.** A soft-reboot leaves an already-connected wheel dark, so either
+  **hot-plug the wheel** (unplug/replug at the Teensy USB-A host port) or
+  power-cycle the board after flashing. Confirm with `WHEELRAW` (`enum=1`,
+  `type=3`).
+- The program button can be hard to reach in the enclosure; the Teensy Loader
+  GUI waits for the press.
 - kart-core is a PlatformIO project; the IDE needs a flat sketch. Run
   **`firmware/kart-core/gen_arduino_sketch.sh`** to (re)generate
   `arduino/kart_core/` from the canonical `src/` + `lib/` + `firmware/common`

firmware/kart-core/patch_usbhost_t36.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# PlatformIO pre-build script: teach USBHost_t36's JoystickController about the
+# Hori "Racing Wheel Overdrive" (VID 0x0F0D / PID 0x0152).
+#
+# Why: the bundled USBHost_t36 (v0.2) only claims Xbox One controllers whose
+# VID/PID are in its hardcoded table (Microsoft devices only). The Hori wheel
+# uses the standard Xbox One GIP interface (class 0xFF/0x47/0xD0) and works fine
+# once its VID/PID is in that table — but without it, JoystickController::claim()
+# bails at the VID/PID check and the wheel never enumerates as a joystick. This
+# is exactly why the project previously HAD to flash from the Arduino IDE (whose
+# Teensyduino shipped a USBHost_t36 that knew the wheel). Patching here lets us
+# flash from PlatformIO/CLI with the wheel working in production.
+#
+# This runs before every build, finds the framework's joystick.cpp, and inserts
+# the table entry if it is missing (idempotent). It re-applies automatically
+# after a toolchain reinstall, and always patches the matching library version
+# (no vendored fork to drift from the core).
+
+import os
+
+Import("env")  # noqa: F821  (injected by PlatformIO)
+
+VID_PID = "0x0f0d, 0x0152"
+ENTRY = "    { 0x0f0d, 0x0152, XBOXONE, false },  // Hori Racing Wheel Overdrive (added by patch_usbhost_t36.py)\n"
+ANCHOR = "pid_vid_mapping[] = {"
+
+pkg_dir = env.PioPlatform().get_package_dir("framework-arduinoteensy")  # noqa: F821
+joystick_cpp = os.path.join(pkg_dir, "libraries", "USBHost_t36", "joystick.cpp")
+
+if not os.path.isfile(joystick_cpp):
+    print("patch_usbhost_t36: WARNING joystick.cpp not found at %s" % joystick_cpp)
+else:
+    with open(joystick_cpp, "r") as f:
+        src = f.read()
+    if VID_PID in src.lower():
+        print("patch_usbhost_t36: Hori wheel (0F0D:0152) already present")
+    else:
+        idx = src.find(ANCHOR)
+        if idx == -1:
+            print("patch_usbhost_t36: WARNING anchor %r not found; wheel may not "
+                  "enumerate (USBHost_t36 layout changed?)" % ANCHOR)
+        else:
+            insert_at = src.find("\n", idx) + 1
+            src = src[:insert_at] + ENTRY + src[insert_at:]
+            with open(joystick_cpp, "w") as f:
+                f.write(src)
+            print("patch_usbhost_t36: added Hori wheel (0F0D:0152) to "
+                  "JoystickController VID/PID table")

firmware/kart-core/platformio.ini

@@ -17,6 +17,10 @@ build_flags = -Wall -Wextra
 platform = teensy
 board = teensy41
 framework = arduino
+; Teach USBHost_t36 about the Hori wheel (0F0D:0152) before building, so the
+; Teensy can be flashed from PlatformIO/CLI with the wheel working — no Arduino
+; IDE needed. See patch_usbhost_t36.py.
+extra_scripts = pre:patch_usbhost_t36.py
 lib_deps =
   https://github.com/tonton81/WDT_T4.git