fizzctl 0.2.0__tar.gz

fizzctl-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,158 @@
+# 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/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "fizzctl"
+version = "0.2.0"
+description = "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"
+readme = "README.md"
+keywords = [
+    "redragon",
+    "k617",
+    "fizz",
+    "rgb",
+    "keyboard",
+    "backlight",
+    "led",
+    "hid",
+    "linux",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Hardware :: Hardware Drivers",
+    "Topic :: System :: Hardware",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "dpkt>=1.9.8",
+    "hidapi>=0.15.0",
+]
+
+[project.license]
+text = "MIT"
+
+[[project.authors]]
+name = "Ayoub Dya"
+email = "ayoubdya@gmail.com"
+
+[project.scripts]
+fizzctl = "fizzctl:main"
+fizzctl-dev = "fizzctl:main_dev"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true

fizzctl-0.2.0/pyproject.toml.orig

@@ -0,0 +1,46 @@
+[project]
+name = "fizzctl"
+version = "0.2.0"
+description = "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"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Ayoub Dya", email = "ayoubdya@gmail.com" }
+]
+keywords = [
+    "redragon",
+    "k617",
+    "fizz",
+    "rgb",
+    "keyboard",
+    "backlight",
+    "led",
+    "hid",
+    "linux",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Hardware :: Hardware Drivers",
+    "Topic :: System :: Hardware",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "dpkt>=1.9.8",
+    "hidapi>=0.15.0",
+]
+
+[project.scripts]
+fizzctl = "fizzctl:main"
+fizzctl-dev = "fizzctl:main_dev"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true

fizzctl-0.2.0/src/fizzctl/__init__.py

@@ -0,0 +1,10 @@
+"""fizzctl — Linux tooling for the Redragon K617 Fizz.
+
+User commands live in the :func:`main` entry point (rgb/effect/key/paint/
+animate/keymap/setup-udev); the full reverse-engineering toolkit is exposed
+by :func:`main_dev` via the ``fizzctl-dev`` console script.
+"""
+from .cli import main, main_dev
+
+__all__ = ["main", "main_dev"]
+__version__ = "0.2.0"

fizzctl-0.2.0/src/fizzctl/animations.py

