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

{lifx_emulator-2.0.0 → lifx_emulator-2.1.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.1.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.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-emulator
-Version: 2.0.0
+Version: 2.1.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.1.0}/docs/changelog.md

@@ -2,6 +2,19 @@
 
 <!-- version list -->
 
+## 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.1.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.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lifx-emulator"
-version = "2.0.0"
+version = "2.1.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.1.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.1.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 = device_state.tile_effect_type
+        if effect_type == 5:  # SKY effect
+            sky_type = device_state.tile_effect_sky_type or 2  # Default to 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,
@@ -285,10 +293,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.1.0}/src/lifx_emulator/protocol/base.py

@@ -10,10 +10,13 @@ Performance optimizations:
 
 from __future__ import annotations
 
+import logging
 import re
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass
 from typing import Any, ClassVar
 
+_LOGGER = logging.getLogger(__name__)
+
 # Performance optimization: Pre-compiled regex patterns
 _CAMEL_TO_SNAKE_PATTERN = re.compile(r"(?<!^)(?=[A-Z])")
 _ARRAY_TYPE_PATTERN = re.compile(r"\[(\d+)\](.+)")
@@ -39,6 +42,11 @@ class Packet:
     _fields: ClassVar[list[dict[str, Any]]]
     _field_info: ClassVar[list[tuple[str, str, int]] | None] = None
 
+    @property
+    def as_dict(self) -> dict[str, Any]:
+        """Return packet as dictionary."""
+        return asdict(self)
+
     def pack(self) -> bytes:
         """Pack packet to bytes using field metadata.
 
@@ -76,9 +84,25 @@ class Packet:
             offset: Offset in bytes to start unpacking
 
         Returns:
-            Packet instance
+            Packet instance with label fields decoded to strings
         """
         packet, _ = cls._unpack_internal(data, offset)
+
+        # Decode label fields from bytes to string in-place
+        # This ensures all State packets have human-readable labels
+        cls._decode_labels_inplace(packet)
+
+        # Log packet values after unpacking and decoding labels
+        packet_values = asdict(packet)
+        _LOGGER.debug(
+            {
+                "class": "Packet",
+                "method": "unpack",
+                "packet_type": type(packet).__name__,
+                "values": packet_values,
+            }
+        )
+
         return packet
 
     @classmethod
@@ -177,6 +201,9 @@ class Packet:
             "MultiZoneApplicationRequest",
             "MultiZoneEffectType",
             "MultiZoneExtendedApplicationRequest",
+            "TileEffectSkyPalette",
+            "TileEffectSkyType",
+            "TileEffectType",
         }
         is_enum = is_nested and base_type in enum_types
 
@@ -320,6 +347,9 @@ class Packet:
             MultiZoneApplicationRequest,
             MultiZoneEffectType,
             MultiZoneExtendedApplicationRequest,
+            TileEffectSkyPalette,
+            TileEffectSkyType,
+            TileEffectType,
         )
 
         base_type, array_count, is_nested = cls._parse_field_type(field_type)
@@ -331,6 +361,9 @@ class Packet:
             "MultiZoneApplicationRequest": MultiZoneApplicationRequest,
             "MultiZoneEffectType": MultiZoneEffectType,
             "MultiZoneExtendedApplicationRequest": MultiZoneExtendedApplicationRequest,
+            "TileEffectSkyPalette": TileEffectSkyPalette,
+            "TileEffectSkyType": TileEffectSkyType,
+            "TileEffectType": TileEffectType,
         }
 
         if array_count:
@@ -386,3 +419,28 @@ class Packet:
         # Cache the result
         _FIELD_TYPE_CACHE[field_type] = result
         return result
