USB2BLE is experimental ESP32-S3 firmware that bridges USB HID controllers to Bluetooth LE gamepad personas, with a Web Serial configurator for runtime mapping profiles.
The current launch candidate is focused on a practical Thrustmaster Flight Pack demo path: T.16000M stick over USB, TWCS throttle over USB, and TFRP pedals through the TWCS RJ12 port via a powered HooToo USB hub.
- Enumerates USB HID devices on the ESP32-S3 USB host path.
- Captures HID descriptors, raw reports, parsed summaries, and normalized input.
- Maps normalized input to BLE Generic Gamepad and Xbox-style report personas.
- Runs an explicit live bridge mode that publishes USB-derived BLE reports.
- Imports, saves, loads, and starts runtime JSON configs over the serial/Web Serial-compatible protocol.
- Provides a Vite/TypeScript Web Serial configurator and ESP Web Tools flashing surface.
This project is in public alpha status. It has real target, host, browser, soak, and self-hosted browser-game smoke evidence for the refined Generic Flight Pack path, but it is not a polished consumer product.
Evidence is the source of truth. Start with docs/EVIDENCE_INDEX.md. The continuously updated, CI-built firmware is published as the latest release and by the GitHub Pages flasher. The named v0.1.0-alpha remains the original public prerelease milestone.
- ESP32-S3 target build and flashable firmware packaging in CI.
- Powered hub attach/detach identity, HID descriptor capture, raw report capture, HID summary, and normalized input.
- Practical RJ12 Flight Pack axis labels for TWCS throttle, TFRP rudder, and both toe brakes.
- Runtime config import/save/load across an actual board reset.
- Chrome Web Serial configurator smoke: connect, load schemas/catalog/config,
import Flight Pack Generic, save, load, and
START_CONFIGURED. - Refined target-side Generic and Xbox mapping/report encoding for the practical RJ12 topology.
- Refined Generic BLE live bridge host visibility in Chrome Gamepad API:
Generic
z/rx/ry/rzappear as browser axesA2/A3/A4/A5. - Refined Generic 300-second live bridge soak in Chrome.
- Narrow self-hosted browser game/app smoke using the refined Generic profile.
- Xbox BLE identity/report publishing and macOS pairing/input witness for the existing Xbox slice.
- Broad game/app compatibility.
- External or native game compatibility.
- iPhone compatibility.
- Xbox host-visible refined Flight Pack mapping.
- Broad BLE bond persistence and reconnect hardening beyond the witnessed Quest 3 Generic Flight Pack path.
- Final product-quality deadzone/calibration feel.
- Broad host/browser support beyond the checked-in witnesses.
- Simultaneous three-separate-USB Flight Pack streaming.
| Area | Evidence-backed status |
|---|---|
| ESP32-S3 target | Target build, flash packaging, serial control plane, BLE witnesses |
| HooToo SHUTTLE HT-UC001 powered hub | Powered-hub topology witnessed |
| Thrustmaster T.16000M stick | USB input, mapping, BLE Generic path witnessed |
| Thrustmaster TWCS throttle | USB input, RJ12 pedal host path, refined Generic mapping witnessed |
| Thrustmaster TFRP pedals via TWCS RJ12 | Rudder and toe-brake labels plus refined Generic mapping witnessed |
| Other hubs/controllers/hosts | Not broadly claimed |
./scripts/validate_no_hardware.sh
./scripts/check_target_build.shOn Windows, run the no-hardware checks through PowerShell:
.\scripts\validate_no_hardware.ps1The no-hardware validation is safe without an ESP32-S3, HOTAS, browser chooser, Bluetooth pairing, or physical controls. The target preflight requires the Xtensa/ESP-IDF toolchain.
./scripts/check_target_build.sh
./scripts/build.sh
./scripts/flash.sh --port <PORT>The Pages build publishes the Web Serial configurator and ESP Web Tools manifest for the latest CI firmware artifact:
- Web configurator and flasher: https://alexoviedo.github.io/T2/
- Firmware manifest: https://alexoviedo.github.io/T2/firmware/manifest.json
python3 tools/configure_board.py --port <PORT> preset flight-pack-generic
python3 tools/serial_command.py --port <PORT> GET_CONFIG_STATUS START_CONFIGURED GET_BRIDGE_STATUSThe Web Serial configurator can perform the same config import/save/load/start flow in Chrome or Edge on desktop. A public GitHub Pages desktop witness on Alex's Windows PC covers Flight Pack Xbox import/save/load/start-configured and soft-reset config persistence; web flashing and mobile Web Serial are separate, unproven paths.
# Serial discovery/probe
python3 tools/serial_command.py --port <PORT> GET_INFO GET_STATUS GET_USB_STATUS LIST_USB_DEVICES
# Config persistence witness
python3 tools/config_persistence_witness.py --port <PORT> --reboot-after-save
# Browser Gamepad API witness server
python3 tools/gamepad_witness/server.py
# Refined Generic live bridge soak
python3 tools/refined_generic_live_bridge_soak.py --port <PORT>
# Self-hosted browser game/app smoke
python3 tools/browser_game_compat_witness.py --port <PORT>Generated witness artifacts go under target/. Only concise reviewed evidence
summaries should be committed under docs/milestone-evidence/.
crates/usb2ble-*- Rust firmware, protocol, mapping, HID, persona, and storage crates.scripts/- build, flash, package, and validation helpers.tools/- serial, config, calibration, soak, browser witness, and evidence validation helpers.web/- Web Serial configurator and firmware flashing UI.docs/- runbooks, evidence, release notes, public claims, and handoff docs..github/workflows/ci.yml- host checks, target preflight, firmware artifact packaging, release upload, and Pages deployment.
- Development workflow
- Configuration
- Project status handoff
- Compatibility matrix
- Game/app compatibility witness standard
- Release checklist
- Public claims guide
USB2BLE is experimental firmware. BLE HID behavior can vary by host OS, browser, Bluetooth cache state, game engine, and controller profile. Do not infer broad compatibility from a single witness. Do not use this project where input loss, unexpected controls, or firmware faults could create safety risk.
USB2BLE is licensed under the Apache License 2.0 (Apache-2.0). See
LICENSE.