LIFX Emulator¶

Test your LIFX LAN protocol libraries without physical devices.

Overview¶

LIFX Emulator is a Python project for testing LIFX LAN protocol client libraries. It implements the complete binary UDP protocol from lan.developer.lifx.com.

Packages¶

This project provides two packages for different use cases:

Package	PyPI Name	Import Name	Description
Standalone	`lifx-emulator`	`lifx_emulator_app`	CLI tool + HTTP management API
Core Library	`lifx-emulator-core`	`lifx_emulator`	Embeddable Python library

Which Package Do I Need?¶

Install lifx-emulator if you want:

A ready-to-run CLI tool
HTTP REST API for device management
Web dashboard for monitoring
Quick testing without writing code

pip install lifx-emulator
lifx-emulator --api --verbose

Install lifx-emulator-core if you want:

To embed emulation in your own Python application
Programmatic control for pytest or other test frameworks
To build custom tooling around LIFX emulation

pip install lifx-emulator-core

from lifx_emulator import create_color_light, EmulatedLifxServer

Quick Start¶

CLI (lifx-emulator)Python Library (lifx-emulator-core)

# Install
pip install lifx-emulator

# Start with default configuration
lifx-emulator

# Multiple devices with web dashboard
lifx-emulator --color 2 --multizone 1 --api --verbose

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

async def main():
    device = create_color_light("d073d5000001")
    device_manager = DeviceManager(DeviceRepository())

    async with EmulatedLifxServer(
        [device], device_manager, "127.0.0.1", 56700
    ) as server:
        print(f"Emulating: {device.state.label}")
        await asyncio.Event().wait()

asyncio.run(main())

Key Features¶

Complete Protocol Support: All packet types from the LIFX LAN protocol
Multiple Device Types: Color lights, infrared, HEV, multizone strips, and matrix tiles
Product Registry: 137+ official LIFX product definitions
Testing Scenarios: Configurable packet loss, delays, malformed responses
HTTP Management API: OpenAPI 3.1.0 compliant REST API (standalone package)
Web Dashboard: Real-time monitoring interface (standalone package)
Persistent Storage: Save device state across sessions

Documentation¶

Getting Started¶

Installation - Install either package
Quick Start - First steps with CLI or Python API

lifx-emulator (Standalone CLI)¶

Overview - CLI tool and HTTP management server
CLI Reference - All CLI commands and options
Web Interface - Browser-based monitoring dashboard
Device Management API - REST API for devices
Scenario API - REST API for test scenarios
Persistent Storage - Save state across restarts
Scenarios Guide - Comprehensive scenario configuration

lifx-emulator-core (Python Library)¶

Python Library Reference - Complete library documentation
Factory Functions - Device creation functions
Server - EmulatedLifxServer configuration
Device - EmulatedLifxDevice and DeviceState
Protocol Types - LightHsbk and other types
Storage - Persistent state management
Product Registry - Product database
Architecture - System design and internals

Guides (Shared)¶

Device Types - Supported LIFX devices
Products & Specs - Product registry usage
Testing Scenarios - Error simulation
Framebuffers - Matrix device framebuffer support
Integration Testing - Using in test suites
Best Practices - Tips for effective testing

Tutorials¶

First Device - Your first emulated device
Basic Usage - Multiple devices and basic testing
Integration Testing - pytest integration
Advanced Scenarios - Error injection
CI/CD Integration - Automated testing pipelines

Reference¶

FAQ - Frequently asked questions
Troubleshooting - Common issues and solutions
Glossary - Terms and definitions
Changelog - Version history

Supported Device Types¶

Device Type	Example Products	Capabilities
Color Lights	LIFX A19, LIFX BR30	Full RGB color control
Color Temperature	LIFX Mini White to Warm	Variable white temperature
Infrared	LIFX A19 Night Vision	IR brightness control
HEV	LIFX Clean	HEV cleaning cycle
Multizone	LIFX Z, LIFX Beam	Linear zones (up to 82+)
Matrix	LIFX Tile, LIFX Candle	2D zone arrays
Switch	LIFX Switch	Relay-based switches

Use Cases¶

Library Testing: Test your LIFX library without physical devices
CI/CD Integration: Run automated tests in pipelines
Protocol Development: Experiment with LIFX protocol features
Error Simulation: Test error handling with configurable scenarios
Performance Testing: Test concurrent device handling

Requirements¶

Python 3.11 or higher