Skip to content

feat(gamepad_map): gamepad button / axis remapping with per-controller profiles; hid-rp decoder for BLE HID gamepads - #918

Open
finger563 wants to merge 3 commits into
mainfrom
feat/gamepad-map
Open

finger563 wants to merge 3 commits into
mainfrom
feat/gamepad-map

Conversation

@finger563

Copy link
Copy Markdown
Contributor

Description

Two parts. Together they let a controller bridge (BLE HID gamepad -> USB controller) or an emulator handle any HID gamepad and remap its controls.

hid-rp: GamepadDecoder for BLE HID gamepads

A BLE HID gamepad in its "Android" mode reported over BLE (here a ShanWan BSP-D8, from finger563/esp-usb-ble-hid#39) did not decode usefully:

  • The layout heuristic picked DirectInput (it has a hat and 16 buttons). These pads, the Xbox Wireless controller over BLE and espp's own GamepadInputReport all use the Android numbering.
  • The decoder had no analog triggers.
  • The left stick was always folded into the d-pad.

Changes:

  • Layout::Android maps 1 south, 2 east, 4 west, 5 north, 7/8 L1/R1, 9/10 L2/R2, 11 select, 12 start, 13 home, 14/15 L3/R3. It is picked when the descriptor reports its triggers as Simulation-page Brake / Accelerator. layout_name() gives the name for logs.
  • Analog triggers: GamepadReport::lt / rt (0..32767) come from Brake / Accelerator, or from Rx / Ry when Z / Rz are the right stick, as on the DualShock.
    • This also fixes DualShock-style pads, where Rx (the left trigger) used to overwrite the right stick's X.
    • GamepadReport::capture reports consumer Record (Share / Capture) on its own.
  • decode(report_id, payload, out) is for transports that carry the report ID out of band, such as BLE's Report Reference.
  • update() / reset() are a stateful variant. They keep the latest report of each ID and decode them together, so a pad that splits its state over several reports (consumer keys in one, the pad in another) does not reset half of it on each report.
  • set_combine_controls(false) turns off the emulator conveniences: the left stick as d-pad, the triggers as L2/R2, and Capture as Home. A pass-through needs every control to report only itself.
    • The default stays on, so existing users (the USB host Tab5 example, emulators) see no change. The one exception is Record, which now also sets capture.
  • Precomputed roles: each field's role is worked out once in the constructor, so decode() only switches on it.
  • The host tests use:
    • the BSP-D8's real descriptor, from the issue
    • espp's Xbox BLE descriptor
    • a DualShock-style descriptor
    • the multi-report update()

gamepad_map (new component)

  • espp::GamepadState names buttons by position (south / east / west / north, L1..R3, select / start / home / capture, d-pad, four paddles), so a map means the same on Xbox, Nintendo and PlayStation pads.

    • Sticks are -32767..32767 with Y pointing down.
    • Triggers are 0..32767.
  • espp::GamepadMapRule / espp::GamepadMap combine radial stick dead zones with four kinds of rule:

    • button -> button
    • axis -> button (threshold, signed for direction)
    • button -> axis (value)
    • axis -> axis (scale in percent; negative inverts)

    How the rules apply:

    • A rule's source is moved, not copied, unless the rule sets KEEP_SOURCE. A NONE target removes the source.
    • Several rules can feed one target: buttons are OR-ed, and axis contributions are summed and clamped.
    • Controls without a rule pass through, so an empty map is the identity.
    • apply() does not allocate.
    • Presets cover swaps, inversion, stick swap, stick <-> d-pad and triggers <-> buttons.
    • valid() checks a map that comes from outside. apply() skips out-of-range rules regardless, so a bad map can never index outside the state.
  • espp::GamepadProfiles holds a default map plus one GamepadProfile per controller type.

    • Profiles are keyed by vendor / product ID, falling back to the name when both are 0.
    • Every change is validated and saved atomically with PersistentData. Invalid or duplicate stored entries are dropped on load.
    • The configured default map applies until the file is first written, which is how an application can migrate older settings into a map.
  • to_gamepad_state() (in gamepad_state_hid_rp.hpp) converts a hid_rp::GamepadReport, and a fmt formatter is provided for GamepadState.

  • Also included: an example (esp32s3, LittleFS), docs, a host test, and the component added to the host library headers.

  • CI: a new gamepad_map_tests.yml workflow runs the gamepad_map host test and the hid-rp report-map host test, which no workflow ran before.

The component's manifest floors espp/hid-rp at >=1.4.6 (the new decoder fields), so the registry job for this new component can only resolve after that release.

Motivation and Context

finger563/esp-usb-ble-hid#39 asks for BLE gamepads other than the Xbox Wireless controller. More generally, the BLE -> USB bridge and the emulators all need per-controller button / axis remapping that users can configure. This is the shared core.

Follow-ups:

  • a vendor-protocol service plus a web panel to edit maps, with a live input view for binding a control by pressing it
  • the bridge reading each pad's report map and PnP ID at connect

How has this been tested?

  • components/gamepad_map/test/gamepad_map_host_test.cpp and components/hid-rp/test/hid_rp_report_map_host_test.cpp pass with g++ 16, -std=c++23 -Wall -Wextra -Werror.
  • The gamepad_map test is also clean under clang++ -std=c++20 -fsyntax-only.
  • components/gamepad_map/example builds for esp32s3 with no warnings.
  • components/usb_host/tab5_example, a decoder user, builds for esp32p4.

There's an unrelated, pre-existing failure: hid_rp_gamepad_host_test fails one check (bytes[9] == 0) on main as well. That test isn't in CI, and it will be fixed separately.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation Update
  • Hardware (schematic, board, system design) change
  • Software change

Checklist:

  • My change requires a change to the documentation.
  • I have added tests to cover my changes.
  • I have updated the documentation accordingly.
  • I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build github action.
  • All new and existing tests passed.
  • My code follows the code style of this project.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU

…r profiles; hid-rp decoder for BLE HID gamepads

hid-rp (hid-rp-report-map.hpp, GamepadDecoder):
- Layout::Android (1 south, 2 east, 4 west, 5 north, 7/8 L1/R1, 9/10 L2/R2,
  11 select, 12 start, 13 home, 14/15 L3/R3), picked when the descriptor
  reports Simulation-page Brake / Accelerator triggers: BLE HID gamepads,
  the Xbox Wireless controller over BLE, espp's own gamepad report.
- Analog triggers (GamepadReport::lt / rt) from Brake / Accelerator, or
  Rx / Ry when Z / Rz are the right stick (DualShock); Rx no longer
  overwrites the right stick's X on such pads. Capture (consumer Record)
  is reported on its own (GamepadReport::capture).
- decode(report_id, payload) for transports that carry the report ID out of
  band (BLE), and a stateful update() / reset() that decodes the latest
  report of every ID together, so a pad that splits its state over several
  reports does not reset half of it on every report.
- set_combine_controls(false) turns off the emulator conveniences (left
  stick as d-pad, analog triggers as L2/R2, Capture as Home) for a
  pass-through; on by default, so existing users see no change.
- Per-field roles are worked out once in the constructor; layout_name().

gamepad_map (new component):
- GamepadState: buttons by position (south / east / west / north ...),
  sticks -32767..32767 (Y down) and triggers 0..32767.
- GamepadMapRule / GamepadMap: radial stick dead zones plus button ->
  button, axis -> button (threshold), button -> axis (value) and axis ->
  axis (scale / invert) rules; sources are moved unless KEEP_SOURCE,
  unmapped controls pass through, apply() does not allocate. Presets for
  swaps, inversion, stick <-> d-pad and triggers <-> buttons; valid().
- GamepadProfiles: a default map plus one map per controller type
  (vendor / product ID, name when both are 0), validated and saved
  atomically with PersistentData.
- to_gamepad_state() from hid_rp::GamepadReport, fmt formatter, example
  (esp32s3, LittleFS), docs, host test; CI workflow gamepad_map_tests.yml
  also runs the hid-rp report-map host test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

✅Static analysis result - no issues found! ✅

…eference, parameters no longer shadow pressed() / profile())

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

