displaypad-driver 1.0.0__tar.gz

displaypad_driver-1.0.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: displaypad-driver
+Version: 1.0.0
+Summary: A Driver to communicate with the mountain displaypad.
+License: MIT
+Author: AnnikenToGo
+Author-email: anniken@annikentogo.de
+Requires-Python: >=3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pillow (>=12.1.0,<13.0.0)
+Requires-Dist: pyusb (>=1.3.1,<2.0.0)
+Description-Content-Type: text/markdown
+
+# displaypad-driver package
+
+`displaypad-driver` provides a thread-safe, high-performance driver for the Mountain DisplayPad device.
+
+## Acknowledgments
+Performance optimizations, dual-interface transport handling, initialization handshakes, and input report interleaving were built with inspiration from [ramisotti13-eng/BaseCamp-Linux](https://github.com/ramisotti13-eng/BaseCamp-Linux).
+
+## Modules
+
+- `transport.py` — Low-level interface opener (`open_interfaces`, `init_handshake_ctrl`, `close_interfaces`). Claims Interface 1 (PyUSB display bulk transfer endpoint `0x02`) and Interface 3 (`hidapi` command/event endpoint), handles temporary IF0 kernel driver detachment to send HID `SET_IDLE` and `SET_REPORT` commands.
+- `device.py` — Thread-safe `DisplayPad` manager.
+  - `upload_button(key_index, bgr_pixels)` — Uploads a 102×102 BGR tile to a specific key slot (0–11) with non-blocking HID report interleaving.
+  - `upload_panel(tiles_bgr)` — Uploads 12 tile payloads in batch.
+  - `poll_key(timeout)` — Non-blocking polling returning `pressed`, `released`, and `current` key lists.
+  - `set_brightness(percent)` — Adjusts backlight brightness (0–100%).
+- `protocol.py` — VID/PID constants, payload headers, INIT/IMG templates, and `get_pressed_keys` bitmask parser.
+- `image.py` — Image processing utilities:
+  - `image_to_bgr102(img, rotation)` — Converts PIL Image to 102×102 BGR bytes with 0°/90°/180°/270° rotation.
+  - `split_image_to_tiles(img, rotation)` — Slices full-panel 612×204 images into 12 BGR tile payloads.
+  - `split_gif_to_tiles(gif)` & `load_gif_frames(gif)` — Animated GIF parser.
+  - `make_label_icon()` & `make_folder_icon()` — Dynamic text label and icon generator.
+
+For a usage example, see [driver_example.py](../../examples/driver_example.py).
+
+

displaypad_driver-1.0.0/README.md

@@ -0,0 +1,24 @@
+# displaypad-driver package
+
+`displaypad-driver` provides a thread-safe, high-performance driver for the Mountain DisplayPad device.
+
+## Acknowledgments
+Performance optimizations, dual-interface transport handling, initialization handshakes, and input report interleaving were built with inspiration from [ramisotti13-eng/BaseCamp-Linux](https://github.com/ramisotti13-eng/BaseCamp-Linux).
+
+## Modules
+
+- `transport.py` — Low-level interface opener (`open_interfaces`, `init_handshake_ctrl`, `close_interfaces`). Claims Interface 1 (PyUSB display bulk transfer endpoint `0x02`) and Interface 3 (`hidapi` command/event endpoint), handles temporary IF0 kernel driver detachment to send HID `SET_IDLE` and `SET_REPORT` commands.
+- `device.py` — Thread-safe `DisplayPad` manager.
+  - `upload_button(key_index, bgr_pixels)` — Uploads a 102×102 BGR tile to a specific key slot (0–11) with non-blocking HID report interleaving.
+  - `upload_panel(tiles_bgr)` — Uploads 12 tile payloads in batch.
+  - `poll_key(timeout)` — Non-blocking polling returning `pressed`, `released`, and `current` key lists.
+  - `set_brightness(percent)` — Adjusts backlight brightness (0–100%).
+- `protocol.py` — VID/PID constants, payload headers, INIT/IMG templates, and `get_pressed_keys` bitmask parser.
+- `image.py` — Image processing utilities:
+  - `image_to_bgr102(img, rotation)` — Converts PIL Image to 102×102 BGR bytes with 0°/90°/180°/270° rotation.
+  - `split_image_to_tiles(img, rotation)` — Slices full-panel 612×204 images into 12 BGR tile payloads.
+  - `split_gif_to_tiles(gif)` & `load_gif_frames(gif)` — Animated GIF parser.
+  - `make_label_icon()` & `make_folder_icon()` — Dynamic text label and icon generator.
+
+For a usage example, see [driver_example.py](../../examples/driver_example.py).
+

displaypad_driver-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "displaypad-driver"
+version = "1.0.0"
+
+description = "A Driver to communicate with the mountain displaypad."
+authors = [
+    {name = "AnnikenToGo",email = "anniken@annikentogo.de"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "pillow (>=12.1.0,<13.0.0)",
+    "pyusb (>=1.3.1,<2.0.0)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

displaypad_driver-1.0.0/src/displaypad_driver/__init__.py

@@ -0,0 +1,41 @@
+"""DisplayPad package exports."""
+
+from .device import DisplayPad
+from .image import (
+    image_to_bgr102, split_image_to_tiles, split_gif_to_tiles,
+    load_gif_frames, make_label_icon, make_folder_icon
+)
+from .exceptions import DisplayPadError, TransportError, DeviceNotFoundError
+from .protocol import (
+    VID, PID, NUM_KEYS, KEYS_PER_ROW, ICON_SIZE, CHUNK_SIZE,
+    HEADER_SIZE, PACKET_SIZE, EP_DISPLAY, EP_CMD, EP_IN
+)
+
+__version__ = "1.0.0"
+
+
+__all__ = [
+    "__version__",
+    "DisplayPad",
+
+    "image_to_bgr102",
+    "split_image_to_tiles",
+    "split_gif_to_tiles",
+    "load_gif_frames",
+    "make_label_icon",
+    "make_folder_icon",
+    "DisplayPadError",
+    "TransportError",
+    "DeviceNotFoundError",
+    "VID",
+    "PID",
+    "NUM_KEYS",
+    "KEYS_PER_ROW",
+    "ICON_SIZE",
+    "CHUNK_SIZE",
+    "HEADER_SIZE",
+    "PACKET_SIZE",
+    "EP_DISPLAY",
+    "EP_CMD",
+    "EP_IN",
+]

displaypad_driver-1.0.0/src/displaypad_driver/device.py

@@ -0,0 +1,222 @@
+"""Higher-level DisplayPad device API built on top of the USB transport."""
+
+import logging
+import threading
+import time
+from typing import List, Dict, Optional, Tuple, Set
+
+
+from .exceptions import DisplayPadError, TransportError, DeviceNotFoundError
+from .protocol import (
+    VID, PID, NUM_KEYS, ICON_SIZE, CHUNK_SIZE, HEADER_SIZE, PACKET_SIZE,
+    EP_DISPLAY, INIT_MSG, IMG_MSG_TEMPLATE, KEY_MAP, get_pressed_keys
+)
+from .transport import open_interfaces, close_interfaces, check_dependencies
+
+log = logging.getLogger(__name__)
+
+
+class DisplayPad:
+    """Object representing the DisplayPad device.
+
+    Example:
+        with DisplayPad() as d:
+            d.set_brightness(50)
+            d.upload_button(0, bgr_data)
+    """
+
+    def __init__(self, vendor_id: int = VID, product_id: int = PID):
+        self.vendor_id = vendor_id
+        self.product_id = product_id
+        self.usb_dev = None
+        self.hid_dev = None
+        self.pressed_keys: Set[int] = set()
+        self.connected = False
+        self._usb_lock = threading.Lock()
+        self._pending_key_packets: List[bytes] = []
+
+        self.connect()
+
+    def connect(self):
+        """Open USB interfaces and execute initialization handshake."""
+        with self._usb_lock:
+            if self.connected:
+                return
+
+            self.usb_dev, self.hid_dev = open_interfaces()
+            self._init_device()
+            self.connected = True
+
+    def close(self):
+        """Close USB interfaces and release resources."""
+        with self._usb_lock:
+            if self.connected:
+                close_interfaces(self.usb_dev, self.hid_dev)
+                self.usb_dev = None
+                self.hid_dev = None
+                self.connected = False
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+    def _init_device(self):
+        """Send INIT_MSG on Interface 3 and wait for a matching echo with 250ms firmware settling sleep."""
+        if not self.hid_dev:
+            raise DisplayPadError("HID device interface not open")
+
+        pkt = INIT_MSG
+        echo = pkt[1:6]
+        ack_received = False
+
+        for _attempt in range(60):
+            try:
+                self.hid_dev.write(pkt)
+            except Exception:
+                time.sleep(0.01)
+                continue
+
+            try:
+                resp = self.hid_dev.read(64, timeout=500)
+            except Exception:
+                resp = None
+
+            if not resp:
+                time.sleep(0.01)
+                continue
+
+            if len(resp) >= 5 and bytes(resp[:5]) == echo:
+                # Firmware settling delay before display engine is ready
+                time.sleep(0.25)
+                ack_received = True
+                break
+
+        if not ack_received:
+            raise DisplayPadError("DisplayPad did not respond to INIT handshake")
+
+    def set_brightness(self, percent: int = 100):
+        """Set DisplayPad backlight brightness. percent: 0 to 100."""
+        with self._usb_lock:
+            if not self.hid_dev:
+                raise DisplayPadError("Device not connected")
+
+            percent = max(0, min(100, int(percent)))
+            buf = bytearray(64)
+            buf[0] = 0x12
+            buf[1] = 0x03
+            buf[4] = percent
+            try:
+                self.hid_dev.write(bytes(buf))
+            except Exception as e:
+                raise DisplayPadError(f"Failed to set brightness: {e}")
+
+    def upload_button(self, key_index: int, bgr_pixels: bytes, key_events: Optional[list] = None):
+        """Upload a 102x102 BGR image payload to a specific button (key_index 0..11).
+
+        If key_events list is provided or key events arrive during ACK wait,
+        key event reports are buffered so no keypresses are lost.
+        """
+        if not (0 <= key_index < NUM_KEYS):
+            raise ValueError(f"key_index must be between 0 and {NUM_KEYS - 1}")
+
+        with self._usb_lock:
+            if not self.usb_dev or not self.hid_dev:
+                raise DisplayPadError("Device not connected")
+
+            # Step 1: Send image message template targeting key_index
+            msg = bytearray(IMG_MSG_TEMPLATE)
+            msg[5] = key_index
+            self.hid_dev.write(bytes(msg))
+
+            # Step 2: Wait for readiness ACK (0x21 0x00 0x00), buffering incoming key events
+            for _ in range(100):
+                resp = self.hid_dev.read(64, timeout=5)
+                if resp and len(resp) >= 3 and resp[0] == 0x21 and resp[1] == 0x00 and resp[2] == 0x00:
+                    break
+                if resp and len(resp) >= 48 and resp[0] == 0x01:
+                    raw_evt = bytes(resp)
+                    if not self._pending_key_packets or self._pending_key_packets[-1] != raw_evt:
+                        self._pending_key_packets.append(raw_evt)
+                    if key_events is not None:
+                        key_events.append(list(resp))
+            else:
+                raise DisplayPadError(f"No ready response for key {key_index}")
+
+            # Step 3: Write payload (HEADER_SIZE + PACKET_SIZE) in 1024-byte chunks
+            payload = bytearray(HEADER_SIZE + PACKET_SIZE)
+            payload[HEADER_SIZE:HEADER_SIZE + len(bgr_pixels)] = bgr_pixels
+
+            for i in range(0, len(payload), CHUNK_SIZE):
+                self.usb_dev.write(EP_DISPLAY, bytes(payload[i:i + CHUNK_SIZE]), timeout=1000)
+
+            # Step 4: Wait for confirmation ACK (0x21 0x00 0xFF), buffering incoming key events
+            for _ in range(100):
+                resp = self.hid_dev.read(64, timeout=5)
+                if resp and len(resp) >= 3 and resp[0] == 0x21 and resp[1] == 0x00 and resp[2] == 0xFF:
+                    return
+                if resp and len(resp) >= 48 and resp[0] == 0x01:
+                    raw_evt = bytes(resp)
+                    if not self._pending_key_packets or self._pending_key_packets[-1] != raw_evt:
+                        self._pending_key_packets.append(raw_evt)
+                    if key_events is not None:
+                        key_events.append(list(resp))
+
+            raise DisplayPadError(f"Transfer confirmation timed out for key {key_index}")
+
+
+
+    def upload_panel(self, tiles_bgr: List[bytes], key_events: Optional[list] = None):
+        """Upload BGR payloads for all 12 buttons."""
+        if len(tiles_bgr) != NUM_KEYS:
+            raise ValueError(f"Expected {NUM_KEYS} BGR tile payloads, got {len(tiles_bgr)}")
+
+        for idx, bgr in enumerate(tiles_bgr):
+            self.upload_button(idx, bgr, key_events=key_events)
+
+    def read_raw_report(self, timeout: int = 150) -> Optional[bytes]:
+        """Read a raw HID report from Interface 3."""
+        with self._usb_lock:
+            if not self.hid_dev:
+                return None
+            try:
+                data = self.hid_dev.read(64, timeout=timeout)
+                return bytes(data) if data else None
+            except Exception as e:
+                log.debug("read_raw_report failed: %s", e)
+                return None
+
+    def poll_key(self, timeout: int = 150) -> Dict[str, List[int]]:
+        """Poll for key events and return newly pressed, newly released, and current key lists.
+
+        Drains buffered key events captured during image updates first.
+        """
+        raw = None
+        with self._usb_lock:
+            if self._pending_key_packets:
+                raw = self._pending_key_packets.pop(0)
+            elif self.hid_dev:
+                try:
+                    data = self.hid_dev.read(64, timeout=timeout)
+                    raw = bytes(data) if data else None
+                except Exception as e:
+                    log.debug("poll_key read failed: %s", e)
+
+        if not raw or len(raw) < 48 or raw[0] != 0x01:
+            return {
+                'pressed': [],
+                'released': [],
+                'current': sorted(list(self.pressed_keys))
+            }
+
+        current_pressed = set(get_pressed_keys(raw))
+        newly_pressed = list(current_pressed - self.pressed_keys)
+        newly_released = list(self.pressed_keys - current_pressed)
+        self.pressed_keys = current_pressed
+
+        return {
+            'pressed': sorted(newly_pressed),
+            'released': sorted(newly_released),
+            'current': sorted(list(current_pressed))
+        }

displaypad_driver-1.0.0/src/displaypad_driver/exceptions.py

@@ -0,0 +1,10 @@
+class DisplayPadError(Exception):
+    """Base error for displaypad package."""
+
+
+class TransportError(DisplayPadError):
+    """Transport/USB related error."""
+
+
+class DeviceNotFoundError(DisplayPadError):
+    """Raised when the device cannot be located."""

displaypad_driver-1.0.0/src/displaypad_driver/image.py

@@ -0,0 +1,187 @@
+"""Image helpers for DisplayPad.
+
+Provides utilities to convert, rotate, slice, and normalize image/GIF data for sending to the device.
+"""
+
+from typing import List, Tuple, Optional, Dict, Union
+from PIL import Image, ImageDraw, ImageFont
+import os
+
+from .protocol import ICON_SIZE, KEYS_PER_ROW, NUM_KEYS
+
+
+def _to_pil_image(image_input: Union[str, Image.Image]) -> Image.Image:
+    if isinstance(image_input, Image.Image):
+        return image_input.copy()
+    return Image.open(image_input)
+
+
+def image_to_bgr102(image_input: Union[str, Image.Image], rotation: int = 0) -> bytes:
+    """Convert an image (file path or PIL Image) to 102x102 raw BGR bytes."""
+    img = _to_pil_image(image_input).convert("RGB").resize((ICON_SIZE, ICON_SIZE), Image.LANCZOS)
+    if rotation:
+        img = img.rotate(-rotation, expand=False)  # PIL rotates CCW, hardware wants CW
+    r, g, b = img.split()
+    return Image.merge("RGB", (b, g, r)).tobytes()
+
+
+def split_image_to_tiles(image_input: Union[str, Image.Image], rotation: int = 0) -> List[bytes]:
+    """Split a full panel image (612x204 nominal grid) into 12 BGR102 tile byte payloads."""
+    grid_w = ICON_SIZE * KEYS_PER_ROW
+    grid_h = ICON_SIZE * (NUM_KEYS // KEYS_PER_ROW)
+    img = _to_pil_image(image_input).convert("RGB").resize((grid_w, grid_h), Image.LANCZOS)
+
+    tiles = []
+    for idx in range(NUM_KEYS):
+        row = idx // KEYS_PER_ROW
+        col = idx % KEYS_PER_ROW
+        x, y = col * ICON_SIZE, row * ICON_SIZE
+        tile = img.crop((x, y, x + ICON_SIZE, y + ICON_SIZE))
+        if rotation:
+            tile = tile.rotate(-rotation, expand=False)
+        r, g, b = tile.split()
+        bgr = Image.merge("RGB", (b, g, r)).tobytes()
+        tiles.append(bgr)
+
+    return tiles
+
+
+def load_gif_frames(image_input: Union[str, Image.Image], rotation: int = 0) -> Optional[List[Tuple[bytes, int]]]:
+    """Extract frames from an animated GIF.
+
+    Returns:
+        List of (bgr_bytes, duration_ms) or None if image is not animated.
+    """
+    try:
+        img = _to_pil_image(image_input)
+        if not getattr(img, 'is_animated', False) and getattr(img, 'n_frames', 1) <= 1:
+            return None
+    except Exception:
+        return None
+
+    frames = []
+    try:
+        for i in range(img.n_frames):
+            img.seek(i)
+            duration = max(img.info.get('duration', 100), 20)
+            frame = img.convert("RGB").resize((ICON_SIZE, ICON_SIZE), Image.LANCZOS)
+            if rotation:
+                frame = frame.rotate(-rotation, expand=False)
+            r, g, b = frame.split()
+            bgr = Image.merge("RGB", (b, g, r)).tobytes()
+            frames.append((bgr, duration))
+    except EOFError:
+        pass
+
+    return frames if len(frames) > 1 else None
+
+
+def split_gif_to_tiles(image_input: Union[str, Image.Image], rotation: int = 0) -> Optional[Dict[int, List[Tuple[bytes, int]]]]:
+    """Split an animated GIF into 12 synchronized tile frame lists.
+
+    Returns:
+        {key_idx: [(bgr_bytes, duration_ms), ...]} or None if not animated.
+    """
+    try:
+        img = _to_pil_image(image_input)
+        if not getattr(img, 'is_animated', False) and getattr(img, 'n_frames', 1) <= 1:
+            return None
+    except Exception:
+        return None
+
+    grid_w = ICON_SIZE * KEYS_PER_ROW
+    grid_h = ICON_SIZE * (NUM_KEYS // KEYS_PER_ROW)
+    result = {k: [] for k in range(NUM_KEYS)}
+    try:
+        for i in range(img.n_frames):
+            img.seek(i)
+            duration = max(img.info.get('duration', 100), 20)
+            frame = img.convert("RGB").resize((grid_w, grid_h), Image.LANCZOS)
+            for idx in range(NUM_KEYS):
+                row = idx // KEYS_PER_ROW
+                col = idx % KEYS_PER_ROW
+                x, y = col * ICON_SIZE, row * ICON_SIZE
+                tile = frame.crop((x, y, x + ICON_SIZE, y + ICON_SIZE))
+                if rotation:
+                    tile = tile.rotate(-rotation, expand=False)
+                r, g, b = tile.split()
+                result[idx].append((Image.merge("RGB", (b, g, r)).tobytes(), duration))
+    except EOFError:
+        pass
+
+    return result if result[0] and len(result[0]) > 1 else None
+
+
+def make_label_icon(text: str, out_path: Optional[str] = None) -> Image.Image:
+    """Render a short text label centered on a 102x102 tile with dark background and shadow."""
+    img = Image.new("RGB", (ICON_SIZE, ICON_SIZE), (28, 28, 36))
+    draw = ImageDraw.Draw(img)
+
+    label = (text or "").strip()
+    font = ImageFont.load_default()
+
+    for size in (30, 26, 22, 18, 15, 12):
+        try:
+            for p in ("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+                      "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans-Bold.ttf"):
+                if os.path.exists(p):
+                    font = ImageFont.truetype(p, size)
+                    break
+        except Exception:
+            pass
+
+        words = label.split()
+        lines, cur = [], ""
+        for w in words or [label]:
+            trial = (cur + " " + w).strip()
+            if draw.textlength(trial, font=font) <= ICON_SIZE - 8 or not cur:
+                cur = trial
+            else:
+                lines.append(cur)
+                cur = w
+        if cur:
+            lines.append(cur)
+        lines = lines[:3]
+        line_h = (draw.textbbox((0, 0), "Ag", font=font)[3]) + 2
+        if line_h * len(lines) <= ICON_SIZE - 6 and all(
+                draw.textlength(ln, font=font) <= ICON_SIZE - 6 for ln in lines):
+            break
+
+    total_h = line_h * len(lines)
+    y = max(2, (ICON_SIZE - total_h) // 2)
+    for ln in lines:
+        tw = draw.textlength(ln, font=font)
+        x = max(2, (ICON_SIZE - tw) // 2)
+        draw.text((x + 1, y + 1), ln, fill=(0, 0, 0), font=font)
+        draw.text((x, y), ln, fill=(255, 255, 255), font=font)
+        y += line_h
+
+    if out_path:
+        img.save(out_path, "PNG")
+    return img
+
+
+def make_folder_icon(base_path: str, label: str, out_path: Optional[str] = None) -> Image.Image:
+    """Render label text on top of a folder icon base image."""
+    img = Image.open(base_path).convert("RGB").resize((ICON_SIZE, ICON_SIZE), Image.LANCZOS)
+    if label:
+        draw = ImageDraw.Draw(img)
+        font = ImageFont.load_default()
+        for p in ("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+                  "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans-Bold.ttf"):
+            if os.path.exists(p):
+                try:
+                    font = ImageFont.truetype(p, 16)
+                    break
+                except Exception:
+                    pass
+        bbox = draw.textbbox((0, 0), label, font=font)
+        tw = bbox[2] - bbox[0]
+        x = max(2, (ICON_SIZE - tw) // 2)
+        draw.text((x + 1, 5), label, fill=(0, 0, 0), font=font)
+        draw.text((x, 4), label, fill=(255, 255, 255), font=font)
+
+    if out_path:
+        img.save(out_path, "PNG")
+    return img
+

displaypad_driver-1.0.0/src/displaypad_driver/protocol.py

@@ -0,0 +1,46 @@
+"""Protocol helpers and constants for the DisplayPad device."""
+
+VID = 0x3282
+PID = 0x0009
+
+NUM_KEYS = 12
+KEYS_PER_ROW = 6
+ICON_SIZE = 102
+CHUNK_SIZE = 1024
+HEADER_SIZE = 306
+PACKET_SIZE = 31438  # total payload = 31744 = 31 × 1024
+EP_DISPLAY = 0x02
+EP_CMD = 0x04
+EP_IN = 0x83
+
+# Key-event byte/bit map: K1-K7 -> data[42], K8-K12 -> data[47]
+KEY_MAP = (
+    [(42, m) for m in (0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80)] +
+    [(47, m) for m in (0x01, 0x02, 0x04, 0x08, 0x10)]
+)
+
+INIT_MSG = bytes.fromhex(
+    "0011800000010000000000000000000000000000000000000000000000000000"
+    "00000000000000000000000000000000000000000000000000000000000000"
+    "0000"
+)
+
+IMG_MSG_TEMPLATE = bytearray.fromhex(
+    "0021000000FF3d00006565000000000000000000000000000000000000000000"
+    "00000000000000000000000000000000000000000000000000000000000000"
+    "0000"
+)
+
+
+def get_pressed_keys(msg: bytes) -> list:
+    """Extract the list of currently pressed keys from the message (0-indexed)."""
+    pressed_keys = []
+    if not msg or len(msg) < 48 or msg[0] != 0x01:
+        return pressed_keys
+
+    for idx, (byte_idx, mask) in enumerate(KEY_MAP):
+        if byte_idx < len(msg) and (msg[byte_idx] & mask):
+            pressed_keys.append(idx)
+
+    return pressed_keys
+

displaypad_driver-1.0.0/src/displaypad_driver/transport.py

@@ -0,0 +1,143 @@
+"""USB transport layer for the DisplayPad device (Interface 1 bulk OUT + Interface 3 hidraw)."""
+
+import gc
+import time
+from logging import getLogger
+from typing import Tuple, Optional
+
+from .exceptions import TransportError, DeviceNotFoundError
+from .protocol import VID, PID
+
+log = getLogger(__name__)
+
+try:
+    import hid
+    HID_AVAILABLE = True
+except ImportError:
+    HID_AVAILABLE = False
+
+try:
+    import usb.core
+    import usb.util
+    PYUSB_AVAILABLE = True
+except ImportError:
+    PYUSB_AVAILABLE = False
+
+
+def check_dependencies():
+    if not HID_AVAILABLE:
+        raise TransportError("hidapi is not installed (pip install hid)")
+    if not PYUSB_AVAILABLE:
+        raise TransportError("PyUSB is not installed (pip install pyusb)")
+
+
+def open_interfaces() -> Tuple[usb.core.Device, hid.Device]:
+    """Open PyUSB device (Interface 1 for pixel bulk data) and HID device (Interface 3 for commands/events)."""
+    check_dependencies()
+    gc.collect()
+
+    device_path = None
+    for d in hid.enumerate(VID, PID):
+        if d.get('interface_number') == 3:
+            device_path = d.get('path')
+            break
+
+    if device_path is None:
+        raise DeviceNotFoundError(f"DisplayPad Interface 3 not found ({hex(VID)}:{hex(PID)})")
+
+    last_err = None
+    for attempt in range(3):
+        hid_dev = None
+        try:
+            hid_dev = hid.Device(path=device_path)
+            hid_dev.nonblocking = False
+            usb_dev = usb.core.find(idVendor=VID, idProduct=PID)
+            if usb_dev is None:
+                hid_dev.close()
+                raise DeviceNotFoundError("DisplayPad not found via PyUSB")
+
+            usb.util.claim_interface(usb_dev, 1)
+            init_handshake_ctrl(usb_dev)
+            return usb_dev, hid_dev
+        except Exception as e:
+            last_err = e
+            if hid_dev is not None:
+                try:
+                    hid_dev.close()
+                except Exception:
+                    pass
+            time.sleep(0.2)
+
+    raise TransportError(f"DisplayPad open failed: {last_err}") if last_err else DeviceNotFoundError("Open failed")
+
+
+def init_handshake_ctrl(usb_dev):
+    """
+    Step 1: Detach kernel driver on IF0 (keyboard) if active.
+    Step 2: SET_IDLE on IF0, IF1 (pixels), IF3 (cmd) to suppress report flooding.
+    Step 3: SET_REPORT (payload {0x03, 0x01}) on IF0 to enable event reporting mode.
+    Step 4: Release IF0 and reattach its kernel driver so OS keyboard keeps working.
+    """
+    if0_was_active = False
+    try:
+        if0_was_active = bool(usb_dev.is_kernel_driver_active(0))
+    except Exception:
+        pass
+
+    if if0_was_active:
+        try:
+            usb_dev.detach_kernel_driver(0)
+        except Exception:
+            pass
+
+    if0_claimed = False
+    try:
+        usb.util.claim_interface(usb_dev, 0)
+        if0_claimed = True
+    except Exception:
+        pass
+
+    def _set_idle(iface):
+        try:
+            usb_dev.ctrl_transfer(0x21, 0x0A, 0x0000, iface, None, timeout=500)
+        except Exception:
+            pass
+
+    if if0_claimed:
+        _set_idle(0)
+    _set_idle(1)  # IF_PIXELS
+    _set_idle(3)  # IF_CMD
+
+    if if0_claimed:
+        try:
+            usb_dev.ctrl_transfer(0x21, 0x09, 0x0203, 0x0000, bytes([0x03, 0x01]), timeout=500)
+        except Exception:
+            pass
+        try:
+            usb.util.release_interface(usb_dev, 0)
+        except Exception:
+            pass
+        if if0_was_active:
+            try:
+                usb_dev.attach_kernel_driver(0)
+            except Exception:
+                pass
+
+
+def close_interfaces(usb_dev: Optional[usb.core.Device], hid_dev: Optional[hid.Device]):
+    """Release interfaces and dispose of USB resources cleanly."""
+    if usb_dev is not None:
+        try:
+            usb.util.release_interface(usb_dev, 1)
+        except Exception:
+            pass
+        try:
+            usb.util.dispose_resources(usb_dev)
+        except Exception:
+            pass
+    if hid_dev is not None:
+        try:
+            hid_dev.close()
+        except Exception:
+            pass
+