This documentation is intended for third-party developers creating client applications, which interact with LIFX lightbulbs over the LAN by sending and receiving, then parsing LIFX Protocol messages.
The LIFX Protocol consists of messages that are used to control and obtain the state of devices (specifically lightbulbs).
Each message is composed of a header and a payload.
Headers contain the message size, type, routing, response flags and more. Payloads contain information germane to a specific message type.
To interact with LIFX lightbulbs over the Internet (Cloud or WAN), see the LIFX HTTP API documention.
The LIFX Protocol utilizes UDP/IP for all messages covered by this documentation.
Numeric data-type byte-order is little-endian
All LIFX Protocol messages start with the header, which is covered in the Header Description.
The header contains the message type field. There are two categories of messages detailed in this documentation:
- Messages understood by all devices
- Those messages specific to lightbulbs.
Most interactions consist of a number of messages transmitted between the client and the device. Some common message exchanges are shown in the Workflow Diagrams.
A machine readable definition of the available messages can be found at https://github.com/LIFX/public-protocol
Most LIFX messages come in triplets. A Get, a Set and a State. So for example, GetLabel will ask the device for a label, which is returned to you as a StateLabel. SetLabel will set the label on the device and give back a StateLabel.
Note that you can change what is returned using the
res_required flags. If
true then you will get an Acknowledgement message (pkt type 45) as well as the State message; and a State message is only given back to you if
res_required is true.
The one exception to this triplet rule is a GetColor/SetWaveform/SetWaveformOptional message will send back a LightState message (pkt type 107).
- Maximum recommended message transmit rate to a device: 20 per second
Using undocumented message types or field values, sending poorly formed messages or excessive message rates to LIFX devices and/or LIFX services may result in unexpected device or protocol message behavior.
LAN Protocol. © LIFX Inc. All rights reserved. Usage of this documentation is bound by the LIFX Developer Terms.
Updated 11 days ago