lifx-async 4.2.0__tar.gz → 4.3.0__tar.gz

{lifx_async-4.2.0 → lifx_async-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-async
-Version: 4.2.0
+Version: 4.3.0
 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.2.0 → lifx_async-4.3.0}/docs/api/devices.md

@@ -214,32 +214,57 @@ async def main():
 ### MultiZone Control
 
 ```python
-from lifx import find_lights, Colors
+from lifx import MultiZoneLight, Colors, FirmwareEffect, Direction
 
 
 async def main():
-    async with find_lights() as lights:
-        for light in lights:
-            # Get all zones - automatically uses best method
-            colors = await light.get_all_color_zones()
-            print(f"Device has {len(colors)} zones")
-
+    async with await MultiZoneLight.from_ip("192.168.1.100") as light:
+        # Get all zones - automatically uses best method
+        colors = await light.get_all_color_zones()
+        print(f"Device has {len(colors)} zones")
+
+        # Set a MOVE effect
+        await light.set_effect(
+            effect_type=FirmwareEffect.MOVE,
+            speed=5.0,  # seconds per cycle
+            direction=Direction.FORWARD,
+        )
+
+        # Get current effect
+        effect = await light.get_effect()
+        print(f"Effect: {effect.effect_type.name}")
+        if effect.effect_type == FirmwareEffect.MOVE:
+            print(f"Direction: {effect.direction.name}")
+
+        # Stop the effect
+        await light.set_effect(effect_type=FirmwareEffect.OFF)
 ```
 
 ### Tile Control
 
 ```python
-from lifx import find_lights, HSBK
+from lifx import MatrixLight, HSBK, FirmwareEffect
 
 
 async def main():
-    async with find_lights() as lights:
-        for light in lights:
-            if light.has_matrix:
-                # Set a gradient across the tile
-                colors = [
-                    HSBK(hue=h, saturation=1.0, brightness=0.5, kelvin=3500)
-                    for h in range(0, 360, 10)
-                ]
-                await light.set_tile_colors(colors)
+    async with await MatrixLight.from_ip("192.168.1.100") as light:
+        # Set a gradient across the tile
+        colors = [
+            HSBK(hue=h, saturation=1.0, brightness=0.5, kelvin=3500)
+            for h in range(0, 360, 10)
+        ]
+        await light.set_tile_colors(colors)
+
+        # Set a tile effect (MORPH, FLAME, or SKY)
+        await light.set_effect(
+            effect_type=FirmwareEffect.FLAME,
+            speed=5.0,  # seconds per cycle
+        )
+
+        # Get current effect
+        effect = await light.get_effect()
+        print(f"Tile effect: {effect.effect_type.name}")
+
+        # Stop the effect
+        await light.set_effect(effect_type=FirmwareEffect.OFF)
 ```

{lifx_async-4.2.0 → lifx_async-4.3.0}/docs/api/protocol.md

@@ -79,17 +79,21 @@ Common protocol type definitions and enums.
       heading_level: 4
       members_order: source
 
-### MultiZone Effect Type
+### Firmware Effect
 
-::: lifx.protocol.protocol_types.MultiZoneEffectType
+Unified enum for all firmware effects (multizone and matrix devices):
+
+::: lifx.protocol.protocol_types.FirmwareEffect
     options:
       show_root_heading: true
       heading_level: 4
       members_order: source
 
-### Tile Effect Type
+### Direction
+
+Direction enum for MOVE effects:
 
-::: lifx.protocol.protocol_types.TileEffectType
+::: lifx.protocol.protocol_types.Direction
     options:
       show_root_heading: true
       heading_level: 4
