mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 15:11:59 +01:00
289 lines
17 KiB
Markdown
289 lines
17 KiB
Markdown
# LIFX Binding
|
|
|
|
This binding integrates the [LIFX LED Lights](https://www.lifx.com/).
|
|
All LIFX lights are directly connected to the WLAN and the binding communicates with them over a UDP protocol.
|
|
|
|
|
|
|
|
## Supported Things
|
|
|
|
The following table lists the thing types of the supported LIFX devices:
|
|
|
|
| Device Type | Thing Type |
|
|
|------------------------------|---------------|
|
|
| Original 1000 | colorlight |
|
|
| Color 650 | colorlight |
|
|
| Color 1000 | colorlight |
|
|
| Color 1000 BR30 | colorlight |
|
|
| LIFX A19 | colorlight |
|
|
| LIFX A21 1600lm | colorlight |
|
|
| LIFX BR30 | colorlight |
|
|
| LIFX Candle | colorlight |
|
|
| LIFX Ceiling | colorlight |
|
|
| LIFX Downlight | colorlight |
|
|
| LIFX GU10 | colorlight |
|
|
| LIFX Mini Color | colorlight |
|
|
| LIFX PAR38 | colorlight |
|
|
| LIFX Round Spot | colorlight |
|
|
| LIFX Round Path | colorlight |
|
|
| LIFX Square Path | colorlight |
|
|
| | |
|
|
| LIFX Clean | colorhevlight |
|
|
| | |
|
|
| LIFX+ A19 | colorirlight |
|
|
| LIFX+ BR30 | colorirlight |
|
|
| | |
|
|
| LIFX Beam | colormzlight |
|
|
| LIFX Neon | colormzlight |
|
|
| LIFX Outdoor Neon | colormzlight |
|
|
| LIFX String | colormzlight |
|
|
| LIFX Z | colormzlight |
|
|
| | |
|
|
| LIFX Tile | tilelight |
|
|
| | |
|
|
| White 800 (Low Voltage) | whitelight |
|
|
| White 800 (High Voltage) | whitelight |
|
|
| White 900 BR30 (Low Voltage) | whitelight |
|
|
| LIFX Candle Warm to White | whitelight |
|
|
| LIFX Filament | whitelight |
|
|
| LIFX Mini Day and Dusk | whitelight |
|
|
| LIFX Mini White | whitelight |
|
|
|
|
The thing type determines the capability of a device and with that the possible ways of interacting with it.
|
|
The following matrix lists the capabilities (channels) for each type:
|
|
|
|
| Thing Type | On/Off | Brightness | Color | Color Zone | (Abs) Color Temperature | (Abs) Color Temperature Zone | HEV Cycle | Infrared | Tile Effects |
|
|
|---------------|:------:|:----------:|:-----:|:----------:|:-----------------------:|:----------------------------:|:---------:|:--------:|:------------:|
|
|
| colorlight | X | | X | | X | | | | |
|
|
| colorhevlight | X | | X | | X | | X | | |
|
|
| colorirlight | X | | X | | X | | | X | |
|
|
| colormzlight | X | | X | X | X | X | | | |
|
|
| tilelight | X | X | X | | X | | | | X |
|
|
| whitelight | X | X | | | X | | | | |
|
|
|
|
## Discovery
|
|
|
|
The binding is able to auto-discover all lights in a network over the LIFX UDP protocol.
|
|
Therefore all lights must be turned on.
|
|
|
|
_Note:_ To get the binding working, all lights must be added to the WLAN network first with the help of the [LIFX smart phone applications](https://www.lifx.com/pages/app).
|
|
The binding is NOT able to add or detect lights outside the network.
|
|
|
|
## Thing Configuration
|
|
|
|
Each light needs a Device ID or Host as a configuration parameter.
|
|
The device ID is printed as a serial number on the light and can also be found within the native LIFX Android or iOS application.
|
|
But usually the discovery works quite reliably, so that a manual configuration is not needed.
|
|
|
|
However, in the thing file, a manual configuration looks e.g. like
|
|
|
|
```java
|
|
Thing lifx:colorlight:living [ deviceId="D073D5A1A1A1", fadetime=200 ]
|
|
```
|
|
|
|
The _fadetime_ is an optional thing configuration parameter which configures the time to fade to a new color value (in ms).
|
|
When the _fadetime_ is not configured, the binding uses 300ms as default.
|
|
|
|
You can optionally also configure a fixed Host or IP address when lights are in a different subnet and are not discovered.
|
|
|
|
```java
|
|
Thing lifx:colorirlight:porch [ host="10.120.130.4", fadetime=0 ]
|
|
```
|
|
|
|
## Channels
|
|
|
|
All devices support some of the following channels:
|
|
|
|
| Channel Type ID | Item Type | Description | Thing Types |
|
|
|--------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
|
|
| abstemperature | Number:Temperature | This channel supports adjusting the color temperature in Kelvin. | colorlight, colorhevlight, colorirlight, colormzlight, tilelight, whitelight |
|
|
| abstemperaturezone | Number:Temperature | This channel supports adjusting the zone color temperature in Kelvin. | colormzlight |
|
|
| brightness | Dimmer | This channel supports adjusting the brightness value. | whitelight |
|
|
| color | Color | This channel supports full color control with hue, saturation and brightness values. | colorlight, colorhevlight, colorirlight, colormzlight, tilelight |
|
|
| colorzone | Color | This channel supports full zone color control with hue, saturation and brightness values. | colormzlight |
|
|
| effect | String | This channel represents a type of light effect (e.g. for tile light: off, morph, flame) | tilelight |
|
|
| hevcycle | Switch | This channel supports starting and stopping the HEV clean cycle. | colorhevlight |
|
|
| infrared | Dimmer | This channel supports adjusting the infrared value. _Note:_ IR capable lights only activate their infrared LEDs when the brightness drops below a certain level. | colorirlight |
|
|
| signalstrength | Number | This channel represents signal strength with values 0, 1, 2, 3 or 4; 0 being worst strength and 4 being best strength. | colorlight, colorhevlight, colorirlight, colormzlight, tilelight, whitelight |
|
|
| temperature | Dimmer | This channel supports adjusting the color temperature from cold (0%) to warm (100%). | colorlight, colorhevlight, colorirlight, colormzlight, tilelight, whitelight |
|
|
| temperaturezone | Dimmer | This channel supports adjusting the zone color temperature from cold (0%) to warm (100%). | colormzlight |
|
|
|
|
The _color_ and _brightness_ channels have a "Power On Brightness" configuration option that is used to determine the brightness when a light is switched on.
|
|
When it is left empty, the brightness of a light remains unchanged when a light is switched on or off.
|
|
|
|
The _color_ channels have a "Power On Color" configuration option that is used to determine the hue, saturation, brightness levels when a light is switched on.
|
|
When it is left empty, the color of a light remains unchanged when a light is switched on or off.
|
|
Configuration options contains 3 comma separated values, where first value is hue (0-360), second saturation (0-100) and third brightness (0-100).
|
|
If both "Power on brightness" and "Power On Color" configuration options are defined, "Power on brightness" option overrides the brightness level defined on the "Power on color" configuration option.
|
|
|
|
The _temperature_ channels have a "Power On Temperature" configuration option that is used to determine the color temperature when a light is switched on. When it is left empty, the color temperature of a light remains unchanged when a light is switched on or off.
|
|
|
|
MultiZone lights (_colormzlight_) have several channels (e.g. _colorzone0_, _temperaturezone0_, _abstemperaturezone0_, etc.) that allow for controlling specific zones of the light.
|
|
Changing the _color_, _temperature_ and _abstemperature_ channels will update the states of all zones.
|
|
The _color_, _temperature_ and _abstemperature_ channels of MultiZone lights always return the same state as _colorzone0_, _temperaturezone0_, _abstemperaturezone0_.
|
|
|
|
The _hevcycle_ channels have an optional "HEV Cycle Duration" configuration option that can be used to override the cycle duration configured in the light.
|
|
|
|
LIFX Tile (_tilelight_) supports special tile effects: morph and flame.
|
|
These effects are predefined to their appearance using LIFX application.
|
|
Each effect has a separate speed configuration option.
|
|
|
|
## Full Example
|
|
|
|
In this example **living** is a Color 1000 light that has a _colorlight_ thing type which supports _color_ and _temperature_ channels.
|
|
|
|
The **desk** light is a LIFX Clean that has a _colorhevlight_ thing type which supports _color_, _temperature_ and _hevcycle_ channels.
|
|
|
|
The **porch** light is a LIFX+ BR30 that has a _colorirlight_ thing type which supports _color_, _temperature_ and _infrared_ channels.
|
|
|
|
The **ceiling** light is a LIFX Z with 2 strips (16 zones) that has a _colormzlight_ thing type which supports _color_, _colorzone_, _temperature_ and _temperaturezone_ channels.
|
|
|
|
Finally, **kitchen** is a White 800 (Low Voltage) light that has a _whitelight_ thing type which supports _brightness_ and _temperature_ channels.
|
|
|
|
Either create a single _Color_ item linked to the _color_ channel and define _Switch_, _Slider_ and _Colorpicker_ entries with this item in the sitemap.
|
|
Or create items for each type (_Color_, _Switch_, _Dimmer_) and define the correspondent entries in the sitemap.
|
|
|
|
### `demo.things` Example
|
|
|
|
```java
|
|
Thing lifx:colorlight:living [ deviceId="D073D5A1A1A1" ]
|
|
|
|
Thing lifx:colorlight:living2 [ deviceId="D073D5A2A2A2" ] {
|
|
Channels:
|
|
Type color : color [ powerOnBrightness=50 ]
|
|
}
|
|
|
|
Thing lifx:colorhevlight:desk [ deviceId="D073D5A3A3A3" ] {
|
|
Channels:
|
|
Type hevcycle : hevcycle [ hevCycleDuration=3600 ]
|
|
}
|
|
|
|
Thing lifx:colorirlight:porch [ deviceId="D073D5B2B2B2", host="10.120.130.4", fadetime=0 ] {
|
|
Channels:
|
|
Type color : color [ powerOnBrightness=75 ]
|
|
}
|
|
|
|
Thing lifx:colorirlight:porch [ deviceId="D073D5B2B2B2", host="10.120.130.4", fadetime=0 ] {
|
|
Channels:
|
|
Type temperature : temperature [ powerOnTemperature=20 ]
|
|
}
|
|
|
|
Thing lifx:colorirlight:porch [ deviceId="D073D5B2B2B2", host="10.120.130.4", fadetime=0 ] {
|
|
Channels:
|
|
Type color : color [ powerOnColor="120,100,50" ] // Deep green, 50% brightness
|
|
}
|
|
|
|
Thing lifx:colormzlight:ceiling [ host="10.120.130.5" ]
|
|
|
|
Thing lifx:whitelight:kitchen [ deviceId="D073D5D4D4D4", fadetime=150 ]
|
|
```
|
|
|
|
### `demo.items` Example
|
|
|
|
```java
|
|
// Living
|
|
Color Living_Color { channel="lifx:colorlight:living:color" }
|
|
Dimmer Living_Temperature { channel="lifx:colorlight:living:temperature" }
|
|
Number:Temperature Living_Abs_Temperature "Living Room Lights Color Temperature [%d K]" { channel="lifx:colorlight:living:abstemperature" }
|
|
|
|
// Living2 (alternative approach)
|
|
Color Living2_Color { channel="lifx:colorlight:living2:color" }
|
|
Switch Living2_Switch { channel="lifx:colorlight:living2:color" }
|
|
Dimmer Living2_Dimmer { channel="lifx:colorlight:living2:color" }
|
|
Dimmer Living2_Temperature { channel="lifx:colorlight:living2:temperature" }
|
|
Number:Temperature Living2_Abs_Temperature "Living Room Lights Color Temperature [%d K]" { channel="lifx:colorlight:living2:abstemperature" }
|
|
|
|
// Desk
|
|
Color Desk_Color { channel="lifx:colorhevlight:desk:color" }
|
|
Dimmer Desk_Temperature { channel="lifx:colorhevlight:desk:temperature" }
|
|
Number:Temperature Desk_Abs_Temperature "Desk Lamp Color Temperature [%d K]" { channel="lifx:colorhevlight:desk:abstemperature" }
|
|
Switch Desk_HEV_Cycle { channel="lifx:colorhevlight:desk:hevcycle" }
|
|
|
|
// Porch
|
|
Color Porch_Color { channel="lifx:colorirlight:porch:color" }
|
|
Dimmer Porch_Infrared { channel="lifx:colorirlight:porch:infrared" }
|
|
Dimmer Porch_Temperature { channel="lifx:colorirlight:porch:temperature" }
|
|
Number:Temperature Porch_Abs_Temperature "Porch Light Color Temperature [%d K]" { channel="lifx:colorirlight:porch:abstemperature" }
|
|
Number Porch_Signal_Strength { channel="lifx:colorirlight:porch:signalstrength" }
|
|
|
|
// Ceiling
|
|
Color Ceiling_Color { channel="lifx:colormzlight:ceiling:color" }
|
|
Dimmer Ceiling_Temperature { channel="lifx:colormzlight:ceiling:temperature" }
|
|
Number:Temperature Ceiling_Abs_Temperature "Ceiling Light Color Temperature [%d K]" { channel="lifx:colormzlight:ceiling:abstemperature" }
|
|
Color Ceiling_Color_Zone_0 { channel="lifx:colormzlight:ceiling:colorzone0" }
|
|
Dimmer Ceiling_Temperature_Zone_0 { channel="lifx:colormzlight:ceiling:temperaturezone0" }
|
|
Number:Temperature Ceiling_Abs_Temperature_Zone_0 "Ceiling Light 0 Color Temperature [%d K]" { channel="lifx:colormzlight:ceiling:abstemperaturezone0" }
|
|
Color Ceiling_Color_Zone_15 { channel="lifx:colormzlight:ceiling:colorzone15" }
|
|
Dimmer Ceiling_Temperature_Zone_15 { channel="lifx:colormzlight:ceiling:temperaturezone15" }
|
|
Number:Temperature Ceiling_Abs_Temperature_Zone_15 "Ceiling Light 15 Color Temperature [%d K]" { channel="lifx:colormzlight:ceiling:abstemperaturezone15" }
|
|
|
|
// Kitchen
|
|
Switch Kitchen_Toggle { channel="lifx:whitelight:kichen:brightness" }
|
|
Dimmer Kitchen_Brightness { channel="lifx:whitelight:kitchen:brightness" }
|
|
Dimmer Kitchen_Temperature { channel="lifx:whitelight:kitchen:temperature" }
|
|
Number:Temperature Kitchen_Abs_Temperature "Kitchen Light Color Temperature [%d K]" { channel="lifx:whitelight:kitchen:abstemperature" }
|
|
```
|
|
|
|
### `demo.sitemap` Example
|
|
|
|
```perl
|
|
sitemap demo label="Main Menu"
|
|
{
|
|
Frame label="Living" {
|
|
Switch item=Living_Color
|
|
Slider item=Living_Color
|
|
Colorpicker item=Living_Color
|
|
Slider item=Living_Temperature
|
|
Slider item=Living_Abs_Temperature
|
|
}
|
|
|
|
Frame label="Living2" {
|
|
Switch item=Living2_Toggle
|
|
Slider item=Living2_Dimmer
|
|
Colorpicker item=Living2_Color
|
|
Slider item=Living2_Temperature
|
|
Slider item=Living2_Abs_Temperature
|
|
}
|
|
|
|
Frame label="Desk" {
|
|
Switch item=Desk_Color
|
|
Slider item=Desk_Color
|
|
Colorpicker item=Desk_Color
|
|
Slider item=Desk_Temperature
|
|
Slider item=Desk_Abs_Temperature
|
|
Switch item=Desk_HEV_Cycle
|
|
}
|
|
|
|
Frame label="Porch" {
|
|
Switch item=Porch_Color
|
|
Slider item=Porch_Color
|
|
Colorpicker item=Porch_Color
|
|
Slider item=Porch_Temperature
|
|
Slider item=Porch_Abs_Temperature
|
|
Slider item=Porch_Infrared
|
|
Text item=Porch_Signal_Strength
|
|
}
|
|
|
|
Frame label="Ceiling" {
|
|
Switch item=Ceiling_Color
|
|
Slider item=Ceiling_Color
|
|
Colorpicker item=Ceiling_Color
|
|
Slider item=Ceiling_Temperature
|
|
Slider item=Ceiling_Abs_Temperature
|
|
Colorpicker item=Ceiling_Color_Zone_0
|
|
Slider item=Ceiling_Temperature_Zone_0
|
|
Slider item=Ceiling_Abs_Temperature_Zone_0
|
|
Colorpicker item=Ceiling_Color_Zone_15
|
|
Slider item=Ceiling_Temperature_Zone_15
|
|
Slider item=Ceiling_Abs_Temperature_Zone_15
|
|
}
|
|
|
|
Frame label="Kitchen" {
|
|
Switch item=Kitchen_Toggle
|
|
Slider item=Kitchen_Brightness
|
|
Slider item=Kitchen_Temperature
|
|
Slider item=Kitchen_Abs_Temperature
|
|
}
|
|
}
|
|
```
|