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)
Color temperature range¶
Every product has its own color temperature range, read from the product
registry for the light's current firmware: light.min_kelvin and
light.max_kelvin. Many newer lights widen from 1500-9000 K to 1000-10000 K
after a firmware upgrade.
A color you pass to a write is checked against that range. A kelvin outside
it raises ValueError, naming the light and its range, and nothing is sent:
from lifx import HSBK
# On a light with a 2500-9000 K range
await light.set_color(HSBK(0, 0, 1.0, 1500))
# ValueError: Kelvin 1500 is outside the 2500-9000 range of d073d5...
This covers set_color(), set_kelvin(), waveforms such as pulse() and
breathe(), zone and tile writes, the Ceiling and Mirror component writes and
DeviceGroup writes. A group checks every light before it sends to any, so one
light with a narrower range does not leave the others already changed. Kelvin
0, which lights report for a color with no white component, is always
accepted. When the range is not yet known, any value from 1000 to 10000 is
accepted.
Colors the library generates are clamped into the range instead of refused, so they paint on every product. That covers themes, moods, software effects and the palettes of firmware effects such as Morph. A theme that holds 1500 K paints as 2500 K on a light that stops at 2500 K.
Waveforms¶
Create visual waveforms:
import asyncio
from lifx import Colors, Device
async def main():
async with await Device.connect("192.168.1.100") as light:
# Pulse waveform
await light.pulse(Colors.RED, period=1.0, cycles=5)
# Breathe waveform (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¶
- Next: Themes Quick Start — Apply color palettes to your lights
- Next: Light Effects — Run visual effects on your lights
- High-Level API —
discover(),find_by_serial(),DeviceGroupreference - Color Utilities — HSBK, RGB conversion, built-in presets