blocksd 0.2.0__py3-none-any.whl

blocksd/__init__.py

@@ -0,0 +1,3 @@
+"""blocksd — Linux daemon for ROLI Blocks devices."""
+
+__version__ = "0.1.0"

blocksd/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m blocksd`."""
+
+from blocksd.cli.app import app
+
+app()

blocksd/api/__init__.py

@@ -0,0 +1,5 @@
+"""blocksd API — Unix socket server for external integration (Hypercolor, etc.)."""
+
+from blocksd.api.server import ApiServer
+
+__all__ = ["ApiServer"]

blocksd/api/events.py

@@ -0,0 +1,183 @@
+"""Event subscription manager — broadcasts device/touch/button events to clients."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any
+
+from blocksd.device.registry import bitmap_grid_dimensions
+
+if TYPE_CHECKING:
+    from blocksd.device.models import (
+        ButtonEvent,
+        ConfigValue,
+        DeviceConnection,
+        DeviceInfo,
+        Topology,
+        TouchEvent,
+    )
+
+log = logging.getLogger(__name__)
+
+# Supported event categories
+VALID_EVENTS = frozenset({"device", "touch", "button", "config", "topology"})
+
+
+class EventBroadcaster:
+    """Manages client subscriptions and broadcasts events."""
+
+    def __init__(self) -> None:
+        self._subscribers: dict[int, _Subscriber] = {}
+        self._next_id = 0
+
+    def subscribe(self, queue: asyncio.Queue[dict[str, Any]], events: set[str]) -> int:
+        """Register a client for event types. Returns subscription ID."""
+        valid = events & VALID_EVENTS
+        sub_id = self._next_id
+        self._next_id += 1
+        self._subscribers[sub_id] = _Subscriber(queue=queue, events=valid)
+        log.debug("Client %d subscribed to %s", sub_id, valid)
+        return sub_id
+
+    def unsubscribe(self, sub_id: int) -> None:
+        """Remove a client subscription."""
+        self._subscribers.pop(sub_id, None)
+
+    def broadcast_device_added(self, dev: DeviceInfo) -> None:
+        """Broadcast a device_added event."""
+        msg = {
+            "type": "device_added",
+            "device": _device_to_dict(dev),
+        }
+        self._broadcast("device", msg)
+
+    def broadcast_device_removed(self, dev: DeviceInfo) -> None:
+        """Broadcast a device_removed event."""
+        msg = {
+            "type": "device_removed",
+            "uid": dev.uid,
+            "reason": "disconnected",
+        }
+        self._broadcast("device", msg)
+
+    def broadcast_touch(self, event: TouchEvent) -> None:
+        """Broadcast a touch event."""
+        if event.is_start:
+            action = "start"
+        elif event.is_end:
+            action = "end"
+        else:
+            action = "move"
+
+        msg = {
+            "type": "touch",
+            "uid": event.uid,
+            "action": action,
+            "index": event.touch_index,
+            "x": round(event.x, 4),
+            "y": round(event.y, 4),
+            "z": round(event.z, 4),
+            "vx": round(event.vx, 4),
+            "vy": round(event.vy, 4),
+            "vz": round(event.vz, 4),
+        }
+        self._broadcast("touch", msg)
+
+    def broadcast_button(self, event: ButtonEvent) -> None:
+        """Broadcast a button event."""
+        msg = {
+            "type": "button",
+            "uid": event.uid,
+            "action": "press" if event.is_down else "release",
+        }
+        self._broadcast("button", msg)
+
+    def broadcast_topology_changed(self, topo: Topology) -> None:
+        """Broadcast a topology change event."""
+        msg: dict[str, Any] = {
+            "type": "topology_changed",
+            "devices": [_device_to_dict(d) for d in topo.devices],
+            "connections": [_connection_to_dict(c) for c in topo.connections],
+        }
+        self._broadcast("topology", msg)
+
+    def broadcast_config_changed(self, uid: int, config: ConfigValue) -> None:
+        """Broadcast a config change event."""
+        msg: dict[str, Any] = {
+            "type": "config_changed",
+            "uid": uid,
+            "item": config.item,
+            "value": config.value,
+        }
+        self._broadcast("config", msg)
+
+    def _broadcast(self, category: str, msg: dict[str, Any]) -> None:
+        """Send message to all subscribers of the given category."""
+        dead: list[int] = []
+        for sub_id, sub in self._subscribers.items():
+            if category in sub.events:
+                try:
+                    sub.queue.put_nowait(msg)
+                except asyncio.QueueFull:
+                    dead.append(sub_id)
+                    log.debug("Client %d queue full, dropping", sub_id)
+
+        for sub_id in dead:
+            self._subscribers.pop(sub_id, None)
+
+    @property
+    def subscriber_count(self) -> int:
+        return len(self._subscribers)
+
+
+class _Subscriber:
+    __slots__ = ("events", "queue")
+
+    def __init__(self, queue: asyncio.Queue[dict[str, Any]], events: set[str]) -> None:
+        self.queue = queue
+        self.events = events
+
+
+def _device_to_dict(dev: DeviceInfo) -> dict[str, Any]:
+    """Serialize DeviceInfo to the API wire format."""
+    grid_width, grid_height = bitmap_grid_dimensions(dev.block_type)
+    return {
+        "uid": dev.uid,
+        "serial": dev.serial,
+        "block_type": _block_type_to_api(dev.block_type),
+        "name": dev.name or dev.block_type.value,
+        "battery_level": dev.battery_level,
+        "battery_charging": dev.battery_charging,
+        "grid_width": grid_width,
+        "grid_height": grid_height,
+        "firmware_version": dev.version or None,
+    }
+
+
+def _connection_to_dict(conn: DeviceConnection) -> dict[str, Any]:
+    """Serialize DeviceConnection to the API wire format."""
+    return {
+        "device1_uid": conn.device1_uid,
+        "device2_uid": conn.device2_uid,
+        "port1": conn.port1,
+        "port2": conn.port2,
+    }
+
+
+def _block_type_to_api(block_type: Any) -> str:
+    """Convert BlockType enum to API string."""
+    from blocksd.device.models import BlockType
+
+    mapping = {
+        BlockType.LIGHTPAD: "lightpad",
+        BlockType.LIGHTPAD_M: "lightpad_m",
+        BlockType.SEABOARD: "seaboard",
+        BlockType.LUMI_KEYS: "lumi_keys",
+        BlockType.LIVE: "live",
+        BlockType.LOOP: "loop",
+        BlockType.TOUCH: "touch",
+        BlockType.DEV_CTRL: "developer",
+        BlockType.UNKNOWN: "unknown",
+    }
+    return mapping.get(block_type, "unknown")

blocksd/api/http.py

@@ -0,0 +1,146 @@
+"""Minimal HTTP/1.1 server — static file serving and WebSocket upgrade.
+
+Not a general-purpose HTTP server. Handles exactly what blocksd needs: serve the
+built SPA from a static directory (with SPA fallback) and upgrade ``/ws`` to WebSocket.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import asyncio
+    from pathlib import Path
+
+WS_MAGIC = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+MIME_TYPES: dict[str, str] = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "application/javascript; charset=utf-8",
+    ".mjs": "application/javascript; charset=utf-8",
+    ".json": "application/json",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".map": "application/json",
+    ".txt": "text/plain; charset=utf-8",
+    ".wasm": "application/wasm",
+}
+
+CORS_HEADERS = "Access-Control-Allow-Origin: *\r\nAccess-Control-Allow-Headers: *\r\n"
+
+
+class HttpRequest:
+    """Parsed HTTP/1.1 request — method, path, and headers."""
+
+    __slots__ = ("headers", "method", "path")
+
+    def __init__(self, method: str, path: str, headers: dict[str, str]) -> None:
+        self.method = method
+        self.path = path
+        self.headers = headers
+
+    @property
+    def is_websocket_upgrade(self) -> bool:
+        return (
+            self.headers.get("upgrade", "").lower() == "websocket"
+            and "upgrade" in self.headers.get("connection", "").lower()
+        )
+
+    @property
+    def ws_key(self) -> str:
+        return self.headers.get("sec-websocket-key", "")
+
+
+async def parse_request(reader: asyncio.StreamReader) -> HttpRequest | None:
+    """Parse an HTTP/1.1 request line + headers. Returns None on EOF."""
+    line = await reader.readline()
+    if not line:
+        return None
+
+    parts = line.decode("latin-1").strip().split(" ", 2)
+    if len(parts) < 2:
+        return None
+
+    method, raw_path = parts[0], parts[1]
+    path = raw_path.split("?", 1)[0]  # strip query string
+
+    headers: dict[str, str] = {}
+    while True:
+        hdr = await reader.readline()
+        if hdr in (b"\r\n", b"\n", b""):
+            break
+        decoded = hdr.decode("latin-1").strip()
+        if ":" in decoded:
+            k, _, v = decoded.partition(":")
+            headers[k.strip().lower()] = v.strip()
+
+    return HttpRequest(method, path, headers)
+
+
+def ws_upgrade_response(key: str) -> bytes:
+    """Build the 101 Switching Protocols response for WebSocket upgrade."""
+    accept = base64.b64encode(hashlib.sha1((key + WS_MAGIC).encode()).digest()).decode()
+    return (
+        "HTTP/1.1 101 Switching Protocols\r\n"
+        "Upgrade: websocket\r\n"
+        "Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Accept: {accept}\r\n"
+        "\r\n"
+    ).encode()
+
+
+def http_response(
+    status: int,
+    body: bytes,
+    content_type: str = "text/plain; charset=utf-8",
+) -> bytes:
+    """Build a minimal HTTP/1.1 response with CORS headers."""
+    reason = {200: "OK", 204: "No Content", 404: "Not Found", 405: "Method Not Allowed"}.get(
+        status, "Error"
+    )
+    return (
+        f"HTTP/1.1 {status} {reason}\r\n"
+        f"Content-Type: {content_type}\r\n"
+        f"Content-Length: {len(body)}\r\n"
+        f"{CORS_HEADERS}"
+        "Connection: close\r\n"
+        "\r\n"
+    ).encode() + body
+
+
+_NOT_BUILT_HTML = (
+    b"<html><body style='background:#1a1a2e;color:#e0e0e0;font-family:monospace;padding:2em'>"
+    b"<h1>blocksd</h1><p>Web UI not built yet.</p>"
+    b"<pre>cd web &amp;&amp; bun install &amp;&amp; bun run build</pre></body></html>"
+)
+
+
+def serve_static(path: str, static_dir: Path) -> bytes:
+    """Serve a file from *static_dir* with SPA fallback to ``index.html``."""
+    if not static_dir.is_dir():
+        return http_response(200, _NOT_BUILT_HTML, "text/html; charset=utf-8")
+
+    clean = path.lstrip("/") or "index.html"
+    target = (static_dir / clean).resolve()
+
+    # Path traversal guard
+    if not str(target).startswith(str(static_dir.resolve())):
+        return http_response(404, b"Not Found")
+
+    if target.is_file():
+        mime = MIME_TYPES.get(target.suffix, "application/octet-stream")
+        return http_response(200, target.read_bytes(), mime)
+
+    # SPA fallback — serve index.html for client-side routes
+    index = static_dir / "index.html"
+    if index.is_file():
+        return http_response(200, index.read_bytes(), MIME_TYPES[".html"])
+
+    return http_response(404, b"Not Found")

blocksd/api/protocol.py

@@ -0,0 +1,62 @@
+"""Wire protocol — NDJSON + binary frame parser/serializer.
+
+Two message formats coexist on the same socket:
+
+- **JSON:** newline-delimited JSON objects (first byte is `{` = 0x7B)
+- **Binary:** fixed-size frame writes (first byte is magic 0xBD)
+
+The server peeks at the first byte to dispatch to the correct parser.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import dataclass
+from typing import Any
+
+# Binary frame constants
+BINARY_MAGIC = 0xBD
+BINARY_TYPE_FRAME = 0x01
+BINARY_FRAME_SIZE = 685  # 1 magic + 1 type + 8 uid + 675 pixels
+BINARY_HEADER = struct.Struct("<BBQ")  # magic, type, uid (u64 little-endian)
+PIXEL_DATA_SIZE = 675  # 15 * 15 * 3 bytes (RGB888)
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryFrame:
+    """A binary frame write message."""
+
+    uid: int
+    pixels: bytes  # 675 bytes of RGB888
+
+    def to_bytes(self) -> bytes:
+        return BINARY_HEADER.pack(BINARY_MAGIC, BINARY_TYPE_FRAME, self.uid) + self.pixels
+
+
+def parse_binary_frame(data: bytes) -> BinaryFrame:
+    """Parse a 685-byte binary frame message.
+
+    Raises ValueError if the data is malformed.
+    """
+    if len(data) != BINARY_FRAME_SIZE:
+        raise ValueError(f"binary frame wrong size: {len(data)} != {BINARY_FRAME_SIZE}")
+
+    magic, msg_type, uid = BINARY_HEADER.unpack_from(data)
+    if magic != BINARY_MAGIC:
+        raise ValueError(f"bad magic: 0x{magic:02X}")
+    if msg_type != BINARY_TYPE_FRAME:
+        raise ValueError(f"unknown binary type: 0x{msg_type:02X}")
+
+    pixels = data[BINARY_HEADER.size : BINARY_HEADER.size + PIXEL_DATA_SIZE]
+    return BinaryFrame(uid=uid, pixels=pixels)
+
+
+def encode_json(msg: dict[str, Any]) -> bytes:
+    """Encode a JSON message as NDJSON (newline-terminated)."""
+    return json.dumps(msg, separators=(",", ":")).encode() + b"\n"
+
+
+def decode_json(line: bytes) -> dict[str, Any]:
+    """Decode a single NDJSON line."""
+    return json.loads(line)