Querying the device for data

The LIFX protocol supplies a number of Get messages for getting information from the LIFX devices. When you send these messages to the device with the res_required flag set to 0 you will get one or more State messages in response.

Below you will find the type of the message, the fields that make up the payload of the message, the information you get from the request, and how many State messages you should expect in response.

Note that unless specified these packets have an empty payload.

Discovery

GetService - Packet 2

This packet is used for Discovery of devices. Typically you would broadcast this message to the network (with tagged field in the header set to 0 and the target field in the header set to all zeros)

Each device on the network that receives this packet will send back multiple StateService (3) messages that say what services are available and the port those services are on.

The only StateService (3) message you care about will tell you that UDP is available on a port that is usually 56700. You can determine the IP address of the device from information your UDP socket should receive when it gets those bytes.

Device

GetHostFirmware - Packet 14

This is used to determine the version of the firmware you have on your device. Typically you would use this information to determine the capabilities of your device as specified in our Product Registry.

Will return one StateHostFirmware (15) message

GetWifiInfo - Packet 16

This packet is used to determine the signal strength of the device.

Will return one StateWifiInfo (17) message

GetWifiFirmware - Packet 18

Our first and second generation devices have separate wifi firmware to the host firmware. For these devices, this message will return the version of the wifi firmware on the device. This message can be used to determine the version of this firmware.

Will return one StateWifiFirmware (19) message

GetPower - Packet 20

This packet can be used to determine the power level of the device.

Will return one StatePower (22) message

GetLabel - Packet 23

This packet can be used to determine the label set on the device.

Will return one StateLabel (25) message

GetVersion - Packet 32

This packet can be used to determine the product type of the device.

Typically this information is used to determine what capabilities the device has as defined by our Product Registry.

Will return one StateVersion (33) message

GetInfo - Packet 34

This can be used to determine the uptime and downtime of the device. As well as the current time according to the device.

Will return one StateInfo (35) message

GetLocation - Packet 48

This packet can be used to determine the uuid and label of the location assigned to this device.

Will return one StateLocation (50) message

GetGroup - Packet 51

This packet can be used to determine the uuid and label of the group assigned to this device.

Will return one StateGroup (53) message

EchoRequest - Packet 58

This packet can be used to check that a device is online and responding to you.

Will return one EchoResponse (59) message

echoing: 64 Bytes
The bytes you want to receive in the EchoResponse (59) message.

Light

GetColor - Packet 101

This packet is used to get the current visual state of the device.

Will return one LightState (107) message

GetLightPower - Packet 116

Like GetPower (20) this packet will return the current power level of the device.

Will return one StateLightPower (118) message

GetInfrared - Packet 120

This packet is used to determine the current infrared level of the device.

Will return one StateInfrared (121) message

This packet requires the device has the infrared capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

GetHevCycle - Packet 142

This packet is used to determine the state of the HEV LEDs on the device

Will return one StateHevCycle (144) message

This packet requires the device has the hev capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

GetHevCycleConfiguration - Packet 145

This packet is used to determine the default configuration for using the HEV LEDs on the device.

Will return one StateHevCycleConfiguration (147) message

This packet requires the device has the hev capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

GetLastHevCycleResult - Packet 148

This packet is used to determine the result of the last HEV cycle that was run

Will return one StateLastHevCycleResult (149) message

This packet requires the device has the hev capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

MultiZone

GetColorZones - Packet 502

There are two possible messages that this request may return. If the number of zones in the response is just one then you will get a single StateZone (503). Otherwise you will get one or more StateMultiZone (506) replies.

You can determine how many StateMultizone messages you will receive by looking at the request and the first reply.

Some pseudo code would look like this:

number_segments_of_8 = (request.end_index - request.start_index) / 8
count_from_request = maximum(1, floor(number_segements_of_8) + 1)

count_from_response = ceil(first_response.zone_count / 8)

expected_number_of_messages = minimum(count_from_request, count_from_response)

Note that if you want all the zones to be returned to you, you should set start_index to 0 and end_index to 255

This packet requires the device has the Linear Zones capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

start_index: Uint8
The first zone you want to get information from
end_index: Uint8
The second zone you want to get information from

GetMultiZoneEffect - Packet 507

This packet can be used to determine if the device is currently running a multizone Firmware Effect.

Will return one StateMultiZoneEffect (509) message

This packet requires the device has the Linear Zones capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

GetExtendedColorZones - Packet 511

This packet can be used to get response packets containing the HSBK values for every zone on your strip.

Will return StateExtendedColorZones (512) messages. If the light has more than 82 zones, then multiple responses shall be returned with different zone_index values. The value of the zone_count property shall indicate the total number of zones on the device.

This packet requires the device has the Extended Linear Zones capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

Relay

GetRPower - Packet 816

Get the power state of a relay on a switch device.

Will return one StateRPower (818) message

This packet requires the device has the Relays capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

relay_index: Uint8
The relay on the switch starting from 0.

Tile

GetDeviceChain - Packet 701

This packet can be used to get information about all the devices in the chain. Note that for LIFX Tiles this will only ever be up to 5 devices and for the LIFX Candle it will only be 1 device.

Will return one StateDeviceChain (702) message

This packet requires the device has the Matrix Zones capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

Get64 - Packet 707

Used to get the HSBK values of all the zones in devices connected in the chain.

this will return one or more State64 (711) messages. The maximum number of messages you will receive is the number specified by length in your request.

This packet requires the device has the Matrix Zones capability. You may use GetVersion (32), GetHostFirmware (14) and the Product Registry to determine whether your device has this capability

tile_index: Uint8
The first item in the chain you want zones
length: Uint8
The number of tiles after tile_index you want HSBK values from.
reserved6: 1 Reserved bytes
x: Uint8
The x value to start from. You likely always want this to be 0.
y: Uint8
The y value to start from. You likely always want this to be 0.
width: Uint8
The width of each item in the chain. For the LIFX Tile you want this to be 8 and for the LIFX Candle you want this to be 5.

GetTileEffect - Packet 718

Used to determine if the device is running a Firmware Effect.

Will return one StateTileEffect (720) message

reserved6: 1 Reserved bytes
reserved7: 1 Reserved bytes

SensorGetAmbientLight - Packet 401

Used to get the current ambient light level from a device. Device will return a SensorStateAmbientLight (402) message.