feat(device): HID protocol from ChatGPT Work Louder kit - #35
Conversation
Document VID/PID, framing, and v.oai.* RPC from the bundled kit; probe by USB identity; map Agent Key frames to thstatus; opt-in hidapi claim via MICROBRIDGE_HID_CLAIM so ChatGPT can keep the device by default. Co-authored-by: Cursor <cursoragent@cursor.com>
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 9 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (20)
Comment |
There was a problem hiding this comment.
Pull request overview
Adds a best-effort HID implementation for Work Louder Codex Micro devices by introducing VID/PID probing, HID report framing, and compact JSON-RPC (v.oai.thstatus) packing, with live device claiming gated by MICROBRIDGE_HID_CLAIM=1 to avoid fighting ChatGPT Desktop by default.
Changes:
- Introduces
mb-deviceHID protocol modules (IDs, USB probe, framing, JSON-RPC helpers, optionalhidapiclaim backend). - Wires daemon state palette colors into
LedFrameso device RPC can carry explicit per-key colors. - Updates docs/README/INSTALL and CI/release workflows to reflect HID support and Linux build dependencies.
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| ROADMAP.md | Updates M2 status to reflect implemented VID/PID + HID framing + v.oai.thstatus packing and opt-in writes. |
| README.md | Updates project status text and crate map to reflect HID framing + opt-in claim. |
| INSTALL.md | Documents opt-in HID claim via MICROBRIDGE_HID_CLAIM=1 and “Detected-only” default behavior. |
| docs/device-hid.md | Replaces placeholder notes with detailed protocol notes (VID/PID, framing, JSON-RPC shapes, claim instructions). |
| crates/microbridged/src/state.rs | Adds palette→RGB packing and populates new LedFrame.key_colors. |
| crates/mb-device/src/rpc.rs | Adds compact JSON-RPC request building + notification parsing for Work Louder/OAI firmware. |
| crates/mb-device/src/probe.rs | Adds macOS system_profiler-based VID/PID presence probe without claiming HID. |
| crates/mb-device/src/lighting.rs | Maps LedFrame into v.oai.thstatus params and provides parse_rgb_hex. |
| crates/mb-device/src/lib.rs | Integrates probe/claim/RPC packing into HidDevice, adds key_colors to LedFrame, and updates default device selection. |
| crates/mb-device/src/ids.rs | Defines supported VID/PID set and usage page constants. |
| crates/mb-device/src/framing.rs | Implements 64-byte HID report framing and parsing for RPC/debug channels. |
| crates/mb-device/src/claim.rs | Adds optional hidapi-based claim, RPC write, and non-blocking notify polling. |
| crates/mb-device/Cargo.toml | Introduces hid feature (default) with optional hidapi dependency plus serde/serde_json. |
| Cargo.lock | Locks new dependencies (hidapi, pkg-config, build tooling deps). |
| .github/workflows/release.yml | Installs Linux hidapi build deps for release builds. |
| .github/workflows/ci.yml | Installs Linux hidapi build deps for CI. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| pub fn next_rpc_id(&mut self) -> u32 { | ||
| let id = self.rpc_id; | ||
| self.rpc_id = (self.rpc_id + 1) % 999; | ||
| if self.rpc_id == 0 { | ||
| self.rpc_id = 1; | ||
| } | ||
| id | ||
| } |
| fn next_rpc_id(&mut self) -> u32 { | ||
| #[cfg(feature = "hid")] | ||
| if let Some(claimed) = self.claimed.as_mut() { | ||
| return claimed.next_rpc_id(); | ||
| } | ||
| let id = self.rpc_seq; | ||
| self.rpc_seq = (self.rpc_seq % 998) + 1; | ||
| id | ||
| } |
|
|
||
| /// Build a JSON-RPC request body (UTF-8). `id` is clamped to `0..999`. | ||
| pub fn build_request(method: &str, params: Value, id: u32) -> String { | ||
| let id = id % 999; |
Push the pre-device work as far as it goes without the physical Micro. - `microbridgectl hid-capture [seconds]`: read-only observer that opens the Work Louder vendor interface and streams/decodes `v.oai.hid` + `v.oai.rad` events, then prints a fill-in-the-blank summary of the distinct key strings. This is the day-one tool that harvests the real input map in one pass. - `docs/hardware-bringup.md`: exact ordered runbook (detect -> capture -> map -> claim -> verify LEDs -> ownership) turning the "needs hardware" list into a ~15-minute checklist. Cross-linked from device-hid.md. - Characterization tests for `agent_key_index` / `joystick_from_angle` so the current guessed mapping is locked and regressions are visible before the real strings land. - `ACKNOWLEDGMENTS.md`: a sincere thank-you to OpenAI for keeping the Micro open (open protocol, non-exclusive HID, open tooling) — the choices that let this project exist. Linked from the README, non-affiliation preserved. Stops short of wiring live input-routing into the daemon loop: that needs the real key-string map (which hid-capture produces) to avoid shipping a broken deck. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Summary
Everything about the Codex Micro HID protocol that can be done without the physical device — mined from ChatGPT Desktop's bundled Work Louder kit — plus the tooling to make day-one-with-hardware fast.
Protocol (from
@worklouder/wl-device-kit, no hardware needed)0x303A/ PID0x8360), report framing, andv.oai.thstatuslighting packing.hidapiclaim (MICROBRIDGE_HID_CLAIM=1, non-exclusive so ChatGPT Desktop coexists).LedFrame; docs/CI updated forlibudev.Pre-device tooling
microbridgectl hid-capture [seconds]— read-only observer that streams/decodesv.oai.hid+v.oai.radevents and prints a fill-in-the-blank summary of the distinct key strings. Harvests the real input map in one pass.docs/hardware-bringup.md— exact ordered runbook (detect → capture → map → claim → verify LEDs → ownership).agent_key_index/joystick_from_angleso the guessed mapping is locked before real strings land.Also
ACKNOWLEDGMENTS.md— a sincere thank-you to OpenAI for keeping the Micro open (open protocol, non-exclusive HID, open tooling), linked from the README with non-affiliation preserved.Deliberately stops before wiring live input-routing into the daemon loop: that needs the real key-string map (which
hid-captureproduces) to avoid shipping a broken deck.Test plan
cargo test --workspacecargo clippy --workspace --all-targets -- -D warnings(default +--no-default-features)cargo fmt --all --check0x303A/ PID0x8360microbridgectl hid-capture→ record realv.oai.hidstrings in the bring-up runbookMICROBRIDGE_HID_CLAIM=1and verify Agent Key LEDs