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.

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.

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.

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).

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.

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.

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

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

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

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

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.

StatePower - 22

Response to GetPower message.

Provides device power level.

GetLabel - 23

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

SetLabel - 24

Set the device label text.

StateLabel - 25

Response to GetLabel message.

Provides device label.

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

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)

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.

StateLocation - 50

Device location.

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.

StateGroup - 53

Device group.

EchoRequest - 58

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

EchoResponse - 59

Response to EchoRequest message.

Echo response with payload sent in the EchoRequest.