docs: device-side HID facts from an independent shim, measured on firmware v0.6.1 - #7
Merged
Merged
Conversation
The lighting protocol document was written entirely from the host side: we write to the keyboard and never see what Codex sends to it. The micro-shim of maxxspotter/codex-micro-app takes the opposite position, presenting a synthetic Micro inside the Codex process, so it observes that half of the exchange. Its framing matches ours exactly, which corroborates the evidence matrix independently. Four value-level facts are new: the ACT06-ACT12 action key names, the normalised angles of v.oai.rad, act 2 for encoder notches, and the sys.version / device.status requests Codex sends to the device. All four are marked as read from a third-party source and never reproduced here, and three of them join the open questions. Where the shim's inferred field labels contradict our hardware measurements, the document keeps the measurement. Attribution added to Sources, for that project and for the MIT-licensed Stream Deck emulator it adapts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe English and French HID protocol research documents add independently sourced device observations, explicit verification caveats, unresolved measurement targets, and references to the MIT project and related emulator. ChangesHID protocol documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/research/hid-lighting-protocol.md (1)
147-151: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winPin both external citations to immutable source revisions.
The documents cite moving repository URLs. Add the commit SHA used for the observations and the access date in both language versions.
docs/research/hid-lighting-protocol.md#L147-L151: pin both cited repositories to their source commits.docs/fr/research/hid-lighting-protocol.md#L152-L157: use the same pinned commits and date.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/research/hid-lighting-protocol.md` around lines 147 - 151, Pin both cited repositories in docs/research/hid-lighting-protocol.md lines 147-151 to their immutable source commit SHAs and include the access date. Apply the same commit SHAs and date to the corresponding citations in docs/fr/research/hid-lighting-protocol.md lines 152-157, preserving the existing attribution and licensing context.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/research/hid-lighting-protocol.md`:
- Around line 147-151: Pin both cited repositories in
docs/research/hid-lighting-protocol.md lines 147-151 to their immutable source
commit SHAs and include the access date. Apply the same commit SHAs and date to
the corresponding citations in docs/fr/research/hid-lighting-protocol.md lines
152-157, preserving the existing attribution and licensing context.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 20bb1c00-d748-4cce-bf20-308012c0dda7
📒 Files selected for processing (2)
docs/fr/research/hid-lighting-protocol.mddocs/research/hid-lighting-protocol.md
The four facts borrowed from the micro-shim were recorded as third-party and unverified. Three are now measured here, by actuating every control by hand against scripts/lighting.mjs listen. The fourth, what Codex sends to the device, stays out of reach from the host side. ACT11 is not a key. One press of the wide bottom key emits ACT11 then ACT10, nested within 3 to 6 ms, three times out of three, with hold durations matching every other key in the capture. It is a single actuator on two matrix positions, which is why the shim has nothing to expose there. That also settles the count: 13 keycodes for 12 key actuators, plus the wheel press. The shim's joystick angles hold at the digit: 0.0107, 0.2388, 0.4894, 0.7614 for right, down, left, up. Two divergences appear against it — the device resets the angle to zero on release rather than repeating it, and the Agent keys carry no ag field, which the evidence matrix wrongly listed. The channel itself survives the vendor update from v0.4.1 to v0.6.1 unchanged. Dropped encoder notches join the open questions. Five slow notches produced four events while a fast burst produced five, so speed does not explain the loss and the 90 ms wheel calibration is not implicated; why an isolated slow notch disappears is unexplained. The direction of rotation in that capture rests on the operator's intent, not on an independent signal, so clockwise to ENC_CC still stands on the earlier hardware measurement rather than on this one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
thannous
changed the title
Two corrections to the section added in the previous commit, both from a raw capture that bypasses hid-frame.mjs and logs every 64-byte report. device.status was recorded as unreachable from the host side. It is not. The non-exclusive open broadcasts input reports to every reader, so the device's answers to Codex are visible here too, and the real payload arrives every 60.009 s carrying layer_index, which the roadmap's layer work can now read without a device-side vantage point. The earlier reasoning confused being unable to send Codex's requests with being unable to see the answers. The dropped-notch anomaly is retracted as a phenomenon. It rested on comparing event counts against detents counted by hand, a ground truth the operator judged unreliable afterwards, so no drop rate follows from those runs. What the raw capture does establish is that any such loss would not be ours: 38 reports, 30 notch events, zero unparseable lines. Settling the question needs an independent counter rather than a human one. The same capture also confirms the direction of rotation on a run whose direction was declared in advance: 30 ENC_CC and 0 ENC_CW for clockwise. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
docs/research/hid-lighting-protocol.mdwas written entirely from the hostside: we write to the keyboard. The
apps/micro-shim/ofmaxxspotter/codex-micro-app(MIT) takes the opposite position, patching
node-hidinside the Codex desktopprocess to advertise a synthetic Micro. Its framing matches ours exactly
(report
0x06, channel2, 61-byte chunks, same descriptor), whichcorroborates our evidence matrix independently.
It supplied four facts about values, where we had only field names. Rather
than record them as third-party hearsay, all four were measured on hardware
— every control actuated by hand, plus a raw probe bypassing
hid-frame.mjs—on firmware
v0.6.1.Results
ACT06fast …ACT12send,ACT11unexplainedACT11explained0, down0.25, left0.5, up0.750.0107,0.2388,0.4894,0.7614atd = 1act: 2on rotation,ENC_CLKon click, CW/CC swappedENC_CC, 0ENC_CWdevice.statuswithprofile_index/layer_indexACT11is not a keyOne press of the wide bottom key emits two keycodes, three times out of three:
Invariant order, 3–6 ms nesting, hold durations in line with every other key.
One physical actuator on two matrix positions — hence the shim's apparent
gap. That settles the count too: 13 keycodes for 12 key actuators, plus the
wheel press, which is how the README's 13 switches are composed.
Codex's own traffic is readable from the host
The non-exclusive open broadcasts input reports to every reader, so the
device's answers to Codex are visible here as well. The real
device.statusresponse arrives every 60.009 s:
{"version":"v0.6.1","profile_index":0,"layer_index":1,"battery":100,"is_charging":false}layer_indexreports the active layer — the roadmap's layer work can read itwith no device-side vantage point.
Two divergences from the shim
{a: 0, d: 0}, resetting the angle;the shim repeats the last angle with
d: 0.agfield: Agent keys emit{k, act}only; the evidence matrixwrongly listed
{k, act, ag}.Firmware
A vendor update from
v0.4.1tov0.6.1landed mid-investigation. Framing,RPC channel and
v.oai.thstatusare unchanged across it; the document recordsboth versions.
What is deliberately left open
Whether the device drops rotation notches at all is untested, and the
document says so. Earlier captures returned fewer events than intended, but the
ground truth was detents counted by hand and is not reliable, so no drop rate is
quoted. What the raw probe does establish is that any such loss would not be
ours: 38 reports, 30 notch events, zero unparseable lines.
Attribution
Sources credit the project and the MIT-licensed
Codex Micro Stream Deck emulator
its interception layer adapts, with an explicit note that no code from either is
reused — consistent with the existing "Legal framing, restated" section.
Verification
Documentation only, no code touched.
node scripts/check-doc-links.mjspasses(53 files).
🤖 Generated with Claude Code