lifx-async 4.7.5__py3-none-any.whl → 4.8.0__py3-none-any.whl

lifx/__init__.py

@@ -10,6 +10,7 @@ from importlib.metadata import version as get_version
 from lifx.api import (
     DeviceGroup,
     discover,
+    discover_mdns,
     find_by_ip,
     find_by_label,
     find_by_serial,
@@ -48,6 +49,7 @@ from lifx.exceptions import (
     LifxUnsupportedCommandError,
 )
 from lifx.network.discovery import DiscoveredDevice, discover_devices
+from lifx.network.mdns import LifxServiceRecord, discover_lifx_services
 from lifx.products import ProductCapability, ProductInfo, ProductRegistry
 from lifx.protocol.protocol_types import (
     Direction,
@@ -100,12 +102,16 @@ __all__ = [
     # High-level API
     "DeviceGroup",
     "discover",
+    "discover_mdns",
     "find_by_serial",
     "find_by_label",
     "find_by_ip",
     # Discovery (low-level)
     "discover_devices",
     "DiscoveredDevice",
+    # mDNS Discovery (low-level)
+    "discover_lifx_services",
+    "LifxServiceRecord",
     # Products
     "ProductInfo",
     "ProductRegistry",

lifx/api.py

@@ -803,6 +803,59 @@ async def discover(
             yield device
 
 
+async def discover_mdns(
+    timeout: float = DISCOVERY_TIMEOUT,
+    max_response_time: float = MAX_RESPONSE_TIME,
+    idle_timeout_multiplier: float = IDLE_TIMEOUT_MULTIPLIER,
+    device_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+) -> AsyncGenerator[Light, None]:
+    """Discover LIFX devices via mDNS and yield them as they are found.
+
+    Uses mDNS/DNS-SD discovery with the _lifx._udp.local service type.
+    This method is faster than broadcast discovery as device type information
+    is included in the mDNS TXT records, eliminating the need for additional
+    device queries.
+
+    Note: mDNS discovery requires the mDNS multicast group (224.0.0.251:5353)
+    to be accessible. Some network configurations may block multicast traffic.
+
+    Args:
+        timeout: Discovery timeout in seconds (default 15.0)
+        max_response_time: Max time to wait for responses
+        idle_timeout_multiplier: Idle timeout multiplier
+        device_timeout: request timeout set on discovered devices
+        max_retries: max retries per request set on discovered devices
+
+    Yields:
+        Device instances as they are discovered
+
+    Example:
+        ```python
+        # Process devices as they're discovered
+        async for device in discover_mdns():
+            print(f"Found: {device.serial}")
+            async with device:
+                await device.set_power(True)
+
+        # Or collect all devices first
+        devices = []
+        async for device in discover_mdns():
+            devices.append(device)
+        ```
+    """
+    from lifx.network.mdns.discovery import discover_devices_mdns
+
+    async for device in discover_devices_mdns(
+        timeout=timeout,
+        max_response_time=max_response_time,
+        idle_timeout_multiplier=idle_timeout_multiplier,
+        device_timeout=device_timeout,
+        max_retries=max_retries,
+    ):
+        yield device
+
+
 async def find_by_serial(
     serial: str,
     timeout: float = DISCOVERY_TIMEOUT,
@@ -996,6 +1049,7 @@ __all__ = [
     "LocationGrouping",
     "GroupGrouping",
     "discover",
+    "discover_mdns",
     "find_by_serial",
     "find_by_ip",
     "find_by_label",

lifx/const.py

@@ -38,6 +38,19 @@ STATE_REFRESH_DEBOUNCE_MS: Final[int] = 300
 # Default maximum number of retry attempts for failed requests
 DEFAULT_MAX_RETRIES: Final[int] = 8
 
+# ============================================================================
+# mDNS Constants
+# ============================================================================
+
+# mDNS multicast address (IPv4)
+MDNS_ADDRESS: Final[str] = "224.0.0.251"
+
+# mDNS port
+MDNS_PORT: Final[int] = 5353
+
+# LIFX mDNS service type
+LIFX_MDNS_SERVICE: Final[str] = "_lifx._udp.local"
+
 # ============================================================================
 # HSBK Min/Max Values
 # ============================================================================

lifx/network/mdns/__init__.py

@@ -0,0 +1,58 @@
+"""mDNS/DNS-SD discovery for LIFX devices.
+
+This module provides mDNS-based discovery using the _lifx._udp.local service type.
+It uses only Python stdlib (no external dependencies).
+
+Example:
+    Low-level API (raw mDNS records):
+    ```python
+    async for record in discover_lifx_services():
+        print(f"Found: {record.serial} at {record.ip}:{record.port}")
+    ```
+
+    High-level API (device instances):
+    ```python
+    async for device in discover_devices_mdns():
+        print(f"Found {type(device).__name__}: {device.serial}")
+    ```
+"""
+
+from lifx.network.mdns.discovery import (
+    create_device_from_record,
+    discover_devices_mdns,
+    discover_lifx_services,
+)
+from lifx.network.mdns.dns import (
+    DnsHeader,
+    DnsResourceRecord,
+    ParsedDnsResponse,
+    SrvData,
+    TxtData,
+    build_ptr_query,
+    parse_dns_response,
+    parse_name,
+    parse_txt_record,
+)
+from lifx.network.mdns.transport import MdnsTransport
+from lifx.network.mdns.types import LifxServiceRecord
+
+__all__ = [
+    # Types
+    "LifxServiceRecord",
+    # Discovery functions
+    "discover_lifx_services",
+    "discover_devices_mdns",
+    "create_device_from_record",
+    # DNS parsing
+    "DnsHeader",
+    "DnsResourceRecord",
+    "ParsedDnsResponse",
+    "SrvData",
+    "TxtData",
+    "build_ptr_query",
+    "parse_dns_response",
+    "parse_name",
+    "parse_txt_record",
+    # Transport
+    "MdnsTransport",
+]

lifx/network/mdns/discovery.py

@@ -0,0 +1,403 @@
+"""mDNS discovery for LIFX devices.
+
+This module provides discovery functions using mDNS/DNS-SD to find
+LIFX devices on the local network.
+
+Example:
+    Low-level API (raw service records):
+    ```python
+    async for record in discover_lifx_services():
+        print(f"Found: {record.serial} at {record.ip}:{record.port}")
+    ```
+
+    High-level API (device instances):
+    ```python
+    async for device in discover_devices_mdns():
+        async with device:
+            print(f"Found: {await device.get_label()}")
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING
+
+from lifx.const import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_REQUEST_TIMEOUT,
+    DISCOVERY_TIMEOUT,
+    IDLE_TIMEOUT_MULTIPLIER,
+    LIFX_MDNS_SERVICE,
+    MAX_RESPONSE_TIME,
+)
+from lifx.network.mdns.dns import (
+    DNS_TYPE_A,
+    DNS_TYPE_PTR,
+    DNS_TYPE_SRV,
+    DNS_TYPE_TXT,
+    SrvData,
+    TxtData,
+    build_ptr_query,
+    parse_dns_response,
+)
+from lifx.network.mdns.transport import MdnsTransport
+from lifx.network.mdns.types import LifxServiceRecord
+
+if TYPE_CHECKING:
+    from lifx.devices.light import Light
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _extract_lifx_info(
+    records: list,
+    source_ip: str,
+) -> LifxServiceRecord | None:
+    """Extract LIFX device info from mDNS records.
+
+    Args:
+        records: List of DnsResourceRecord from the response
+        source_ip: IP address the response came from
+
+    Returns:
+        LifxServiceRecord if valid LIFX device info found, None otherwise
+    """
+    # Find records of each type
+    srv_data: SrvData | None = None
+    txt_data: TxtData | None = None
+    a_record_ip: str | None = None
+
+    for record in records:
+        if record.rtype == DNS_TYPE_SRV and isinstance(record.parsed_data, SrvData):
+            srv_data = record.parsed_data
+        elif record.rtype == DNS_TYPE_TXT and isinstance(record.parsed_data, TxtData):
+            txt_data = record.parsed_data
+        elif record.rtype == DNS_TYPE_A and isinstance(record.parsed_data, str):
+            a_record_ip = record.parsed_data
+
+    # Need at least TXT record to identify the device
+    if txt_data is None:
+        return None
+
+    # Extract required fields from TXT record
+    serial = txt_data.pairs.get("id", "").lower()
+    product_id_str = txt_data.pairs.get("p", "")
+    firmware = txt_data.pairs.get("fw", "")
+
+    # Validate required fields
+    if not serial or not product_id_str:
+        return None
+
+    try:
+        product_id = int(product_id_str)
+    except ValueError:
+        return None
+
+    # Get port from SRV record or use default
+    port = srv_data.port if srv_data else 56700
+
+    # Get IP from A record or use source IP
+    ip = a_record_ip if a_record_ip else source_ip
+
+    return LifxServiceRecord(
+        serial=serial,
+        ip=ip,
+        port=port,
+        product_id=product_id,
+        firmware=firmware,
+    )
+
+
+def create_device_from_record(
+    record: LifxServiceRecord,
+    timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+) -> Light | None:
+    """Create appropriate device class based on product ID from mDNS record.
+
+    Uses the product registry to determine device capabilities and instantiate
+    the correct device class (Light, MatrixLight, MultiZoneLight, etc.).
+
+    Args:
+        record: LifxServiceRecord from mDNS discovery
+        timeout: Request timeout for the device
+        max_retries: Maximum retry attempts for requests
+
+    Returns:
+        Device instance of the appropriate type, or None if device should be skipped
+        (e.g., relay/button-only devices)
+
+    Example:
+        ```python
+        async for record in discover_lifx_services():
+            device = create_device_from_record(record)
+            if device:
+                async with device:
+                    print(f"Device: {await device.get_label()}")
+        ```
+    """
+    from lifx.devices.ceiling import CeilingLight
+    from lifx.devices.hev import HevLight
+    from lifx.devices.infrared import InfraredLight
+    from lifx.devices.light import Light
+    from lifx.devices.matrix import MatrixLight
+    from lifx.devices.multizone import MultiZoneLight
+    from lifx.products import get_product, is_ceiling_product
+
+    product = get_product(record.product_id)
+    kwargs = {
+        "serial": record.serial,
+        "ip": record.ip,
+        "port": record.port,
+        "timeout": timeout,
+        "max_retries": max_retries,
+    }
+
+    # Priority-based selection matching DiscoveredDevice.create_device()
+    if is_ceiling_product(record.product_id):
+        return CeilingLight(**kwargs)
+    if product.has_matrix:
+        return MatrixLight(**kwargs)
+    if product.has_multizone:
+        return MultiZoneLight(**kwargs)
+    if product.has_infrared:
+        return InfraredLight(**kwargs)
+    if product.has_hev:
+        return HevLight(**kwargs)
+    if product.has_relays or (product.has_buttons and not product.has_color):
+        return None
+    return Light(**kwargs)
+
+
+async def discover_lifx_services(
+    timeout: float = DISCOVERY_TIMEOUT,
+    max_response_time: float = MAX_RESPONSE_TIME,
+    idle_timeout_multiplier: float = IDLE_TIMEOUT_MULTIPLIER,
+) -> AsyncGenerator[LifxServiceRecord, None]:
+    """Discover LIFX devices via mDNS and yield service records.
+
+    Sends an mDNS PTR query for _lifx._udp.local and yields service records
+    as devices respond. Records are deduplicated by serial number.
+
+    This is the low-level API that provides raw mDNS data. For device instances,
+    use discover_devices_mdns() instead.
+
+    Args:
+        timeout: Overall discovery timeout in seconds
+        max_response_time: Maximum expected response time
+        idle_timeout_multiplier: Multiplier for idle timeout
+
+    Yields:
+        LifxServiceRecord for each discovered device
+
+    Example:
+        ```python
+        async for record in discover_lifx_services(timeout=10.0):
+            print(f"Found: {record.serial} (product {record.product_id})")
+            print(f"  IP: {record.ip}:{record.port}")
+            print(f"  Firmware: {record.firmware}")
+        ```
+    """
+    seen_serials: set[str] = set()
+    start_time = time.time()
+
+    async with MdnsTransport() as transport:
+        # Build and send PTR query
+        query = build_ptr_query(LIFX_MDNS_SERVICE)
+        request_time = time.time()
+
+        _LOGGER.debug(
+            {
+                "class": "discover_lifx_services",
+                "method": "discover",
+                "action": "sending_query",
+                "service": LIFX_MDNS_SERVICE,
+                "timeout": timeout,
+            }
+        )
+
+        await transport.send(query)
+
+        # Calculate idle timeout
+        idle_timeout = max_response_time * idle_timeout_multiplier
+        last_response_time = request_time
+
+        # Collect responses with dynamic timeout
+        while True:
+            # Calculate elapsed time since last response
+            elapsed_since_last = time.time() - last_response_time
+
+            # Stop if we've been idle too long
+            if elapsed_since_last >= idle_timeout:
+                _LOGGER.debug(
+                    {
+                        "class": "discover_lifx_services",
+                        "method": "discover",
+                        "action": "idle_timeout",
+                        "idle_time": elapsed_since_last,
+                        "idle_timeout": idle_timeout,
+                    }
+                )
+                break
+
+            # Stop if we've exceeded the overall timeout
+            if time.time() - request_time >= timeout:
+                _LOGGER.debug(
+                    {
+                        "class": "discover_lifx_services",
+                        "method": "discover",
+                        "action": "overall_timeout",
+                        "elapsed": time.time() - request_time,
+                        "timeout": timeout,
+                    }
+                )
+                break
+
+            # Calculate remaining timeout
+            remaining_idle = idle_timeout - elapsed_since_last
+            remaining_overall = timeout - (time.time() - request_time)
+            remaining = min(remaining_idle, remaining_overall)
+
+            try:
+                data, addr = await transport.receive(timeout=remaining)
+                response_timestamp = time.time()
+
+            except Exception:
+                # Timeout or error - stop collecting
+                _LOGGER.debug(
+                    {
+                        "class": "discover_lifx_services",
+                        "method": "discover",
+                        "action": "no_responses",
+                    }
+                )
+                break
+
+            try:
+                # Parse DNS response
+                response = parse_dns_response(data)
+
+                # Only process responses (not queries)
+                if not response.header.is_response:
+                    continue
+
+                # Check if this is a LIFX response (has PTR for _lifx._udp.local)
+                has_lifx_ptr = any(
+                    r.rtype == DNS_TYPE_PTR and LIFX_MDNS_SERVICE in r.name
+                    for r in response.records
+                )
+
+                if not has_lifx_ptr:
+                    # Might still be a LIFX device responding without PTR
+                    # Check TXT records for LIFX format
+                    has_lifx_txt = any(
+                        r.rtype == DNS_TYPE_TXT
+                        and isinstance(r.parsed_data, TxtData)
+                        and "id" in r.parsed_data.pairs
+                        and "p" in r.parsed_data.pairs
+                        for r in response.records
+                    )
+                    if not has_lifx_txt:
+                        continue
+
+                # Extract device info from records
+                record = _extract_lifx_info(response.records, addr[0])
+
+                if record is None:
+                    continue
+
+                # Deduplicate by serial
+                if record.serial in seen_serials:
+                    continue
+
+                seen_serials.add(record.serial)
+
+                _LOGGER.debug(
+                    {
+                        "class": "discover_lifx_services",
+                        "method": "discover",
+                        "action": "device_found",
+                        "serial": record.serial,
+                        "ip": record.ip,
+                        "port": record.port,
+                        "product_id": record.product_id,
+                    }
+                )
+
+                yield record
+
+                # Update last response time for idle timeout
+                last_response_time = response_timestamp
+
+            except Exception as e:
+                _LOGGER.debug(
+                    {
+                        "class": "discover_lifx_services",
+                        "method": "discover",
+                        "action": "parse_error",
+                        "error": str(e),
+                        "source_ip": addr[0],
+                    }
+                )
+                continue
+
+        _LOGGER.debug(
+            {
+                "class": "discover_lifx_services",
+                "method": "discover",
+                "action": "complete",
+                "devices_found": len(seen_serials),
+                "elapsed": time.time() - start_time,
+            }
+        )
+
+
+async def discover_devices_mdns(
+    timeout: float = DISCOVERY_TIMEOUT,
+    max_response_time: float = MAX_RESPONSE_TIME,
+    idle_timeout_multiplier: float = IDLE_TIMEOUT_MULTIPLIER,
+    device_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+) -> AsyncGenerator[Light, None]:
+    """Discover LIFX devices via mDNS and yield device instances.
+
+    This is the high-level API that yields fully-typed device instances
+    (Light, MatrixLight, MultiZoneLight, etc.) based on product capabilities.
+
+    Devices that are not lights (relays, buttons without color) are automatically
+    filtered out and not yielded.
+
+    Args:
+        timeout: Overall discovery timeout in seconds
+        max_response_time: Maximum expected response time
+        idle_timeout_multiplier: Multiplier for idle timeout
+        device_timeout: Request timeout for created devices
+        max_retries: Maximum retry attempts for device requests
+
+    Yields:
+        Device instances (Light, MatrixLight, etc.) as they are discovered
+
+    Example:
+        ```python
+        async for device in discover_devices_mdns(timeout=10.0):
+            async with device:
+                label = await device.get_label()
+                print(f"{type(device).__name__}: {label} at {device.ip}")
+        ```
+    """
+    async for record in discover_lifx_services(
+        timeout=timeout,
+        max_response_time=max_response_time,
+        idle_timeout_multiplier=idle_timeout_multiplier,
+    ):
+        device = create_device_from_record(
+            record,
+            timeout=device_timeout,
+            max_retries=max_retries,
+        )
+
+        if device is not None:
+            yield device

lifx/network/mdns/dns.py

@@ -0,0 +1,356 @@
+"""DNS wire format parser for mDNS discovery.
+
+This module provides minimal DNS parsing for mDNS service discovery,
+supporting PTR, SRV, A, and TXT record types.
+
+Uses only Python stdlib (struct, socket).
+"""
+
+from __future__ import annotations
+
+import socket
+import struct
+from dataclasses import dataclass, field
+from typing import Any
+
+# DNS record types
+DNS_TYPE_A = 1
+DNS_TYPE_PTR = 12
+DNS_TYPE_TXT = 16
+DNS_TYPE_AAAA = 28
+DNS_TYPE_SRV = 33
+
+# DNS classes
+DNS_CLASS_IN = 1
+DNS_CLASS_UNIQUE = 0x8001  # Cache flush bit set
+
+# Type names for display
+_TYPE_NAMES = {
+    DNS_TYPE_A: "A",
+    DNS_TYPE_PTR: "PTR",
+    DNS_TYPE_TXT: "TXT",
+    DNS_TYPE_AAAA: "AAAA",
+    DNS_TYPE_SRV: "SRV",
+}
+
+
+@dataclass
+class DnsHeader:
+    """DNS message header (12 bytes).
+
+    Attributes:
+        id: Transaction ID (0 for mDNS)
+        flags: DNS flags
+        qd_count: Question count
+        an_count: Answer count
+        ns_count: Authority count
+        ar_count: Additional count
+    """
+
+    id: int
+    flags: int
+    qd_count: int
+    an_count: int
+    ns_count: int
+    ar_count: int
+
+    @property
+    def is_response(self) -> bool:
+        """Check if this is a response (QR bit set)."""
+        return bool(self.flags & 0x8000)
+
+    @classmethod
+    def parse(cls, data: bytes) -> DnsHeader:
+        """Parse a DNS header from bytes.
+
+        Args:
+            data: At least 12 bytes of DNS header data
+
+        Returns:
+            Parsed DnsHeader
+
+        Raises:
+            ValueError: If data is too short
+        """
+        if len(data) < 12:
+            raise ValueError(f"DNS header too short: {len(data)} bytes")
+        id_, flags, qd, an, ns, ar = struct.unpack("!HHHHHH", data[:12])
+        return cls(id_, flags, qd, an, ns, ar)
+
+
+@dataclass
+class SrvData:
+    """Parsed SRV record data.
+
+    Attributes:
+        priority: Service priority
+        weight: Service weight
+        port: Service port
+        target: Target hostname
+    """
+
+    priority: int
+    weight: int
+    port: int
+    target: str
+
+
+@dataclass
+class TxtData:
+    """Parsed TXT record data.
+
+    Attributes:
+        strings: Raw TXT strings
+        pairs: Key-value pairs parsed from strings containing '='
+    """
+
+    strings: list[str] = field(default_factory=list)
+    pairs: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class DnsResourceRecord:
+    """DNS resource record.
+
+    Attributes:
+        name: Record name
+        rtype: Record type (A, PTR, TXT, SRV, etc.)
+        rclass: Record class (usually IN)
+        ttl: Time to live in seconds
+        rdata: Raw record data bytes
+        parsed_data: Parsed record data (type varies by rtype)
+    """
+
+    name: str
+    rtype: int
+    rclass: int
+    ttl: int
+    rdata: bytes
+    parsed_data: Any = None
+
+    @property
+    def type_name(self) -> str:
+        """Get human-readable record type name."""
+        return _TYPE_NAMES.get(self.rtype, f"TYPE{self.rtype}")
+
+    @property
+    def cache_flush(self) -> bool:
+        """Check if cache flush bit is set (mDNS unique)."""
+        return bool(self.rclass & 0x8000)
+
+
+@dataclass
+class ParsedDnsResponse:
+    """Parsed DNS response message.
+
+    Attributes:
+        header: DNS header
+        records: All resource records (answers + authority + additional)
+    """
+
+    header: DnsHeader
+    records: list[DnsResourceRecord]
+
+
+def parse_name(data: bytes, offset: int) -> tuple[str, int]:
+    """Parse a DNS name with compression pointer support.
+
+    DNS names use length-prefixed labels, with 0xC0 prefix indicating
+    compression pointers to earlier positions in the message.
+
+    Args:
+        data: Complete DNS message bytes
+        offset: Starting offset in data
+
+    Returns:
+        Tuple of (parsed name, new offset after the name)
+
+    Raises:
+        ValueError: If name parsing fails
+    """
+    labels: list[str] = []
+    original_offset = offset
+    jumped = False
+    max_jumps = 10  # Prevent infinite loops
+    jumps = 0
+
+    while True:
+        if offset >= len(data):
+            raise ValueError(f"DNS name parsing ran off end of data at offset {offset}")
+
+        length = data[offset]
+
+        # Check for compression pointer (top 2 bits set)
+        if (length & 0xC0) == 0xC0:
+            if offset + 1 >= len(data):
+                raise ValueError("Compression pointer incomplete")
+            # Pointer to earlier in message
+            pointer = ((length & 0x3F) << 8) | data[offset + 1]
+            if not jumped:
+                original_offset = offset + 2
+            jumped = True
+            offset = pointer
+            jumps += 1
+            if jumps > max_jumps:
+                raise ValueError("Too many compression pointer jumps")
+            continue
+
+        offset += 1
+
+        if length == 0:
+            # End of name
+            break
+
+        if offset + length > len(data):
+            raise ValueError(
+                f"Label extends beyond data: offset={offset}, length={length}"
+            )
+
+        label = data[offset : offset + length].decode("utf-8", errors="replace")
+        labels.append(label)
+        offset += length
+
+    name = ".".join(labels) if labels else "."
+    final_offset = original_offset if jumped else offset
+
+    return name, final_offset
+
+
+def parse_txt_record(rdata: bytes) -> TxtData:
+    """Parse TXT record data.
+
+    TXT records contain one or more length-prefixed strings.
+    LIFX uses key=value format in these strings.
+
+    Args:
+        rdata: TXT record data bytes
+
+    Returns:
+        Parsed TxtData with strings and key-value pairs
+    """
+    txt_data = TxtData()
+    offset = 0
+
+    while offset < len(rdata):
+        str_len = rdata[offset]
+        offset += 1
+        if offset + str_len > len(rdata):
+            break
+        txt_str = rdata[offset : offset + str_len].decode("utf-8", errors="replace")
+        txt_data.strings.append(txt_str)
+        # Try to parse as key=value
+        if "=" in txt_str:
+            key, _, value = txt_str.partition("=")
+            txt_data.pairs[key] = value
+        offset += str_len
+
+    return txt_data
+
+
+def _parse_resource_record(data: bytes, offset: int) -> tuple[DnsResourceRecord, int]:
+    """Parse a single DNS resource record.
+
+    Args:
+        data: Complete DNS message bytes
+        offset: Starting offset of the record
+
+    Returns:
+        Tuple of (parsed record, new offset after the record)
+
+    Raises:
+        ValueError: If record parsing fails
+    """
+    name, offset = parse_name(data, offset)
+
+    if offset + 10 > len(data):
+        raise ValueError(f"Resource record header incomplete at offset {offset}")
+
+    rtype, rclass, ttl, rdlength = struct.unpack("!HHIH", data[offset : offset + 10])
+    offset += 10
+
+    if offset + rdlength > len(data):
+        available = len(data) - offset
+        raise ValueError(
+            f"Resource record data incomplete: need {rdlength}, have {available}"
+        )
+
+    rdata = data[offset : offset + rdlength]
+    offset += rdlength
+
+    # Parse specific record types
+    parsed_data: Any = None
+
+    if rtype == DNS_TYPE_A and rdlength == 4:
+        parsed_data = socket.inet_ntoa(rdata)
+
+    elif rtype == DNS_TYPE_AAAA and rdlength == 16:
+        parsed_data = socket.inet_ntop(socket.AF_INET6, rdata)
+
+    elif rtype == DNS_TYPE_PTR:
+        parsed_data, _ = parse_name(data, offset - rdlength)
+
+    elif rtype == DNS_TYPE_SRV and rdlength >= 6:
+        priority, weight, port = struct.unpack("!HHH", rdata[:6])
+        target, _ = parse_name(data, offset - rdlength + 6)
+        parsed_data = SrvData(priority, weight, port, target)
+
+    elif rtype == DNS_TYPE_TXT:
+        parsed_data = parse_txt_record(rdata)
+
+    return DnsResourceRecord(name, rtype, rclass, ttl, rdata, parsed_data), offset
+
+
+def parse_dns_response(data: bytes) -> ParsedDnsResponse:
+    """Parse a complete DNS response message.
+
+    Args:
+        data: Complete DNS message bytes
+
+    Returns:
+        ParsedDnsResponse containing header and all records
+
+    Raises:
+        ValueError: If message parsing fails
+    """
+    header = DnsHeader.parse(data)
+    offset = 12
+    records: list[DnsResourceRecord] = []
+
+    # Skip questions (we don't need them for responses)
+    for _ in range(header.qd_count):
+        _, offset = parse_name(data, offset)
+        offset += 4  # QTYPE + QCLASS
+
+    # Parse all resource records (answers, authority, additional)
+    total_records = header.an_count + header.ns_count + header.ar_count
+    for _ in range(total_records):
+        record, offset = _parse_resource_record(data, offset)
+        records.append(record)
+
+    return ParsedDnsResponse(header, records)
+
+
+def build_ptr_query(service: str) -> bytes:
+    """Build an mDNS PTR query for a service type.
+
+    Args:
+        service: Service name (e.g., "_lifx._udp.local")
+
+    Returns:
+        DNS query packet bytes ready to send
+
+    Example:
+        >>> query = build_ptr_query("_lifx._udp.local")
+        >>> # Send to 224.0.0.251:5353
+    """
+    # Header: ID=0 (mDNS), standard query, 1 question
+    header = struct.pack("!HHHHHH", 0, 0, 1, 0, 0, 0)
+
+    # Question: service name, PTR type, IN class
+    question = b""
+    for label in service.split("."):
+        question += bytes([len(label)]) + label.encode("utf-8")
+    question += b"\x00"  # Root label
+    question += struct.pack("!HH", DNS_TYPE_PTR, DNS_CLASS_IN)
+
+    return header + question

lifx/network/mdns/transport.py

@@ -0,0 +1,313 @@
+"""mDNS transport for multicast UDP communication.
+
+This module provides a UDP transport specifically for mDNS queries,
+with multicast group joining and appropriate socket configuration.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket
+import struct
+from asyncio import DatagramTransport
+from typing import TYPE_CHECKING
+
+from lifx.const import MDNS_ADDRESS, MDNS_PORT
+from lifx.exceptions import LifxNetworkError, LifxTimeoutError
+
+if TYPE_CHECKING:
+    pass
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class _MdnsProtocol(asyncio.DatagramProtocol):
+    """Asyncio protocol for mDNS UDP communication."""
+
+    def __init__(self) -> None:
+        """Initialize the protocol."""
+        self.queue: asyncio.Queue[tuple[bytes, tuple[str, int]]] = asyncio.Queue()
+        self._transport: DatagramTransport | None = None
+
+    def connection_made(self, transport: DatagramTransport) -> None:  # type: ignore[override]
+        """Called when connection is established."""
+        self._transport = transport
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        """Called when a datagram is received."""
+        self.queue.put_nowait((data, addr))
+
+    def error_received(self, exc: Exception) -> None:
+        """Called when an error is received."""
+        _LOGGER.debug(
+            {
+                "class": "_MdnsProtocol",
+                "method": "error_received",
+                "action": "error",
+                "error": str(exc),
+            }
+        )
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        """Called when connection is lost."""
+        _LOGGER.debug(
+            {
+                "class": "_MdnsProtocol",
+                "method": "connection_lost",
+                "action": "lost",
+                "error": str(exc) if exc else None,
+            }
+        )
+
+
+class MdnsTransport:
+    """UDP transport for mDNS multicast communication.
+
+    This transport is specifically designed for mDNS queries and responses,
+    with support for multicast group membership and appropriate socket options.
+
+    Example:
+        >>> async with MdnsTransport() as transport:
+        ...     await transport.send(query, (MDNS_ADDRESS, MDNS_PORT))
+        ...     data, addr = await transport.receive(timeout=5.0)
+    """
+
+    def __init__(self) -> None:
+        """Initialize mDNS transport."""
+        self._protocol: _MdnsProtocol | None = None
+        self._transport: DatagramTransport | None = None
+        self._socket: socket.socket | None = None
+
+    async def __aenter__(self) -> MdnsTransport:
+        """Enter async context manager."""
+        await self.open()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Exit async context manager."""
+        await self.close()
+
+    async def open(self) -> None:
+        """Open the mDNS socket with multicast configuration.
+
+        Creates a UDP socket, configures it for mDNS multicast,
+        and joins the mDNS multicast group.
+
+        Raises:
+            LifxNetworkError: If socket creation or configuration fails
+        """
+        if self._protocol is not None:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "already_open",
+                }
+            )
+            return
+
+        try:
+            loop = asyncio.get_running_loop()
+
+            # Create and configure socket manually for multicast
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+            # Try to set SO_REUSEPORT if available (Linux/macOS)
+            try:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+            except (AttributeError, OSError):
+                pass
+
+            # Bind to mDNS port (or ephemeral if busy)
+            try:
+                sock.bind(("", MDNS_PORT))
+                _LOGGER.debug(
+                    {
+                        "class": "MdnsTransport",
+                        "method": "open",
+                        "action": "bound_to_mdns_port",
+                        "port": MDNS_PORT,
+                    }
+                )
+            except OSError as e:
+                _LOGGER.debug(
+                    {
+                        "class": "MdnsTransport",
+                        "method": "open",
+                        "action": "mdns_port_busy",
+                        "error": str(e),
+                    }
+                )
+                # Fall back to ephemeral port
+                sock.bind(("", 0))
+                _LOGGER.debug(
+                    {
+                        "class": "MdnsTransport",
+                        "method": "open",
+                        "action": "bound_to_ephemeral_port",
+                        "port": sock.getsockname()[1],
+                    }
+                )
+
+            # Join mDNS multicast group
+            mreq = struct.pack("4sl", socket.inet_aton(MDNS_ADDRESS), socket.INADDR_ANY)
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "joined_multicast_group",
+                    "group": MDNS_ADDRESS,
+                }
+            )
+
+            # Set multicast TTL (1 for link-local)
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, 1)
+
+            # Make socket non-blocking
+            sock.setblocking(False)
+            self._socket = sock
+
+            # Create protocol
+            protocol = _MdnsProtocol()
+            self._protocol = protocol
+
+            # Create datagram endpoint using our configured socket
+            self._transport, _ = await loop.create_datagram_endpoint(
+                lambda: protocol,
+                sock=sock,
+            )
+
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "opened",
+                }
+            )
+
+        except OSError as e:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "failed",
+                    "error": str(e),
+                }
+            )
+            raise LifxNetworkError(f"Failed to open mDNS socket: {e}") from e
+
+    async def send(self, data: bytes, address: tuple[str, int] | None = None) -> None:
+        """Send data to mDNS multicast address.
+
+        Args:
+            data: Bytes to send
+            address: Target address (defaults to mDNS multicast address)
+
+        Raises:
+            LifxNetworkError: If socket is not open or send fails
+        """
+        if self._transport is None or self._protocol is None:
+            raise LifxNetworkError("Socket not open")
+
+        if address is None:
+            address = (MDNS_ADDRESS, MDNS_PORT)
+
+        try:
+            self._transport.sendto(data, address)
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "send",
+                    "action": "sent",
+                    "size": len(data),
+                    "destination": address,
+                }
+            )
+        except OSError as e:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "send",
+                    "action": "failed",
+                    "destination": address,
+                    "error": str(e),
+                }
+            )
+            raise LifxNetworkError(f"Failed to send mDNS data: {e}") from e
+
+    async def receive(self, timeout: float = 5.0) -> tuple[bytes, tuple[str, int]]:
+        """Receive data from socket.
+
+        Args:
+            timeout: Timeout in seconds
+
+        Returns:
+            Tuple of (data, address) where address is (host, port)
+
+        Raises:
+            LifxTimeoutError: If no data received within timeout
+            LifxNetworkError: If socket is not open or receive fails
+        """
+        if self._protocol is None:
+            raise LifxNetworkError("Socket not open")
+
+        try:
+            async with asyncio.timeout(timeout):
+                data, addr = await self._protocol.queue.get()
+                return data, addr
+        except TimeoutError as e:
+            raise LifxTimeoutError(f"No mDNS data received within {timeout}s") from e
+        except OSError as e:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "receive",
+                    "action": "failed",
+                    "error": str(e),
+                }
+            )
+            raise LifxNetworkError(f"Failed to receive mDNS data: {e}") from e
+
+    async def close(self) -> None:
+        """Close the mDNS socket."""
+        if self._transport is not None:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "close",
+                    "action": "closing",
+                }
+            )
+
+            # Leave multicast group
+            if self._socket is not None:
+                try:
+                    mreq = struct.pack(
+                        "4sl", socket.inet_aton(MDNS_ADDRESS), socket.INADDR_ANY
+                    )
+                    self._socket.setsockopt(
+                        socket.IPPROTO_IP, socket.IP_DROP_MEMBERSHIP, mreq
+                    )
+                except OSError:
+                    pass  # Ignore errors when leaving group
+
+            self._transport.close()
+            self._transport = None
+            self._protocol = None
+            self._socket = None
+
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "close",
+                    "action": "closed",
+                }
+            )
+
+    @property
+    def is_open(self) -> bool:
+        """Check if socket is open."""
+        return self._protocol is not None

lifx/network/mdns/types.py

@@ -0,0 +1,35 @@
+"""Type definitions for mDNS discovery.
+
+This module defines the data structures used for mDNS service discovery.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LifxServiceRecord:
+    """Information about a LIFX device discovered via mDNS.
+
+    Attributes:
+        serial: Device serial number as 12-digit hex string (e.g., "d073d5123456")
+        ip: Device IP address
+        port: Device UDP port (typically 56700)
+        product_id: Product ID from TXT record 'p' field
+        firmware: Firmware version from TXT record 'fw' field
+    """
+
+    serial: str
+    ip: str
+    port: int
+    product_id: int
+    firmware: str
+
+    def __hash__(self) -> int:
+        """Hash based on serial number for deduplication."""
+        return hash(self.serial)
+
+    def __eq__(self, other: object) -> bool:
+        """Equality based on serial number."""
+        if not isinstance(other, LifxServiceRecord):
+            return False
+        return self.serial == other.serial

{lifx_async-4.7.5.dist-info → lifx_async-4.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-async
-Version: 4.7.5
+Version: 4.8.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.7.5.dist-info → lifx_async-4.8.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-lifx/__init__.py,sha256=aiMLKLhmcXADJyeISNHIZ_Nuc6jEhPG8-I_R3peWpwo,2610
-lifx/api.py,sha256=XV2CJLi3N9UpbZuqVE56K-MEsSaqOte9WhcBbhkmHQM,33962
+lifx/__init__.py,sha256=DKHG1vFJvPw_LpMkQgZN85gyOSD8dnceq6LnEGgR9vs,2810
+lifx/api.py,sha256=xHUM6NDgv8V8tLpDtpnPVJNGcVU5y_8da9wI3pnm06Y,35903
 lifx/color.py,sha256=wcmeeiBmOAjunInERNd6rslKvBEpV4vfjwwiZ8v7H8A,17877
-lifx/const.py,sha256=cf_O_3TqJjIBXF1tI35PkJ1JOhmy4tRt14PSa63pilA,3471
+lifx/const.py,sha256=5LEh4h0-bEJlOfpG8fgyht0LkAEV9jkkpuCiuatBhEI,3840
 lifx/exceptions.py,sha256=pikAMppLn7gXyjiQVWM_tSvXKNh-g366nG_UWyqpHhc,815
 lifx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lifx/devices/__init__.py,sha256=4b5QtO0EFWxIqN2lUYgM8uLjWyHI5hUcReiF9QCjCGw,1061
@@ -25,6 +25,11 @@ lifx/network/connection.py,sha256=aerPiYWf096lq8oBiS7JfE4k-P18GS50mNEC4TYa2g8,38
 lifx/network/discovery.py,sha256=syFfkDYWo0AEoBdEBjWqBm4K7UJwZW5x2K0FBMiA2I0,24186
 lifx/network/message.py,sha256=jCLC9v0tbBi54g5CaHLFM_nP1Izu8kJmo2tt23HHBbA,2600
 lifx/network/transport.py,sha256=8QS0YV32rdP0EDiPEwuvZXbplRWL08pmjKybd87mkZ0,11070
+lifx/network/mdns/__init__.py,sha256=LlZgsFe6q5_SIXvXqtuZ_O9tJbcJZ-nsFkD2_wD8_TM,1412
+lifx/network/mdns/discovery.py,sha256=EZ2zlJmy96rMDmu5J-68ystXJ2gYa18zTYP3iqmTGgU,13200
+lifx/network/mdns/dns.py,sha256=OsvNSxLepIG3Nhw-kkQF3JrBYI-ikod5SHD2HO5_yGE,9363
+lifx/network/mdns/transport.py,sha256=k8gVZCvU-gksV2dV-jm2YG-_kuKWx0whtP3Va0EjCd8,10242
+lifx/network/mdns/types.py,sha256=9fhH5iuMQxLkFPhmFTf2-kOcUNoWEu7LrN15Qr9tFE0,990
 lifx/products/__init__.py,sha256=pf2O-fzt6nOrQd-wmzhiog91tMiGa-dDbaSNtU2ZQfE,764
 lifx/products/generator.py,sha256=5bDFfrJ8ocwuhEr4dZB4LpVcqOqC3KxJSDiphPMu8CI,15660
 lifx/products/quirks.py,sha256=B8Kb4pxaXmovMbjgXRfPPWre5JEvJrn8d6PAWK_FT1U,2544
@@ -42,7 +47,7 @@ lifx/theme/canvas.py,sha256=4h7lgN8iu_OdchObGDgbxTqQLCb-FRKC-M-YCWef_i4,8048
 lifx/theme/generators.py,sha256=nq3Yvntq_h-eFHbmmow3LcAdA_hEbRRaP5mv9Bydrjk,6435
 lifx/theme/library.py,sha256=tKlKZNqJp8lRGDnilWyDm_Qr1vCRGGwuvWVS82anNpQ,21326
 lifx/theme/theme.py,sha256=qMEx_8E41C0Cc6f083XHiAXEglTv4YlXW0UFsG1rQKg,5521
-lifx_async-4.7.5.dist-info/METADATA,sha256=1SN5XqtWLHrF_JtLHyWGNSCCeoajcu32g0MWFC48VIM,2609
-lifx_async-4.7.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-lifx_async-4.7.5.dist-info/licenses/LICENSE,sha256=eBz48GRA3gSiWn3rYZAz2Ewp35snnhV9cSqkVBq7g3k,1832
-lifx_async-4.7.5.dist-info/RECORD,,
+lifx_async-4.8.0.dist-info/METADATA,sha256=kwOq2Vzad06tvCCZiq7JhT7lMkO4wEZI5JHxyIPSfbE,2609
+lifx_async-4.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+lifx_async-4.8.0.dist-info/licenses/LICENSE,sha256=eBz48GRA3gSiWn3rYZAz2Ewp35snnhV9cSqkVBq7g3k,1832
+lifx_async-4.8.0.dist-info/RECORD,,