Protocol API Reference¶

@dataclass
class LifxHeader:
    # Class constants
    HEADER_SIZE: ClassVar[int] = 36
    PROTOCOL_NUMBER: ClassVar[int] = 1024
    ORIGIN: ClassVar[int] = 0        # Message origin (always 0)
    ADDRESSABLE: ClassVar[int] = 1   # Addressable flag (always 1)

    # Frame
    size: int = 0                # Total packet size (header + payload)
    protocol: int = 1024         # Protocol number (must be 1024)
    source: int = 0              # Unique client identifier
    tagged: bool = False         # Broadcast flag (True = all devices)

    # Frame Address
    target: bytes = b'\x00' * 8  # 6-byte serial + 2 null bytes
    ack_required: bool = False   # Request acknowledgment
    res_required: bool = False   # Request response
    sequence: int = 0            # Message sequence number (0-255)
    thread_connection: bool = False  # Flags bit 3: set by Thread devices on replies

    # Protocol Header
    pkt_type: int = 0            # Packet type number (e.g., 2, 101, 116)

from lifx_emulator.protocol.header import LifxHeader

header = LifxHeader(
    size=36,
    source=12345,
    target=bytes.fromhex("d073d5000001") + b'\x00\x00',
    res_required=True,
    sequence=1,
    pkt_type=101,  # Light.GetColor
)
raw_header = header.pack()
# Returns: 36 bytes

from lifx_emulator.protocol.header import LifxHeader

raw_header = sock.recv(36)
header = LifxHeader.unpack(raw_header)
print(f"Packet type: {header.pkt_type}")
print(f"Source: {header.source}")
print(f"Target: {header.target.hex()}")

from lifx_emulator.protocol.packets import Button, Device, Light, MultiZone, Sensor, Tile

# Device discovery and information
Device.GetService             # Type 2
Device.StateService           # Type 3
Device.GetHostFirmware        # Type 14
Device.StateHostFirmware      # Type 15
Device.GetVersion             # Type 32
Device.StateVersion           # Type 33
Device.GetLocation            # Type 48
Device.StateLocation          # Type 50
Device.GetGroup               # Type 51
Device.StateGroup             # Type 53
Device.Acknowledgement        # Type 45
Device.EchoRequest            # Type 58
Device.EchoResponse           # Type 59
Device.StateUnhandled         # Type 223

# Light control (all color-capable devices)
Light.GetColor                # Type 101
Light.SetColor                # Type 102
Light.SetWaveform             # Type 103
Light.StateColor              # Type 107
Light.GetPower                # Type 116
Light.SetPower                # Type 117
Light.StatePower              # Type 118
Light.SetWaveformOptional     # Type 119
Light.GetInfrared             # Type 120 (infrared devices only)
Light.StateInfrared           # Type 121
Light.SetInfrared             # Type 122

# HEV (germicidal light)
Light.GetHevCycle                     # Type 142
Light.SetHevCycle                     # Type 143
Light.StateHevCycle                   # Type 144
Light.GetHevCycleConfiguration        # Type 145
Light.SetHevCycleConfiguration        # Type 146
Light.StateHevCycleConfiguration      # Type 147
Light.GetLastHevCycleResult           # Type 148
Light.StateLastHevCycleResult         # Type 149

# Multizone control (strips/beams)
MultiZone.SetColorZones       # Type 501
MultiZone.GetColorZones       # Type 502
MultiZone.StateZone           # Type 503
MultiZone.StateMultiZone      # Type 506
MultiZone.GetEffect           # Type 507
MultiZone.SetEffect           # Type 508
MultiZone.StateEffect         # Type 509

# Extended multizone
MultiZone.ExtendedSetColorZones       # Type 510
MultiZone.ExtendedGetColorZones       # Type 511
MultiZone.ExtendedStateMultiZone      # Type 512

# Tile/Matrix control (2D arrangements)
Tile.GetDeviceChain           # Type 701
Tile.StateDeviceChain         # Type 702
Tile.SetUserPosition          # Type 703
Tile.Get64                    # Type 707
Tile.State64                  # Type 711
Tile.Set64                    # Type 715
Tile.CopyFrameBuffer          # Type 716
Tile.GetEffect                # Type 718
Tile.SetEffect                # Type 719
Tile.StateEffect              # Type 720

# Ambient light sensor
Sensor.GetAmbientLight        # Type 401
Sensor.StateAmbientLight      # Type 402

# Buttons (switches)
Button.Get                    # Type 905
Button.Set                    # Type 906
Button.State                  # Type 907
Button.GetConfig              # Type 909
Button.SetConfig              # Type 910
Button.StateConfig            # Type 911

