ledmatrix 0.1.0__py3-none-any.whl

ledmatrix/__init__.py

@@ -0,0 +1,33 @@
+"""Framework 16 LED Matrix SDK."""
+from .async_device import AsyncDevice
+from .canvas import Canvas
+from .device import Device, DeviceDetails, DeviceInfo, list_devices, open_device
+from .dither import dither
+from .exceptions import (
+    DeviceDisconnected,
+    DeviceError,
+    DeviceNotFound,
+    DeviceStalled,
+    ImageDependencyError,
+    LedMatrixError,
+    ProtocolError,
+    TransportError,
+    TransportUnavailable,
+    UnsupportedCapability,
+)
+from .geometry import FW16_LED_MATRIX, MatrixGeometry, PackingOrder
+from .font import Font, draw_text_scrolling
+from .hotplug import DeviceWatcher
+from .image import ImagePipeline
+from .protocol import Command, DeviceCapabilities, FirmwareVersion, Pattern
+from .scheduler import FrameScheduler
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncDevice", "Canvas", "Command", "Device", "DeviceCapabilities", "DeviceDetails", "DeviceDisconnected",
+    "DeviceError", "DeviceInfo", "DeviceNotFound", "DeviceStalled", "DeviceWatcher", "FW16_LED_MATRIX",
+    "FirmwareVersion", "Font", "FrameScheduler", "ImageDependencyError", "ImagePipeline", "LedMatrixError",
+    "MatrixGeometry", "PackingOrder", "Pattern", "ProtocolError", "TransportError", "TransportUnavailable",
+    "UnsupportedCapability", "__version__", "dither", "draw_text_scrolling", "list_devices", "open_device",
+]

ledmatrix/async_device.py

@@ -0,0 +1,64 @@
+"""Async wrapper around :class:`ledmatrix.device.Device`."""
+from __future__ import annotations
+
+import asyncio
+from typing import Optional, Sequence, Union
+
+from .canvas import Canvas
+from .device import Device, DeviceDetails
+from .protocol import FirmwareVersion, Pattern
+
+
+class AsyncDevice:
+    """Run the synchronous serial API in worker threads without changing its semantics."""
+
+    def __init__(self, device: Device) -> None:
+        self.device = device
+
+    async def __aenter__(self) -> "AsyncDevice":
+        await asyncio.to_thread(self.device.__enter__)
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await asyncio.to_thread(self.device.close)
+
+    async def set_brightness(self, percent: int) -> None:
+        await asyncio.to_thread(self.device.set_brightness, percent)
+
+    async def get_brightness(self) -> int:
+        return await asyncio.to_thread(self.device.get_brightness)
+
+    async def set_pattern(self, pattern: Union[int, Pattern], value: Optional[int] = None) -> None:
+        await asyncio.to_thread(self.device.set_pattern, pattern, value)
+
+    async def sleep(self) -> None:
+        await asyncio.to_thread(self.device.sleep)
+
+    async def wake(self) -> None:
+        await asyncio.to_thread(self.device.wake)
+
+    async def is_awake(self) -> bool:
+        return await asyncio.to_thread(self.device.is_awake)
+
+    async def show_frame(self, frame: Union[Canvas, bytes, bytearray]) -> None:
+        await asyncio.to_thread(self.device.show_frame, frame)
+
+    async def schedule_frame(self, frame: Union[Canvas, bytes, bytearray]) -> None:
+        await asyncio.to_thread(self.device.schedule_frame, frame)
+
+    async def set_fps(self, fps: float) -> None:
+        await asyncio.to_thread(self.device.set_fps, fps)
+
+    async def get_firmware_version(self) -> FirmwareVersion:
+        return await asyncio.to_thread(self.device.get_firmware_version)
+
+    async def get_device_info(self) -> DeviceDetails:
+        return await asyncio.to_thread(self.device.get_device_info)
+
+    async def raw_command(
+        self, opcode: int, payload: Union[bytes, bytearray, Sequence[int]] = b"", response_bytes: int = 0
+    ) -> bytes:
+        return await asyncio.to_thread(self.device.raw_command, opcode, payload, response_bytes)

ledmatrix/canvas.py

