muxplex-deck 0.4.0__py3-none-any.whl

deck_probe/__init__.py

@@ -0,0 +1,14 @@
+"""deck_probe: Elgato Stream Deck+ hardware probe.
+
+Proves we can drive every feature of the Stream Deck+ (8 LCD keys, 4 dial
+encoders, 800x100 touch strip) and capture every input, including clean
+hotplug (unplug/replug) handling with no crash and no zombie threads.
+
+This is the seed of the future muxplex sidecar's device I/O layer -- no
+server/network integration lives in this package, device I/O only.
+"""
+
+from .main import main
+
+__all__ = ["main"]
+__version__ = "0.2.0"

deck_probe/__main__.py

@@ -0,0 +1,6 @@
+"""Allows `python -m deck_probe` to run the probe."""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

deck_probe/capabilities.py

@@ -0,0 +1,130 @@
+"""Capability discovery for any Stream Deck model.
+
+The probe adapts to whatever deck is plugged in by querying the library's
+capability methods (present on every model -- the base `StreamDeck` class
+exposes each subclass's constants). The hard rule: **branch only on
+numeric/boolean capability values, never on `deck_type()` strings** --
+model names collide (Original vs MK2 are both 15-key/3x5) and new models
+would need matrix updates. Capabilities self-describe.
+
+`describe_capabilities` is pure: it takes any object exposing the
+capability methods (real deck, fake, emulator) and returns a plain dict,
+so the "which deck is this and what can it do" logic is unit-testable
+without hardware.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class DeckCapabilitySource(Protocol):
+    """The capability surface every `StreamDeck` subclass exposes.
+
+    Structural typing lets tests substitute fakes and keeps this module
+    free of hardware imports. `get_serial_number`/`get_firmware_version`
+    require an *open* device; everything else reads class constants.
+    """
+
+    def deck_type(self) -> str: ...
+    def get_serial_number(self) -> str: ...
+    def get_firmware_version(self) -> str: ...
+    def vendor_id(self) -> int: ...
+    def product_id(self) -> int: ...
+    def key_count(self) -> int: ...
+    def key_layout(self) -> tuple[int, int]: ...
+    def key_image_format(self) -> dict[str, Any]: ...
+    def dial_count(self) -> int: ...
+    def touch_key_count(self) -> int: ...
+    def is_touch(self) -> bool: ...
+    def is_visual(self) -> bool: ...
+    def touchscreen_image_format(self) -> dict[str, Any]: ...
+
+
+def describe_capabilities(deck: DeckCapabilitySource) -> dict[str, Any]:
+    """Build a capability report dict for the given (open) deck.
+
+    Pure with respect to the deck object: only calls its capability
+    methods, performs no device I/O beyond the serial/firmware reads.
+    """
+    rows, cols = deck.key_layout()
+    is_visual = deck.is_visual()
+    key_format = deck.key_image_format() if is_visual else None
+    has_touchscreen = deck.is_touch()
+    touchscreen_size = (
+        tuple(deck.touchscreen_image_format()["size"]) if has_touchscreen else None
+    )
+    return {
+        "model": deck.deck_type(),
+        "serial": deck.get_serial_number(),
+        "firmware": deck.get_firmware_version(),
+        "vendor_id": deck.vendor_id(),
+        "product_id": deck.product_id(),
+        "key_count": deck.key_count(),
+        "key_rows": rows,
+        "key_cols": cols,
+        "key_image_size": tuple(key_format["size"]) if key_format else None,
+        "key_image_format": key_format["format"] if key_format else None,
+        "dial_count": deck.dial_count(),
+        "touch_key_count": deck.touch_key_count(),
+        "has_touchscreen": has_touchscreen,
+        "touchscreen_size": touchscreen_size,
+        "is_visual": is_visual,
+    }
+
+
+def exercises_keys(caps: dict[str, Any]) -> bool:
+    """Should the probe paint and monitor LCD keys? (Pedal has none visual.)"""
+    return caps["key_count"] > 0 and caps["is_visual"]
+
+
+def exercises_dials(caps: dict[str, Any]) -> bool:
+    """Should the probe attach dial handling? Only when dials exist."""
+    return caps["dial_count"] > 0
+
+
+def exercises_touchscreen(caps: dict[str, Any]) -> bool:
+    """Should the probe paint/monitor the touch strip? Only when one exists."""
+    return caps["has_touchscreen"]
+
+
+def exercises_touch_keys(caps: dict[str, Any]) -> bool:
+    """Does this model have discrete touch buttons (e.g. Neo's 2)?"""
+    return caps["touch_key_count"] > 0
+
+
+def format_capability_report(caps: dict[str, Any]) -> str:
+    """Render the capability dict as a human-readable multi-line block."""
+    key_size = caps["key_image_size"]
+    key_size_text = f"{key_size[0]}x{key_size[1]}" if key_size else "none (not visual)"
+    key_format_text = caps["key_image_format"] or "-"
+    if caps["has_touchscreen"]:
+        ts_w, ts_h = caps["touchscreen_size"]
+        touchscreen_text = f"yes ({ts_w}x{ts_h})"
+    else:
+        touchscreen_text = "no"
+    lines = [
+        "deck capabilities:",
+        f"  model:            {caps['model']}",
+        f"  serial:           {caps['serial']}",
+        f"  firmware:         {caps['firmware']}",
+        f"  usb id:           {caps['vendor_id']:04x}:{caps['product_id']:04x}",
+        f"  keys:             {caps['key_count']} ({caps['key_rows']}x{caps['key_cols']})",
+        f"  key image:        {key_size_text} {key_format_text}",
+        f"  dials:            {caps['dial_count']}",
+        f"  touch keys:       {caps['touch_key_count']}",
+        f"  touchscreen:      {touchscreen_text}",
+        f"  visual:           {'yes' if caps['is_visual'] else 'no'}",
+        "  probe will exercise: "
+        + ", ".join(
+            part
+            for part, active in (
+                ("keys", exercises_keys(caps)),
+                ("dials", exercises_dials(caps)),
+                ("touchscreen", exercises_touchscreen(caps)),
+                ("touch-keys", exercises_touch_keys(caps)),
+            )
+            if active
+        ),
+    ]
+    return "\n".join(lines)

deck_probe/events.py

@@ -0,0 +1,211 @@
+"""Device-event handling for the Stream Deck probe (any model).
+
+Owns the small piece of mutable session state each control's callback needs
+(dial counters, current brightness, last tap marker) and wires the
+`streamdeck` library's key/dial/touchscreen callbacks to logging plus
+`rendering.py` calls that reflect the new state back onto the device.
+
+Everything is capability-gated: keys are always exercised (sized from the
+deck's own `key_image_format()`), dials only when `dial_count() > 0`, the
+touch strip only when `is_touch()`. Branching is on numeric/boolean
+capabilities -- never on `deck_type()` strings.
+
+No hotplug/lifecycle logic lives here -- that's main.py's job. This module
+only cares about "device is open, here's what happened, here's how to show it."
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from StreamDeck.Devices.StreamDeck import (
+    DialEventType,
+    StreamDeck,
+    TouchscreenEventType,
+)
+
+from . import rendering
+
+logger = logging.getLogger("deck_probe")
+
+BRIGHTNESS_DIAL_INDEX = 0
+DEFAULT_BRIGHTNESS_PERCENT = 75
+
+
+@dataclass
+class ProbeState:
+    """Mutable runtime state for one active (connected) probe session."""
+
+    brightness_percent: int = DEFAULT_BRIGHTNESS_PERCENT
+    dial_counters: list[int] = field(default_factory=list)
+    marker_x: int | None = None
+
+
+def _paint_full_touchscreen(deck: StreamDeck, image: bytes) -> None:
+    """Paint the entire touch strip.
+
+    Only call on decks where `is_touch()` is True. The library requires
+    explicit region dimensions for a non-empty image (width/height default
+    to 0, which raises `IndexError: Invalid draw width 0.`), so full
+    repaints must pass the strip's full size.
+    """
+    width, height = deck.touchscreen_image_format()["size"]
+    deck.set_touchscreen_image(image, 0, 0, width, height)
+
+
+def paint_initial_state(deck: StreamDeck) -> ProbeState:
+    """Paint keys (and the touch strip, when present) for a fresh connection.
+
+    Returns the fresh `ProbeState` that callbacks should mutate for the
+    lifetime of this connection. Adapts to the connected model: key count
+    and image size come from the device, and the touch strip is painted
+    only when the deck has one.
+    """
+    state = ProbeState(dial_counters=[0] * deck.dial_count())
+    with deck:
+        deck.set_brightness(state.brightness_percent)
+        for index in range(deck.key_count()):
+            deck.set_key_image(index, rendering.render_key_image(deck, index))
+        if deck.is_touch():
+            _paint_full_touchscreen(
+                deck,
+                rendering.render_touchscreen_full(
+                    deck,
+                    brightness_percent=state.brightness_percent,
+                    counters=state.dial_counters,
+                ),
+            )
+    return state
+
+
+def _zone_label_and_value(
+    state: ProbeState, dial_index: int, labels: tuple[str, ...]
+) -> tuple[str, str]:
+    if dial_index == BRIGHTNESS_DIAL_INDEX:
+        return labels[0], f"{state.brightness_percent}%"
+    return labels[dial_index], str(state.dial_counters[dial_index])
+
+
+def _redraw_zone(deck: StreamDeck, state: ProbeState, dial_index: int) -> None:
+    labels = rendering.zone_labels(deck.dial_count())
+    label, value = _zone_label_and_value(state, dial_index, labels)
+    image, x, y, width, height = rendering.render_touchscreen_zone(
+        deck, dial_index, label, value
+    )
+    deck.set_touchscreen_image(image, x, y, width, height)
+
+
+def make_key_callback():
+    """Build the key-press callback: log + invert colors while held."""
+
+    def on_key(deck: StreamDeck, key: int, pressed: bool) -> None:
+        logger.info("key[%d] %s", key, "PRESSED" if pressed else "released")
+        deck.set_key_image(
+            key, rendering.render_key_image(deck, key, highlighted=pressed)
+        )
+
+    return on_key
+
+
+def make_dial_callback(state: ProbeState):
+    """Build the dial callback: dial 0 drives brightness, the rest are counters.
+
+    Zone repaints on the touch strip happen only when the deck has one
+    (`is_touch()`); dial-only decks still get full logging + brightness.
+    """
+
+    def on_dial(
+        deck: StreamDeck, dial: int, event_type: DialEventType, value: object
+    ) -> None:
+        if event_type == DialEventType.TURN:
+            amount = int(value)  # type: ignore[arg-type]
+            direction = "clockwise" if amount > 0 else "counter-clockwise"
+            logger.info("dial[%d] TURN %+d (%s)", dial, amount, direction)
+            with deck:
+                if dial == BRIGHTNESS_DIAL_INDEX:
+                    state.brightness_percent = max(
+                        0, min(100, state.brightness_percent + amount)
+                    )
+                    deck.set_brightness(state.brightness_percent)
+                else:
+                    state.dial_counters[dial] += amount
+                if deck.is_touch():
+                    _redraw_zone(deck, state, dial)
+
+        elif event_type == DialEventType.PUSH:
+            pressed = bool(value)
+            logger.info("dial[%d] %s", dial, "PRESSED" if pressed else "released")
+            if pressed:
+                with deck:
+                    if dial == BRIGHTNESS_DIAL_INDEX:
+                        state.brightness_percent = DEFAULT_BRIGHTNESS_PERCENT
+                        deck.set_brightness(state.brightness_percent)
+                    else:
+                        state.dial_counters[dial] = 0
+                    if deck.is_touch():
+                        _redraw_zone(deck, state, dial)
+
+    return on_dial
+
+
+def make_touchscreen_callback(state: ProbeState):
+    """Build the touchscreen callback: tap draws a marker, drag/long just log."""
+
+    def on_touch(
+        deck: StreamDeck, event_type: TouchscreenEventType, value: dict
+    ) -> None:
+        if event_type == TouchscreenEventType.SHORT:
+            x, y = value["x"], value["y"]
+            logger.info("touch SHORT tap at (%d, %d)", x, y)
+            state.marker_x = x
+            with deck:
+                _paint_full_touchscreen(
+                    deck,
+                    rendering.render_touchscreen_full(
+                        deck,
+                        brightness_percent=state.brightness_percent,
+                        counters=state.dial_counters,
+                        marker_x=state.marker_x,
+                    ),
+                )
+
+        elif event_type == TouchscreenEventType.LONG:
+            logger.info("touch LONG press at (%d, %d)", value["x"], value["y"])
+
+        elif event_type == TouchscreenEventType.DRAG:
+            logger.info(
+                "touch DRAG from (%d, %d) to (%d, %d)",
+                value["x"],
+                value["y"],
+                value["x_out"],
+                value["y_out"],
+            )
+
+    return on_touch
+
+
+def attach_callbacks(deck: StreamDeck, state: ProbeState) -> None:
+    """Register callbacks for every control the connected deck actually has.
+
+    Capability-gated: keys always, dials only if the deck has dials, the
+    touchscreen only if the deck has one. Absent controls are logged so the
+    user knows the skip is deliberate, not a failure.
+    """
+    deck.set_key_callback(make_key_callback())
+
+    if deck.dial_count() > 0:
+        deck.set_dial_callback(make_dial_callback(state))
+    else:
+        logger.info("no dials on this model -- skipping dial exercise")
+
+    if deck.is_touch():
+        deck.set_touchscreen_callback(make_touchscreen_callback(state))
+    else:
+        logger.info("no touchscreen on this model -- skipping touch exercise")
+
+    if deck.touch_key_count() > 0:
+        logger.info(
+            "model reports %d touch key(s) -- these surface as regular key events",
+            deck.touch_key_count(),
+        )

deck_probe/main.py

@@ -0,0 +1,220 @@
+"""Stream Deck hardware probe (any model): entry point and hotplug state machine.
+
+The probe is capability-driven: it reports what the connected deck can do
+(model, keys, layout, dials, touchscreen, touch keys) and exercises only
+the controls that exist -- one probe for the 15-key Original/MK2, the
+Plus, the XL, the Mini, the Neo, and whatever ships next. Branching is on
+numeric/boolean capabilities (`key_count()`, `dial_count()`, `is_touch()`),
+never on `deck_type()` model-name strings.
+
+This state machine (DEVICE_ABSENT <-> DEVICE_ACTIVE) is the seed of the
+future muxplex sidecar's core loop, so it's kept clean and self-contained:
+
+- DEVICE_ABSENT: no device found. Re-enumerate every `POLL_INTERVAL_SECONDS`,
+  logging once (not spamming every poll), with a periodic heartbeat.
+- DEVICE_ACTIVE: device is open and its callbacks are attached. We poll the
+  device's own health (`is_open()` / `connected()`) to detect unplug, since
+  the underlying reader thread may or may not surface a read error the
+  instant the cable is pulled.
+- Ctrl+C / SIGTERM: clean shutdown from either state -- reset/blank the
+  device if one is connected, close the handle, exit 0.
+
+No server/network integration lives here -- device I/O only.
+"""
+
+from __future__ import annotations
+
+import logging
+import signal
+import sys
+import threading
+import time
+
+from StreamDeck.DeviceManager import DeviceManager, ProbeError
+from StreamDeck.Devices.StreamDeck import StreamDeck
+from StreamDeck.Transport.Transport import TransportError
+
+from . import capabilities, events
+
+logger = logging.getLogger("deck_probe")
+
+POLL_INTERVAL_SECONDS = 2.0
+ABSENT_HEARTBEAT_SECONDS = 30.0
+ACTIVE_HEALTH_CHECK_SECONDS = 2.0
+
+
+def _configure_logging() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s.%(msecs)03d %(levelname)s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def _explain_missing_hidapi() -> str:
+    return (
+        "Could not find the native HIDAPI library required to talk to the Stream Deck.\n"
+        "Install it for your platform, then try again:\n"
+        "  macOS:          brew install hidapi\n"
+        "  Debian/Ubuntu:  sudo apt install libhidapi-libusb0\n"
+        "  Windows:        bundled with the 'streamdeck' wheel; if missing, install\n"
+        "                  hidapi via your package manager of choice.\n"
+    )
+
+
+def _no_device_guidance() -> str:
+    return (
+        "No Stream Deck found. Things to check:\n"
+        "  - All platforms: close the official Elgato Stream Deck app -- it holds\n"
+        "    exclusive HID access, so this probe cannot open the device while it runs.\n"
+        "  - Linux (incl. WSL): a udev rule must grant access to Elgato devices\n"
+        "    (vendor id 0x0fd9). Create /etc/udev/rules.d/70-streamdeck.rules with:\n"
+        '      SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0fd9", MODE="0666"\n'
+        "    then: sudo udevadm control --reload-rules && replug the device.\n"
+        "  - WSL specifically: USB devices are not visible until attached from\n"
+        "    Windows via usbipd -- in an admin PowerShell:\n"
+        "      usbipd list                        (find the Stream Deck's BUSID)\n"
+        "      usbipd bind --busid <BUSID>        (first time only)\n"
+        "      usbipd attach --wsl --busid <BUSID>\n"
+        "    (and remember the Elgato app on the Windows side must be closed).\n"
+    )
+
+
+def _find_deck(manager: DeviceManager) -> StreamDeck | None:
+    decks = manager.enumerate()
+    return decks[0] if decks else None
+
+
+def _log_device_info(deck: StreamDeck) -> None:
+    """Print the capability report: which deck this is and what it can do."""
+    for line in capabilities.format_capability_report(
+        capabilities.describe_capabilities(deck)
+    ).splitlines():
+        logger.info("%s", line)
+
+
+def _safe_close(deck: StreamDeck) -> None:
+    """Reset and close the device, swallowing (but logging) any I/O errors.
+
+    Used both for clean Ctrl+C shutdown and for recovering after an unplug
+    or unexpected error -- either way we must not leave a half-open handle
+    or a zombie reader thread behind.
+    """
+    try:
+        if deck.is_open():
+            deck.reset()
+    except TransportError:
+        pass
+    except Exception:
+        logger.exception("Unexpected error while resetting deck during close")
+
+    try:
+        deck.close()
+    except Exception:
+        logger.exception("Unexpected error while closing deck")
+
+
+def _run_active(deck: StreamDeck, shutting_down: threading.Event) -> None:
+    """Run one connected-device session until it disconnects or shutdown is requested."""
+    _log_device_info(deck)
+    state = events.paint_initial_state(deck)
+    events.attach_callbacks(deck, state)
+    logger.info("%s active -- waiting for input (Ctrl+C to exit)", deck.deck_type())
+
+    try:
+        while True:
+            if shutting_down.wait(ACTIVE_HEALTH_CHECK_SECONDS):
+                return
+            if not deck.is_open() or not deck.connected():
+                logger.warning("Stream Deck disconnected")
+                return
+    finally:
+        _safe_close(deck)
+
+
+def _install_signal_handler() -> threading.Event:
+    shutting_down = threading.Event()
+
+    def handler(signum: int, frame: object) -> None:
+        shutting_down.set()
+
+    signal.signal(signal.SIGINT, handler)
+    signal.signal(signal.SIGTERM, handler)
+    return shutting_down
+
+
+def run() -> int:
+    _configure_logging()
+
+    try:
+        manager = DeviceManager()
+    except ProbeError:
+        print(_explain_missing_hidapi(), file=sys.stderr)
+        return 1
+
+    shutting_down = _install_signal_handler()
+    logged_waiting = False
+    guidance_shown = False
+    last_heartbeat = 0.0
+
+    logger.info("deck-probe starting")
+    try:
+        while not shutting_down.is_set():
+            try:
+                deck = _find_deck(manager)
+            except Exception:
+                logger.exception(
+                    "Unexpected error while enumerating Stream Deck devices; will retry"
+                )
+                shutting_down.wait(POLL_INTERVAL_SECONDS)
+                continue
+
+            if deck is None:
+                now = time.monotonic()
+                if not logged_waiting:
+                    if not guidance_shown:
+                        for line in _no_device_guidance().splitlines():
+                            logger.info("%s", line)
+                        guidance_shown = True
+                    logger.info(
+                        "waiting for a Stream Deck (polling every %.0fs)...",
+                        POLL_INTERVAL_SECONDS,
+                    )
+                    logged_waiting = True
+                    last_heartbeat = now
+                elif now - last_heartbeat >= ABSENT_HEARTBEAT_SECONDS:
+                    logger.info("still waiting for a Stream Deck...")
+                    last_heartbeat = now
+                shutting_down.wait(POLL_INTERVAL_SECONDS)
+                continue
+
+            logged_waiting = False
+            try:
+                deck.open()
+            except Exception:
+                logger.exception("Failed to open Stream Deck device; will retry")
+                shutting_down.wait(POLL_INTERVAL_SECONDS)
+                continue
+
+            try:
+                _run_active(deck, shutting_down)
+            except Exception:
+                logger.exception("Unexpected error during active session; recovering")
+                _safe_close(deck)
+                # Back off before re-enumerating: without this, a deterministic
+                # error during session setup (e.g. a bad paint call) spins the
+                # connect/fail/reset cycle at full speed -- flooding the log and
+                # strobing the device.
+                shutting_down.wait(POLL_INTERVAL_SECONDS)
+    finally:
+        logger.info("deck-probe shutting down")
+
+    return 0
+
+
+def main() -> None:
+    sys.exit(run())
+
+
+if __name__ == "__main__":
+    main()