ledmatrix 0.1.0__tar.gz

ledmatrix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ledmatrix contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ledmatrix-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include src/ledmatrix/font/data *.bdf
+recursive-include src/ledmatrix/data *.rules

ledmatrix-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: ledmatrix
+Version: 0.1.0
+Summary: A cross-platform Python SDK for the Framework 16 LED Matrix Input Module
+Author: ledmatrix contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jeffthepineapple/ledmatrix
+Project-URL: Documentation, https://github.com/jeffthepineapple/ledmatrix#readme
+Project-URL: Issues, https://github.com/jeffthepineapple/ledmatrix/issues
+Project-URL: Repository, https://github.com/jeffthepineapple/ledmatrix
+Keywords: framework,framework16,led,matrix,serial,hardware
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Provides-Extra: image
+Requires-Dist: Pillow>=9.0; extra == "image"
+Provides-Extra: array
+Requires-Dist: numpy>=1.21; extra == "array"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Provides-Extra: all
+Requires-Dist: Pillow>=9.0; extra == "all"
+Requires-Dist: numpy>=1.21; extra == "all"
+Dynamic: license-file
+
+# ledmatrix
+
+`ledmatrix` is a Python SDK and command-line tool for the Framework 16 LED
+Matrix Input Module. It provides a small drawing API, device discovery, frame
+transport, image/text helpers, frame pacing, and diagnostics that can run with
+or without hardware attached.
+
+Current package status: `0.1.0`. The SDK has deterministic tests for protocol
+encoding, canvas operations, fonts, dithering, scheduler behavior, device
+helpers, and CLI behavior. Hardware-in-loop validation is still tracked
+separately because it requires a physical Framework 16 LED Matrix Input Module.
+
+## Features
+
+- Canvas drawing for pixels, rectangles, lines, fills, inversion, and packed
+  frame output.
+- Device discovery and synchronous or asynchronous device control.
+- CLI commands for listing devices, showing pixels/rectangles/text/images,
+  brightness, raw packet inspection, and diagnostics.
+- Optional image and array support through Pillow and NumPy.
+- Font rendering with bundled bitmap fonts.
+- Mock transport for examples, dry runs, and tests without LED hardware.
+- Geometry helpers for the Framework 16 LED Matrix Input Module layout.
+
+## Install
+
+Install the base package:
+
+```bash
+pip install ledmatrix
+```
+
+Install optional image and NumPy helpers:
+
+```bash
+pip install "ledmatrix[image]"
+```
+
+Install development tools from a checkout:
+
+```bash
+python -m pip install -e ".[dev,image]"
+```
+
+Linux users may need udev rules before a non-root process can access the input
+module. A packaged rule is included under `src/ledmatrix/data/`.
+
+## Quick Start
+
+Create a frame in memory:
+
+```python
+from ledmatrix import Canvas
+
+frame = Canvas()
+frame.clear()
+frame.set_pixel(0, 0, 255)
+frame.fill_rect(2, 4, 5, 3, 180)
+frame.draw_line(0, 33, 8, 0, 255)
+```
+
+Send a frame to the first discovered device:
+
+```python
+from ledmatrix import Canvas, open_device
+
+canvas = Canvas().clear()
+canvas.fill_rect(1, 8, 7, 4, 200)
+
+with open_device() as device:
+    device.show_frame(canvas)
+```
+
+Use explicit discovery if you want to choose a device:
+
+```python
+from ledmatrix import list_devices, open_device
+
+devices = list_devices()
+if not devices:
+    raise SystemExit("No LED Matrix Input Module found")
+
+with open_device(devices[0].path) as device:
+    print(device.get_device_info())
+```
+
+## Drawing And Geometry
+
+The default geometry is the Framework 16 LED Matrix Input Module: 9 columns by
+34 rows. Coordinates are zero-based with `(0, 0)` at the top-left of the canvas.
+Pixel values are grayscale integers from `0` to `255`.
+
+```python
+from ledmatrix import Canvas
+
+canvas = Canvas()
+canvas.clear()
+canvas.set_pixel(8, 33, 255)
+canvas.fill_rect(x=1, y=8, width=7, height=4, value=160)
+canvas.invert_rect(x=2, y=9, width=2, height=2)
+
+payload = canvas.to_bytes()
+```
+
+Additional helpers include `draw_circle`, `draw_triangle`, `ImagePipeline`,
+`normalize_dither`, and `dither`.
+
+Per-pixel intensity is controlled by the pixel value in the frame:
+
+```python
+canvas = Canvas().clear()
+canvas.set_pixel(4, 17, 64)   # dim pixel
+canvas.set_pixel(5, 17, 255)  # full-intensity pixel
+```
+
+Device brightness is separate and applies globally to the module:
+
+```python
+from ledmatrix import open_device
+
+with open_device() as device:
+    device.set_brightness(50)
+    device.show_frame(canvas)
+```
+
+The CLI `pixel` command currently turns a coordinate on; use the Python API when
+you need a specific per-pixel grayscale value.
+
+## Text And Images
+
+Text rendering uses bundled bitmap fonts:
+
+```python
+from ledmatrix import Canvas
+from ledmatrix.font import Font
+
+canvas = Canvas().clear()
+font = Font.load("3x5")
+font.draw_text(canvas, 0, 0, "Hi")
+```
+
+Image helpers are available when Pillow is installed:
+
+```python
+from PIL import Image
+from ledmatrix import ImagePipeline
+
+image = Image.open("icon.png")
+canvas = ImagePipeline(dither="bayer4x4").process(image)
+```
+
+## Device API
+
+The synchronous API is centered on `Device`:
+
+```python
+from ledmatrix import Canvas, Device
+
+with Device("/dev/ttyACM0") as device:
+    device.set_brightness(50)
+    device.show_frame(Canvas().clear().set_pixel(4, 17, 255))
+```
+
+The package also exports `AsyncDevice` for asyncio applications,
+`FrameScheduler` for frame pacing, and exceptions such as
+`DeviceNotFound`, `DeviceDisconnected`, and `ProtocolError`.
+
+## CLI
+
+The package installs a `ledmatrix` command:
+
+```bash
+ledmatrix list
+ledmatrix info
+ledmatrix brightness 50
+ledmatrix pixel 4 17
+ledmatrix rect 1 8 7 4
+ledmatrix clear
+ledmatrix text "Hi"
+ledmatrix image icon.png
+```
+
+Diagnostics and hardware-free inspection:
+
+```bash
+ledmatrix pixel 4 17 --dry-run
+ledmatrix rect 1 8 7 4 --dry-run
+ledmatrix raw 0x32 00 --dry-run
+ledmatrix orientation-test
+ledmatrix system
+```
+
+Use `ledmatrix --help` and `ledmatrix <command> --help` for command-specific
+arguments such as device paths, orientation, brightness, and dry-run options.
+
+## Current Validation Status
+
+Validated in the repository:
+
+- Canvas bounds handling, drawing primitives, and packed frame conversion.
+- Protocol message encoding for SDK commands.
+- Device helper behavior with mock transports.
+- Font loading/rendering and image dithering helpers.
+- CLI command behavior in deterministic tests.
+
+Known validation follow-up:
+
+- Static analysis cleanup remains for the current checkout. The test suite
+  passes, but the virtualenv `mypy src` run reports existing serial-transport
+  typing issues.
+
+Still requiring real hardware validation:
+
+- End-to-end frame display on a physical Framework 16 LED Matrix Input Module.
+- Brightness/power behavior against firmware.
+- Orientation confirmation on the installed module.
+- Host setup notes for platform-specific serial permissions.
+
+See `BUILD_REPORT.md` and `docs/IMPLEMENTATION_NOTES.md` for the current
+validation notes.
+
+## Development
+
+From a checkout:
+
+```bash
+python -m pip install -e ".[dev,image]"
+python -m pytest
+ruff check src tests examples
+mypy src
+```
+
+Examples are in `examples/`:
+
+```bash
+python examples/mock_demo.py
+python examples/snake_game.py --dry-run
+python examples/snake_game.py --port /dev/ttyACM0
+python examples/draw_primitives.py /dev/ttyACM0
+python examples/text_marquee.py /dev/ttyACM0
+python examples/hardware_smoketest.py /dev/ttyACM0
+```
+
+More detailed API and PyPI-facing documentation is available in `docs/API.md`
+and `docs/PYPI_GUIDE.md`.

