Skip to content

Quick Start

Get up and running with lifx-async in minutes!

Basic Usage

1. Discover Lights

The simplest way to find and control LIFX lights:

import asyncio
from lifx import discover


async def main():
    count = 0
    async for device in discover():
        count += 1
        print(f"Found: {device.serial}")
    print(f"Total: {count} lights")


asyncio.run(main())

Alternative: mDNS Discovery

As an explicit alternative to broadcast discovery, mDNS can provide device type metadata without a separate LIFX product query for every device:

import asyncio
from lifx import discover_mdns


async def main():
    async for device in discover_mdns():
        async with device:
            color, power, label = await device.get_color()
            print(f"{label}: {type(device).__name__}")


asyncio.run(main())

mDNS discovery sends an initial DNS-SD PTR service query and may retransmit that PTR query once at one second and once at three seconds within the caller's deadline. It assembles valid legacy-unicast replies during the quiet window and yields devices incrementally as an async generator. Only when a valid SRV target lacks a usable address does it send bounded A/AAAA follow-ups: one successful send, or no more than two failed attempts, for each of at most 64 targets.

This opt-in discovery path may be unavailable on networks or devices that do not expose the required DNS-SD service records. Use discover() as the broadcast fallback when mDNS is not available. Each yielded device reports connectivity as "wifi" or "thread". These are members of the Connectivity enum (Connectivity.WIFI and Connectivity.THREAD), which derives from str, so plain string comparisons still work.

2. Control a Light

Turn on the first discovered light, then change its color:

import asyncio
from lifx import discover, Colors


async def main():
    async for light in discover():
        await light.set_power(True)
        await light.set_color(Colors.BLUE, duration=1.0)
        break


asyncio.run(main())

3. Batch Operations

Control multiple lights as a group:

import asyncio
from lifx import discover, DeviceGroup, Colors


async def main():
    devices = []
    async for device in discover():
        devices.append(device)

    # Create DeviceGroup for batch operations
    group = DeviceGroup(devices)
    await group.set_power(True)
    await group.set_color(Colors.BLUE, duration=1.0)
    await group.set_brightness(0.5)




asyncio.run(main())

Common Patterns

Direct Connection

If you only know the IP address, connect() first performs a unicast discovery round-trip: it sends GetService to that address to learn the device's serial number, then connects using both. It also returns the class that matches the product, so a strip comes back as a MultiZoneLight:

import asyncio
from lifx import Colors, Device


async def main():
    async with await Device.connect("192.168.1.100") as light:
        await light.set_color(Colors.RED)


asyncio.run(main())

If you know both the serial and the IP address, no discovery of any kind is needed — the library connects straight to the device:

import asyncio
from lifx import Colors, Device


async def main():
    async with await Device.connect("192.168.1.100", "d073d5010203") as light:
        await light.set_color(Colors.RED)


asyncio.run(main())

Find Specific Devices

Find devices by label, IP, or serial:

import asyncio
from lifx import find_by_label, find_by_ip, find_by_serial, Colors


async def main():
    # Find by label (substring match)
    async for device in find_by_label("Bedroom"):  # Matches "Bedroom", "Master Bedroom", etc.
        await device.set_color(Colors.WARM)

    # Find by exact label
    async for device in find_by_label("Master Bedroom", exact_match=True):
        await device.set_brightness(0.8)
        break  # exact_match returns at most one device

    # Find by IP address (fastest if you only know the IP)
    device = await find_by_ip("192.168.1.100")
    if device:
        await device.set_power(True)

    # Find by serial number
    device = await find_by_serial("d073d5123456")
    if device:
        await device.set_color(Colors.BLUE)


asyncio.run(main())

Color Presets

Use built-in color presets:

from lifx import Colors

# Primary colors
Colors.RED
Colors.GREEN
Colors.BLUE

# White variants
Colors.WARM
Colors.COOL
Colors.DAYLIGHT

# Pastels
Colors.PASTEL_BLUE
Colors.PASTEL_PINK

RGB to HSBK

Convert RGB values to HSBK:

from lifx import HSBK

# Create color from RGB
purple = HSBK.from_rgb(0.5, 0.0, 0.5)
await light.set_color(purple)

Effects

Create visual effects:

import asyncio
from lifx import Colors, Device


async def main():
    async with await Device.connect("192.168.1.100") as light:
        # Pulse effect
        await light.pulse(Colors.RED, period=1.0, cycles=5)

        # Breathe effect (10 cycles)
        await light.breathe(Colors.BLUE, period=2.0, cycles=10)


asyncio.run(main())

Error Handling

Always use proper error handling:

import asyncio
from lifx import discover, Colors, LifxError


async def main():
    try:
        async for device in discover():
            await device.set_color(Colors.GREEN)
    except LifxError as e:
        print(f"LIFX error: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")


asyncio.run(main())

Next Steps