docs(dispatcher): in-depth guide to building custom modules/protocols

[finger563]

Summary

• Adds doc/en/dispatcher/custom_modules.rst, an in-depth, worked tutorial for building a custom module/protocol on top of espp::Dispatcher + espp::stream_frame, and pairing it with a browser web app over the USB vendor (WebUSB) transport.
• Wires the new page into doc/en/dispatcher/index.rst's toctree (and adds a pointer to it from the index blurb).
• Refreshes the module-id table in doc/en/dispatcher/dispatcher.rst, which was missing BLDC haptics (2), Telemetry (3), and MCP266 (6).

What the guide covers

1. Concepts — the stream_frame (framing) → Dispatcher (routing + discovery) → transport (USB vendor/CDC) layering, with a mermaid diagram and the current module-id table (cites components/dispatcher/README.md).
2. Writing a module — walks through espp::CoreDumpService (components/coredump/include/coredump_service.hpp) as the canonical five-part shape: module id, Msg enum, Config{send_fn}, build(), and the feed()/handle_frame() lock-then-send-unlocked pattern — then a minimal from-scratch "hello" PING/PONG module built purely from Dispatcher/stream_frame APIs (no new component/example file added).
3. Payload conventions — little-endian packing, put_u16/put_u32/get_u16/get_u32, the reply bit vs. type-value conventions used differently by CoreDumpService/Telemetry/MCP266, optional correlation ids, and adding a typed helper (Telemetry::put_f32, cited verbatim from components/telemetry/include/telemetry.hpp).
4. USB vendor transport — espp::UsbDevice::VendorFunction, write_vendor()/set_vendor_receive_callback(), Kconfig (CONFIG_TINYUSB_VENDOR_COUNT=1), the RX-queue-to-worker-task pattern from coredump_example.cpp, and the browser-side UsbTransport/crc32/buildFrame/StreamParser JS building blocks shared (verified via grep) across every shipped module console.
5. Discovery — ModuleInfo, set_device_info()/serve_discovery(), the describe() TLV payload layout, and how dispatcher_hub.html discovers and safely links a module's hosted webapp (safeAppName()).
6. A shipping checklist.

Every API name/signature/path was verified against the current source (dispatcher.hpp, stream_frame.hpp, coredump_service.hpp, usb_device.hpp, telemetry.hpp, mcp266_protocol.hpp, the example .cpp files, and dispatcher_hub.html) rather than invented.

Constraints followed

• Docs only — no C++ components added or modified.
• No new example/snippet source files; code blocks are either copied verbatim from existing files (cited) or a clearly-labeled from-scratch illustrative module built only from documented public APIs.
• Validated the three changed/added .rst files with a docutils structural parse (tables, section targets, cross-references) — clean, no warnings. A full Sphinx (esp-docs/Doxygen) build was not run (heavy toolchain not set up in this environment).

Test plan

• docutils.core.publish_doctree parse of all three .rst files — no warnings/errors (tables, backtick-underscore section links, directives all resolve).
• Full Sphinx docs build (not run here — see note above); reviewer with the doc/ toolchain set up may want to pip install -r doc/requirements.txt && cd doc/en && sphinx-build -b html . _build to render it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

🟡 Changes recommended

Unresolved documentation correctness and rendering issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds an in-depth Dispatcher custom-module/WebUSB tutorial, integrates it into the documentation, and updates module-ID references.

Changes:

• Added guidance on modules, framing, payloads, USB transport, and discovery.
• Linked the tutorial in Dispatcher documentation.
• Refreshed the module-ID table.

File summaries

File	Summary
doc/en/dispatcher/index.rst	Links the new tutorial.
doc/en/dispatcher/dispatcher.rst	Updates module-ID documentation.
doc/en/dispatcher/custom_modules.rst	Adds the comprehensive custom protocol and WebUSB guide.

Review details

Suppressed comments (6)

doc/en/dispatcher/custom_modules.rst:498

• The prose says this UsbTransport can be reused verbatim, but the block is not functional as shown: it has no constructor or reading = true, never discovers/assigns epIn and epOut or claims the interface, and therefore readLoop() exits while send() targets unset endpoints. Include the full implementation from dispatcher_hub.html, or label this block as abbreviated pseudocode/reference rather than a copyable building block.

   class UsbTransport {
     async open(anyDevice) {
       const options = anyDevice ? { filters: [] } : { filters: [{ vendorId: DEFAULT_VID }] };
       this.device = await navigator.usb.requestDevice(options);
       await this.device.open();

doc/en/dispatcher/custom_modules.rst:595

• The statement that every shipped module console re-runs discovery is not true for components/telemetry/web/telemetry.html: its WebUSB path sends a module-3 schema request and its parser ignores 0xFF discovery frames. This makes the guide's claimed cross-console behavior inaccurate; qualify the list or update telemetry before using it as an example.

Your module's own console additionally re-runs the same discovery query
itself on connect (every shipped console does) so it can confirm its module
is actually present on the device it just connected to, independent of
whether the user arrived via the hub or opened the console directly.

doc/en/dispatcher/custom_modules.rst:324

• This wiring calls usb.write_vendor() from the TinyUSB receive callback and ignores its bool result, but the hello payload is unconstrained (up to kMaxPayloadSize). In callback context write_vendor() fails immediately when the whole frame does not currently fit, and frames larger than the FIFO are streamed non-atomically; a large valid PING can leave a partial PONG on the wire or silently drop it. Either route RX/replies through a worker task, or cap the example to the configured FIFO and handle send failure.

   HelloModule hello({.send = [&](std::span<const uint8_t> frame) { usb.write_vendor(frame); }});
   dispatcher.register_module(
       hello_module::kModule, [&](const espp::stream_frame::Frame &f) { hello.handle(f); },
       {.name = "Hello", .app = "hello_console.html", .description = "PING/PONG demo module"});

doc/en/dispatcher/custom_modules.rst:299

• build() returns an empty vector when the payload exceeds stream_frame::kMaxPayloadSize, but this path passes that empty result directly to send_, producing no valid PONG for an oversized PING and hiding the failure. Reject or cap the input before building and guard the encoded frame before sending.

       send_(build(hello_module::Msg::Pong, std::span<const uint8_t>(
                                                reinterpret_cast<const uint8_t *>(text.data()),
                                                text.size())));

doc/en/dispatcher/custom_modules.rst:517

• This list is not accurate as written: ota_console.html is also a shipped module console, while the BLDC haptics source is components/bldc_haptics/example/webapp/index.html and the docs workflow only copies components/*/web/*.html; there is no hosted haptics_console.html for the hub link. Make this explicitly a hosted/partial list or fix the asset and ModuleInfo::app path before describing these as all shipped consoles.

Every shipped module console (``coredump_console.html``, ``mcp266_console.html``,
``can_bridge_console.html``, ``ds402_panel.html``, the BLDC haptics webapp,
``telemetry.html``) carries its own copy of the same three building blocks:

doc/en/dispatcher/custom_modules.rst:420

• 0x0d36 is already used by the coredump example (components/coredump/example/main/coredump_example.cpp:107), so it is not a distinct PID as this comment claims. A custom-module tutorial should not encourage reusing an existing example's PID; use an explicitly allocated application-specific PID or omit the assignment and tell the reader to allocate one.

   usb_cfg.pid = 0x0d36; // give your device a distinct PID so a webapp's WebUSB
                         // filter can find it specifically

• Files reviewed: 3/3 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]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.