# Philips Hue Binding Configuration for API v2
# 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.:
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:
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
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 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 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:
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. |
| scene1) | 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. |
| alert1) | String | This channel allows setting an alert on the lights e.g. flashing them. |
1) 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.
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.
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.
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.
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:
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:
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:
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
}
}