OpenPuck Architecture

This document is the map of the firmware. It explains what the device is, how the code is laid out, how data flows through it, and how to extend it. If you only read one thing before touching the code, read this.

What the device is

OpenPuck turns an nRF52840 Pro Micro into a clone of the Steam Controller 2 "puck" — the little USB radio dongle the controller pairs with. It does three jobs at once:

Speaks the puck's RF protocol to a real Steam Controller 2 ("Triton") over a bare-metal nRF radio (no SoftDevice, no BLE stack). It bonds controllers, transmits the host frame they reconnect on, and polls them for input at ~250 Hz.
Presents a USB personality to the host PC/console. The same controller input can be re-dressed as the Valve puck (for Steam), an Xbox 360 pad, a Switch controller, a PS5 DualSense, or a DS4 — selected at boot.
Exposes config surfaces — a WebUSB channel for the browser panel and a CDC serial console for debugging and the protocol reverse-engineering tooling.

It runs as a single-threaded loop() plus USB interrupt callbacks. There is no RTOS task switching in our code; concurrency is cooperative. The only preemption is the USB stack's ISR (which calls our HID report callbacks) and the radio's hardware events (which we poll, never interrupt on).

The big picture

                 ┌──────────────────────── host PC / console ────────────────────────┐
                 │  USB: one personality at a time (puck / xbox / switch / ps5 / ds4) │
                 └───────────────▲─────────────────────────────────▲──────────────────┘
                                 │ HID reports                      │ WebUSB / CDC
                                 │                                  │
        ┌────────────────────────┴─────────────┐        ┌──────────┴───────────┐
        │  controllers.h  (IController vtable)  │        │ webusb_config        │
        │  mode_*.cpp  — one per personality    │        │ serial_console       │
        └───────▲───────────────────▲───────────┘        └──────────┬───────────┘
   onReport45() │                   │ task()                        │ tunables / commands
        (push)  │                   │ (stream)                      ▼
        ┌───────┴───────────────────┴───────────────────────────────────────────┐
        │  rf_link.cpp  — operational puck protocol                              │
        │   • host-frame beacon  • connected poll (E7/E3)  • decode 0xF1 → g_in  │
        │   • mode-switch chord  • remote wakeup  • QoS channel hop  • stats     │
        └───────▲──────────────────────────────────────────▲────────────────────┘
                │ rfConfig / rfConnTx                       │ relay (haptics.cpp)
        ┌───────┴────────────┐                     ┌────────┴──────────┐
        │  radio.cpp         │   rf_diag.cpp ─────▶│  (RE/calibration  │
        │  nRF52 RADIO HW    │   (capture/sniff/   │   tooling, isolated)
        └────────────────────┘    replay/sweep)    └───────────────────┘

   shared state:  config (modes+tunables) · identity · bonds (slots+link) · triton (g_in) · gamepad_util

The central data flow is one direction for input:

radio RX → rf_link decodes report 0x45 into g_in (a PuckInput struct) → the active IController reads g_in and emits a host HID report.

and the reverse for haptics/config:

host OUTPUT report / WebUSB / CDC → queued into the haptic relay or a tunable → rf_link flushes the relay to the controller inside the poll cadence.

Module layout (`OpenPuck/`)

The Arduino build compiles every .cpp/.h in the sketch folder; the build command is unchanged (it still just points at the OpenPuck directory). Modules are layered low → high:

