From fa32b9f54f4cbb63ff27e28348021e4239d09c4a Mon Sep 17 00:00:00 2001 From: Avi Miller Date: Tue, 25 Oct 2022 03:35:44 +1100 Subject: [PATCH] Add documentation for the LIFX Flame and Morph effects (#24331) Co-authored-by: J. Nick Koston Co-authored-by: Franck Nijhof --- source/_integrations/lifx.markdown | 38 ++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/source/_integrations/lifx.markdown b/source/_integrations/lifx.markdown index 4e947354c51..169bc51072b 100644 --- a/source/_integrations/lifx.markdown +++ b/source/_integrations/lifx.markdown @@ -102,13 +102,17 @@ script:          change: 35 ``` -The `lifx.effect_move` effect is hardware effect that is only available on LIFX multizone devices like the LIFX Z, Lightstrip or Beam. Note that if all the LEDs of the multizone device are set to the same color, the effect will not be visible. The effect can be stopped and started regardless of the power state of the device, but the default is to turn the device on when starting the effect. Set the `power_on` attribute of the `lifx.effect_move` service to `false` to override the default. +### Hardware effects + +The Flame (`lifx_effect_flame`), Morph (`lifx.effect_morph`) and Move (`lifx.effect_move`) effects are hardware-based and only work on specific LIFX devices. Flame and Morph are available on the LIFX Tile and Candle, while the Move effect requires a LIFX Z, Lightstrip, or Beam. + +All hardware-based effects can be stopped and started regardless of the device's power state, but the default behavior for each service is to turn the device on when starting an effect. Set the `power_on` attribute of the service to `false` to override this default. All the available light effects and their options are listed below. ### Service `lifx.effect_pulse` -Run a flash effect by changing to a color and then back. +Run a software-based flash effect by changing to a color and then back. | Service data attribute | Description | | ---------------------- | ----------- | @@ -123,7 +127,7 @@ Run a flash effect by changing to a color and then back. ### Service `lifx.effect_colorloop` -Run an effect with colors looping around the color wheel. All participating lights will coordinate to keep similar (but not identical) colors. +Run a software-based effect that continuously loops colors around the color wheel. All participating lights will coordinate to keep similar (but not identical) colors. | Service data attribute | Description | | ---------------------- | ----------- | @@ -135,9 +139,35 @@ Run an effect with colors looping around the color wheel. All participating ligh | `spread` | Maximum color difference between participating lights, in degrees on a color wheel (ranges from 0 to 359). | `power_on` | Set this to False to skip the effect on lights that are turned off (defaults to True). +### Service `lifx.effect_flame` + +Run a hardware-based effect on LIFX matrix devices that creates a flame effect on the device. The device will be powered on by default, but this can be overridden by setting `power_on` to `false`. The `speed` attribute controls the speed of the flames. + +| Service data attribute | Description | +| ---------------------- | ----------- | +| `entity_id` | String or list of strings that point at `entity_id`s of matrix lights. +| `speed` | Duration in seconds for the effect to travel the length of the device (min: 1s, max: 25s) +| `power_on` | Whether to turn the light on before starting the effect (optional, default: true) + +### Service `lifx.effect_morph` + +Run a hardware-based effect on LIFX matrix devices that animates blobs of colors across the device. The `speed` attribute controls the speed of the movement. + +You must provide a `palette` or `theme` to use for the effect, but not both. The `palette` attribute allows you to select the colors used by the effect, while the `theme` attribute allows you to select one of the pre-configured themes which match those found in the LIFX smartphone app. + +The device will be powered on by default, but this can be overridden by setting `power_on` to `false`. + +| Service data attribute | Description | +| ---------------------- | ----------- | +| `entity_id` | String or list of strings that point at `entity_id`s of matrix lights. +| `speed` | Duration in seconds for the effect to travel the length of the device (min: 1s, max: 25s) +| `palette` | A list of at least 2 and at most 16 HSBK values to use for this effect. +| `theme` | The theme to use for the effect. Must be one of: `autumn`, `blissful`, `cheerful`, `dream`, `energizing`, `epic`, `exciting`, `focusing`, `halloween`, `hanukkah`, `holly`, `independence` `day`, `intense`, `mellow`, `peaceful`, `powerful`, `relaxing`, `santa`, `serene`, `soothing`, `sports`, `spring`, `tranquil`, `warming`. +| `power_on` | Whether to turn the light on before starting the effect (optional, default: true) + ### Service `lifx.effect_move` -A harware-based effect available on LIFX multizone devices that creates a movement animation of the colors currently set on the device. The direction and speed of the animation are controlled by the `speed` and `direction` attributes. You can change the colors of the effect while it is running using the `lifx.set_state` service. +Run a hardware-based effect on LIFX multizone devices that move the current colors on the device in a particular direction. The direction and speed of the animation are controlled by the `speed` and `direction` attributes. You can change the effect's colors while running using the `lifx.set_state` service. The effect will not be visible if all LEDs on the device are set to the same color and is ignored by unsupported devices.