demus/openhab-addons
1
0
Fork 0
mirror of https://github.com/openhab/openhab-addons.git synced 2025-01-11 15:42:10 +01:00
Code Issues Packages Projects Releases Wiki Activity
94be9fdca7
openhab-addons/bundles/org.openhab.binding.hue/doc/readme_v2.md
Andrew Fiddian-Green 4f6d33bb79
[hue] Support new home security products (#15601) 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
2023-11-09 08:09:20 +01:00

255 lines
19 KiB
Markdown
Raw Blame History

# Philips Hue Binding Configuration for API v2
[Back to Overview](../README.md#philips-hue-binding)
## Supported Things
The binding supports `bridge-api2`, `device`, `room`, and `zone` thing types.
The `bridge-api2` thing type represents the Hue Bridge which is the server for all other things.
The `device` thing type represents a piece of physical equipment in the home.
Such `device` things may contain either a *light*, a *button*, or (one or more) *sensors*.
Lights can be of any type from a simple on/off light, through dimmable monochrome lights, to full colour dimmable lights.
Buttons are devices having one or more push buttons.
Sensors can be (for example) light level sensors, temperature sensors, or motion sensors.
The `room` and `zone` thing type represents logical groupings of equipment in the home, either within a specific room, or a logical group of equipment.
## Thing Configuration
### Bridge
The Hue Bridge requires the IP address as a configuration value in order for the binding to know where to access it.
It requires an 'application key' to authenticate against the Hue Bridge.
This may be copied from an API v1 installation, or it may be automatically generated (press button to authenticate).
Please note that the generated application key cannot be written automatically to the `.things` file, and has to be set manually.
The generated application key can be found, after pressing the authentication button on the bridge, with the following console command: `openhab:hue <bridgeUID> applicationkey`.
The application key can be set using the `applicationKey` configuration value, e.g.:
```java
Bridge hue:bridge-api2:1 [ ipAddress="192.168.0.64", applicationKey="qwertzuiopasdfghjklyxcvbnm1234" ]
```
| Parameter | Description |
|--------------------------|----------------------------------------------------------------------------------------------------|
| ipAddress | Network address of the Hue Bridge. **Mandatory**. |
| applicationKey | A code generated by the bridge that allows to access the API. **Mandatory** |
| checkMinutes | Interval in minutes between retrying the HTTP 2 and SSE connections. Default is 60. **Advanced** |
| useSelfSignedCertificate | Use self-signed certificate for HTTPS connection to Hue Bridge. Default is `true`. **Advanced** |
### Devices, Rooms, and Zones
Apart from the Bridge, there are three other types of thing -- namely `device`, `room`, and `zone`.
Device things represent physical hardware devices in the system, whereas `room` and `zone` things represent sets of physical lights, either in a room or a zone.
In addition to regular rooms and zones, there is a 'super' `zone` that allows you to control all of the lights in the system.
All things are identified by a unique Resource Identifier string that the Hue Bridge assigns to them e.g. `d1ae958e-8908-449a-9897-7f10f9b8d4c2`.
Thus, all it needs for manual configuration is this single value, like:
```java
device officelamp "Lamp 1" @ "Office" [ resourceId="d1ae958e-8908-449a-9897-7f10f9b8d4c2" ]
..
zone kitchenLights "Kitchen Down Lights" @ "Kitchen" [ resourceId="7f10f9b8-8908-449a-9897-d4c2d1ae958e" ]
```
You can get a list of all devices in the bridge and their respective Resource Ids by entering the following console command: `openhab:hue <bridgeUID> things`
See [console command](#console-command-for-finding-resourceids)
The configuration of all things (as described above) is the same regardless of whether it is a device containing a light, a button, or (one or more) sensors, or whether it is a room or zone.
### Channels for Devices
Device things support some of the following channels:
| Channel ID | Item Type | Description |
|-------------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------|
| color | Color | Supports full color control with hue, saturation and brightness values, or brightness only, or switching on or off. |
| brightness | Dimmer | Supports control of the brightness value, or switching on or off. |
| color-temperature | Dimmer | Supports control of the color temperature in percent from cold (0%) to warm (100%). |
| color-temperature-abs | Number:Temperature | Supports control of the color temperature via a QuantityType having a temperature unit e.g. Kelvin. (Advanced) |
| switch | Switch | Supports switching the device on and off. |
| dynamics | Number:Time | Sets the duration of dynamic transitions between light states. (Advanced) |
| alert | String | Allows setting an alert on a light e.g. flashing them. (Advanced) |
| effect | String | Allows setting an effect on a light e.g. 'candle' effect. (Advanced) |
| button-last-event | (String) | Informs which button was last pressed in the device. (Trigger Channel) |
| button-last-updated | DateTime | The date and time when a button was last pressed. (Read Only) (Advanced) |
| rotary-steps | (String) | Informs about the number of rotary steps of the last rotary dial movement. (Trigger Channel) |
| rotary-steps-last-updated | DateTime | The date and time when the rotary steps were last updated. (Read Only) (Advanced) |
| motion | Switch | Shows if motion has been detected by the sensor. (Read Only) |
| motion-enabled | Switch | Supports enabling / disabling the motion sensor. (Advanced) |
| motion-last-updated | DateTime | The date and time when the motion value was last updated. (Read Only) (Advanced) |
| light-level | Number:Illuminance | Shows the current light level measured by the sensor. (Read Only) |
| light-level-last-updated | DateTime | The date and time when the light level was last updated. (Read Only) (Advanced) |
| light-level-enabled | Switch | Supports enabling / disabling the light level sensor. (Advanced) |
| temperature | Number:Temperature | Shows the current temperature measured by the sensor. (Read Only) |
| temperature-last-updated | DateTime | The date and time when the temperature was last updated. (Read Only) (Advanced) |
| temperature-enabled | Switch | Supports enabling / disabling the temperature sensor. (Advanced) |
| battery-level | Number | Shows the battery level. (Read Only) |
| battery-low | Switch | Indicates whether the battery is low or not. (Read Only) |
| last-updated | DateTime | The date and time when the thing state was last updated. (Read Only) (Advanced) |
| color-xy-only | Color | Allows access to the `color-xy` parameter of the light(s) only. Has no impact on `dimming` or `on-off` parameters. |
| dimming-only | Dimmer | Allows access to the `dimming` parameter of the light(s) only. Has no impact on `color-xy` or `on-off` parameters. |
| on-off-only | Switch | Allows access to the `on-off` parameter of the light(s) only. Has no impact on `color-xy` or `dimming` parameters. |
| security-contact | Contact | Indicates whether a security contact has been triggered. (Read Only) |
| security-contact-enabled | Switch | Supports enabling / disabling the security contact. (Advanced) |
| security-contact-last-updated | DateTime | The date and time when the security contact state was last updated. (Read Only) (Advanced) |
| security-tamper | Contact | Indicates whether a security tamper contact has been triggered. `Open` means tampering detected. (Read Only) |
| security-tamper-last-updated | DateTime | The date and time when the security tamper contact state was last updated. (Read Only) (Advanced) |
The exact list of channels in a given device is determined at run time when the system is started.
Each device reports its own live list of capabilities, and the respective list of channels is created accordingly.
The channels `color-xy-only`, `dimming-only` and `on-off-only` are *advanced* channels - see [below](#advanced-channels-for-devices-rooms-and-zones) for more details.
The `effect` channel is an amalgamation of 'normal' and 'timed' effects.
To activate a 'normal' effect, the binding sends a single command to activate the respective effect.
To activate a 'timed' effect, the binding sends a first command to set the timing followed a second command to activate the effect.
You can explicitly send the timing command via the [dynamics channel](#the-dynamics-channel) before you send the effect command.
Or otherwise the binding will send a default timing command of 15 minutes.
The `button-last-event` channel is a trigger channel.
When the button is pressed the channel receives a number as calculated by the following formula:
```text
value = (button_id * 1000) + event_id;
```
In a single button device, the `button_id` is 1, whereas in a multi- button device the `button_id` can be either 1, 2, 3, or 4 depending on which button was pressed.
The `event_id` can have the following values:
| Event | Value |
|----------------------|-------|
| INITIAL_PRESS | 0 |
| REPEAT | 1 |
| SHORT_RELEASE | 2 |
| LONG_RELEASE | 3 |
| DOUBLE_SHORT_RELEASE | 4 |
So (for example) the channel value `1002` ((1 * 1000) + 2) means that the second button in the device had a short release event.
The `rotary-steps` channel is a trigger channel.
When the dial is turned, the channel receives a number corresponding to the number of steps of the last movement of a rotary dial.
A positive number means the dial was rotated clock-wise, whereas a negative number means it was rotated counter-clockwise.
### Channels for Rooms and Zones
Room and Zone things allow you to control the lights in a given zone or room.
They support the following channels:
| Channel ID | Item Type | Description |
|---------------------|--------------------|-----------------------------------------------------------------------------------|
| brightness | Dimmer | Supports adjusting the brightness or switching the lights on and off. |
| switch | Switch | Supports switching the lights on and off. |
| scene<sup>1)</sup> | String | Setting the string to a valid scene friendly name activates the respective scene. |
| dynamics | Number:Time | The duration of dynamic transitions between light or scene states. |
| alert<sup>1)</sup> | String | This channel allows setting an alert on the lights e.g. flashing them. |
<sup>1)</sup> The scene and alert channels are optional.
If the respective room or zone has no scenes or alerts associated with it, the respective channel will not be shown.
### The `dynamics` Channel
Some channels support dynamic transitions between light states.
A dynamic transition is where, instead of the light state changing immediately to its new target value, it changes gradually to the new value over a period of time.
If a thing supports dynamic transitions, then it will have a `dynamics` channel.
This is a numeric channel where you can set the time delay for the transition in milliseconds.
When you set a value for the `dynamics` channel (e.g. 2000 milliseconds) and then quickly issue another command (e.g. brightness 100%), the second command will be executed gradually over the period of milliseconds given by the `dynamics` channel value.
When the `dynamics` channel value is changed, it triggers a time window of ten seconds during which the value is active.
If the second command is sent within the active time window, it will be executed gradually according to the `dynamics` channel value.
However, if the second command is sent after the active time window has expired, then it will be executed immediately.
If the second command is a 'timed' effect, then the dynamics duration will be applied to that effect.
### Advanced Channels for Devices, Rooms and Zones
Some things support additional advanced channels `color-xy-only`, `dimming-only` and/or `on-off-only`.
For convenience the normal channels often amalgamate multiple elements of the state of a light, room or zone into one single channel.
For example, a full color light has one single `color` channel that can accept HSBType commands for changing the color, PercentType commands for changing the brightness, and OnOffType commands for switching it on or off.
By contrast, the purpose of the advanced channels is to individually access specificstate elements of the respective lights, rooms or zones.
These advanced channels can be used as "presets".
For example, you may want to preset the `dimming-only` channel to 20% at night, and to 100% in the day time.
Then if somebody turns on the light at night time it will turn on to 20% resp. to 100% in the day time.
You can also use the `color-xy-only` channel to preset (say) a cool color in the morning, and a warm color in the evening.
NOTE: you can also preset color temperature values in advance via the `color-temperature` and `color-temperature-abs` channels described above.
## Console Command for finding ResourceIds
The openHAB console has a command named `openhab:hue` that (among other things) lists the `resourceId` of all device things in the bridge.
The console command usage is `openhab:hue <brigeUID> things`.
An exampe of such a console command, and its respective output, is shown below.
```shell
openhab> openhab:hue hue:bridge-api2:g24 things
Bridge hue:bridge-api2:g24 "Philips Hue Bridge" [ipAddress="192.168.1.234", applicationKey="abcdefghijklmnopqrstuvwxyz0123456789ABCD"] {
Thing device 11111111-2222-3333-4444-555555555555 "Standard Lamp L" [resourceId="11111111-2222-3333-4444-555555555555"] // Hue color lamp
Thing device 11111111-2222-3333-4444-666666666666 "Kitchen Wallplate Switch" [resourceId="11111111-2222-3333-4444-666666666666"] // Hue wall switch module
}
```
The `openhab:hue <brigeUID> things` command produces an output that can be used to directly create a `.things` file, as shown below.
```shell
openhab> openhab:hue hue:bridge-api2:g24 things > myThingsFile.things
```
## Rule Actions
This binding includes a rule action, which implements dynamic (i.e. gradual) transitions to a new scene or light(s) state.
Each thing has a separate action instance, which can be retrieved as follows.
```php
val hueActions = getActions("hue","hue:device:g24:11111111-2222-3333-4444-555555555555")
```
Where the first parameter must always be `hue` and the second must be the full thing UID.
Once the action instance has been retrieved, you can invoke its `dynamicCommand(String channelId, Command command, Long durationMs)` method as follows.
```php
hueActions.dynamicCommand("brightness", new PercentType(100), new Long(10000))
hueActions.dynamicCommand("scene", new StringType("SceneName"), new Long(20000))
```
| Parameter | Description |
|------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| channelId | The channel ID of the channel to send the command to (one of `brightness`, `color`, `color-temperature`, `color-temp-kelvin`, or `scene`). |
| command | The target command state to transition to. |
| durationMs | The dynamic transition duration in milliseconds. |
## Full Example
### demo.things:
```java
Bridge hue:bridge-api2:g24 "Philips Hue Hub" @ "Home" [ipAddress="192.168.1.234", applicationKey="abcdefghijklmnopqrstuvwxyz0123456789ABCD"] {
Thing device 11111111-2222-3333-4444-555555555555 "Living Room Standard Lamp Left" @ "Living Room" [resourceId="11111111-2222-3333-4444-555555555555"]
Thing device 11111111-2222-3333-4444-666666666666 "Kitchen Wallplate Switch" @ "Kitchen" [resourceId="11111111-2222-3333-4444-666666666666"]
Thing zone 11111111-2222-3333-4444-666666666666 "Kitchen Lights" @ "Kitchen" [resourceId="11111111-2222-3333-4444-666666666666"]
}
```
### demo.items:
```java
Color Living_Room_Standard_Lamp_Left_Colour "Living Room Standard Lamp Left Colour" {channel="hue:device:g24:11111111-2222-3333-4444-555555555555:color"}
Dimmer Living_Room_Standard_Lamp_Left_Brightness "Living Room Standard Lamp Left Brightness [%.0f %%]" {channel="hue:device:g24:11111111-2222-3333-4444-555555555555:brightness"}
Switch Living_Room_Standard_Lamp_Left_Switch "Living Room Standard Lamp Left Switch" (g_Lights_On_Count) {channel="hue:device:g24:11111111-2222-3333-4444-555555555555:switch"}
String Kitchen_Wallplate_Switch_Last_Event "Kitchen Wallplate Switch Last Event" {channel="hue:device:g24:11111111-2222-3333-4444-666666666666:button-last-event"}
Switch Kitchen_Wallplate_Switch_Battery_Low_Alarm "Kitchen Wallplate Switch Battery Low Alarm" {channel="hue:device:g24:11111111-2222-3333-4444-666666666666:battery-low"}
```
### demo.sitemap:
```perl
sitemap demo label="Hue" {
Frame label="Standard Lamp" {
Switch item=Living_Room_Standard_Lamp_Left_Switch
Slider item=Living_Room_Standard_Lamp_Left_Brightness
Colorpicker item=Living_Room_Standard_Lamp_Left_Colour
}
}
```
[Back to Overview](../README.md#philips-hue-binding)
Reference in New Issue View Git Blame Copy Permalink