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

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.

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.