fizzctl 0.2.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: fizzctl
-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
+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,6 +60,8 @@ 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, `--remove-all`, or `--read` | yes |
+| `restore` | Reset to the factory keymap, lighting and macros | yes |
 | `animate` | Host-streamed animation (volatile) | no |
 
 ## Examples
@@ -80,6 +83,39 @@ Apply the full keymap (bindings, lighting zones, function keys) from a
 fizzctl keymap Cfg.ini
 ```
 
+- A `keymap` write keeps your current effect/color/brightness and any macros
+  you have bound.
+- `fizzctl restore` does the opposite: it resets the keyboard to factory
+  state by writing the packaged stock keymap and lighting and wiping every
+  macro.
+
+### Macros
+
+Bind a key to a macro that types text. Each macro gets its own slot (up to
+8), and previously bound macros are kept — the device's current keymap is
+read and reused as the base, and your lighting is untouched:
+
+```bash
+fizzctl macro --key CapsLock rgb          # type "rgb" each press
+fizzctl macro --key LAlt --delay-ms 50 --cycles 3 hello
+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 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 restore                     # full factory reset (keymap, lighting, macros)
+```
+
 ### Set the whole board to one color
 
 ```bash
@@ -152,11 +188,11 @@ fizzctl-dev list
 
 ## How the RGB paths work
 
-**Flash writes** (`rgb`, `key`, `paint`, `effect`, `keymap`) send a 4-5 frame
-burst through the vendor HID interface (`258a:0049`, interface 1, usage page
-`0xFF00`). The sequence ends with a `5AA5` magic commit that writes to flash.
-Colors persist across reboots. Keys not listed in a `key` or `paint` canvas
-turn off.
+**Flash writes** (`rgb`, `key`, `paint`, `effect`, `keymap`, `macro`,
+`restore`) send a burst through the vendor HID interface (`258a:0049`,
+interface 1, usage page `0xFF00`). The sequence ends with a `5AA5` magic
+commit that writes to flash. Colors persist across reboots. Keys not listed
+in a `key` or `paint` canvas turn off.
 
 **Animations** (`animate`) stream 382-byte per-key reports at the requested
 frame rate with no flash commit. They are host-side only and lost on

{fizzctl-0.2.1 → 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,6 +40,8 @@ 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, `--remove-all`, or `--read` | yes |
+| `restore` | Reset to the factory keymap, lighting and macros | yes |
 | `animate` | Host-streamed animation (volatile) | no |
 
 ## Examples
@@ -60,6 +63,39 @@ Apply the full keymap (bindings, lighting zones, function keys) from a
 fizzctl keymap Cfg.ini
 ```
 
+- A `keymap` write keeps your current effect/color/brightness and any macros
+  you have bound.
+- `fizzctl restore` does the opposite: it resets the keyboard to factory
+  state by writing the packaged stock keymap and lighting and wiping every
+  macro.
+
+### Macros
+
+Bind a key to a macro that types text. Each macro gets its own slot (up to
+8), and previously bound macros are kept — the device's current keymap is
+read and reused as the base, and your lighting is untouched:
+
+```bash
+fizzctl macro --key CapsLock rgb          # type "rgb" each press
+fizzctl macro --key LAlt --delay-ms 50 --cycles 3 hello
+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 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 restore                     # full factory reset (keymap, lighting, macros)
+```
+
 ### Set the whole board to one color
 
 ```bash
@@ -132,11 +168,11 @@ fizzctl-dev list
 
 ## How the RGB paths work
 
-**Flash writes** (`rgb`, `key`, `paint`, `effect`, `keymap`) send a 4-5 frame
-burst through the vendor HID interface (`258a:0049`, interface 1, usage page
-`0xFF00`). The sequence ends with a `5AA5` magic commit that writes to flash.
-Colors persist across reboots. Keys not listed in a `key` or `paint` canvas
-turn off.
+**Flash writes** (`rgb`, `key`, `paint`, `effect`, `keymap`, `macro`,
+`restore`) send a burst through the vendor HID interface (`258a:0049`,
+interface 1, usage page `0xFF00`). The sequence ends with a `5AA5` magic
+commit that writes to flash. Colors persist across reboots. Keys not listed
+in a `key` or `paint` canvas turn off.
 
 **Animations** (`animate`) stream 382-byte per-key reports at the requested
 frame rate with no flash commit. They are host-side only and lost on

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

@@ -1,7 +1,7 @@
 [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"
+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.2.1 → fizzctl-0.4.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [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"
+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.2.1 → 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.2.0"
+__version__ = "0.4.0"

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

@@ -6,6 +6,10 @@ All constants come from USB captures of the OEM software:
   * 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.
+  * CONST_KEYMAP — a clean 1032-byte 06 04 d4 keymap block (no macro
+    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.
 """
 
 
@@ -209,6 +213,42 @@ FW_TEMPLATE = [
     _patch(CONST_EXEC, EXEC_DIFFS),
 ]
 
+CONST_KEYMAP = bytes.fromhex(
+    "0604d4004000000000000000020000000200000d02000014060000e1060000e0"
+    "00000000020000010200000e020000150000001d0200001e0000000002000002"
+    "0200000f020000160000001b0200001f00000000020000030200001002000017"
+    "0000000600000000000000000200000400000015000000090000001900000000"
+    "0000000002000005000000170000000a00000005020000200000000002000006"
+    "0000001c0000000b00000011000000000000000002000007000000180000000d"
+    "0200001a0000000000000000020000080000000c0000000e0200001b20000000"
+    "0000000002000009000000120000000f0200001c00000050000000000200000a"
+    "02000011020000180200001d00000000000000000200000b0200001202000019"
+    "0000000000000000000000000200000c02000013000000000000000000000051"
+    "000000000000002a0000003100000028000000520000004f0000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "000000000000000000000000000000000000000000000000000000290000001e"
+    "0000001f00000020000000210000002200000023000000240000002500000026"
+    "000000270000002d0000002e0000002b000000140000001a0000000800000013"
+    "0000002f00000030000000390000000400000016000000070000003300000034"
+    "00000010000000360000003700000038060000e3060000e20000002c00000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "000000000000000000000000000000000000000000000000000000350000003a"
+    "0000003b0000003c0000003d0000003e0000003f000000400000004100000042"
+    "000000430000004400000045040000cd040000ea00000052040000e900000046"
+    "000000490000004c040000e200000050000000510000004f0000004a0000004d"
+    "0c0003000d0003000000004b0000004e0e0000010b0003000e00000700000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000000000000000000000000000000000000000000000000000"
+    "0000000000000000"
+)
+
 RGB_SEC = bytes.fromhex(
     "ffffffffff000000000000000000000000000000ffffffffff00000000000000"
     "00000000000000000000ffffff00ff000000000000000000000000000000ff00"