macOS WebHID: DualSense Bluetooth gyro fusion produces wrong orientation (USB-vs-BT report layout)

[petegordon]

Type: Bug / hardware-verification · Status: Observed (2026-06-19)

Context

macOS Electron build, WebHID input spine (#80). Per-vendor 3D model + sensor-fusion gyro is the product. DualSense over Bluetooth on macOS produces incorrect fused orientation — motion data is arriving (fusion runs), but the result is wrong. Failure is in parsing/fusion, not enumeration.

Observed (Fri 2026-06-19)

• DualSense over BT on macOS → fused orientation swings/jerks hard side to side ("side-to-side fusing"), observed during petegordon/tandemonium gameplay.
• Same DualSense over USB → correct.

Primary hypothesis

The DualSense BT report (ID 0x31, ~78 bytes, CRC-tailed) has different gyro/accel byte offsets than the USB report (ID 0x01, ~64 bytes). The macOS BT path is likely reading USB offsets, or mis-detecting the report ID, feeding wrong raw values into fusion.

The "side to side" symptom sharpens this: it matches a documented failure mode in the driver where a wrong gyro offset reads an accelerometer axis as gyro. From playstation-driver.js (near init() / the probe): "the gyro tie-breaker can flip to the wrong (off-by-2) neighbour — which reads an accel axis as gyro and makes steering jerk hard side to side." So this looks like an offset misread on the BT path, not a sign-flip or scale error — gravity bleeding into a gyro axis yaws the model side to side as the controller tilts.

Sub-hypothesis (most likely macOS-specific culprit)

macOS/IOKit may include or strip the leading report-ID byte in the inputreport event's data DataView differently than Windows/Linux. The driver's gyro/accel offsets are computed assuming the report-ID byte is absent from event.data (offsets are relative to event.data byteOffset 0, with event.reportId carried separately). If macOS's WebHID/IOKit path includes the report-ID byte (or shifts by the BT counter/header byte differently), every gyro/accel field lands one byte off on the BT path — reading an accel axis as gyro / shifted values into fusion, which matches "data arrives but orientation is wrong" and the side-to-side swing.

Relevant code (where a fix would land)

packages/core/src/drivers/playstation-driver.js:

• _defaultGyroOffset() — USB DS5 = 15, BT DS5 (0x31) = 16 (+1); DS4 BT (0x11) = +2. The +1/+2 "counter byte" shift is already modeled — but assumes a fixed platform convention for whether the report-ID byte is in event.data.
• _probeConfig() — BT DS5 path: { reportId: 0x31, baseOffset: 1, candidates: [16, 15, 17] }.
• _probeImuOffset() — the at-rest IMU-offset probe (scores candidate offsets by at-rest accel magnitude ≈ 8192 = 1g). Key gap: per its own docstring it "Only runs on USB report 0x01 today. BT branch differs … punted for now." So on BT the driver falls back to the documented default offset with no at-rest self-correction — meaning a macOS-specific 1-byte shift would go uncaught, exactly the scenario here.

Suggested investigation

1. Capture a raw macOS BT 0x31 report and dump event.data.byteLength + the first ~24 bytes alongside event.reportId. Compare against the USB 0x01 capture to see whether the report-ID byte is present in event.data on macOS (i.e. is byteLength ~77 vs ~78?), and whether the CRC tail is present.
2. Confirm the gyro/accel offsets against the macOS byte layout: at rest, accel magnitude at the chosen offset should be ≈ 8192 (1g) and gyro ≈ 0. If the best at-rest offset is documented ± 1/± 2, that's the smoking gun for the report-ID-byte convention. The side-to-side symptom predicts an axis where gravity (≈8192) is currently being integrated as rotation.
3. Extend the IMU-offset probe to the BT branch (_probeImuOffset over 0x31/0x11), so the at-rest magnitude check auto-corrects a platform-specific offset shift instead of trusting the static default. The probe-then-add-baseOffset logic already generalizes; only the USB-only guard needs lifting.
4. Add a committed macOS-BT 0x31 fixture under packages/core/test/fixtures/ (mirroring the existing GameSir USB capture) and a parseReport/offset-probe unit test, so this is regression-covered cross-platform.

Acceptance

• DualSense over BT on macOS yields fused orientation matching USB (axis directions, scale, stability) — no side-to-side swing.
• Cross-platform: no regression for DualSense BT on Windows/Linux, or DS4 BT.
• Covered by a committed macOS-BT fixture + test.

_{Symptom confirmed from in-game observation during petegordon/tandemonium play, 2026-06-19.}

[petegordon]

First-pass fix up as a draft: #84.

What it changes: the IMU-offset probe already runs on BT (the "USB-only" docstring was stale) — the gap was the selection in init() trusting the documented offset on accel magnitude alone. A byte-shifted offset reads an accel axis as a gyro axis, so its at-rest "gyro" sits near gravity (~8192) → fusion integrates gravity as rotation → side-to-side swing. #84 adds an accel-as-gyro guard that rejects the default when its at-rest gyro is pinned near gravity and recovers the clean candidate (~1g accel + near-zero gyro), while preserving the off-by-2 still-pad protection. 89 tests pass.

It's a draft pending a real macOS + DualSense BT capture — I can't run that hardware here, so this targets the documented accel-as-gyro failure mode rather than a confirmed root cause.

How to capture (≈1 min, in the running macOS Electron app)

1. Connect the DualSense over Bluetooth, set it on a flat surface (still).
2. Open DevTools console (Cmd+Shift+I) and reconnect/re-init the controller so the probe runs.
3. Copy the two lines it logs:

   PlayStation IMU probe scan (report 0x31, NNB): g=16 accel≈… gyro≈…  |  g=15 …  |  g=17 …
   PlayStation IMU probe bytes (bluetooth 0x31, len=NN, baseOffset=1): 31 .. .. …
   

4. For a baseline, do the same over USB (report 0x01) and copy those two lines too.

What the capture tells us

• len=NN on BT vs USB → whether macOS includes the leading report-ID byte (a +1 length/offset shift is the prime suspect).
• The per-offset accel≈/gyro≈ table → which offset is actually clean (~8192 accel, ~0 gyro). If that's 16/15/17, PlayStation BT IMU: guard against accel-as-gyro offset shift (macOS side-to-side) (#83) #84 already recovers it; if it's outside that set (e.g. 18), it's a one-line widen of the candidate list.

Paste those four lines here and I'll confirm the fix or adjust the candidates, then flip #84 out of draft.

---

Generated by Claude Code