private-assistant-picture-display-skill 0.4.1__py3-none-any.whl

private_assistant_picture_display_skill/services/device_mqtt_client.py

@@ -0,0 +1,163 @@
+"""Authenticated MQTT client for device communication."""
+
+import json
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import aiomqtt
+
+from private_assistant_picture_display_skill.config import DeviceMqttConfig
+from private_assistant_picture_display_skill.models.commands import (
+    DisplayCommand,
+    RegistrationResponse,
+)
+
+
+class DeviceMqttClient:
+    """Secondary MQTT client for authenticated device communication.
+
+    This client connects to a separate Mosquitto broker with password
+    authentication for secure communication with Inky display devices.
+
+    Topics:
+        Subscribe:
+            - inky/register: Device registration requests
+            - inky/+/status: Device status heartbeats
+
+        Publish:
+            - inky/{device_id}/command: Display commands
+            - inky/{device_id}/registered: Registration confirmations
+    """
+
+    REGISTER_TOPIC = "inky/register"
+    STATUS_TOPIC_PATTERN = "inky/+/status"
+    COMMAND_TOPIC_TEMPLATE = "inky/{device_id}/command"
+    REGISTERED_TOPIC_TEMPLATE = "inky/{device_id}/registered"
+    _STATUS_TOPIC_PARTS = 3  # inky/{device_id}/status has 3 parts
+
+    def __init__(self, config: DeviceMqttConfig, logger: logging.Logger) -> None:
+        """Initialize the device MQTT client.
+
+        Args:
+            config: Device MQTT configuration with host, port, and credentials
+            logger: Logger instance from parent skill
+        """
+        self.config = config
+        self.logger = logger
+        self._client: aiomqtt.Client | None = None
+
+    @asynccontextmanager
+    async def connect(self) -> AsyncIterator["DeviceMqttClient"]:
+        """Connect to the device MQTT broker.
+
+        Yields:
+            Self for use in async context manager
+        """
+        async with aiomqtt.Client(
+            hostname=self.config.host,
+            port=self.config.port,
+            username=self.config.username,
+            password=self.config.password,
+        ) as client:
+            self._client = client
+            self.logger.info(
+                "Connected to device MQTT broker at %s:%d",
+                self.config.host,
+                self.config.port,
+            )
+            try:
+                yield self
+            finally:
+                self._client = None
+                self.logger.info("Disconnected from device MQTT broker")
+
+    async def subscribe_device_topics(self) -> None:
+        """Subscribe to device registration and status topics."""
+        if self._client is None:
+            raise RuntimeError("MQTT client not connected")
+
+        await self._client.subscribe(self.REGISTER_TOPIC, qos=1)
+        self.logger.info("Subscribed to device registration topic: %s", self.REGISTER_TOPIC)
+
+        await self._client.subscribe(self.STATUS_TOPIC_PATTERN, qos=1)
+        self.logger.info("Subscribed to device status topic: %s", self.STATUS_TOPIC_PATTERN)
+
+    async def publish_command(self, device_id: str, command: DisplayCommand) -> None:
+        """Publish a display command to a specific device.
+
+        Args:
+            device_id: Target device identifier
+            command: Command to send
+        """
+        if self._client is None:
+            raise RuntimeError("MQTT client not connected")
+
+        topic = self.COMMAND_TOPIC_TEMPLATE.format(device_id=device_id)
+        payload = command.model_dump_json()
+
+        await self._client.publish(topic, payload, qos=1)
+        self.logger.debug("Published command to %s: %s", topic, command.action)
+
+    async def publish_registered(self, device_id: str, response: RegistrationResponse) -> None:
+        """Send registration confirmation with MinIO credentials.
+
+        Args:
+            device_id: Device that registered
+            response: Registration response with credentials
+        """
+        if self._client is None:
+            raise RuntimeError("MQTT client not connected")
+
+        topic = self.REGISTERED_TOPIC_TEMPLATE.format(device_id=device_id)
+        payload = response.model_dump_json()
+
+        await self._client.publish(topic, payload, qos=1)
+        self.logger.info("Sent registration confirmation to %s", device_id)
+
+    async def messages(self) -> AsyncIterator[aiomqtt.Message]:
+        """Iterate over incoming MQTT messages.
+
+        Yields:
+            MQTT messages from subscribed topics
+        """
+        if self._client is None:
+            raise RuntimeError("MQTT client not connected")
+
+        async for message in self._client.messages:
+            yield message
+
+    @staticmethod
+    def decode_payload(payload: bytes | bytearray | str | Any) -> dict[str, Any] | None:
+        """Decode MQTT message payload to dictionary.
+
+        Args:
+            payload: Raw MQTT payload
+
+        Returns:
+            Decoded JSON dictionary or None if decoding fails
+        """
+        try:
+            if isinstance(payload, bytes | bytearray):
+                return json.loads(payload.decode("utf-8"))  # type: ignore[no-any-return]
+            if isinstance(payload, str):
+                return json.loads(payload)  # type: ignore[no-any-return]
+            return None
+        except json.JSONDecodeError:
+            return None
+
+    @staticmethod
+    def extract_device_id_from_topic(topic: str) -> str | None:
+        """Extract device ID from a status topic.
+
+        Args:
+            topic: MQTT topic string (e.g., "inky/livingroom/status")
+
+        Returns:
+            Device ID or None if topic doesn't match expected pattern
+        """
+        parts = topic.split("/")
+        if len(parts) == DeviceMqttClient._STATUS_TOPIC_PARTS and parts[0] == "inky" and parts[2] == "status":
+            return parts[1]
+        return None

