feat(switch2_pro): Nintendo Switch 2 Pro Controller BLE emulation

[finger563]

Warning

Do not merge until h2zero/esp-nimble-cpp#443 is merged and released.
This PR bumps the esp-nimble-cpp submodule to a branch commit that carries the new
NimBLEServer::registerServicesFirst() API (needed for the exact GATT handle layout).
Once #443 is released, the submodule pin moves to the released commit and the manifest
dependency is bumped. Opening now for review.

Summary

Adds a new switch2_pro component that emulates a Nintendo Switch 2 Pro Controller
over BLE so a real Switch 2 console accepts it as a native controller — pairing,
encrypted link, continuous input streaming, reconnect, and wake-from-sleep. Built on
espp::BleGattServer (NimBLE); implements the reverse-engineered Nintendo custom GATT
interface (not HID-over-GATT) and the console's custom pairing handshake (not BLE SMP).

Status

• ESP32-C6 (and the other open-NimBLE-controller chips — C61/C2/H2): fully working,
  verified against a real console. Pairs (full battery + correct icon), streams input
  lag-free at ~62 Hz, buttons/sticks register on "Test Input Devices", and reconnect +
  wake-from-sleep work without re-pairing.
• ESP32-S3: builds and pairs, but does not yet stream input reliably. Its closed
  BTDM BLE controller degrades the encrypted stream under sustained notifications. This
  is documented as a known issue and is a fast-follow — see the component README.

What's included

• The switch2_pro component: pairing crypto (known-answer verified) + LTK injection,
  the exact GATT handle layout, the full console init/command sequence, NVS bond
  persistence, continuous input streaming with real (mbuf-pool-based) backpressure, and
  a wake_console() API.
• A small, additive ble_gatt_server enhancement: conn_params_update_callback.
• esp-nimble-cpp submodule bump for registerServicesFirst() (see the warning above).
• The opt-in SWITCH2_PRO_PATCH_NIMBLE_5MS controller patch (off by default; required
  only for reconnect/wake, since the console connects a bonded controller at a sub-spec
  5 ms interval) + a hardware-free smoke_test_5ms.py verifier.
• Docs (doc/en/ble/switch2_pro*, Doxyfile), CI matrix entries (C6 + S3), example, and
  DESIGN/README.

Testing

• On-hardware against a real Switch 2 (ESP32-C6): pairing, input, reconnect, wake — all
  working; input stays lag-free indefinitely at the console's 15 ms / ~62 Hz cadence.
• The example builds clean for both esp32c6 and esp32s3. The 5 ms patch is off by
  default so CI builds do not mutate the IDF install.

Attribution / scope

Interoperability only — no Nintendo or Espressif binaries are included. The pairing
"authentication" relies on a published fixed key (a possession check, not per-device
attestation). Protocol reverse-engineering credit: the community, principally
ndeadly/switch2_controller_research; the NimBLE 5 ms patch technique is adapted (MIT)
from zhantss/ESP32-BLE5-NSController-Emulator.

🤖 Generated with Claude Code

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

🟡 Changes recommended

There are several correctness/documentation mismatches and missing error-handling paths (paired-state semantics, pthread config error checking, PSA crypto status handling, and dependency/version alignment) that should be resolved before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new switch2_pro component to ESPP that emulates a Nintendo Switch 2 Pro Controller over BLE (custom GATT + custom pairing/crypto + continuous input streaming), plus a small ble_gatt_server enhancement to support the required GATT/connection-parameter behavior, along with docs and CI coverage for the new example.

Changes:

• Introduces the components/switch2_pro component (protocol constants, pairing crypto/self-test, GATT layout, advertising variants, bond persistence, and an input streaming task with backpressure).
• Extends espp::BleGattServer with a connection-parameters-update callback and an option to disable built-in DIS/BAS services (needed for strict handle layout emulation).
• Adds documentation pages, Doxygen inputs, and CI build matrix entries for the new example (ESP32-C6 + ESP32-S3).

File summaries

