fizzctl 0.3.0__tar.gz → 0.4.0__tar.gz

{fizzctl-0.3.0 → fizzctl-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: fizzctl
-Version: 0.3.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
+Version: 0.4.0
+Summary: Control a Redragon K617 Fizz keyboard on Linux: solid colors, 22 firmware-native RGB effects, per-key painting, live animations, on-device key macros, 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>
@@ -20,8 +20,9 @@ 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.
+Control a Redragon K617 Fizz keyboard on Linux: solid colors, 22 firmware-native
+RGB effects, per-key painting, live animations, on-device key macros with a
+readable back, and `Cfg.ini` keymap restore — no vendor software required.
 
 ## Install
 
@@ -59,7 +60,7 @@ the trigger did not pick it up.
 | `key` | Paint a single key | yes |
 | `paint` | Paint multiple keys at once | yes |
 | `keymap` | Write the keymap from a Cfg.ini | yes |
-| `macro` | Bind a key that types text on press | yes |
+| `macro` | Bind a key that types text, `--remove-all`, or `--read` | yes |
 | `restore` | Reset to the factory keymap, lighting and macros | yes |
 | `animate` | Host-streamed animation (volatile) | no |
 
@@ -102,9 +103,13 @@ fizzctl macro --key 2 --until-released aaaa
 
 Options: `--delay-ms` (default 30) is the delay between typed events,
 `--cycles` (default 1) plays the macro that many times per press, and
-`--until-released` types in a loop until the key is let go. Macros and their
-bindings are remembered in a local state file (`$XDG_STATE_HOME/fizzctl/`)
-so later macro/keymap writes never drop them. To undo:
+`--until-released` types in a loop until the key is let go. Macros are read
+straight back off the keyboard's flash: each write reads the current keymap
+and macro table first, patches them, and writes the full table back — so
+later macro/keymap writes never drop your existing macros, and nothing is
+saved on the host. `fizzctl macro --read` dumps the on-device table back,
+each slot shown with the key(s) bound to it and whether it repeats until the
+key is released. To undo:
 
 ```bash
 fizzctl macro --remove-all          # unbind every macro, keep keymap + lighting

{fizzctl-0.3.0 → fizzctl-0.4.0}/README.md

@@ -1,7 +1,8 @@
 # fizzctl
 
-Linux tool for controlling the Redragon K617 Fizz keyboard's RGB lighting
-and restoring keymaps from `Cfg.ini` files.
+Control a Redragon K617 Fizz keyboard on Linux: solid colors, 22 firmware-native
+RGB effects, per-key painting, live animations, on-device key macros with a
+readable back, and `Cfg.ini` keymap restore — no vendor software required.
 
 ## Install
 
@@ -39,7 +40,7 @@ the trigger did not pick it up.
 | `key` | Paint a single key | yes |
 | `paint` | Paint multiple keys at once | yes |
 | `keymap` | Write the keymap from a Cfg.ini | yes |
-| `macro` | Bind a key that types text on press | yes |
+| `macro` | Bind a key that types text, `--remove-all`, or `--read` | yes |
 | `restore` | Reset to the factory keymap, lighting and macros | yes |
 | `animate` | Host-streamed animation (volatile) | no |
 
@@ -82,9 +83,13 @@ fizzctl macro --key 2 --until-released aaaa
 
 Options: `--delay-ms` (default 30) is the delay between typed events,
 `--cycles` (default 1) plays the macro that many times per press, and
-`--until-released` types in a loop until the key is let go. Macros and their
-bindings are remembered in a local state file (`$XDG_STATE_HOME/fizzctl/`)
-so later macro/keymap writes never drop them. To undo:
+`--until-released` types in a loop until the key is let go. Macros are read
+straight back off the keyboard's flash: each write reads the current keymap
+and macro table first, patches them, and writes the full table back — so
+later macro/keymap writes never drop your existing macros, and nothing is
+saved on the host. `fizzctl macro --read` dumps the on-device table back,
+each slot shown with the key(s) bound to it and whether it repeats until the
+key is released. To undo:
 
 ```bash
 fizzctl macro --remove-all          # unbind every macro, keep keymap + lighting

{fizzctl-0.3.0 → fizzctl-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "fizzctl"
-version = "0.3.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"
+version = "0.4.0"
+description = "Control a Redragon K617 Fizz keyboard on Linux: solid colors, 22 firmware-native RGB effects, per-key painting, live animations, on-device key macros, and Cfg.ini keymap restore — no vendor software required"
 readme = "README.md"
 keywords = [
     "redragon",

{fizzctl-0.3.0 → fizzctl-0.4.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "fizzctl"
-version = "0.3.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"
+version = "0.4.0"
+description = "Control a Redragon K617 Fizz keyboard on Linux: solid colors, 22 firmware-native RGB effects, per-key painting, live animations, on-device key macros, and Cfg.ini keymap restore — no vendor software required"
 readme = "README.md"
 license = { text = "MIT" }
 authors = [{ name = "Ayoub Dya", email = "ayoubdya@gmail.com" }]

{fizzctl-0.3.0 → fizzctl-0.4.0}/src/fizzctl/__init__.py

@@ -7,4 +7,4 @@ by :func:`main_dev` via the ``fizzctl-dev`` console script.
 from .cli import main, main_dev
 
 __all__ = ["main", "main_dev"]
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{fizzctl-0.3.0 → fizzctl-0.4.0}/src/fizzctl/blobs.py

@@ -7,8 +7,9 @@ All constants come from USB captures of the OEM software:
     a distinct CANVAS, and five byte overrides of CONST_EXEC.
   * RGB_EXEC / RGB_SEC — the whole-board solid-color variant.
   * CONST_KEYMAP — a clean 1032-byte 06 04 d4 keymap block (no macro
-    bindings), captured from the device.  The macro command uses it as the
-    default base; KeymapEncoder can rebuild the same block from a Cfg.ini.
+    bindings), captured from the device.  Used as the fallback base when the
+    device's keymap cannot be read; KeymapEncoder can rebuild the same block
+    from a Cfg.ini.
 """
 
 

{fizzctl-0.3.0 → fizzctl-0.4.0}/src/fizzctl/cli.py

@@ -9,6 +9,7 @@ User commands (``fizzctl``):
     fizzctl keymap <Cfg.ini>           # write full keymap from Cfg.ini (FLASH WRITE)
     fizzctl restore                  # restore factory keymap+lighting (FLASH WRITE)
     fizzctl macro --key K <text>     # bind a macro that types text (FLASH WRITE)
+    fizzctl macro --read             # dump on-device macros + their key bindings
     fizzctl setup-udev               # install 99-k617.rules (needs root)
 
 Dev commands (``fizzctl-dev``, reverse-engineering toolkit):
@@ -29,7 +30,7 @@ from pathlib import Path
 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 NoDeviceError, open_device, read_keymap, read_lighting, send_burst
+from .hid import NoDeviceError, open_device, read_keymap, read_lighting, read_macro, send_burst
 from .keymap import KeymapEncoder
 from .protocol import RESTORE_CONSTANT_FRAMES
 
@@ -129,68 +130,28 @@ def _live_keymap(dev, debug: bool = False) -> bytes:
         return bytes(CONST_KEYMAP)
 
 
-def _apply_bindings(keymap: bytearray, bindings: dict,
-                    cache: dict | None = None) -> list[str]:
-    """Patch every cached macro binding into ``keymap`` in place; return the
-    keys that could not be found.
+def _live_macro(dev, debug: bool = False) -> bytes:
+    """Read the device's current macro table so a write keeps every slot;
+    fall back to an empty table if the read fails."""
+    from .macro import build_macro_frame
+    try:
+        return read_macro(dev)
+    except Exception as e:                   # keep working on read failure
+        if debug:
+            print(f"  could not read macro table ({e}); using empty table")
+        return build_macro_frame({})
 
-    A binding the device already has (a ``10`` record echoed in the read-back)
-    counts as applied even though :func:`bind_macro` cannot rediscover it.
-    When ``cache`` is given, each binding also records the key's original
-    record and offset so it can be restored later (``--remove-all``).
-    """
-    from .blobs import CONST_KEYMAP
-    from .macro import NAME_TO_HID, bind_macro, find_binding, locate_key
-    missed = []
-    for key, info in bindings.items():
-        hid = NAME_TO_HID.get(key)
-        if hid is None:
-            missed.append(key)
-            continue
-        slot = int(info["slot"])
-        mode = int(info["mode"])
-        off = locate_key(keymap, hid)
-        if off is not None:
-            if cache is not None:
-                cache["bindings"][key]["offset"] = off
-                cache["bindings"][key]["record"] = bytes(keymap[off:off + 4]).hex()
-            bind_macro(keymap, hid, slot, mode)
-        else:
-            off = find_binding(keymap, slot, mode)
-            if off is None:
-                missed.append(key)
-            elif cache is not None and cache["bindings"][key].get("record") is None:
-                # already bound in the read-back: remember where, and fall back
-                # to the stock record as the best guess for the original
-                cache["bindings"][key]["offset"] = off
-                cache["bindings"][key]["record"] = bytes(CONST_KEYMAP[off:off + 4]).hex()
-    return missed
-
-
-def _strip_bindings(keymap: bytearray, cache: dict) -> int:
-    """Restore the original records of cached macro bindings in ``keymap``.
-
-    Returns how many records were restored.  Bindings without a recorded
-    original (created before this feature) fall back to the stock record for
-    their offset.
-    """
+
+def _binding_for_hid(keymap, hid: int) -> tuple[int, int] | None:
+    """``(offset, slot)`` of the macro binding whose stock record outputs
+    ``hid`` — i.e. which bound physical key this is."""
     from .blobs import CONST_KEYMAP
-    from .macro import find_binding
-    n = 0
-    for info in cache["bindings"].values():
-        off = info.get("offset")
-        rec = info.get("record")
-        if isinstance(off, int) and isinstance(rec, str) and len(rec) == 8:
-            original = bytes.fromhex(rec)
-            if keymap[off:off + 4] != original:
-                keymap[off:off + 4] = original
-                n += 1
-            continue
-        off = find_binding(keymap, int(info["slot"]), int(info["mode"]))
-        if off is not None:
-            keymap[off:off + 4] = bytes(CONST_KEYMAP[off:off + 4])
-            n += 1
-    return n
+    from .macro import collect_bindings
+    for off, _mode, slot in collect_bindings(keymap):
+        rec = CONST_KEYMAP[off:off + 4]
+        if rec[0] in (0x00, 0x06) and rec[3] == (hid & 0xFF):
+            return off, slot
+    return None
 
 
 def cmd_macro_remove_all(args):
@@ -202,13 +163,9 @@ def cmd_macro_remove_all(args):
     Examples:
         fizzctl macro --remove-all
     """
-    from . import state
-    from .macro import build_macro_frame
+    from .blobs import CONST_KEYMAP
+    from .macro import build_macro_frame, collect_bindings, slots_in_frame
 
-    cache = state.load()
-    if not cache["slots"] and not cache["bindings"]:
-        print("no macros to remove")
-        return 0
     try:
         dev = open_device(debug=args.debug)
     except NoDeviceError:
@@ -218,7 +175,13 @@ def cmd_macro_remove_all(args):
     try:
         mode_f, canvas_f, routing_f, exec_f = _live_lighting(dev, args.debug)
         base = bytearray(_live_keymap(dev, args.debug))
-        removed = _strip_bindings(base, cache)
+        live_mf = _live_macro(dev, args.debug)
+        bindings = collect_bindings(base)
+        if not bindings and not slots_in_frame(live_mf):
+            print("no macros to remove")
+            return 0
+        for off, _mode, _slot in bindings:
+            base[off:off + 4] = bytes(CONST_KEYMAP[off:off + 4])
         frames = [
             bytes.fromhex("0583b6000000"),   # INIT
             mode_f, canvas_f, routing_f,     # current lighting (kept)
@@ -229,35 +192,27 @@ def cmd_macro_remove_all(args):
         send_burst(dev, frames, handshake=False, delay_ms=args.burst_ms)
     finally:
         dev.close()
-    state.save({"slots": {}, "bindings": {}})
-    print(f"removed {removed} macro binding(s) and cleared all macro slots")
+    print(f"removed {len(bindings)} macro binding(s) and cleared all macro slots")
     return 0
 
 
 def cmd_keymap(args):
     """Write a full keymap from a Cfg.ini (flash write).
 
-    Previously created macros are re-applied on top, and the current lighting
-    (effect, color, brightness) is kept.
+    Existing macro bindings and slots are read back from the device and
+    re-applied on top, and the current lighting (effect, color, brightness)
+    is kept.
 
     Examples:
         fizzctl keymap cfgs/cfg_final.ini
     """
-    from . import state
-    from .macro import build_macro_frame
+    from .blobs import CONST_KEYMAP
+    from .macro import collect_bindings, relocate_bindings, slots_in_frame
 
     keymap = bytearray(KeymapEncoder(CfgIni(args.cfg)).build())
     if len(keymap) != 1032:
         print("error: keymap block is not 1032 bytes")
         return 1
-    cache = state.load()
-    missed = _apply_bindings(keymap, cache["bindings"])
-    if args.debug:
-        print(f"built keymap from {args.cfg}")
-        if cache["slots"]:
-            print(f"  re-applying {len(cache['bindings'])} macro binding(s)")
-    if missed:
-        print(f"warning: could not bind {', '.join(missed)} in this keymap")
     try:
         dev = open_device(debug=args.debug)
     except NoDeviceError:
@@ -266,14 +221,22 @@ def cmd_keymap(args):
         return 1
     try:
         mode, canvas, routing, exec_ = _live_lighting(dev, args.debug)
+        live_km = _live_keymap(dev, args.debug)
+        live_mf = _live_macro(dev, args.debug)
+        keymap, warnings = relocate_bindings(live_km, keymap, CONST_KEYMAP)
+        for w in warnings:
+            print(f"warning: {w}")
+        nb = len(collect_bindings(live_km))
+        if args.debug:
+            print(f"built keymap from {args.cfg} (re-applied {nb} macro binding(s))")
         # exact capture order, but with the device's live lighting blocks
         frames = [
             bytes.fromhex("050581000000"),       # INIT
             bytes.fromhex("0583b6000000"),       # INIT
             mode, canvas, routing,                # current lighting
         ]
-        if cache["slots"]:
-            frames.append(build_macro_frame(state.raw_slots(cache)))
+        if slots_in_frame(live_mf):
+            frames.append(live_mf)                # 06 05 dc (slots kept)
         frames += [
             bytes(keymap),                        # 06 04 d4 keymap block
             exec_,                                # EXEC (5AA5 commit)
@@ -300,7 +263,6 @@ def cmd_restore(args):
     Examples:
         fizzctl restore
     """
-    from . import state
     from .macro import build_macro_frame
 
     keymap = bytearray(KeymapEncoder(CfgIni(_stock_cfg())).build())
@@ -326,11 +288,71 @@ def cmd_restore(args):
         send_burst(dev, frames, handshake=False, delay_ms=args.delay_ms)
     finally:
         dev.close()
-    state.save({"slots": {}, "bindings": {}})
     print("restored factory keymap, lighting and macros")
     return 0
 
 
+def cmd_macro_read(args):
+    """Read the on-device macro table back (dev tool).
+
+    Shows every non-empty slot with the key(s) bound to it (a slot can be
+    shared) and the events it types.  Since the keymap is read alongside the
+    macro table, bindings are identified by the stock record at their live
+    offset (the CONST_KEYMAP oracle), and keys bound with ``--until-released``
+    are flagged as such.
+
+    Examples:
+        fizzctl macro --read
+    """
+    from .blobs import CONST_KEYMAP
+    from .macro import MAX_SLOTS, MODE_UNTIL_RELEASED, NAME_TO_HID, \
+        SLOT_BASE, SLOT_STRIDE, collect_bindings, decode_slot
+
+    names = {hid: name for name, hid in NAME_TO_HID.items()}
+    try:
+        dev = open_device(debug=args.debug)
+    except NoDeviceError:
+        return 1
+    if dev is None:
+        return 1
+    try:
+        frame = read_macro(dev)
+        keymap = read_keymap(dev)
+    finally:
+        dev.close()
+
+    binds: dict[int, list[tuple[str, int]]] = {}
+    for off, mode, slot in collect_bindings(keymap):
+        rec = CONST_KEYMAP[off:off + 4]
+        hid = rec[3] if rec[0] in (0x00, 0x06) else None
+        label = (names.get(hid) if hid else None) or (f"key 0x{hid:02x}" if hid else f"@+{off:#06x}")
+        if mode & MODE_UNTIL_RELEASED:
+            label += " (until released)"
+        binds.setdefault(slot, []).append(label)
+
+    print(f"macro table header: {frame[:5].hex(' ')}")
+    found = 0
+    for i in range(MAX_SLOTS):
+        base = SLOT_BASE + i * SLOT_STRIDE
+        cycles, events = decode_slot(frame[base:base + SLOT_STRIDE])
+        if not events and cycles == 0:
+            continue
+        found += 1
+        line = f"slot{i}:"
+        if cycles:
+            line += f" cycles={cycles}"
+        if i in binds:
+            line += "  bound to: " + ", ".join(binds[i])
+        print(line)
+        ev = " ".join(f"{d}{names.get(h, f'#{h:02x}')}{'R' if r else 'P'}"
+                      for d, h, r in events)
+        print(f"  {ev}")
+    if not found:
+        print("  (no non-empty slots read back)")
+    print(f"({found} slot(s) non-empty)")
+    return 0
+
+
 def cmd_rgb(args):
     """Shortcut for `effect fixed-on <color>` (whole-board solid color).
 
@@ -399,22 +421,26 @@ def cmd_effect(args):
 def cmd_macro(args):
     """Bind a key to a macro that types text (flash write).
 
-    Each macro gets its own slot, and previously created macros are re-applied.
-    The device's current keymap is read first and used as the base, and the
-    current lighting is kept, so neither your remaps nor your effect/color are
-    disturbed.  ``--remove-all`` unbinds every macro instead.
+    The device's current keymap and macro table are read back first, so
+    existing macros, bindings and remaps are kept with no local state file;
+    the current lighting is kept too.  ``--remove-all`` unbinds every macro
+    instead.
 
     Examples:
         fizzctl macro --key CapsLock rgb
         fizzctl macro --key LAlt --delay-ms 50 --cycles 3 hello
+        fizzctl macro --until-released --key 2 aaaa
+        fizzctl macro --read            # dump the on-device macro table + bindings
         fizzctl macro --remove-all
     """
-    from . import state
     from .macro import (
-        MODE_CYCLES, MODE_UNTIL_RELEASED, NAME_TO_HID,
-        build_macro_frame, encode_slot, text_events,
+        MODE_CYCLES, MODE_UNTIL_RELEASED, MAX_SLOTS, NAME_TO_HID,
+        build_macro_frame, encode_slot, locate_key, slots_in_frame,
+        text_events,
     )
 
+    if args.read:
+        return cmd_macro_read(args)
     if args.remove_all:
         return cmd_macro_remove_all(args)
     if not args.key:
@@ -437,19 +463,6 @@ def cmd_macro(args):
         return 1
 
     mode = MODE_UNTIL_RELEASED if args.until_released else MODE_CYCLES
-    cache = state.load()
-    try:
-        slot = state.alloc_slot(cache, args.key)
-    except ValueError as e:
-        print(e)
-        return 1
-    cache["slots"][str(slot)] = encode_slot(args.cycles, events).hex()
-    cache["bindings"][args.key] = {"slot": slot, "mode": mode}
-
-    if args.debug:
-        print(f"macro: slot{slot} cycles={args.cycles} events={len(events)} "
-              f"mode={mode:#04x} bind={args.key}")
-
     try:
         dev = open_device(debug=args.debug)
     except NoDeviceError:
@@ -459,25 +472,45 @@ def cmd_macro(args):
     try:
         mode_f, canvas_f, routing_f, exec_f = _live_lighting(dev, args.debug)
         base = bytearray(_live_keymap(dev, args.debug))
-        missed = _apply_bindings(base, cache["bindings"], cache)
-        if args.key in missed:
-            print(f"could not find key {args.key!r} in the keymap")
-            return 1
-        if missed:
-            print(f"warning: could not bind {', '.join(missed)} in the keymap")
-        # exact capture order, but with the device's live lighting blocks
+        live_mf = _live_macro(dev, args.debug)
+        slots = slots_in_frame(live_mf)
+        hid = NAME_TO_HID[args.key]
+
+        off = locate_key(base, hid)
+        if off is None:
+            # already bound: the device echoes it as a `10` record, so find
+            # which binding this key is by its stock record instead
+            pos = _binding_for_hid(base, hid)
+            if pos is None:
+                print(f"could not find key {args.key!r} in the keymap")
+                return 1
+            bind_off, slot_idx = pos
+        else:
+            free = [i for i in range(MAX_SLOTS) if i not in slots]
+            if not free:
+                print(f"all {MAX_SLOTS} macro slots are in use")
+                return 1
+            bind_off, slot_idx = off, free[0]
+
+        slots[slot_idx] = encode_slot(args.cycles, events)
+        base[bind_off:bind_off + 4] = bytes((0x10, 0x00, mode, slot_idx))
+
+        if args.debug:
+            print(f"macro: slot{slot_idx} cycles={args.cycles} events={len(events)} "
+                  f"mode={mode:#04x} bind={args.key}")
+
+        # exact capture order, but with the device's live blocks
         frames = [
             bytes.fromhex("0583b6000000"),   # INIT
             mode_f, canvas_f, routing_f,     # current lighting
-            build_macro_frame(state.raw_slots(cache)),   # 06 05 dc (all slots)
+            build_macro_frame(slots),        # 06 05 dc (all slots)
             bytes(base),                     # 06 04 d4 (all bindings)
             exec_f,                          # EXEC (5AA5 commit)
         ]
         send_burst(dev, frames, handshake=False, delay_ms=args.burst_ms)
     finally:
         dev.close()
-    state.save(cache)
-    print(f"bound {args.key} -> macro typing {args.text!r} (slot {slot})")
+    print(f"bound {args.key} -> macro typing {args.text!r} (slot {slot_idx})")
     return 0
 
 
@@ -627,17 +660,21 @@ Examples:
     prs.add_argument("--delay-ms", type=int, default=30)
 
     pm = sub.add_parser("macro",
-                        help="bind a key that types TEXT, or --remove-all (flash write)",
+                        help="bind a key that types TEXT, --remove-all, or --read (flash write)",
                         description="""
 Examples:
   fizzctl macro --key CapsLock rgb
   fizzctl macro --key LAlt --delay-ms 50 --cycles 3 hello
+  fizzctl macro --until-released --key 2 aaaa
+  fizzctl macro --read            # dump on-device macros + their key bindings
   fizzctl macro --remove-all
 """.rstrip(),
                         formatter_class=argparse.RawDescriptionHelpFormatter)
     pm.add_argument("text", nargs="?", help="characters the macro types")
     pm.add_argument("-k", "--key",
                     help="key to bind (e.g. CapsLock, LAlt, A)")
+    pm.add_argument("--read", action="store_true",
+                    help="read the on-device macro table back, showing each slot's key binding")
     pm.add_argument("--remove-all", action="store_true",
                     help="unbind every macro and wipe all macro slots")
     pm.add_argument("--delay-ms", type=int, default=30,
@@ -662,7 +699,7 @@ Examples:
                         formatter_class=argparse.RawDescriptionHelpFormatter)
     pres.add_argument("--delay-ms", type=int, default=30)
 
-    psudev = sub.add_parser("setup-udev", help="install 99-k617.rules + reload udev (needs root)")
+    prd = sub.add_parser("setup-udev", help="install 99-k617.rules + reload udev (needs root)")
 
     return p
 
@@ -676,7 +713,8 @@ def main(dev: bool = False) -> int:
         "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,
-        "restore": cmd_restore, "macro": cmd_macro, "setup-udev": cmd_setup_udev,
+        "restore": cmd_restore, "macro": cmd_macro,
+        "setup-udev": cmd_setup_udev,
     }[args.cmd]
     return fn(args)
 

{fizzctl-0.3.0 → fizzctl-0.4.0}/src/fizzctl/hid.py

@@ -234,10 +234,19 @@ def read_lighting(dev: K617) -> list[bytes]:
 
 
 def read_keymap(dev: K617) -> bytes:
-    """Read the device's current (base) keymap block.
+    """Read the device's current keymap block.
 
-    Only the base layer comes back — macro bindings (``10`` records) are not
-    exposed — which is why :mod:`fizzctl.state` caches them separately.  The
-    base layer is live, so it does contain your current Cfg.ini remaps.
+    The base layer comes back live, so it contains your current Cfg.ini
+    remaps.  Bound macro keys are echoed back as their ``10 00 <mode> <slot>``
+    binding record (the original output is not recoverable from the device).
     """
     return _read_block(dev, "0584d4000000", bytes.fromhex("0604d40040"))
+
+
+def read_macro(dev: K617) -> bytes:
+    """Read the device's macro table block.
+
+    Mirrors the keymap read (``05 84 d4``) using the macro block id ``dc``;
+    the live slots come back intact (hardware-verified).
+    """
+    return _read_block(dev, "0585dc000000", bytes.fromhex("0605dc0040"))

{fizzctl-0.3.0 → fizzctl-0.4.0}/src/fizzctl/macro.py

@@ -80,6 +80,32 @@ def build_macro_frame(slots: dict[int, bytes]) -> bytes:
     return bytes(frame)
 
 
+def decode_slot(slot: bytes) -> tuple[int, list[tuple[int, int, bool]]]:
+    """Decode a 128-byte slot into ``(cycles, events)``.
+
+    ``events`` are ``(delay_ms, hid, release)`` triples in on-wire order.
+    """
+    cycles = slot[0]
+    events = []
+    off = 1
+    while off + 1 < len(slot) and slot[off] != 0:
+        b0 = slot[off]
+        events.append((b0 & MAX_DELAY_MS, slot[off + 1], bool(b0 & 0x80)))
+        off += 2
+    return cycles, events
+
+
+def decode_macro_frame(frame: bytes) -> dict[int, tuple[int, list[tuple[int, int, bool]]]]:
+    """Decode every non-empty slot of a 1032-byte macro frame."""
+    slots = {}
+    for i in range(MAX_SLOTS):
+        base = SLOT_BASE + i * SLOT_STRIDE
+        slot = frame[base:base + SLOT_STRIDE]
+        if any(slot):
+            slots[i] = decode_slot(slot)
+    return slots
+
+
 def encode_macro_frame(slots: list[tuple[int, list[bytes]]]) -> bytes:
     """Build the 1032-byte ``06 05 dc`` frame.
 
@@ -140,24 +166,99 @@ def bind_macro(keymap: bytearray, hid: int, slot: int,
     return off
 
 
-def find_binding(keymap, slot: int, mode: int = MODE_CYCLES) -> int | None:
-    """Offset of a ``10 00 <mode> <slot>`` binding already in ``keymap``.
+def collect_bindings(keymap) -> list[tuple[int, int, int]]:
+    """Every macro binding in ``keymap`` as ``(offset, mode, slot)``.
 
-    The device echoes macro bindings back as ``10`` records instead of the
-    key's base output, so a read-back keymap can contain the binding even
-    though :func:`bind_macro` cannot rediscover it.  Used to treat an existing
-    binding as "already applied" rather than a failed re-apply.
+    The device echoes live macro bindings back as ``10 00 <mode> <slot>``
+    records, so a read-back keymap contains them.  Region B (FN keys) is
+    scanned before the column records, matching :func:`locate_key`'s order.
     """
-    rec = bytes((ACTION_MACRO, 0x00, mode & 0xFF, slot & 0xFF))
+    out: list[tuple[int, int, int]] = []
     for start, count in (
         (REGION_B_BASE, (REGION_B_END - REGION_B_BASE) // 4),
         (REGION_A_BASE, (REGION_B_BASE - REGION_A_BASE) // 4),
     ):
         for pos in range(count):
             off = start + pos * 4
-            if keymap[off:off + 4] == rec:
-                return off
-    return None
+            if keymap[off] == ACTION_MACRO:
+                out.append((off, keymap[off + 2], keymap[off + 3]))
+    return out
+
+
+def slots_in_frame(frame: bytes) -> dict[int, bytes]:
+    """The non-empty slots of a macro frame as ``{index: 128-byte slot}``."""
+    slots: dict[int, bytes] = {}
+    for i in range(MAX_SLOTS):
+        base = SLOT_BASE + i * SLOT_STRIDE
+        slot = frame[base:base + SLOT_STRIDE]
+        if any(slot):
+            slots[i] = slot
+    return slots
+
+
+def relocate_bindings(live: bytes, target: bytearray,
+                      oracle: bytes | None = None) -> tuple[bytes, list[str]]:
+    """Re-apply the macro bindings read from ``live`` onto ``target``.
+
+    Bindings are matched to their **physical key** by the live layout, then
+    written at that key's position in ``target``.  Layouts are free to move
+    keys (e.g. an ``Alt`` that is an FN-layered key at offset 660 in one
+    layout and a plain column-17 key at offset 76 in another); copying raw
+    offsets would drop the binding onto a different key.
+
+    A binding below the FN area (``< 0x218``) is a plain key, its column is
+    the offset's own column.  A binding in the FN area is the key whose column
+    record points at that FN slot (``02 00 00 <slot>``).  If the live layout
+    can't identify the key (an orphan binding left behind by an earlier
+    layout—nothing points at its FN slot), ``oracle`` (a captured keymap, e.g.
+    ``CONST_KEYMAP``) is consulted at the same offset and the key located in
+    ``target`` by its HID.
+    """
+    target = bytearray(target)
+    warnings: list[str] = []
+    n = 0
+    for off, mode, slot in collect_bindings(live):
+        if off < REGION_B_BASE:
+            col = (off - REGION_A_BASE) // 4
+        else:
+            fp = (off - REGION_B_BASE) // 4
+            cols = [
+                c for c in range((REGION_B_BASE - REGION_A_BASE) // 4)
+                if live[REGION_A_BASE + c * 4] == 0x02
+                and live[REGION_A_BASE + c * 4 + 3] == fp
+            ]
+            col = cols[0] if len(cols) == 1 else None
+        if col is not None:
+            rec_off = REGION_A_BASE + col * 4
+            kind = target[rec_off]
+            if kind == 0x02:                     # FN-layered key here too -> follow it
+                dst = REGION_B_BASE + target[rec_off + 3] * 4
+            elif kind in (0x00, 0x06):           # plain key -> its own column record
+                dst = rec_off
+            else:
+                warnings.append(
+                    f"macro binding @+{off:#06x}: column {col} is not bindable in this "
+                    f"keymap (record {target[rec_off:rec_off + 4].hex(' ')})")
+                continue
+        elif oracle is not None:
+            rec = oracle[off:off + 4]
+            if rec[0] in (0x00, 0x06):
+                dst = locate_key(target, rec[3])
+                warnings.append(
+                    f"macro binding @+{off:#06x}: located as key "
+                    f"0x{rec[3]:02x} (moved from @+{off:#06x} to @+{dst:#06x})" if dst is not None
+                    else f"macro binding @+{off:#06x}: cannot identify its key")
+                if dst is None:
+                    continue
+            else:
+                warnings.append(f"macro binding @+{off:#06x}: cannot identify its key")
+                continue
+        else:
+            warnings.append(f"macro binding @+{off:#06x}: cannot identify its key")
+            continue
+        target[dst:dst + 4] = bytes((ACTION_MACRO, 0x00, mode & 0xFF, slot & 0xFF))
+        n += 1
+    return bytes(target), warnings
 
 
 # --------------------------------------------------------------------------

fizzctl-0.3.0/src/fizzctl/state.py

@@ -1,59 +0,0 @@
-"""Local cache of fizzctl-created macros and their key bindings.
-
-The K617 only exposes the **base** keymap (``05 84 d4``) and a **factory**
-macro table (``05 85 dc``): macro bindings (the ``10 00 <mode> <slot>``
-records) and the user's macro slots live in an overlay the device does not
-return.  Reading the base keymap therefore never contains them, so we remember
-what we created here and re-apply it on every keymap/macro write.
-
-Keymaps are *not* cached — the base keymap is read straight off the device, so
-binding a macro keeps your existing Cfg.ini remaps.
-"""
-from __future__ import annotations
-
-import json
-import os
-from pathlib import Path
-
-from .macro import MAX_SLOTS
-
-
-def state_path() -> Path:
-    base = os.environ.get("XDG_STATE_HOME") or os.path.join(Path.home(), ".local", "state")
-    return Path(base) / "fizzctl" / "state.json"
-
-
-def load() -> dict:
-    """Load the macro cache; a missing or corrupt file yields an empty cache."""
-    try:
-        data = json.loads(state_path().read_text())
-    except (OSError, ValueError):
-        data = {}
-    if not isinstance(data, dict):
-        data = {}
-    data.setdefault("slots", {})
-    data.setdefault("bindings", {})
-    return data
-
-
-def save(state: dict) -> None:
-    path = state_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n")
-
-
-def alloc_slot(state: dict, key: str) -> int:
-    """Slot for ``key``: its existing one, else the lowest free slot index."""
-    existing = state["bindings"].get(key)
-    if existing is not None:
-        return int(existing["slot"])
-    used = {int(slot) for slot in state["slots"]}
-    for i in range(MAX_SLOTS):
-        if i not in used:
-            return i
-    raise ValueError(f"all {MAX_SLOTS} macro slots are in use")
-
-
-def raw_slots(state: dict) -> dict[int, bytes]:
-    """The cached slots as ``{index: 128-byte slot}``."""
-    return {int(slot): bytes.fromhex(hex_) for slot, hex_ in state["slots"].items()}