This page is part of archived documentation for openHAB 4.0. Go to the current stable version

# Philips Hue Binding Configuration for API v2

Back to Overview

# 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 Number Informs which button was last pressed in the device. (Trigger Channel)
rotary-steps Number Informs about the number of rotary steps of the last rotary dial movement. (Trigger Channel)
motion Switch Shows if motion has been detected by the sensor. (Read Only)
motion-enabled Switch Supports enabling / disabling the motion sensor. (Advanced)
light-level Number:Illuminance Shows the current light level measured by the sensor. (Read Only)
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-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.

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 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.

# 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"}

Number 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
  }
}

Back to Overview