fizzctl 0.2.0__py3-none-any.whl

fizzctl/cli.py

@@ -0,0 +1,409 @@
+"""fizzctl — command-line interface.
+
+User commands (``fizzctl``):
+    fizzctl rgb <color> [--brightness N]  # whole-board solid color (flash write)
+    fizzctl effect <name>            # firmware-native effect (FLASH WRITE)
+    fizzctl key <key> <color>        # paint one key (FLASH WRITE)
+    fizzctl paint <key>=<color>...   # paint many keys (FLASH WRITE)
+    fizzctl animate <name>           # host-side animation (volatile stream)
+    fizzctl keymap <Cfg.ini>           # write full keymap from Cfg.ini (FLASH WRITE)
+    fizzctl setup-udev               # install 99-k617.rules (needs root)
+
+Dev commands (``fizzctl-dev``, reverse-engineering toolkit):
+    fizzctl-dev list
+    fizzctl-dev cfg <Cfg.ini>
+    fizzctl-dev inspect <cap.json>
+    fizzctl-dev diff <capA.json> <capB.json>
+    fizzctl-dev export <cap.json> <frames.json>
+    fizzctl-dev replay <frames.json> [--delay-ms N]
+    plus every user command above
+"""
+from __future__ import annotations
+
+import argparse
+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 .keymap import KeymapEncoder
+from .protocol import RESTORE_CONSTANT_FRAMES
+
+
+def cmd_list(_):
+    import hid
+    from .protocol import PID, VID
+
+    for d in hid.enumerate(VID, PID):
+        print(d["path"], "iface", d.get("interface_number"), "usage", hex(d.get("usage_page", 0)))
+    if not hid.enumerate(VID, PID):
+        print("no K617 found (is it plugged in?)")
+
+
+def cmd_cfg(args):
+    cfg = CfgIni(args.cfg)
+    print(f"[FN] {len(cfg.fn)} entries")
+    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)} entries")
+    for idx, e in cfg.key_entries:
+        print(f"  K{idx:<3} matrix={e.matrix} {', '.join(f'0x{b:02X}' for b in e.behavior)}")
+
+
+def cmd_inspect(args):
+    recs = load_tshark_json(args.capture)
+    out = significant(recs)
+    print(f"{len(recs)} USB records, {len(out)} host->device writes")
+    for r in out:
+        print(" ", r)
+
+
+def cmd_diff(args):
+    a = load_tshark_json(args.a)
+    b = load_tshark_json(args.b)
+    changes = diff_captures(a, b)
+    print(f"aligned {len(significant(a))} vs {len(significant(b))} writes; {len(changes)} differ")
+    for c in changes:
+        print(f"\nframe {c['frame']}: {c['kind_a']} ({c['len_a']}B) -> {c['kind_b']} ({c['len_b']}B), "
+              f"{c['diff_count']} bytes differ")
+        for off, ca, cb in c["offsets"]:
+            print(f"   +{off:#06x}  {ca:>2} -> {cb:>2}")
+    if not changes:
+        print("no differences — both captures identical")
+
+
+def cmd_export(args):
+    recs = load_tshark_json(args.capture)
+    export_frames(recs, args.out)
+
+
+def cmd_replay(args):
+    frames = load_frames(args.frames)
+    print(f"{len(frames)} frames loaded from {args.frames}")
+    for i, f in enumerate(frames):
+        from .protocol import frame_kind
+        print(f"  {i}: {frame_kind(f)} ({len(f)}B)")
+    try:
+        dev = open_device(debug=args.debug)
+    except NoDeviceError:
+        return 1
+    if dev is None:
+        return 1
+    try:
+        dev.send_sequence(frames, delay_ms=args.delay_ms)
+    finally:
+        dev.close()
+    return 0
+
+
+def cmd_keymap(args):
+    cfg = CfgIni(args.cfg)
+    keymap = KeymapEncoder(cfg).build()
+    # exact capture order: INIT, INIT, MODE, CANVAS, ROUTING, KEYMAP, EXEC
+    frames = [
+        bytes.fromhex("050581000000"),       # INIT
+        bytes.fromhex("0583b6000000"),       # INIT
+        RESTORE_CONSTANT_FRAMES[0],          # MODE
+        RESTORE_CONSTANT_FRAMES[1],          # CANVAS
+        RESTORE_CONSTANT_FRAMES[2],          # ROUTING
+        keymap,                               # 06 04 d4 keymap block
+        RESTORE_CONSTANT_FRAMES[3],          # EXEC (5AA5 commit)
+    ]
+    if args.debug:
+        print(f"built {len(frames)} frames from {args.cfg}")
+        print(f"  keymap block: {len(keymap)}B, must equal 1032")
+    if len(keymap) != 1032:
+        print("error: keymap block is not 1032 bytes")
+        return 1
+    try:
+        dev = open_device(debug=args.debug)
+    except NoDeviceError:
+        return 1
+    if dev is None:
+        return 1
+    try:
+        dev.send_sequence(frames, delay_ms=args.delay_ms)
+    finally:
+        dev.close()
+    print(f"wrote keymap from {args.cfg} to flash")
+    return 0
+
+
+def cmd_rgb(args):
+    """Shortcut for `effect fixed-on <color>` (whole-board solid color).
+
+    Examples:
+        fizzctl rgb ff0000
+        fizzctl rgb 00ff00 --brightness 4
+    """
+    args.name = "fixed-on"
+    args.speed = None
+    return cmd_effect(args)
+
+
+def cmd_effect(args):
+    """Run a firmware-native effect (flash write).
+
+    Examples:
+        fizzctl effect rainbow                 # default speed/brightness
+        fizzctl effect rainbow --speed 2 --brightness 4
+        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
+
+    name = args.name
+    if name is None:
+        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]
+            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
+
+    color = None
+    if args.color:
+        color = parse_color(args.color)
+        if color is None:
+            print(f"bad color {args.color!r}: use a name or hex")
+            return 1
+
+    frames = encode_firmware_effect(name, color, speed=args.speed, brightness=args.brightness)
+    try:
+        dev = open_device(debug=args.debug)
+    except NoDeviceError:
+        return 1
+    if dev is None:
+        return 1
+    try:
+        send_firmware_effect(dev, frames)
+    finally:
+        dev.close()
+    desc = f"effect {name}"
+    if color:
+        desc += f" (color=#{color[0]:02x}{color[1]:02x}{color[2]:02x})"
+    if args.speed is not None or args.brightness is not None:
+        desc += f" (speed={args.speed}, brightness={args.brightness})"
+    print(f"applied {desc}")
+    return 0
+
+
+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
+
+
+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 .protocol import NAME_TO_INDEX
+
+    colors = {}
+    for spec in args.specs:
+        if "=" not in spec:
+            print(f"bad spec {spec!r}: expected KEY=COLOR")
+            return 1
+        key, c = spec.split("=", 1)
+        if key not in NAME_TO_INDEX:
+            print(f"unknown key {key!r}")
+            return 1
+        color = parse_color(c)
+        if color is None:
+            print(f"bad color {c!r}")
+            return 1
+        colors[key] = color
+    frames = rgb_sequence(colors)
+    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 {len(colors)} keys")
+    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",
+        description="Redragon K617 Fizz controller"
+        if not dev
+        else "Redragon K617 reverse-engineering toolkit (dev)",
+    )
+    p.add_argument("--debug", action="store_true", help="verbose frame-level logging")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    if dev:
+        sub.add_parser("list", help="list K617 HID interfaces")
+        pc = sub.add_parser("cfg", help="parse and dump a Cfg.ini")
+        pc.add_argument("cfg")
+        pi = sub.add_parser("inspect", help="summarise a tshark JSON capture")
+        pi.add_argument("capture")
+        pd = sub.add_parser("diff", help="diff two tshark JSON captures")
+        pd.add_argument("a")
+        pd.add_argument("b")
+        pe = sub.add_parser("export", help="extract host->device writes to frames.json")
+        pe.add_argument("capture")
+        pe.add_argument("out")
+        pr = sub.add_parser("replay", help="replay exported frames via hidapi")
+        pr.add_argument("frames")
+        pr.add_argument("--delay-ms", type=int, default=30)
+
+    px = sub.add_parser("rgb",
+                      help="solid color: rgb red -b 4 (shortcut for `effect fixed-on`)",
+                      description="""
+Examples:
+  fizzctl rgb red
+  fizzctl rgb ff0000 --brightness 4
+  fizzctl rgb green -b 3
+""".rstrip(),
+                      formatter_class=argparse.RawDescriptionHelpFormatter)
+    px.add_argument("color")
+    px.add_argument("-b", "--brightness", type=int, help="0..4 (level; higher = brighter)")
+
+    peff = sub.add_parser("effect",
+                          help="run a firmware-native effect (flash write); run without a name to list all",
+                          description="""
+Examples:
+  fizzctl effect rainbow                      # defaults from stock config
+  fizzctl effect rainbow --speed 2 --brightness 4
+  fizzctl effect waterfall --color cyan
+  fizzctl effect                              # lists all 22 effects
+""".rstrip(),
+                          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("-b", "--brightness", type=int, help="0..4 (level; higher = brighter)")
+
+    pk = sub.add_parser("key",
+                        help="paint one key: key W red (flash write)",
+                        description="""
+Examples:
+  fizzctl key W ff0000
+  fizzctl key A yellow
+""".rstrip(),
+                        formatter_class=argparse.RawDescriptionHelpFormatter)
+    pk.add_argument("key")
+    pk.add_argument("color")
+
+    pp = sub.add_parser("paint",
+                        help="paint many keys: paint W=ff0000 A=00ff00 (flash write)",
+                        description="""
+Examples:
+  fizzctl paint W=ff0000 A=00ff00 S=ffff00 D=ff00ff
+  fizzctl paint W=red A=orange S=yellow D=green
+""".rstrip(),
+                        formatter_class=argparse.RawDescriptionHelpFormatter)
+    pp.add_argument("specs", nargs="+")
+
+    pa = sub.add_parser("animate",
+                        help="host-side per-key animation: animate chase -c red -s 2 (volatile stream)",
+                        description="""
+Examples:
+  fizzctl animate rainbow --fps 30 --duration 10
+  fizzctl animate chase --color yellow --speed 2
+  fizzctl animate solid --color ff0000
+  fizzctl animate                                 # lists all animations
+""".rstrip(),
+                        formatter_class=argparse.RawDescriptionHelpFormatter)
+    pa.add_argument("name", nargs="?",
+                    help="animation name (omit or run `animate` alone to list all)")
+    pa.add_argument("-c", "--color", default="ff0000", help="base color (name or hex)")
+    pa.add_argument("-s", "--speed", type=float, default=1.0, help="animation speed multiplier")
+    pa.add_argument("-f", "--fps", type=int, default=30, help="frames per second")
+    pa.add_argument("--duration", type=float, help="stop after N seconds (default: until Ctrl+C)")
+
+    prs = sub.add_parser("keymap",
+                        help="write the keymap from a Cfg.ini: keymap Cfg.ini (flash write)",
+                        description="""
+Examples:
+  fizzctl keymap captures/cfg-runs/cfg_r2_stock.ini
+""".rstrip(),
+                        formatter_class=argparse.RawDescriptionHelpFormatter)
+    prs.add_argument("cfg")
+    prs.add_argument("--delay-ms", type=int, default=30)
+
+    psudev = sub.add_parser("setup-udev", help="install 99-k617.rules + reload udev (needs root)")
+
+    return p
+
+
+def main(dev: bool = False) -> int:
+    p = _build_parser(dev)
+    args = p.parse_args()
+
+    fn = {
+        "list": cmd_list, "cfg": cmd_cfg, "inspect": cmd_inspect,
+        "diff": cmd_diff, "export": cmd_export, "replay": cmd_replay,
+        "rgb": cmd_rgb, "effect": cmd_effect, "key": cmd_key,
+        "paint": cmd_paint, "animate": cmd_animate, "keymap": cmd_keymap,
+        "setup-udev": cmd_setup_udev,
+    }[args.cmd]
+    return fn(args)
+
+
+def main_dev() -> int:
+    """Dev entry point: full toolkit including capture/RE tools."""
+    return main(dev=True)
+
+
+def cmd_setup_udev(args) -> int:
+    from .udev_rules import install_udev_rules
+
+    return install_udev_rules()
+
+
+if __name__ == "__main__":
+    sys.exit(main_dev())

fizzctl/effects.py

@@ -0,0 +1,223 @@
+"""Firmware-native effects and the Sinodragon per-key protocol.
+
+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)
+  Sending requires the mandatory GET_REPORT(0x06, 1032) handshake after INIT
+  (without it the firmware silently ignores the burst).
+
+* 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
+  every frame for animations.  Verified on hardware: Esc=1, Menu=77, RCtrl=83
+  (an earlier mapping had Esc=0/Menu=65/RCtrl=71, which lands on dead
+  positions).
+"""
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Firmware effects
+# ---------------------------------------------------------------------------
+
+# 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).
+# The effect id byte at EXEC[21] equals the 1-indexed position in that menu:
+# 8 independently-captured effects all land exactly
+# on their menu position (Fixed_on=0x01, Rainbow=0x03, ... Blossom=0x11), so
+# the un-captured ids are inferred by position and marked ``pending-live-verify``.
+# ``name`` is the canonical slug; ``aliases`` keep old short names working.
+EFFECTS = [
+    # (name,            aliases,             id,   accepts_color, default_sb,  notes)
+    ("fixed-on",        ("static",),         0x01, True,  0x33, ""),
+    ("respire",         (),                  0x02, True,  0x33, ""),
+    ("rainbow",         (),                  0x03, True,  0x33, ""),
+    ("flash-away",      (),                  0x04, True,  0x33, ""),
+    ("raindrops",       (),                  0x05, True,  0x33, ""),
+    ("rainbow-wheel",   ("wheel",),          0x06, True,  0x33, ""),
+    ("ripples-shining", (),                  0x07, True,  0x33, ""),
+    ("stars-twinkle",   ("star-twinkle",),   0x08, True,  0x33, ""),
+    ("shadow-disappear", (),                 0x09, True,  0x33, ""),
+    ("retro-snake",     ("snake",),          0x0a, True,  0x44, ""),
+    ("neon-stream",     (),                  0x0b, True,  0x44, ""),
+    ("reaction",        (),                  0x0c, True,  0x44, ""),
+    ("sine-wave",       (),                  0x0d, True,  0x44, ""),
+    ("retinue-scanning", (),                 0x0e, True,  0x44, ""),
+    ("rotating-windmill", (),                0x0f, True,  0x33, ""),
+    ("colorful-waterfall", ("waterfall",),   0x10, True,  0x33, ""),
+    ("blossoming",      ("rainbow-blossom",), 0x11, True,  0x44, ""),
+    ("rotating-storm",  (),                  0x12, True,  0x33, ""),
+    ("collision",       (),                  0x13, True,  0x33, ""),
+    ("perfect",         (),                  0x14, True,  0x33, ""),
+    ("self-define",     (),                  0x15, True,  0x33, ""),
+    ("off",             ("off",),            0x16, True,  0x00, ""),
+]
+
+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}
+EFFECT_DEFAULTS = {n: (sb >> 4, sb & 0x0F) for n, _, _, _, sb, *_ in EFFECTS}
+
+
+def _canonical(name: str) -> str:
+    if name in EFFECT_ID:
+        return name
+    canon = _ALIASES.get(name)
+    if canon is None:
+        raise ValueError(
+            f"unknown effect {name!r}; choose from {', '.join(effect_names())}"
+        )
+    return canon
+
+
+def effect_names() -> list[str]:
+    return list(EFFECT_ID)
+
+
+def encode_firmware_effect(
+    name: str,
+    color: tuple[int, int, int] | None = None,
+    speed: int | None = None,
+    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.
+
+    speed/brightness are 0..4 levels (clamped to a nibble); Python ints get
+    clamped.  A color is only applied when the effect accepts one.
+    """
+    name = _canonical(name)
+    eid = EFFECT_ID[name]
+    defaults = EFFECT_DEFAULTS[name]
+
+    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
+
+    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)))
+    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
+
+    return [bytes(frames[0])] + [bytes(f) for f in frames[1:]]
+
+
+# ---------------------------------------------------------------------------
+# Per-key (Sinodragon) protocol — 382-byte single report
+# ---------------------------------------------------------------------------
+
+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
+# is "phantom"/unused except Esc which lives at col0/row1 (=1), NOT 0.
+# All verified on hardware except where noted.
+PER_KEY_POS = {
+    # Row 0 — number row
+    "Esc": 1, "1": 7, "2": 13, "3": 19, "4": 25,
+    "5": 31, "6": 37, "7": 43, "8": 49, "9": 55,
+    "0": 61, "-": 67, "=": 73, "Bksp": 79,
+    # Row 1 — QWERTY
+    "Tab": 2,
+    "Q": 8, "W": 14, "E": 20, "R": 26, "T": 32, "Y": 38,
+    "U": 44, "I": 50, "O": 56, "P": 62, "[": 68, "]": 74, "\\": 80,
+    # Row 2 — home row
+    "CapsLk": 3,
+    "A": 9, "S": 15, "D": 21, "F": 27, "G": 33, "H": 39,
+    "J": 45, "K": 51, "L": 57, ";": 63, "'": 69, "Enter": 81,
+    # Row 3 — bottom row
+    "LShift": 4,
+    "Z": 10, "X": 16, "C": 22, "V": 28, "B": 34, "N": 40,
+    "M": 46, ",": 52, ".": 58, "/": 64, "RShift": 82,
+    # Row 4 — modifier row
+    "LCtrl": 5, "LWin": 11, "LAlt": 17, "Space": 35, "RAlt": 53,
+    "Fn": 59, "Menu": 77, "RCtrl": 83,
+}
+
+
+def encode_per_key_frame(colors: dict[str, tuple[int, int, int]] | None = None) -> bytes:
+    """Build the single 382-byte per-key report.  `colors` maps key name ->
+    (r,g,b); keys not listed light as off.  `None` = all keys black."""
+    frame = bytearray(PERKEY_PACKET_LEN)
+    frame[0:4] = PERKEY_HEADER
+    for key, (r, g, b) in (colors or {}).items():
+        pos = PER_KEY_POS.get(key)
+        if pos is None:
+            raise KeyError(f"unknown key {key!r} for per-key paint")
+        off = 4 + pos * 3
+        frame[off], frame[off + 1], frame[off + 2] = r & 0xFF, g & 0xFF, b & 0xFF
+    return bytes(frame)
+
+
+def encode_per_key_solid(color: tuple[int, int, int]) -> bytes:
+    return encode_per_key_frame({key: color for key in PER_KEY_POS})
+
+
+def parse_color(s: str) -> tuple[int, int, int] | None:
+    """Parse a color name or hex string into (r, g, b)."""
+    named = {
+        # primary
+        "red": (255, 0, 0), "green": (0, 255, 0), "blue": (0, 0, 255),
+        # secondary
+        "yellow": (255, 255, 0), "cyan": (0, 255, 255), "magenta": (255, 0, 255),
+        "purple": (128, 0, 255), "orange": (255, 165, 0), "pink": (255, 105, 180),
+        "lime": (191, 255, 0), "teal": (0, 128, 128), "violet": (238, 130, 238),
+        "brown": (165, 42, 42), "gold": (255, 215, 0), "silver": (192, 192, 192),
+        "gray": (128, 128, 128), "grey": (128, 128, 128),
+        "navy": (0, 0, 128), "maroon": (128, 0, 0), "olive": (128, 128, 0),
+        "coral": (255, 127, 80), "indigo": (75, 0, 130), "salmon": (250, 128, 114),
+        # light / shades
+        "lightred": (255, 102, 102), "lightgreen": (144, 238, 144),
+        "lightblue": (173, 216, 230),
+        "darkred": (139, 0, 0), "darkgreen": (0, 100, 0), "darkblue": (0, 0, 139),
+        # neutral
+        "white": (255, 255, 255), "off": (0, 0, 0), "black": (0, 0, 0),
+    }
+    s = s.strip().lstrip("#")
+    key = s.lower().replace("_", "").replace("-", "").replace(" ", "")
+    if key in named:
+        return named[key]
+    if len(s) == 6:
+        try:
+            return (int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16))
+        except ValueError:
+            return None
+    return None
+
+
+# Re-export the RGB canvas pieces used by the "static canvas" path so callers
+# only need one import site.
+__all__ = [
+    "EFFECTS", "EFFECT_ID", "EFFECT_ACCEPTS_COLOR", "EFFECT_DEFAULTS",
+    "effect_names", "encode_firmware_effect", "PERKEY_HEADER",
+    "PERKEY_PACKET_LEN", "PER_KEY_POS",
+    "encode_per_key_frame", "encode_per_key_solid",
+]