File	Description
doc/en/ble/switch2_pro.rst	New Sphinx page documenting the Switch 2 Pro BLE emulation component and 5 ms interval patch.
doc/en/ble/switch2_pro_example.md	Includes the example README into the docs site.
doc/en/ble/index.rst	Adds switch2_pro docs pages to the BLE docs toctree.
doc/Doxyfile	Adds Switch2Pro headers and example to Doxygen INPUT/EXAMPLE_PATH.
components/switch2_pro/tools/smoke_test_5ms.py	Hardware-free verifier for the 5 ms controller patch (disassembly-based).
components/switch2_pro/tools/patch_nimble_5ms.py	Opt-in patcher that edits ESP-IDF controller archives to accept 5 ms intervals.
components/switch2_pro/src/switch2_pro.cpp	Core implementation: GATT layout, pairing handling, bond persistence, advertising, and input streaming/backpressure.
components/switch2_pro/src/switch2_pro_pairing.cpp	Pairing crypto implementation using PSA Crypto API + self-test.
components/switch2_pro/README.md	Component README covering usage, 5 ms patch rationale, and known issues.
components/switch2_pro/Kconfig	Adds SWITCH2_PRO_PATCH_NIMBLE_5MS opt-in configuration.
components/switch2_pro/include/switch2_pro.hpp	Public API for espp::Switch2Pro and its configuration/streaming behavior.
components/switch2_pro/include/switch2_pro_report.hpp	Defines the packed Pro Controller 2 input report helper.
components/switch2_pro/include/switch2_pro_protocol.hpp	Protocol constants: UUIDs, command IDs, feature bits, manufacturer data, golden vectors.
components/switch2_pro/include/switch2_pro_pairing.hpp	Pairing crypto interface and self-test API.
components/switch2_pro/include/switch2_pro_motion.hpp	Embedded captured IMU motion sequence for optional replay.
components/switch2_pro/include/switch2_pro_flash.hpp	Embedded captured flash blocks and a simulated flash reader.
components/switch2_pro/idf_component.yml	Component Manager manifest for switch2_pro.
components/switch2_pro/example/sdkconfig.defaults.esp32c6	ESP32-C6-specific sdkconfig defaults (libc/toolchain workaround notes).
components/switch2_pro/example/sdkconfig.defaults	Example defaults for BLE/NimBLE tuning and patch guidance.
components/switch2_pro/example/README.md	Example walkthrough (pairing, streaming, wake/reconnect instructions).
components/switch2_pro/example/partitions.csv	Partition table enabling NVS for bond persistence.
components/switch2_pro/example/main/switch2_pro_example.cpp	Example app implementing BOOT-as-A and wake-on-press logic.
components/switch2_pro/example/main/CMakeLists.txt	Registers the example main component.
components/switch2_pro/example/CMakeLists.txt	Example project wiring for ESP-IDF build and components list.
components/switch2_pro/DESIGN.md	Design notes, protocol sources/attribution, and patch rationale.
components/switch2_pro/CMakeLists.txt	Component build registration + opt-in patch invocation at configure time.
components/switch2_pro/.gitignore	Ignores example build artifacts and generated sdkconfig files.
components/ble_gatt_server/src/ble_gatt_server_callbacks.cpp	Plumbs NimBLE conn-param-update event into server callbacks.
components/ble_gatt_server/include/ble_gatt_server.hpp	Adds conn-param-update callback typedef + togglable DIS/BAS creation/start/deinit.
components/ble_gatt_server/include/ble_gatt_server_callbacks.hpp	Declares the new onConnParamsUpdate callback override.
.github/workflows/build.yml	Adds CI build matrix entries for switch2_pro/example (C6 + S3).

Review details

• Files reviewed: 32/32 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Critical synchronization, lifecycle, handshake, and configuration issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (13)

Previously missed (12) — in code that hasn't changed since the last review.

components/switch2_pro/example/main/switch2_pro_example.cpp:31

• Initialization failures are ignored, including failure of the erase/retry path, so the example proceeds even though this component's advertised reconnect/wake behavior cannot persist a bond. Check the final NVS status before constructing the controller.
  components/switch2_pro/include/switch2_pro_report.hpp:82
