qmk-rgb/PLAN.md

Wobkey RGB CLI — Implementation Plan

Status

• ✅ Go module initialized (github.com/wobkey/rgb)
• ✅ git init + AGENTS.md + README.md
• ✅ Directory structure: cmd/wobkey/, internal/device/, internal/hid/, internal/rgb/, internal/via/
• ✅ Pure-Go HID layer: reads /dev/hidraw* + parses /sys/bus/hid/devices/*/uevent (no cgo, no libudev)
• ✅ Keyboard discovery: detects Impact 80 (VID 0x36B0, PID 0x309F) and Rainy 75
• ✅ All 8 RGB subcommands implemented (effect, brightness, speed, color, mode, enable, disable, info)
• ✅ go build ✅ go vet ✅ go test ./internal/rgb/... (18/18 pass) ✅ gofmt clean
• ✅ VIA protocol: Enable handshake + Set/Get commands
• ✅ keyboards.json with decimal VID/PID

Open Issues

1. Linux HID Permissions — BLOCKS ALL FUNCTIONAL TESTING

All /dev/hidraw* are root:root 600. The tool can't open them as paul.

Action for next session:

1. Run: sudo chown root:adm /dev/hidraw* && sudo chmod 660 /dev/hidraw*
2. Or: apply the udev rule from README.md for a permanent fix
3. Verify: ls -la /dev/hidraw* shows group adm with rw for group
4. Run: /tmp/wobkey keyboard info — should output JSON with the Impact 80

2. Test the Keyboard — Needs Step 1 First

Once permissions are fixed:

1. /tmp/wobkey keyboard info — verify Impact 80 is discovered
2. /tmp/wobkey rgb disable — test disable
3. /tmp/wobkey rgb enable — test enable
4. /tmp/wobkey rgb info — verify it returns JSON state
5. /tmp/wobkey rgb effect rainbow — test effect switching
6. /tmp/wobkey rgb brightness 200 — test brightness
7. /tmp/wobkey rgb color ff0000 — test red color

3. Color Command — RGB to HSV Conversion

Current implementation is a hack: it treats R→hue, G→saturation with no actual RGB→HSV conversion.

Action:

• Add rgbto.hsv() conversion in internal/rgb/effects.go
• R=red channel → HSV H, G=green → HSV S, B=blue → use as V when setting static
• This makes wobkey rgb color ff0000 actually red instead of unpredictable

4. QMK rgblight Parameter Numbers

Current code uses hardcoded numbers that need verification against QMK spec:

• rgb.Mode (param 0) ✅
• rgb.Brightness (param 1) ✅
  
• rgb.Speed (param 2) ✅
• rgb.Enable (param 3) ✅
• Hue = 26, Sat = 27 — unverified
• Effect param = 48, effect_sw = 49, bright_set = 50 — missing

Action:

• Add all QMK rgblight param constants to internal/rgb/effects.go
• Map them properly

5. Test Coverage

Currently only internal/rgb/effects_test.go has tests (18/18 pass).

Action:

• internal/device/device_test.go — test LoadKeyboards (parse JSON file)
• internal/hid/hid_test.go — test parseHex and splitLines helper functions
• internal/via/protocol_test.go — mock-based tests for protocol methods

6. Cross-Compile Binaries

The pure-Go HID layer should work on macOS/Windows, but needs verification.

Action:

• GOOS=darwin GOARCH=amd64 go build -o dist/wobkey-darwin-amd64 ./cmd/wobkey/
• GOOS=darwin GOARCH=arm64 go build -o dist/wobkey-darwin-arm64 ./cmd/wobkey/
• GOOS=windows GOARCH=amd64 go build -o dist/wobkey-windows-amd64.exe ./cmd/wobkey/
• The Linux HID layer (/dev/hidraw*) won't work on macOS/Windows — need conditional compilation or platform-specific HID backends

Quick Commands for Next Session

# 1. Fix permissions (requires sudo)
sudo chown root:adm /dev/hidraw* && sudo chmod 660 /dev/hidraw*

# 2. Rebuild with latest code
go build -o /tmp/wobkey ./cmd/wobkey/

# 3. Test discovery
/tmp/wobkey keyboard info

# 4. Test RGB commands
/tmp/wobkey rgb disable
/tmp/wobkey rgb enable
/tmp/wobkey rgb info

# 5. Run all tests
go test ./...