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    

Device Messages

Device messages control and acquire the state of a device, independent of its specific type. The state is composed of the label, port, power level, time, firmware version and microcontroller statistics.

These messages are common to all LIFX devices, which may also implement device specific messages, such as Light Messages.

The Protocol header message type field value (decimal) appears after each message name in this document. Each section below describes the payload that is appended to the message header. Some messages do not require a payload.

Enumerated Types

Service

Describes the services exposed by the device.

Type

Value

UDP

1

When a device is discovered the Service types and IP port are provided.

All values other than those documented above are reserved for future protocol expansion.

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

Message Field Data Types

Labels

For user interfaces purposes, each device can be identified by their label as well as a group and a location.

Field

Type

label

string, size: 32 bytes

The label string is a fixed-length field, which is not null-terminated.

If you are setting a label/group/location for your light, it is highly recommended you store the label as a utf-8 string for compatibility with existing clients.

Port

The IP port number used by a LIFX device for a specific Service.

FieldType
portunsigned 32-bit integer

Whilst LIFX devices usually listen to port 56700, it is strongly recommended that devices are discovered and the provided port number is used.

As of LIFX Protocol V2, LIFX devices sending unicast message responses will reply to whichever port number the client has bound. See message header frame source identifier regarding the conditions under which unicast messages are sent.

Prior to LIFX Protocol V2, i.e the Original LIFX A21 lightbulb running firmware version 1.x, LIFX devices send broadcast message responses to port 56700.

To get the best compatibility across both newer and older LIFX devices, clients should bind to UDP port 56700.

Power level

The power level can be either standby (0) or enabled (65535).

FieldType
levelunsigned 16-bit integer

Currently, only the values 0 and 65535 are supported

Time

All time values have a precision of nanoseconds. When an absolute time value is provided, then it is the number of nanoseconds since the epoch, i.e Thursday 1st January 1970 00:00:00.

FieldType
timeunsigned 64-bit integer

Device Messages

GetService - 2

Sent by a client to acquire responses from all devices on the local network. No payload is required. Causes the devices to transmit a StateService message.

When using this message the Frame tagged field must be set to one (1).

StateService - 3

Response to GetService message.

Provides the device Service and port. If the Service is temporarily unavailable, then the port value will be 0.

FieldType
serviceunsigned 8-bit integer, maps to Service
portunsigned 32-bit integer

GetHostInfo - 12

Get Host MCU information. No payload is required. Causes the device to transmit a StateHostInfo message.

StateHostInfo - 13

Response to GetHostInfo message.

Provides host MCU information.

  • signal: radio receive signal strength in milliWatts
  • tx: bytes transmitted since power on
  • rx: bytes received since power on
FieldType
signal32-bit float
txunsigned 32-bit integer
rxunsigned 32-bit integer
reservedsigned 16-bit integer

GetHostFirmware - 14

Gets Host MCU firmware information. No payload is required. Causes the device to transmit a StateHostFirmware message.

StateHostFirmware - 15

Response to GetHostFirmware message.

Provides host firmware information.

  • build: firmware build time (absolute time in nanoseconds since epoch)
  • version: firmware version
FieldType
buildunsigned 64-bit integer
reservedunsigned 64-bit integer
version_minorunsigned 16-bit integer
version_majorunsigned 16-bit integer

GetWifiInfo - 16

Get Wifi subsystem information. No payload is required. Causes the device to transmit a StateWifiInfo message.

StateWifiInfo - 17

Response to GetWifiInfo message.

Provides Wifi subsystem information.

  • signal: radio receive signal strength in mw or signal to noise ratio
  • tx: bytes transmitted since power on
  • rx: bytes received since power on
FieldType
signal32-bit float
txunsigned 32-bit integer
rxunsigned 32-bit integer
reservedsigned 16-bit integer

Note that while most of our products report wifi rssi in the signal property, some products will report signal to noise ratio. The following code can be used to determine the strength of the wifi signal from this value:

import math

signal = "[value from the StateWifiInfo.Signal property]"

val = math.floor(10 * math.log10(signal) + 0.5)

if val < 0 or val == 200:
    # The value is wifi rssi

    if val == 200:
        return "No signal"
    elif val <= -80:
        return "Very bad signal"
    elif val <= -70:
        return "Somewhat bad signal"
    elif val < -60:
        return "Alright signal"
    else:
        return "Good signal"
else:
    # The value is signal to noise ratio
    
    if val == 4 or val == 5:
        return "Very bad signal"
    elif val >= 7 and val <= 11:
        return "Somewhat bad signal"
    elif val >= 12 and val <= 16:
        return "Alright signal"
    elif val > 16:
        return "Good signal"
    else:
        return "No signal"

