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
• claw-keyboard info — show keyboard details (rows, cols, firmware, mode, RGB state)
• claw-keyboard rgb color red — set backlight to red
• claw-keyboard rgb brightness 128 — set brightness (0-255)
• claw-keyboard rgb effect 1 — set lighting effect mode (0-20)
• claw-keyboard rgb save — 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
• claw-keyboard rgb color <name|hue> — set color by name (red, green, blue, cyan, purple, orange, yellow, white) or hue value (0-255)
• claw-keyboard rgb brightness <0-255> — set LED brightness
• claw-keyboard rgb effect <0-20> — set lighting effect mode (0 = rainbow, 1 = solid, 2-20 = animations)
• claw-keyboard rgb speed <0-5> — set animation speed (0 = slowest, 5 = fastest)
• claw-keyboard rgb save — 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
• claw-keyboard led off <row> <col> — turn off a single LED
• claw-keyboard led clear — turn off all LEDs
• claw-keyboard led list — list currently lit LED positions
• claw-keyboard led sync-start — start onboard LED effect sync (keyboard reports LED data to PC)
• claw-keyboard led sync-stop — stop onboard LED effect sync

Key mapping

• claw-keyboard keymap read — dump current key layout (all layers)
• claw-keyboard keymap layers — show number of supported layers
• claw-keyboard keymap get <layer> <row> <col> — read the 2-byte HID key value at a position
• claw-keyboard keymap set <layer> <row> <col> <keyvalue> — set a single key (4-digit hex, e.g. 0029 = Escape). Requires user confirmation — this changes a physical key binding on the keyboard.
• claw-keyboard keymap write <file> — 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
• claw-keyboard macro clear — erase all macros. Requires user confirmation — this deletes all macros permanently.
• claw-keyboard macro dump — hex dump of raw macro storage data
• claw-keyboard macro set <actions> [<actions>...] — configure macros from action strings (replaces all existing macros). Requires user confirmation.
  • Action format: tap:<keycode>, press:<keycode>, release:<keycode>, delay:<ms> separated by commas
  • Example: claw-keyboard macro set "press:0xE0,tap:0x06,release:0xE0" (Ctrl+C)

Profile parameters

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

KLE layout tools

• claw-keyboard kle info <file.json> — show parsed KLE layout summary
• claw-keyboard kle render <file.json> — 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)
• macro clear / macro set — erases or replaces all macros
• keymap set / keymap write — changes key bindings
• rgb save — 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.