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
• ⚠️ Automated implementation is complete; hardware smoke acceptance is pending. The last observed raw device was /dev/hidraw7 (root:root, mode 600); it later disappeared, so use the currently discovered path.

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.

Handoff Status

Implementation is complete on feature/impact80-effects at commit 62852e7. All task reviews and the final whole-branch code review passed. Automated checks pass:

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

The only open acceptance item is the live hardware smoke sequence. At the last attempt, discovery found the Impact 80 but HID access was denied; the device then disappeared. Do not assume /dev/hidraw7; run keyboard info after connecting the keyboard and use the path it reports.

Continue With Hardware

1. Check out feature/impact80-effects and build /tmp/wobkey.
2. Connect the Impact 80 and run /tmp/wobkey keyboard info.
3. Verify the current hidraw path and grant access using the system’s existing device-permission policy. If temporary access is explicitly chosen, record the original mode and restore it after testing.
4. Run the smoke commands in the Verification section above.
5. Confirm the default unsupported-zone warning, explicit Backlight effect, three-zone rgb info JSON, and final enabled state.
6. Record the hardware result here, rerun the automated checks, and only then merge the feature branch into main.

Do not stage graphify-out/ unless explicitly requested.