private-assistant-display-controller 0.1.0__py3-none-any.whl

private_assistant_display_controller/__init__.py

@@ -0,0 +1,39 @@
+"""Inky Display Controller - E-ink display management for Raspberry Pi.
+
+This package provides a daemon that receives MQTT commands from the
+picture-display-skill and displays images on an Inky Impression e-ink display.
+"""
+
+__version__ = "0.1.0"
+
+from private_assistant_display_controller.config import Settings, load_settings
+from private_assistant_display_controller.controller import DisplayController
+from private_assistant_display_controller.exceptions import (
+    CommunicationError,
+    ConfigurationError,
+    DisplayControllerError,
+    DisplayError,
+)
+from private_assistant_display_controller.models import (
+    DeviceAcknowledge,
+    DeviceRegistration,
+    DisplayCommand,
+    DisplayInfo,
+    RegistrationResponse,
+)
+
+__all__ = [
+    "CommunicationError",
+    "ConfigurationError",
+    "DeviceAcknowledge",
+    "DeviceRegistration",
+    "DisplayCommand",
+    "DisplayController",
+    "DisplayControllerError",
+    "DisplayError",
+    "DisplayInfo",
+    "RegistrationResponse",
+    "Settings",
+    "__version__",
+    "load_settings",
+]

private_assistant_display_controller/config.py