File	Responsibility
`OpenPuck.ino`	Entry point only: `setup()` builds the USB presentation for the persisted mode + arms the watchdog; `loop()` pumps each subsystem.
`config.{h,cpp}`	USB-mode definitions (`MODE_*`), persisted settings (`cfg.bin`), all runtime tunables, mode-switch persistence policy.
`identity.{h,cpp}`	Unique device serial from FICR DEVICEID; the puck `0x83` attribute blob.
`bonds.{h,cpp}`	The four bond slots (`g_slot`), bond persistence (`bonds.bin`), and the live link state (`g_connSlot`, `g_connReplyMs`).
`radio.{h,cpp}`	Bare-metal nRF52 `RADIO` register layer: PHY/CRC/whitening/address config (all live-tunable), `rfConfig()`/`rfSetAddr()`, the `rfrx`/`rftx` DMA buffers.
`triton.{h,cpp}`	The controller's native input: report `0x45` button masks (`TB_`) + decoders, and the shared decoded-input struct `g_in`*.
`gamepad_util.{h,cpp}`	Cross-mode helpers for building host reports: stick rescaling, Steam-trackpad → touch mapping, PlayStation-layout button packers.
`haptics.{h,cpp}`	Host→controller haptic relay queue + the watchdogs that stop a latched buzz; the OUTPUT-report capture ring.
`controllers.{h,cpp}`	The `IController` abstraction + the `mode → singleton` registry.
`puck_hid.{h,cpp}`	Steam/Lizard personality: the puck HID slot interfaces, the feature command channel (bond read/write, attributes), the auto-lizard decision, and the USB connection presentation.
`mode_lizard.{h,cpp}`	The lizard keyboard+mouse mapping (rides on the puck interface; not a standalone controller).
`mode_xinput.{h,cpp}`	Xbox personality: a custom TinyUSB XInput class driver + right-pad mouse + rumble relay.
`mode_switch_hori.{h,cpp}`	Switch HORIPAD personality (console-friendly, no handshake).
`mode_switch_pro.{h,cpp}`	Switch Pro personality: the full Nintendo USB handshake/subcommand state machine + SPI calibration + gyro.
`mode_ps5.{h,cpp}`	PS5 DualSense personality: gyro + split trackpad.
`mode_hidgyro.{h,cpp}`	DS4-layout generic HID gyro personality (motion-aware PC games).
`rf_link.{h,cpp}`	The operational puck protocol: host-frame beacons, connected-mode poll loop, `0xF1` decode + dispatch, chord detection, remote wakeup, QoS hopping, stats.
`rf_diag.{h,cpp}`	RF reverse-engineering / calibration tooling: raw capture, CRC-validating config sweeps, frame replay, address listen, scan-then-respond, live-session sniffer. Not used in normal operation.
`webusb_config.{h,cpp}`	The WebUSB binary config channel for the browser panel.
`serial_console.{h,cpp}`	The CDC single-letter debug command line.

The controller abstraction

IController (in controllers.h) is the seam that makes each USB personality a self-contained file. Exactly one controller is active per boot, chosen by g_usbMode via controllerFor() and stored in g_active.

class IController {
  virtual void begin();                                              // setup(): register USB interface(s) + IDs
  virtual void onReport45(const uint8_t* rep, bool fresh, uint8_t bodyTlen);  // RF input arrived (PUSH modes)
  virtual void task();                                               // loop(): streaming emit / handshake drains
  virtual bool isPuck() const;                                       // Steam/Lizard keep the boot CDC composite
};

Two emission styles:

Push modes (puck/lizard, xbox) build and send their host report inside onReport45(), driven by each decoded RF frame. They care about fresh (was the report new?) and the raw report bytes.
Stream modes (switch hori/pro, ps5, ds4) ignore onReport45() and instead emit at a fixed ~250 Hz cadence from task(), reading the latest g_in. This decouples the USB report rate from the RF rate, which is what those hosts expect.

setup() owns the shared USB lifecycle (detach, keep-or-clear the CDC composite based on isPuck(), set the per-mode serial suffix, attach); begin() only adds the interfaces specific to that controller.

Adding a new personality

Create mode_foo.{h,cpp} defining class FooController : public IController and a singleton extern FooController g_fooCtl;.
Implement begin() (set USBDevice VID/PID/strings, register your HID/vendor interface) and either onReport45() (push) or task() (stream) reading g_in.
Add a MODE_FOO constant in config.h (bump MODE_MAX), a MODE_SUFFIX letter in OpenPuck.ino, and a case MODE_FOO: return &g_fooCtl; in controllerFor() (controllers.cpp).

Nothing in rf_link, radio, or the other modes needs to change — g_in is your input contract.

Shared input state: `g_in`

