# 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

```bash
# 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 ./...
```