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

On Linux, `libudev-dev` is required for building (the hid library uses it for device discovery).
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` |

## Effect Behavior

Effects fall into categories that behave differently:

- **Static** effects (`solid_color`, `none`) display a steady output. The color is set by `rgb color` and is constant.
- **Reactive** effects (`solid_reactive*`) light up on key press. They honor the color set by `rgb color` — the pressed key's LEDs flash in the configured color. Use `rgb speed` to adjust how long the illumination lasts.
- **Breathing** effects (`breathing`, `hue_breathing`) slowly fade in and out. They do not honor `rgb color` directly; `hue_breathing` cycles through the full hue range.
- **Dynamic/stream** effects (`band_*`, `cycle_*`, `rainbow_*`, `starlight*`, `raindrops`, `jellybean_raindrops`, `flower_blooming`, `pixel_flow`, `riverflow`) animate independently. Most ignore `rgb color` and use their own color palettes. `hue_breathing`, `hue_pendulum`, and `hue_wave` cycle through hues.
- **Splash** effects (`splash`, `multisplash`, `solid_splash`, `solid_multisplash`) react to key presses like reactive effects but with a splash pattern. `solid_splash` and `solid_multisplash` honor `rgb color`.
- **Gradient** effects (`gradient_up_down`, `gradient_left_right`) create a color gradient across the keyboard. They do not honor `rgb color`.
- **Alphas mods** (`alphas_mods`) colors modifier keys differently from alphanumeric keys. The colors are built-in and cannot be changed.

To set a permanent color, use `solid_color` and then `rgb color <hex>`.

## Compatibility Aliases
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`.

The effect catalog is consistent with the QMK RGB Matrix firmware. The
keyboard implements the VIA protocol (version 3) and its 46 backlight effect
names match the QMK RGB Matrix effect catalog exactly — verified through live
testing. The animations are defined in
[QMK `rgb_matrix/animations/`](https://github.com/qmk/qmk_firmware/tree/master/quantum/rgb_matrix/animations),
where each effect has its own header file (e.g.
`digital_rain_anim.h`, `solid_reactive_anim.h`, `riverflow_anim.h`).

ID 39 is `multisplash`; ID 41 is the distinct `solid_multisplash` name.

`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

To build, `libudev-dev` is required:

```bash
sudo apt install -y libudev-dev
```

To run without `sudo`, grant your user group access to hidraw devices. By default, hidraw devices are owned by root (`600`).
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                  |
| `wobkey rgb save [name]`        | Save current RGB state to `profiles/<name>.json` |
| `wobkey rgb load [name]`        | Load and apply a profile from `profiles/` |
| `wobkey rgb list`               | List saved profiles                        |
| `wobkey rgb delete [name]`      | Delete a saved profile                     |

## Profiles

Profiles store RGB state (effect, brightness, speed, color) per zone as JSON
files in the `profiles/` directory. They are the only way to persist RGB
settings across reboots. The keyboard's VIA protocol does not expose a
standard command to save RGB state to internal EEPROM, so profiles rely on
files instead.

## 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`