@@ -313,6 +317,23 @@ LightWaveform.TRIANGLE
 LightWaveform.PULSE
 ```
 
+### Firmware Effects
+
+```python
+from lifx.protocol.protocol_types import FirmwareEffect, Direction
+
+# Available firmware effects (for multizone and matrix devices)
+FirmwareEffect.OFF
+FirmwareEffect.MOVE       # MultiZone only
+FirmwareEffect.MORPH      # Tile/Matrix only
+FirmwareEffect.FLAME      # Tile/Matrix only
+FirmwareEffect.SKY        # Tile/Matrix only
+
+# Direction for MOVE effects
+Direction.FORWARD   # Move forward through zones
+Direction.REVERSED  # Move backward through zones
+```
+
 ## Product Registry
 
 The product registry provides automatic device type detection and capability information:

{lifx_async-4.2.0 → lifx_async-4.3.0}/docs/changelog.md

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v4.3.0 (2025-11-22)
+
+### Features
+
+- **effects**: Unify effect enums and simplify API
+  ([`df1c3c8`](https://github.com/Djelibeybi/lifx-async/commit/df1c3c8ba63dbf6cbfa5b973cdfe648c100a1371))
+
+
+## v4.2.1 (2025-11-21)
+
+### Bug Fixes
+
+- Get_wifi_info now returns signal and rssi correctly
+  ([`6db03b3`](https://github.com/Djelibeybi/lifx-async/commit/6db03b334a36de6faa1b9749f545f3775a01d7dd))
+
+
 ## v4.2.0 (2025-11-21)
 
 ### Documentation

lifx_async-4.3.0/docs/migration/effect-api-changes.md

@@ -0,0 +1,245 @@
+# Effect API Changes (v4.3.0)
+
+This document describes changes to the effect handling API introduced in version 4.3.0.
+
+## Overview
+
+The effect handling API has been simplified and unified to provide a cleaner, more consistent interface:
+
+1. **Unified Effect Enum**: `MultiZoneEffectType` and `TileEffectType` merged into `FirmwareEffect`
+2. **Direction Enum**: New `Direction` enum for MOVE effect direction control
+3. **Simplified Methods**: Effect methods renamed for clarity (`set_effect`, `get_effect`)
+4. **Unified Application Request**: `MultiZoneExtendedApplicationRequest` removed in favor of single `MultiZoneApplicationRequest`
+
+## Changes
+
+### 1. Effect Type Enums Consolidated
+
+**Before:**
+```python
+from lifx import MultiZoneEffectType, TileEffectType
+
+# MultiZone effects
+effect = MultiZoneEffectType.MOVE
+
+# Tile effects
+effect = TileEffectType.MORPH
+```
+
+**After:**
+```python
+from lifx import FirmwareEffect
+
+# All firmware effects (multizone and matrix)
+effect = FirmwareEffect.MOVE   # MultiZone
+effect = FirmwareEffect.MORPH  # Matrix/Tile
+effect = FirmwareEffect.FLAME  # Matrix/Tile
+effect = FirmwareEffect.SKY    # Matrix/Tile
+```
+
+### 2. Direction Control for MOVE Effects
+
+**Before:**
+```python
+# Direction was embedded in specialized methods
+await light.set_move_effect(speed=5.0, direction=1)  # 0=reversed, 1=forward
+```
+
+**After:**
+```python
+from lifx import FirmwareEffect, Direction
+
+# Direction is a proper enum with named values
+await light.set_effect(
+    effect_type=FirmwareEffect.MOVE,
+    speed=5.0,
+    direction=Direction.FORWARD,  # or Direction.REVERSED
+)
+
+# Direction can also be accessed as a property on MultiZoneEffect
+effect = await light.get_effect()
+if effect.effect_type == FirmwareEffect.MOVE:
+    print(f"Direction: {effect.direction.name}")  # FORWARD or REVERSED
+```
+
+### 3. Method Naming Simplified
+
+**Before:**
+```python
+# MultiZone devices
+await multizone_light.set_multizone_effect(...)
+effect = await multizone_light.get_multizone_effect()
+
+# Tile/Matrix devices
+await matrix_light.set_tile_effect(...)
+effect = await matrix_light.get_tile_effect()
+
+# Specialized MOVE method
+await multizone_light.set_move_effect(speed=5.0, direction=1)
+```
+
+**After:**
+```python
+# Unified naming across all device types
+await multizone_light.set_effect(effect_type=FirmwareEffect.MOVE, ...)
+effect = await multizone_light.get_effect()
+
+await matrix_light.set_effect(effect_type=FirmwareEffect.FLAME, ...)
+effect = await matrix_light.get_effect()
+
+# No more specialized methods - use set_effect with Direction enum
+```
+
+### 4. Application Request Enum Unified
+
+**Before:**
+```python
+from lifx import MultiZoneApplicationRequest, MultiZoneExtendedApplicationRequest
+
+# Different enums for different packet types
+await light.set_color_zones(..., apply=MultiZoneApplicationRequest.APPLY)
+await light.set_extended_color_zones(..., apply=MultiZoneExtendedApplicationRequest.APPLY)
+```
+
+**After:**
+```python
+from lifx import MultiZoneApplicationRequest
+
+# Single enum for all multizone application control
+await light.set_color_zones(..., apply=MultiZoneApplicationRequest.APPLY)
+await light.set_extended_color_zones(..., apply=MultiZoneApplicationRequest.APPLY)
+```
+
+## Migration Guide
+
+### Updating MultiZone Effect Code
+
+**Old Code:**
+```python
+from lifx import MultiZoneLight, MultiZoneEffectType
+
+async with await MultiZoneLight.from_ip("192.168.1.100") as light:
+    # Old API
+    await light.set_multizone_effect(
+        effect_type=MultiZoneEffectType.MOVE,
+        speed=5.0,
+    )
+
+    # Or using specialized method
+    await light.set_move_effect(speed=5.0, direction=1)
+
+    effect = await light.get_multizone_effect()
+```
+
+**New Code:**
+```python
+from lifx import MultiZoneLight, FirmwareEffect, Direction
+
+async with await MultiZoneLight.from_ip("192.168.1.100") as light:
+    # New unified API
+    await light.set_effect(
+        effect_type=FirmwareEffect.MOVE,
+        speed=5.0,
+        direction=Direction.FORWARD,
+    )
+
+    effect = await light.get_effect()
+    if effect.effect_type == FirmwareEffect.MOVE:
+        print(f"Direction: {effect.direction.name}")
+```
+
+### Updating Matrix/Tile Effect Code
+
+**Old Code:**
+```python
+from lifx import MatrixLight, TileEffectType
+
+async with await MatrixLight.from_ip("192.168.1.100") as light:
+    # Old API
+    await light.set_tile_effect(
+        effect_type=TileEffectType.FLAME,
+        speed=5.0,
+    )
+
+    effect = await light.get_tile_effect()
+```
+
+**New Code:**
+```python
+from lifx import MatrixLight, FirmwareEffect
+
+async with await MatrixLight.from_ip("192.168.1.100") as light:
+    # New unified API
+    await light.set_effect(
+        effect_type=FirmwareEffect.FLAME,
+        speed=5.0,
+    )
+
+    effect = await light.get_effect()
+```
+
+### Updating Application Request Code
+
+**Old Code:**
+```python
+from lifx import MultiZoneApplicationRequest, MultiZoneExtendedApplicationRequest
+
+# Standard zones
+await light.set_color_zones(
+    start=0,
+    end=9,
+    color=color,
+    apply=MultiZoneApplicationRequest.APPLY,
+)
+
+# Extended zones
+await light.set_extended_color_zones(
+    zone_index=0,
+    colors=colors,
+    apply=MultiZoneExtendedApplicationRequest.APPLY,
+)
+```
+
+**New Code:**
+```python
+from lifx import MultiZoneApplicationRequest
+
+# Standard zones
+await light.set_color_zones(
+    start=0,
+    end=9,
+    color=color,
+    apply=MultiZoneApplicationRequest.APPLY,
+)
+
+# Extended zones
+await light.set_extended_color_zones(
+    zone_index=0,
+    colors=colors,
+    apply=MultiZoneApplicationRequest.APPLY,  # Same enum
+)
+```
+
+## Summary of Removals
+
+The following have been **removed** in v4.3.0:
+
+- `lifx.protocol.protocol_types.MultiZoneEffectType` → use `FirmwareEffect`
+- `lifx.protocol.protocol_types.TileEffectType` → use `FirmwareEffect`
+- `lifx.protocol.protocol_types.MultiZoneExtendedApplicationRequest` → use `MultiZoneApplicationRequest`
+- `MultiZoneLight.set_multizone_effect()` → use `set_effect()`
+- `MultiZoneLight.get_multizone_effect()` → use `get_effect()`
+- `MultiZoneLight.set_move_effect()` → use `set_effect(effect_type=FirmwareEffect.MOVE, direction=Direction.FORWARD)`
+- `MultiZoneLight.get_move_effect()` → use `get_effect()` and access `effect.direction`
+- `MatrixLight.set_tile_effect()` → use `set_effect()`
+- `MatrixLight.get_tile_effect()` → use `get_effect()`
+
+## Benefits
+
+These changes provide several improvements:
+
+1. **Consistency**: All firmware effects use the same enum and method names
+2. **Type Safety**: Direction is now a proper enum instead of integer values (0/1)
+3. **Discoverability**: Cleaner API with fewer specialized methods
+4. **Simplicity**: One enum for application requests instead of two identical ones
+5. **Maintainability**: Easier to extend with new effect types in the future

{lifx_async-4.2.0 → lifx_async-4.3.0}/mkdocs.yml

@@ -148,6 +148,8 @@ plugins:
       - api/network.md: Network layer components
       - api/protocol.md: Protocol layer and packet structures
       - api/exceptions.md: Exception hierarchy
+      Migration:
+      - migration/effect-api-changes.md: Effect API breaking changes and migration guide
       Additional Resources:
       - faq.md: Frequently asked questions
       - changelog.md: Version history and release notes
@@ -215,6 +217,8 @@ nav:
   - Network Layer: api/network.md
   - Protocol Layer: api/protocol.md
   - Exceptions: api/exceptions.md
+- Migration:
+  - Effect API Changes: migration/effect-api-changes.md
 - FAQ: faq.md
 - Changelog: changelog.md
 

{lifx_async-4.2.0 → lifx_async-4.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lifx-async"
-version = "4.2.0"
+version = "4.3.0"
 description = "A modern, type-safe, async Python library for controlling LIFX lights"
 readme = "README.md"
 requires-python = ">=3.11"

{lifx_async-4.2.0 → lifx_async-4.3.0}/src/lifx/__init__.py

@@ -43,9 +43,9 @@ from lifx.exceptions import (
 from lifx.network.discovery import DiscoveredDevice, discover_devices
 from lifx.products import ProductCapability, ProductInfo, ProductRegistry
 from lifx.protocol.protocol_types import (
+    Direction,
+    FirmwareEffect,
     LightWaveform,
-    MultiZoneEffectType,
-    TileEffectType,
 )
 from lifx.theme import Theme, ThemeLibrary, get_theme
 
@@ -98,8 +98,8 @@ __all__ = [
     "ProductCapability",
     # Protocol types
     "LightWaveform",
-    "MultiZoneEffectType",
-    "TileEffectType",
+    "FirmwareEffect",
+    "Direction",
     # Exceptions
     "LifxError",
     "LifxDeviceNotFoundError",

{lifx_async-4.2.0 → lifx_async-4.3.0}/src/lifx/devices/base.py

@@ -7,7 +7,8 @@ import ipaddress
 import logging
 import time
 import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from math import floor, log10
 from typing import Self
 
 from lifx.const import (
@@ -60,14 +61,16 @@ class WifiInfo:
     """Device WiFi module information.
 
     Attributes:
-        signal: WiFi signal strength (mW)
-        tx: Bytes transmitted since power on
-        rx: Bytes received since power on
+        signal: WiFi signal strength
+        rssi: WiFi RSSI
     """
 
     signal: float
-    tx: int
-    rx: int
+    rssi: int = field(init=False)
+
+    def __post_init__(self) -> None:
+        """Calculate RSSI from signal."""
+        self.rssi = int(floor(10 * log10(self.signal) + 0.5))
 
 
 @dataclass
@@ -677,7 +680,7 @@ class Device:
         Always fetches from device.
 
         Returns:
-            WifiInfo with signal strength and network stats
+            WifiInfo with signal strength and RSSI
 
         Raises:
             LifxDeviceNotFoundError: If device is not connected
@@ -687,22 +690,22 @@ class Device:
         Example:
             ```python
             wifi_info = await device.get_wifi_info()
