fizzctl 0.2.0__tar.gz → 0.2.1__tar.gz

{fizzctl-0.2.0 → fizzctl-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fizzctl
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -14,7 +14,6 @@ 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
@@ -91,9 +90,9 @@ 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:
+speed and brightness control. `speed` is 1..5 and `brightness` is 0..4 (5
+levels each, matching the firmware); higher = faster / brighter. Run
+`fizzctl effect` with no name to list every effect:
 
 ```bash
 fizzctl effect

{fizzctl-0.2.0 → fizzctl-0.2.1}/README.md

@@ -70,9 +70,9 @@ 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:
+speed and brightness control. `speed` is 1..5 and `brightness` is 0..4 (5
+levels each, matching the firmware); higher = faster / brighter. Run
+`fizzctl effect` with no name to list every effect:
 
 ```bash
 fizzctl effect

{fizzctl-0.2.0 → fizzctl-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fizzctl"
-version = "0.2.0"
+version = "0.2.1"
 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 = [
@@ -25,10 +25,7 @@ classifiers = [
     "Topic :: System :: Hardware",
 ]
 requires-python = ">=3.14"
-dependencies = [
-    "dpkt>=1.9.8",
-    "hidapi>=0.15.0",
-]
+dependencies = ["hidapi>=0.15.0"]
 
 [project.license]
 text = "MIT"

fizzctl-0.2.1/pyproject.toml.orig

@@ -0,0 +1,41 @@
+[project]
+name = "fizzctl"
+version = "0.2.1"
+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 = ["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 → fizzctl-0.2.1}/src/fizzctl/blobs.py

@@ -1,11 +1,22 @@
 """Baked firmware bytes, inlined as hex so the package ships no binary files.
 
 All constants come from USB captures of the OEM software:
-  * CONST_MODE / CONST_CANVAS / CONST_ROUTING / CONST_EXEC  — the
+  * CONST_MODE / CONST_CANVAS / CONST_ROUTING / CONST_EXEC — the
     four constant 1032-byte frames of the Restore sequence.
-  * FW_FRAMES — the 5-frame static-effect template used for RGB writes.
+  * FW_TEMPLATE — the 5-frame effect template: shared MODE and ROUTING,
+    a distinct CANVAS, and five byte overrides of CONST_EXEC.
+  * RGB_EXEC / RGB_SEC — the whole-board solid-color variant.
 """
 
+
+def _patch(base: bytes, diffs: dict[int, int]) -> bytes:
+    """Copy `base`, overriding a handful of byte offsets."""
+    b = bytearray(base)
+    for off, val in diffs.items():
+        b[off] = val
+    return bytes(b)
+
+
 CONST_MODE = bytes.fromhex(
     "0608b80040000000000000000000000000000000000000000000000000ff0000"
     "0000ff00ff00ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00"
@@ -150,49 +161,9 @@ CONST_EXEC = bytes.fromhex(
     "0000000000000000"
 )
 
-FW_FRAMES = [
-    # frame 0: 6B
-    bytes.fromhex(
-    "0583b6000000"
-    ),
-    # frame 1: 1032B
-    bytes.fromhex(
-    "0608b80040000000000000000000000000000000000000000000000000ff0000"
-    "0000ff00ff00ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00"
-    "ff00ffffffffffff00000000ff00ff00ffff00ff00ff00ffffffffffff000000"
-    "00ff00ff00ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00ff"
-    "00ffffffffffff00000000ff00ff00ffff00ff00ff00ffffffffffff00000000"
-    "ff00ff00ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00ff00"
-    "ffffffffffff00000000ff00ff00ffff00ff00ff00ffffffffffff00000000ff"
-    "00ff00ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00ff00ff"
-    "ffffffffff00000000ff00ff00ffff00ff00ff00ffffffffffff00000000ff00"
-    "ff00ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00ff00ffff"
-    "ffffffff00000000ff00ff00ffff00ff00ff00ffffffffffff00000000ff00ff"
-    "00ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00ff00ffffff"
-    "ffffff00000000ff00ff00ffff00ff00ff00ffffffffffff00000000ff00ff00"
-    "ffff00ff00ff00ffffffffffff00000000ff00ff00ffff00ff00ff00ffffffff"
-    "ffff00000000ff00ff00ffff00ff00ff00ffffffffffff00000000ff00ff00ff"
-    "ff00ff00ff00ffffffffff000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000"
-    ),
-    # frame 2: 1032B
-    bytes.fromhex(
+INIT = bytes.fromhex("0583b6000000")
+
+FW_CANVAS = bytes.fromhex(
     "0609bc0040000000000000000000000000000000000000000000000000000000"
     "00000000000000000000000000000000000000ff00ff00ff0000000000000000"
     "0000000000000000ffffff00ff0000000000000000000000000000000000ff00"
@@ -226,89 +197,18 @@ FW_FRAMES = [
     "0000000000000000000000000000000000000000000000000000000000000000"
     "0000000000000000000000000000000000000000000000000000000000000000"
     "0000000000000000"
-    ),
-    # frame 3: 1032B
-    bytes.fromhex(
-    "0609c00040000000000000000000ffffffffffffff0000000000000000000000"
-    "000000ffffffffff00000000000000000000000000000000ffffffffff000000"
-    "000000000000000000000000ff000000ffff0000000000000000000000000000"
-    "00ff000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000ffffffffffffff0000000000000000000000000000ffffff"
-    "ff0000000000000000000000000000000000ffffffff00000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "000000000000000000000000000000000000000000000000ff00ff0000000000"
-    "000000000000000000000000ffffff0000000000000000000000000000000000"
-    "ff0000000000000000000000000000000000000000ff00ff0000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000"
-    ),
-    # frame 4: 1032B
-    bytes.fromhex(
-    "0603b600000000000000000000005aa503030000000120010000000055550100"
-    "00000000ffff0034073307330733073307330733073307330733073307330733"
-    "07330733073307330733073307335aa500100744074407440744074407440744"
-    "0404040404040404040400000000000000000000000000000000000000000000"
-    "0000000000000000005aa5030300000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000000000000000000000000000000000000000000000000000"
-    "0000000000000000"
-    ),
-]
+)
 
+EXEC_DIFFS = {18: 0, 21: 1, 38: 0, 39: 52, 141: 0}
 
+FW_TEMPLATE = [
+    INIT,
+    CONST_MODE,
+    FW_CANVAS,
+    CONST_ROUTING,
+    _patch(CONST_EXEC, EXEC_DIFFS),
+]
 
-# --- RGB static-color protocol ---
-RGB_INIT = bytes.fromhex("0583b6000000")
-# P1 canvas is BUILT (header + split-plane colors + SEC at 660), not taken from
-# a template.  P2 routing is the same 06 09 c0 block used by the Restore
-# sequence (matches RESTORE_CONSTANT_FRAMES[2] exactly).  EXEC must be the
-# static-color variant: effect_id=0x01, brightness=0x15.
 RGB_SEC = bytes.fromhex(
     "ffffffffff000000000000000000000000000000ffffffffff00000000000000"
     "00000000000000000000ffffff00ff000000000000000000000000000000ff00"

{fizzctl-0.2.0 → fizzctl-0.2.1}/src/fizzctl/capture.py

@@ -1,8 +1,7 @@
 """USB capture import/diff/export for the K617 OEM software.
 
-Inputs accepted:
+Input accepted:
   * Wireshark JSON : `tshark -r cap.pcapng -T json > cap.json` (recommended)
-  * raw .pcap     : Linux usbmon capture, parsed with dpkt
 
 The job:
   1. pull every HID feature-report payload out of the USB stream,
@@ -147,24 +146,6 @@ def _parse_usb_layer(u: dict, setup: dict | None = None) -> FrameCapture | None:
     )
 
 
-def load_pcap_usbmon(path: str) -> list[FrameCapture]:
-    """Minimal Linux usbmon .pcap reader (dpkt)."""
-    import dpkt
-
-    out: list[FrameCapture] = []
-    with open(path, "rb") as fh:
-        pcap = dpkt.pcap.Reader(fh)
-        for _, buf in pcap:
-            try:
-                u = dpkt.usbmon.LinuxUSB(buf)
-            except Exception:
-                continue
-            data = bytes(u.transfer_buffer) if u.xfer_type & 0x80 else None
-            direction = "IN" if u.urb_type == 0x55 else "OUT"
-            out.append(FrameCapture(direction=direction, transfer="urb", request=None, report_id=None, data=data or b""))
-    return out
-
-
 def significant(records: list[FrameCapture], direction: str = "OUT") -> list[FrameCapture]:
     """Keep only payload-bearing writes from the host (the interesting direction)."""
     return [r for r in records if r.direction == direction and len(r.data) > 0]

{fizzctl-0.2.0 → fizzctl-0.2.1}/src/fizzctl/cfg.py

@@ -104,15 +104,3 @@ class CfgIni:
     @property
     def key_entries(self) -> list[tuple[int, KeyEntry]]:
         return sorted(self.keys.items())
-
-
-if __name__ == "__main__":
-    import sys
-    cfg = CfgIni(sys.argv[1] if len(sys.argv) > 1 else "Cfg.ini")
-    print(f"OPT: {len(cfg.opt)} keys")
-    print(f"[FN] {len(cfg.fn)} mappings")
-    for idx, be in cfg.fn_entries:
-        print(f"  K{idx:<3} = {', '.join(f'0x{b:02X}' for b in be)}")
-    print(f"[KEY] {len(cfg.keys)} keys")
-    for idx, e in cfg.key_entries:
-        print(f"  K{idx:<3} = {e.matrix} {', '.join(f'0x{b:02X}' for b in e.behavior)}")

{fizzctl-0.2.0 → fizzctl-0.2.1}/src/fizzctl/cli.py

@@ -26,7 +26,7 @@ import sys
 from .animations import cmd_animate
 from .capture import diff_captures, export_frames, load_frames, load_tshark_json, significant
 from .cfg import CfgIni
-from .hid import K617, NoDeviceError, open_device
+from .hid import NoDeviceError, open_device, send_burst
 from .keymap import KeymapEncoder
 from .protocol import RESTORE_CONSTANT_FRAMES
 
@@ -91,7 +91,7 @@ def cmd_replay(args):
     if dev is None:
         return 1
     try:
-        dev.send_sequence(frames, delay_ms=args.delay_ms)
+        send_burst(dev, frames, handshake=False, delay_ms=args.delay_ms)
     finally:
         dev.close()
     return 0
@@ -123,7 +123,7 @@ def cmd_keymap(args):
     if dev is None:
         return 1
     try:
-        dev.send_sequence(frames, delay_ms=args.delay_ms)
+        send_burst(dev, frames, handshake=False, delay_ms=args.delay_ms)
     finally:
         dev.close()
     print(f"wrote keymap from {args.cfg} to flash")
@@ -151,24 +151,22 @@ def cmd_effect(args):
         fizzctl effect waterfall --color ff8800
         fizzctl effect static --brightness 1
     """
-    from .effects import EFFECT_ACCEPTS_COLOR, EFFECT_DEFAULTS, EFFECT_ID, encode_firmware_effect
-    from .hid import send_firmware_effect
+    from .effects import (
+        EFFECT_ACCEPTS_COLOR, EFFECT_DEFAULTS, EFFECT_ID,
+        _ALIASES, encode_firmware_effect, parse_color,
+    )
 
-    name = args.name
-    if name is None:
+    name = _ALIASES.get(args.name, args.name)
+    if name is None or name not in EFFECT_ID:
+        if name is not None:
+            print(f"unknown effect {name!r}")
         print("Firmware effects (22). Run like:  fizzctl effect rainbow --speed 2 --brightness 4")
         for n, eid in EFFECT_ID.items():
-            defs = EFFECT_DEFAULTS[n]
-            color = "yes" if n in EFFECT_ACCEPTS_COLOR else "-"
-            print(f"  {n:18s} id={eid:#04x} color:{color:3s} default sb={defs[0]}.{defs[1]}")
-        return 0
-    if name not in EFFECT_ID:
-        print(f"unknown effect {name!r}. Available ({', '.join(EFFECT_ID)}):")
-        for n, eid in EFFECT_ID.items():
-            defs = EFFECT_DEFAULTS[n]
+            spd, bri = EFFECT_DEFAULTS[n]
+            spd = spd + 1 if spd else 0   # stored 0-based, displayed 1..5
             color = "yes" if n in EFFECT_ACCEPTS_COLOR else "-"
-            print(f"  {n:18s} id={eid:#04x} color:{color:3s} default sb={defs[0]}.{defs[1]}")
-        return 1
+            print(f"  {n:18s} id={eid:#04x} color:{color:3s} default speed={spd} brightness={bri}")
+        return 0 if name is None else 1
 
     color = None
     if args.color:
@@ -185,7 +183,7 @@ def cmd_effect(args):
     if dev is None:
         return 1
     try:
-        send_firmware_effect(dev, frames)
+        send_burst(dev, frames)
     finally:
         dev.close()
     desc = f"effect {name}"
@@ -198,38 +196,17 @@ def cmd_effect(args):
 
 
 def cmd_key(args):
-    """Paint a single key via the CANVAS + 5AA5 execute path (flash write),
-    persistent across reboots."""
-    from .hid import rgb_sequence, send_rgb
-    from .protocol import NAME_TO_INDEX
-
-    color = parse_color(args.color)
-    if color is None:
-        print(f"bad color {args.color!r}")
-        return 1
-    if args.key not in NAME_TO_INDEX:
-        print(f"unknown key {args.key!r}. Available: {', '.join(sorted(NAME_TO_INDEX))}")
-        return 1
-    frames = rgb_sequence({args.key: color})
-    try:
-        dev = open_device(debug=args.debug)
-    except NoDeviceError:
-        return 1
-    if dev is None:
-        return 1
-    try:
-        send_rgb(dev, frames)
-        print(f"painted {args.key} -> #{color[0]:02x}{color[1]:02x}{color[2]:02x}")
-    finally:
-        dev.close()
-    return 0
+    """Paint a single key (`key W red` == `paint W=red`)."""
+    args.specs = [f"{args.key}={args.color}"]
+    return cmd_paint(args)
 
 
 def cmd_paint(args):
     """Paint many keys via the CANVAS + 5AA5 execute path (flash write):
     fizzctl paint W=ff0000 A=00ff00 S=0000ff D=ffffff
     """
-    from .hid import rgb_sequence, send_rgb
+    from .effects import parse_color
+    from .hid import rgb_sequence
     from .protocol import NAME_TO_INDEX
 
     colors = {}
@@ -237,7 +214,7 @@ def cmd_paint(args):
         if "=" not in spec:
             print(f"bad spec {spec!r}: expected KEY=COLOR")
             return 1
-        key, c = spec.split("=", 1)
+        key, c = spec.rsplit("=", 1)
         if key not in NAME_TO_INDEX:
             print(f"unknown key {key!r}")
             return 1
@@ -254,25 +231,13 @@ def cmd_paint(args):
     if dev is None:
         return 1
     try:
-        send_rgb(dev, frames)
-        print(f"painted {len(colors)} keys")
+        send_burst(dev, frames)
+        print(f"painted {len(colors)} key{'s' if len(colors) != 1 else ''}")
     finally:
         dev.close()
     return 0
 
 
-def parse_color(s: str) -> tuple[int, int, int] | None:
-    from .effects import parse_color as _pc
-
-    return _pc(s)
-
-
-def _kind(frame: bytes) -> str:
-    from .protocol import frame_kind
-
-    return frame_kind(frame)
-
-
 def _build_parser(dev: bool) -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="fizzctl" if not dev else "fizzctl-dev",
@@ -323,8 +288,8 @@ Examples:
                           formatter_class=argparse.RawDescriptionHelpFormatter)
     peff.add_argument("name", nargs="?",
                       help="effect name (omit or run `effect` alone to list all)")
-    peff.add_argument("-c", "--color", help="base color (name or hex) — only for color-capable effects")
-    peff.add_argument("-s", "--speed", type=int, help="0..4 (level; higher = faster)")
+    peff.add_argument("-c", "--color", help="base color (name or hex) — RGB/single-color mode")
+    peff.add_argument("-s", "--speed", type=int, help="1..5 (level; higher = faster)")
     peff.add_argument("-b", "--brightness", type=int, help="0..4 (level; higher = brighter)")
 
     pk = sub.add_parser("key",

{fizzctl-0.2.0 → fizzctl-0.2.1}/src/fizzctl/effects.py

@@ -4,12 +4,24 @@ Two independent protocols:
 
 * Firmware effects — a 5-frame burst, all built from the fw-static template
   by patching a few bytes:
-      MODE[29..31]  = base color (R,G,B)
-      EXEC[21]      = effect_id (selects rainbow/snake/wheel/...)
-      EXEC[39]      = packed nibbles (high=speed, low=brightness)
+      MODE[218..220] = base color (R,G,B) — the real color field (per-effect
+                       slot; sine-wave uses MODE[281..283])
+      EXEC[38+2*(id-1)] = per-effect RGB/color toggle: 0x07 multicolor,
+                         0x00 render the MODE base color
+      EXEC[21]       = effect_id (selects rainbow/snake/wheel/...)
+      EXEC[39]       = packed nibbles (high=speed-1 (0..4), low=brightness 0..4)
   Sending requires the mandatory GET_REPORT(0x06, 1032) handshake after INIT
   (without it the firmware silently ignores the burst).
 
+  Speed is stored 0-based: the firmware displays ``nibble + 1`` as speed
+  1..5, so passing ``--speed 1`` stores 0.  Verified on hardware (sine-wave:
+  sending 1/2/3 showed 2/3/4 before the fix).  Brightness is stored raw
+  (0..4).  The color mechanism was verified from OEM captures (same effect in
+  red/green/blue differs only at the effect's MODE color slots, with that
+  effect's flag byte zeroed); all stock templates bake every flag byte to
+  0x07 (multicolor), so the base color needs the effect's own flag flipped to
+  0x00 to take effect — EXEC[56] (the old assumption) is only snake's slot.
+
 * Per-key paint — a SINGLE 382-byte feature report ``08 0a 7a 01`` followed by
   96 RGB triplets in a 16-col x 6-row column-major raster (pos = col*6+row).
   No handshake, no flash commit, host-side (volatile) — bytes are re-applied
@@ -26,7 +38,6 @@ from __future__ import annotations
 # Baseline is the captured fw-static template (init + mode + canvas + routing
 # + exec).  Every other effect only differs in the 3-5 bytes listed below.
 # Indexes into base_frames(): 0=INIT, 1=MODE, 2=CANVAS, 3=ROUTING, 4=EXEC.
-from .blobs import RGB_EXEC, RGB_INIT, RGB_SEC
 from .protocol import base_frames
 
 # Official Redragon software effect menu (order from K617 software).
@@ -61,6 +72,23 @@ EFFECTS = [
     ("off",             ("off",),            0x16, True,  0x00, ""),
 ]
 
+# The base color slot in the MODE frame is effect-specific.  Verified:
+#   fixed-on (0x01)   -> MODE[29..31]   live-tested green on hardware
+#   snake (0x0a)      -> MODE[218,219,220]  live-tested blue on hardware
+#   sine-wave (0x0d)  -> MODE[280..284]-ish: red/green OEM captures moved
+#       bytes [281]=R and [282]=G (byte [280]=0xff constant; B at [283]
+#       inferred since both captured colors had B=0).  Everything else
+#       defaults to the [218..220] slot (snake-verified).
+_COLOR_SLOTS: dict[str, tuple[int, int, int]] = {
+    "fixed-on": (29, 30, 31),
+    "sine-wave": (281, 282, 283),
+}
+
+
+def _color_slot(name: str) -> tuple[int, int, int]:
+    return _COLOR_SLOTS.get(name, (218, 219, 220))
+
+
 EFFECT_ID: dict[str, int] = {n: eid for n, _, eid, *_ in EFFECTS}
 _ALIASES: dict[str, str] = {a: n for n, as_, *_ in EFFECTS for a in as_}
 EFFECT_ACCEPTS_COLOR = {n for n, _, _, ac, *_ in EFFECTS if ac}
@@ -89,11 +117,24 @@ def encode_firmware_effect(
     brightness: int | None = None,
 ) -> list[bytes]:
     """Encode the 5-frame burst (INIT, MODE, CANVAS, ROUTING, EXEC) for an
-    effect.  Patches MODE[29..31] (color), EXEC[21] (effect_id) and
-    EXEC[69]/[71] (speed|brightness nibbles) onto the fw-static baseline.
+    effect.  Patches the effect's MODE color slot, EXEC[21] (effect_id), its
+    EXEC[38+2*(id-1)] RGB/color toggle and the speed/brightness onto the
+    fw-static baseline.
+
+    The color mechanism was established from OEM captures: applying the same
+    effect in red/green/blue differs ONLY at the MODE color slot (snake:
+    MODE[218..220]; sine-wave: MODE[281..283]).  Each effect owns an
+    RGB/color toggle byte at EXEC[38+2*(id-1)]: 0x07 = multicolor animation,
+    0x00 = render the MODE base color instead.  Stock templates bake every
+    toggle to 0x07 (the OEM's "RGB" checkbox is ON by default), which is why
+    colors silently never took effect before — and EXEC[56] is only snake's
+    toggle, not a global one.
 
-    speed/brightness are 0..4 levels (clamped to a nibble); Python ints get
-    clamped.  A color is only applied when the effect accepts one.
+    OEM slider ranges: speed 1..5, brightness 0..4 (5 levels each).  Values
+    are clamped when the user passes them; missing flags keep the template
+    default (so ``off`` at 0x00 is preserved).  A color is only applied when
+    the effect accepts one; when no color is given the baked RGB-mode flag
+    is left untouched.
     """
     name = _canonical(name)
     eid = EFFECT_ID[name]
@@ -102,28 +143,31 @@ def encode_firmware_effect(
     frames = [bytearray(f) for f in base_frames()]
     mode, canvas, routing, exec_ = frames[1], frames[2], frames[3], frames[4]
 
-    if name in EFFECT_ACCEPTS_COLOR:
-        r, g, b = color if color is not None else (255, 0, 0)
-        mode[29], mode[30], mode[31] = r & 0xFF, g & 0xFF, b & 0xFF
+    if color is not None and name in EFFECT_ACCEPTS_COLOR:
+        r, g, b = color[0] & 0xFF, color[1] & 0xFF, color[2] & 0xFF
+        ro, go, bo = _color_slot(name)
+        mode[ro], mode[go], mode[bo] = r, g, b
+        # EXEC[38 + 2*(eid-1)] is this effect's RGB/single-color flag byte
+        # (0x07 = RGB/random, 0x00 = render MODE color).  EXEC[56] is the
+        # snake (eid 10) slot -- not a global toggle, which is why sine stayed
+        # multicolor before the per-effect slot was used.
+        exec_[38 + 2 * (eid - 1)] = 0x00
 
     exec_[21] = eid
 
-    # Byte 39 is the active speed×brightness slot (high nibble = speed,
-    # low nibble = brightness).  The firmware only exposes ~5 levels per axis:
-    # defaults in stock captures are 0x33/0x44 (speed 3/4, brightness 3/4)
-    # and `off` uses 0x00, so a nibble of 4 is max and values above 4 clamp.
-    # Verified by diffing USB captures — previously bytes 69/71 were patched
-    # (a different byte layout); those are ignored by this firmware.
-    target_speed = speed if speed is not None else defaults[0]
-    target_bright = brightness if brightness is not None else defaults[1]
-    new_speed = max(0, min(4, round(target_speed)))
-    new_bright = max(0, min(4, round(target_bright)))
+    # EXEC[39] is the live speed×brightness value (high nibble = speed,
+    # low nibble = brightness).  Evidence: an OEM solid-color capture carries
+    # 0x32 there, the fw-static template 0x34, and the OEM keeps per-effect
+    # remembered values in a 20-slot table at EXEC[39 + 2*(id-1)] (ids 1..20;
+    # the same capture shows saved 0x44 in slot 5 and 0x22 in slot 12).  The
+    # value must land in both places or per-effect speed/brightness is ignored.
+    # Speed is stored 0-based: the OEM displays nibble+1 (hardware-verified).
+    new_speed = (max(1, min(5, round(speed))) - 1) if speed is not None else defaults[0]
+    new_bright = max(0, min(4, round(brightness))) if brightness is not None else defaults[1]
     packed = ((new_speed & 0x0F) << 4) | (new_bright & 0x0F)
     exec_[39] = packed
-    # Mirror into the effect's own table slot (each entry is 2 bytes wide
-    # starting at byte 39; slot[eid] lives at 39 + eid*2).
-    if 1 <= eid <= 19:
-        exec_[39 + eid * 2] = packed
+    if 1 <= eid <= 20:
+        exec_[39 + 2 * (eid - 1)] = packed
 
     return [bytes(frames[0])] + [bytes(f) for f in frames[1:]]
 
@@ -134,7 +178,6 @@ def encode_firmware_effect(
 
 PERKEY_HEADER = bytes.fromhex("080a7a01")
 PERKEY_PACKET_LEN = 382
-SINODRAGON_LED_COUNT = 96
 
 # K617 key name -> position in the 16x6 column-major raster (pos = col*6+row).
 # Rows 1..4 in the 6-row raster hold rows 0..4 of the keyboard; raster row 0

{fizzctl-0.2.0 → fizzctl-0.2.1}/src/fizzctl/hid.py

@@ -16,7 +16,7 @@ import time
 
 import hid
 
-from .protocol import PID, VID
+from .protocol import PID, VID, frame_kind
 
 
 class NoDeviceError(Exception):
@@ -100,17 +100,6 @@ class K617:
         raw = self._dev.get_feature_report(report_id, size)
         return bytes(raw) if raw is not None else bytes(size)
 
-    def send_sequence(self, frames: list[bytes], delay_ms: int = 30) -> None:
-        """Send a list of frames sequentially (init -> data -> commit)."""
-        from time import sleep
-
-        for i, frame in enumerate(frames):
-            kind = _kind(frame)
-            self.send_feature(frame)
-            if self.debug:
-                print(f"  [{i + 1}/{len(frames)}] {kind}")
-            sleep(delay_ms / 1000)
-
     def close(self) -> None:
         if self._dev is not None:
             try:
@@ -161,12 +150,6 @@ def open_device(debug: bool = False) -> K617 | None:
         return None
 
 
-def _kind(frame: bytes) -> str:
-    from .protocol import frame_kind
-
-    return frame_kind(frame)
-
-
 def rgb_sequence(led_colors: dict[int, tuple[int, int, int]]) -> list[bytes]:
     """Build the RGB-write payloads: [INIT, P1(no SEC yet), P2, EXEC].
 
@@ -175,7 +158,7 @@ def rgb_sequence(led_colors: dict[int, tuple[int, int, int]]) -> list[bytes]:
 
     NOTE: the EXEC frame commits to flash (5AA5 magic). Do not loop this.
     """
-    from .blobs import RGB_EXEC, RGB_INIT, RGB_SEC
+    from .blobs import INIT, RGB_EXEC, RGB_SEC
     from .protocol import NAME_TO_INDEX, RESTORE_CONSTANT_FRAMES, set_key_color
 
     canvas = bytearray(1032)
@@ -186,68 +169,29 @@ def rgb_sequence(led_colors: dict[int, tuple[int, int, int]]) -> list[bytes]:
         set_key_color(canvas, idx, rgb)
     canvas[660:660 + len(RGB_SEC)] = RGB_SEC
     p2 = RESTORE_CONSTANT_FRAMES[2]  # routing, never modify
-    return [bytes(RGB_INIT), bytes(canvas), p2, RGB_EXEC]
-
+    return [bytes(INIT), bytes(canvas), p2, RGB_EXEC]
 
-def rgb_all(color: tuple[int, int, int]) -> list[bytes]:
-    from .protocol import LED_INDEX
 
-    return rgb_sequence({idx: color for idx in LED_INDEX})
+def send_burst(dev: K617, frames: list[bytes], handshake: bool = True,
+               delay_ms: int = 60) -> None:
+    """Send an RGB write burst: INIT -> [mandatory GET handshake] -> blocks.
 
-
-def send_rgb(dev: K617, frames: list[bytes]) -> None:
-    """Send the RGB sequence WITH the mandatory GET_REPORT handshake.
-
-    Protocol: INIT -> GET (handshake) -> P1 -> P2 -> EXEC.
-    Without the handshake the firmware silently ignores the writes.
-    """
-    from time import sleep
-
-    init, canvas, p2, exec_ = frames
-    dev.send_feature(init)
-    if dev.debug:
-        print("  [1/4] INIT")
-    sleep(0.06)
-    resp = dev.get_feature(0x06, 1032)  # mandatory handshake
-    if dev.debug:
-        print(f"  [handshake] get_feature(0x06, 1032) -> {len(resp)}B")
-    sleep(0.06)
-    dev.send_feature(canvas)
-    if dev.debug:
-        print("  [2/4] CANVAS")
-    sleep(0.06)
-    dev.send_feature(p2)
-    if dev.debug:
-        print("  [3/4] ROUTING")
-    sleep(0.06)
-    dev.send_feature(exec_)
-    if dev.debug:
-        print("  [4/4] EXEC")
-
-
-# firmware effects + per-key paint (see fizzctl.effects)
-def send_firmware_effect(dev: K617, frames: list[bytes]) -> None:
-    """Send the 5-frame firmware-effect burst WITH the mandatory handshake.
-
-    Protocol: INIT -> GET (handshake) -> MODE -> CANVAS -> ROUTING -> EXEC.
-    The EXEC block commits the effect selection to flash (5AA5 magic).
+    ``handshake=True`` (rgb/effect/key/paint): the firmware ignores the burst
+    unless we poll GET_REPORT(0x06, 1032) after INIT.  ``handshake=False``
+    (keymap/replay) skips it.
     """
     from time import sleep
 
-    init, *blocks = frames
-    dev.send_feature(init)
-    if dev.debug:
-        print("  [1/5] INIT")
-    sleep(0.06)
-    resp = dev.get_feature(0x06, 1032)  # mandatory handshake
-    if dev.debug:
-        print(f"  [handshake] get_feature(0x06, 1032) -> {len(resp)}B")
-    sleep(0.06)
-    for i, block in enumerate(blocks, start=2):
-        dev.send_feature(block)
+    for i, frame in enumerate(frames, start=1):
+        dev.send_feature(frame)
         if dev.debug:
-            print(f"  [{i}/5] {_kind(block)}")
-        sleep(0.06)
+            print(f"  [{i}/{len(frames)}] {frame_kind(frame)}")
+        sleep(delay_ms / 1000)
+        if handshake and i == 1:
+            resp = dev.get_feature(0x06, 1032)
+            if dev.debug:
+                print(f"  [handshake] get_feature(0x06, 1032) -> {len(resp)}B")
+            sleep(delay_ms / 1000)
 
 
 def send_per_key(dev: K617, frame: bytes) -> None:

{fizzctl-0.2.0 → fizzctl-0.2.1}/src/fizzctl/protocol.py

@@ -4,27 +4,18 @@ Nothing in this module talks to hardware; it's pure constants + helpers.
 """
 from __future__ import annotations
 
-from .blobs import CONST_CANVAS, CONST_EXEC, CONST_MODE, CONST_ROUTING, FW_FRAMES
+from .blobs import CONST_CANVAS, CONST_EXEC, CONST_MODE, CONST_ROUTING, FW_TEMPLATE
 
 VID = 0x258A
 PID = 0x0049
 
-# ---- report IDs seen in HID descriptors (interface 1, vendor usage 0xFF00) ----
-REPORT_IDS = [0x05, 0x06, 0x08]
-
-# ---- known frame sizes ----
-SIZE_INIT = 6
-SIZE_BLOCK = 1032
-SIZE_PERKEY = 382
-
 # ---- known-good packet interiors (inlined in blobs.py from captures) ----
-# Index in the static-effect template (FW_FRAMES):
+# Index in the static-effect template (base_frames()):
 #   0 = INIT            (05 83 b6 00 00 00)
 #   1 = mode/config     (06 08 b8 00 40 ...)
 #   2 = RGB canvas base (06 09 bc 00 40 ...)
 #   3 = routing         (06 09 c0 00 40 ...)  — same family as P2, never hand-edit
 #   4 = EXEC/commit     (06 03 b6 00 00 ...)  — contains 5A A5 flash-commit magic
-FRAME_INIT, FRAME_MODE, FRAME_CANVAS, FRAME_ROUTING, FRAME_EXEC = range(5)
 
 # Constant frames of the Restore sequence (06 xx xx 00 40 ...), 1032 bytes each.
 RESTORE_CONSTANT_FRAMES: list[bytes] = [
@@ -35,13 +26,9 @@ RESTORE_CONSTANT_FRAMES: list[bytes] = [
 ]
 
 
-def base_frames(effect: str = "fw-static") -> list[bytes]:
-    """Return the captured static-effect frame template.
-
-    `effect` is accepted for API compatibility; only the built-in template is
-    shipped (no data files on disk anymore).
-    """
-    return [bytes(f) for f in FW_FRAMES]
+def base_frames() -> list[bytes]:
+    """Return the captured static-effect frame template."""
+    return [bytes(f) for f in FW_TEMPLATE]
 
 
 def frame_kind(frame: bytes) -> str:

fizzctl-0.2.0/pyproject.toml.orig

@@ -1,46 +0,0 @@
-[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