kovarctl 0.1.0__py3-none-any.whl

kovarctl/__init__.py

@@ -0,0 +1 @@
+"""Control the lighting of KOVAR keyboards (ROYUAN YC500 firmware)."""

kovarctl/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

kovarctl/cli.py

@@ -0,0 +1,411 @@
+"""Command line interface for KOVAR keyboards."""
+
+import colorsys
+import json
+import sys
+import time
+
+import click
+
+from . import protocol
+from .device import DONGLE_PRODUCT_IDS, Keyboard, KeyboardError, find_vendor_interfaces
+
+
+class Context:
+    def __init__(self, device, model_id, dry_run, force, verbose):
+        self.device = device
+        self.model_id = model_id
+        self.dry_run = dry_run
+        self.force = force
+        self.verbose = verbose
+
+    def log(self, message):
+        if self.verbose or self.dry_run:
+            click.echo(message, err=True)
+
+    def open(self, probe=True):
+        if self.device:
+            paths = [self.device]
+        else:
+            paths = find_vendor_interfaces()
+            if not paths:
+                raise click.ClickException("no KOVAR keyboard found (3151:4010); dongles are not supported yet")
+
+        keyboards = []
+        for path in paths:
+            try:
+                keyboard = Keyboard(path, self.dry_run, self.force, self.log, probe=probe)
+            except KeyboardError as error:
+                if len(paths) == 1:
+                    raise click.ClickException(str(error))
+                continue
+            if self.model_id is None or keyboard.device_id == self.model_id:
+                keyboards.append(keyboard)
+            else:
+                keyboard.close()
+
+        if len(keyboards) != 1:
+            for keyboard in keyboards:
+                keyboard.close()
+            raise click.ClickException(
+                "no matching keyboard" if not keyboards else
+                "several keyboards found, select one with --device or --id (see 'kovarctl list')")
+
+        keyboard = keyboards[0]
+        if probe and keyboard.model is None:
+            keyboard.close()
+            raise click.ClickException(f"unknown model ID {keyboard.device_id}")
+        return keyboard
+
+
+pass_context = click.make_pass_decorator(Context)
+
+
+class Group(click.Group):
+    """Report device errors as normal command errors."""
+
+    def invoke(self, ctx):
+        try:
+            return super().invoke(ctx)
+        except KeyboardError as error:
+            raise click.ClickException(str(error))
+
+
+def color_argument(ctx, param, value):
+    if value is None:
+        return None
+    try:
+        return protocol.parse_color(value)
+    except ValueError as error:
+        raise click.BadParameter(str(error))
+
+
+def describe(state, side=False):
+    effect = protocol.EFFECTS_BY_VALUE.get(state.effect)
+    name = effect.name if effect else f"unknown (0x{state.effect:02X})"
+    parts = [name]
+    if effect is None or effect.speed:
+        parts.append(f"speed {state.speed}")
+    parts.append(f"brightness {state.brightness}")
+    if effect is None or effect.color:
+        parts.append("rainbow" if state.rainbow else f"color {protocol.format_color(state.effective_color)}")
+    if effect and effect.directions and not side:
+        parts.append(f"direction {effect.directions[state.variant % len(effect.directions)]}")
+    return ", ".join(parts)
+
+
+@click.group(cls=Group)
+@click.option("--device", metavar="PATH", help="hidraw node of the keyboard's vendor interface.")
+@click.option("--id", "model_id", type=int, help="Select the keyboard by firmware model ID.")
+@click.option("--dry-run", is_flag=True, help="Read from the keyboard, but only print what would be written.")
+@click.option("--force", is_flag=True, help="Ignore the flash write rate limit.")
+@click.option("-v", "--verbose", is_flag=True, help="Report flash writes.")
+@click.version_option(package_name="kovarctl")
+@click.pass_context
+def main(ctx, device, model_id, dry_run, force, verbose):
+    """Control the lighting of KOVAR keyboards (ROYUAN YC500 firmware).
+
+    Effect settings and custom pictures are stored in the keyboard flash.
+    kovarctl skips writes that change nothing and limits how often flash is
+    written. Use 'live' for frequently changing colors.
+    """
+    ctx.obj = Context(device, model_id, dry_run, force, verbose)
+
+
+@main.command("list")
+def list_keyboards():
+    """List connected keyboards."""
+    for path in find_vendor_interfaces():
+        try:
+            with Keyboard(path) as keyboard:
+                name = keyboard.model.name if keyboard.model else "unknown model"
+                click.echo(f"{path}  ID {keyboard.device_id:<4} {name}  (firmware {keyboard.revision()})")
+        except (KeyboardError, OSError) as error:
+            click.echo(f"{path}  {error}")
+    for path in find_vendor_interfaces(DONGLE_PRODUCT_IDS):
+        click.echo(f"{path}  wireless dongle (not supported yet, use the USB cable)")
+
+
+@main.command()
+@pass_context
+def info(obj):
+    """Show model, firmware and current lighting."""
+    with obj.open() as keyboard:
+        click.echo(f"Model:     {keyboard.model.name} (ID {keyboard.device_id})")
+        click.echo(f"Firmware:  {keyboard.revision()}")
+        click.echo(f"Device:    {keyboard.path}")
+        click.echo(f"Keys:      {describe(keyboard.light_state())}")
+        if keyboard.model.side_light:
+            click.echo(f"Side:      {describe(keyboard.light_state(side=True), side=True)}")
+        picture = keyboard.picture()
+        lit = sum(1 for slot in keyboard.model.keys.values() if any(picture[slot * 3:slot * 3 + 3]))
+        click.echo(f"Custom:    {lit} of {len(keyboard.model.keys)} keys lit")
+
+
+@main.command()
+def effects():
+    """List effects and their options."""
+    for effect in protocol.EFFECTS:
+        options = []
+        if effect.speed:
+            options.append("speed")
+        if effect.color:
+            options.append("color/rainbow")
+        if effect.directions:
+            options.append("direction: " + "/".join(effect.directions))
+        side = " (also side light)" if effect in protocol.SIDE_EFFECTS else ""
+        click.echo(f"{effect.name:15} {', '.join(options)}{side}")
+
+
+@main.command()
+@pass_context
+def keys(obj):
+    """List the key names of the connected keyboard."""
+    with obj.open() as keyboard:
+        click.echo(" ".join(keyboard.model.keys))
+
+
+def light_options(command):
+    command = click.option("--speed", type=click.IntRange(0, protocol.SPEED_MAX), help="0 (slow) to 4 (fast).")(command)
+    command = click.option("--brightness", type=click.IntRange(0, protocol.BRIGHTNESS_MAX), help="0 to 4.")(command)
+    command = click.option("--color", callback=color_argument, help="RRGGBB or a color name.")(command)
+    command = click.option("--rainbow", is_flag=True, help="Use changing colors instead of one color.")(command)
+    return command
+
+
+def apply_light(keyboard, effect, speed, brightness, color, rainbow, direction=None, side=False):
+    current = keyboard.light_state(side=side)
+    same_effect = current.effect == effect.value
+
+    speed = speed if speed is not None else (current.speed if same_effect else 2)
+    brightness = brightness if brightness is not None else current.brightness or protocol.BRIGHTNESS_MAX
+
+    if effect.value == protocol.EFFECT_OFF:
+        speed, brightness, option, color = 0, 0, protocol.OPTION_USER_COLOR, (0, 0, 0)
+    elif effect.value == protocol.EFFECT_CUSTOM:
+        option, color = protocol.OPTION_CUSTOM_SLOT_1, (0x00, 0xC8, 0xC8)
+    elif not effect.color:
+        option, color = protocol.OPTION_USER_COLOR, (0, 0, 0)
+    else:
+        if rainbow:
+            option = protocol.OPTION_RAINBOW
+        elif color is not None:
+            option = protocol.OPTION_USER_COLOR
+        else:
+            option = protocol.OPTION_RAINBOW if current.rainbow else protocol.OPTION_USER_COLOR
+        color = color or current.effective_color
+
+    if effect.directions:
+        variant = effect.directions.index(direction) if direction else (current.variant if same_effect else 0)
+        option |= variant << 4
+    elif direction:
+        raise click.BadParameter(f"{effect.name} has no direction", param_hint="--direction")
+
+    if not effect.speed:
+        speed = 0
+
+    return keyboard.set_light(effect.value, speed, brightness, option, color, side=side)
+
+
+@main.command()
+@click.argument("effect", type=click.Choice([effect.name for effect in protocol.EFFECTS if effect.name != "live"]))
+@light_options
+@click.option("--direction", type=click.Choice(["left", "right", "up", "down", "clockwise", "anticlockwise"]))
+@pass_context
+def mode(obj, effect, speed, brightness, color, rainbow, direction):
+    """Set the effect of the keys (stored in flash).
+
+    Options that are not given keep their current value.
+    """
+    effect = protocol.EFFECTS_BY_NAME[effect]
+    if direction and effect.directions and direction not in effect.directions:
+        raise click.BadParameter(f"{effect.name} supports {', '.join(effect.directions)}", param_hint="--direction")
+    with obj.open() as keyboard:
+        changed = apply_light(keyboard, effect, speed, brightness, color, rainbow, direction)
+        if not changed:
+            click.echo("Keys: unchanged")
+        elif not obj.dry_run:
+            click.echo(f"Keys: {describe(keyboard.light_state())}")
+
+
+@main.command()
+@pass_context
+def off(obj):
+    """Turn the key lighting off (stored in flash)."""
+    with obj.open() as keyboard:
+        apply_light(keyboard, protocol.EFFECTS_BY_NAME["off"], None, None, None, False)
+
+
+@main.command()
+@click.argument("effect", type=click.Choice([effect.name for effect in protocol.SIDE_EFFECTS]))
+@light_options
+@pass_context
+def side(obj, effect, speed, brightness, color, rainbow):
+    """Set the side light (stored in flash)."""
+    with obj.open() as keyboard:
+        if not keyboard.model.side_light:
+            raise click.ClickException(f"{keyboard.model.name} has no known side light")
+        changed = apply_light(keyboard, protocol.EFFECTS_BY_NAME[effect], speed, brightness, color, rainbow, side=True)
+        if changed and not obj.dry_run:
+            click.echo(f"Side: {describe(keyboard.light_state(side=True), side=True)}")
+
+
+@main.command()
+@click.argument("color", required=False, callback=color_argument)
+@click.option("--fade", type=float, metavar="SECONDS", help="Cycle through all hues for this long.")
+@click.option("--stdin", "from_stdin", is_flag=True, help="Read one color per line from standard input.")
+@pass_context
+def live(obj, color, fade, from_stdin):
+    """Set one color for all keys, without writing flash.
+
+    Switching into live mode is one flash write the first time; after that,
+    colors can change as often as wanted. The color is lost when the
+    keyboard is unplugged.
+    """
+    if sum(option is not None and option is not False for option in (color, fade, from_stdin)) != 1:
+        raise click.UsageError("give exactly one of COLOR, --fade or --stdin")
+
+    with obj.open() as keyboard:
+        keyboard.set_light(protocol.EFFECT_LIVE, 0, protocol.BRIGHTNESS_MAX, protocol.OPTION_USER_COLOR, (0, 0, 0))
+
+        if color is not None:
+            keyboard.live_color(color)
+        elif fade is not None:
+            start = time.time()
+            while time.time() - start < fade:
+                hue = ((time.time() - start) / 5.0) % 1.0
+                keyboard.live_color(tuple(int(c * 255) for c in colorsys.hsv_to_rgb(hue, 1.0, 1.0)))
+                time.sleep(1 / 30)
+        else:
+            for line in sys.stdin:
+                if line.strip():
+                    try:
+                        keyboard.live_color(protocol.parse_color(line))
+                    except ValueError as error:
+                        click.echo(f"skipped: {error}", err=True)
+
+
+@main.group()
+def custom():
+    """Per-key colors of the custom effect (stored in flash)."""
+
+
+def picture_colors(keyboard, picture):
+    return {key: tuple(picture[slot * 3:slot * 3 + 3]) for key, slot in keyboard.model.keys.items()}
+
+
+def write_picture(obj, keyboard, picture, changed_slots, activate):
+    if changed_slots and len(changed_slots) <= 3:
+        for slot in changed_slots:
+            keyboard.set_picture_key(slot, tuple(picture[slot * 3:slot * 3 + 3]))
+    elif changed_slots:
+        keyboard.set_picture(picture)
+    else:
+        obj.log("picture unchanged, nothing written")
+
+    if activate:
+        apply_light(keyboard, protocol.EFFECTS_BY_NAME["custom"], None, None, None, False)
+
+
+@custom.command("show")
+@click.option("--all", "show_all", is_flag=True, help="Also show keys that are off.")
+@click.option("--json", "as_json", is_flag=True, help="Print JSON (the format 'custom load' reads).")
+@pass_context
+def custom_show(obj, show_all, as_json):
+    """Show the stored custom picture."""
+    with obj.open() as keyboard:
+        colors = picture_colors(keyboard, keyboard.picture())
+    if as_json:
+        click.echo(json.dumps({key: protocol.format_color(color) for key, color in colors.items()}, indent=2))
+        return
+    for key, color in colors.items():
+        if show_all or any(color):
+            click.echo(f"{key:20} {protocol.format_color(color)}")
+
+
+@custom.command("set")
+@click.argument("assignments", nargs=-1, required=True, metavar="KEY=COLOR...")
+@click.option("--activate", is_flag=True, help="Also switch the keys to the custom effect.")
+@pass_context
+def custom_set(obj, assignments, activate):
+    """Change keys of the custom picture, e.g. 'escape=red w=00ff00'.
+
+    The key 'all' sets every key. 'kovarctl keys' lists the key names.
+    """
+    with obj.open() as keyboard:
+        picture = keyboard.picture()
+        changed = set()
+        for assignment in assignments:
+            key, _, value = assignment.partition("=")
+            try:
+                color = protocol.parse_color(value)
+            except ValueError as error:
+                raise click.BadParameter(str(error), param_hint=assignment)
+            if key == "all":
+                slots = list(keyboard.model.keys.values())
+            elif key in keyboard.model.keys:
+                slots = [keyboard.model.keys[key]]
+            else:
+                raise click.BadParameter(f"unknown key {key!r}, see 'kovarctl keys'", param_hint=assignment)
+            for slot in slots:
+                if tuple(picture[slot * 3:slot * 3 + 3]) != color:
+                    picture[slot * 3:slot * 3 + 3] = bytes(color)
+                    changed.add(slot)
+        write_picture(obj, keyboard, picture, sorted(changed), activate)
+
+
+@custom.command("save")
+@click.argument("file", type=click.File("w"))
+@pass_context
+def custom_save(obj, file):
+    """Save the custom picture as JSON."""
+    with obj.open() as keyboard:
+        colors = picture_colors(keyboard, keyboard.picture())
+    json.dump({key: protocol.format_color(color) for key, color in colors.items()}, file, indent=2)
+    file.write("\n")
+
+
+@custom.command("load")
+@click.argument("file", type=click.File("r"))
+@click.option("--activate", is_flag=True, help="Also switch the keys to the custom effect.")
+@pass_context
+def custom_load(obj, file, activate):
+    """Load a custom picture from JSON ({"escape": "#FF0000", ...}).
+
+    Keys missing in the file keep their color.
+    """
+    try:
+        data = json.load(file)
+    except ValueError as error:
+        raise click.ClickException(f"{file.name}: {error}")
+    with obj.open() as keyboard:
+        picture = keyboard.picture()
+        changed = set()
+        for key, value in data.items():
+            if key not in keyboard.model.keys:
+                raise click.ClickException(f"{file.name}: unknown key {key!r}")
+            slot = keyboard.model.keys[key]
+            color = protocol.parse_color(value)
+            if tuple(picture[slot * 3:slot * 3 + 3]) != color:
+                picture[slot * 3:slot * 3 + 3] = bytes(color)
+                changed.add(slot)
+        write_picture(obj, keyboard, picture, sorted(changed), activate)
+
+
+@main.command()
+@pass_context
+def recover(obj):
+    """Reset the keyboard if its lighting interface stopped answering."""
+    with obj.open(probe=False) as keyboard:
+        if obj.dry_run:
+            click.echo(f"would reset the keyboard at {keyboard.path}")
+            return
+        keyboard.reset()
+    time.sleep(3)
+    paths = find_vendor_interfaces()
+    for path in paths:
+        try:
+            with Keyboard(path) as keyboard:
+                click.echo(f"{path}: answers again, model ID {keyboard.device_id}")
+        except KeyboardError as error:
+            click.echo(f"{path}: {error}")