+
+    @staticmethod
+    def _decode_labels_inplace(packet: object) -> None:
+        """Decode label fields from bytes to string in-place.
+
+        Automatically finds and decodes any field named 'label' or ending with '_label'
+        for all State packets. This ensures human-readable labels in all contexts.
+
+        Args:
+            packet: Packet instance to process (modified in-place)
+        """
+        from dataclasses import fields, is_dataclass
+
+        if not is_dataclass(packet):
+            return
+
+        for field_info in fields(packet):
+            # Check if this looks like a label field
+            if field_info.name == "label" or field_info.name.endswith("_label"):
+                value = getattr(packet, field_info.name)
+                if isinstance(value, bytes):
+                    # Decode: strip null terminator, decode UTF-8
+                    decoded = value.rstrip(b"\x00").decode("utf-8")
+                    # Use object.__setattr__ to bypass frozen dataclass if needed
+                    object.__setattr__(packet, field_info.name, decoded)

{lifx_emulator-2.0.0 → lifx_emulator-2.1.0}/src/lifx_emulator/protocol/protocol_types.py

@@ -505,16 +505,11 @@ class TileBufferRect:
 
 @dataclass
 class TileEffectParameter:
-    """Auto-generated field structure."""
+    """Auto-generated field structure for Sky effects."""
 
-    parameter0: int
-    parameter1: int
-    parameter2: int
-    parameter3: int
-    parameter4: int
-    parameter5: int
-    parameter6: int
-    parameter7: int
+    sky_type: TileEffectSkyType
+    cloud_saturation_min: int
+    cloud_saturation_max: int
 
     def pack(self) -> bytes:
         """Pack to bytes."""
@@ -522,22 +517,18 @@ class TileEffectParameter:
 
         result = b""
 
-        # parameter0: uint32
-        result += serializer.pack_value(self.parameter0, "uint32")
-        # parameter1: uint32
-        result += serializer.pack_value(self.parameter1, "uint32")
-        # parameter2: uint32
-        result += serializer.pack_value(self.parameter2, "uint32")
-        # parameter3: uint32
-        result += serializer.pack_value(self.parameter3, "uint32")
-        # parameter4: uint32
-        result += serializer.pack_value(self.parameter4, "uint32")
-        # parameter5: uint32
-        result += serializer.pack_value(self.parameter5, "uint32")
-        # parameter6: uint32
-        result += serializer.pack_value(self.parameter6, "uint32")
-        # parameter7: uint32
-        result += serializer.pack_value(self.parameter7, "uint32")
+        # sky_type: TileEffectSkyType (enum)
+        result += serializer.pack_value(int(self.sky_type), "uint8")
+        # Reserved 3 bytes
+        result += serializer.pack_reserved(3)
+        # cloud_saturation_min: uint8
+        result += serializer.pack_value(self.cloud_saturation_min, "uint8")
+        # Reserved 3 bytes
+        result += serializer.pack_reserved(3)
+        # cloud_saturation_max: uint8
+        result += serializer.pack_value(self.cloud_saturation_max, "uint8")
+        # Reserved 23 bytes
+        result += serializer.pack_reserved(23)
 
         return result
 
@@ -547,49 +538,31 @@ class TileEffectParameter:
         from lifx_emulator.protocol import serializer
 
         current_offset = offset
-        # parameter0: uint32
-        parameter0, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter1: uint32
-        parameter1, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter2: uint32
-        parameter2, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter3: uint32
-        parameter3, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter4: uint32
-        parameter4, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter5: uint32
-        parameter5, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
+        # sky_type: TileEffectSkyType (enum)
+        sky_type_raw, current_offset = serializer.unpack_value(
+            data, "uint8", current_offset
         )
-        # parameter6: uint32
-        parameter6, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
+        sky_type = TileEffectSkyType(sky_type_raw)
+        # Skip reserved 3 bytes
+        current_offset += 3
+        # cloud_saturation_min: uint8
+        cloud_saturation_min, current_offset = serializer.unpack_value(
+            data, "uint8", current_offset
         )
-        # parameter7: uint32
-        parameter7, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
+        # Skip reserved 3 bytes
+        current_offset += 3
+        # cloud_saturation_max: uint8
+        cloud_saturation_max, current_offset = serializer.unpack_value(
+            data, "uint8", current_offset
         )
