Skip to content

Your First LIFX Device

Difficulty: 🟢 Beginner | Time: ⏱️ 5 minutes | Prerequisites: Python 3.11+, LIFX Emulator installed

This tutorial walks you through creating and running your first emulated LIFX device. By the end, you'll have a virtual LIFX light running on your machine that responds to LIFX protocol commands.

What You'll Learn

  • How to create a single emulated device
  • How to start the emulator server
  • How to verify the device is running
  • How to test it with a LIFX client (optional)

Step 1: Create Your First Device

The fastest way to get started is with the CLI:

# Install (if not already installed)
pip install lifx-emulator

# Create a single color light with verbose output
lifx-emulator --color 1 --verbose

You should see output like:

INFO - Starting LIFX Emulator on 127.0.0.1:56700
INFO - Created 1 emulated device(s):
INFO -   • A19 d073d5000001 (d073d5000001) - full color
INFO - Server running with verbose packet logging... Press Ctrl+C to stop

That's it! You now have a virtual LIFX device running.

Create a new Python file called first_device.py:

import asyncio
from lifx_emulator import EmulatedLifxServer, create_color_light
from lifx_emulator.repositories import DeviceRepository
from lifx_emulator.devices import DeviceManager

async def main():
    # Create a LIFX A19 color light
    device = create_color_light("d073d5000001")

    # Create repository and manager (required)
    device_manager = DeviceManager(DeviceRepository())

    # Create server on standard LIFX port (56700)
    server = EmulatedLifxServer(
        [device], device_manager, "127.0.0.1", 56700
    )

    # Start the server
    async with server:
        print(f"Emulator running!")
        print(f"Device: {device.state.label}")
        print(f"Serial: {device.state.serial}")
        print(f"Listening on: 127.0.0.1:56700")
        print("\nPress Ctrl+C to stop")

        # Keep server running
        try:
            await asyncio.sleep(3600)  # Run for 1 hour
        except KeyboardInterrupt:
            print("\nShutting down...")

if __name__ == "__main__":
    asyncio.run(main())

Run your script:

python first_device.py

You should see output like:

Emulator running!
Device: LIFX Light
Serial: d073d5000001
Listening on: 127.0.0.1:56700

Press Ctrl+C to stop

Congratulations! You now have a virtual LIFX device running on your machine.

Step 2: Understanding What's Happening

The CLI command lifx-emulator --color 1 --verbose does the following:

  • --color 1 - Creates 1 LIFX A19 color light (product ID 27)
  • --verbose - Enables detailed packet logging to see activity

CLI Options Explained:

Option Description
--color N Create N color lights
--verbose Show packet-level details
--port PORT Use custom UDP port (default: 56700)
--bind IP Bind to specific IP (default: 127.0.0.1)
--api Enable HTTP management API

Creating the Device

device = create_color_light("d073d5000001")
  • create_color_light() - Creates a LIFX A19 bulb (product ID 27)
  • "d073d5000001" - The device's unique serial number (MAC address)

Creating the Server

device_manager = DeviceManager(DeviceRepository())
server = EmulatedLifxServer([device], device_manager, "127.0.0.1", 56700)
  • DeviceManager and DeviceRepository - Required for device lifecycle management
  • [device] - List of devices to emulate (we have one)
  • "127.0.0.1" - IP address to bind to (localhost)
  • 56700 - Standard LIFX UDP port

Using the Context Manager

async with server:
    # Server is running here
    await asyncio.sleep(3600)

The async with statement:

  1. Starts the server automatically
  2. Runs your code inside the block
  3. Stops the server cleanly when done

Step 4: Customizing Your Device (Optional)

You can customize the device before starting the server:

from lifx_emulator.protocol.protocol_types import LightHsbk

# Create device
device = create_color_light("d073d5000001")

# Customize it
device.state.label = "My First Light"
device.state.power = 65535  # On (max power)
device.state.color = LightHsbk(
    hue=21845,      # Green (120 degrees)
    saturation=65535,  # Fully saturated
    brightness=32768,  # 50% brightness
    kelvin=3500
)

# Now start the server...

Step 5: Testing with a LIFX Client (Optional)

If you have a LIFX client library installed, you can test your emulated device.

Using the lifx-async library

Install the library:

pip install lifx-async

In a separate terminal, create test_client.py:

import asyncio
from lifx import discover
from lifx.color import HSBK

async def main():
    # Discover devices
    async with discover() as group:
        print(f"Found {len(group.devices)} device(s)")

        if group.devices:
            device = group.devices[0]
            print(f"Device: {device.label}")
            print(f"Power: {device.power}")

            # Change color to red
            print("Setting color to red...")
            await device.set_color(HSBK.from_rgb(255, 0, 0))
            print("Done!")

asyncio.run(main())

Run it while your emulator is running:

python test_client.py

You should see:

Found 1 device(s)
Device: LIFX Light
Power: 65535
Setting color to red...
Done!

Troubleshooting

Port Already in Use

Error: OSError: [Errno 48] Address already in use

Solution: Change the port number:

server = EmulatedLifxServer([device], "127.0.0.1", 56701)  # Different port

Device Not Discovered

Problem: Client can't find the device

Solutions: 1. Make sure the emulator is running 2. Check that both emulator and client are on the same network interface 3. Try binding to "0.0.0.0" instead of "127.0.0.1":

server = EmulatedLifxServer([device], "0.0.0.0", 56700)

Python Version Error

Error: SyntaxError or import errors

Solution: Ensure you're using Python 3.11 or newer:

python --version  # Should show 3.11 or higher

What You've Learned

✓ How to create an emulated LIFX device ✓ How to start the emulator server ✓ How to use the context manager pattern ✓ How to customize device properties ✓ How to test with a LIFX client

Next Steps

Now that you have a basic device running, you can:

  1. Basic Usage Tutorial - Learn more patterns (multiple devices, state queries, etc.)
  2. Integration Testing - Use the emulator in your pytest test suite
  3. Advanced Scenarios - Explore multizone devices, tiles, and error injection

Quick Wins

Try these modifications to your first_device.py:

  • Multiple devices: Add more devices to the list: 

    devices = [
    create_color_light("d073d5000001"),
    create_color_light("d073d5000002"),
    create_color_light("d073d5000003"),
]
server = EmulatedLifxServer(devices, "127.0.0.1", 56700)

  • Different device type: Try a multizone strip: 

    from lifx_emulator import create_multizone_light
device = create_multizone_light("d073d8000001", zone_count=16)

  • Custom labels: Give each device a unique name: 

    device.state.label = "Living Room"

See Also