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

{lifx_async-4.0.2 → lifx_async-4.2.0}/CLAUDE.md

@@ -209,7 +209,7 @@ except LifxDeviceNotFoundError:
 **Current Behavior**:
 - Selected properties cache static/semi-static values to reduce network requests
 - Cached properties: `label`, `version`, `host_firmware`, `wifi_firmware`, `location`, `group`, `hev_config`, `hev_result`, `zone_count`, `multizone_effect`, `tile_chain`, `tile_count`, `tile_effect`
-- Volatile state (power, color, hev_cycle, zones, tile_colors) is **not** cached - always use `get_*()` methods to fetch fresh data
+- Volatile state (power, color, hev_cycle, zones, tile_colors, ambient_light_level) is **not** cached - always use `get_*()` methods to fetch fresh data
 - Use `get_*()` methods to fetch fresh data from devices for any property
 - No automatic expiration - application controls when to refresh
 - Use `get_color()` to retrieve color, power, and label values as two of the three are volatile and it returns all three in a single request/response pair.
@@ -228,7 +228,7 @@ async with device:
     is_on = power_level > 0
 ```
 
-**Note**: Volatile state properties (`power`, `color`, `hev_cycle`, `zones`, `tile_colors`) were removed as they change too frequently to benefit from caching. Always fetch these values using `get_*()` methods.
+**Note**: Volatile state properties (`power`, `color`, `hev_cycle`, `zones`, `tile_colors`, `ambient_light_level`) were removed as they change too frequently to benefit from caching. Always fetch these values using `get_*()` methods.
 
 ## Common Patterns
 
@@ -404,6 +404,31 @@ async with await InfraredLight.from_ip("192.168.1.100") as light:
     print(f"IR brightness: {brightness * 100}%")
 ```
 
+### Ambient Light Sensor (Light Level Detection)
+
+Light devices with ambient light sensors can measure the current ambient light level in lux:
+
+```python
+from lifx.devices import Light
+
+async with await Light.from_ip("192.168.1.100") as light:
+    # Turn light off for accurate reading
+    await light.set_power(False)
+
+    # Get ambient light level in lux
+    lux = await light.get_ambient_light_level()
+    if lux > 0:
+        print(f"Ambient light: {lux} lux")
+    else:
+        print("No ambient light sensor or completely dark")
+```
+
+**Notes:**
+- This is a volatile property and is never cached - always fetched fresh from the device
+- Devices without ambient light sensors return 0.0 (not an error)
+- For accurate readings, the light should be off - otherwise the light's own illumination interferes with the sensor
+- A reading of 0.0 could mean either no sensor or complete darkness
+
 ### MultiZone Light Control (Strips and Beams)
 
 MultiZoneLight devices support zone-based color control:
@@ -695,6 +720,10 @@ Local generator quirks:
   - Unions starting with "Button" or "Relay" are excluded
   - All packets in "button" and "relay" categories are excluded
   - This keeps the library focused on LIFX lighting devices
+- **sensor packets**: Adds undocumented ambient light sensor packets:
+  - `SensorGetAmbientLight` (401): Request packet with no parameters
+  - `SensorStateAmbientLight` (402): Response packet with lux field (float32)
+  - These packets are not in the official protocol.yml but are supported by LIFX devices with ambient light sensors
 
 Run `uv run python -m lifx.protocol.generator` to regenerate Python code.
 

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

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

@@ -182,6 +182,35 @@ async def main():
         print(f"IR brightness: {brightness * 100}%")
 ```
 
+### Ambient Light Sensor
+
+Light devices with ambient light sensors can measure the current ambient light level in lux:
+
+```python
+from lifx import Light
+
+
+async def main():
+    async with await Light.from_ip("192.168.1.100") as light:
+        # Ensure light is off for accurate reading
+        await light.set_power(False)
+
+        # Get ambient light level in lux
+        lux = await light.get_ambient_light_level()
+        if lux > 0:
+            print(f"Ambient light: {lux} lux")
+        else:
+            print("No ambient light sensor or completely dark")
+```
+
+**Notes:**
+
+- Devices without ambient light sensors return 0.0 (not an error)
+- For accurate readings, the light should be turned off (otherwise the light's own illumination interferes with the sensor)
+- This is a volatile property - always fetched fresh from the device
+- A reading of 0.0 could mean either no sensor or complete darkness
+- Returns ambient light level in lux (higher values indicate brighter ambient light)
+
 ### MultiZone Control
 
 ```python

