Communicating with a device

All LIFX packets are sent over UDP to each device on port 56700. UDP is a state-less protocol where you send bytes to a remote destination without first making a specific connection to the destination. If the device you sent bytes to decides to send information back, your UDP socket will receive those bytes.

There are five scenarios with sending packets to a device:

Broadcasting a message to everything on the network (i.e. discovery)
Sending a message and getting back just an Acknowledgment
Sending a message and getting back just a State message
Sending a message and getting both an Acknowledgement and a State message
Sending a message and getting no reply

Discovery

There are two supported forms of discovery for LIFX devices. Broadcast discovery is supported on all devices, while mDNS-based discovery is only supported on newer devices. mDNS discovery is more efficient and should always be the first choice if you don't need to work with older devices.

Broadcast Discovery

Send GetService (2) as a UDP broadcast to port 56700 with the Frame Header tagged field set to 1.
All devices on LAN should respond back with one or more StateService (3) messages.
Clients can then send further messages directly to individual devices or broadcast them.

mDNS Discovery

mDNS discovery relies on a custom Multicast DNS service, that is provided by all LIFX devices running firmware 4.110 or higher. This is the new method of LIFX device discovery, and will be the preferred method going forward.

The LIFX mDNS service is _lifx._udp and it provides several TXT record values to allow for quickly identifying what kind of device it is.

id Serial number of the device. This should always be used instead of looking at the service name (You cannot assume the service name will always match the serial number)
fw Semantic version of current firmware (e.g. 4.110)
p Product ID of the device

Request with acknowledgement

Discover devices as above.
Set the source field with a unique 32-bit number, it does not have to be globally unique.
Use the wrap around sequence as a message ID.
Set the ack_required field to 1
Send message and it is acknowledged with Acknowledgement (45) having same source and sequence.

Note that Get messages will also send back a State response, even if the res_required field is set to 0.

Request with response

Discover devices as above.
Set the source field with a unique 32-bit number, it does not have to be globally unique.
Use the wrap around sequence as a message ID.
Send a Get message and/or set the res_required field to 1
Send message and a corresponding semantic reply is sent back having same source and sequence.

We recommend not relying on State messages when you send a Set message as the State is likely the state before the change.

Request with acknowledgement and response

When a request receives a State message and also requests an acknowledgement, the ack will be sent to you just before the device processes the message.

Request without acknowledgement or response

If you send a packet with ack_required and res_required set to false and the message is not a Get message: then your device may or may not receive your packet and no response will be sent back to you. In this case you may want to query the device at some point in the future to determine if your packet had an impact on the device.