private_assistant_picture_display_skill/services/image_manager.py

@@ -0,0 +1,175 @@
+"""Image queue management and selection service."""
+
+import logging
+from datetime import datetime
+from uuid import UUID
+
+from private_assistant_commons.database.models import GlobalDevice
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel import col, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from private_assistant_picture_display_skill.config import PictureSkillConfig
+from private_assistant_picture_display_skill.models.commands import DisplayCommand
+from private_assistant_picture_display_skill.models.device import DeviceDisplayState
+from private_assistant_picture_display_skill.models.image import Image
+from private_assistant_picture_display_skill.services.device_mqtt_client import DeviceMqttClient
+
+
+class ImageManager:
+    """Manages image queue and selection for display devices.
+
+    Implements FIFO image selection with device compatibility filtering.
+    Images are selected based on when they were last displayed, with
+    never-displayed images taking priority.
+    """
+
+    def __init__(
+        self,
+        engine: AsyncEngine,
+        device_mqtt: DeviceMqttClient,
+        skill_config: PictureSkillConfig,
+        logger: logging.Logger,
+    ) -> None:
+        """Initialize the image manager.
+
+        Args:
+            engine: Async database engine
+            device_mqtt: Device MQTT client for commands
+            skill_config: Skill configuration
+            logger: Logger instance from parent skill
+        """
+        self.engine = engine
+        self.device_mqtt = device_mqtt
+        self.skill_config = skill_config
+        self.logger = logger
+
+    async def get_next_image_for_device(self, device: GlobalDevice) -> Image | None:
+        """Select next image using FIFO algorithm with device compatibility.
+
+        Selection criteria:
+        1. Images never displayed (last_displayed_at IS NULL) first
+        2. Then by least recently displayed (last_displayed_at ASC)
+        3. Filtered by device dimensions (image must fit)
+
+        Args:
+            device: GlobalDevice with device_attributes containing display dimensions
+
+        Returns:
+            Next image to display, or None if no suitable images available
+        """
+        # Extract display dimensions from device_attributes
+        attrs = device.device_attributes or {}
+        display_width = attrs.get("display_width")
+        display_height = attrs.get("display_height")
+
+        async with AsyncSession(self.engine) as session:
+            # Build query - filter by device compatibility if dimensions known
+            query = select(Image)
+
+            if display_width is not None:
+                query = query.where(col(Image.original_width).is_(None) | (col(Image.original_width) <= display_width))
+            if display_height is not None:
+                query = query.where(
+                    col(Image.original_height).is_(None) | (col(Image.original_height) <= display_height)
+                )
+
+            # Order by FIFO (nulls first = never displayed)
+            query = query.order_by(col(Image.last_displayed_at).asc().nullsfirst()).limit(1)
+
+            result = await session.exec(query)
+            return result.first()
+
+    async def send_display_command(self, device: GlobalDevice, image: Image) -> None:
+        """Send display command to device and update state.
+
+        Args:
+            device: GlobalDevice to send command to
+            image: Image to display
+        """
+        # Create display command
+        command = DisplayCommand(
+            action="display",
+            image_path=image.storage_path,
+            image_id=str(image.id),
+            title=image.title,
+        )
+
+        # Publish command to device (use device.name as topic identifier)
+        await self.device_mqtt.publish_command(device.name, command)
+
+        # Update database state
+        await self._update_display_state(device.id, image)
+
+        self.logger.info(
+            "Sent display command to %s for image %s (%s)",
+            device.name,
+            image.id,
+            image.title or "untitled",
+        )
+
+    async def _update_display_state(self, global_device_id: UUID, image: Image) -> None:
+        """Update database after sending display command.
+
+        Args:
+            global_device_id: GlobalDevice UUID that received the command
+            image: Image being displayed
+        """
+        now = datetime.now()
+
+        async with AsyncSession(self.engine) as session:
+            # Update image last displayed time
+            image_result = await session.exec(select(Image).where(Image.id == image.id))
+            db_image = image_result.first()
+            if db_image:
+                db_image.last_displayed_at = now
+
+            # Update device display state
+            state_result = await session.exec(
+                select(DeviceDisplayState).where(DeviceDisplayState.global_device_id == global_device_id)
+            )
+            display_state = state_result.first()
+
+            if display_state:
+                display_state.current_image_id = image.id
+                display_state.displayed_since = now
+                # Schedule next display based on default duration
+                display_state.scheduled_next_at = datetime.fromtimestamp(
+                    now.timestamp() + self.skill_config.default_display_duration
+                )
+            else:
+                # Create display state if it doesn't exist
+                display_state = DeviceDisplayState(
+                    global_device_id=global_device_id,
+                    current_image_id=image.id,
+                    displayed_since=now,
+                    scheduled_next_at=datetime.fromtimestamp(
+                        now.timestamp() + self.skill_config.default_display_duration
+                    ),
+                )
+                session.add(display_state)
+
+            await session.commit()
+
+    async def get_current_image_for_device(self, global_device_id: UUID) -> Image | None:
+        """Get the currently displayed image for a device.
+
+        Args:
+            global_device_id: GlobalDevice UUID
+
+        Returns:
+            Currently displayed image, or None if not displaying
+        """
+        async with AsyncSession(self.engine) as session:
+            # Get display state
+            state_result = await session.exec(
+                select(DeviceDisplayState).where(DeviceDisplayState.global_device_id == global_device_id)
+            )
+            display_state = state_result.first()
+
+            if display_state is None or display_state.current_image_id is None:
+                return None
+
+            # Get the image
+            image_result = await session.exec(select(Image).where(Image.id == display_state.current_image_id))
+            return image_result.first()

