lifx-async 4.4.1__py3-none-any.whl → 4.5.1__py3-none-any.whl

lifx/__init__.py

@@ -16,6 +16,7 @@ from lifx.api import (
 )
 from lifx.color import HSBK, Colors
 from lifx.devices import (
+    CeilingLight,
     Device,
     DeviceInfo,
     DeviceVersion,
@@ -71,6 +72,7 @@ __all__ = [
     "MultiZoneLightState",
     "MatrixLight",
     "MatrixLightState",
+    "CeilingLight",
     # Color
     "HSBK",
     "Colors",

lifx/devices/__init__.py

@@ -10,6 +10,7 @@ from lifx.devices.base import (
     FirmwareInfo,
     WifiInfo,
 )
+from lifx.devices.ceiling import CeilingLight
 from lifx.devices.hev import HevLight, HevLightState
 from lifx.devices.infrared import InfraredLight, InfraredLightState
 from lifx.devices.light import Light, LightState
@@ -17,6 +18,7 @@ from lifx.devices.matrix import MatrixEffect, MatrixLight, MatrixLightState, Til
 from lifx.devices.multizone import MultiZoneEffect, MultiZoneLight, MultiZoneLightState
 
 __all__ = [
+    "CeilingLight",
     "CollectionInfo",
     "Device",
     "DeviceInfo",

lifx/devices/ceiling.py

@@ -0,0 +1,784 @@
+"""LIFX Ceiling Light Device.
+
+This module provides the CeilingLight class for controlling LIFX Ceiling lights with
+independent uplight and downlight component control.
+
+Terminology:
+- Zone: Individual HSBK pixel in the matrix (indexed 0-63 or 0-127)
+- Component: Logical grouping of zones:
+  - Uplight Component: Single zone for ambient lighting (zone 63 or 127)
+  - Downlight Component: Multiple zones for main illumination (zones 0-62 or 0-126)
+
+Product IDs:
+- 176: Ceiling (US) - 8x8 matrix
+- 177: Ceiling (Intl) - 8x8 matrix
+- 201: Ceiling Capsule (US) - 16x8 matrix
+- 202: Ceiling Capsule (Intl) - 16x8 matrix
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from lifx.color import HSBK
+from lifx.devices.matrix import MatrixLight
+from lifx.exceptions import LifxError
+from lifx.products import get_ceiling_layout, is_ceiling_product
+
+if TYPE_CHECKING:
+    pass
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CeilingLight(MatrixLight):
+    """LIFX Ceiling Light with independent uplight and downlight control.
+
+    CeilingLight extends MatrixLight to provide semantic control over uplight and
+    downlight components while maintaining full backward compatibility with the
+    MatrixLight API.
+
+    The uplight component is the last zone in the matrix, and the downlight component
+    consists of all other zones.
+
+    Example:
+        ```python
+        from lifx.devices import CeilingLight
+        from lifx.color import HSBK
+
+        async with await CeilingLight.from_ip("192.168.1.100") as ceiling:
+            # Independent component control
+            await ceiling.set_downlight_colors(HSBK(hue=0, sat=0, bri=1.0, kelvin=3500))
+            await ceiling.set_uplight_color(HSBK(hue=30, sat=0.2, bri=0.3, kelvin=2700))
+
+            # Turn components on/off
+            await ceiling.turn_downlight_on()
+            await ceiling.turn_uplight_off()
+
+            # Check component state
+            if ceiling.uplight_is_on:
+                print("Uplight is on")
+        ```
+    """
+
+    def __init__(
+        self,
+        serial: str,
+        ip: str,
+        port: int = 56700,  # LIFX_UDP_PORT
+        timeout: float = 0.5,  # DEFAULT_REQUEST_TIMEOUT
+        max_retries: int = 3,  # DEFAULT_MAX_RETRIES
+        state_file: str | None = None,
+    ):
+        """Initialize CeilingLight.
+
+        Args:
+            serial: Device serial number
+            ip: Device IP address
+            port: Device UDP port (default: 56700)
+            timeout: Overall timeout for network requests in seconds
+                (default: 0.5)
+            max_retries: Maximum number of retry attempts for network requests
+                (default: 3)
+            state_file: Optional path to JSON file for state persistence
+
+        Raises:
+            LifxError: If device is not a supported Ceiling product
+        """
+        super().__init__(serial, ip, port, timeout, max_retries)
+        self._state_file = state_file
+        self._stored_uplight_state: HSBK | None = None
+        self._stored_downlight_state: list[HSBK] | None = None
+        self._last_uplight_color: HSBK | None = None
+        self._last_downlight_colors: list[HSBK] | None = None
+
+    async def __aenter__(self) -> CeilingLight:
+        """Async context manager entry."""
+        await super().__aenter__()
+
+        # Validate product ID after version is fetched
+        if self.version and not is_ceiling_product(self.version.product):
+            raise LifxError(
+                f"Product ID {self.version.product} is not a supported Ceiling light."
+            )
+
+        # Load state from disk if state_file is provided
+        if self._state_file:
+            self._load_state_from_file()
+
+        return self
+
+    @classmethod
+    async def from_ip(
+        cls,
+        ip: str,
+        port: int = 56700,  # LIFX_UDP_PORT
+        serial: str | None = None,
+        timeout: float = 0.5,  # DEFAULT_REQUEST_TIMEOUT
+        max_retries: int = 3,  # DEFAULT_MAX_RETRIES
+        *,
+        state_file: str | None = None,
+    ) -> CeilingLight:
+        """Create CeilingLight from IP address.
+
+        Args:
+            ip: Device IP address
+            port: Port number (default LIFX_UDP_PORT)
+            serial: Serial number as 12-digit hex string
+            timeout: Request timeout for this device instance
+            max_retries: Maximum number of retries for requests
+            state_file: Optional path to JSON file for state persistence
+
+        Returns:
+            CeilingLight instance
+
+        Raises:
+            LifxDeviceNotFoundError: Device not found at IP
+            LifxTimeoutError: Device did not respond
+            LifxError: Device is not a supported Ceiling product
+        """
+        # Use parent class factory method
+        device = await super().from_ip(ip, port, serial, timeout, max_retries)
+        # Type cast to CeilingLight and set state_file
+        ceiling = CeilingLight(device.serial, device.ip)
+        ceiling._state_file = state_file
+        ceiling.connection = device.connection
+        return ceiling
+
+    @property
+    def uplight_zone(self) -> int:
+        """Zone index of the uplight component.
+
+        Returns:
+            Zone index (63 for standard Ceiling, 127 for Capsule)
+
+        Raises:
+            LifxError: If device version is not available or not a Ceiling product
+        """
+        if not self.version:
+            raise LifxError("Device version not available. Use async context manager.")
+
+        layout = get_ceiling_layout(self.version.product)
+        if not layout:
+            raise LifxError(f"Product ID {self.version.product} is not a Ceiling light")
+
+        return layout.uplight_zone
+
+    @property
+    def downlight_zones(self) -> slice:
+        """Slice representing the downlight component zones.
+
+        Returns:
+            Slice object (slice(0, 63) for standard, slice(0, 127) for Capsule)
+
+        Raises:
+            LifxError: If device version is not available or not a Ceiling product
+        """
+        if not self.version:
+            raise LifxError("Device version not available. Use async context manager.")
+
+        layout = get_ceiling_layout(self.version.product)
+        if not layout:
+            raise LifxError(f"Product ID {self.version.product} is not a Ceiling light")
+
+        return layout.downlight_zones
+
+    @property
+    def uplight_is_on(self) -> bool:
+        """True if uplight component is currently on.
+
+        Calculated as: power_level > 0 AND uplight brightness > 0
+
+        Note:
+            Requires recent data from device. Call get_uplight_color() or
+            get_power() to refresh cached values before checking this property.
+
+        Returns:
+            True if uplight component is on, False otherwise
+        """
+        if self._state is None or self._state.power == 0:
+            return False
+
+        if self._last_uplight_color is None:
+            return False
+
+        return self._last_uplight_color.brightness > 0
+
+    @property
+    def downlight_is_on(self) -> bool:
+        """True if downlight component is currently on.
+
+        Calculated as: power_level > 0 AND NOT all downlight zones have brightness == 0
+
+        Note:
+            Requires recent data from device. Call get_downlight_colors() or
+            get_power() to refresh cached values before checking this property.
+
+        Returns:
+            True if downlight component is on, False otherwise
+        """
+        if self._state is None or self._state.power == 0:
+            return False
+
+        if self._last_downlight_colors is None:
+            return False
+
+        # Downlight is on if any downlight zone has a brightness > 0
+        return any(c.brightness > 0 for c in self._last_downlight_colors)
+
+    async def get_uplight_color(self) -> HSBK:
+        """Get current uplight component color from device.
+
+        Returns:
+            HSBK color of uplight zone
+
+        Raises:
+            LifxTimeoutError: Device did not respond
+        """
+        # Get all colors from tile
+        all_colors = await self.get_all_tile_colors()
+        tile_colors = all_colors[0]  # First tile
+
+        # Extract uplight zone
+        uplight_color = tile_colors[self.uplight_zone]
+
+        # Cache for is_on property
+        self._last_uplight_color = uplight_color
+
+        return uplight_color
+
+    async def get_downlight_colors(self) -> list[HSBK]:
+        """Get current downlight component colors from device.
+
+        Returns:
+            List of HSBK colors for each downlight zone (63 or 127 zones)
+
+        Raises:
+            LifxTimeoutError: Device did not respond
+        """
+        # Get all colors from tile
+        all_colors = await self.get_all_tile_colors()
+        tile_colors = all_colors[0]  # First tile
+
+        # Extract downlight zones
+        downlight_colors = tile_colors[self.downlight_zones]
+
+        # Cache for is_on property
+        self._last_downlight_colors = downlight_colors
+
+        return downlight_colors
+
+    async def set_uplight_color(self, color: HSBK, duration: float = 0.0) -> None:
+        """Set uplight component color.
+
+        Args:
+            color: HSBK color to set
+            duration: Transition duration in seconds (default 0.0)
+
+        Raises:
+            ValueError: If color.brightness == 0 (use turn_uplight_off instead)
+            LifxTimeoutError: Device did not respond
+
+        Note:
+            Also updates stored state for future restoration.
+        """
+        if color.brightness == 0:
+            raise ValueError(
+                "Cannot set uplight color with brightness=0. "
+                "Use turn_uplight_off() instead."
+            )
+
+        # Get current colors for all zones
+        all_colors = await self.get_all_tile_colors()
+        tile_colors = all_colors[0]
+
+        # Update uplight zone
+        tile_colors[self.uplight_zone] = color
+
+        # Set all colors back (duration in milliseconds for set_matrix_colors)
+        await self.set_matrix_colors(0, tile_colors, duration=int(duration * 1000))
+
+        # Store state
+        self._stored_uplight_state = color
+        self._last_uplight_color = color
+
+        # Persist if enabled
+        if self._state_file:
+            self._save_state_to_file()
+
+    async def set_downlight_colors(
+        self, colors: HSBK | list[HSBK], duration: float = 0.0
+    ) -> None:
+        """Set downlight component colors.
+
+        Args:
+            colors: Either:
+                - Single HSBK: sets all downlight zones to same color
+                - List[HSBK]: sets each zone individually (must match zone count)
+            duration: Transition duration in seconds (default 0.0)
+
+        Raises:
+            ValueError: If any color.brightness == 0 (use turn_downlight_off instead)
+            ValueError: If list length doesn't match downlight zone count
+            LifxTimeoutError: Device did not respond
+
+        Note:
+            Also updates stored state for future restoration.
+        """
+        # Validate and normalize colors
+        if isinstance(colors, HSBK):
+            if colors.brightness == 0:
+                raise ValueError(
+                    "Cannot set downlight color with brightness=0. "
+                    "Use turn_downlight_off() instead."
+                )
+            downlight_colors = [colors] * len(range(*self.downlight_zones.indices(256)))
+        else:
+            if all(c.brightness == 0 for c in colors):
+                raise ValueError(
+                    "Cannot set downlight colors with brightness=0. "
+                    "Use turn_downlight_off() instead."
+                )
+
+            expected_count = len(range(*self.downlight_zones.indices(256)))
+            if len(colors) != expected_count:
+                raise ValueError(
+                    f"Expected {expected_count} colors for downlight, got {len(colors)}"
+                )
+            downlight_colors = colors
+
+        # Get current colors for all zones
+        all_colors = await self.get_all_tile_colors()
+        tile_colors = all_colors[0]
+
+        # Update downlight zones
+        tile_colors[self.downlight_zones] = downlight_colors
+
+        # Set all colors back
+        await self.set_matrix_colors(0, tile_colors, duration=int(duration * 1000))
+
+        # Store state
+        self._stored_downlight_state = downlight_colors
+        self._last_downlight_colors = downlight_colors
+
+        # Persist if enabled
+        if self._state_file:
+            self._save_state_to_file()
+
+    async def turn_uplight_on(
+        self, color: HSBK | None = None, duration: float = 0.0
+    ) -> None:
+        """Turn uplight component on.
+
+        Args:
+            color: Optional HSBK color. If provided:
+                - Uses this color immediately
+                - Updates stored state
+                If None, uses brightness determination logic
+            duration: Transition duration in seconds (default 0.0)
+
+        Raises:
+            ValueError: If color.brightness == 0
+            LifxTimeoutError: Device did not respond
+        """
+        if color is not None:
+            if color.brightness == 0:
+                raise ValueError("Cannot turn on uplight with brightness=0")
+            await self.set_uplight_color(color, duration)
+        else:
+            # Determine color using priority logic
+            determined_color = await self._determine_uplight_brightness()
+            await self.set_uplight_color(determined_color, duration)
+
+    async def turn_uplight_off(
+        self, color: HSBK | None = None, duration: float = 0.0
+    ) -> None:
+        """Turn uplight component off.
+
+        Args:
+            color: Optional HSBK color to store for future turn_on.
+                If provided, stores this color (with brightness=0 on the device).
+                If None, stores current color from device before turning off.
+            duration: Transition duration in seconds (default 0.0)
+
+        Raises:
+            ValueError: If color.brightness == 0
+            LifxTimeoutError: Device did not respond
+
+        Note:
+            Sets uplight zone brightness to 0 on device while preserving H, S, K.
+        """
+        if color is not None:
+            if color.brightness == 0:
+                raise ValueError(
+                    "Provided color cannot have brightness=0. "
+                    "Omit the parameter to use current color."
+                )
+            # Store the provided color
+            self._stored_uplight_state = color
+        else:
+            # Get and store current color
+            current_color = await self.get_uplight_color()
+            self._stored_uplight_state = current_color
+
+        # Create color with brightness=0 for device
+        off_color = HSBK(
+            hue=self._stored_uplight_state.hue,
+            saturation=self._stored_uplight_state.saturation,
+            brightness=0.0,
+            kelvin=self._stored_uplight_state.kelvin,
+        )
+
+        # Get all colors and update uplight zone
+        all_colors = await self.get_all_tile_colors()
+        tile_colors = all_colors[0]
+        tile_colors[self.uplight_zone] = off_color
+        await self.set_matrix_colors(0, tile_colors, duration=int(duration * 1000))
+
+        # Update cache
+        self._last_uplight_color = off_color
+
+        # Persist if enabled
+        if self._state_file:
+            self._save_state_to_file()
+
+    async def turn_downlight_on(
+        self, colors: HSBK | list[HSBK] | None = None, duration: float = 0.0
+    ) -> None:
+        """Turn downlight component on.
+
+        Args:
+            colors: Optional colors. Can be:
+                - None: uses brightness determination logic
+                - Single HSBK: sets all downlight zones to same color
+                - List[HSBK]: sets each zone individually (must match zone count)
+                If provided, updates stored state.
+            duration: Transition duration in seconds (default 0.0)
+
+        Raises:
+            ValueError: If any color.brightness == 0
+            ValueError: If list length doesn't match downlight zone count
+            LifxTimeoutError: Device did not respond
+        """
+        if colors is not None:
+            await self.set_downlight_colors(colors, duration)
+        else:
+            # Determine colors using priority logic
+            determined_colors = await self._determine_downlight_brightness()
+            await self.set_downlight_colors(determined_colors, duration)
+
+    async def turn_downlight_off(
+        self, colors: HSBK | list[HSBK] | None = None, duration: float = 0.0
+    ) -> None:
+        """Turn downlight component off.
+
+        Args:
+            colors: Optional colors to store for future turn_on. Can be:
+                - None: stores current colors from device
+                - Single HSBK: stores this color for all zones
+                - List[HSBK]: stores individual colors (must match zone count)
+                If provided, stores these colors (with brightness=0 on device).
+            duration: Transition duration in seconds (default 0.0)
+
+        Raises:
+            ValueError: If any color.brightness == 0
+            ValueError: If list length doesn't match downlight zone count
+            LifxTimeoutError: Device did not respond
+
+        Note:
+            Sets all downlight zone brightness to 0 on device while preserving H, S, K.
+        """
+        expected_count = len(range(*self.downlight_zones.indices(256)))
+
+        if colors is not None:
+            # Validate and normalize provided colors
+            if isinstance(colors, HSBK):
+                if colors.brightness == 0:
+                    raise ValueError(
+                        "Provided color cannot have brightness=0. "
+                        "Omit the parameter to use current colors."
+                    )
+                colors_to_store = [colors] * expected_count
+            else:
+                if all(c.brightness == 0 for c in colors):
+                    raise ValueError(
+                        "Provided colors cannot have brightness=0. "
+                        "Omit the parameter to use current colors."
+                    )
+                if len(colors) != expected_count:
+                    raise ValueError(
+                        f"Expected {expected_count} colors for downlight, "
+                        f"got {len(colors)}"
+                    )
+                colors_to_store = colors
+
+            self._stored_downlight_state = colors_to_store
+        else:
+            # Get and store current colors
+            current_colors = await self.get_downlight_colors()
+            self._stored_downlight_state = current_colors
+
+        # Create colors with brightness=0 for device
+        off_colors = [
+            HSBK(
+                hue=c.hue,
+                saturation=c.saturation,
+                brightness=0.0,
+                kelvin=c.kelvin,
+            )
+            for c in self._stored_downlight_state
+        ]
+
+        # Get all colors and update downlight zones
+        all_colors = await self.get_all_tile_colors()
+        tile_colors = all_colors[0]
+        tile_colors[self.downlight_zones] = off_colors
+        await self.set_matrix_colors(0, tile_colors, duration=int(duration * 1000))
+
+        # Update cache
+        self._last_downlight_colors = off_colors
+
+        # Persist if enabled
+        if self._state_file:
+            self._save_state_to_file()
+
+    async def _determine_uplight_brightness(self) -> HSBK:
+        """Determine uplight brightness using priority logic.
+
+        Priority order:
+        1. Stored state (if available)
+        2. Infer from downlight average brightness
+        3. Hardcoded default (0.8)
+
+        Returns:
+            HSBK color for uplight
+        """
+        # 1. Stored state
+        if self._stored_uplight_state is not None:
+            return self._stored_uplight_state
+
+        # Get current uplight color for H, S, K
+        current_uplight = await self.get_uplight_color()
+
+        # 2. Infer from downlight average brightness
+        try:
+            downlight_colors = await self.get_downlight_colors()
+            avg_brightness = sum(c.brightness for c in downlight_colors) / len(
+                downlight_colors
+            )
+
+            # Only use inferred brightness if it's > 0
+            # If all downlights are off (brightness=0), skip to default
+            if avg_brightness > 0:
+                return HSBK(
+                    hue=current_uplight.hue,
+                    saturation=current_uplight.saturation,
+                    brightness=avg_brightness,
+                    kelvin=current_uplight.kelvin,
+                )
+        except Exception:  # nosec B110
+            # If inference fails, fall through to default
+            pass
+
+        # 3. Hardcoded default (0.8)
+        return HSBK(
+            hue=current_uplight.hue,
+            saturation=current_uplight.saturation,
+            brightness=0.8,
+            kelvin=current_uplight.kelvin,
+        )
+
+    async def _determine_downlight_brightness(self) -> list[HSBK]:
+        """Determine downlight brightness using priority logic.
+
+        Priority order:
+        1. Stored state (if available)
+        2. Infer from uplight brightness
+        3. Hardcoded default (0.8)
+
+        Returns:
+            List of HSBK colors for downlight zones
+        """
+        # 1. Stored state
+        if self._stored_downlight_state is not None:
+            return self._stored_downlight_state
+
+        # Get current downlight colors for H, S, K
+        current_downlight = await self.get_downlight_colors()
+
+        # 2. Infer from uplight brightness
+        try:
+            uplight_color = await self.get_uplight_color()
+
+            # Only use inferred brightness if it's > 0
+            # If uplight is off (brightness=0), skip to default
+            if uplight_color.brightness > 0:
+                return [
+                    HSBK(
+                        hue=c.hue,
+                        saturation=c.saturation,
+                        brightness=uplight_color.brightness,
+                        kelvin=c.kelvin,
+                    )
+                    for c in current_downlight
+                ]
+        except Exception:  # nosec B110
+            # If inference fails, fall through to default
+            pass
+
+        # 3. Hardcoded default (0.8)
+        return [
+            HSBK(
+                hue=c.hue,
+                saturation=c.saturation,
+                brightness=0.8,
+                kelvin=c.kelvin,
+            )
+            for c in current_downlight
+        ]
+
+    def _is_stored_state_valid(
+        self, component: str, current: HSBK | list[HSBK]
+    ) -> bool:
+        """Check if stored state matches current (ignoring brightness).
+
+        Args:
+            component: Either "uplight" or "downlight"
+            current: Current color(s) from device
+
+        Returns:
+            True if stored state matches current (H, S, K), False otherwise
+        """
+        if component == "uplight":
+            if self._stored_uplight_state is None or not isinstance(current, HSBK):
+                return False
+
+            stored = self._stored_uplight_state
+            return (
+                stored.hue == current.hue
+                and stored.saturation == current.saturation
+                and stored.kelvin == current.kelvin
+            )
+
+        if component == "downlight":
+            if self._stored_downlight_state is None or not isinstance(current, list):
+                return False
+
+            if len(self._stored_downlight_state) != len(current):
+                return False
+
+            # Check if all zones match (H, S, K)
+            return all(
+                s.hue == c.hue and s.saturation == c.saturation and s.kelvin == c.kelvin
+                for s, c in zip(self._stored_downlight_state, current)
+            )
+
+        return False
+
+    def _load_state_from_file(self) -> None:
+        """Load state from JSON file.
+
+        Handles file not found and JSON errors gracefully.
+        """
+        if not self._state_file:
+            return
+
+        try:
+            state_path = Path(self._state_file).expanduser()
+            if not state_path.exists():
+                _LOGGER.debug("State file does not exist: %s", state_path)
+                return
+
+            with state_path.open("r") as f:
+                data = json.load(f)
+
+            # Get state for this device
+            device_state = data.get(self.serial)
+            if not device_state:
+                _LOGGER.debug("No state found for device %s", self.serial)
+                return
+
+            # Load uplight state
+            if "uplight" in device_state:
+                uplight_data = device_state["uplight"]
+                self._stored_uplight_state = HSBK(
+                    hue=uplight_data["hue"],
+                    saturation=uplight_data["saturation"],
+                    brightness=uplight_data["brightness"],
+                    kelvin=uplight_data["kelvin"],
+                )
+
+            # Load downlight state
+            if "downlight" in device_state:
+                downlight_data = device_state["downlight"]
+                self._stored_downlight_state = [
+                    HSBK(
+                        hue=c["hue"],
+                        saturation=c["saturation"],
+                        brightness=c["brightness"],
+                        kelvin=c["kelvin"],
+                    )
+                    for c in downlight_data
+                ]
+
+            _LOGGER.debug("Loaded state from %s for device %s", state_path, self.serial)
+
+        except Exception as e:
+            _LOGGER.warning("Failed to load state from %s: %s", self._state_file, e)
+
+    def _save_state_to_file(self) -> None:
+        """Save state to JSON file.
+
+        Handles file I/O errors gracefully.
+        """
+        if not self._state_file:
+            return
+
+        try:
+            state_path = Path(self._state_file).expanduser()
+
+            # Load existing data or create new
+            if state_path.exists():
+                with state_path.open("r") as f:
+                    data = json.load(f)
+            else:
+                data = {}
+
+            # Update state for this device
+            device_state = {}
+
+            if self._stored_uplight_state:
+                device_state["uplight"] = {
+                    "hue": self._stored_uplight_state.hue,
+                    "saturation": self._stored_uplight_state.saturation,
+                    "brightness": self._stored_uplight_state.brightness,
+                    "kelvin": self._stored_uplight_state.kelvin,
+                }
+
+            if self._stored_downlight_state:
+                device_state["downlight"] = [
+                    {
+                        "hue": c.hue,
+                        "saturation": c.saturation,
+                        "brightness": c.brightness,
+                        "kelvin": c.kelvin,
+                    }
+                    for c in self._stored_downlight_state
+                ]
+
+            data[self.serial] = device_state
+
+            # Ensure directory exists
+            state_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write to file
+            with state_path.open("w") as f:
+                json.dump(data, f, indent=2)
+
+            _LOGGER.debug("Saved state to %s for device %s", state_path, self.serial)
+
+        except Exception as e:
+            _LOGGER.warning("Failed to save state to %s: %s", self._state_file, e)

lifx/devices/matrix.py

@@ -354,10 +354,7 @@ class MatrixLight(Light):
     def __init__(self, *args, **kwargs) -> None:
         """Initialize MatrixLight device.
 
-        Args:
-            serial: Device serial number
-            ip: Device IP address
-            port: Device port (default: 56700)
+        See :class:`Light` for parameter documentation.
         """
         super().__init__(*args, **kwargs)
         # Matrix specific properties
@@ -550,12 +547,15 @@ class MatrixLight(Light):
         as a list of color lists (one per tile). This is the matrix equivalent
         of MultiZoneLight's get_all_color_zones().
 
+        For tiles with >64 zones (e.g., 16x8 Ceiling with 128 zones), makes
+        multiple Get64 requests to fetch all colors.
+
         Always fetches from device. Tiles are queried sequentially to avoid
         overwhelming the device with concurrent requests.
 
         Returns:
             List of color lists, one per tile. Each inner list contains
-            the colors for that tile (typically 64 for 8x8 tiles).
+            all colors for that tile (64 for 8x8 tiles, 128 for 16x8 Ceiling).
 
         Raises:
             LifxDeviceNotFoundError: If device is not connected
@@ -583,8 +583,28 @@ class MatrixLight(Light):
         # Fetch colors from each tile sequentially
         all_colors: list[list[HSBK]] = []
         for tile in device_chain:
-            tile_colors = await self.get64(tile_index=tile.tile_index)
-            all_colors.append(tile_colors)
+            tile_zone_count = tile.width * tile.height
+
+            if tile_zone_count <= 64:
+                # Single request for tiles with ≤64 zones
+                tile_colors = await self.get64(tile_index=tile.tile_index)
+                all_colors.append(tile_colors)
+            else:
+                # Multiple requests for tiles with >64 zones (e.g., 16x8 Ceiling)
+                # Split into multiple 64-zone requests by row
+                tile_colors = []
+                rows_per_request = 64 // tile.width  # e.g., 64/16 = 4 rows
+
+                for y_offset in range(0, tile.height, rows_per_request):
+                    chunk = await self.get64(
+                        tile_index=tile.tile_index,
+                        x=0,
+                        y=y_offset,
+                        width=tile.width,
+                    )
+                    tile_colors.extend(chunk)
+
+                all_colors.append(tile_colors)
 
         # Update state if it exists (flatten for state storage)
         if self._state is not None and hasattr(self._state, "tile_colors"):

lifx/network/discovery.py

@@ -56,8 +56,8 @@ class DiscoveredDevice:
 
         Queries the device for its product ID and uses the product registry
         to instantiate the appropriate device class (Device, Light, HevLight,
-        InfraredLight, MultiZoneLight, or MatrixLight) based on the product
-        capabilities.
+        InfraredLight, MultiZoneLight, MatrixLight, or CeilingLight) based on
+        the product capabilities.
 
         This is the single source of truth for device type detection and
         instantiation across the library.
@@ -79,11 +79,13 @@ class DiscoveredDevice:
             ```
         """
         from lifx.devices.base import Device
+        from lifx.devices.ceiling import CeilingLight
         from lifx.devices.hev import HevLight
         from lifx.devices.infrared import InfraredLight
         from lifx.devices.light import Light
         from lifx.devices.matrix import MatrixLight
         from lifx.devices.multizone import MultiZoneLight
+        from lifx.products import is_ceiling_product
 
         kwargs = {
             "serial": self.serial,
@@ -100,6 +102,12 @@ class DiscoveredDevice:
             await temp_device._ensure_capabilities()
 
             if temp_device.capabilities:
+                # Check for Ceiling products first (before generic MatrixLight)
+                if temp_device.version and is_ceiling_product(
+                    temp_device.version.product
+                ):
+                    return CeilingLight(**kwargs)
+
                 if temp_device.capabilities.has_matrix:
                     return MatrixLight(**kwargs)
                 if temp_device.capabilities.has_multizone:

lifx/products/__init__.py

@@ -9,6 +9,11 @@ products.json specification.
 To update: run `uv run python -m lifx.products.generator`
 """
 
+from lifx.products.quirks import (
+    CeilingComponentLayout,
+    get_ceiling_layout,
+    is_ceiling_product,
+)
 from lifx.products.registry import (
     ProductCapability,
     ProductInfo,
@@ -19,10 +24,13 @@ from lifx.products.registry import (
 )
 
 __all__ = [
+    "CeilingComponentLayout",
     "ProductCapability",
     "ProductInfo",
     "ProductRegistry",
     "TemperatureRange",
+    "get_ceiling_layout",
     "get_product",
     "get_registry",
+    "is_ceiling_product",
 ]

lifx/products/quirks.py

@@ -0,0 +1,91 @@
+"""Product-specific quirks and metadata not available in products.json.
+
+This module provides additional metadata for LIFX products that is not included
+in the official products.json specification. These quirks are manually maintained
+and should be updated as needed when new products are released or when LIFX adds
+this information to products.json.
+
+Note:
+    If LIFX adds any of this information to products.json in the future,
+    the generator should be updated to include it in the auto-generated registry,
+    and the corresponding quirk should be removed from this module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CeilingComponentLayout:
+    """Component layout for LIFX Ceiling lights.
+
+    Ceiling lights have two logical components:
+    - Uplight: Single zone for ambient/indirect lighting
+    - Downlight: Multiple zones for main illumination
+
+    Attributes:
+        width: Matrix width in zones
+        height: Matrix height in zones
+        uplight_zone: Zone index for the uplight component
+        downlight_zones: Slice representing downlight component zones
+    """
+
+    width: int
+    height: int
+    uplight_zone: int
+    downlight_zones: slice
+
+
+# Ceiling product component layouts
+# TODO: Remove once LIFX adds component layout metadata to products.json
+CEILING_LAYOUTS: dict[int, CeilingComponentLayout] = {
+    176: CeilingComponentLayout(  # Ceiling (US)
+        width=8,
+        height=8,
+        uplight_zone=63,
+        downlight_zones=slice(0, 63),
+    ),
+    177: CeilingComponentLayout(  # Ceiling (Intl)
+        width=8,
+        height=8,
+        uplight_zone=63,
+        downlight_zones=slice(0, 63),
+    ),
+    201: CeilingComponentLayout(  # Ceiling Capsule (US)
+        width=16,
+        height=8,
+        uplight_zone=127,
+        downlight_zones=slice(0, 127),
+    ),
+    202: CeilingComponentLayout(  # Ceiling Capsule (Intl)
+        width=16,
+        height=8,
+        uplight_zone=127,
+        downlight_zones=slice(0, 127),
+    ),
+}
+
+
+def get_ceiling_layout(pid: int) -> CeilingComponentLayout | None:
+    """Get component layout for a Ceiling product.
+
+    Args:
+        pid: Product ID
+
+    Returns:
+        CeilingComponentLayout if product is a Ceiling light, None otherwise
+    """
+    return CEILING_LAYOUTS.get(pid)
+
+
+def is_ceiling_product(pid: int) -> bool:
+    """Check if product ID is a Ceiling light.
+
+    Args:
+        pid: Product ID
+
+    Returns:
+        True if product is a Ceiling light
+    """
+    return pid in CEILING_LAYOUTS

{lifx_async-4.4.1.dist-info → lifx_async-4.5.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-async
-Version: 4.4.1
+Version: 4.5.1
 Summary: A modern, type-safe, async Python library for controlling LIFX lights
 Author-email: Avi Miller <me@dje.li>
 Maintainer-email: Avi Miller <me@dje.li>

{lifx_async-4.4.1.dist-info → lifx_async-4.5.1.dist-info}/RECORD

@@ -1,15 +1,16 @@
-lifx/__init__.py,sha256=GBubbz5IrtHDMCJ9aeBzOGztvg0GTLE70rS_di1VMBQ,2524
+lifx/__init__.py,sha256=Kn1QXDD2xcT5rgqGLfXFtnVF8ATtlg0FVxOvpaG4Z1M,2562
 lifx/api.py,sha256=PFS2b28ow40kCQvT_MKvBLZD6fKCbvsoOQFtiODDrPE,33861
 lifx/color.py,sha256=wcmeeiBmOAjunInERNd6rslKvBEpV4vfjwwiZ8v7H8A,17877
 lifx/const.py,sha256=cf_O_3TqJjIBXF1tI35PkJ1JOhmy4tRt14PSa63pilA,3471
 lifx/exceptions.py,sha256=pikAMppLn7gXyjiQVWM_tSvXKNh-g366nG_UWyqpHhc,815
 lifx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lifx/devices/__init__.py,sha256=vMNbhQKMpx3zD7EPbiejjDoAYTeT-q_USYez0RtwgmQ,951
+lifx/devices/__init__.py,sha256=QQxJ6FewWEbihnjayjXwWPESsrwOWmylpwXKillQkuY,1017
 lifx/devices/base.py,sha256=x2RlGeCv60QLKklP6kA9wbCc3rmcHHhmvkSJHqTow5s,63151
+lifx/devices/ceiling.py,sha256=hpzSDxUzPvvgr3RSiqljek6u5IYTocbLcqTt82pr_18,27542
 lifx/devices/hev.py,sha256=T5hvt2q_vdgPBvThx_-M7n5pZu9pL0y9Fs3Zz_KL0NM,15588
 lifx/devices/infrared.py,sha256=ePk9qxX_s-hv5gQMvio1Vv8FYiCd68HF0ySbWgSrvuU,8130
 lifx/devices/light.py,sha256=gk92lhViUWINGaxDWbs4qn8Stnn2fGCfRkC5Kk0Q-hI,34087
-lifx/devices/matrix.py,sha256=8Z0FbBGUzRhvqs3h9fL9ZQ691C9mAoA6kuOrhe89Qwk,41061
+lifx/devices/matrix.py,sha256=AVNM2071NFtPg3Eq7kZ3asRGus36He02iDDvIa8RaQ0,41951
 lifx/devices/multizone.py,sha256=8OJ6zP5xgSCmlMQDj2mLUZ352EMkbYMbDZ1X-Cux7AU,32786
 lifx/effects/__init__.py,sha256=4DF31yp7RJic5JoltMlz5dCtF5KQobU6NOUtLUKkVKE,1509
 lifx/effects/base.py,sha256=YO0Hbg2VYHKPtfYnWxmrtzYoPGOi9BUXhn8HVFKv5IM,10283
@@ -21,11 +22,12 @@ lifx/effects/pulse.py,sha256=t5eyjfFWG1xT-RXKghRqHYJ9CG_50tPu4jsDapJZ2mw,8721
 lifx/effects/state_manager.py,sha256=iDfYowiCN5IJqcR1s-pM0mQEJpe-RDsMcOOSMmtPVDE,8983
 lifx/network/__init__.py,sha256=uSyA8r8qISG7qXUHbX8uk9A2E8rvDADgCcf94QIZ9so,499
 lifx/network/connection.py,sha256=aerPiYWf096lq8oBiS7JfE4k-P18GS50mNEC4TYa2g8,38401
-lifx/network/discovery.py,sha256=FoFoZcw3dtJs1daESiZiNXytanKQsMTdF9PjOxEgHM0,23804
+lifx/network/discovery.py,sha256=syFfkDYWo0AEoBdEBjWqBm4K7UJwZW5x2K0FBMiA2I0,24186
 lifx/network/message.py,sha256=jCLC9v0tbBi54g5CaHLFM_nP1Izu8kJmo2tt23HHBbA,2600
 lifx/network/transport.py,sha256=8QS0YV32rdP0EDiPEwuvZXbplRWL08pmjKybd87mkZ0,11070
-lifx/products/__init__.py,sha256=P5ZtYsr48hCrPNv9PS8wZVdoitnQWVDp7jn_qWnvHmQ,569
+lifx/products/__init__.py,sha256=pf2O-fzt6nOrQd-wmzhiog91tMiGa-dDbaSNtU2ZQfE,764
 lifx/products/generator.py,sha256=5bDFfrJ8ocwuhEr4dZB4LpVcqOqC3KxJSDiphPMu8CI,15660
+lifx/products/quirks.py,sha256=B8Kb4pxaXmovMbjgXRfPPWre5JEvJrn8d6PAWK_FT1U,2544
 lifx/products/registry.py,sha256=ILIJlQxcxJUzRH-LGU_bnHjV-TxDEucKovuJcWvG4q8,43831
 lifx/protocol/__init__.py,sha256=-wjC-wBcb7fxi5I-mJr2Ad8K2YRflJFdLLdobfD-W1Q,56
 lifx/protocol/base.py,sha256=x4cKT5sbaEmILbmPH3y5Lwk6gj3h9Xv_JvTX91cPQwM,12354
@@ -40,7 +42,7 @@ lifx/theme/canvas.py,sha256=4h7lgN8iu_OdchObGDgbxTqQLCb-FRKC-M-YCWef_i4,8048
 lifx/theme/generators.py,sha256=nq3Yvntq_h-eFHbmmow3LcAdA_hEbRRaP5mv9Bydrjk,6435
 lifx/theme/library.py,sha256=tKlKZNqJp8lRGDnilWyDm_Qr1vCRGGwuvWVS82anNpQ,21326
 lifx/theme/theme.py,sha256=qMEx_8E41C0Cc6f083XHiAXEglTv4YlXW0UFsG1rQKg,5521
-lifx_async-4.4.1.dist-info/METADATA,sha256=GPXITqP1r-6RIp91S1SuabkN4ie0cJxMvM498v3AKwg,2609
-lifx_async-4.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-lifx_async-4.4.1.dist-info/licenses/LICENSE,sha256=eBz48GRA3gSiWn3rYZAz2Ewp35snnhV9cSqkVBq7g3k,1832
-lifx_async-4.4.1.dist-info/RECORD,,
+lifx_async-4.5.1.dist-info/METADATA,sha256=OjmlAONCtPMp3Ur3aNJB8HHmkSDq8wKmu9I00zsXvnk,2609
+lifx_async-4.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+lifx_async-4.5.1.dist-info/licenses/LICENSE,sha256=eBz48GRA3gSiWn3rYZAz2Ewp35snnhV9cSqkVBq7g3k,1832
+lifx_async-4.5.1.dist-info/RECORD,,