Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,9 @@ jobs:
target: esp32s3
- path: 'components/gamepad_map/example'
target: esp32s3
- path: 'components/gamepad_map/webapp_example'
target: esp32s3
command: 'IDF_COMPONENT_MANAGER=0 idf.py build'
- path: 'components/gfps_service/example'
target: esp32s3
- path: 'components/gps/example'
Expand Down
17 changes: 17 additions & 0 deletions .github/workflows/gamepad_map_tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ name: Gamepad map host test
# file round trip)
# - components/hid-rp/test/hid_rp_report_map_host_test.cpp (the runtime
# report map + Gamepad / Keyboard / Mouse decoders the map is fed from)
# - components/gamepad_map/test/gamepad_map_protocol_host_test.cpp (the
# GamepadMapService wire protocol codec)
# - components/gamepad_map/web/test/gamepad_map_codec_test.js (the web
# console's copy of that codec, with node)
# Runs whenever either component, or what they store / log with, changes.

# Minimal token scope: build + run tests, never writes.
Expand All @@ -22,6 +26,7 @@ on:
- "components/logger/**"
- "components/format/**"
- "components/base_component/**"
- "components/stream_frame/**"
- ".github/workflows/gamepad_map_tests.yml"
push:
branches:
Expand All @@ -34,6 +39,7 @@ on:
- "components/logger/**"
- "components/format/**"
- "components/base_component/**"
- "components/stream_frame/**"
- ".github/workflows/gamepad_map_tests.yml"
workflow_dispatch:

Expand Down Expand Up @@ -73,3 +79,14 @@ jobs:
components/gamepad_map/test/gamepad_map_host_test.cpp components/logger/src/logger.cpp \
-o gamepad_map_host_test
./gamepad_map_host_test
- name: Build and run gamepad_map_protocol_host_test
run: |
g++ -std=c++23 -Wall -Wextra -Werror \
-I components/gamepad_map/include -I components/stream_frame/include \
components/gamepad_map/test/gamepad_map_protocol_host_test.cpp \
-o gamepad_map_protocol_host_test
./gamepad_map_protocol_host_test
- name: Run the web console codec test
run: |
node --version
node components/gamepad_map/web/test/gamepad_map_codec_test.js
2 changes: 2 additions & 0 deletions components/dispatcher/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ protocols and examples use these ids by default:
| 7 | System info / reboot (`espp::SystemService`) | `espp.system` v1 |
| 8 | Heap / task monitor (`espp::MonitorService`) | `espp.monitor` v1 |
| 9 | Windowed desktop (`espp::DesktopService`) | `espp.desktop` v2 |
| 10 | VL53L5CX ToF console (`espp::Vl53l5cxService`) | `espp.vl53l5cx` v1 |
| 11 | Gamepad map (`espp::GamepadMapService`) | `espp.gamepad_map` v1 |
| 0xF0–0xFE | reserved (meta) | — |
| 0xFF | capability discovery | — |