private_assistant_picture_display_skill/templates/describe_image.j2

@@ -0,0 +1,11 @@
+{%- if image.description -%}
+{{ image.description }}
+{%- else -%}
+{%- if image.title -%}
+This is {{ image.title }}.
+{%- else -%}
+No description available for this image.
+{%- endif -%}
+{%- endif -%}
+{%- if image.author %} By {{ image.author }}.{% endif -%}
+{%- if image.source_name and image.source_name != "manual" %} From {{ image.source_name }}.{% endif -%}

private_assistant_picture_display_skill/templates/help.j2

@@ -0,0 +1 @@
+You can control the picture display with these commands. Say "next picture" to show the next image. Say "what am I seeing" to hear a description of the current picture.

private_assistant_picture_display_skill/templates/next_picture.j2

@@ -0,0 +1,9 @@
+{%- if image.title -%}
+Showing {{ image.title }}
+{%- if image.source_name and image.source_name != "manual" %} from {{ image.source_name }}{% endif -%}
+.
+{%- else -%}
+Showing the next picture
+{%- if image.source_name and image.source_name != "manual" %} from {{ image.source_name }}{% endif -%}
+.
+{%- endif -%}

private_assistant_picture_display_skill/utils/__init__.py

@@ -0,0 +1,15 @@
+"""Utility modules for image processing and other common operations."""
+
+from private_assistant_picture_display_skill.utils.color_analysis import ColorProfileAnalyzer
+from private_assistant_picture_display_skill.utils.image_processing import (
+    ImageProcessingError,
+    ImageProcessor,
+)
+from private_assistant_picture_display_skill.utils.metadata_builder import MetadataBuilder
+
+__all__ = [
+    "ColorProfileAnalyzer",
+    "ImageProcessingError",
+    "ImageProcessor",
+    "MetadataBuilder",
+]

