# Wobkey RGB CLI

Cross-platform CLI for Linux, macOS, and Windows. Designed for automation, scripting, and agent consumption.

## Installation

```bash
git clone <repo-url>
cd wobkey-rgb
go build -o wobkey ./cmd/wobkey/
```

Or install globally:

```bash
go install ./cmd/wobkey/
```

## Usage

```bash
# Discover connected keyboards
./wobkey keyboard info

# RGB commands target Logo, Backlight, and Side by default
./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
# Raw mode IDs are zone-specific; ID 17 is Backlight-only
./wobkey rgb mode 17 --zone backlight
./wobkey rgb enable
./wobkey rgb disable
./wobkey rgb info

# Select exactly one zone
./wobkey rgb brightness 160 --zone side

# Specify a target device (when multiple are connected)
./wobkey rgb --device /dev/hidraw0 enable
```

`--zone` is persistent on `rgb` and accepts `logo`, `backlight`, or `side`.
Without `--zone`, commands target Logo, Backlight, and Side in that order.
With `--zone`, commands target exactly the selected zone. An unsupported
name for an explicit zone fails before the device is opened; a default
command skips unsupported zones and prints a warning on stderr.

All output is machine-parseable JSON when applicable.

## Impact 80 Zones and Effects

| Zone | CLI name | VIA channel | Effect IDs |
|---|---|---:|---|
| Logo | `logo` | 2 | 0–6 |
| Backlight | `backlight` | 3 | 0–45 |
| Side | `side` | 4 | 0–6 |

Logo and Side share this complete effect family:

| ID | Name |
|---:|---|
| 0 | `none` |
| 1 | `wave` |
| 2 | `fixed_wave` |
| 3 | `spectrum` |
| 4 | `breathing` |
| 5 | `light` |
| 6 | `shutdown` |

Backlight uses the complete Impact 80 catalog:

| ID | Name | ID | Name |
|---:|---|---:|---|
| 0 | `none` | 23 | `flower_blooming` |
| 1 | `solid_color` | 24 | `raindrops` |
| 2 | `alphas_mods` | 25 | `jellybean_raindrops` |
| 3 | `gradient_up_down` | 26 | `hue_breathing` |
| 4 | `gradient_left_right` | 27 | `hue_pendulum` |
| 5 | `breathing` | 28 | `hue_wave` |
| 6 | `band_sat` | 29 | `pixel_flow` |
| 7 | `band_val` | 30 | `digital_rain` |
| 8 | `band_pinwheel_sat` | 31 | `solid_reactive` |
| 9 | `band_pinwheel_val` | 32 | `solid_reactive_wide` |
| 10 | `band_spiral_sat` | 33 | `solid_reactive_multiwide` |
| 11 | `band_spiral_val` | 34 | `solid_reactive_cross` |
| 12 | `cycle_all` | 35 | `solid_reactive_multicross` |
| 13 | `cycle_left_right` | 36 | `solid_reactive_nexus` |
| 14 | `cycle_up_down` | 37 | `solid_reactive_multinexus` |
| 15 | `cycle_out_in` | 38 | `splash` |
| 16 | `cycle_out_in_dual` | 39 | `multisplash` |
| 17 | `rainbow_moving_chevron` | 40 | `solid_splash` |
| 18 | `cycle_pinwheel` | 41 | `solid_multisplash` |
| 19 | `cycle_spiral` | 42 | `starlight` |
| 20 | `dual_beacon` | 43 | `starlight_dual_hue` |
| 21 | `rainbow_beacon` | 44 | `starlight_dual_sat` |
| 22 | `rainbow_pinwheels` | 45 | `riverflow` |

ID 39 is `multisplash`; ID 41 is the distinct `solid_multisplash` name.
Effect names are resolved independently for each target zone. Compatibility
aliases are `off` → `none`, `breathe` → `breathing`, `rainbow` → `spectrum`
for Logo/Side and `rainbow_moving_chevron` for Backlight, `rainbow_wave` →
`wave` for Logo/Side, and `solid` → `light` for Logo/Side and `solid_color`
for Backlight. The legacy `static` alias remains accepted as a compatibility
alias for `solid`.