Expand Down
3 changes: 2 additions & 1 deletion components/dispatcher/web/test/apps_registry_test.js
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,8 @@ for (const p of pages) {
// constants are declared as `<PREFIX_>PROTOCOL = "id", <PREFIX_>PROTOCOL_VERSION = n`
// with the same (possibly empty) prefix, e.g. OTA_PROTOCOL / OTA_PROTOCOL_VERSION
// or the bare PROTOCOL / PROTOCOL_VERSION pair
for (const m of src.matchAll(/\b[A-Z0-9_]*PROTOCOL\s*=\s*"(espp\.[a-z0-9.-]+)"/g)) idsInScript.add(m[1]);
// (ids may contain `_`, e.g. espp.gamepad_map, as the generator's PROTOCOL_RE allows)
for (const m of src.matchAll(/\b[A-Z0-9_]*PROTOCOL\s*=\s*"(espp\.[a-z0-9._-]+)"/g)) idsInScript.add(m[1]);
for (const id of idsInScript) assert.ok(protocols.some((p) => p.id === id), rel + ": script defines protocol " + id + " not declared in espp-protocols");
// and the version it implements: every declared protocol must have its pair
for (const pr of protocols) {
Expand Down
1 change: 1 addition & 0 deletions components/dispatcher/web/test/resolve_module_id_test.js
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ const consoles = [
"components/system/web/system_console.html",
"components/desktop/web/desktop.html",
"components/vl53l/web/vl53l5cx_console.html",
"components/gamepad_map/web/gamepad_map_console.html",
];
const hub = "components/dispatcher/web/dispatcher_hub.html";

Expand Down
2 changes: 1 addition & 1 deletion components/gamepad_map/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
idf_component_register(
INCLUDE_DIRS "include"
REQUIRES base_component format hid-rp persistent_data
REQUIRES base_component dispatcher format hid-rp persistent_data stream_frame task
)
46 changes: 41 additions & 5 deletions components/gamepad_map/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,9 @@ whatever comes next (an emulated USB controller, an emulator's input).
- [Rules](#rules)
- [Profiles](#profiles)
- [From a HID gamepad](#from-a-hid-gamepad)
- [Web console](#web-console)
- [Host test](#host-test)
- [Example](#example)
- [Examples](#examples)

<!-- markdown-toc end -->

Expand All @@ -32,6 +33,7 @@ whatever comes next (an emulated USB controller, an emulator's input).
| `espp::GamepadMap` | Stick dead zones plus a list of rules; `apply()` maps one state to another |
| `espp::GamepadProfiles` | A default map plus one map per controller type, saved in a file |
| `espp::to_gamepad_state()` | A state from a `hid_rp::GamepadReport` (`gamepad_state_hid_rp.hpp`) |
| `espp::GamepadMapService` | Serves a `GamepadProfiles` store to the web console (dispatcher module 11) |

Everything except `GamepadProfiles` is header-only plain data with no
allocation in `apply()`, so it can run on every report.
Expand Down Expand Up @@ -122,15 +124,49 @@ if (decoder.update(report_id, payload, report)) // BLE: the ID comes out of ba
send(map.apply(espp::to_gamepad_state(report)));
```

## Web console

`espp::GamepadMapService` serves a `GamepadProfiles` store over any framed byte
stream (WebUSB vendor, Web Serial CDC...) through an `espp::Dispatcher`. Its
protocol is `espp.gamepad_map` v1 on module 11 by default
(`include/detail/gamepad_map_protocol.hpp` is the wire spec). The hosted
[Gamepad Map Console](https://esp-cpp.github.io/espp/apps/gamepad_map_console.html)
uses it to edit the maps and to show the controller's input before and after
mapping, live. The application tells the service about the controller and feeds
it the input:

```cpp
espp::GamepadMapService service({.send = send_to_host,
.profiles = &profiles,
.on_active_map_changed = [&](const espp::GamepadMap &m) {
std::lock_guard lock(map_mutex);
active_map = m; // the console changed this controller's map
}});
dispatcher.register_module(service);

{
std::lock_guard lock(map_mutex); // the callback above may run on another thread
active_map = service.set_controller(vid, pid, name); // on connect; clear_controller() on disconnect
}
// for every report:
service.publish_input(raw, mapped); // a 32-byte copy under a lock; never sends
```

The INPUT stream ends by itself when the host stops renewing it
(`Config::stream_lease`), so a closed browser tab does not leave it running.

## Host test

`test/gamepad_map_host_test.cpp` covers the rule semantics, validation, the
hid-rp conversion (with a real BLE gamepad's descriptor) and the profile store's
file round trip. The build command is at the top of the file, and CI runs it in
file round trip. `test/gamepad_map_protocol_host_test.cpp` checks the wire
protocol against golden encodings. The build command is at the top of the file, and CI runs it in
`.github/workflows/gamepad_map_tests.yml` together with the hid-rp report-map
test.

## Example
## Examples

The [example](./example) decodes a BLE gamepad report, remaps it, and stores
per-controller profiles on a LittleFS partition.
- [example](./example) decodes a BLE gamepad report, remaps it, and stores
per-controller profiles on a LittleFS partition.
- [webapp_example](./webapp_example) serves the profiles over USB (WebUSB /
Web Serial) to the Gamepad Map Console, with a demo controller.
4 changes: 4 additions & 0 deletions components/gamepad_map/idf_component.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ maintainers:
documentation: "https://esp-cpp.github.io/espp/input/gamepad_map.html"
examples:
- path: example
- path: webapp_example
tags:
- cpp
- Component
Expand All @@ -18,7 +19,10 @@ dependencies:
idf:
version: '>=5.0'
espp/base_component: '>=1.0'
espp/dispatcher: '>=1.0'
espp/format: '>=1.0'
# GamepadReport::lt / rt / capture and GamepadDecoder::set_combine_controls()
espp/hid-rp: '>=1.4.6'
espp/persistent_data: '>=1.0'
espp/stream_frame: '>=1.0'
espp/task: '>=1.0'
Loading
Loading