kovarctl/device.py

@@ -0,0 +1,263 @@
+"""Access to KOVAR keyboards through Linux hidraw.
+
+Safety rules learned on real hardware:
+- Only one program may talk to the vendor interface at a time. A lock file
+  guards kovarctl instances, and other programs (e.g. OpenRGB) holding the
+  hidraw node open are detected.
+- After a flash write the firmware must not receive anything for a while.
+  The end of that busy time is stored on disk, so separate kovarctl calls
+  respect it too.
+- Flash writes are rate limited across calls to protect the flash.
+"""
+
+import fcntl
+import glob
+import json
+import os
+import time
+
+from . import protocol
+
+VENDOR_ID = 0x3151
+PRODUCT_ID = 0x4010
+DONGLE_PRODUCT_IDS = (0x4011, 0x4014)
+VENDOR_INTERFACE = "input2"
+
+FLASH_WRITE_LIMIT = 12
+FLASH_WRITE_WINDOW = 60.0
+
+
+def _ioc(direction, nr, size):
+    return (direction << 30) | (size << 16) | (ord("H") << 8) | nr
+
+
+HIDIOCSFEATURE = _ioc(3, 0x06, protocol.REPORT_LENGTH + 1)
+HIDIOCGFEATURE = _ioc(3, 0x07, protocol.REPORT_LENGTH + 1)
+USBDEVFS_RESET = (ord("U") << 8) | 20
+
+
+class KeyboardError(Exception):
+    pass
+
+
+class FlashGuardError(KeyboardError):
+    pass
+
+
+def _hid_id(hidraw):
+    try:
+        uevent = open(f"/sys/class/hidraw/{hidraw}/device/uevent").read()
+    except OSError:
+        return None, None, None
+    fields = dict(line.split("=", 1) for line in uevent.splitlines() if "=" in line)
+    _, vid, pid = fields.get("HID_ID", "0:0:0").split(":")
+    return int(vid, 16), int(pid, 16), fields.get("HID_PHYS", "")
+
+
+def find_vendor_interfaces(product_ids=(PRODUCT_ID,)):
+    """Return /dev/hidrawN paths of the vendor interfaces of matching devices."""
+    paths = []
+    for node in sorted(glob.glob("/sys/class/hidraw/hidraw*"), key=lambda p: int(p.rsplit("hidraw", 1)[1])):
+        hidraw = os.path.basename(node)
+        vid, pid, phys = _hid_id(hidraw)
+        if vid == VENDOR_ID and pid in product_ids and phys.endswith(VENDOR_INTERFACE):
+            paths.append("/dev/" + hidraw)
+    return paths
+
+
+def other_users(path):
+    """Names of other processes that have the given device node open."""
+    users = []
+    for fd_dir in glob.glob("/proc/[0-9]*/fd"):
+        pid = fd_dir.split("/")[2]
+        if int(pid) == os.getpid():
+            continue
+        try:
+            for fd in os.listdir(fd_dir):
+                if os.readlink(os.path.join(fd_dir, fd)) == path:
+                    users.append(f"{open(f'/proc/{pid}/comm').read().strip()} ({pid})")
+                    break
+        except OSError:
+            continue
+    return users
+
+
+def _state_dir():
+    base = os.environ.get("XDG_RUNTIME_DIR") or f"/tmp/kovarctl-{os.getuid()}"
+    path = os.path.join(base, "kovarctl")
+    os.makedirs(path, mode=0o700, exist_ok=True)
+    return path
+
+
+class Keyboard:
+    """One KOVAR keyboard, opened through its vendor hidraw interface."""
+
+    def __init__(self, path, dry_run=False, force=False, log=None, probe=True):
+        vid, pid, phys = _hid_id(os.path.basename(path))
+        if vid != VENDOR_ID or pid != PRODUCT_ID or not phys.endswith(VENDOR_INTERFACE):
+            raise KeyboardError(f"{path} is not the vendor interface of a 3151:4010 keyboard")
+
+        self.path = path
+        self.dry_run = dry_run
+        self.force = force
+        self.log = log or (lambda message: None)
+        self.usb_port = phys.split("/")[0]
+
+        name = self.usb_port.replace("/", "_").replace(":", "_")
+        self._lock_file = open(os.path.join(_state_dir(), name + ".lock"), "w")
+        self._state_path = os.path.join(_state_dir(), name + ".json")
+        try:
+            fcntl.flock(self._lock_file, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise KeyboardError("another kovarctl is using this keyboard") from None
+
+        users = other_users(path)
+        if users:
+            raise KeyboardError(f"{path} is in use by {', '.join(users)}; close it first (e.g. OpenRGB)")
+
+        self._fd = os.open(path, os.O_RDWR)
+        self.device_id = None
+        self.model = None
+
+        if probe:
+            try:
+                self.device_id = protocol.parse_device_id(self.query(protocol.CMD_GET_DEVICE_INFO))
+            except (KeyboardError, ValueError) as error:
+                self.close()
+                raise KeyboardError(f"{path} does not answer ({error}); try 'kovarctl recover'") from None
+            self.model = protocol.MODELS.get(self.device_id)
+
+    def close(self):
+        os.close(self._fd)
+        self._lock_file.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # Persistent state shared between calls
+
+    def _load_state(self):
+        try:
+            with open(self._state_path) as state_file:
+                return json.load(state_file)
+        except (OSError, ValueError):
+            return {"busy_until": 0.0, "flash_writes": []}
+
+    def _save_state(self, state):
+        with open(self._state_path, "w") as state_file:
+            json.dump(state, state_file)
+
+    def wait_idle(self):
+        remaining = self._load_state()["busy_until"] - time.time()
+        if remaining > 0:
+            time.sleep(remaining)
+
+    # Raw transfers
+
+    def _send(self, data):
+        report = b"\0" + bytes(data).ljust(protocol.REPORT_LENGTH, b"\0")
+        try:
+            fcntl.ioctl(self._fd, HIDIOCSFEATURE, report)
+        except OSError as error:
+            raise KeyboardError(f"sending to {self.path} failed ({error}); "
+                                "if the keyboard stopped answering, run 'kovarctl recover'") from None
+
+    def _receive(self):
+        report = bytearray(protocol.REPORT_LENGTH + 1)
+        try:
+            fcntl.ioctl(self._fd, HIDIOCGFEATURE, report)
+        except OSError as error:
+            raise KeyboardError(f"reading from {self.path} failed ({error}); "
+                                "if the keyboard stopped answering, run 'kovarctl recover'") from None
+        return bytes(report[1:])
+
+    def query(self, command, *arguments, wait=0.02):
+        """Send a read request and return the 64 byte response."""
+        self.wait_idle()
+        self._send(protocol.payload(command, *arguments))
+        time.sleep(wait)
+        return self._receive()
+
+    # Reading
+
+    def revision(self):
+        response = self.query(protocol.CMD_GET_REV)
+        return f"{response[2]}.{response[1]:02d}"
+
+    def light_state(self, side=False):
+        command = protocol.CMD_GET_SIDE_PARAMS if side else protocol.CMD_GET_LED_PARAMS
+        return protocol.parse_led_params(self.query(command), side=side)
+
+    def picture(self):
+        data = b"".join(self.query(protocol.CMD_GET_PICTURE, 0x00, page) for page in range(protocol.PICTURE_FRAMES))
+        return bytearray(data[:protocol.PICTURE_SIZE])
+
+    # Writing
+
+    def flash_write(self, packets, busy, what):
+        """Send packets that end in a flash write, respecting busy time and rate limit."""
+        state = self._load_state()
+        now = time.time()
+        recent = [stamp for stamp in state["flash_writes"] if now - stamp < FLASH_WRITE_WINDOW]
+
+        if len(recent) >= FLASH_WRITE_LIMIT and not self.force:
+            raise FlashGuardError(
+                f"{len(recent)} flash writes in the last {FLASH_WRITE_WINDOW:.0f} s; refusing to write more "
+                "to protect the keyboard flash (use --force to override, or 'live' for fast changes)")
+
+        if self.dry_run:
+            for packet in packets:
+                self.log(f"would send {packet[:16].hex(' ')} ...")
+            return
+
+        self.wait_idle()
+        for index, packet in enumerate(packets):
+            if index > 0:
+                time.sleep(protocol.PICTURE_FRAME_DELAY)
+            self._send(packet)
+
+        state["busy_until"] = time.time() + busy
+        state["flash_writes"] = recent + [time.time()]
+        self._save_state(state)
+        self.log(f"flash write: {what}")
+
+    def set_light(self, effect, speed, brightness, option, color, side=False):
+        """Write LED or side light parameters unless the keyboard already has them."""
+        packet = protocol.led_params(effect, speed, brightness, option, color, side=side)
+        if protocol.state_bytes(self.light_state(side=side), side=side) == packet[:8]:
+            self.log("unchanged, nothing written")
+            return False
+        self.flash_write([packet], protocol.BUSY_LED_PARAMS, "side light" if side else "LED parameters")
+        return True
+
+    def set_picture(self, picture):
+        if bytes(self.picture()) == bytes(picture):
+            self.log("picture unchanged, nothing written")
+            return False
+        self.flash_write(protocol.picture_frames(picture), protocol.BUSY_PICTURE, "custom picture")
+        return True
+
+    def set_picture_key(self, slot, color):
+        self.flash_write([protocol.picture_key(slot, color)], protocol.BUSY_PICTURE_KEY, f"custom key slot {slot}")
+
+    def live_color(self, color):
+        """RAM only, safe to send often."""
+        if self.dry_run:
+            self.log(f"would send {protocol.live_color(color)[:8].hex(' ')}")
+            return
+        self.wait_idle()
+        self._send(protocol.live_color(color))
+
+    def reset(self):
+        """USB reset of the keyboard, recovers a locked up vendor interface."""
+        usb_device = os.path.realpath(f"/sys/class/hidraw/{os.path.basename(self.path)}/device/../..")
+        bus = int(open(os.path.join(usb_device, "busnum")).read())
+        device = int(open(os.path.join(usb_device, "devnum")).read())
+        fd = os.open(f"/dev/bus/usb/{bus:03d}/{device:03d}", os.O_WRONLY)
+        try:
+            fcntl.ioctl(fd, USBDEVFS_RESET, 0)
+        finally:
+            os.close(fd)