qmk-rgb/PLAN.md

Wobkey RGB CLI — Implementation Plan

Status

• ✅ Go module initialized (github.com/wobkey/rgb)
• ✅ HID discovery and QMK v12 Raw HID transport implemented
• ✅ Impact 80 three-zone lighting control (Logo, Backlight, Side) implemented
• ✅ Zone selection with default-all and explicit --zone behavior implemented
• ✅ Zone-aware effect names, aliases, and target resolution implemented
• ✅ Per-zone rgb info JSON implemented
• ✅ All RGB subcommands implemented (effect, brightness, speed, color, mode, enable, disable, info)
• ✅ Automated tests, vet, formatting, and build verification
• ⚠️ Hardware smoke discovery succeeds, but the connected Impact 80 is blocked by root-only /dev/hidraw7 permissions

Zone-Aware Lighting Semantics

The rgb command has a persistent --zone flag with the values logo, backlight, and side. Without the flag, commands target Logo, Backlight, and Side in that order. With the flag, commands target exactly one zone.

An unknown effect name fails before the device is opened. An effect that is unsupported by an explicitly selected zone also fails before the device is opened. For a default all-zone request, supported zones receive the command and unsupported zones are skipped with a warning on stderr.

The exact effect examples are:

wobkey rgb effect breathing
wobkey rgb effect rainbow_moving_chevron
wobkey rgb effect rainbow_moving_chevron --zone backlight
wobkey rgb brightness 160
wobkey rgb speed 2
wobkey rgb color 00ff00

Effect Families

Logo and Side share the complete seven-name family:

none, wave, fixed_wave, spectrum, breathing, light, shutdown

Backlight uses these complete 46 names, with IDs 0–45:

none, solid_color, alphas_mods, gradient_up_down, gradient_left_right,
breathing, band_sat, band_val, band_pinwheel_sat, band_pinwheel_val,
band_spiral_sat, band_spiral_val, cycle_all, cycle_left_right,
cycle_up_down, cycle_out_in, cycle_out_in_dual, rainbow_moving_chevron,
cycle_pinwheel, cycle_spiral, dual_beacon, rainbow_beacon,
rainbow_pinwheels, flower_blooming, raindrops, jellybean_raindrops,
hue_breathing, hue_pendulum, hue_wave, pixel_flow, digital_rain,
solid_reactive, solid_reactive_wide, solid_reactive_multiwide,
solid_reactive_cross, solid_reactive_multicross, solid_reactive_nexus,
solid_reactive_multinexus, splash, multisplash, solid_splash,
solid_multisplash, starlight, starlight_dual_hue, starlight_dual_sat,
riverflow

Backlight ID 39 is multisplash; ID 41 is the distinct solid_multisplash name. Compatibility aliases are off, breathe, rainbow, rainbow_wave, solid, and the legacy static alias; aliases resolve independently for each zone.

Verification

Run the complete automated check set from the repository root:

gofmt -w .
go test -count=1 ./...
go vet ./...
go build -o /tmp/wobkey ./cmd/wobkey/
git diff --check

Run the hardware smoke sequence when the Impact 80 is available:

/tmp/wobkey keyboard info
/tmp/wobkey rgb effect breathing
/tmp/wobkey rgb effect rainbow_moving_chevron
/tmp/wobkey rgb effect rainbow_moving_chevron --zone backlight
/tmp/wobkey rgb info
/tmp/wobkey rgb color 00ff00
/tmp/wobkey rgb disable
/tmp/wobkey rgb enable

The expected result is three selected zones, warnings only for unsupported default targets, a working explicit Backlight command, per-zone JSON from rgb info, and a final enabled state. Record device or permission failures without changing unrelated code.

Open Issues

Cross-Platform HID Backends

The current transport is Linux-specific (/dev/hidraw* and Linux syscalls). macOS and Windows require platform-specific HID backends or a shared library.

Hardware Environment

Hardware smoke tests require the Impact 80 to be connected and the user to have permission to access its hidraw device. In the acceptance environment, /dev/hidraw7 is root:root with mode 600, so discovery succeeds but all HID opens fail with permission denied. No persistent profile storage or EEPROM save command is included.