from lifx_emulator.protocol.packets import Light
from lifx_emulator.protocol.protocol_types import LightHsbk

# Create SetColor packet
packet = Light.SetColor(
    color=LightHsbk(hue=21845, saturation=65535, brightness=32768, kelvin=3500),
    duration=1000,  # Transition time in milliseconds
)

# Serialize to bytes
raw_payload = packet.pack()

# Parse from bytes
received_packet = Light.SetColor.unpack(raw_payload)
print(f"Color: H={received_packet.color.hue} S={received_packet.color.saturation}")
print(f"Duration: {received_packet.duration}ms")

from lifx_emulator.protocol.packets import MultiZone

# Request zones 0-7
packet = MultiZone.GetColorZones(
    start_index=0,
    end_index=7,
)

raw_payload = packet.pack()

from lifx_emulator.protocol.packets import Tile
from lifx_emulator.protocol.protocol_types import TileBufferRect

# Request 8x8 rectangle starting at (0,0) from tile 0
packet = Tile.Get64(
    tile_index=0,
    length=1,      # Number of tiles to read, starting at tile_index
    rect=TileBufferRect(fb_index=0, x=0, y=0, width=8),
)

raw_payload = packet.pack()

@dataclass
class LightHsbk:
    hue: int          # 0-65535 (0° to 360°)
    saturation: int   # 0-65535 (0% to 100%)
    brightness: int   # 0-65535 (0% to 100%)
    kelvin: int       # 1500-9000 (color temperature)

from lifx_emulator.protocol.protocol_types import LightHsbk

# Red at 50% brightness
red = LightHsbk(hue=0, saturation=65535, brightness=32768, kelvin=3500)

# Green at full brightness
green = LightHsbk(hue=21845, saturation=65535, brightness=65535, kelvin=3500)

# Blue at 75% brightness
blue = LightHsbk(hue=43690, saturation=65535, brightness=49152, kelvin=3500)

# Warm white (no color)
warm_white = LightHsbk(hue=0, saturation=0, brightness=65535, kelvin=2700)

# Cool white (no color)
cool_white = LightHsbk(hue=0, saturation=0, brightness=65535, kelvin=6500)

@dataclass
class TileStateDevice:
    accel_meas: TileAccelMeas               # Accelerometer reading (x, y, z)
    user_x: float                           # User-configured X position
    user_y: float                           # User-configured Y position
    width: int                              # Tile width in zones (e.g., 8)
    height: int                             # Tile height in zones (e.g., 8)
    device_version: DeviceStateVersion      # vendor, product
    firmware: DeviceStateHostFirmware       # build, version_minor, version_major

from lifx_emulator.protocol.protocol_types import (
    DeviceService,
    LightWaveform,
    LightLastHevCycleResult,
    MultiZoneEffectType,
    MultiZoneApplicationRequest,
    TileEffectType,
)

# Service types
DeviceService.UDP                          # 1

# Waveform types for Light.SetWaveform
LightWaveform.SAW                          # 0
LightWaveform.SINE                         # 1
LightWaveform.HALF_SINE                    # 2
LightWaveform.TRIANGLE                     # 3
LightWaveform.PULSE                        # 4

# Multizone effects
MultiZoneEffectType.OFF                    # 0
MultiZoneEffectType.MOVE                   # 1

# Tile effects
TileEffectType.OFF                         # 0
TileEffectType.MORPH                       # 2
TileEffectType.FLAME                       # 3
TileEffectType.SKY                         # 5

from lifx_emulator.protocol.header import LifxHeader
from lifx_emulator.protocol.packets import PACKET_REGISTRY, get_packet_class

# Get packet class by type number
packet_class = PACKET_REGISTRY[102]  # Light.SetColor
print(packet_class.PKT_TYPE)  # 102

# Or use the helper function
packet_class = get_packet_class(102)

# Parse unknown packet type
data = sock.recv(1024)
header = LifxHeader.unpack(data[:36])
raw_payload = data[36:]
packet_class = get_packet_class(header.pkt_type)
if packet_class:
    packet = packet_class.unpack(raw_payload)
else:
    print(f"Unknown packet type: {header.pkt_type}")

from lifx_emulator.protocol.header import LifxHeader
from lifx_emulator.protocol.packets import Light
from lifx_emulator.protocol.protocol_types import LightHsbk