@@ -0,0 +1,145 @@
+"""Host-side per-key animations streamed at N fps via the Sinodragon protocol.
+
+These are NOT firmware effects — they render color maps on the host and push
+one 382-byte per-key report per frame (volatile; stop with Ctrl+C).  Only the
+8 firmware-native effects (`fizzctl effect`) survive a disconnect.
+
+Animation helpers are pure ("render_frame(t, color, speed) -> dict") so they
+can be unit-tested without hardware.
+"""
+from __future__ import annotations
+
+import math
+import time
+
+from .effects import PER_KEY_POS, encode_per_key_frame, parse_color
+
+ANIMATIONS = ["solid", "blink", "pulse", "chase", "wave", "rainbow", "drop"]
+
+
+def hsv(h: float, s: float, v: float) -> tuple[int, int, int]:
+    """HSV (h 0..360, s/v 0..1) -> (r,g,b) 0..255."""
+    c = v * s
+    x = c * (1 - abs((h / 60) % 2 - 1))
+    m = v - c
+    if h < 60:
+        r, g, b = c, x, 0
+    elif h < 120:
+        r, g, b = x, c, 0
+    elif h < 180:
+        r, g, b = 0, c, x
+    elif h < 240:
+        r, g, b = 0, x, c
+    elif h < 300:
+        r, g, b = x, 0, c
+    else:
+        r, g, b = c, 0, x
+    return int((r + m) * 255), int((g + m) * 255), int((b + m) * 255)
+
+
+def render_frame(t: float, anim: str, color: tuple[int, int, int],
+                 speed: float = 1.0) -> dict[str, tuple[int, int, int]]:
+    """Produce a color map for animation `anim` at time `t` (seconds).
+
+    speed scales the cycle period (higher = faster).  Positions are the
+    verified col*6+row raster from effects.PER_KEY_POS.
+    """
+    r, g, b = color
+    out: dict[str, tuple[int, int, int]] = {}
+    period = max(0.1, 2.0 / speed)
+
+    if anim == "solid":
+        return {k: color for k in PER_KEY_POS}
+
+    if anim == "blink":
+        cycle = (t / period) % 1
+        return {k: color if cycle < 0.5 else (0, 0, 0) for k in PER_KEY_POS}
+
+    if anim == "pulse":
+        v = 0.5 + 0.5 * math.sin(2 * math.pi * t / period)
+        dim = tuple(int(c * v) for c in color)
+        return {k: dim for k in PER_KEY_POS}
+
+    if anim == "chase":
+        order = sorted(PER_KEY_POS, key=lambda k: PER_KEY_POS[k])
+        idx = int((t / period) * len(order)) % len(order)
+        for i, k in enumerate(order):
+            dist = (i - idx) % len(order)
+            frac = max(0.0, 1.0 - dist / 5)
+            out[k] = tuple(int(c * frac) for c in color) if dist < 5 else (0, 0, 0)
+        return out
+
+    if anim == "wave":
+        for k, pos in PER_KEY_POS.items():
+            col = pos // 6
+            phase = (t / period + col / 14) % 1
+            v = 0.5 + 0.5 * math.sin(2 * math.pi * phase)
+            out[k] = tuple(int(c * v) for c in color)
+        return out
+
+    if anim == "rainbow":
+        order = sorted(PER_KEY_POS, key=lambda k: PER_KEY_POS[k])
+        for i, k in enumerate(order):
+            hue = (360 * t / period + 360 * i / len(order)) % 360
+            out[k] = hsv(hue, 1.0, 1.0)
+        return out
+
+    if anim == "drop":
+        for k, pos in PER_KEY_POS.items():
+            col = pos // 6
+            row = pos % 6
+            phase = ((t * speed + col) % 6) - row
+            out[k] = color if 0 <= phase < 1 else (0, 0, 0)
+        return out
+
+    raise ValueError(f"unknown animation {anim!r}; choose from {', '.join(ANIMATIONS)}")
+
+
+def run_animation(dev, anim: str, color: tuple[int, int, int],
+                  fps: int = 30, speed: float = 1.0, duration: float | None = None) -> None:
+    """Stream `anim` until Ctrl+C (or `duration` seconds)."""
+    from .hid import send_per_key
+
+    period = 1.0 / fps
+    start = time.monotonic()
+    try:
+        while True:
+            if duration is not None and time.monotonic() - start >= duration:
+                break
+            frame = encode_per_key_frame(render_frame(time.monotonic() - start, anim, color, speed))
+            send_per_key(dev, frame)
+            time.sleep(period)
+    except KeyboardInterrupt:
+        pass
+
+
+def cmd_animate(args):
+    """fizzctl animate <name> [--color HEX] [--speed N] [--fps N] [--duration S]"""
+    from .hid import NoDeviceError, open_device
+
+    anim = args.name
+    if anim is None:
+        print("Host-side animations (volatile — lost on disconnect). Run like:")
+        print("  fizzctl animate chase --color yellow --speed 2 --fps 30")
+        for name in ANIMATIONS:
+            print(f"  {name}")
+        return 0
+    if anim not in ANIMATIONS:
+        print(f"unknown animation {anim!r}. Available: {', '.join(ANIMATIONS)}")
+        return 1
+    color = parse_color(args.color or "ff0000")
+    if color is None:
+        print(f"bad color {args.color!r}")
+        return 1
+    try:
+        dev = open_device(debug=getattr(args, 'debug', False))
+    except NoDeviceError:
+        return 1
+    if dev is None:
+        return 1
+    try:
+        print(f"streaming {anim} at {args.fps}fps (Ctrl+C to stop)...")
+        run_animation(dev, anim, color, fps=args.fps, speed=args.speed, duration=args.duration)
+    finally:
+        dev.close()
+    return 0