lifx-async¶

A modern, type-safe, async Python library for controlling LIFX lights over the local network.

Features¶

• 📦 No Runtime Dependencies: only Python standard libraries required
• 🎯 Type-Safe: Full type hints, validated with Pyright
• 🔌 Async Generators: Provides async for usage pattern
• ⚡ Async Context Managers: Provides async with and await usage patterns
• 🔌 Lazy Connections: Auto-open on first request, explicit cleanup
• 🔍 Dual Discovery: UDP broadcast plus zero-dependency mDNS/DNS-SD discovery
• 🏗️ Layered Architecture: Protocol → Network → Device → API
• 🔄 Protocol Generator: generates LIFX protocol Packets, Fields and Enum classes from LIFX public protocol definition
• ✨ Built-in Effects: 26 software effects plus 166 colour themes, filtered by device capability
• 🎞️ Animation Layer: high-frequency frame delivery for real-time multizone and matrix effects
• 🌈 Comprehensive Support: supports all LIFX smart lighting products — see the device classes documentation

Examples¶

import asyncio
from lifx import discover, Colors

async def main():
    # Discover devices asynchronously:
    async for device in discover():
        # Control each device as it is discovered
        await device.set_power(True)
        await device.set_color(Colors.BLUE, duration=1.0)

asyncio.run(main())

import asyncio
from lifx import Light, HSBK

async def main():
    # Connect most efficiently without discovery using serial and IP
    async with Light(serial="d073d5010203", ip="192.168.1.100") as light:
        # Using Light as a context manager auto-populates non-volatile state information
        print(f"{light.label} is a {light.model} at {light.location} in the {light.group} group.")

        await light.set_color(HSBK(hue=0, saturation=1.0, brightness=0.8, kelvin=3500), duration=2.0)

asyncio.run(main())

import asyncio
from lifx import Light, HSBK, Colors

async def main():
    async with Light(serial="d073d5010203", ip="192.168.1.100") as light:
        # Use RGB
        red = HSBK.from_rgb(1.0, 0.0, 0.0)
        await light.set_color(red)

        # Use presets
        await light.set_color(Colors.WARM)

        # Custom HSBK
        custom = HSBK(
            hue=180,         # 0-360 degrees
            saturation=0.7,  # 0.0-1.0
            brightness=0.8,  # 0.0-1.0
            kelvin=3500,     # 1500-9000
        )
        await light.set_color(custom)

asyncio.run(main())

Installation¶

# Using uv (recommended)
uv pip install lifx-async

# Or using pip
pip install lifx-async

For development:

git clone https://github.com/Djelibeybi/lifx-async.git
cd lifx-async
uv sync

Why lifx-async?¶

Modern Python¶

• Async For and Async With: extensive use of asynchronous generators and context managers
• Async/Await: Native asyncio support for concurrent operations
• Type Hints: Full type annotations for better IDE support
• Python 3.10+: Modern language features and performance

Reliable¶

• Comprehensive Tests: 2425+ tests covering over 90% of the source code
• Lazy Connections: Auto-open on first request
• Stores State: Reduces network traffic

Developer Friendly¶

• Clear API: Intuitive, Pythonic interface
• Rich Documentation: Extensive guides and examples
• Code Generation: Protocol updates are automatic
• No External Dependencies: Only Python standard libraries required

Support¶

• Documentation: https://djelibeybi.github.io/lifx-async/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License¶

Universal Permissive License 1.0 - see LICENSE for details.