fizzctl 0.2.0__py3-none-any.whl

fizzctl-0.2.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.3
+Name: fizzctl
+Version: 0.2.0
+Summary: Control a Redragon K617 Fizz keyboard on Linux: solid colors, 22 firmware-native RGB effects, per-key painting, live animations, and Cfg.ini keymap restore — no vendor software required
+Keywords: redragon,k617,fizz,rgb,keyboard,backlight,led,hid,linux
+Author: Ayoub Dya
+Author-email: Ayoub Dya <ayoubdya@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Classifier: Topic :: System :: Hardware
+Requires-Dist: dpkt>=1.9.8
+Requires-Dist: hidapi>=0.15.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# fizzctl
+
+Linux tool for controlling the Redragon K617 Fizz keyboard's RGB lighting
+and restoring keymaps from `Cfg.ini` files.
+
+## Install
+
+```bash
+# from PyPI
+pip install fizzctl
+
+# from PyPI (uv)
+uv tool install fizzctl
+
+# from source
+git clone https://github.com/you/fizzctl.git && cd fizzctl
+uv build && uv tool install .
+```
+
+### Udev rules (needs one `sudo`)
+
+```bash
+fizzctl setup-udev
+```
+
+This installs `99-k617.rules` to `/etc/udev/rules.d/`, reloads udev and
+re-triggers device events. The command elevates its own privileged steps
+via `sudo` (you are prompted for your password), so you do **not** need to
+wrap it as `sudo fizzctl ...` — that fails because the binary lives in a
+user-local path like `~/.local/bin`. Unplug/replug the keyboard afterwards if
+the trigger did not pick it up.
+
+## Commands
+
+| Command | Description | Persists |
+|---|---|---|
+| `rgb` | Set the whole board to a solid color | yes |
+| `effect` | Run one of 22 firmware-native effects | yes |
+| `key` | Paint a single key | yes |
+| `paint` | Paint multiple keys at once | yes |
+| `keymap` | Write the keymap from a Cfg.ini | yes |
+| `animate` | Host-streamed animation (volatile) | no |
+
+## Examples
+
+All commands accept short flag aliases alongside their long forms:
+| Long | Short | Applies to |
+|---|---|---|
+| `--color` | `-c` | `effect`, `animate` |
+| `--speed` | `-s` | `effect`, `animate` |
+| `--brightness` | `-b` | `effect`, `rgb` |
+| `--fps` | `-f` | `animate` |
+
+### Write keymap (most important)
+
+Apply the full keymap (bindings, lighting zones, function keys) from a
+`Cfg.ini` — the file the official Redragon software exports:
+
+```bash
+fizzctl keymap Cfg.ini
+```
+
+### Set the whole board to one color
+
+```bash
+fizzctl rgb red
+fizzctl rgb 00ff00 --brightness 4       # or: rgb 00ff00 -b 4
+```
+
+### Firmware effects
+
+All 22 effects from the official Redragon software are supported, with full
+speed and brightness control. `speed` and `brightness` are 5 levels (0-4,
+matching the firmware); higher = faster / brighter. Run `fizzctl effect`
+with no name to list every effect:
+
+```bash
+fizzctl effect
+fizzctl effect rainbow
+fizzctl effect rainbow --speed 2 --brightness 4   # or: -s 2 -b 4
+fizzctl effect fixed-on --color 00ff00 --brightness 3
+fizzctl effect snake --color ff0000 --speed 4
+fizzctl effect off
+```
+
+Aliases are supported: `static` → `fixed-on`, `wheel` → `rainbow-wheel`,
+`snake` → `retro-snake`, `waterfall` → `colorful-waterfall`.
+
+### Per-key painting
+
+Keys are named by their top-left legend. Any key *not* listed turns off
+because the canvas is absolute:
+
+```bash
+fizzctl key W ff0000
+fizzctl paint W=ff0000 A=00ff00 S=ffff00 D=ff00ff Space=ffffff
+```
+
+### Host-side animations
+
+Volatile — lost when the keyboard reconnects or reboots. Run `fizzctl
+animate` with no name to list the animations:
+
+```bash
+fizzctl animate
+fizzctl animate rainbow --fps 30 --duration 10  # or: -f 30
+fizzctl animate chase --color ff0000 --speed 2  # or: -c yellow -s 2
+fizzctl animate solid --color 0000ff
+```
+
+### Debug mode
+
+```bash
+fizzctl --debug effect rainbow
+```
+
+Shows the raw frames and handshake bytes sent over HID.
+
+## Dev tools
+
+The `fizzctl-dev` binary exposes the full reverse-engineering toolkit
+(capture inspect, diff, export, replay) in addition to all user commands.
+
+```bash
+fizzctl-dev inspect captures/r3.json
+fizzctl-dev diff captures/r2.json captures/r3.json
+fizzctl-dev export captures/r2.json frames.json
+fizzctl-dev replay frames.json
+fizzctl-dev cfg Cfg.ini
+fizzctl-dev list
+```
+
+## How the RGB paths work
+
+**Flash writes** (`rgb`, `key`, `paint`, `effect`, `keymap`) send a 4-5 frame
+burst through the vendor HID interface (`258a:0049`, interface 1, usage page
+`0xFF00`). The sequence ends with a `5AA5` magic commit that writes to flash.
+Colors persist across reboots. Keys not listed in a `key` or `paint` canvas
+turn off.
+
+**Animations** (`animate`) stream 382-byte per-key reports at the requested
+frame rate with no flash commit. They are host-side only and lost on
+reconnect.
+
+## Colors
+
+Colors can be given as a name or `RRGGBB` hex (with or without `#`). Spaces,
+dashes and underscores in names are ignored, so `light green`, `light-green`
+and `lightgreen` are equivalent:
+
+```text
+red green blue white black off
+yellow cyan magenta orange pink purple lime teal violet indigo coral salmon
+navy brown gold silver gray grey olive maroon
+lightred lightgreen lightblue darkred darkgreen darkblue
+```
+
+Both `-c yellow` and `--color ffaa00` work anywhere a color flag is accepted.