ledmatrix-0.1.0/README.md

@@ -0,0 +1,245 @@
+# ledmatrix
+
+`ledmatrix` is a Python SDK and command-line tool for the Framework 16 LED
+Matrix Input Module. It provides a small drawing API, device discovery, frame
+transport, image/text helpers, frame pacing, and diagnostics that can run with
+or without hardware attached.
+
+Current package status: `0.1.0`. The SDK has deterministic tests for protocol
+encoding, canvas operations, fonts, dithering, scheduler behavior, device
+helpers, and CLI behavior. Hardware-in-loop validation is still tracked
+separately because it requires a physical Framework 16 LED Matrix Input Module.
+
+## Features
+
+- Canvas drawing for pixels, rectangles, lines, fills, inversion, and packed
+  frame output.
+- Device discovery and synchronous or asynchronous device control.
+- CLI commands for listing devices, showing pixels/rectangles/text/images,
+  brightness, raw packet inspection, and diagnostics.
+- Optional image and array support through Pillow and NumPy.
+- Font rendering with bundled bitmap fonts.
+- Mock transport for examples, dry runs, and tests without LED hardware.
+- Geometry helpers for the Framework 16 LED Matrix Input Module layout.
+
+## Install
+
+Install the base package:
+
+```bash
+pip install ledmatrix
+```
+
+Install optional image and NumPy helpers:
+
+```bash
+pip install "ledmatrix[image]"
+```
+
+Install development tools from a checkout:
+
+```bash
+python -m pip install -e ".[dev,image]"
+```
+
+Linux users may need udev rules before a non-root process can access the input
+module. A packaged rule is included under `src/ledmatrix/data/`.
+
+## Quick Start
+
+Create a frame in memory:
+
+```python
+from ledmatrix import Canvas
+
+frame = Canvas()
+frame.clear()
+frame.set_pixel(0, 0, 255)
+frame.fill_rect(2, 4, 5, 3, 180)
+frame.draw_line(0, 33, 8, 0, 255)
+```
+
+Send a frame to the first discovered device:
+
+```python
+from ledmatrix import Canvas, open_device
+
+canvas = Canvas().clear()
+canvas.fill_rect(1, 8, 7, 4, 200)
+
+with open_device() as device:
+    device.show_frame(canvas)
+```
+
+Use explicit discovery if you want to choose a device:
+
+```python
+from ledmatrix import list_devices, open_device
+
+devices = list_devices()
+if not devices:
+    raise SystemExit("No LED Matrix Input Module found")
+
+with open_device(devices[0].path) as device:
+    print(device.get_device_info())
+```
+
+## Drawing And Geometry
+
+The default geometry is the Framework 16 LED Matrix Input Module: 9 columns by
+34 rows. Coordinates are zero-based with `(0, 0)` at the top-left of the canvas.
+Pixel values are grayscale integers from `0` to `255`.
+
+```python
+from ledmatrix import Canvas
+
+canvas = Canvas()
+canvas.clear()
+canvas.set_pixel(8, 33, 255)
+canvas.fill_rect(x=1, y=8, width=7, height=4, value=160)
+canvas.invert_rect(x=2, y=9, width=2, height=2)
+
+payload = canvas.to_bytes()
+```
+
+Additional helpers include `draw_circle`, `draw_triangle`, `ImagePipeline`,
+`normalize_dither`, and `dither`.
+
+Per-pixel intensity is controlled by the pixel value in the frame:
+
+```python
+canvas = Canvas().clear()
+canvas.set_pixel(4, 17, 64)   # dim pixel
+canvas.set_pixel(5, 17, 255)  # full-intensity pixel
+```
+
+Device brightness is separate and applies globally to the module:
+
+```python
+from ledmatrix import open_device
+
+with open_device() as device:
+    device.set_brightness(50)
+    device.show_frame(canvas)
+```
+
+The CLI `pixel` command currently turns a coordinate on; use the Python API when
+you need a specific per-pixel grayscale value.
+
+## Text And Images
+
+Text rendering uses bundled bitmap fonts:
+
+```python
+from ledmatrix import Canvas
+from ledmatrix.font import Font
+
+canvas = Canvas().clear()
+font = Font.load("3x5")
+font.draw_text(canvas, 0, 0, "Hi")
+```
+
+Image helpers are available when Pillow is installed:
+
+```python
+from PIL import Image
+from ledmatrix import ImagePipeline
+
+image = Image.open("icon.png")
+canvas = ImagePipeline(dither="bayer4x4").process(image)
+```
+
+## Device API
+
+The synchronous API is centered on `Device`:
+
+```python
+from ledmatrix import Canvas, Device
+
+with Device("/dev/ttyACM0") as device:
+    device.set_brightness(50)
+    device.show_frame(Canvas().clear().set_pixel(4, 17, 255))
+```
+
+The package also exports `AsyncDevice` for asyncio applications,
+`FrameScheduler` for frame pacing, and exceptions such as
+`DeviceNotFound`, `DeviceDisconnected`, and `ProtocolError`.
+
+## CLI
+
+The package installs a `ledmatrix` command:
+
+```bash
+ledmatrix list
+ledmatrix info
+ledmatrix brightness 50
+ledmatrix pixel 4 17
+ledmatrix rect 1 8 7 4
+ledmatrix clear
+ledmatrix text "Hi"
+ledmatrix image icon.png
+```
+
+Diagnostics and hardware-free inspection:
+
+```bash
+ledmatrix pixel 4 17 --dry-run
+ledmatrix rect 1 8 7 4 --dry-run
+ledmatrix raw 0x32 00 --dry-run
+ledmatrix orientation-test
+ledmatrix system
+```
+
+Use `ledmatrix --help` and `ledmatrix <command> --help` for command-specific
+arguments such as device paths, orientation, brightness, and dry-run options.
+
+## Current Validation Status
+
+Validated in the repository:
+
+- Canvas bounds handling, drawing primitives, and packed frame conversion.
+- Protocol message encoding for SDK commands.
+- Device helper behavior with mock transports.
+- Font loading/rendering and image dithering helpers.
+- CLI command behavior in deterministic tests.
+
+Known validation follow-up:
+
+- Static analysis cleanup remains for the current checkout. The test suite
+  passes, but the virtualenv `mypy src` run reports existing serial-transport
+  typing issues.
+
+Still requiring real hardware validation:
+
+- End-to-end frame display on a physical Framework 16 LED Matrix Input Module.
+- Brightness/power behavior against firmware.
+- Orientation confirmation on the installed module.
+- Host setup notes for platform-specific serial permissions.
+
+See `BUILD_REPORT.md` and `docs/IMPLEMENTATION_NOTES.md` for the current
+validation notes.
+
+## Development
+
+From a checkout:
+
+```bash
+python -m pip install -e ".[dev,image]"
+python -m pytest
+ruff check src tests examples
+mypy src
+```
+
+Examples are in `examples/`:
+
+```bash
+python examples/mock_demo.py
+python examples/snake_game.py --dry-run
+python examples/snake_game.py --port /dev/ttyACM0
+python examples/draw_primitives.py /dev/ttyACM0
+python examples/text_marquee.py /dev/ttyACM0
+python examples/hardware_smoketest.py /dev/ttyACM0
+```
+
+More detailed API and PyPI-facing documentation is available in `docs/API.md`
+and `docs/PYPI_GUIDE.md`.

ledmatrix-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ledmatrix"
+version = "0.1.0"
+description = "A cross-platform Python SDK for the Framework 16 LED Matrix Input Module"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{name = "ledmatrix contributors"}]
+keywords = ["framework", "framework16", "led", "matrix", "serial", "hardware"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Hardware",
+]
+dependencies = ["pyserial>=3.5"]
+
+[project.optional-dependencies]
+image = ["Pillow>=9.0"]
+array = ["numpy>=1.21"]
+dev = ["build>=1.2", "pytest>=7.4", "pytest-cov>=4.1", "ruff>=0.6", "mypy>=1.10"]
+all = ["Pillow>=9.0", "numpy>=1.21"]
+
+[project.scripts]
+ledmatrix = "ledmatrix.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/jeffthepineapple/ledmatrix"
+Documentation = "https://github.com/jeffthepineapple/ledmatrix#readme"
+Issues = "https://github.com/jeffthepineapple/ledmatrix/issues"
+Repository = "https://github.com/jeffthepineapple/ledmatrix"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ledmatrix = ["font/data/*.bdf", "data/*.rules"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_unused_ignores = true

ledmatrix-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ledmatrix-0.1.0/src/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",
+]