Lightstrip, String, Neon and Beam

Several LIFX products consist of multiple light zones in a line. We say these devices have a Linear layout of zones and we can use the MultiZone messages on these devices to control each zone. In these devices, each zone is represented by an index starting at 0, with 0 being the zone closest to the controller.

We have two APIs for these products: Legacy Multizone and Extended Multizone.

The legacy messages are only required for older LIFX Z products, however all products still support the legacy messages. The Extended Multizone messages are preferable if your device supports them as they can be used to retrieve color information much more efficiently.

📘

Backwards Compatibility

When not using the MultiZone Messages the whole device is controlled. For example if you send a SetColor (102) message to the device, all zones will change to the chosen color. This means applications that already support the current protocol do not need to make any changes to support whole device control.

Extended Multizone Messages

You may refer to the Product Registry for how to tell if the device you want to control supports these messages.

We introduced the Extended Multizone messages so that you may control/query all the zones with significantly fewer messages. We found that the legacy messages didn't scale well to certain use cases.

📘

The Extended messages have a fixed size of 82 zones. If a device has fewer than 82 zones, then some zones will contain all 0 values. When devices have more than 82 zones, they'll return multiple messages with different starting zone_index. It is important to check the zone_count property to know how many zones the device has in total.

Legacy Multizone messages

We recommend using extended messages where you can. For devices that don't support those messages, you have the legacy messages available to you.

To query the entire strip you would ask the strip to tell you the value of all it's zones and then it would respond with multiple packets for each 8 zone section of the strip.

When changing the strip you may only specify one color for each contiguous section of the zone. So if you wanted red for three zones, blue for the next 2 zones and then red for 5 zones after that, you would have to send three messages to the device.

This means if your 82 zone strip has a different color for each zone, you would end up sending 82 separate messages to the device.

If you would like to set the whole strip to a single color either use the SetColorZones (501) message with start_index set to 0 and the end_index set to 255, or use a SetColor (102) message instead.

If you want to alter the entire strip to use different colors (such as a rainbow) there are two approaches we suggest.

• Send a single SetColorZones (501) message for each zone starting with 0 and ending at the last zone on the device, setting apply to APPLY. This will make the strip appear to 'load' the new settings reminiscent of a progress bar.

• Use the apply field to buffer all the changes before applying them with the last change you wish to make. Send a message for each zone with the apply field set to NO_APPLY. This makes the device store the changes in a buffer. Then send the final message with the apply field set to APPLY which will cause the device to apply all the change in the message along with all the changes in the buffer at once.