LIFX Developer Home | LAN Protocol. LiFi Labs, Inc. © 2015. All rights reserved. Usage of this documentation is bound by the [LIFX Developer Terms] (http://developer.lifx.com/terms.html).
- Overview
- Enumerated types
- Message field data types
- Device messages - message type value
- GetService - 2
- StateService - 3
- GetHostInfo - 12
- StateHostInfo - 13
- GetHostFirmware - 14
- StateHostFirmware - 15
- GetWifiInfo - 16
- StateWifiInfo - 17
- GetWifiFirmware - 18
- StateWifiFirmware - 19
- GetPower - 20
- SetPower - 21
- StatePower - 22
- GetLabel - 23
- SetLabel - 24
- StateLabel - 25
- GetVersion - 32
- StateVersion - 33
- GetInfo - 34
- StateInfo - 35
- Acknowledgement - 45
- GetLocation - 48
- StateLocation - 50
- GetGroup - 51
- StateGroup - 53
- EchoRequest - 58
- EchoResponse - 59
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.
Describes the services exposed by the device.
| Type | Value |
|---|---|
| UDP | 1 |
When a device is discovered the Service types and IP port are provided.
The LIFX Protocol utilizes UDP/IP for all messages covered by this documentation.
All values other than those documented above are reserved for future protocol expansion.
For user interfaces purposes, each device can be identified by their label.
| Field | Type |
|---|---|
| label | string, size: 32 bytes |
The label string is a fixed-length field, which is not null-terminated.
The IP port number used by a LIFX device for a specific Service.
| Field | Type |
|---|---|
| port | unsigned 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.
The power level can be either standby (0) or enabled (65535).
| Field | Type |
|---|---|
| level | unsigned 16-bit integer |
Currently, only the values 0 and 65535 are supported
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.
| Field | Type |
|---|---|
| time | unsigned 64-bit integer |
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).
Response to GetService message.
Provides the device Service and port. If the Service is temporarily unavailable, then the port value will be 0.
| Field | Type |
|---|---|
| service | unsigned 8-bit integer, maps to Service |
| port | unsigned 32-bit integer |
Get Host MCU information. No payload is required. Causes the device to transmit a StateHostInfo message.
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
| Field | Type |
|---|---|
| signal | 32-bit float |
| tx | unsigned 32-bit integer |
| rx | unsigned 32-bit integer |
| reserved | signed 16-bit integer |
Gets Host MCU firmware information. No payload is required. Causes the device to transmit a StateHostFirmware message.
Response to GetHostFirmware message.
Provides host firmware information.
- build: firmware build time (absolute time in nanoseconds since epoch)
- version: firmware version
| Field | Type |
|---|---|
| build | unsigned 64-bit integer |
| reserved | unsigned 64-bit integer |
| version | unsigned 32-bit integer |
Get Wifi subsystem information. No payload is required. Causes the device to transmit a StateWifiInfo message.
Response to GetWifiInfo message.
Provides Wifi subsystem information.
- signal: radio receive signal strength in mw
- tx: bytes transmitted since power on
- rx: bytes received since power on
| Field | Type |
|---|---|
| signal | 32-bit float |
| tx | unsigned 32-bit integer |
| rx | unsigned 32-bit integer |
| reserved | signed 16-bit integer |
Get Wifi subsystem firmware. No payload is required. Causes the device to transmit a StateWifiFirmware message.
Response to GetWifiFirmware message.
Provides Wifi subsystem information.
- build: firmware build time (absolute time in nanoseconds since epoch)
- version: firmware version
| Field | Type |
|---|---|
| build | unsigned 64-bit integer |
| reserved | unsigned 64-bit integer |
| version | unsigned 32-bit integer |
Get device power level. No payload is required. Causes the device to transmit a StatePower message.
Set device power level.
Zero implies standby and non-zero sets a corresponding power draw level. Currently only 0 and 65535 are supported.
| Field | Type |
|---|---|
| level | unsigned 16-bit integer |
Response to GetPower message.
Provides device power level.
| Field | Type |
|---|---|
| level | unsigned 16-bit integer |
Get device label. No payload is required. Causes the device to transmit a StateLabel message.
Set the device label text.
| Field | Type |
|---|---|
| label | string, size: 32 bytes |
Response to GetLabel message.
Provides device label.
| Field | Type |
|---|---|
| label | string, size: 32 bytes |
Get the hardware version. No payload is required. Causes the device to transmit a StateVersion message.
Response to GetVersion message.
Provides the hardware version of the device.
- vendor: vendor ID
- product: product ID
- version: hardware version
| Field | Type |
|---|---|
| vendor | unsigned 32-bit integer |
| product | unsigned 32-bit integer |
| version | unsigned 32-bit integer |
Get run-time information. No payload is required. Causes the device to transmit a StateInfo message.
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)
| Field | Type |
|---|---|
| time | unsigned 64-bit integer |
| uptime | unsigned 64-bit integer |
| downtime | unsigned 64-bit integer |
Response to any message sent with ack_required set to 1. See message header frame address.
Ask the bulb to return its location information. No payload is required. Causes the device to transmit a StateLocation message.
Device location.
| Field | Type |
|---|---|
| location | byte array, size: 16 |
| label | string, size: 32 |
| updated_at | unsigned 64-bit integer |
Ask the bulb to return its group membership information. No payload is required. Causes the device to transmit a StateGroup message.
Device group.
| Field | Type |
|---|---|
| group | byte array, size: 16 |
| label | string, size: 32 |
| updated_at | unsigned 64-bit integer |
Request an arbitrary payload be echoed back. Causes the device to transmit an EchoResponse message.
| Field | Type |
|---|---|
| payload | byte array, size: 64 bytes |
Response to EchoRequest message.
Echo response with payload sent in the EchoRequest.
| Field | Type |
|---|---|
| payload | byte array, size: 64 bytes |