• At the documented neutral input v == 0, this expression truncates 4095 / 2 to 2047, despite STICK_CENTER being 2048. Consequently every default/reset report encodes both sticks one count off center. Scale each half around STICK_CENTER so the endpoints remain 0/4095 and zero maps exactly to 2048.
  components/switch2_pro/src/switch2_pro.cpp:425
• The underlying API returns false when advertising cannot start, but that result is discarded and success is logged; wake_console() likewise returns true unconditionally. This makes callers believe the wake/discovery advertisement was issued when it was not. Return and propagate the start result through start_advertising(), advertise(), wake_console(), and initialization.
  components/switch2_pro/src/switch2_pro.cpp:445
• wake_console_on_boot_ is immutable and remains true after the first successful connection. With the default configuration, every later disconnect therefore immediately advertises the wake variant, and the persistent timer resumes doing so every five seconds, potentially waking a console the user just put to sleep. Use a one-shot wake-pending latch initialized at boot and clear/cancel it on successful connection, as the public configuration contract states.
  components/switch2_pro/src/switch2_pro.cpp:788
• Byte 0x0b is forced to the rumble-enabled value even when FEATURE_SELECT has not enabled rumble or has explicitly disabled it. This contradicts Pro2InputReport::reset() and the feature-state contract in the header, and sends a feature state different from the negotiated mask.
  components/switch2_pro/src/switch2_pro.cpp:853
• A failed ble_store_write_our_sec is logged at INFO as “ready,” and callers continue to mark/save the pairing even though the controller cannot answer the upcoming encryption request. Propagate this failure from inject_ltk() so finalization/reconnect can fail explicitly rather than reporting a usable bond.
  components/switch2_pro/src/switch2_pro.cpp:885
• The return values from nvs_set_blob and nvs_commit are ignored, yet the method logs success and updates the in-memory bond even when persistence failed. This makes pairing appear durable while reconnect/wake fails after reboot. Only publish success after both operations complete successfully.
  components/switch2_pro/tools/patch_nimble_5ms.py:205
• Targets with two controller archives are modified one at a time. If the first archive is patched and validation of the second archive fails, the tool exits after leaving the global ESP-IDF installation partially patched. Preflight every archive and create all backups before writing any archive, or roll back already-written archives on failure.
  components/switch2_pro/tools/smoke_test_5ms.py:99
• The smoke test documents exit code 2 for tool errors, but failures from ar raise CalledProcessError, missing tools raise OSError, and objdump failures are silently treated as empty output; the first two terminate with Python's exit code 1, which is documented as “unpatched.” Catch tool-execution failures and consistently return the indeterminate/error status 2.
  components/switch2_pro/DESIGN.md:43
• This states that every link is driven at 5 ms and cannot stream without the patch, contradicting the verified behavior documented elsewhere in this PR: fresh pairing and first-session streaming use 15 ms, while only bonded reconnect/wake starts at 5 ms. Clarify the distinction here because it changes whether the invasive patch is required.
  components/switch2_pro/include/switch2_pro.hpp:195
• This says on-change mode is the default, but Config::continuous_streaming defaults to true. Update the method documentation so generated API docs describe the actual default behavior.
  components/switch2_pro/include/switch2_pro_protocol.hpp:40
• The protocol comment declares this characteristic as WRITE, but build_gatt() intentionally creates it with NIMBLE_PROPERTY::WRITE_NR to match the real controller. Correct the public protocol documentation to avoid sending users toward the wrong GATT layout.

components/switch2_pro/DESIGN.md:85

• This says absolute handles are not strict and “we discover by UUID,” whereas the implementation and required registerServicesFirst() API are explicitly based on the console using fixed handles without discovery. Resolve this contradiction; it changes whether the exact GATT ordering is a protocol requirement or merely emulation fidelity.

Two proprietary primary services; contiguous handles matter for some console
firmwares (FW 2.0.0+ shifts them +8 for headset audio, so absolute-handle dependence
is not strict — we reproduce the map but discover by UUID).

• Files reviewed: 32/32 changed files
• Comments generated: 9
• Review effort level: Balanced