{lifx_async-4.0.2 → lifx_async-4.2.0}/docs/api/network.md

@@ -31,17 +31,6 @@ Low-level UDP transport for sending and receiving LIFX protocol messages.
       filters:
         - "!^_"
 
-## Message Building
-
-Utilities for building and parsing LIFX protocol messages.
-
-::: lifx.network.message.MessageBuilder
-    options:
-      show_root_heading: true
-      heading_level: 3
-      members_order: source
-      show_if_no_docstring: false
-
 ## Examples
 
 ### Device Discovery

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

@@ -2,6 +2,27 @@
 
 <!-- version list -->
 
+## v4.2.0 (2025-11-21)
+
+### Documentation
+
+- **api**: Remove obsolete reference to MessageBuilder
+  ([`9847948`](https://github.com/Djelibeybi/lifx-async/commit/98479483d00c875e324d5a7dcd88bf08f11f73cb))
+
+### Features
+
+- **devices**: Add ambient light sensor support
+  ([`75f0673`](https://github.com/Djelibeybi/lifx-async/commit/75f0673dc9b6e8bce30a5b5958215a600925357e))
+
+
+## v4.1.0 (2025-11-20)
+
+### Features
+
+- **network**: Replace polling architecture with event-driven background receiver
+  ([`9862eac`](https://github.com/Djelibeybi/lifx-async/commit/9862eac1eea162fa66bf19d277a3772de7c70db1))
+
+
 ## v4.0.2 (2025-11-19)
 
 ### Bug Fixes

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

@@ -1,6 +1,6 @@
 [project]
 name = "lifx-async"
-version = "4.0.2"
+version = "4.2.0"
 description = "A modern, type-safe, async Python library for controlling LIFX lights"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,7 +31,7 @@ classifiers = [
 [dependency-groups]
 dev = [
     "hatchling>=1.27.0",
-    "lifx-emulator>=2.3.1",
+    "lifx-emulator>=2.4.0",
     "mkdocs-git-revision-date-localized-plugin>=1.4.7",
     "mkdocs-llmstxt>=0.4.0",
     "mkdocs-material>=9.6.22",

{lifx_async-4.0.2 → lifx_async-4.2.0}/src/lifx/color.py

@@ -119,30 +119,6 @@ class HSBK:
         self._brightness = brightness
         self._kelvin = kelvin
 
-    def __lt__(self, other: object) -> bool:
-        """A color is less than another color if it has lower HSBK values."""
-        if not isinstance(other, HSBK):  # pragma: no cover
-            return NotImplemented
-
-        return (self.hue, self.saturation, self.brightness, self.kelvin) < (
-            other.hue,
-            other.saturation,
-            other.brightness,
-            other.kelvin,
-        )
-
-    def __gt__(self, other: object) -> bool:
-        """A color is more than another color if it has higher HSBK values."""
-        if not isinstance(other, HSBK):  # pragma: no cover
-            return NotImplemented
-
-        return (self.hue, self.saturation, self.brightness, self.kelvin) > (
-            other.hue,
-            other.saturation,
-            other.brightness,
-            other.kelvin,
-        )
-
     def __eq__(self, other: object) -> bool:
         """Two colors are equal if they have the same HSBK values."""
         if not isinstance(other, HSBK):  # pragma: no cover

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

@@ -355,39 +355,24 @@ class Device:
             tg.create_task(self.get_location())
             tg.create_task(self.get_group())
 
-    def _calculate_mac_address(self) -> None:
-        """Calculate MAC address from serial and host firmware version.
-
-        The MAC address calculation depends on the major version of the host firmware:
-        - Version 2 or 4: MAC address matches the serial
-        - Version 3: MAC address is serial with LSB + 1 (with wraparound from FF to 00)
-        - Unknown versions: Default to serial
-
-        This method is called automatically when host firmware is fetched.
-        """
-        if self._host_firmware is None:  # pragma: no cover
-            return
-
-        # Get serial bytes
-        serial_obj = Serial.from_string(self.serial)
-        serial_bytes = bytearray(serial_obj.value)
+    async def get_mac_address(self) -> str:
+        """Calculate and return the MAC address for this device."""
+        if self._mac_address is None:
+            firmware = (
+                self._host_firmware
+                if self._host_firmware is not None
+                else await self.get_host_firmware()
+            )
+            octets = [
+                int(self.serial[i : i + 2], 16) for i in range(0, len(self.serial), 2)
+            ]
 
-        # Check firmware major version
-        major_version = self._host_firmware.version_major
+            if firmware.version_major == 3:
+                octets[5] = (octets[5] + 1) % 256
 
-        if major_version in (2, 4):
-            # MAC address matches serial
-            mac_bytes = bytes(serial_bytes)
-        elif major_version == 3:
-            # Add 1 to least significant byte (with wraparound)
-            serial_bytes[5] = (serial_bytes[5] + 1) % 256
-            mac_bytes = bytes(serial_bytes)
-        else:
-            # For unknown versions, default to serial
-            mac_bytes = bytes(serial_bytes)
+            self._mac_address = ":".join(f"{octet:02x}" for octet in octets)
 
-        # Convert to colon-separated hex string format (e.g., "d0:73:d5:01:02:03")
-        self._mac_address = ":".join(f"{b:02x}" for b in mac_bytes)
+        return self._mac_address
 
     async def _ensure_capabilities(self) -> None:
         """Ensure device capabilities are populated.
@@ -753,7 +738,8 @@ class Device:
         self._host_firmware = firmware
 
         # Calculate MAC address now that we have firmware info
-        self._calculate_mac_address()
+        if self.mac_address is None:
+            await self.get_mac_address()
 
         _LOGGER.debug(
             {

{lifx_async-4.0.2 → lifx_async-4.2.0}/src/lifx/devices/light.py

@@ -379,6 +379,45 @@ class Light(Device):
 
         return state.level
 
+    async def get_ambient_light_level(self) -> float:
+        """Get ambient light level from device sensor.
+
+        Always fetches from device (volatile property, not cached).
+
+        This method queries the device's ambient light sensor to get the current
+        lux reading. Devices without ambient light sensors will return 0.0.
+
+        Returns:
+            Ambient light level in lux (0.0 if device has no sensor)
+
+        Raises:
+            LifxDeviceNotFoundError: If device is not connected
+            LifxTimeoutError: If device does not respond
+            LifxProtocolError: If response is invalid
+
+        Example:
+            ```python
+            lux = await light.get_ambient_light_level()
+            if lux > 0:
+                print(f"Ambient light: {lux} lux")
+            else:
+                print("No ambient light sensor or completely dark")
+            ```
+        """
+        # Request automatically unpacks response
+        state = await self.connection.request(packets.Sensor.GetAmbientLight())
+
+        _LOGGER.debug(
+            {
+                "class": "Light",
+                "method": "get_ambient_light_level",
+                "action": "query",
+                "reply": {"lux": state.lux},
+            }
+        )
+
+        return state.lux
+
     async def set_power(self, level: bool | int, duration: float = 0.0) -> None:
         """Set light power state (specific to light, not device).
 

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

@@ -285,12 +285,7 @@ class MatrixLight(Light):
         ...     await matrix.set64(tile_index=0, colors=colors, width=8)
     """
 
-    def __init__(
-        self,
-        serial: str,
-        ip: str,
-        port: int = 56700,
-    ) -> None:
+    def __init__(self, *args, **kwargs) -> None:
         """Initialize MatrixLight device.
 
         Args:
@@ -298,7 +293,8 @@ class MatrixLight(Light):
             ip: Device IP address
             port: Device port (default: 56700)
         """
-        super().__init__(serial, ip, port)
+        super().__init__(*args, **kwargs)
+        # Matrix specific properties
         self._device_chain: list[TileInfo] | None = None
         self._tile_effect: MatrixEffect | None = None
 

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

@@ -2,14 +2,13 @@
 
 from lifx.network.connection import DeviceConnection
 from lifx.network.discovery import DiscoveredDevice, discover_devices
-from lifx.network.message import MessageBuilder, create_message, parse_message
+from lifx.network.message import create_message, parse_message
 from lifx.network.transport import UdpTransport
 
 __all__ = [
     # Transport
     "UdpTransport",
     # Message
-    "MessageBuilder",
     "create_message",
     "parse_message",
     # Discovery