rf_link decodes the controller's report 0x45 into a single PuckInput g_in (triton.h): buttons, sticks, triggers, both trackpad coordinates, and IMU (accel + gyro). Every controller reads from this one struct. (The pre-refactor firmware copied the same IMU/stick/button values into three separate per-mode global sets; that duplication is gone.)

The raw report bytes are still passed to onReport45() for the modes that forward them verbatim (the Steam path forwards the puck's raw 0x45 body untouched so Steam does its own trackpad smoothing).

The RF protocol, briefly

Full details are in docs/PROTOCOL.md; the register-level constants and their provenance are commented in radio.cpp and rf_link.cpp. The essentials:

PHY/framing (decoded from real-puck capture): Ble_2Mbit, big-endian, whitening off, 5-byte address "ibex", CRC16 0x11021/0xFFFF (address included). On-air address is the bit-reversed stored bytes.
Bonding/reconnect: we transmit a host frame on the rendezvous address (channel 2) carrying the bonded controller's UUIDs plus the session base/prefix/channel we want it to use. The controller filters by UUID and connects on the clean session channel (default 18).
Connected poll: we are the PTX/master. We announce host-awake (E7 00 00), then each poll cycle send E3 + a GET-report-0x45 sub-TLV; the controller replies with a 0xF1 input report containing TLVs (type 6 = the HID report 0x45). Cycling the ESB PID on the poll is what drains the controller's report queue at full rate (~400 new reports/s instead of ~60).
Haptics ride back as a SET sub-TLV inside the poll (haptics.cpp queues, rf_link flushes).

Timing & concurrency model

One cooperative loop(). Each subsystem's per-loop hook (g_active->task(), rfLinkTask(), hapticTask(), rfDiagTask(), webusbPoll(), serialConsolePoll()) must be non-blocking — anything that spins risks starving USB servicing.
The RF poll is busy-wait bounded: every radio wait (RWAIT_DISABLED, the RX windows) has a microsecond timeout and bails rather than hanging. A wedged radio must never freeze the loop.
A hardware watchdog (~8 s, armed in setup()) resets the chip if loop() ever stops feeding it — so a hang re-enumerates USB and re-inits RF on its own without a physical replug.
USB HID report callbacks (handleSet/handleGet in puck_hid, jcSet in mode_switch_pro) run in ISR context. They only stage data (into bond slots, the relay queue, or an SPSC reply ring); the actual sendReport happens later from task()/loop() where it's safe.
volatile marks state shared across the ISR/loop boundary (the relay queue, the Switch-Pro reply ring indices, the rumble level).

Persistence

Two files in the nRF52 internal LittleFS:

cfg.bin (config.cpp) — USB mode, tunables, chord assignments, persistence policy. A magic byte versions the layout; a mismatch falls back to clean defaults.
bonds.bin (bonds.cpp) — the four bond records.

Mode switches (chord, WebUSB, or CDC) call saveMode() then reboot so the next boot enumerates the right interface set. By default every cold boot returns to Steam mode unless "persist last mode" is enabled.

Config & debug surfaces

WebUSB (webusb_config.cpp): present in every mode; the browser panel reads a status blob and sets one-byte tunable fields or requests a mode switch.
CDC console (serial_console.cpp): present only in puck modes. Single-letter commands toggle RF diag modes, poke radio registers live, switch USB mode, edit tunables, inject test haptics, and dump capture history. It is an else-if chain, so the first matching letter wins — a couple of letters (C, H) appear twice and the second occurrence is currently unreachable (preserved verbatim from the original; worth cleaning up if those commands are ever needed).

RF reverse-engineering tooling

rf_diag.cpp holds everything used to discover the protocol — promiscuous capture, config sweeps, bit-exact replay, the session sniffer, scan-then-respond. The protocol is solved, so none of it runs in normal use, but it's kept compiled and reachable (via the CDC console) because it's the only way to re-derive parameters if a controller firmware update ever changes them. It depends only on radio and bonds, so it stays out of the operational path in rf_link.

ARCHITECTURE.md 14 KB Cronologia Originale