@@ -0,0 +1,208 @@
+"""Packed 1-bit drawing surface for the Framework LED Matrix."""
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional, Sequence, TYPE_CHECKING
+
+from .geometry import FW16_LED_MATRIX, MatrixGeometry
+
+if TYPE_CHECKING:
+    from .device import Device
+
+
+class Canvas:
+    """A mutable 1-bit canvas backed by a packed :class:`bytearray`.
+
+    Coordinates are zero-based: ``x`` increases across the short edge and ``y`` down the
+    long edge. The default 9x34 geometry and column-major LSB packing match the current
+    upstream Framework protocol's DrawBW payload.
+    """
+
+    def __init__(self, geometry: MatrixGeometry = FW16_LED_MATRIX, data: Optional[bytes] = None) -> None:
+        self.geometry = geometry
+        if data is None:
+            self._data = bytearray(geometry.frame_bytes)
+        else:
+            if len(data) != geometry.frame_bytes:
+                raise ValueError(
+                    "expected %d packed bytes, got %d" % (geometry.frame_bytes, len(data))
+                )
+            self._data = bytearray(data)
+
+    @property
+    def width(self) -> int:
+        return self.geometry.width
+
+    @property
+    def height(self) -> int:
+        return self.geometry.height
+
+    @property
+    def buffer(self) -> bytearray:
+        """The mutable packed framebuffer. Treat direct mutation as an advanced API."""
+        return self._data
+
+    def _address(self, x: int, y: int) -> tuple[int, int]:
+        index = self.geometry.bit_index(x, y)
+        return index // 8, index % 8
+
+    def set_pixel(self, x: int, y: int, state: Any = True) -> "Canvas":
+        byte_index, bit = self._address(x, y)
+        mask = 1 << bit
+        if bool(state):
+            self._data[byte_index] |= mask
+        else:
+            self._data[byte_index] &= ~mask & 0xFF
+        return self
+
+    def get_pixel(self, x: int, y: int) -> bool:
+        byte_index, bit = self._address(x, y)
+        return bool(self._data[byte_index] & (1 << bit))
+
+    def clear(self) -> "Canvas":
+        self._data[:] = b"\x00" * len(self._data)
+        return self
+
+    def fill(self, state: Any = True) -> "Canvas":
+        self._data[:] = (b"\xff" if bool(state) else b"\x00") * len(self._data)
+        # The last byte may contain unused bits. Clear them so frames are deterministic.
+        unused = len(self._data) * 8 - self.geometry.pixels
+        if bool(state) and unused:
+            self._data[-1] &= (1 << (8 - unused)) - 1
+        return self
+
+    def _clip_rect(self, x: int, y: int, width: int, height: int) -> tuple[int, int, int, int]:
+        if width < 0 or height < 0:
+            raise ValueError("rectangle width and height must be non-negative")
+        x0 = max(0, x)
+        y0 = max(0, y)
+        x1 = min(self.width, x + width)
+        y1 = min(self.height, y + height)
+        return x0, y0, x1, y1
+
+    def fill_rect(self, x: int, y: int, width: int, height: int, state: Any = True) -> "Canvas":
+        x0, y0, x1, y1 = self._clip_rect(x, y, width, height)
+        for xx in range(x0, x1):
+            for yy in range(y0, y1):
+                self.set_pixel(xx, yy, state)
+        return self
+
+    def clear_rect(self, x: int, y: int, width: int, height: int) -> "Canvas":
+        return self.fill_rect(x, y, width, height, False)
+
+    def draw_rect(
+        self, x: int, y: int, width: int, height: int, state: Any = True
+    ) -> "Canvas":
+        if width < 0 or height < 0:
+            raise ValueError("rectangle width/height must be non-negative")
+        if width == 0 or height == 0:
+            return self
+
+        x1 = x + width - 1
+        y1 = y + height - 1
+        self.draw_line(x, y, x1, y, state)
+        if height > 1:
+            self.draw_line(x, y1, x1, y1, state)
+        if height > 2:
+            self.draw_line(x, y + 1, x, y1 - 1, state)
+            if width > 1:
+                self.draw_line(x1, y + 1, x1, y1 - 1, state)
+        return self
+
+    def invert_rect(self, x: int, y: int, width: int, height: int) -> "Canvas":
+        x0, y0, x1, y1 = self._clip_rect(x, y, width, height)
+        for xx in range(x0, x1):
+            for yy in range(y0, y1):
+                byte_index, bit = self._address(xx, yy)
+                self._data[byte_index] ^= 1 << bit
+        return self
+
+    def draw_line(self, x0: int, y0: int, x1: int, y1: int, state: Any = True) -> "Canvas":
+        """Draw an inclusive Bresenham line; pixels outside the canvas are clipped."""
+        dx = abs(x1 - x0)
+        sx = 1 if x0 < x1 else -1
+        dy = -abs(y1 - y0)
+        sy = 1 if y0 < y1 else -1
+        error = dx + dy
+        while True:
+            if 0 <= x0 < self.width and 0 <= y0 < self.height:
+                self.set_pixel(x0, y0, state)
+            if x0 == x1 and y0 == y1:
+                break
+            twice_error = 2 * error
+            if twice_error >= dy:
+                error += dy
+                x0 += sx
+            if twice_error <= dx:
+                error += dx
+                y0 += sy
+        return self
+
+    def shift(self, dx: int, dy: int, fill: Any = False) -> "Canvas":
+        if dx == 0 and dy == 0:
+            return self
+
+        source = self.copy()
+        self.fill(fill)
+
+        for y in range(self.height):
+            src_y = y - dy
+            if not 0 <= src_y < self.height:
+                continue
+            for x in range(self.width):
+                src_x = x - dx
+                if 0 <= src_x < self.width:
+                    self.set_pixel(x, y, source.get_pixel(src_x, src_y))
+        return self
+
+    def copy(self) -> "Canvas":
+        return Canvas(self.geometry, bytes(self._data))
+
+    clone = copy
+
+    def to_bytes(self) -> bytes:
+        """Return an immutable copy in the device's packed DrawBW wire format."""
+        return bytes(self._data)
+
+    def to_rows(self, on: str = "#", off: str = ".") -> list[str]:
+        return [
+            "".join(on if self.get_pixel(x, y) else off for x in range(self.width))
+            for y in range(self.height)
+        ]
+
+    def show(self, device: "Device") -> None:
+        device.show_frame(self)
+
+    @classmethod
+    def from_bytes(cls, data: bytes, geometry: MatrixGeometry = FW16_LED_MATRIX) -> "Canvas":
+        return cls(geometry=geometry, data=data)
+
+    @classmethod
+    def from_array(
+        cls, values: Sequence[Sequence[Any]], geometry: MatrixGeometry = FW16_LED_MATRIX, threshold: int = 0
+    ) -> "Canvas":
+        """Build a canvas from a row-major nested sequence or NumPy ``(height, width)`` array."""
+        if len(values) != geometry.height:
+            raise ValueError("expected %d rows, got %d" % (geometry.height, len(values)))
+        canvas = cls(geometry)
+        for y, row in enumerate(values):
+            if len(row) != geometry.width:
+                raise ValueError("expected %d columns in row %d, got %d" % (geometry.width, y, len(row)))
+            for x, value in enumerate(row):
+                canvas.set_pixel(x, y, bool(value) if isinstance(value, bool) else int(value) > threshold)
+        return canvas
+
+    @classmethod
+    def from_pil(
+        cls,
+        image: Any,
+        geometry: MatrixGeometry = FW16_LED_MATRIX,
+        dither: str = "threshold",
+        resize: str = "nearest",
+        threshold: int = 128,
+    ) -> "Canvas":
+        from .image import ImagePipeline
+
+        return ImagePipeline(geometry=geometry, dither=dither, resize=resize, threshold=threshold).process(image)
+
+    def __repr__(self) -> str:
+        return "Canvas(width=%d, height=%d, bytes=%r)" % (self.width, self.height, bytes(self._data))