rtps memory footprint (QEMU, esp32)

Deltas in parentheses are against main @ 597ba27 (run 44213624598): a bigger size or a smaller free heap than the baseline's is a cost of this change.

librtps.a in the image (bytes, idf.py size-components)

embedded host host_large
flash code 162,076 (+0) 163,438 (+0) 163,846 (+0)
flash data 1,272 (+0) 1,272 (+0) 1,272 (+0)
DRAM (.data + .bss) 126 (+0) 126 (+0) 126 (+0)
IRAM 0 (+0) 0 (+0) 0 (+0)

engine objects, sizeof (bytes; the Domain is allocated from the heap at start())

object embedded host host_large
rtps::Domain (holds every pool below) 99,208 (+0) 569,968 (+0) 3,156,208 (+0)
rtps::Participant 34,304 (+0) 42,736 (+0) 52,720 (+0)
rtps::StatefulWriter 2,528 (+0) 2,960 (+0) 6,416 (+0)
rtps::StatelessWriter 1,872 (+0) 2,256 (+0) 3,792 (+0)
rtps::StatefulReader 1,968 (+0) 2,008 (+0) 2,104 (+0)
rtps::StatelessReader 1,960 (+0) 2,000 (+0) 2,096 (+0)
espp::RtpsParticipant 608 (+0) 608 (+0) 608 (+0)

