inky-image-display-controller 0.14.0__py3-none-any.whl

inky_image_display_controller/__init__.py

@@ -0,0 +1,40 @@
+"""Inky Display Controller - E-ink display management for Raspberry Pi.
+
+This package provides a daemon that receives WebSocket commands from the
+inky-image-display API and displays images on an Inky Impression e-ink display.
+"""
+
+__version__ = "0.2.2"
+
+from inky_image_display_shared.schemas import (
+    DeviceAcknowledge,
+    DeviceRegistration,
+    DisplayCommand,
+    DisplayInfo,
+    RegistrationResponse,
+)
+
+from inky_image_display_controller.config import Settings, load_settings
+from inky_image_display_controller.controller import DisplayController
+from inky_image_display_controller.exceptions import (
+    CommunicationError,
+    ConfigurationError,
+    DisplayControllerError,
+    DisplayError,
+)
+
+__all__ = [
+    "CommunicationError",
+    "ConfigurationError",
+    "DeviceAcknowledge",
+    "DeviceRegistration",
+    "DisplayCommand",
+    "DisplayController",
+    "DisplayControllerError",
+    "DisplayError",
+    "DisplayInfo",
+    "RegistrationResponse",
+    "Settings",
+    "__version__",
+    "load_settings",
+]

inky_image_display_controller/config.py

