fizzctl 0.2.0__py3-none-any.whl

fizzctl/hid.py

@@ -0,0 +1,255 @@
+"""Thin hidapi wrapper for the K617 vendor interface (interface 1).
+
+The K617 exposes two HID interfaces:
+  * interface 0  — boot keyboard / media keys (standard)
+  * interface 1  — vendor-defined usage page 0xFF00, holds the feature
+                   reports used by every protocol (report IDs 0x05/0x06/0x08).
+
+We always talk to interface 1 via hidapi's `send_feature_report` /
+`get_feature_report`.  These map to USB SET_REPORT / GET_REPORT control
+transfers — the exact URBs you will see in USBPcap captures.
+"""
+from __future__ import annotations
+
+import os
+import time
+
+import hid
+
+from .protocol import PID, VID
+
+
+class NoDeviceError(Exception):
+    """The K617 vendor interface could not be found or opened."""
+
+
+class UdevRequiredError(NoDeviceError):
+    """The HID node exists but cannot be opened — udev rules are missing."""
+
+
+def udev_rules_installed() -> bool:
+    return os.path.exists("/etc/udev/rules.d/99-k617.rules")
+
+
+class K617:
+    def __init__(self, debug: bool = False):
+        self.debug = debug
+        self._dev = self._open()
+
+    @staticmethod
+    def _open():
+        try:
+            uid = os.geteuid()
+        except AttributeError:
+            uid = None
+        paths = []
+        for d in hid.enumerate(VID, PID):
+            iface = int(d.get("interface_number") or 0)
+            if iface == 1:
+                paths.append(d["path"])
+        if not paths:
+            msg = (
+                "Could not find your K617 keyboard. Make sure it is "
+                "plugged in (and in wireless mode if it supports it), "
+                "then try again."
+            )
+            if uid != 0:
+                msg += (
+                    "\nIf it is plugged in, your user may lack permission "
+                    "to see it — try running `fizzctl setup-udev` first."
+                )
+            raise NoDeviceError(msg)
+        path = paths[0]
+        display = path.decode(errors="replace") if isinstance(path, bytes) else str(path)
+        try:
+            dev = hid.Device(path=path) if hasattr(hid, "Device") else \
+                K617._open_ctypes(path)
+            return dev
+        except Exception as e:
+            if uid != 0 and not udev_rules_installed():
+                raise UdevRequiredError(
+                    f"Found your K617 but it could not be opened ({display}).\n"
+                    "The udev rules that let you access the keyboard without "
+                    "sudo are not installed."
+                ) from e
+            if uid != 0:
+                raise NoDeviceError(
+                    f"Found your K617 but it could not be opened ({display}: {e}). "
+                    "Your user lacks permission to access it. Try running "
+                    "`fizzctl setup-udev` (or unplug/replug the keyboard), "
+                    "then rerun this command."
+                ) from e
+            raise NoDeviceError(
+                f"Found your K617 but it could not be opened ({display}: {e}). "
+                "Is another program controlling the keyboard right now?"
+            ) from e
+
+    @staticmethod
+    def _open_ctypes(path):
+        """Open via the trezor 'hid' ctypes module (hid.device/open_path)."""
+        dev = hid.device()
+        dev.open_path(path)  # accepts str or bytes
+        return dev
+
+    def send_feature(self, data: bytes) -> None:
+        """Send an arbitrary feature report (bytes includes the report ID)."""
+        self._dev.send_feature_report(data)
+
+    def get_feature(self, report_id: int, size: int) -> bytes:
+        """Read a feature report (returns exactly `size` bytes on success)."""
+        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:
+                self._dev.close()
+            except Exception:
+                pass
+
+
+def open_device(debug: bool = False) -> K617 | None:
+    """Open the K617, prompting to install udev rules when access is denied.
+
+    Returns the device, or None if it could not be opened (the reason is
+    already printed). When the rules are missing the user is asked whether
+    to install them now, then the open is retried.
+    """
+    from .udev_rules import install_udev_rules
+
+    try:
+        return K617(debug=debug)
+    except UdevRequiredError as e:
+        print(f"Trouble opening your K617: {e}")
+        try:
+            answer = input("Install the udev rules now? [Y/n] ").strip().lower()
+        except EOFError:
+            answer = "y"
+        if answer not in ("", "y", "yes"):
+            print("Skipped. You can install them later with `fizzctl setup-udev`.")
+            return None
+        print("Installing udev rules (you may be asked for your password)...")
+        try:
+            install_udev_rules()
+        except Exception as ie:
+            print(f"error: could not install udev rules: {ie}")
+            return None
+        print("udev rules installed. Reopening the keyboard...")
+        last_err = None
+        for _ in range(8):           # udev permission changes settle slowly
+            try:
+                return K617(debug=debug)
+            except NoDeviceError as e2:
+                last_err = e2
+                time.sleep(1.0)
+        print(f"error: {last_err}")
+        print("Hint: unplug and replug the keyboard, then run the command again.")
+        return None
+    except NoDeviceError as e:
+        print(e)
+        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].
+
+    led_colors maps LED index -> (r, g, b). Led indices live in
+    protocol.LED_INDEX.
+
+    NOTE: the EXEC frame commits to flash (5AA5 magic). Do not loop this.
+    """
+    from .blobs import RGB_EXEC, RGB_INIT, RGB_SEC
+    from .protocol import NAME_TO_INDEX, RESTORE_CONSTANT_FRAMES, set_key_color
+
+    canvas = bytearray(1032)
+    canvas[0:5] = bytes.fromhex("0609bc0040")
+    for idx, rgb in led_colors.items():
+        if isinstance(idx, str):
+            idx = NAME_TO_INDEX[idx]
+        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]
+
+
+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_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).
+    """
+    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)
+        if dev.debug:
+            print(f"  [{i}/5] {_kind(block)}")
+        sleep(0.06)
+
+
+def send_per_key(dev: K617, frame: bytes) -> None:
+    """Send a single 382-byte per-key report (no handshake needed)."""
+    dev._dev.send_feature_report(frame)