private_assistant_picture_display_skill/utils/color_analysis.py

@@ -0,0 +1,78 @@
+"""Color profile analysis for e-ink display compatibility."""
+
+from io import BytesIO
+from typing import ClassVar
+
+from coloraide import Color  # type: ignore[import-untyped]
+from PIL import Image
+
+
+class ColorProfileAnalyzer:
+    """Analyze image color compatibility with limited palette displays.
+
+    Designed for Inky Impression 13.3" (2025) with Spectra 6 palette.
+    Uses Delta E (CIE76) for perceptual color distance calculation.
+    """
+
+    # Spectra 6 palette - measured values from actual display
+    # Source: https://forums.pimoroni.com/t/what-rgb-colors-are-you-using-for-the-colors-on-the-impression-spectra-6/27942
+    SPECTRA_6_PALETTE: ClassVar[list[Color]] = [
+        Color("srgb", [0.0, 0.0, 0.0]),  # Black #000000
+        Color("srgb", [1.0, 1.0, 1.0]),  # White #ffffff
+        Color("srgb", [0.627, 0.125, 0.125]),  # Red #a02020
+        Color("srgb", [0.941, 0.878, 0.314]),  # Yellow #f0e050
+        Color("srgb", [0.376, 0.502, 0.314]),  # Green #608050
+        Color("srgb", [0.314, 0.502, 0.722]),  # Blue #5080b8
+    ]
+
+    @classmethod
+    def calculate_compatibility_score(cls, image_data: bytes) -> float:
+        """Score image compatibility with Spectra 6 palette.
+
+        Algorithm:
+        1. Resize image to 100x100 for speed
+        2. Quantize to extract 8 dominant colors
+        3. Calculate weighted Delta E distance to nearest palette color
+        4. Convert to 0-1 score (higher = better fit)
+
+        Args:
+            image_data: Image bytes (JPEG, PNG, HEIC, etc.)
+
+        Returns:
+            Compatibility score 0.0-1.0 (1.0 = perfect match)
+        """
+        with Image.open(BytesIO(image_data)) as img:
+            # Convert and resize for speed
+            resized = img.convert("RGB").resize((100, 100))
+
+            # Quantize to get dominant colors
+            quantized = resized.quantize(colors=8, method=Image.Quantize.MEDIANCUT)
+            palette_data = quantized.getpalette()
+            if palette_data is None:
+                return 0.5  # Default score if quantization fails
+
+            palette = palette_data[:24]  # 8 colors x 3 (RGB)
+            colors_with_counts = quantized.getcolors()
+
+        if not colors_with_counts:
+            return 0.5  # Default score if no colors found
+
+        # Calculate weighted average Delta E to nearest palette color
+        total_pixels = sum(count for count, _ in colors_with_counts)
+        weighted_distance = 0.0
+
+        for count, color_idx in colors_with_counts:
+            # color_idx is palette index (int) for quantized P-mode images
+            idx = int(color_idx)  # type: ignore[arg-type]
+            r, g, b = palette[idx * 3 : idx * 3 + 3]
+            img_color = Color("srgb", [r / 255, g / 255, b / 255])
+
+            # Find minimum Delta E to any Spectra 6 color
+            min_delta = min(img_color.delta_e(p) for p in cls.SPECTRA_6_PALETTE)
+            weighted_distance += (count / total_pixels) * min_delta
+
+        # Convert to 0-1 score
+        # Delta E scale: 0 = identical, ~100 = maximally different
+        # Divide by 50 to normalize (typical "bad" images score ~30-50)
+        score = max(0.0, 1.0 - (weighted_distance / 50.0))
+        return round(score, 3)