GetWifiFirmware - 18

Get Wifi subsystem firmware. No payload is required. Causes the device to transmit a StateWifiFirmware message.

StateWifiFirmware - 19

Response to GetWifiFirmware message.

Provides Wifi subsystem information.

  • build: firmware build time (absolute time in nanoseconds since epoch)
  • version: firmware version
FieldType
buildunsigned 64-bit integer
reservedunsigned 64-bit integer
version_minorunsigned 16-bit integer
version_majorunsigned 16-bit integer

GetPower - 20

Get device power level. No payload is required. Causes the device to transmit a StatePower message.

SetPower - 21

Set device power level.

Zero implies standby and non-zero sets a corresponding power draw level. Currently only 0 and 65535 are supported.

FieldType
levelunsigned 16-bit integer

StatePower - 22

Response to GetPower message.

Provides device power level.

FieldType
levelunsigned 16-bit integer

GetLabel - 23

Get device label. No payload is required. Causes the device to transmit a StateLabel message.

SetLabel - 24

Set the device label text.

FieldType
labelstring, size: 32 bytes

StateLabel - 25

Response to GetLabel message.

Provides device label.

FieldType
labelstring, size: 32 bytes

GetVersion - 32

Get the hardware version. No payload is required. Causes the device to transmit a StateVersion message.

StateVersion - 33

Response to GetVersion message.

Provides the hardware version of the device. See LIFX Products for how to interpret the vendor and product ID fields.

  • vendor: vendor ID
  • product: product ID
  • version: hardware version
FieldType
vendorunsigned 32-bit integer
productunsigned 32-bit integer
versionunsigned 32-bit integer

GetInfo - 34

Get run-time information. No payload is required. Causes the device to transmit a StateInfo message.

StateInfo - 35

Response to GetInfo message.

Provides run-time information of device.

  • time: current time (absolute time in nanoseconds since epoch)
  • uptime: time since last power on (relative time in nanoseconds)
  • downtime: last power off period, 5 second accuracy (in nanoseconds)
FieldType
timeunsigned 64-bit integer
uptimeunsigned 64-bit integer
downtimeunsigned 64-bit integer

Acknowledgement - 45

Response to any message sent with ack_required set to 1. See message header frame address.

GetLocation - 48

Ask the bulb to return its location information.
No payload is required.
Causes the device to transmit a StateLocation message.

SetLocation - 49

Set the device location.

Applications wishing to change either the label or location attributes MUST set the updated_at field to the current timestamp and send the message to all applicable devices that are currently online. This is because when reading these values the applications will consider unique location fields to be a location identifier, and the label on the bulb with the highest updated_at field for that location will be used. Applications SHOULD attempt to correct any labels that are out of date when found.
It is recommended to set the response_required flag on the message header to speed up updating the cloud account.

When creating a new location generate the location field with random data.

  • location: guid byte array.
  • label: text label for location.
  • updated_at: UTC timestamp of last label update in nanoseconds.
FieldType
locationbyte array, size: 16
labelstring, size: 32
updated_atinteger, size: 64

StateLocation - 50

Device location.

FieldType
locationbyte array, size: 16 bytes
labelstring, size: 32 bytes
updated_atunsigned 64-bit integer

GetGroup - 51

Ask the bulb to return its group membership information.
No payload is required.
Causes the device to transmit a StateGroup message.

SetGroup - 52

Set the device group.

Applications wishing to change either the label or group attributes MUST set the updated_at field to the current timestamp and send the message to all applicable devices that are currently online. This is because when reading these values the applications will consider unique group fields to be a group identifier, and the label on the bulb with the highest updated_at field for that group will be used. Applications SHOULD attempt to correct any labels that are out of date when found.
It is recommended to set the response_required flag on the message header to speed up updating the cloud account.

When creating a new group generate the group field with random data.

  • group: guid byte array.
  • label: text label for group.
  • updated_at: UTC timestamp of last label update in nanoseconds.
FieldType
groupbyte array, size: 16
labelstring, size: 32
updated_atinteger, size: 64

StateGroup - 53

Device group.

FieldType
groupbyte array, size: 16 bytes
labelstring, size: 32 bytes
updated_atunsigned 64-bit integer

EchoRequest - 58

Request an arbitrary payload be echoed back. Causes the device to transmit an EchoResponse message.

FieldType
payloadbyte array, size: 64 bytes

EchoResponse - 59

Response to EchoRequest message.

Echo response with payload sent in the EchoRequest.

FieldType
payloadbyte array, size: 64 bytes

Updated less than a minute ago

Device Messages


Suggested Edits are limited on API Reference Pages

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