# Create header
header = LifxHeader(
    size=0,  # Will be calculated
    source=12345,
    target=bytes.fromhex("d073d5000001") + b'\x00\x00',
    res_required=True,
    sequence=1,
    pkt_type=102,  # SetColor
)

# Create packet
packet = Light.SetColor(
    color=LightHsbk(hue=21845, saturation=65535, brightness=32768, kelvin=3500),
    duration=1000,  # Transition time in milliseconds
)

# Pack to binary
payload = packet.pack()
header.size = 36 + len(payload)
header_bytes = header.pack()

# Send over UDP
full_packet = header_bytes + payload
sock.sendto(full_packet, (device_ip, 56700))

from lifx_emulator.protocol.header import LifxHeader
from lifx_emulator.protocol.packets import get_packet_class

# Receive packet
data, addr = sock.recvfrom(1024)

# Parse header
header = LifxHeader.unpack(data[:36])
print(f"Received packet type: {header.pkt_type}")

# Parse payload
packet_class = get_packet_class(header.pkt_type)
if packet_class:
    payload_data = data[36:]
    packet = packet_class.unpack(payload_data)
    print(f"Packet: {packet}")
else:
    print(f"Unknown packet type: {header.pkt_type}")

import socket
from lifx_emulator.protocol.header import LifxHeader
from lifx_emulator.protocol.packets import Light
from lifx_emulator.protocol.protocol_types import LightHsbk

# Create UDP socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.settimeout(2.0)

# Build GetService request (discovery)
header = LifxHeader(
    size=36,
    tagged=True,  # Broadcast
    source=12345,
    res_required=True,
    sequence=1,
    pkt_type=2,  # GetService
)

# Send discovery
sock.sendto(header.pack(), ('<broadcast>', 56700))

# Receive StateService response
data, addr = sock.recvfrom(1024)
resp_header = LifxHeader.unpack(data[:36])
print(f"Device found at {addr}: serial={resp_header.target[:6].hex()}")

# Get light state
header = LifxHeader(
    size=36,
    source=12345,
    target=resp_header.target,
    res_required=True,
    sequence=2,
    pkt_type=101,  # Light.GetColor
)
sock.sendto(header.pack(), addr)

# Receive Light.StateColor (107) response
data, addr = sock.recvfrom(1024)
resp_header = LifxHeader.unpack(data[:36])
state = Light.StateColor.unpack(data[36:])
print(f"Color: H={state.color.hue} S={state.color.saturation} B={state.color.brightness}")
print(f"Power: {state.power}")
print(f"Label: {state.label}")

sock.close()

from lifx_emulator.protocol.header import LifxHeader
from lifx_emulator.protocol.packets import Light

payload = Light.SetPower(level=65535, duration=0).pack()

# Request acknowledgment
header = LifxHeader(
    size=36 + len(payload),
    source=12345,
    target=device_target,
    ack_required=True,  # Request ack
    res_required=False,  # Don't need state response
    sequence=3,
    pkt_type=117,  # SetPower
)

sock.sendto(header.pack() + payload, addr)

# Wait for acknowledgment (type 45)
data, addr = sock.recvfrom(1024)
ack_header = LifxHeader.unpack(data[:36])
if ack_header.pkt_type == 45:
    print("Command acknowledged")

import colorsys

from lifx_emulator.protocol.protocol_types import LightHsbk

def hsbk_to_rgb(hsbk: LightHsbk) -> tuple[int, int, int]:
    """Convert HSBK to RGB (0-255 range)."""
    h = hsbk.hue / 65535.0  # 0-1
    s = hsbk.saturation / 65535.0  # 0-1
    v = hsbk.brightness / 65535.0  # 0-1

    r, g, b = colorsys.hsv_to_rgb(h, s, v)
    return int(r * 255), int(g * 255), int(b * 255)

import colorsys

from lifx_emulator.protocol.protocol_types import LightHsbk

def rgb_to_hsbk(r: int, g: int, b: int, kelvin: int = 3500) -> LightHsbk:
    """Convert RGB (0-255) to HSBK."""
    h, s, v = colorsys.rgb_to_hsv(r / 255.0, g / 255.0, b / 255.0)

    return LightHsbk(
        hue=int(h * 65535),
        saturation=int(s * 65535),
        brightness=int(v * 65535),
        kelvin=kelvin,
    )

def percent_to_uint16(percent: float) -> int:
    """Convert percentage (0-100) to uint16 (0-65535)."""
    return int(percent * 65535 / 100)

def uint16_to_percent(value: int) -> float:
    """Convert uint16 (0-65535) to percentage (0-100)."""
    return value * 100 / 65535