{"__v":1,"_id":"57fdd21bb3d2960e007f5ce3","category":{"project":"5581248904ae5b0d0026289a","version":"57fdb17c4defec0e0064228b","_id":"57fdb520bcc07b0e00d1ef41","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-10-12T03:59:28.475Z","from_sync":false,"order":1,"slug":"guides","title":"Guides"},"project":"5581248904ae5b0d0026289a","user":"557e2561eb75d80d00af3dab","version":{"__v":2,"_id":"57fdb17c4defec0e0064228b","project":"5581248904ae5b0d0026289a","createdAt":"2016-10-12T03:43:56.009Z","releaseDate":"2016-10-12T03:43:56.009Z","categories":["57fdb17c4defec0e0064228c","57fdb17c4defec0e0064228d","57fdb17c4defec0e0064228e","57fdb520bcc07b0e00d1ef41"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-12T06:03:07.125Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":999,"body":"MultiZone lights are single devices that contain more than a single light source. The first such device is the [LIFX Z](http://www.lifx.com/products/lifx-plus) Light Strip. To discover the MultiZone capability on your devices refer to the details on the [LIFX Products](doc:lifx-products) page. We also provide a [machine readable version](https://github.com/LIFX/products) of the product database for embedding inside your applications on Github.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"When not using the [MultiZone Messages](doc:multizone-messages) the whole device is controlled. For example if you send a [SetColor](doc:light-messages#section-setcolor-102) message to the bulb, 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.\",\n  \"title\": \"Backwards Compatibility\"\n}\n[/block]\n\nIn MultiZone devices each zone is represented by an index. For the [LIFX Z](http://www.lifx.com/products/lifx-plus) the zones start at 0, being the closest zone to the controller and increases with each zone leading away from the controller. Different devices will have different methods for numbering their zones.\n\n## Individual Zone Control\n\nThe color of individual zones can be queried with the [MultiZone::GetColorZones](doc:multizone-messages#section-getcolorzones-502) message. This will ask the bulb to return the values of the zones starting with `start_zone` and ending with `end_zone`. The bulb will decide to return the messages as either [MultiZone::StateZone](doc:multizone-messages#section-statezone-503) or [MultiZone::StateMultiZone](doc:multizone-messages#section-statemultizone-506) messages, so your application needs to be able to handle both.\n\nIf you wish to read all zones on the device set `start_zone` to 0 and `end_zone` to 255.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The bulb may return the details for more zones than your application requested. The additional zones may be beyond the zones available on the device, in which case they should be ignored, however zones within the limits will be correct and can be used to update any UI or cache that you may have in the application.\"\n}\n[/block]\nControlling individual zones is done with the [MultiZone::SetColorZones](doc:multizone-messages#section-setcolorzones-501) message. This message takes a single HSBK value and sets that color on all zones between `start_index` and `end_index` inclusive.\n\n## Changing All Zones\nIf you would like to set the whole strip to a single color either use the [MultiZone::SetColorZones](doc:multizone-messages#section-setcolorzones-501) message with `start_index` set to 0 and the `end_index` set to 255, or use a [Light::SetColor](doc:light-messages#section-setcolor-102) message instead.\n\nIf you want to alter the entire strip to use different colors (such as a rainbow) there are two approaches we suggest.\n\n* Send a single [MultiZone::SetColorZones](doc:multizone-messages#section-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.\n\n* 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.","excerpt":"Controlling lights that have more than one light source such as the LIFX Z","slug":"multizone-light-control","type":"basic","title":"MultiZone Light Control"}

MultiZone Light Control

Controlling lights that have more than one light source such as the LIFX Z

MultiZone lights are single devices that contain more than a single light source. The first such device is the [LIFX Z](http://www.lifx.com/products/lifx-plus) Light Strip. To discover the MultiZone capability on your devices refer to the details on the [LIFX Products](doc:lifx-products) page. We also provide a [machine readable version](https://github.com/LIFX/products) of the product database for embedding inside your applications on Github. [block:callout] { "type": "info", "body": "When not using the [MultiZone Messages](doc:multizone-messages) the whole device is controlled. For example if you send a [SetColor](doc:light-messages#section-setcolor-102) message to the bulb, 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.", "title": "Backwards Compatibility" } [/block] In MultiZone devices each zone is represented by an index. For the [LIFX Z](http://www.lifx.com/products/lifx-plus) the zones start at 0, being the closest zone to the controller and increases with each zone leading away from the controller. Different devices will have different methods for numbering their zones. ## Individual Zone Control The color of individual zones can be queried with the [MultiZone::GetColorZones](doc:multizone-messages#section-getcolorzones-502) message. This will ask the bulb to return the values of the zones starting with `start_zone` and ending with `end_zone`. The bulb will decide to return the messages as either [MultiZone::StateZone](doc:multizone-messages#section-statezone-503) or [MultiZone::StateMultiZone](doc:multizone-messages#section-statemultizone-506) messages, so your application needs to be able to handle both. If you wish to read all zones on the device set `start_zone` to 0 and `end_zone` to 255. [block:callout] { "type": "info", "body": "The bulb may return the details for more zones than your application requested. The additional zones may be beyond the zones available on the device, in which case they should be ignored, however zones within the limits will be correct and can be used to update any UI or cache that you may have in the application." } [/block] Controlling individual zones is done with the [MultiZone::SetColorZones](doc:multizone-messages#section-setcolorzones-501) message. This message takes a single HSBK value and sets that color on all zones between `start_index` and `end_index` inclusive. ## Changing All Zones If you would like to set the whole strip to a single color either use the [MultiZone::SetColorZones](doc:multizone-messages#section-setcolorzones-501) message with `start_index` set to 0 and the `end_index` set to 255, or use a [Light::SetColor](doc:light-messages#section-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 [MultiZone::SetColorZones](doc:multizone-messages#section-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.