@@ -0,0 +1,107 @@
+"""Configuration management using pydantic-settings."""
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class DeviceConfig(BaseSettings):
+    """Device identification settings."""
+
+    id: str = Field(default="inky-display", description="Unique device identifier")
+    room: str | None = Field(default=None, description="Room where device is located")
+
+
+class APIConfig(BaseSettings):
+    """API server connection settings."""
+
+    url: str = Field(default="ws://localhost:8000", description="API base URL (ws:// or wss://)")
+    reconnect_interval: int = Field(default=5, description="Initial reconnect delay in seconds")
+    max_reconnect_interval: int = Field(default=60, description="Maximum reconnect delay")
+
+
+class S3Config(BaseSettings):
+    """S3-compatible object storage connection settings.
+
+    These are typically populated from the registration response,
+    but can be pre-configured via environment variables.
+    """
+
+    endpoint: str = Field(default="localhost:9000", description="S3 server endpoint")
+    bucket: str = Field(default="inky-images", description="Bucket containing images")
+    access_key: str | None = Field(default=None, description="S3 access key")
+    secret_key: str | None = Field(default=None, description="S3 secret key")
+    secure: bool = Field(default=False, description="Use HTTPS for S3 connection")
+
+
+class DisplayConfig(BaseSettings):
+    """Display hardware settings."""
+
+    orientation: Literal["landscape", "portrait"] = Field(default="landscape", description="Display orientation")
+    saturation: float = Field(default=0.5, ge=0.0, le=1.0, description="Color saturation for Spectra 6")
+    mock: bool = Field(default=False, description="Use mock display for testing without hardware")
+    # Only used when mock=True (no hardware to query)
+    mock_width: int = Field(default=1600, gt=0, description="Mock display width in pixels")
+    mock_height: int = Field(default=1200, gt=0, description="Mock display height in pixels")
+
+
+class Settings(BaseSettings):
+    """Main application settings aggregating all configuration sections."""
+
+    model_config = SettingsConfigDict(
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    device: DeviceConfig = Field(default_factory=DeviceConfig)
+    api: APIConfig = Field(default_factory=APIConfig)
+    s3: S3Config = Field(default_factory=S3Config)
+    display: DisplayConfig = Field(default_factory=DisplayConfig)
+
+    config_file: Path | None = Field(default=None, description="Path to YAML configuration file")
+
+    @classmethod
+    def from_yaml(cls, yaml_path: Path) -> "Settings":
+        """Load settings from a YAML configuration file.
+
+        Args:
+            yaml_path: Path to the YAML configuration file.
+
+        Returns:
+            Settings instance with values from YAML merged with env vars.
+
+        """
+        with yaml_path.open() as f:
+            yaml_config = yaml.safe_load(f) or {}
+
+        # Build nested config from YAML
+        device_config = DeviceConfig(**yaml_config.get("device", {}))
+        api_config = APIConfig(**yaml_config.get("api", {}))
+        s3_config = S3Config(**yaml_config.get("s3", {}))
+        display_config = DisplayConfig(**yaml_config.get("display", {}))
+
+        return cls(
+            device=device_config,
+            api=api_config,
+            s3=s3_config,
+            display=display_config,
+            config_file=yaml_path,
+        )
+
+
+def load_settings(config_path: Path | None = None) -> Settings:
+    """Load application settings from config file and environment variables.
+
+    Args:
+        config_path: Optional path to YAML configuration file.
+
+    Returns:
+        Settings instance with merged configuration.
+
+    """
+    if config_path and config_path.exists():
+        return Settings.from_yaml(config_path)
+    return Settings()

inky_image_display_controller/controller.py

@@ -0,0 +1,234 @@
+"""Main controller orchestrating all display controller components."""
+
+import asyncio
+import logging
+
+from inky_image_display_shared.schemas import (
+    DeviceAcknowledge,
+    DeviceRegistration,
+    DisplayCommand,
+    DisplayInfo,
+    RegistrationResponse,
+)
+
+from inky_image_display_controller.config import Settings
+from inky_image_display_controller.display import DisplayInterface, create_display
+from inky_image_display_controller.exceptions import CommunicationError, DisplayError
+from inky_image_display_controller.s3_client import S3ImageClient
+from inky_image_display_controller.ws_client import WebSocketClient
+
+logger = logging.getLogger(__name__)
+
+
+class DisplayController:
+    """Main controller orchestrating display operations.
+
+    Coordinates WebSocket communication, S3 image fetching, and display updates.
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        """Initialize the display controller.
+
+        Args:
+            settings: Application settings.
+
+        """
+        self._settings = settings
+        self._current_image_id: str | None = None
+        self._shutdown_event = asyncio.Event()
+
+        # Initialize components
+        self._s3 = S3ImageClient()
+        self._display: DisplayInterface = create_display(
+            mock=settings.display.mock,
+            mock_width=settings.display.mock_width,
+            mock_height=settings.display.mock_height,
+        )
+        self._ws = WebSocketClient(
+            api_url=settings.api.url,
+            device_id=settings.device.id,
+            on_command=self._handle_command,
+            on_registration_response=self._handle_registration_response,
+        )
+
+        # Prepare registration payload so it is sent on every (re-)connect
+        registration = DeviceRegistration(
+            device_id=settings.device.id,
+            display=DisplayInfo(
+                width=self._display.width,
+                height=self._display.height,
+                orientation=settings.display.orientation,
+            ),
+            room=settings.device.room,
+        )
+        self._ws.set_registration_payload(registration.model_dump_json())
+
+    async def run(self) -> None:
+        """Start all async tasks and run until shutdown.
+
+        Runs until shutdown is requested via shutdown() method.
+        """
+        logger.info("Starting display controller for device: %s", self._settings.device.id)
+
+        try:
+            async with asyncio.TaskGroup() as tg:
+                tg.create_task(self._ws.run(), name="websocket")
+                tg.create_task(self._shutdown_monitor(), name="shutdown_monitor")
+        except* Exception as eg:
+            for exc in eg.exceptions:
+                if not isinstance(exc, asyncio.CancelledError):
+                    logger.exception("Task failed: %s", exc)
+        finally:
+            await self._cleanup()
+
+    async def shutdown(self) -> None:
+        """Request graceful shutdown."""
+        logger.info("Shutdown requested")
+        self._shutdown_event.set()
+
+    async def _shutdown_monitor(self) -> None:
+        """Monitor for shutdown signal and cancel tasks."""
+        await self._shutdown_event.wait()
+        raise asyncio.CancelledError("Shutdown requested")
+
+    async def _cleanup(self) -> None:
+        """Clean up resources on shutdown."""
+        logger.info("Cleaning up resources...")
+        self._s3.close()
+        if hasattr(self._display, "close"):
+            self._display.close()  # ty: ignore[call-non-callable]
+        await self._ws.disconnect()
+
+    async def _handle_registration_response(self, response: RegistrationResponse) -> None:
+        """Process registration response and configure S3 client.
+
+        Args:
+            response: Registration response containing S3 credentials.
+
+        """
+        logger.info(
+            "Received registration response: status=%s, endpoint=%s",
+            response.status,
+            response.s3_endpoint,
+        )
+
+        self._s3.configure(
+            endpoint=response.s3_endpoint,
+            access_key=response.s3_access_key,
+            secret_key=response.s3_secret_key,
+            bucket=response.s3_bucket,
+            secure=response.s3_secure,
+            region=response.s3_region,
+        )
+
+    async def _handle_command(self, command: DisplayCommand) -> None:
+        """Process incoming display commands.
+
+        Args:
+            command: Command to process.
+
+        """
+        logger.info("Received command: action=%s, image_id=%s", command.action, command.image_id)
+
+        try:
+            match command.action:
+                case "display":
+                    await self._handle_display(command)
+                case "clear":
+                    await self._handle_clear()
+                case "status":
+                    await self._send_acknowledge(success=True)
+                case _:
+                    logger.warning("Unknown command action: %s", command.action)
+                    await self._send_acknowledge(
+                        image_id=command.image_id,
+                        success=False,
+                        error=f"Unknown action: {command.action}",
+                    )
+        except (CommunicationError, DisplayError) as e:
+            logger.exception("Command failed: %s", command.action)
+            await self._send_acknowledge(
+                image_id=command.image_id,
+                success=False,
+                error=str(e),
+            )
+        except Exception as e:
+            logger.exception("Unexpected error handling command")
+            await self._send_acknowledge(
+                image_id=command.image_id,
+                success=False,
+                error=f"Unexpected error: {e}",
+            )
+
+    async def _handle_display(self, command: DisplayCommand) -> None:
+        """Fetch and display an image.
+
+        Args:
+            command: Display command with image path.
+
+        Raises:
+            ValueError: If image_path or image_id is missing.
+            CommunicationError: If S3 fetch fails.
+            DisplayError: If display update fails.
+
+        """
+        if not command.image_path or not command.image_id:
+            raise ValueError("display command requires image_path and image_id")
+
+        if not self._s3.is_configured:
+            raise CommunicationError("S3 not configured - awaiting registration")
+
+        logger.info("Fetching image: %s", command.image_path)
+        image = await self._s3.fetch_image(command.image_path)
+
+        logger.info("Displaying image: %s", command.image_id)
+        await self._display.show_image(
+            image,
+            saturation=self._settings.display.saturation,
+        )
+
+        self._current_image_id = command.image_id
+
+        await self._send_acknowledge(
+            image_id=command.image_id,
+            success=True,
+        )
+
+    async def _handle_clear(self) -> None:
+        """Clear the display.
+
+        Raises:
+            DisplayError: If display clear fails.
+
+        """
+        logger.info("Clearing display")
+        await self._display.clear()
+        self._current_image_id = None
+
+        await self._send_acknowledge(success=True)
+
+    async def _send_acknowledge(
+        self,
+        image_id: str | None = None,
+        success: bool = True,
+        error: str | None = None,
+    ) -> None:
+        """Send acknowledgment after command processing.
+
+        Args:
+            image_id: Image ID if applicable.
+            success: Whether the command was successful.
+            error: Error message if command failed.
+
+        """
+        acknowledge = DeviceAcknowledge(
+            device_id=self._settings.device.id,
+            image_id=image_id or self._current_image_id,
+            successful_display_change=success,
+            error=error,
+        )
+
+        try:
+            await self._ws.send_acknowledge(acknowledge)
+        except Exception:
+            logger.exception("Failed to send acknowledgment")

inky_image_display_controller/display.py

@@ -0,0 +1,269 @@
+"""Display abstraction layer for Inky e-paper displays."""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from concurrent.futures import ThreadPoolExecutor
+
+from PIL import Image
+
+from inky_image_display_controller.exceptions import DisplayError
+
+logger = logging.getLogger(__name__)
+
+
+class DisplayInterface(ABC):
+    """Abstract interface for display implementations."""
+
+    @property
+    @abstractmethod
+    def width(self) -> int:
+        """Display width in pixels."""
+
+    @property
+    @abstractmethod
+    def height(self) -> int:
+        """Display height in pixels."""
+
+    @abstractmethod
+    async def show_image(self, image: Image.Image, saturation: float = 0.5) -> None:
+        """Display an image on the screen.
+
+        Args:
+            image: PIL Image to display.
+            saturation: Color saturation for Spectra 6 displays (0.0-1.0).
+
+        """
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear the display to white."""
+
+
+class InkyDisplay(DisplayInterface):
+    """Wrapper for Pimoroni Inky e-paper displays.
+
+    The display refresh is a blocking operation (~20-25 seconds),
+    so it runs in a dedicated thread pool to avoid blocking the async loop.
+
+    Dimensions are auto-detected from the hardware during initialization.
+    The Inky library itself handles any internal rotation required by the
+    physical mounting — the public API always expects landscape images
+    (wider than tall).
+    """
+
+    def __init__(
+        self,
+        executor: ThreadPoolExecutor | None = None,
+    ) -> None:
+        """Initialize the Inky display wrapper.
+
+        Connects to hardware immediately to detect display dimensions.
+
+        Args:
+            executor: Optional thread pool executor for display operations.
+
+        Raises:
+            DisplayError: If the display cannot be initialized.
+
+        """
+        self._executor = executor or ThreadPoolExecutor(max_workers=1, thread_name_prefix="inky")
+        self._lock = asyncio.Lock()
+
+        # Eager init - get dimensions from hardware
+        try:
+            from inky.auto import auto  # ty: ignore[unresolved-import]  # noqa: PLC0415
+
+            self._display = auto()
+            self._width: int = self._display.width
+            self._height: int = self._display.height
+            logger.info("Inky display initialized: %dx%d", self._width, self._height)
+        except Exception as e:
+            logger.exception("Failed to initialize Inky display")
+            raise DisplayError(f"Failed to initialize display: {e}") from e
+
+    @property
+    def width(self) -> int:
+        """Display width in pixels (hardware landscape dimension)."""
+        return self._width
+
+    @property
+    def height(self) -> int:
+        """Display height in pixels (hardware landscape dimension)."""
+        return self._height
+
+    async def show_image(self, image: Image.Image, saturation: float = 0.5) -> None:
+        """Display an image on the Inky screen.
+
+        Runs the blocking display update in a thread pool.
+
+        Args:
+            image: PIL Image to display.
+            saturation: Color saturation (0.0-1.0).
+
+        Raises:
+            DisplayError: If the display update fails.
+
+        """
+        async with self._lock:
+            loop = asyncio.get_event_loop()
+            try:
+                await loop.run_in_executor(
+                    self._executor,
+                    self._show_image_sync,
+                    image,
+                    saturation,
+                )
+            except DisplayError:
+                raise
+            except Exception as e:
+                logger.exception("Failed to update display")
+                raise DisplayError(f"Display update failed: {e}") from e
+
+    def _show_image_sync(self, image: Image.Image, saturation: float) -> None:
+        """Perform synchronous display update.
+
+        This method blocks for ~20-25 seconds during the e-ink refresh.
+
+        Args:
+            image: PIL Image to display.
+            saturation: Color saturation (0.0-1.0).
+
+        Raises:
+            DisplayError: If image dimensions don't match display dimensions.
+
+        """
+        # Normalise to landscape: the Inky library always expects the wider
+        # dimension as width, and handles any physical mounting rotation
+        # internally (hard-coded rot90 in InkyEL133UF1.show()).
+        if image.height > image.width:
+            image = image.transpose(Image.Transpose.ROTATE_90)
+
+        if image.size != (self.width, self.height):
+            raise DisplayError(
+                f"Image size {image.size[0]}x{image.size[1]} does not match display size {self.width}x{self.height}."
+            )
+
+        display_image = image
+
+        logger.info("Updating display (this takes ~20-25 seconds)...")
+        self._display.set_image(display_image, saturation=saturation)
+        try:
+            self._display.show(busy_wait=True)
+        except FileNotFoundError as e:
+            raise DisplayError("SPI device not found. Ensure SPI is enabled via raspi-config and reboot.") from e
+        except PermissionError as e:
+            raise DisplayError("Permission denied accessing SPI device. Add user to 'spi' group and re-login.") from e
+        logger.info("Display update complete")
+
+    async def clear(self) -> None:
+        """Clear the display to white."""
+        white_image = Image.new("RGB", (self.width, self.height), (255, 255, 255))
+        await self.show_image(white_image)
+
+    def close(self) -> None:
+        """Clean up resources."""
+        if self._executor:
+            self._executor.shutdown(wait=False)
+
+
+class MockDisplay(DisplayInterface):
+    """Mock display for testing without hardware.
+
+    Stores the last displayed image for inspection in tests.
+    """
+
+    def __init__(self, width: int = 1600, height: int = 1200) -> None:
+        """Initialize the mock display.
+
+        Args:
+            width: Simulated display width.
+            height: Simulated display height.
+
+        """
+        self._width = width
+        self._height = height
+        self._last_image: Image.Image | None = None
+        self._display_count = 0
+
+    @property
+    def width(self) -> int:
+        """Display width in pixels."""
+        return self._width
+
+    @property
+    def height(self) -> int:
+        """Display height in pixels."""
+        return self._height
+
+    @property
+    def last_image(self) -> Image.Image | None:
+        """The last image that was displayed."""
+        return self._last_image
+
+    @property
+    def display_count(self) -> int:
+        """Number of times show_image was called."""
+        return self._display_count
+
+    async def show_image(self, image: Image.Image, saturation: float = 0.5) -> None:
+        """Store the image for inspection.
+
+        Args:
+            image: PIL Image to "display".
+            saturation: Color saturation (ignored in mock).
+
+        Raises:
+            DisplayError: If image dimensions don't match display dimensions.
+
+        """
+        _ = saturation  # Unused in mock, but part of interface
+
+        # Normalise to landscape, same as the real display
+        if image.height > image.width:
+            image = image.transpose(Image.Transpose.ROTATE_90)
+
+        if image.size != (self._width, self._height):
+            raise DisplayError(
+                f"Image size {image.size[0]}x{image.size[1]} does not match display size {self._width}x{self._height}."
+            )
+
+        self._last_image = image.copy()
+        self._display_count += 1
+        logger.debug("Mock display: stored image %dx%d", image.width, image.height)
+        # Simulate a brief delay (real display takes ~25s)
+        await asyncio.sleep(0.1)
+
+    async def clear(self) -> None:
+        """Clear the mock display."""
+        self._last_image = None
+        self._display_count += 1
+        logger.debug("Mock display: cleared")
+        await asyncio.sleep(0.1)
+
+
+def create_display(
+    mock: bool = False,
+    mock_width: int = 1600,
+    mock_height: int = 1200,
+) -> DisplayInterface:
+    """Create the appropriate display implementation.
+
+    Args:
+        mock: If True, create a MockDisplay for testing.
+        mock_width: Width for mock display (ignored for real hardware).
+        mock_height: Height for mock display (ignored for real hardware).
+
+    Returns:
+        DisplayInterface implementation.
+
+    Raises:
+        DisplayError: If real hardware initialization fails.
+
+    """
+    if mock:
+        logger.info("Creating mock display (%dx%d)", mock_width, mock_height)
+        return MockDisplay(width=mock_width, height=mock_height)
+
+    logger.info("Creating Inky display")
+    return InkyDisplay()

inky_image_display_controller/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exception hierarchy for the display controller."""
+
+
+class DisplayControllerError(Exception):
+    """Base exception for all display controller errors."""
+
+
+class ConfigurationError(DisplayControllerError):
+    """Raised when configuration is invalid or missing."""
+
+
+class CommunicationError(DisplayControllerError):
+    """Raised when MQTT or S3 communication fails."""
+
+
+class DisplayError(DisplayControllerError):
+    """Raised when a display hardware operation fails."""

inky_image_display_controller/main.py

@@ -0,0 +1,126 @@
+"""CLI entry point for the Inky Display Controller."""
+
+import asyncio
+import logging
+import signal
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from inky_image_display_controller.config import load_settings
+from inky_image_display_controller.controller import DisplayController
+
+app = typer.Typer(
+    name="inky-controller",
+    help="Inky Display Controller - E-ink display management daemon for Raspberry Pi.",
+    add_completion=False,
+)
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure logging for the application.
+
+    Args:
+        verbose: If True, set log level to DEBUG.
+
+    """
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[logging.StreamHandler(sys.stdout)],
+    )
+
+
+@app.command()
+def main(
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            help="Path to YAML configuration file.",
+            exists=True,
+            dir_okay=False,
+            resolve_path=True,
+        ),
+    ] = None,
+    device_id: Annotated[
+        str | None,
+        typer.Option(
+            "--device-id",
+            "-d",
+            help="Device identifier (overrides config file).",
+            envvar="DEVICE_ID",
+        ),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable verbose debug logging.",
+        ),
+    ] = False,
+) -> None:
+    """Start the Inky Display Controller daemon.
+
+    The controller connects to the Inky Image Display API via WebSocket,
+    registers with the server, and displays images received via commands.
+    """
+    setup_logging(verbose=verbose)
+    logger = logging.getLogger(__name__)
+
+    # Load settings
+    settings = load_settings(config)
+
+    # Override from CLI arguments
+    if device_id:
+        settings.device.id = device_id
+
+    logger.info("Starting Inky Display Controller")
+    logger.info("Device ID: %s", settings.device.id)
+    logger.info("API URL: %s", settings.api.url)
+    logger.info("Mock display: %s", settings.display.mock)
+
+    # Create controller
+    controller = DisplayController(settings)
+
+    # Setup signal handlers for graceful shutdown
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    shutdown_task: asyncio.Task[None] | None = None
+
+    def signal_handler(sig: signal.Signals) -> None:
+        nonlocal shutdown_task
+        logger.info("Received signal %s, initiating shutdown...", sig.name)
+        shutdown_task = loop.create_task(controller.shutdown())
+
+    # Register signal handlers
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(sig, signal_handler, sig)
+
+    _ = shutdown_task  # Reference to prevent unused variable warning
+
+    try:
+        loop.run_until_complete(controller.run())
+    except KeyboardInterrupt:
+        logger.info("Interrupted by user")
+    finally:
+        # Cancel all remaining tasks
+        pending = asyncio.all_tasks(loop)
+        for task in pending:
+            task.cancel()
+
+        # Wait for cancellation
+        if pending:
+            loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+
+        loop.close()
+        logger.info("Display controller stopped")
+
+
+if __name__ == "__main__":
+    app()