ledmatrix/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface package."""

ledmatrix/cli/main.py

@@ -0,0 +1,250 @@
+"""Debugging CLI for Framework 16 LED Matrix modules."""
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib import resources
+from pathlib import Path
+from typing import Optional, Sequence
+
+from ..canvas import Canvas
+from ..device import DeviceInfo, list_devices, open_device
+from ..exceptions import LedMatrixError
+from ..font import Font
+from ..geometry import FW16_LED_MATRIX, MatrixGeometry
+from ..image import ImagePipeline
+from ..transport import FRAMEWORK_VID, LED_MATRIX_PID, MockTransport
+
+
+def _int(value: str) -> int:
+    return int(value, 0)
+
+
+def _hex(value: str) -> bytes:
+    try:
+        return bytes.fromhex(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("payload must be hex bytes, e.g. 00 ff a1") from exc
+
+
+def _add_target_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--port", help="explicit serial port (for example COM3 or /dev/ttyACM0)")
+    parser.add_argument("--serial", help="Framework device serial number")
+    parser.add_argument("--dry-run", action="store_true", help="record commands without opening hardware")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ledmatrix", description="Framework 16 LED Matrix SDK CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("list", help="list discovered LED Matrix serial devices")
+
+    info = sub.add_parser("info", help="show device metadata and firmware version")
+    _add_target_arguments(info)
+
+    brightness = sub.add_parser("brightness", help="set global brightness (0..100 percent)")
+    _add_target_arguments(brightness)
+    brightness.add_argument("value", type=int)
+
+    pixel = sub.add_parser("pixel", help="show a single pixel on a cleared frame")
+    _add_target_arguments(pixel)
+    pixel.add_argument("x", type=int)
+    pixel.add_argument("y", type=int)
+
+    rect = sub.add_parser("rect", help="show a filled rectangle on a cleared frame")
+    _add_target_arguments(rect)
+    rect.add_argument("x", type=int)
+    rect.add_argument("y", type=int)
+    rect.add_argument("width", type=int)
+    rect.add_argument("height", type=int)
+
+    clear = sub.add_parser("clear", help="clear the display")
+    _add_target_arguments(clear)
+
+    image = sub.add_parser("image", help="load, resize, dither, and display an image")
+    _add_target_arguments(image)
+    image.add_argument("path")
+    image.add_argument("--dither", default="threshold", choices=["none", "threshold", "bayer2x2", "bayer4x4", "floyd_steinberg"])
+    image.add_argument("--resize", default="nearest", choices=["nearest", "bilinear", "area"])
+
+    text = sub.add_parser("text", help="render text on a cleared frame")
+    _add_target_arguments(text)
+    text.add_argument("text")
+    text.add_argument("--font", default="5x7", choices=["tom-thumb", "4x6", "5x7", "3x5"])
+    text.add_argument("--x", type=int, default=0)
+    text.add_argument("--y", type=int, default=0)
+    text.add_argument("--rotate", type=int, default=0, choices=[0, 90, 180, 270])
+    text.add_argument("--preview", action="store_true", help="print the 9x34 software frame before sending")
+
+    orientation = sub.add_parser("orientation-test", help="show an asymmetric orientation diagnostic frame")
+    _add_target_arguments(orientation)
+    orientation.add_argument("--preview", action="store_true", help="print the 9x34 software frame before sending")
+
+    raw = sub.add_parser("raw", help="send a raw opcode and hex payload")
+    _add_target_arguments(raw)
+    raw.add_argument("opcode", type=_int)
+    raw.add_argument("payload", type=_hex, nargs="?", default=b"")
+    raw.add_argument("--response-bytes", type=int, default=0)
+
+    system = sub.add_parser("system", help="print or install the optional Linux udev rule")
+    system_sub = system.add_subparsers(dest="system_command", required=True)
+    system_sub.add_parser("udev-rule", help="print the packaged udev rule")
+    install = system_sub.add_parser("install-udev", help="copy the udev rule to a chosen writable path")
+    install.add_argument("--target", required=True, help="destination file; use sudo outside this tool if needed")
+
+    return parser
+
+
+def _open(args: argparse.Namespace):
+    if args.dry_run:
+        mock = MockTransport(responses=[bytes((0, 0, 0))])
+        info = DeviceInfo(
+            path="mock://cli", vid=FRAMEWORK_VID, pid=LED_MATRIX_PID, serial="DRYRUN", product="LED_Matrix"
+        )
+        return open_device(transport=mock, info=info), mock
+    return open_device(port=args.port, serial=args.serial), None
+
+
+def _print_dry_run(mock: Optional[MockTransport]) -> None:
+    if mock is None:
+        return
+    for index, write in enumerate(mock.writes, start=1):
+        print("dry-run write %d: %s" % (index, write.hex(" ")))
+
+
+def _rule_text() -> str:
+    resource = resources.files("ledmatrix.data").joinpath("50-framework-inputmodule.rules")
+    return resource.read_text(encoding="utf-8")
+
+
+def _print_preview(canvas: Canvas) -> None:
+    for row in canvas.to_rows():
+        print(row)
+
+
+def _logical_canvas(rotation: int) -> Canvas:
+    if rotation in (90, 270):
+        return Canvas(MatrixGeometry(width=FW16_LED_MATRIX.height, height=FW16_LED_MATRIX.width))
+    return Canvas()
+
+
+def _rotate_canvas(canvas: Canvas, rotation: int) -> Canvas:
+    rotation %= 360
+    if rotation == 0:
+        return canvas
+
+    output = Canvas()
+    if rotation == 90:
+        for y in range(canvas.height):
+            for x in range(canvas.width):
+                output.set_pixel(output.width - 1 - y, x, canvas.get_pixel(x, y))
+    elif rotation == 180:
+        for y in range(canvas.height):
+            for x in range(canvas.width):
+                output.set_pixel(output.width - 1 - x, output.height - 1 - y, canvas.get_pixel(x, y))
+    elif rotation == 270:
+        for y in range(canvas.height):
+            for x in range(canvas.width):
+                output.set_pixel(y, output.height - 1 - x, canvas.get_pixel(x, y))
+    else:
+        raise ValueError("rotation must be one of 0, 90, 180, or 270")
+    return output
+
+
+def _orientation_test_canvas() -> Canvas:
+    canvas = Canvas()
+    canvas.draw_rect(0, 0, canvas.width, canvas.height)
+    canvas.draw_line(0, 0, canvas.width - 1, canvas.height - 1)
+    canvas.set_pixel(0, 0, True)
+    canvas.set_pixel(canvas.width - 1, 0, True)
+    canvas.set_pixel(0, canvas.height - 1, True)
+    canvas.fill_rect(canvas.width - 2, canvas.height - 3, 2, 3, True)
+    Font.load("3x5").draw_text(canvas, 1, 2, "HI")
+    return canvas
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        if args.command == "list":
+            devices = list_devices()
+            if not devices:
+                print("No Framework LED Matrix serial devices found.")
+                return 0
+            for index, info in enumerate(devices):
+                vid = "%04x" % info.vid if info.vid is not None else "????"
+                pid = "%04x" % info.pid if info.pid is not None else "????"
+                serial = info.serial or ""
+                print("%d: %s vid=%s pid=%s serial=%s" % (index, info.path, vid, pid, serial))
+            return 0
+
+        if args.command == "system":
+            if args.system_command == "udev-rule":
+                print(_rule_text(), end="")
+                return 0
+            if args.system_command == "install-udev":
+                Path(args.target).write_text(_rule_text(), encoding="utf-8")
+                print("installed udev rule to %s" % args.target)
+                return 0
+
+        device, mock = _open(args)
+        with device:
+            if args.command == "info":
+                details = device.get_device_info()
+                print("path: %s" % details.info.path)
+                print("serial: %s" % (details.info.serial or ""))
+                print("firmware: %s" % details.firmware)
+                print("geometry: %dx%d" % (details.geometry.width, details.geometry.height))
+                print("frame bytes: %d" % details.geometry.frame_bytes)
+                print("vblank ack: %s" % details.capabilities.vblank_ack)
+            elif args.command == "clear":
+                device.show_frame(Canvas().clear())
+            elif args.command == "pixel":
+                device.show_frame(Canvas().clear().set_pixel(args.x, args.y, True))
+            elif args.command == "rect":
+                device.show_frame(Canvas().clear().fill_rect(args.x, args.y, args.width, args.height, True))
+            elif args.command == "brightness":
+                device.set_brightness(args.value)
+            elif args.command == "image":
+                from PIL import Image
+
+                with Image.open(args.path) as source:
+                    frame = ImagePipeline(dither=args.dither, resize=args.resize).process(source)
+                device.show_frame(frame)
+            elif args.command == "text":
+                canvas = _logical_canvas(args.rotate).clear()
+                Font.load(args.font).draw_text(canvas, args.x, args.y, args.text)
+                canvas = _rotate_canvas(canvas, args.rotate)
+                if args.preview:
+                    _print_preview(canvas)
+                device.show_frame(canvas)
+            elif args.command == "orientation-test":
+                canvas = _orientation_test_canvas()
+                if args.preview:
+                    _print_preview(canvas)
+                device.show_frame(canvas)
+            elif args.command == "raw":
+                response = device.raw_command(args.opcode, args.payload, response_bytes=args.response_bytes)
+                if response:
+                    print(response.hex(" "))
+            else:
+                raise LedMatrixError("unknown command %r" % args.command)
+        _print_dry_run(mock)
+        return 0
+    except LedMatrixError as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 1
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return run(args)
+    except LedMatrixError as exc:
+        parser.exit(2, "ledmatrix: error: %s\n" % exc)
+    except ValueError as exc:
+        parser.exit(2, "ledmatrix: error: %s\n" % exc)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

ledmatrix/data/50-framework-inputmodule.rules

@@ -0,0 +1,3 @@
+# Framework Laptop 16 Input Modules: USB CDC ACM serial endpoints
+# Install to /etc/udev/rules.d/ and reload udev. Review and adapt group/mode for your system.
+SUBSYSTEM=="tty", ATTRS{idVendor}=="32ac", ATTRS{idProduct}=="0020", MODE="0660", GROUP="plugdev", TAG+="uaccess"

ledmatrix/data/__init__.py

@@ -0,0 +1 @@
+"""Packaged non-code resources for ledmatrix."""