LIFX LAN Protocol

The LIFX LAN Protocol Developer Hub

Welcome to the LIFX LAN Protocol developer hub. You'll find comprehensive guides and documentation to help you start working with LIFX LAN Protocol as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Introduction

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.

Transport Layer

The LIFX Protocol utilizes UDP/IP for all messages covered by this documentation.

Numeric data-type byte-order is little-endian

Message Description

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.

The message type determines the format of payload. The various message payloads are covered in the Device Messages and Light Messages messages documentation.

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.

Often, device discovery is a good place to start. In which case, the discovery workflow, along with the Device::GetService and the Device::StateService messages are relevant.

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 ack_required and res_required flags. If ack_required is 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).

Limits

  • Maximum recommended message transmit rate to a device: 20 per second

Terms and Conditions

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

Introduction


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.