inky_image_display_controller/py.typed

@@ -0,0 +1 @@
+

inky_image_display_controller/s3_client.py

@@ -0,0 +1,132 @@
+"""S3/MinIO client for fetching images from object storage."""
+
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from io import BytesIO
+from typing import Any
+
+from minio import Minio
+from PIL import Image
+
+from inky_image_display_controller.exceptions import CommunicationError
+
+logger = logging.getLogger(__name__)
+
+
+class S3ImageClient:
+    """Client for fetching images from S3-compatible object storage.
+
+    The MinIO SDK is synchronous, so operations are wrapped with
+    run_in_executor to avoid blocking the async event loop.
+    """
+
+    def __init__(self, executor: ThreadPoolExecutor | None = None) -> None:
+        """Initialize the S3 client.
+
+        Args:
+            executor: Optional thread pool executor for async operations.
+
+        """
+        self._client: Minio | None = None
+        self._bucket: str | None = None
+        self._executor = executor or ThreadPoolExecutor(max_workers=2)
+
+    def configure(  # noqa: PLR0913
+        self,
+        endpoint: str,
+        access_key: str,
+        secret_key: str,
+        bucket: str,
+        secure: bool = False,
+        region: str | None = None,
+    ) -> None:
+        """Configure the S3 client with credentials.
+
+        Typically called after receiving RegistrationResponse from MQTT.
+
+        Args:
+            endpoint: S3 server endpoint (host:port).
+            access_key: S3 access key.
+            secret_key: S3 secret key.
+            bucket: Bucket name containing images.
+            secure: Whether to use HTTPS.
+            region: Optional S3 region. Falls back to the client library default when None.
+
+        """
+        kwargs: dict[str, Any] = {
+            "access_key": access_key,
+            "secret_key": secret_key,
+            "secure": secure,
+        }
+        if region is not None:
+            kwargs["region"] = region
+        self._client = Minio(endpoint, **kwargs)
+        self._bucket = bucket
+        logger.info("S3 client configured for endpoint: %s, bucket: %s", endpoint, bucket)
+
+    @property
+    def is_configured(self) -> bool:
+        """Check if the client has been configured with credentials."""
+        return self._client is not None and self._bucket is not None
+
+    async def fetch_image(self, object_path: str) -> Image.Image:
+        """Fetch an image from S3 storage and return as PIL Image.
+
+        Runs the synchronous MinIO SDK operation in a thread pool
+        to avoid blocking the async event loop.
+
+        Args:
+            object_path: Path to the object in the S3 bucket.
+
+        Returns:
+            PIL Image object.
+
+        Raises:
+            CommunicationError: If the S3 client is not configured or fetch fails.
+
+        """
+        if not self.is_configured:
+            raise CommunicationError("S3 client not configured. Await registration.")
+
+        loop = asyncio.get_event_loop()
+        try:
+            return await loop.run_in_executor(
+                self._executor,
+                self._fetch_image_sync,
+                object_path,
+            )
+        except Exception as e:
+            logger.exception("Failed to fetch image from S3: %s", object_path)
+            raise CommunicationError(f"Failed to fetch image: {e}") from e
+
+    def _fetch_image_sync(self, object_path: str) -> Image.Image:
+        """Fetch image data from S3 synchronously.
+
+        Args:
+            object_path: Path to the object in the S3 bucket.
+
+        Returns:
+            PIL Image object.
+
+        """
+        assert self._client is not None
+        assert self._bucket is not None
+
+        logger.debug("Fetching image from S3: %s/%s", self._bucket, object_path)
+        response = self._client.get_object(self._bucket, object_path)
+        try:
+            image_data = BytesIO(response.read())
+            image = Image.open(image_data)
+            # Load the image data into memory so we can close the response
+            image.load()
+            logger.debug("Successfully fetched image: %s (size: %s)", object_path, image.size)
+            return image
+        finally:
+            response.close()
+            response.release_conn()
+
+    def close(self) -> None:
+        """Clean up resources."""
+        if self._executor:
+            self._executor.shutdown(wait=False)