@@ -0,0 +1,110 @@
+"""Configuration management using pydantic-settings."""
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import Field, SecretStr
+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 MQTTConfig(BaseSettings):
+    """MQTT broker connection settings."""
+
+    host: str = Field(default="localhost", description="MQTT broker hostname")
+    port: int = Field(default=1883, description="MQTT broker port")
+    username: str | None = Field(default=None, description="MQTT username")
+    password: SecretStr | None = Field(default=None, description="MQTT password")
+    client_id: str | None = Field(default=None, description="MQTT client ID (auto-generated if not set)")
+    transport: Literal["tcp", "websockets"] = Field(default="tcp", description="MQTT transport protocol")
+    websocket_path: str | None = Field(default=None, description="WebSocket path (e.g., '/mqtt')")
+    tls: bool = Field(default=False, description="Enable TLS/SSL encryption")
+
+
+class MinIOConfig(BaseSettings):
+    """MinIO 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="MinIO server endpoint")
+    bucket: str = Field(default="inky-images", description="Bucket containing images")
+    access_key: SecretStr | None = Field(default=None, description="MinIO access key")
+    secret_key: SecretStr | None = Field(default=None, description="MinIO secret key")
+    secure: bool = Field(default=False, description="Use HTTPS for MinIO 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)
+    mqtt: MQTTConfig = Field(default_factory=MQTTConfig)
+    minio: MinIOConfig = Field(default_factory=MinIOConfig)
+    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", {}))
+        mqtt_config = MQTTConfig(**yaml_config.get("mqtt", {}))
+        minio_config = MinIOConfig(**yaml_config.get("minio", {}))
+        display_config = DisplayConfig(**yaml_config.get("display", {}))
+
+        return cls(
+            device=device_config,
+            mqtt=mqtt_config,
+            minio=minio_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()

private_assistant_display_controller/controller.py

@@ -0,0 +1,260 @@
+"""Main controller orchestrating all display controller components."""
+
+import asyncio
+import logging
+
+from private_assistant_display_controller.config import Settings
+from private_assistant_display_controller.display import DisplayInterface, create_display
+from private_assistant_display_controller.exceptions import CommunicationError, DisplayError
+from private_assistant_display_controller.minio_client import MinIOImageClient
+from private_assistant_display_controller.models import (
+    DeviceAcknowledge,
+    DeviceRegistration,
+    DisplayCommand,
+    DisplayInfo,
+    RegistrationResponse,
+)
+from private_assistant_display_controller.mqtt_client import MQTTClient
+
+logger = logging.getLogger(__name__)
+
+
+class DisplayController:
+    """Main controller orchestrating display operations.
+
+    Coordinates MQTT communication, MinIO 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._is_registered = asyncio.Event()
+        self._shutdown_event = asyncio.Event()
+
+        # Initialize components
+        self._minio = MinIOImageClient()
+        self._display: DisplayInterface = create_display(
+            mock=settings.display.mock,
+            orientation=settings.display.orientation,
+            mock_width=settings.display.mock_width,
+            mock_height=settings.display.mock_height,
+        )
+        self._mqtt = MQTTClient(
+            config=settings.mqtt,
+            device_id=settings.device.id,
+            on_command=self._handle_command,
+            on_registration_response=self._handle_registration_response,
+        )
+
+    async def run(self) -> None:
+        """Main entry point - start all async tasks.
+
+        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._mqtt.run(), name="mqtt")
+                tg.create_task(self._registration_loop(), name="registration")
+                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._minio.close()
+        if hasattr(self._display, "close"):
+            self._display.close()  # type: ignore[attr-defined]
+        await self._mqtt.disconnect()
+
+    async def _registration_loop(self) -> None:
+        """Send registration on startup and retry until acknowledged.
+
+        Runs until registration is successful, then exits.
+        """
+        registration = DeviceRegistration(
+            device_id=self._settings.device.id,
+            display=DisplayInfo(
+                width=self._display.width,
+                height=self._display.height,
+                orientation=self._settings.display.orientation,
+            ),
+            room=self._settings.device.room,
+        )
+
+        retry_interval = 10
+        max_retry_interval = 60
+
+        while not self._is_registered.is_set():
+            try:
+                logger.info("Sending registration...")
+                await self._mqtt.publish_registration(registration)
+
+                # Wait for response with timeout
+                try:
+                    await asyncio.wait_for(
+                        self._is_registered.wait(),
+                        timeout=30.0,
+                    )
+                    logger.info("Registration successful")
+                    return
+                except TimeoutError:
+                    logger.warning(
+                        "Registration response timeout. Retrying in %d seconds...",
+                        retry_interval,
+                    )
+            except Exception:
+                logger.exception("Registration failed")
+
+            await asyncio.sleep(retry_interval)
+            retry_interval = min(retry_interval * 2, max_retry_interval)
+
+    async def _handle_registration_response(self, response: RegistrationResponse) -> None:
+        """Process registration response and configure MinIO client.
+
+        Args:
+            response: Registration response containing MinIO credentials.
+        """
+        logger.info(
+            "Received registration response: status=%s, endpoint=%s",
+            response.status,
+            response.minio_endpoint,
+        )
+
+        self._minio.configure(
+            endpoint=response.minio_endpoint,
+            access_key=response.minio_access_key,
+            secret_key=response.minio_secret_key,
+            bucket=response.minio_bucket,
+            secure=response.minio_secure,
+        )
+        self._is_registered.set()
+
+    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 MinIO 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._minio.is_configured:
+            raise CommunicationError("MinIO not configured - awaiting registration")
+
+        logger.info("Fetching image: %s", command.image_path)
+        image = await self._minio.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._mqtt.publish_acknowledge(acknowledge)
+        except Exception:
+            logger.exception("Failed to send acknowledgment")

private_assistant_display_controller/display.py

@@ -0,0 +1,254 @@
+"""Display abstraction layer for Inky e-paper displays."""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from concurrent.futures import ThreadPoolExecutor
+from typing import Literal
+
+from PIL import Image
+
+from private_assistant_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.
+    """
+
+    def __init__(
+        self,
+        orientation: Literal["landscape", "portrait"] = "landscape",
+        executor: ThreadPoolExecutor | None = None,
+    ) -> None:
+        """Initialize the Inky display wrapper.
+
+        Connects to hardware immediately to detect display dimensions.
+
+        Args:
+            orientation: Display orientation.
+            executor: Optional thread pool executor for display operations.
+
+        Raises:
+            DisplayError: If the display cannot be initialized.
+        """
+        self._orientation = orientation
+        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  # noqa: PLC0415
+
+            self._display = auto()
+            self._width: int = self._display.width  # type: ignore[union-attr]
+            self._height: int = self._display.height  # type: ignore[union-attr]
+            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."""
+        return self._width
+
+    @property
+    def height(self) -> int:
+        """Display height in pixels."""
+        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:
+        """Synchronous display update implementation.
+
+        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.
+        """
+        # Validate image dimensions - skill is responsible for correct sizing
+        if image.size != (self.width, self.height):
+            raise DisplayError(
+                f"Image size {image.size[0]}x{image.size[1]} does not match "
+                f"display size {self.width}x{self.height}. "
+                "The skill must provide correctly sized images."
+            )
+
+        logger.info("Updating display (this takes ~20-25 seconds)...")
+        self._display.set_image(image, saturation=saturation)  # type: ignore[union-attr]
+        self._display.show(busy_wait=True)  # type: ignore[union-attr]
+        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
+
+        # Validate image dimensions - same behavior as real display
+        if image.size != (self._width, self._height):
+            raise DisplayError(
+                f"Image size {image.size[0]}x{image.size[1]} does not match "
+                f"display size {self._width}x{self._height}. "
+                "The skill must provide correctly sized images."
+            )
+
+        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,
+    orientation: Literal["landscape", "portrait"] = "landscape",
+    mock_width: int = 1600,
+    mock_height: int = 1200,
+) -> DisplayInterface:
+    """Factory function to create the appropriate display implementation.
+
+    Args:
+        mock: If True, create a MockDisplay for testing.
+        orientation: Display orientation for real hardware.
+        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 with orientation: %s", orientation)
+    return InkyDisplay(orientation=orientation)

private_assistant_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 MinIO communication fails."""
+
+
+class DisplayError(DisplayControllerError):
+    """Raised when a display hardware operation fails."""