Hue Lighting

This driver controls the Hue family of lighting devices. It was written using the external control protocol version 1.1. Version 1.1 supports API version 1.4.

Version History

1.0 The original release of the driver

1.01 Fixes a problem with systems that don't use groups

1.02 Adds events for all lights and groups

1.1 fixes a change in the security settings of the discovery protocol that prevented connections. Changed the data parsing to fix new return framing and added support for scenes (see below)

1.11 adds dynamic naming (the names from the config) to the driver events.

1.12 fixes a problem that can cause the driver to stop parsing data from the bridge

1.2 Updates to match API 1.8: Updates authentication procedures. Expands the number of groups to 64.

1.21 Adds increment/decrement commands for light and group parameters. Adds a group 'Set All' command to match the one for lights and set all all hsb parameters in one call.

Configuration

Finding the bridge

The bridge communicates with a web portal to report its configuration. The driver can contact the same portal and find the address of local Hue bridges. If the processor and the bridge have internet access, there’s no need for any configuration. If the internet is not accessible, then an option exists in the configuration to enter the IP address of the bridge.

You may also need to enter the address if there is more than one bridge on the local network.

Naming Lights and Groups

The configuration allows you to control the appearance of commands and variables in ID by specifying the number and names of Hue lights and groups. These are used to make programming the system easier but are not passed on to the system. The user has control, through the Hue and other third-party apps, of the number and names of objects in their Hue system. There is also a mechanism in the driver for creating new groups and renaming existing ones. Driver commands are sent to the light or group number however so changing the name of a group or light will not change whether it gets commands from a particular button.

All 'Name' variables in the driver are extracted from the devices themselves and are not the names given in the configuration.

Authorization

Once the driver finds the bridge it will put its address into the Bridge Address variable. The first time a processor connects to the Hue Bridge it will need to be granted permission to access it. This is done by pressing the button on top of the bridge after the driver is running. The processor will set the Not Authorized variable if it is not allowed access, and then clear it when it is allowed in. The samples all use the flag to display a message asking for the button to be pressed. In normal operation this should never be seen.

Once the driver has found the bridge it will get the current system status and fill the variables with the current state of the lights (see below for notes on the group variables)

Lights

The driver allows for the adjustment and display of all the lamps parameters: brightness, hue, saturation and color temperature. It also allows changing several operation states:

Alert: The lamps can be set to flash. The option is to flash a single time, or to have it flash for 30 seconds. It is also possible to stop the alert before the 30 seconds are up. The variable will change to show an alert when the alert starts but will only change back when a stop command is sent (it does not change back on its own).

Effect: The lamp can be set to do a slow circuit through the full range of hue values at the current brightness and saturation levels. This will continue indefinitely.

Color Mode: This variable shows whether the lamp is being operated through Hue/Saturation commands or through Color Temperature commands.

Lamp Names: The driver allows you to give names to the lamps you're using but the variable in the driver gets the actual lamp names. If you use the variable names to label the buttons the names will change if the user changes a lamp name externally (through their phone or tablet).

On/Off vs Dim: The Hue system treats brightness and state (on/off) separately. This means:

A lamp dimmed to 0 will very noticeably be on, this is characteristic of LED lighting

A lamp that is off will not respond to any brightness commands

Sending an on command to a lamp that you dimmed to off will turn it on at its lowest dim level.

For these reasons the driver command for brightness will also send state commands to match. If you send a brightness command with a level of zero, the driver will set the state of the lamp to off. If the level is anything but 0 the driver will set the state to on.

Variables in the driver are rewritten as soon as a command is acknowledged by the processor. Any changes to the state of the lamp created outside the use of the ‘Light’ commands will eventually be discovered and transferred to the processor but that can take several seconds. This includes not only the use of the app for external control, but also the use of the group commands (see below).

Groups

All lights are part of Group 0. You can’t name or edit Group 0 but it is always there. Any command you want sent to ALL lights should be sent to Group 0

Group commands are used to send commands to multiple lamps. They allow the same adjustment possible with individual bulbs but let you make more global changes. There are also variables that match those commands. Neither the bridge, nor the driver, attempt to keep the variables for the groups updated when changes are made to the lights outside of that group If a group is turned off it will show off even if every light in the group is subsequently turned back through individual light on commands. The group variables will always be the values that were last sent to the device.

The driver allows groups to be completely edited on the fly. All groups appear in a list variable allowing a specific group to be ‘Selected’ for that device, additional groups can be created, groups can be renamed, and lights can be added and removed from lists. Some important things to know:

o Groups must always have at least one light; you cannot delete the last light in a group

o Any new group you create will always have the first light in it by default.

o If you have 5 groups and you delete group 3 you will not have a group 3. The next group you create will become Group 3

You use the Groups list to display the current list of groups by both number and name. Once one of these groups is selected all the ‘selected’ (see below as well) variables for that remote device will be filled in, including the Selected Group Light List which is a list of the lights currently in that group. Putting the Delete Light from Group command on this list lets you delete the light from the group. Adding lights to the group is as simple as putting the Add Light to Group command on the Lights list (the list of all lights). In addition, the selected group can be deleted or renamed. Renaming requires building a keyboard for entry but the sample file has an example of how that’s done.

Finally, there are commands that allow you to send any of the lighting control commands to the selected group.

Selected Lights/Groups

'Selected' lights and groups allow you to save pages, space and programming in your project by using the same button to control different lights based on the user’s actions. The Light On command has a pull-down menu that allows you to set which light the button controls. All the lights in your configuration are listed along with a choice labeled <selected>. In addition, there is a set of variables for each light in your config as well as a set of variables for the Selected Light.

Lights (or groups) can be selected in several ways, by directly putting the light into the command, by rotating up and down through all the lights, or by putting the 'Select Light from List' command on a two-way list using the Light List variable. When a light is selected its variables will be transferred to the Selected Light variables and any buttons or sliders pointed at the selected light will now control that light. You can create a page with the Light List and a single set of controls that can control every light in the system.

In addition, the selected light is only the selected light for the remote or panel that selected it. Each device has its own copy of the selected variables to use. This is important because the processor needs to know which device's variables to fill in. Because of this:

You cannot 'Select' a light or group via a macro running on a processor. The processor will not know which device to assign the selected item to.

Scenes

The driver cannot create scenes but can recall any scene created on any device. Because of the way scenes are named in the gateway's memory it is not possible at this point to create a usable list, but you can name the scene directly in the command parameter and the driver will find it.

To recall a scene, you enter the scene name as a parameter to the 'Group to Named Scene' command. You send the scene to a group so that you have the option of only turning the scene to some of its light. If you want the scene to be recalled on all its lights you can send it to Group 0 which is the default.