+        # Skip reserved 23 bytes
+        current_offset += 23
 
         return (
             cls(
-                parameter0=parameter0,
-                parameter1=parameter1,
-                parameter2=parameter2,
-                parameter3=parameter3,
-                parameter4=parameter4,
-                parameter5=parameter5,
-                parameter6=parameter6,
-                parameter7=parameter7,
+                sky_type=sky_type,
+                cloud_saturation_min=cloud_saturation_min,
+                cloud_saturation_max=cloud_saturation_max,
             ),
             current_offset,
         )

{lifx_emulator-2.0.0 → lifx_emulator-2.1.0}/src/lifx_emulator/server.py

@@ -217,7 +217,7 @@ class EmulatedLifxServer:
             resp_packet_name = _get_packet_type_name(resp_header.pkt_type)
             resp_fields_str = _format_packet_fields(resp_packet)
             logger.debug(
-                "→ TX %s to %s:%s (device=%s, seq=%s) [%s]",
+                "→ TX %s to %s:%s (target=%s, seq=%s) [%s]",
                 resp_packet_name,
                 addr[0],
                 addr[1],
@@ -303,7 +303,9 @@ class EmulatedLifxServer:
 
             # Log received packet with details
             packet_name = _get_packet_type_name(header.pkt_type)
-            target_str = "broadcast" if header.tagged else header.target.hex()
+            target_str = (
+                "broadcast" if header.tagged else header.target.hex().rstrip("0000")
+            )
             fields_str = _format_packet_fields(packet)
             logger.debug(
                 "← RX %s from %s:%s (target=%s, seq=%s) [%s]",

{lifx_emulator-2.0.0 → lifx_emulator-2.1.0}/tests/test_tile_handlers_extended.py

@@ -7,6 +7,7 @@ from lifx_emulator.protocol.protocol_types import (
     TileBufferRect,
     TileEffectParameter,
     TileEffectSettings,
+    TileEffectSkyType,
     TileEffectType,
 )
 
@@ -478,14 +479,9 @@ class TestTileEffects:
             palette.append(LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500))
 
         parameter = TileEffectParameter(
-            parameter0=0,
-            parameter1=0,
-            parameter2=0,
-            parameter3=0,
-            parameter4=0,
-            parameter5=0,
-            parameter6=0,
-            parameter7=0,
+            sky_type=TileEffectSkyType.SUNRISE,
+            cloud_saturation_min=0,
+            cloud_saturation_max=0,
         )
 
         settings = TileEffectSettings(
@@ -522,14 +518,9 @@ class TestTileEffects:
             LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500) for _ in range(16)
         ]
         parameter = TileEffectParameter(
-            parameter0=0,
-            parameter1=0,
-            parameter2=0,
-            parameter3=0,
-            parameter4=0,
-            parameter5=0,
-            parameter6=0,
-            parameter7=0,
+            sky_type=TileEffectSkyType.SUNRISE,
+            cloud_saturation_min=0,
+            cloud_saturation_max=0,
         )
 
         settings = TileEffectSettings(
@@ -584,14 +575,9 @@ class TestTileEffects:
             LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500) for _ in range(16)
         ]
         parameter = TileEffectParameter(
-            parameter0=0,
-            parameter1=0,
-            parameter2=0,
-            parameter3=0,
-            parameter4=0,
-            parameter5=0,
-            parameter6=0,
-            parameter7=0,
+            sky_type=TileEffectSkyType.SUNRISE,
+            cloud_saturation_min=0,
+            cloud_saturation_max=0,
         )
         settings = TileEffectSettings(
             instanceid=1,
@@ -629,14 +615,9 @@ class TestTileEffects:
             palette.append(LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500))
 
         parameter = TileEffectParameter(
-            parameter0=0,
-            parameter1=0,
-            parameter2=0,
-            parameter3=0,
-            parameter4=0,
-            parameter5=0,
-            parameter6=0,
-            parameter7=0,
+            sky_type=TileEffectSkyType.SUNRISE,
+            cloud_saturation_min=0,
+            cloud_saturation_max=0,
         )
 
         settings = TileEffectSettings(