private_assistant_picture_display_skill/utils/image_processing.py

@@ -0,0 +1,104 @@
+"""Image processing utilities for resize and crop operations."""
+
+from io import BytesIO
+
+import pillow_heif  # type: ignore[import-untyped]
+from PIL import Image
+from PIL.Image import Resampling
+
+# Register HEIF/HEIC format support with Pillow
+pillow_heif.register_heif_opener()
+
+
+class ImageProcessingError(Exception):
+    """Raised when image processing fails."""
+
+
+class ImageProcessor:
+    """Handles image resizing and cropping for display devices.
+
+    Strategy: Downscale first (preserving aspect ratio to cover target),
+    then center-crop to exact dimensions.
+    """
+
+    @staticmethod
+    def process_for_display(
+        image_data: bytes,
+        target_width: int,
+        target_height: int,
+        *,
+        upscale: bool = False,
+        quality: int = 85,
+    ) -> bytes | None:
+        """Resize and crop image to fit target dimensions.
+
+        Algorithm:
+        1. Calculate scale factor to COVER target (image will be >= target in both dimensions)
+        2. Resize using LANCZOS for high quality downscaling
+        3. Center-crop to exact target dimensions
+
+        Args:
+            image_data: Original image bytes
+            target_width: Target width in pixels
+            target_height: Target height in pixels
+            upscale: Allow upscaling small images (default: False)
+            quality: JPEG quality 1-100 (default: 85)
+
+        Returns:
+            Processed JPEG image bytes, or None if image is too small and upscale=False
+
+        Raises:
+            ImageProcessingError: If image cannot be processed
+        """
+        try:
+            with Image.open(BytesIO(image_data)) as original:
+                # Convert to RGB if needed (for JPEG output), otherwise copy
+                processed = original.convert("RGB") if original.mode in ("RGBA", "P", "LA", "L") else original.copy()
+
+                orig_width, orig_height = processed.size
+
+                # Check if image is too small to fit target without upscaling
+                if not upscale and (orig_width < target_width or orig_height < target_height):
+                    return None
+
+                # Step 1: Calculate scale to COVER target (may overflow one dimension)
+                scale_w = target_width / orig_width
+                scale_h = target_height / orig_height
+                scale = max(scale_w, scale_h)
+
+                # Don't upscale unless explicitly requested
+                if not upscale and scale > 1.0:
+                    scale = 1.0
+
+                new_width = int(orig_width * scale)
+                new_height = int(orig_height * scale)
+
+                # Step 2: Resize with LANCZOS (high quality)
+                if scale != 1.0:
+                    processed = processed.resize((new_width, new_height), resample=Resampling.LANCZOS)
+
+                # Step 3: Center crop to exact target dimensions
+                current_width, current_height = processed.size
+                if current_width > target_width or current_height > target_height:
+                    left = (current_width - target_width) // 2
+                    top = (current_height - target_height) // 2
+                    right = left + target_width
+                    bottom = top + target_height
+
+                    # Ensure we don't crop beyond image boundaries
+                    left = max(0, left)
+                    top = max(0, top)
+                    right = min(current_width, right)
+                    bottom = min(current_height, bottom)
+
+                    processed = processed.crop((left, top, right, bottom))
+
+                # Step 4: Save as JPEG
+                output = BytesIO()
+                processed.save(output, format="JPEG", quality=quality)
+                return output.getvalue()
+
+        except Exception as e:
+            if isinstance(e, ImageProcessingError):
+                raise
+            raise ImageProcessingError(f"Failed to process image: {e}") from e