lifx-emulator 2.0.0__tar.gz → 2.2.0__tar.gz

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7
+      uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -65,7 +65,7 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7
+      uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ matrix.python-version }}
@@ -124,7 +124,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7
+      uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/.github/workflows/docs.yml

@@ -35,7 +35,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7
+      uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -69,7 +69,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7
+      uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -97,7 +97,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7
+      uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-emulator
-Version: 2.0.0
+Version: 2.2.0
 Summary: LIFX Emulator for testing LIFX LAN protocol libraries
 Author-email: Avi Miller <me@dje.li>
 Maintainer-email: Avi Miller <me@dje.li>

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/docs/changelog.md

@@ -2,6 +2,27 @@
 
 <!-- version list -->
 
+## v2.2.0 (2025-11-18)
+
+### Features
+
+- **products**: Add per-product firmware version defaults to specs.yml
+  ([`336692c`](https://github.com/Djelibeybi/lifx-emulator/commit/336692c381b94956ab29235d81e358fcb2c91089))
+
+
+## v2.1.0 (2025-11-18)
+
+### Documentation
+
+- Add mkdocs-llmstxt to generate llms.txt and llms-full.txt
+  ([`4ddea81`](https://github.com/Djelibeybi/lifx-emulator/commit/4ddea813cf269991857d4871554839b5447404ae))
+
+### Features
+
+- **protocol**: Add Sky Effect support and protocol quirks
+  ([`09422ab`](https://github.com/Djelibeybi/lifx-emulator/commit/09422ab8ab200b555ff7308c37ba087ff2e848e3))
+
+
 ## v2.0.0 (2025-11-12)
 
 ### Documentation

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/mkdocs.yml

@@ -49,6 +49,57 @@ theme:
 plugins:
 - search:
     lang: en
+- llmstxt:
+    markdown_description: |
+      A comprehensive LIFX device emulator for testing LIFX LAN protocol libraries.
+
+      This emulator implements the binary UDP protocol from https://lan.developer.lifx.com
+      and emulates various LIFX device types including color lights, multizone strips,
+      tiles, infrared, and HEV devices. It provides a complete testing environment with
+      persistent storage, HTTP management API, and advanced scenario testing capabilities
+      for simulating protocol edge cases, packet loss, delays, and malformed responses.
+    full_output: llms-full.txt
+    sections:
+      Getting Started:
+      - getting-started/index.md: Overview of getting started with the emulator
+      - getting-started/installation.md: Installation instructions
+      - getting-started/quickstart.md: Quick start guide
+      - getting-started/cli.md: Command-line interface usage
+      Tutorials:
+      - tutorials/index.md: Tutorial overview
+      - tutorials/01-first-device.md: Creating your first emulated device
+      - tutorials/02-basic.md: Basic usage patterns
+      - tutorials/03-integration.md: Integration testing
+      - tutorials/04-advanced-scenarios.md: Advanced testing scenarios
+      - tutorials/05-cicd.md: CI/CD integration
+      User Guide:
+      - guide/index.md: User guide overview
+      - guide/device-types.md: Available device types
+      - guide/products-and-specs.md: Product registry and specifications
+      - guide/web-interface.md: HTTP management API and web interface
+      - guide/testing-scenarios.md: Testing scenario capabilities
+      - guide/best-practices.md: Best practices
+      - guide/integration-testing.md: Advanced testing patterns
+      API Reference:
+      - api/index.md: API reference overview
+      - api/factories.md: Device factory functions
+      - api/device.md: Device API
+      - api/server.md: Server API
+      - api/protocol.md: Protocol types
+      - api/storage.md: Storage and persistence
+      - api/products.md: Product registry
+      Advanced Topics:
+      - advanced/index.md: Advanced topics overview
+      - advanced/storage.md: Persistent storage
+      - advanced/device-management-api.md: Device management API
+      - advanced/scenarios.md: Custom scenarios
+      - advanced/scenario-api.md: Scenario management API
+      Architecture:
+      - architecture/index.md: Architecture overview
+      - architecture/overview.md: System architecture
+      - architecture/packet-flow.md: Packet flow and processing
+      - architecture/protocol.md: Protocol layer details
+      - architecture/device-state.md: Device state management
 - mkdocstrings:
     handlers:
       python:

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lifx-emulator"
-version = "2.0.0"
+version = "2.2.0"
 description = "LIFX Emulator for testing LIFX LAN protocol libraries"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -51,6 +51,7 @@ dev = [
     "mkdocs-material>=9.6.0",
     "mkdocstrings[python]>=0.27.0",
     "mkdocs-git-revision-date-localized-plugin>=1.4.0",
+    "mkdocs-llmstxt>=0.3.0",
 ]
 
 [build-system]

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/src/lifx_emulator/devices/states.py

@@ -90,10 +90,17 @@ class MatrixState:
     tile_devices: list[dict[str, Any]]
     tile_width: int
     tile_height: int
-    effect_type: int = 0  # 0=OFF, 2=MORPH, 3=FLAME
+    effect_type: int = 0  # 0=OFF, 2=MORPH, 3=FLAME, 5=SKY
     effect_speed: int = 5  # Duration of one cycle in seconds
     effect_palette_count: int = 0
     effect_palette: list[LightHsbk] = field(default_factory=list)
+    effect_sky_type: int = 0  # 0=SUNRISE, 1=SUNSET, 2=CLOUDS (only when effect_type=5)
+    effect_cloud_sat_min: int = (
+        0  # Min cloud saturation 0-200 (only when effect_type=5)
+    )
+    effect_cloud_sat_max: int = (
+        0  # Max cloud saturation 0-200 (only when effect_type=5)
+    )
 
 
 @dataclass
@@ -205,6 +212,9 @@ class DeviceState:
         "tile_effect_speed": ("matrix", "effect_speed"),
         "tile_effect_palette_count": ("matrix", "effect_palette_count"),
         "tile_effect_palette": ("matrix", "effect_palette"),
+        "tile_effect_sky_type": ("matrix", "effect_sky_type"),
+        "tile_effect_cloud_sat_min": ("matrix", "effect_cloud_sat_min"),
+        "tile_effect_cloud_sat_max": ("matrix", "effect_cloud_sat_max"),
     }
 
     # Default values for optional state attributes when state object is None
@@ -227,6 +237,9 @@ class DeviceState:
         "tile_effect_speed": 0,
         "tile_effect_palette_count": 0,
         "tile_effect_palette": [],
+        "tile_effect_sky_type": 0,
+        "tile_effect_cloud_sat_min": 0,
+        "tile_effect_cloud_sat_max": 0,
     }
 
     def get_target_bytes(self) -> bytes:

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/src/lifx_emulator/factories/builder.py

@@ -211,7 +211,9 @@ class DeviceBuilder:
 
         # 3. Determine firmware version
         version_major, version_minor = self._firmware_config.get_firmware_version(
-            extended_multizone=self._extended_multizone, override=self._firmware_version
+            product_id=self._product_info.pid,
+            extended_multizone=self._extended_multizone,
+            override=self._firmware_version,
         )
 
         # 4. Get default color

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/src/lifx_emulator/factories/firmware_config.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from lifx_emulator.products.specs import get_default_firmware_version
+
 
 class FirmwareConfig:
     """Determines firmware versions for devices.
@@ -25,12 +27,19 @@ class FirmwareConfig:
 
     def get_firmware_version(
         self,
+        product_id: int | None = None,
         extended_multizone: bool | None = None,
         override: tuple[int, int] | None = None,
     ) -> tuple[int, int]:
-        """Get firmware version based on extended multizone support.
+        """Get firmware version based on product specs or extended multizone support.
+
+        Precedence order:
+        1. Explicit override parameter
+        2. Product-specific default from specs.yml
+        3. Extended multizone flag (3.70 for True/None, 2.60 for False)
 
         Args:
+            product_id: Optional product ID to check specs for defaults
             extended_multizone: Whether device supports extended multizone.
                                None or True defaults to 3.70, False gives 2.60
             override: Optional explicit firmware version to use
@@ -46,11 +55,20 @@ class FirmwareConfig:
             (2, 60)
             >>> config.get_firmware_version(override=(4, 0))
             (4, 0)
+            >>> # With product_id, uses specs if defined
+            >>> config.get_firmware_version(product_id=27)  # doctest: +SKIP
+            (3, 70)
         """
         # Explicit override takes precedence
         if override is not None:
             return override
 
+        # Check product-specific defaults from specs
+        if product_id is not None:
+            specs_version = get_default_firmware_version(product_id)
+            if specs_version is not None:
+                return specs_version
+
         # None or True defaults to extended (3.70)
         # Only explicit False gives legacy (2.60)
         if extended_multizone is False:

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/src/lifx_emulator/handlers/tile_handlers.py

@@ -237,16 +237,24 @@ class GetEffectHandler(PacketHandler):
         while len(palette) < 16:
             palette.append(LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500))
 
-        # Create effect settings
+        # Create effect settings with Sky parameters
+        from lifx_emulator.protocol.protocol_types import TileEffectSkyType
+
+        # Use defaults for SKY effect (type=5), otherwise use stored values
+        effect_type = TileEffectType(device_state.tile_effect_type)
+        if effect_type == TileEffectType.SKY:
+            sky_type = device_state.tile_effect_sky_type or TileEffectSkyType.CLOUDS
+            cloud_sat_min = device_state.tile_effect_cloud_sat_min or 50
+            cloud_sat_max = device_state.tile_effect_cloud_sat_max or 180
+        else:
+            sky_type = device_state.tile_effect_sky_type
+            cloud_sat_min = device_state.tile_effect_cloud_sat_min
+            cloud_sat_max = device_state.tile_effect_cloud_sat_max
+
         parameter = TileEffectParameter(
-            parameter0=0,
-            parameter1=0,
-            parameter2=0,
-            parameter3=0,
-            parameter4=0,
-            parameter5=0,
-            parameter6=0,
-            parameter7=0,
+            sky_type=TileEffectSkyType(sky_type),
+            cloud_saturation_min=cloud_sat_min,
+            cloud_saturation_max=cloud_sat_max,
         )
         settings = TileEffectSettings(
             instanceid=0,
@@ -276,6 +284,27 @@ class SetEffectHandler(PacketHandler):
             return []
 
         if packet:
+            # Sky effect is only supported on LIFX Ceiling devices (176, 177, 201, 202)
+            # running firmware 4.4 or higher
+            if packet.settings.type == TileEffectType.SKY:
+                ceiling_product_ids = {176, 177, 201, 202}
+                is_ceiling = device_state.product in ceiling_product_ids
+
+                # Check firmware version >= 4.4
+                firmware_supported = device_state.version_major > 4 or (
+                    device_state.version_major == 4 and device_state.version_minor >= 4
+                )
+
+                if not (is_ceiling and firmware_supported):
+                    logger.debug(
+                        f"Ignoring SKY effect request: "
+                        f"product={device_state.product}, "
+                        f"firmware={device_state.version_major}."
+                        f"{device_state.version_minor} "
+                        f"(requires Ceiling product and firmware >= 4.4)"
+                    )
+                    return []
+
             device_state.tile_effect_type = int(packet.settings.type)
             device_state.tile_effect_speed = (
                 packet.settings.speed // 1000
@@ -285,10 +314,22 @@ class SetEffectHandler(PacketHandler):
             )
             device_state.tile_effect_palette_count = packet.settings.palette_count
 
+            # Save Sky effect parameters
+            device_state.tile_effect_sky_type = int(packet.settings.parameter.sky_type)
+            device_state.tile_effect_cloud_sat_min = (
+                packet.settings.parameter.cloud_saturation_min
+            )
+            device_state.tile_effect_cloud_sat_max = (
+                packet.settings.parameter.cloud_saturation_max
+            )
+
             logger.info(
                 f"Tile effect set: type={packet.settings.type}, "
                 f"speed={packet.settings.speed}ms, "
-                f"palette_count={packet.settings.palette_count}"
+                f"palette_count={packet.settings.palette_count}, "
+                f"sky_type={packet.settings.parameter.sky_type}, "
+                f"cloud_sat=[{packet.settings.parameter.cloud_saturation_min}, "
+                f"{packet.settings.parameter.cloud_saturation_max}]"
             )
 
         if res_required:

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/src/lifx_emulator/products/generator.py

@@ -788,7 +788,7 @@ def _generate_yaml_header() -> list[str]:
         "#",
         "# This file contains product-specific details that are not available in the",
         "# upstream LIFX products.json catalog, such as default zone counts, tile",
-        "# configurations, and other device-specific defaults.",
+        "# configurations, firmware versions, and other device-specific defaults.",
         "#",
         "# These values are used by the emulator to create realistic device",
         "# configurations when specific parameters are not provided by the user.",
@@ -809,8 +809,25 @@ def _generate_yaml_header() -> list[str]:
         "#     tile_width: <number>              # Width of each tile in pixels",
         "#     tile_height: <number>             # Height of each tile in pixels",
         "#",
+        "#     # Host firmware version (optional, overrides auto firmware selection)",
+        "#     default_firmware_major: <number>  # Firmware major version (e.g., 3)",
+        "#     default_firmware_minor: <number>  # Firmware minor version (e.g., 70)",
+        "#",
         "#     # Other device-specific defaults",
         '#     notes: "<string>"                 # Notes about product',
+        "#",
+        "# Firmware Version Notes:",
+        "# ----------------------",
+        "# If default_firmware_major and default_firmware_minor are both specified ",
+        "# they will be used as the default firmware version when creating devices",
+        "# of that type. This overrides the automatic firmware version selection",
+        "# based on extended_multizone capability (which defaults to 3.70 for extended",
+        "# multizone or 2.60 for non-extended).",
+        "#",
+        "# Precedence order for firmware version:",
+        "# 1. Explicit firmware_version parameter to create_device()",
+        "# 2. Product-specific default from this specs.yml file",
+        "# 3. Automatic selection based on extended_multizone flag",
         "",
         "products:",
     ]
@@ -847,6 +864,15 @@ def _generate_multizone_section(
         lines.append(f"    min_zone_count: {specs['min_zone_count']}")
         lines.append(f"    max_zone_count: {specs['max_zone_count']}")
 
+        # Add firmware version if present
+        if "default_firmware_major" in specs and "default_firmware_minor" in specs:
+            lines.append(
+                f"    default_firmware_major: {specs['default_firmware_major']}"
+            )
+            lines.append(
+                f"    default_firmware_minor: {specs['default_firmware_minor']}"
+            )
+
         notes = specs.get("notes", "")
         if notes:
             notes_escaped = notes.replace('"', '\\"')
@@ -889,6 +915,15 @@ def _generate_matrix_section(
         lines.append(f"    tile_width: {specs['tile_width']}")
         lines.append(f"    tile_height: {specs['tile_height']}")
 
+        # Add firmware version if present
+        if "default_firmware_major" in specs and "default_firmware_minor" in specs:
+            lines.append(
+                f"    default_firmware_major: {specs['default_firmware_major']}"
+            )
+            lines.append(
+                f"    default_firmware_minor: {specs['default_firmware_minor']}"
+            )
+
         notes = specs.get("notes", "")
         if notes:
             notes_escaped = notes.replace('"', '\\"')

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/src/lifx_emulator/products/specs.py

@@ -27,6 +27,8 @@ class ProductSpecs:
         max_tile_count: Maximum tiles supported
         tile_width: Width of each tile in pixels
         tile_height: Height of each tile in pixels
+        default_firmware_major: Default firmware major version
+        default_firmware_minor: Default firmware minor version
         notes: Human-readable notes about this product
     """
 
@@ -39,6 +41,8 @@ class ProductSpecs:
     max_tile_count: int | None = None
     tile_width: int | None = None
     tile_height: int | None = None
+    default_firmware_major: int | None = None
+    default_firmware_minor: int | None = None
     notes: str | None = None
 
     @property
@@ -51,6 +55,14 @@ class ProductSpecs:
         """Check if this product has matrix-specific specs."""
         return self.tile_width is not None or self.tile_height is not None
 
+    @property
+    def has_firmware_specs(self) -> bool:
+        """Check if this product has firmware version specs."""
+        return (
+            self.default_firmware_major is not None
+            and self.default_firmware_minor is not None
+        )
+
 
 class SpecsRegistry:
     """Registry of product specs loaded from specs.yml."""
@@ -93,6 +105,8 @@ class SpecsRegistry:
                 max_tile_count=specs_data.get("max_tile_count"),
                 tile_width=specs_data.get("tile_width"),
                 tile_height=specs_data.get("tile_height"),
+                default_firmware_major=specs_data.get("default_firmware_major"),
+                default_firmware_minor=specs_data.get("default_firmware_minor"),
                 notes=specs_data.get("notes"),
             )
 
@@ -169,6 +183,23 @@ class SpecsRegistry:
             return (specs.tile_width, specs.tile_height)
         return None
 
+    def get_default_firmware_version(self, product_id: int) -> tuple[int, int] | None:
+        """Get default firmware version for a product.
+
+        Args:
+            product_id: Product ID
+
+        Returns:
+            Tuple of (major, minor) if defined, None otherwise
+        """
+        specs = self.get_specs(product_id)
+        if specs and specs.has_firmware_specs:
+            # has_firmware_specs ensures both values are not None
+            assert specs.default_firmware_major is not None  # nosec
+            assert specs.default_firmware_minor is not None  # nosec
+            return (specs.default_firmware_major, specs.default_firmware_minor)
+        return None
+
     def __len__(self) -> int:
         """Get number of products with specs."""
         if not self._loaded:
@@ -239,3 +270,15 @@ def get_tile_dimensions(product_id: int) -> tuple[int, int] | None:
         Tuple of (width, height) if defined, None otherwise
     """
     return _specs_registry.get_tile_dimensions(product_id)
+
+
+def get_default_firmware_version(product_id: int) -> tuple[int, int] | None:
+    """Get default firmware version for a product.
+
+    Args:
+        product_id: Product ID
+
+    Returns:
+        Tuple of (major, minor) if defined, None otherwise
+    """
+    return _specs_registry.get_default_firmware_version(product_id)

{lifx_emulator-2.0.0 → lifx_emulator-2.2.0}/src/lifx_emulator/products/specs.yml

@@ -3,7 +3,7 @@
 #
 # This file contains product-specific details that are not available in the
 # upstream LIFX products.json catalog, such as default zone counts, tile
-# configurations, and other device-specific defaults.
+# configurations, firmware versions, and other device-specific defaults.
 #
 # These values are used by the emulator to create realistic device
 # configurations when specific parameters are not provided by the user.
@@ -24,8 +24,25 @@
 #     tile_width: <number>              # Width of each tile in pixels
 #     tile_height: <number>             # Height of each tile in pixels
 #
+#     # Host firmware version (optional, overrides automatic firmware selection)
+#     default_firmware_major: <number>  # Firmware major version (e.g., 3)
+#     default_firmware_minor: <number>  # Firmware minor version (e.g., 70)
+#
 #     # Other device-specific defaults
 #     notes: "<string>"                 # Notes about product
+#
+# Firmware Version Notes:
+# ----------------------
+# If default_firmware_major and default_firmware_minor are both specified for a
+# product, they will be used as the default firmware version when creating devices
+# of that product type. This overrides the automatic firmware version selection
+# based on extended_multizone capability (which defaults to 3.70 for extended
+# multizone or 2.60 for non-extended).
+#
+# Precedence order for firmware version:
+# 1. Explicit firmware_version parameter to create_device()
+# 2. Product-specific default from this specs.yml file
+# 3. Automatic selection based on extended_multizone flag
 
 products:
   # ========================================
@@ -220,15 +237,19 @@ products:
     max_tile_count: 1
     tile_width: 8
     tile_height: 8
+    default_firmware_major: 4
+    default_firmware_minor: 10
     notes: 'LIFX Ceiling, 8x8 matrix, zones 1-63: downlight, zone 64: uplight'
 
-  177:  # LIFX Tube Intl
+  177:  # LIFX Ceiling Intl
     default_tile_count: 1
     min_tile_count: 1
     max_tile_count: 1
-    tile_width: 5
-    tile_height: 11
-    notes: LIFX Tube Intl
+    tile_width: 8
+    tile_height: 8
+    default_firmware_major: 4
+    default_firmware_minor: 10
+    notes: LIFX Ceiling Intl
 
   185:  # LIFX Candle Color US
     default_tile_count: 1
@@ -252,6 +273,8 @@ products:
     max_tile_count: 1
     tile_width: 16
     tile_height: 8
+    default_firmware_major: 4
+    default_firmware_minor: 10
     notes: LIFX Ceiling 13x26" US
 
   202:  # LIFX Ceiling 13x26" Intl
@@ -260,6 +283,8 @@ products:
     max_tile_count: 1
     tile_width: 16
     tile_height: 8
+    default_firmware_major: 4
+    default_firmware_minor: 10
     notes: LIFX Ceiling 13x26" Intl
 
   215:  # LIFX Candle Color US