embedded: heap by stage (free bytes; a cost is a negative delta)

stage internal delta internal low-water mark largest internal block PSRAM delta
boot 220,543 (+0) 217,468 (+0) 131,072 4,191,540 (+0)
started 159,255 (+0) -61,288 157,192 (+0) 73,728 4,025,508 (+0) -166,032
endpoints 138,891 (+4) -20,364 136,532 (+4) 69,632 4,091,048 (+0) +65,540

embedded: heap after each host-driven step (free bytes; deltas against the previous row; the pools are preallocated, so a peer costs little heap - the low-water mark shows the transients)

step internal delta internal low-water mark largest internal block PSRAM delta
baseline 132,811 (+4) 129,084 (+68) 69,632 4,091,048 (+0)
+1 remote participant (no match) 132,679 (+4) -132 124,004 (-160) 69,632 4,091,048 (+0) +0
+1 more remote participant (no match) 132,655 (+16) -24 124,004 (+172) 69,632 4,091,048 (+0) +0
+1 remote participant with a matched publisher 132,635 (+16) -20 122,792 (+1,448) 69,632 4,091,048 (+0) +0
after a service call 132,611 (+8) -24 95,304 (+16) 69,632 4,091,048 (+0) +0
after an action goal 131,559 (+16) -1,052 78,304 (-3,312) 69,632 4,091,048 (+0) +0
after one 30 KB sample 131,559 (+20) +0 74,668 (-12) 69,632 4,060,836 (+0) -30,212
all peers gone 131,551 (+8) -8 74,668 (-12) 69,632 4,060,836 (+0) +0

host: heap by stage (free bytes; a cost is a negative delta)

stage internal delta internal low-water mark largest internal block PSRAM delta
boot 219,311 (+0) 216,236 (+0) 131,072 4,191,540 (+0)
started 129,819 (-264) -89,492 128,248 (-256) 69,632 3,617,960 (+0) -573,580
endpoints 109,359 (+88) -20,460 107,000 (+88) 69,632 3,617,960 (+0) +0

host_large: the participant did not start on this target - the profile does not fit (panicked while the engine was being built - internal RAM exhausted building the Domain's mutexes (the first error logged: [RtpsTransport/E][3.436]: Failed to create valid UDP socket for port 7401)); its sizeof is in the table above, the boot heap below

host_large: heap by stage (free bytes; a cost is a negative delta)

stage internal delta internal low-water mark largest internal block PSRAM delta
boot 219,311 (+0) 217,600 (+0) 131,072 4,191,540 (+0)
started n/a
endpoints n/a

The QEMU memory suite on b06606a (run); the full numbers are the run's rtps-memory artifact.

gamepad_map:
- Radial dead zone no longer caps the stick's magnitude: a square-gate
  corner (both axes full) stays a full diagonal instead of ~23170 per axis.
- A trigger inverted onto a trigger reads from full (32767 - v) instead of
  clamping to "never pressed".
- Documented that a map's rules apply in parallel to the controller's
  input (a source used twice feeds both targets).
- GamepadProfiles: names stored cut to 64 bytes (and matched cut); the
  PersistentData size limit is derived from max_profiles so whatever save()
  writes, load() accepts; a file that cannot be read is set aside as
  <file>.unreadable (load_error()) instead of being overwritten by the next
  change; stored maps are sanitized rule by rule (an invalid rule no longer
  drops its whole profile), unmatchable profiles (no VID, PID or name) are
  dropped; has_profile() / profile_count(); one in-memory copy of the store.
- Example / README: check the parsed report map before using it; the
  example's expected output matches what it prints.

hid-rp GamepadDecoder:
- Button 13 is Home on the Xbox-style and DirectInput layouts (the PS
  button of a DualShock / DualSense).
- update() returns false (and leaves `out` alone) for a report with no
  gamepad control (e.g. the Xbox battery report) instead of re-sending the
  last state.
- Each field's report slot is computed once (no per-field search per report).

Tests for all of the above; the documented host-test commands work pasted
into a shell again (line continuations + -Wno-comment); the host test
workflow also runs on logger / format / base_component changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant