lifx-emulator 2.2.1__tar.gz → 2.3.0__tar.gz

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/CLAUDE.md

@@ -523,6 +523,9 @@ delay = manager.get_response_delay(502, merged)  # 1.0s
 - Dataclass holding all device state (color, power, zones, tiles, firmware version, etc.)
 - Capability flags: `has_color`, `has_infrared`, `has_multizone`, `has_matrix`, `has_hev`
 - Initialized differently per device type via factory functions
+- **TileFramebuffers**: Internal dataclass for storing non-visible framebuffers (1-7) per tile
+  - Provides `get_framebuffer(fb_index, width, height)` for lazy initialization
+  - Framebuffer 0 remains in protocol-defined `tile_devices[i]["colors"]`
 
 ### Protocol Layer
 
@@ -748,6 +751,19 @@ product.supports_extended_multizone(131148)  # False (below requirement)
 - Tiles with more than 64 zones (16×8) require multiple Get64 requests with different y coordinates
 - Tile state stored in `DeviceState.tile_devices` list, each with `colors` array
 
+#### Framebuffer Support
+Matrix devices support 8 framebuffers (0-7) for advanced rendering:
+- **Framebuffer 0**: The visible buffer, stored in `tile_devices[i]["colors"]`
+- **Framebuffers 1-7**: Non-visible buffers, stored in `MatrixState.tile_framebuffers`
+- **Set64**: Respects `rect.fb_index` to update the specified framebuffer
+- **Get64**: Always returns framebuffer 0 (visible buffer) regardless of request `fb_index`
+- **CopyFrameBuffer**: Copies rectangular zones from one framebuffer to another
+  - Can copy from any FB (0-7) to any other FB (0-7)
+  - Supports source/destination offsets and partial rectangles
+  - Use to make non-visible buffers visible by copying to FB0
+- Framebuffers are lazily initialized on first access
+- Non-visible framebuffers are persisted with device state
+
 ### Testing Scenarios
 Configure via ScenarioConfig in HierarchicalScenarioManager:
 - `drop_packets`: Dict mapping packet type to drop rate (0.0-1.0, where 1.0 = always drop)

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-emulator
-Version: 2.2.1
+Version: 2.3.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.2.1 → lifx_emulator-2.3.0}/docs/changelog.md

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v2.3.0 (2025-11-18)
+
+### Features
+
+- **tile**: Implement multi-framebuffer support for matrix devices
+  ([`16a69ca`](https://github.com/Djelibeybi/lifx-emulator/commit/16a69cacbdf0472d8f7116eb0acfda9808431c5c))
+
+
 ## v2.2.1 (2025-11-18)
 
 ### Bug Fixes

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/docs/guide/device-types.md

@@ -329,6 +329,17 @@ single tile.
 # split either by row or column.
 ```
 
+### Framebuffers (v2.3+)
+
+Matrix devices support **8 framebuffers (0-7)** to enable atomic updates of tiles with more than 64 zones:
+
+- **Framebuffer 0**: Visible buffer (displayed on device)
+- **Framebuffers 1-7**: Non-visible buffers for preparing content off-screen
+
+For large tiles (>64 zones), prepare all zones in a non-visible framebuffer, then use `CopyFrameBuffer` to atomically display them without flicker.
+
+See [Framebuffer Guide](framebuffers.md) for complete documentation and examples.
+
 
 ## Using Generic create_device()
 

lifx_emulator-2.3.0/docs/guide/framebuffers.md

@@ -0,0 +1,209 @@
+# Matrix Framebuffer Support
+
+Matrix devices with more than 64 zones require multiple Set64 packets to update all zones. Framebuffers enable atomic updates by allowing you to prepare all zones off-screen before displaying them.
+
+## Overview
+
+Matrix devices support **8 framebuffers (0-7)**:
+
+- **Framebuffer 0**: The visible buffer displayed on the device
+- **Framebuffers 1-7**: Non-visible buffers for preparing content
+
+## Why Framebuffers Matter
+
+For large tiles (>64 zones), such as the LIFX Ceiling 13"x26" with 128 zones (16×8):
+
+**Without framebuffers:**
+```
+Set64(fb=0, zones 0-63)   → Visible immediately (partial update)
+Set64(fb=0, zones 64-127) → Visible immediately (flicker as zones update)
+```
+
+**With framebuffers:**
+```
+Set64(fb=1, zones 0-63)      → Prepared off-screen
+Set64(fb=1, zones 64-127)    → Prepared off-screen
+CopyFrameBuffer(fb=1 → fb=0) → All 128 zones appear atomically
+```
+
+## Framebuffer Operations
+
+### Set64 - Update Zones
+
+The `rect.fb_index` field specifies which framebuffer to update:
+
+```python
+from lifx_emulator.protocol.packets import Tile
+from lifx_emulator.protocol.protocol_types import TileBufferRect, LightHsbk
+
+# Update visible framebuffer (immediate display)
+rect = TileBufferRect(fb_index=0, x=0, y=0, width=8)
+packet = Tile.Set64(
+    tile_index=0,
+    rect=rect,
+    duration=0,
+    colors=[...64 colors...]
+)
+
+# Update non-visible framebuffer 1 (off-screen)
+rect = TileBufferRect(fb_index=1, x=0, y=0, width=8)
+packet = Tile.Set64(
+    tile_index=0,
+    rect=rect,
+    duration=0,
+    colors=[...64 colors...]
+)
+```
+
+### Get64 - Read Zones
+
+Get64 **always returns framebuffer 0** (the visible buffer), regardless of the `fb_index` in the request:
+
+```python
+# Request can specify any fb_index
+rect = TileBufferRect(fb_index=1, x=0, y=0, width=8)
+packet = Tile.Get64(tile_index=0, rect=rect)
+
+# Response will contain framebuffer 0 content
+# Response rect.fb_index is always 0
+```
+
+### CopyFrameBuffer - Atomic Display
+
+Copy zones between framebuffers to make prepared content visible:
+
+```python
+# Copy entire framebuffer 1 to framebuffer 0 (make visible)
+packet = Tile.CopyFrameBuffer(
+    tile_index=0,
+    src_fb_index=1,
+    dst_fb_index=0,
+    src_x=0,
+    src_y=0,
+    dst_x=0,
+    dst_y=0,
+    width=16,
+    height=8,
+    duration=0
+)
+```
+
+## Complete Example: Updating a 16×8 Tile
+
+```python
+from lifx_emulator import create_tile_device
+from lifx_emulator.protocol.packets import Tile
+from lifx_emulator.protocol.protocol_types import TileBufferRect, LightHsbk
+
+# Create 16×8 tile (128 zones)
+device = create_tile_device(
+    serial="d073dc000001",
+    tile_count=1,
+    tile_width=16,
+    tile_height=8
+)
+
+# Prepare colors for all 128 zones
+red = LightHsbk(hue=0, saturation=65535, brightness=65535, kelvin=3500)
+green = LightHsbk(hue=21845, saturation=65535, brightness=65535, kelvin=3500)
+
+# Step 1: Update first 64 zones in framebuffer 1 (rows 0-3)
+rect1 = TileBufferRect(fb_index=1, x=0, y=0, width=16)
+set1 = Tile.Set64(
+    tile_index=0,
+    rect=rect1,
+    duration=0,
+    colors=[red] * 64
+)
+device.process_packet(header, set1)
+
+# Step 2: Update next 64 zones in framebuffer 1 (rows 4-7)
+rect2 = TileBufferRect(fb_index=1, x=0, y=4, width=16)
+set2 = Tile.Set64(
+    tile_index=0,
+    rect=rect2,
+    duration=0,
+    colors=[green] * 64
+)
+device.process_packet(header, set2)
+
+# Step 3: Atomically display all 128 zones
+copy = Tile.CopyFrameBuffer(
+    tile_index=0,
+    src_fb_index=1,
+    dst_fb_index=0,
+    src_x=0,
+    src_y=0,
+    dst_x=0,
+    dst_y=0,
+    width=16,
+    height=8,
+    duration=0
+)
+device.process_packet(header, copy)
+
+# All 128 zones now visible without flicker
+```
+
+## Implementation Details
+
+### Storage
+
+- **Framebuffer 0**: Stored in `tile_devices[i]["colors"]` (protocol-defined)
+- **Framebuffers 1-7**: Stored in `MatrixState.tile_framebuffers` (internal)
+
+### Lazy Initialization
+
+Non-visible framebuffers are created on first access:
+
+```python
+# First Set64 to framebuffer 2 creates it automatically
+# Initialized with black (hue=0, saturation=0, brightness=0)
+```
+
+### Persistence
+
+Non-visible framebuffers are saved with device state when persistence is enabled:
+
+```bash
+lifx-emulator --persistent --tile 1
+```
+
+## Best Practices
+
+### For Tiles ≤64 Zones
+Update framebuffer 0 directly (no need for off-screen preparation):
+
+```python
+rect = TileBufferRect(fb_index=0, x=0, y=0, width=8)
+```
+
+### For Tiles >64 Zones
+Always use a non-visible framebuffer:
+
+1. Prepare all zones in framebuffer 1-7
+2. Use CopyFrameBuffer to make visible
+3. Prevents flicker during multi-packet updates
+
+### Partial Updates
+Use CopyFrameBuffer with specific rectangles:
+
+```python
+# Copy only top-left 4×4 area
+copy = Tile.CopyFrameBuffer(
+    src_fb_index=1,
+    dst_fb_index=0,
+    src_x=0,
+    src_y=0,
+    dst_x=0,
+    dst_y=0,
+    width=4,
+    height=4,
+    duration=0
+)
+```
+
+## Related Documentation
+
+- [Device Types](device-types.md#matrix-devices) - Matrix device capabilities
+- [Protocol](../architecture/protocol.md) - LIFX LAN protocol details

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lifx-emulator"
-version = "2.2.1"
+version = "2.3.0"
 description = "LIFX Emulator for testing LIFX LAN protocol libraries"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -88,6 +88,7 @@ max-statements = 50
 [tool.ruff.lint.per-file-ignores]
 "src/lifx_emulator/__main__.py" = ["C901"]
 "src/lifx_emulator/devices/state_restorer.py" = ["C901"]
+"src/lifx_emulator/handlers/tile_handlers.py" = ["C901"]
 "src/lifx_emulator/protocol/generator.py" = ["E501", "C901"]
 "src/lifx_emulator/protocol/packets.py" = ["E501"]
 "src/lifx_emulator/products/registry.py" = ["C901"]

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/src/lifx_emulator/devices/device.py

@@ -9,7 +9,7 @@ import time
 from typing import Any
 
 from lifx_emulator.constants import LIFX_HEADER_SIZE
-from lifx_emulator.devices.states import DeviceState
+from lifx_emulator.devices.states import DeviceState, TileFramebuffers
 from lifx_emulator.handlers import HandlerRegistry, create_default_registry
 from lifx_emulator.protocol.header import LifxHeader
 from lifx_emulator.protocol.packets import (
@@ -114,6 +114,12 @@ class EmulatedLifxDevice:
                         }
                     )
 
+            # Initialize framebuffer storage for each tile (framebuffers 1-7)
+            # Framebuffer 0 is stored in tile_devices[i]["colors"]
+            if not self.state.tile_framebuffers:
+                for i in range(self.state.tile_count):
+                    self.state.tile_framebuffers.append(TileFramebuffers(tile_index=i))
+
         # Save initial state if persistence is enabled
         # This ensures newly created devices are immediately persisted
         if self.storage:

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/src/lifx_emulator/devices/state_serializer.py

@@ -97,6 +97,17 @@ def serialize_device_state(device_state: Any) -> dict[str, Any]:
             }
             for t in device_state.tile_devices
         ]
+        # Serialize tile framebuffers (non-visible framebuffers 1-7)
+        state_dict["tile_framebuffers"] = [
+            {
+                "tile_index": fb.tile_index,
+                "framebuffers": {
+                    str(fb_idx): [serialize_hsbk(c) for c in colors]
+                    for fb_idx, colors in fb.framebuffers.items()
+                },
+            }
+            for fb in device_state.tile_framebuffers
+        ]
 
     return state_dict
 
@@ -127,4 +138,20 @@ def deserialize_device_state(state_dict: dict[str, Any]) -> dict[str, Any]:
         for tile_dict in state_dict["tile_devices"]:
             tile_dict["colors"] = [deserialize_hsbk(c) for c in tile_dict["colors"]]
 
+    # Deserialize tile framebuffers if present (for backwards compatibility)
+    if "tile_framebuffers" in state_dict:
+        from lifx_emulator.devices.states import TileFramebuffers
+
+        deserialized_fbs = []
+        for fb_dict in state_dict["tile_framebuffers"]:
+            tile_fb = TileFramebuffers(tile_index=fb_dict["tile_index"])
+            # Deserialize each framebuffer's colors
+            for fb_idx_str, colors_list in fb_dict["framebuffers"].items():
+                fb_idx = int(fb_idx_str)
+                tile_fb.framebuffers[fb_idx] = [
+                    deserialize_hsbk(c) for c in colors_list
+                ]
+            deserialized_fbs.append(tile_fb)
+        state_dict["tile_framebuffers"] = deserialized_fbs
+
     return state_dict

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/src/lifx_emulator/devices/states.py

@@ -82,6 +82,32 @@ class MultiZoneState:
     effect_speed: int = 5  # Duration of one cycle in seconds
 
 
+@dataclass
+class TileFramebuffers:
+    """Internal storage for non-visible tile framebuffers (1-7).
+
+    Framebuffer 0 is stored in tile_devices[i]["colors"] (the visible buffer).
+    Framebuffers 1-7 are stored here for Set64/CopyFrameBuffer operations.
+    Each framebuffer is a list of LightHsbk colors with length = width * height.
+    """
+
+    tile_index: int  # Which tile this belongs to
+    framebuffers: dict[int, list[LightHsbk]] = field(default_factory=dict)
+
+    def get_framebuffer(
+        self, fb_index: int, width: int, height: int
+    ) -> list[LightHsbk]:
+        """Get framebuffer by index, creating it if needed."""
+        if fb_index not in self.framebuffers:
+            # Initialize with default black color
+            pixels = width * height
+            self.framebuffers[fb_index] = [
+                LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500)
+                for _ in range(pixels)
+            ]
+        return self.framebuffers[fb_index]
+
+
 @dataclass
 class MatrixState:
     """Matrix (tile/candle) capability state."""
@@ -101,6 +127,9 @@ class MatrixState:
     effect_cloud_sat_max: int = (
         0  # Max cloud saturation 0-200 (only when effect_type=5)
     )
+    # Internal storage for non-visible framebuffers (1-7) per tile
+    # Framebuffer 0 remains in tile_devices[i]["colors"]
+    tile_framebuffers: list[TileFramebuffers] = field(default_factory=list)
 
 
 @dataclass
@@ -215,6 +244,7 @@ class DeviceState:
         "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"),
+        "tile_framebuffers": "matrix",
     }
 
     # Default values for optional state attributes when state object is None
@@ -240,6 +270,7 @@ class DeviceState:
         "tile_effect_sky_type": 0,
         "tile_effect_cloud_sat_min": 0,
         "tile_effect_cloud_sat_max": 0,
+        "tile_framebuffers": [],
     }
 
     def get_target_bytes(self) -> bytes:

{lifx_emulator-2.2.1 → lifx_emulator-2.3.0}/src/lifx_emulator/handlers/tile_handlers.py

@@ -12,6 +12,7 @@ from lifx_emulator.protocol.protocol_types import (
     DeviceStateVersion,
     LightHsbk,
     TileAccelMeas,
+    TileBufferRect,
     TileEffectParameter,
     TileEffectSettings,
     TileEffectType,
@@ -137,6 +138,10 @@ class Get64Handler(PacketHandler):
         tile_width = tile["width"]
         tile_height = tile["height"]
 
+        # Get64 always returns framebuffer 0 (the visible buffer)
+        # regardless of which fb_index is in the request
+        tile_colors = tile["colors"]
+
         # Calculate how many rows fit in 64 pixels
         rows_to_return = 64 // rect.width if rect.width > 0 else 1
         rows_to_return = min(rows_to_return, tile_height - rect.y)
@@ -161,8 +166,8 @@ class Get64Handler(PacketHandler):
 
                 # Calculate pixel index in flat color array
                 pixel_idx = y * tile_width + x
-                if pixel_idx < len(tile["colors"]):
-                    colors.append(tile["colors"][pixel_idx])
+                if pixel_idx < len(tile_colors):
+                    colors.append(tile_colors[pixel_idx])
                 else:
                     colors.append(
                         LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500)
@@ -173,7 +178,14 @@ class Get64Handler(PacketHandler):
         while len(colors) < 64:
             colors.append(LightHsbk(hue=0, saturation=0, brightness=0, kelvin=3500))
 
-        return [Tile.State64(tile_index=tile_index, rect=rect, colors=colors)]
+        # Return with fb_index forced to 0 (visible buffer)
+        return_rect = TileBufferRect(
+            fb_index=0,  # Always return FB0
+            x=rect.x,
+            y=rect.y,
+            width=rect.width,
+        )
+        return [Tile.State64(tile_index=tile_index, rect=return_rect, colors=colors)]
 
 
 class Set64Handler(PacketHandler):
@@ -188,16 +200,60 @@ class Set64Handler(PacketHandler):
             return []
 
         tile_index = packet.tile_index
+        fb_index = packet.rect.fb_index
 
-        if tile_index < len(device_state.tile_devices):
-            # Update colors from packet
-            for i, color in enumerate(packet.colors[:64]):
-                if i < len(device_state.tile_devices[tile_index]["colors"]):
-                    device_state.tile_devices[tile_index]["colors"][i] = color
+        if tile_index >= len(device_state.tile_devices):
+            return []
 
-            logger.info(
-                f"Tile {tile_index} set 64 colors, duration={packet.duration}ms"
-            )
+        tile = device_state.tile_devices[tile_index]
+        tile_width = tile["width"]
+        tile_height = tile["height"]
+        rect = packet.rect
+
+        # Determine which framebuffer to update
+        if fb_index == 0:
+            # Update visible framebuffer (stored in tile_devices)
+            target_colors = tile["colors"]
+        else:
+            # Update non-visible framebuffer (stored in tile_framebuffers)
+            if tile_index < len(device_state.tile_framebuffers):
+                fb_storage = device_state.tile_framebuffers[tile_index]
+                target_colors = fb_storage.get_framebuffer(
+                    fb_index, tile_width, tile_height
+                )
+            else:
+                logger.warning(f"Tile {tile_index} framebuffer storage not initialized")
+                return []
+
+        # Update colors in the specified rectangle
+        # Calculate how many rows fit in 64 pixels
+        rows_to_write = 64 // rect.width if rect.width > 0 else 1
+        rows_to_write = min(rows_to_write, tile_height - rect.y)
+
+        pixels_written = 0
+        for row in range(rows_to_write):
+            y = rect.y + row
+            if y >= tile_height:
+                break
+
+            for col in range(rect.width):
+                x = rect.x + col
+                if x >= tile_width or pixels_written >= 64:
+                    pixels_written += 1
+                    continue
+
+                # Calculate pixel index in flat color array
+                pixel_idx = y * tile_width + x
+                if pixel_idx < len(target_colors) and pixels_written < len(
+                    packet.colors
+                ):
+                    target_colors[pixel_idx] = packet.colors[pixels_written]
+                pixels_written += 1
+
+        logger.info(
+            f"Tile {tile_index} FB{fb_index} set {pixels_written} colors at "
+            f"({rect.x},{rect.y}), duration={packet.duration}ms"
+        )
 
         # Tiles never return a response to Set64 regardless of res_required
         # https://lan.developer.lifx.com/docs/changing-a-device#set64---packet-715
@@ -212,12 +268,83 @@ class CopyFrameBufferHandler(PacketHandler):
     def handle(
         self, device_state: DeviceState, packet: Any | None, res_required: bool
     ) -> list[Any]:
-        if not device_state.has_matrix:
+        if not device_state.has_matrix or not packet:
+            return []
+
+        tile_index = packet.tile_index
+        if tile_index >= len(device_state.tile_devices):
             return []
 
-        logger.debug("Tile copy frame buffer command received (no-op in emulator)")
-        # In a real device, this would copy the frame buffer to display
-        # In emulator, we don't need to do anything special
+        tile = device_state.tile_devices[tile_index]
+        tile_width = tile["width"]
+        tile_height = tile["height"]
+
+        src_fb_index = packet.src_fb_index
+        dst_fb_index = packet.dst_fb_index
+
+        # Get source framebuffer
+        if src_fb_index == 0:
+            src_colors = tile["colors"]
+        else:
+            if tile_index < len(device_state.tile_framebuffers):
+                fb_storage = device_state.tile_framebuffers[tile_index]
+                src_colors = fb_storage.get_framebuffer(
+                    src_fb_index, tile_width, tile_height
+                )
+            else:
+                logger.warning(f"Tile {tile_index} framebuffer storage not initialized")
+                return []
+
+        # Get destination framebuffer
+        if dst_fb_index == 0:
+            dst_colors = tile["colors"]
+        else:
+            if tile_index < len(device_state.tile_framebuffers):
+                fb_storage = device_state.tile_framebuffers[tile_index]
+                dst_colors = fb_storage.get_framebuffer(
+                    dst_fb_index, tile_width, tile_height
+                )
+            else:
+                logger.warning(f"Tile {tile_index} framebuffer storage not initialized")
+                return []
+
+        # Copy the specified rectangle from source to destination
+        src_x = packet.src_x
+        src_y = packet.src_y
+        dst_x = packet.dst_x
+        dst_y = packet.dst_y
+        width = packet.width
+        height = packet.height
+
+        pixels_copied = 0
+        for row in range(height):
+            src_row = src_y + row
+            dst_row = dst_y + row
+
+            if src_row >= tile_height or dst_row >= tile_height:
+                break
+
+            for col in range(width):
+                src_col = src_x + col
+                dst_col = dst_x + col
+
+                if src_col >= tile_width or dst_col >= tile_width:
+                    continue
+
+                src_idx = src_row * tile_width + src_col
+                dst_idx = dst_row * tile_width + dst_col
+
+                if src_idx < len(src_colors) and dst_idx < len(dst_colors):
+                    dst_colors[dst_idx] = src_colors[src_idx]
+                    pixels_copied += 1
+
+        logger.info(
+            f"Tile {tile_index} copied {pixels_copied} pixels from "
+            f"FB{src_fb_index}({src_x},{src_y}) to "
+            f"FB{dst_fb_index}({dst_x},{dst_y}), "
+            f"size={width}x{height}, duration={packet.duration}ms"
+        )
+
         return []