-            print(f"WiFi signal: {wifi_info.signal} mW")
-            print(f"TX: {wifi_info.tx} bytes, RX: {wifi_info.rx} bytes")
+            print(f"WiFi signal: {wifi_info.signal}")
+            print(f"WiFi RSSI: {wifi_info.rssi}")
             ```
         """
         # Request WiFi info from device
         state = await self.connection.request(packets.Device.GetWifiInfo())
 
         # Extract WiFi info from response
-        wifi_info = WifiInfo(signal=state.signal, tx=state.tx, rx=state.rx)
+        wifi_info = WifiInfo(signal=state.signal)
 
         _LOGGER.debug(
             {
                 "class": "Device",
                 "method": "get_wifi_info",
                 "action": "query",
-                "reply": {"signal": state.signal, "tx": state.tx, "rx": state.rx},
+                "reply": {"signal": state.signal},
             }
         )
         return wifi_info

{lifx_async-4.2.0 → lifx_async-4.3.0}/src/lifx/devices/matrix.py

@@ -23,12 +23,12 @@ if TYPE_CHECKING:
 from lifx.devices.light import Light
 from lifx.protocol import packets
 from lifx.protocol.protocol_types import (
+    FirmwareEffect,
     LightHsbk,
     TileBufferRect,
     TileEffectParameter,
     TileEffectSettings,
     TileEffectSkyType,
-    TileEffectType,
 )
 from lifx.protocol.protocol_types import (
     TileStateDevice as LifxProtocolTileDevice,
@@ -161,7 +161,7 @@ class MatrixEffect:
         cloud_saturation_max: Maximum cloud saturation (0-255, for CLOUDS sky type)
     """
 
-    effect_type: TileEffectType
+    effect_type: FirmwareEffect
     speed: int
     duration: int = 0
     palette: list[HSBK] | None = None
@@ -178,7 +178,7 @@ class MatrixEffect:
 
         # Validate all fields
         # Speed can be 0 only when effect is OFF
-        if self.effect_type != TileEffectType.OFF:
+        if self.effect_type != FirmwareEffect.OFF:
             self._validate_speed_active(self.speed)
         elif self.speed < 0:
             raise ValueError(f"Effect speed must be non-negative, got {self.speed}")
@@ -190,7 +190,7 @@ class MatrixEffect:
 
         # Apply cloud saturation defaults only for CLOUDS sky type
         if (
-            self.effect_type == TileEffectType.SKY
+            self.effect_type == FirmwareEffect.SKY
             and self.sky_type == TileEffectSkyType.CLOUDS
         ):
             # Apply sensible defaults for cloud saturation if not specified
@@ -722,7 +722,7 @@ class MatrixLight(Light):
 
     async def set_tile_effect(
         self,
-        effect_type: TileEffectType,
+        effect_type: FirmwareEffect,
         speed: int = 3000,
         duration: int = 0,
         palette: list[HSBK] | None = None,
@@ -750,7 +750,7 @@ class MatrixLight(Light):
             ...     HSBK(240, 1.0, 1.0, 3500),  # Blue
             ... ]
             >>> await matrix.set_tile_effect(
-            ...     effect_type=TileEffectType.MORPH,
+            ...     effect_type=FirmwareEffect.MORPH,
             ...     speed=5000,
             ...     palette=rainbow,
             ... )