feat(keychron): support the G3 Air on Launcher's 8K Nordic protocol - #145
Merged
Merged
Conversation
The G3 Air's Launcher config (static/device/875876471/json/v3.json) forces the "8k_nordic" protocol: the 4K family's 0xff0a collection and framing with Orbital's DMS v2 settings blocks. Decoded from Keychron Launcher (main.be11320b2a72b61b.js, webpack module 20706, plus the lazy settings chunks for ranges): - sensor block 04/81/01, written as 04/bc/02: processing toggles, 20K FPS mode, lift-off (0.7, 1 and 2 mm), a signed angle, five X/Y DPI stages and their colours - system block 04/83/03, written as 04/98/04: sleep in seconds, debounce, and a six-gear polling table whose active byte is a gear index. From firmware 1.6.0 a second gear set for 2.4 GHz follows and the write grows to 04/a0/04 - buttons 03/81/01 and 03/85/04 with 4-byte codes (01 00 f0-f4 00 for mouse buttons, 07 00 0x 00 for DPI), profiles 02/82/02, and a save (0a/81/01) after every write, as Launcher does A polling change picks the gear that already holds the rate, else puts the rate in the active gear, which is what Launcher's assistant does. Fields Launcher never edits (full speed, lift-down, glass, quick response, wake sources, wheel reverse) are written back as read. The driver claims the wired G3 Air (0xd077) and the Ultra-Link 8K receivers 0xd05b and 0xd078 from Keychron's product list. A receiver has to answer the unrouted handshake with Keychron's or Lemokey's vendor ID in bytes 6-7 (Launcher's test for this protocol) before anything is written; bytes 8-9 name the paired mouse. When the mouse does not answer, readStatus returns the name alone. The 4K driver now leaves these ids alone and names the product ID when it meets an 8K Nordic receiver it does not know. Not yet tested on hardware. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
🎉 This PR is included in version 0.21.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
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
2 participants
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.
Summary
Adds
Keychron8kNordicHidClient(src/drivers/keychron/mouse-8k-nordic-hid.ts) for the Keychron G3 Air, which Keychron Launcher drives with its "8k_nordic" protocol. It shares the 4K family's 0xff0a collection and framing (64-byte report 0,0xa1 - sumchecksum, 0x40 on byte 0 routes through the receiver) and uses Orbital's DMS v2 settings blocks, with Keychron's polling gear table added to the system block.Read and write:
performanceMode), angle tuning (-90 to 90)When the mouse does not answer (asleep behind the receiver),
readStatusreturns the name withsettingsReady: false.Devices
"protocol": "8k_nordic"; Keychron's product API describes it as the 54L protocolThe receiver PIDs are the weakest part: Launcher never names them, it recognises the protocol only by the handshake. So the driver sends that handshake unrouted first and refuses to go on unless bytes 6-7 carry Keychron's (0x3434) or Lemokey's (0x362d) vendor ID; bytes 8-9 then name the paired mouse.
Keychron4kHidClientnow leaves these three ids alone, and its 8K Nordic error includes the product ID so an unknown receiver can be reported and added.Evidence
main.be11320b2a72b61b.js, module 20706: the 8k_nordic command classes (sensor and system blocks, buttons, profile switch, save, factory reset, version, receiver status)01 00 f0-f4 00, the same table the GearHub driver confirmed on hardware)resolvePollingRateLevel) and theUsgear sorterlauncher.keychron.com/static/device/875876471/json/v3.json: DPI 100-30000, rates up to 8000, LOD indexes 0/1/2 = 0.7/1/2 mm, buttons at indexes 0-4Assumptions and unknowns
Tested
npm run checkpasses: 1862 tests, including the registry overlap matrixnpm run check(241 tests) with this build linked locally, and the dev server with a simulated G3 Air behind a stubbednavigator.hid: it connected as "Keychron G3 Air" (wired, 1000 Hz, 76%) with every card rendered, and applying 8000 Hz, High lift-off, angle snapping, Forward to DPI Loop, 4 ms debounce, 30 minute sleep and profile 4 sent the expected packets and read backNot tested on a real G3 Air yet.
Related