Z and Beam

The 1st and 2nd generation LIFX Z, and the LIFX Beam consist of multiple zones that form 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 and the maximum number of zones being 82. When working with one of these devices, you can ask the device how many zones it currently has.

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

Currently, only the LIFX Beam and second generation LIFX Z support the Extended messages if they have new enough firmware. All devices and firmware versions support the Legacy messages.

📘

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 one message instead of many. 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 less than 82 zones, then some zones will contain all 0 values. It is important to always check the count property in the message to check how many zones are valid.

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.