`rgb info` reports a `zones` array with each zone's channel, enabled state,
effect name and ID, brightness, speed, and color. The top-level `enabled`,
`mode`, `brightness`, and `speed` fields summarize the first selected zone.
If one zone cannot be queried, its record contains an `error`, other records
are retained, and the process exits non-zero after printing the JSON.

## Platform Setup

The tool uses [hidapi](https://github.com/libusb/hidapi) for cross-platform HID access.
Most platforms need no configuration, but Linux requires extra setup.

### Linux

The tool accesses keyboards via hidraw which requires special permissions by default. To run without `sudo`, choose one of the methods below.

#### Option 1: Quick (Per Session)

Grant your user group access to all HIDRAW devices:

```bash
sudo chown root:adm /dev/hidraw*
sudo chmod 660 /dev/hidraw*
```

This works for the current session only. Permissions reset after reboot.

#### Option 2: Permanent (udev Rule)

Create a persistent rule for the Wobkey Impact 80:

```bash
echo 'SUBSYSTEM=="hidraw", ATTRS{idVendor}=="36b0", ATTRS{idProduct}=="309f", MODE="0660", GROUP="adm"' \
  | sudo tee /etc/udev/rules.d/99-wobkey.rules

sudo udevadm control --reload-rules
sudo udevadm trigger
sudo udevadm reload
```

This makes the Impact 80 accessible to members of the `adm` group on every boot.

### macOS

No setup required. macOS applications access HID devices directly through IOKit.

### Windows

No setup required. Windows applications access HID devices directly through the Windows HID API.

After Linux setup, run the tool as your regular user (no `sudo` needed).

## Supported Keyboards

| Keyboard        | VID    | PID    | Status    |
|-----------------|--------|--------|-----------|
| Wobkey Rainy 75 | 0x6666 | 0x0001 | Supported |
| Wobkey Impact 80| 0x36B0 | 0x309F | Supported |

New keyboards can be added to `keyboards.json`.

## CLI Reference

| Command                         | Description                              |
|---------------------------------|------------------------------------------|
| `wobkey keyboard info`          | Discover connected VIA-compatible keyboards |
| `wobkey rgb enable`             | Enable selected lighting zones           |
| `wobkey rgb disable`            | Disable selected lighting zones           |
| `wobkey rgb info`               | Show per-zone RGB state (JSON)            |
| `wobkey rgb effect <name>`      | Set a zone-aware effect by name           |
| `wobkey rgb brightness <val>`   | Set brightness (0–255) on selected zones |
| `wobkey rgb speed <val>`        | Set effect speed (0–255) on selected zones |
| `wobkey rgb color <hex>`        | Set color (e.g. `ff0000`) on selected zones |
| `wobkey rgb mode <index>`       | Set a raw zone-specific effect ID        |
| `wobkey rgb --zone <zone> ...`  | Target `logo`, `backlight`, or `side`     |
| `wobkey rgb --device <path> ...`| Specify HID device path                  |

## Architecture

```
cmd/wobkey/       # Cobra-based CLI
cmd/wobkey/rgb/   # RGB subcommands
internal/device/  # HID discovery + keyboards.json loader
internal/hid/     # Cross-platform HID access (hidapi)
internal/rgb/     # Effects, colors, state
internal/via/     # VIA protocol implementation
```

## Protocol

Communicates via the QMK Raw HID interface (`Usage Page 0xFF60`, `Usage 0x61`) with 32-byte feature reports.

- `0x07` — Custom set value
- `0x08` — Custom get value
- Lighting channels: `0x02` logo, `0x03` backlight, `0x04` side lighting
- RGB values: brightness `0x01`, effect `0x02`, speed `0x03`, color `0x04`