claw-keyboard

Use claw-keyboard to discover and control USB keyboards that support the vendor HID protocol (UsagePage 0xFF60, Usage 0x61). Tested with LUXSWH R68pro. Supports RGB backlight, custom per-key LEDs, macros, key remapping, profile tuning, KLE layout rendering, and multi-keyboard management.

Quick start

• - claw-keyboard discover — scan for connected keyboards
• INLINECODE4 — show keyboard details (rows, cols, firmware, mode, RGB state)
• INLINECODE5 — set backlight to red
• INLINECODE6 — set brightness (0-255)
• INLINECODE7 — set lighting effect mode (0-20)
• INLINECODE8 — persist current settings to flash

Device selection

When multiple keyboards are connected, use --device <path> to target a specific one. Run discover to list available paths.

RGB control

• - claw-keyboard rgb status — show current brightness, effect, speed, color
• INLINECODE12 — set color by name (red, green, blue, cyan, purple, orange, yellow, white) or hue value (0-255)
• INLINECODE13 — set LED brightness
• INLINECODE14 — set lighting effect mode (0 = rainbow, 1 = solid, 2-20 = animations)
• INLINECODE15 — set animation speed (0 = slowest, 5 = fastest)
• INLINECODE16 — write current config to flash (avoid frequent calls — flash has limited write cycles)

Custom LED control

• - claw-keyboard led on <row> <col> — turn on a single LED at row/col position
• INLINECODE18 — turn off a single LED
• INLINECODE19 — turn off all LEDs
• INLINECODE20 — list currently lit LED positions
• INLINECODE21 — start onboard LED effect sync (keyboard reports LED data to PC)
• INLINECODE22 — stop onboard LED effect sync

Key mapping

• - claw-keyboard keymap read — dump current key layout (all layers)
• INLINECODE24 — show number of supported layers
• INLINECODE25 — read the 2-byte HID key value at a position
• INLINECODE26 — set a single key (4-digit hex, e.g. 0029 = Escape). Requires user confirmation — this changes a physical key binding on the keyboard.
• INLINECODE28 — write complete keymap from hex file. Requires user confirmation — this overwrites all key bindings.

Macro management

• - claw-keyboard macro list — show macro count, storage usage, and parsed macros
• INLINECODE30 — erase all macros. Requires user confirmation — this deletes all macros permanently.
• INLINECODE31 — hex dump of raw macro storage data
• INLINECODE32 — configure macros from action strings (replaces all existing macros). Requires user confirmation.

Profile parameters

• - claw-keyboard profile get — read profile parameters (debounce, TAP layer, sleep, power-down)
• INLINECODE39 — configure profile parameters (use --debounce, --tap, --sleep, --powerdown flags)

KLE layout tools

• - claw-keyboard kle info <file.json> — show parsed KLE layout summary
• INLINECODE45 — render KLE JSON layout to SVG

Other

• - claw-keyboard reset — factory reset keyboard. Requires explicit user confirmation — this permanently erases all settings, key mappings, and macros from the keyboard, restoring it to factory defaults. Only run when the user explicitly requests a factory reset.

Safety

The following commands modify keyboard hardware state and should only be run with explicit user confirmation. Never run these autonomously:

• - reset — factory reset (irreversible, erases everything)
• INLINECODE48 / macro set — erases or replaces all macros
• INLINECODE50 / keymap write — changes key bindings
• INLINECODE52 — writes to flash (limited write cycles)

Read-only commands (discover, info, rgb status, keymap read, macro list, profile get, kle info) are always safe to run.

Notes

• - The tool auto-discovers keyboards by scanning for HID interfaces with UsagePage 0xFF60 and Usage 0x61, then verifying via a challenge-response handshake.
• Not all keyboards expose the vendor HID interface. If discover finds nothing, the keyboard may not support this protocol.
• On macOS, you may need to grant HID access permission to the terminal application in System Settings > Privacy & Security > Input Monitoring.
• On Linux, you may need udev rules to access USB HID devices without root. Create /etc/udev/rules.d/99-claw-keyboard.rules with SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1a86", MODE="0666" and run sudo udevadm control --reload-rules.
• SHA256 checksums for all binaries are available in the SHA256SUMS file on the GitHub Releases page. Verify after downloading: shasum -a 256 -c SHA256SUMS.
• Use --json flag for machine-readable output.