fizzctl-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+fizzctl/__init__.py,sha256=u5xtNuChnfsZDbitOyropXhjaPTOmWISwdlTx25wgBA,357
+fizzctl/animations.py,sha256=jUDA-GP19MzJKgTLaNKRzRbyaumPje8um3qimKeB-LY,4937
+fizzctl/blobs.py,sha256=AqB6tzOnKO31Gdwpa2fAXByTjZbAyfZyrR7rcs4ikKY,22056
+fizzctl/capture.py,sha256=bKMofNzSuzfpdcnLKu1c2XnFWqzzVky09hRLQW58mmc,7488
+fizzctl/cfg.py,sha256=zOuFgSofoF7dt3Gli-fKdv5_Oqbr3seIlJKQOiKwwjM,4857
+fizzctl/cli.py,sha256=6k4MY-8HQNPeMI1vvsluHioxu7TB4ESC-ZKEhVgZDy8,14312
+fizzctl/effects.py,sha256=HjAGbdKZN0RA0rsL6thGtrtV-hz4Djq5YSnK3Pcq2Fw,9989
+fizzctl/hid.py,sha256=wnJh1Diztfy5STkiTUpZaGHSaBpXUhdkE6Epn2QmYNo,8860
+fizzctl/keymap.py,sha256=KgmjETVSDkTVUZ3sjVUSXo5Ems_07qHMy9pOW93O-2U,6387
+fizzctl/protocol.py,sha256=htTjPKTNVgQhuOlac9kkTW6vUEJNAijy0lD_XfBMwGA,3597
+fizzctl/udev_rules.py,sha256=aFvGMqUBhkql9mVLp6oJyzc9VRwQzfOhy-ZUPIbz6Z4,3272
+fizzctl-0.2.0.dist-info/WHEEL,sha256=_d8F1e7SqtoW6CDj4Gi8lFC26a_7I17R7zPLCKTp4Fg,81
+fizzctl-0.2.0.dist-info/entry_points.txt,sha256=jnEQru2UrKpaDSd0zljE1Rgbh2_Uxz8Eta5c01gEk3k,73
+fizzctl-0.2.0.dist-info/METADATA,sha256=ZSW-6v8idkufmEMOd3QzGy0uAY6tF5ctz3ml8tMRny0,5412
+fizzctl-0.2.0.dist-info/RECORD,,

fizzctl-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.15
+Root-Is-Purelib: true
+Tag: py3-none-any

fizzctl-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+fizzctl = fizzctl:main
+fizzctl-dev = fizzctl:main_dev
+