fizzctl/keymap.py

@@ -0,0 +1,178 @@
+"""K617 KEYMAP block (06 04 d4) encoder.
+
+The keymap block is 1032 bytes = 8-byte command header +
+256 four-byte records.  Records are indexed by MATRIX COLUMN and
+hold, for each physical key, what the key SENDS as a USB HID usage code.
+
+Layout (all offsets relative to block start):
+  +0x00  header        06 04 d4 00 40 00 00 00
+  +0x08  col records   256 slots * 4B; slot n holds the record for the
+                        matrix column n (slot = column index, 0-based:
+                        offset = 8 + col*4).  Content by key type:
+                          normal key   -> 00 00 00 <HID>
+                          modifier     -> 06 00 00 <HID>
+                          has FN layer -> 02 00 00 <FN index>
+                          Fn key       -> 20 00 00 00
+                          unassigned   -> 00 00 00 00
+  +0x218 region B      FN keys' BASE-layer output, in row-major physical
+                        order (top row -> bottom row, left -> right):
+                          normal -> 00 00 00 <HID>   modifier -> 06 00 00 <HID>
+  +0x2d8 region C      FN keys' FN-layer output, same order as region B:
+                          normal FN -> 00 00 00 <HID>
+                          media FN  -> 04 00 00 <media code>
+                          special   -> 4B big-endian value (type 9 fns)
+
+The FN index stored in the col records is the 0-based position of that
+key in the region-B/C row-major list.
+"""
+
+from dataclasses import dataclass
+
+HEADER = bytes.fromhex("0604d40040000000")
+
+# Windows VK code -> USB HID keyboard usage code, for the K617's key set.
+VK2HID = {}
+VK2HID[0x30] = 0x27                                          # 0
+VK2HID.update({0x31 + i: 0x1e + i for i in range(9)})         # 1-9 -> a-row
+VK2HID.update({ord('A') + i: 0x04 + i for i in range(26)})      # A-Z
+VK2HID.update({0x70 + i: 0x3a + i for i in range(12)})          # F1-F12
+VK2HID.update({
+    0x08: 0x2a,   # backspace
+    0x09: 0x2b,   # tab
+    0x0d: 0x28,   # enter
+    0x14: 0x39,   # capslock
+    0x1b: 0x29,   # esc
+    0x20: 0x2c,   # space
+    0x21: 0x4b,   # pageup
+    0x22: 0x4e,   # pagedown
+    0x23: 0x4d,   # end
+    0x24: 0x4a,   # home
+    0x25: 0x50,   # left
+    0x26: 0x52,   # up
+    0x27: 0x4f,   # right
+    0x28: 0x51,   # down
+    0x2d: 0x49,   # insert
+    0x2e: 0x4c,   # delete
+    0x2c: 0x46,   # print screen
+    0x5b: 0xe3,   # lwin
+    0x5d: 0x65,   # rwin (stored as a normal key, not a modifier)
+    0xa0: 0xe1,   # lshift
+    0xa1: 0xe5,   # rshift
+    0xa2: 0xe0,   # lctrl
+    0xa3: 0xe4,   # rctrl
+    0xa4: 0xe2,   # lalt
+    0xa5: 0xe6,   # ralt
+    0xa6: 0xe3,   # lwin
+    0xba: 0x33,   # ;
+    0xbb: 0x2e,   # =
+    0xbc: 0x36,   # ,
+    0xbd: 0x2d,   # -
+    0xbe: 0x37,   # .
+    0xbf: 0x38,   # /
+    0xc0: 0x35,   # `
+    0xdb: 0x2f,   # [
+    0xdc: 0x31,   # backslash
+    0xdd: 0x30,   # ]
+    0xde: 0x34,   # '
+})
+
+REGION_B_BASE = 0x218  # FN keys' base-layer outputs
+REGION_C_BASE = 0x2d8  # FN keys' fn-layer outputs
+N_COLS = 256
+N_ROWS = 5              # physical keyboard rows of the 60% layout
+
+
+@dataclass
+class MediaCode:
+    """Maps a cfg FN media type-4 code to the on-wire media byte."""
+
+    cfg_code: int
+    wire: int
+    name: str
+
+
+# type-4 FN media codes.  The on-wire byte is the USB HID Consumer Page
+# usage code (Play/Pause confirmed by capture cfg_r4: cfg 0x22 -> 0xcd,
+# which is consumer usage 0x00cd).  The rest follow the same table.
+MEDIA_CODES = {
+    0x22: MediaCode(0x22, 0xcd, "play/pause"),   # captured in cfg_r4
+    0x26: MediaCode(0x26, 0xe9, "vol+"),
+    0x27: MediaCode(0x27, 0xea, "vol-"),
+    0x28: MediaCode(0x28, 0xe2, "mute"),
+}
+
+
+class KeymapEncoder:
+    """Builds a 1032-byte 06 04 d4 block from a CfgIni."""
+
+    def __init__(self, cfg, vk2hid=None):
+        self.cfg = cfg
+        self.vk2hid = vk2hid if vk2hid is not None else VK2HID
+        self.b = bytearray(1032)
+        self.b[0:8] = HEADER
+
+    def _is_mod(self, vk):
+        return 0xA0 <= vk <= 0xA6 or vk == 0x5B
+
+    def _row_major_fn_keys(self):
+        # order by row (geom y, bucketed by ~36px spacing), then by geom x
+        def key(i):
+            k = self.cfg.keys[i]
+            return (k.geom[1] // 36, k.geom[0])
+
+        return sorted(
+            (idx for idx in self.cfg.fn if idx in self.cfg.keys), key=key
+        )
+
+    def build(self):
+        fn_keys = self._row_major_fn_keys()
+        fn_index = {idx: pos for pos, idx in enumerate(fn_keys)}
+
+        # region A: col records, written directly to self.b
+        cols = {k.matrix[0]: k for k in (self.cfg.keys[i] for i in self.cfg.keys)}
+        for col in range(N_COLS):
+            off = 8 + col * 4
+            key = cols.get(col)
+            if key is None:
+                rec = b"\x00\x00\x00\x00"
+            else:
+                vk = key.behavior[1]
+                if vk == 0xFA:                       # Fn key
+                    rec = b"\x20\x00\x00\x00"
+                elif key.index in fn_index:          # has FN layer
+                    rec = bytes([2, 0, 0, fn_index[key.index]])
+                elif self._is_mod(vk):
+                    rec = bytes([6, 0, 0, self._hid(vk)])
+                else:
+                    rec = bytes([0, 0, 0, self._hid(vk)])
+            self.b[off:off + 4] = rec
+
+        # region B/C in the same row-major order
+        for pos, idx in enumerate(fn_keys):
+            key = self.cfg.keys[idx]
+            vk = key.behavior[1]
+            b_off = REGION_B_BASE + pos * 4
+            c_off = REGION_C_BASE + pos * 4
+            base = bytes([6 if self._is_mod(vk) else 0, 0, 0, self._hid(vk)])
+            self.b[b_off:b_off + 4] = base
+            self.b[c_off:c_off + 4] = self._fn_output(idx)
+
+        return bytes(self.b)
+
+    def _hid(self, vk):
+        return self.vk2hid.get(vk, 0)
+
+    def _fn_output(self, key_idx):
+        """4-byte region-C entry for key_idx's FN function."""
+        t, code, extra = self.cfg.fn[key_idx]
+        if t == 4:                               # media key
+            wire = self._media_wire(code)
+            return bytes([4, 0, 0, wire])
+        if t == 9:                               # special function: packed value
+            return extra.to_bytes(4, "big")
+        # t == 2 -> normal keycode (VK code) -> HID usage
+        return bytes([0, 0, 0, self._hid(code)])
+
+    def _media_wire(self, code):
+        m = MEDIA_CODES.get(code)
+        return m.wire if m else 0

fizzctl/protocol.py

@@ -0,0 +1,97 @@
+"""Device identity, report IDs and known-good frame knowledge for the K617 Fizz.
+
+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
+
+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):
+#   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] = [
+    CONST_MODE,    # 06 08 b8 00 40
+    CONST_CANVAS,  # 06 09 bc 00 40
+    CONST_ROUTING, # 06 09 c0 00 40
+    CONST_EXEC,    # 06 03 b6 ... 5AA5 commit
+]
+
+
+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 frame_kind(frame: bytes) -> str:
+    """Identify a known frame / report by its lead bytes."""
+    if not frame:
+        return "empty"
+    rid = frame[0]
+    if rid == 0x05:
+        return "INIT(05)"
+    if rid == 0x06:
+        head = frame[1:5]
+        if head == bytes.fromhex("08b80040"):
+            return "MODE(06 08 b8)"
+        if head == bytes.fromhex("09bc0040"):
+            return "CANVAS(06 09 bc)"
+        if head == bytes.fromhex("09c00040"):
+            return "ROUTING(06 09 c0)"
+        if head == bytes.fromhex("03b60000"):
+            return "EXEC(06 03 b6)"
+        return f"BLOCK(06 {frame[1]:02x} {frame[2]:02x})"
+    if rid == 0x08:
+        return "PERKEY(08 0a 7a 01)" if frame[1:4] == bytes.fromhex("0a7a01") else f"REP08?({frame[1]:02x})"
+    return f"report {rid:#04x}"
+
+
+# ---- known split-plane RGB layout inside the 1032-byte CANVAS block ----
+BLUE_BASE = 8
+GREEN_BASE = 134
+RED_BASE = 260
+
+# LED index map (LED index -> key), rows with 14 data + 7 gap, stride 21.
+LED_INDEX = {
+    21: "Esc", 22: "1", 23: "2", 24: "3", 25: "4", 26: "5", 27: "6",
+    28: "7", 29: "8", 30: "9", 31: "0", 32: "-", 33: "=", 34: "Bksp",
+    42: "Tab", 43: "Q", 44: "W", 45: "E", 46: "R", 47: "T", 48: "Y",
+    49: "U", 50: "I", 51: "O", 52: "P", 53: "[", 54: "]", 55: "\\",
+    63: "CapsLk", 64: "A", 65: "S", 66: "D", 67: "F", 68: "G", 69: "H",
+    70: "J", 71: "K", 72: "L", 73: ";", 74: "'", 76: "Enter",
+    84: "LShift", 86: "Z", 87: "X", 88: "C", 89: "V", 90: "B", 91: "N",
+    92: "M", 93: ",", 94: ".", 95: "/", 97: "RShift",
+    105: "LCtrl", 106: "LWin", 107: "LAlt", 110: "Space", 113: "RAlt",
+    114: "Fn", 117: "Menu", 118: "RCtrl",
+}
+
+NAME_TO_INDEX = {name: idx for idx, name in LED_INDEX.items()}
+
+
+def set_key_color(frame: bytearray, led_index: int, rgb: tuple[int, int, int]) -> None:
+    """Patch one key's RGB into a 1032-byte CANVAS frame (in place)."""
+    r, g, b = rgb
+    frame[RED_BASE + led_index] = r
+    frame[GREEN_BASE + led_index] = g
+    frame[BLUE_BASE + led_index] = b

fizzctl/udev_rules.py

@@ -0,0 +1,89 @@
+"""Udev rules for the Redragon K617 Fizz (VID 258a, PID 0049).
+
+The rules grant the current user access to the vendor HID interface(s) via the
+``uaccess`` tag (systemd-logind) and a permissive mode so ``fizzctl`` works
+without root.  Install with ``fizzctl setup-udev`` — the command escalates
+its own privileged steps via ``sudo`` (prompting for a password if needed),
+so you do not need ``sudo fizzctl`` itself.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+
+UDEV_DIR = "/etc/udev/rules.d"
+UDEV_FILE = "99-k617.rules"
+
+RULES = """\
+SUBSYSTEM=="hidraw",  ATTRS{idVendor}=="258a", ATTRS{idProduct}=="0049", MODE="0666", TAG+="uaccess"
+SUBSYSTEM=="usb",     ATTRS{idVendor}=="258a", ATTRS{idProduct}=="0049", MODE="0666", TAG+="uaccess"
+SUBSYSTEM=="input",   ATTRS{idVendor}=="258a", ATTRS{idProduct}=="0049", MODE="0660", TAG+="uaccess"
+KERNEL=="event*",     ATTRS{idVendor}=="258a", ATTRS{idProduct}=="0049", MODE="0660", TAG+="uaccess"
+"""
+
+
+def _is_root() -> bool:
+    return hasattr(os, "geteuid") and os.geteuid() == 0
+
+
+def _reload_udev() -> None:
+    """Reload udev rules and re-trigger device events (needs root)."""
+    res = subprocess.run(["udevadm", "control", "--reload-rules"], capture_output=True, text=True)
+    if res.returncode != 0:
+        print(f"warning: udevadm reload failed ({res.stderr.strip() or res.returncode})")
+        print("unplug/replug the keyboard, or run: sudo udevadm trigger")
+        return
+    subprocess.run(["udevadm", "trigger"], capture_output=True)
+
+
+def _install_as_root(target: str) -> int:
+    try:
+        os.makedirs(UDEV_DIR, exist_ok=True)
+        with open(target, "w", encoding="utf-8") as fh:
+            fh.write(RULES)
+        print(f"installed udev rules -> {target}")
+    except PermissionError as e:
+        print(f"error: cannot write {target}: {e}")
+        return 1
+    _reload_udev()
+    return 0
+
+
+def install_udev_rules() -> int:
+    """Install the udev rules file and reload udev (elevating via sudo)."""
+    target = os.path.join(UDEV_DIR, UDEV_FILE)
+
+    if _is_root():
+        return _install_as_root(target)
+
+    # Not root: escalate the privileged steps.  The binary is often installed
+    # in a user-local path (e.g. ~/.local/bin), so `sudo fizzctl` would fail
+    # with "command not found" — instead we only elevate the syscalls that need
+    # root, in a single sudo session (one password prompt).
+    if shutil.which("sudo") is None:
+        print("error: not running as root and `sudo` is not available")
+        return 1
+
+    with tempfile.NamedTemporaryFile(
+        mode="w", encoding="utf-8", suffix=".rules", delete=False, prefix="k617-",
+    ) as fh:
+        fh.write(RULES)
+        src = fh.name
+    try:
+        cmd = (
+            f"install -o root -g root -m 0644 {src!r} {target!r} "
+            "&& udevadm control --reload-rules "
+            "&& udevadm trigger"
+        )
+        print("elevating to root via sudo to install udev rules…")
+        res = subprocess.run(["sudo", "sh", "-c", cmd])
+        if res.returncode != 0:
+            print("error: sudo install/udevadm failed (see output above)")
+            return 1
+    finally:
+        os.unlink(src)
+
+    print(f"installed udev rules -> {target}")
+    return 0