inky_image_display_controller/ws_client.py

@@ -0,0 +1,142 @@
+"""WebSocket client for device communication with the API server."""
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+
+import websockets
+from inky_image_display_shared.schemas import (
+    DeviceAcknowledge,
+    DisplayCommand,
+    RegistrationResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+CommandHandler = Callable[[DisplayCommand], Awaitable[None]]
+RegistrationHandler = Callable[[RegistrationResponse], Awaitable[None]]
+
+
+class WebSocketClient:
+    """WebSocket client that connects to the API and handles device communication.
+
+    Replaces the MQTT-based transport. The lifecycle is:
+    1. Connect to ``ws://{api_url}/ws/devices/{device_id}``.
+    2. Send ``DeviceRegistration`` JSON.
+    3. First response is ``RegistrationResponse`` → call ``on_registration_response``.
+    4. All subsequent messages are ``DisplayCommand`` → call ``on_command``.
+    5. On disconnect: exponential backoff reconnect.
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        device_id: str,
+        on_command: CommandHandler,
+        on_registration_response: RegistrationHandler,
+    ) -> None:
+        """Initialize the WebSocket client.
+
+        Args:
+            api_url: API base URL (e.g. ``ws://localhost:8000``).
+            device_id: Device identifier for the WebSocket path.
+            on_command: Callback for incoming display commands.
+            on_registration_response: Callback for the registration response.
+
+        """
+        self._api_url = api_url.rstrip("/")
+        self._device_id = device_id
+        self._on_command = on_command
+        self._on_registration_response = on_registration_response
+        self._ws: websockets.ClientConnection | None = None
+        self._connected = asyncio.Event()
+        self._registration: str | None = None  # JSON payload set before run()
+
+    def set_registration_payload(self, payload_json: str) -> None:
+        """Store the registration JSON to send on (re-)connect.
+
+        Args:
+            payload_json: Serialised ``DeviceRegistration``.
+
+        """
+        self._registration = payload_json
+
+    async def run(self) -> None:
+        """Connect, register, and listen for commands. Auto-reconnects on failure."""
+        reconnect_interval = 5
+        max_reconnect_interval = 60
+        ws_url = f"{self._api_url}/ws/devices/{self._device_id}"
+
+        while True:
+            try:
+                async with websockets.connect(ws_url) as ws:
+                    self._ws = ws
+                    self._connected.set()
+                    logger.info("Connected to API at %s", ws_url)
+
+                    # Reset backoff on successful connection
+                    reconnect_interval = 5
+
+                    # Send registration
+                    if self._registration is not None:
+                        await ws.send(self._registration)
+                        logger.info("Sent registration for device %s", self._device_id)
+
+                        # First message back is the RegistrationResponse
+                        raw = await ws.recv()
+                        if isinstance(raw, bytes):
+                            raw = raw.decode("utf-8")
+                        response = RegistrationResponse.model_validate_json(raw)
+                        await self._on_registration_response(response)
+
+                    # Listen for commands
+                    async for raw_msg in ws:
+                        text = raw_msg.decode("utf-8") if isinstance(raw_msg, bytes) else raw_msg
+                        try:
+                            command = DisplayCommand.model_validate_json(text)
+                            await self._on_command(command)
+                        except Exception:
+                            logger.exception("Error handling message: %s", text[:200])
+
+            except (
+                websockets.ConnectionClosed,
+                OSError,
+                TimeoutError,
+            ) as e:
+                self._connected.clear()
+                self._ws = None
+                logger.warning(
+                    "WebSocket connection lost: %s. Reconnecting in %d seconds...",
+                    e,
+                    reconnect_interval,
+                )
+                await asyncio.sleep(reconnect_interval)
+                reconnect_interval = min(reconnect_interval * 2, max_reconnect_interval)
+
+    async def send_acknowledge(self, acknowledge: DeviceAcknowledge) -> None:
+        """Send acknowledgment JSON over the WebSocket.
+
+        Args:
+            acknowledge: Acknowledgment payload.
+
+        """
+        try:
+            async with asyncio.timeout(30.0):
+                await self._connected.wait()
+        except TimeoutError:
+            raise RuntimeError("WebSocket connection timeout") from None
+
+        if self._ws is not None:
+            await self._ws.send(acknowledge.model_dump_json())
+            logger.debug(
+                "Sent acknowledgment: success=%s, image_id=%s",
+                acknowledge.successful_display_change,
+                acknowledge.image_id,
+            )
+
+    async def disconnect(self) -> None:
+        """Close the WebSocket connection."""
+        self._connected.clear()
+        if self._ws is not None:
+            await self._ws.close()
+            self._ws = None

inky_image_display_controller-0.14.0.dist-info/METADATA

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: inky-image-display-controller
+Version: 0.14.0
+Summary: Device-side controller for Inky e-ink picture displays.
+Author: stkr22
+Author-email: stkr22 <stkr22@github.com>
+License-Expression: GPL-3.0-only
+Requires-Dist: inky-image-display-shared
+Requires-Dist: websockets~=16.0.0
+Requires-Dist: minio~=7.2.20
+Requires-Dist: pillow~=12.2.0
+Requires-Dist: pydantic~=2.12.5
+Requires-Dist: pydantic-settings~=2.13.1
+Requires-Dist: pyyaml~=6.0.3
+Requires-Dist: typer~=0.24.1
+Requires-Dist: inky~=2.4.0 ; extra == 'rpi'
+Requires-Python: >=3.12, <3.14
+Provides-Extra: rpi

inky_image_display_controller-0.14.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+inky_image_display_controller/__init__.py,sha256=huQUfIIHA7tAIRTQ5-DBcSaoxdkF5SU_4zYJxRt0oIQ,1028
+inky_image_display_controller/config.py,sha256=_2O6fpZYRQpb_GJH7BCsfw0QCZ5avLebr-8pj3NgSew,3934
+inky_image_display_controller/controller.py,sha256=K_izyWaKTGNnAvkf7yd-H8H026IZfCZfbBrXcB0KqPI,7956
+inky_image_display_controller/display.py,sha256=z5FrLpnkyLpWEKPswVcQS_2hSf8Um4PcdfHsqJCDIbU,8695
+inky_image_display_controller/exceptions.py,sha256=M0KP0mUgf_mUL_V5Xs3snY3r5IRq5M0YlQCjuTkxYog,485
+inky_image_display_controller/main.py,sha256=1x-5R6TWiKQ-QUqIPAHJYN6Zq2tIOsShDY9ZPd5kppE,3449
+inky_image_display_controller/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+inky_image_display_controller/s3_client.py,sha256=STbAFGQfp3iiuj5pd_ZXhR1gXf0OmFJDbGJWYE9tHN0,4267
+inky_image_display_controller/ws_client.py,sha256=SWNXtg4ibE_zKGSZGDvRLahsmGdDY2ro541-KAqofEI,5296
+inky_image_display_controller-0.14.0.dist-info/WHEEL,sha256=s_zqWxHFEH8b58BCtf46hFCqPaISurdB9R1XJ8za6XI,80
+inky_image_display_controller-0.14.0.dist-info/entry_points.txt,sha256=EuHhjcTCob8ozXeOhrkHU6AeOL4fEiGq1p0UQVSIzt4,90
+inky_image_display_controller-0.14.0.dist-info/METADATA,sha256=nBr8wAFD2fEaLUrg9c2mzN37MCCb67TeJHP0wupaXsw,588
+inky_image_display_controller-0.14.0.dist-info/RECORD,,

inky_image_display_controller-0.14.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.6
+Root-Is-Purelib: true
+Tag: py3-none-any

inky_image_display_controller-0.14.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+inky-image-display-controller = inky_image_display_controller.main:app
+