The Philips Hue controller allows PowerHome to communicate with a Philips Hue Bridge and control / query status of Philips Hue bulbs, groups, and scenes. PowerHome in no way supports the configuration of Hue devices within a Hue bridge and is not a replacement for the appropriate Hue app that performs these functions. In order for PowerHome to control individual devices, groups, and scenes, they must first be configured within the Hue bridge using the Philips Hue smartphone (or equivalent) app.
Once your Philips Hue devices / groups / scenes are configured and able to be controlled via the Hue app, you can then configure PowerHome to also control and monitor the defined devices. Setup within PowerHome is accomplished using the Analog IO screen using Input/Output device types. Using Input/Output device types, you declare a single light (on/off/brightness) as a Unit 0 device. A Unit 1 device is the color/temperature values associated with a single device. To fully support a color bulb, you must declare two Analog IO devices, a unit 0 for the status/brightness and a unit 1 for the color/temperature settings.
Unit 2 and Unit 3 devices are equivalent to Unit 0 and Unit 1 devices respectively but represent a Philips Hue Group vs a single device ID. A Unit 2 device controls a groups status/brightness and a Unit 3 device controls a groups color temperature values.
Unit 4 covers Philips Hue scenes and allows you to define a list of scenes and allows you to select a scene from this list to activate it. Scenes are declared within the "User Ranges" screens of the PowerHome Explorer under Devices->Analog I/O->User Ranges. A user range for Philips Hue scenes associates a raw value with an "Alpha Value" that contains the Philips Hue unique scene ID.
Unlike Unit values of 0, 1, 2, 3, and 4 which are declared as Input/Output device types, a Unit 5 device (single scene activation) is declared using IOT Input / IOT Output device types. The Philips Hue unique scene ID will be entered in the "ROM ID / IP / Topic / Channel" column for these device types. Configuring a scene within PowerHome using this method does not require you to define the scene in the User Range section. Keep in mind that a single scene can equivalent to a Unit 5 scene can be accomplished by declaring a Unit 4 scene with a User Range containing a single scene.
For Units 0, 1, 2, and 3, the Point column is set to the unique sequential numeric ID that configuration within the Philips Hue app assigned to individual devices or groups.
For Units 5 and 6, you can limit the actual scene being activated to a specific group by setting the Point value to the sequentially assigned group ID. If you wish a scene activation to apply to ALL devices (assuming they have been configured to respond to the scene), use a Point value of 0.
For individual devices (Unit 0) and groups (Unit 2) on/off/brightness, the rawvalues are set as follows: To turn off the light, use a rawvalue of 0. To turn on the light at the last brightness level, use a rawvalue of 256. To set a brightness (Hue devices use brightness values from 1 (least bright) to 254 (most bright)), set the rawvalue to the appropriate brightness value in the range of 1 to 254. Setting a brightness will also turn on the light if it is off. You cannot set the brightness without also turning it on. To retrieve the current "status" of a device or group, check bit 256 of the rawvalue to determine if the device or group is on or off. If bit 256 is set, the group/device is on. If bit 256 is clear, it is off. To determine the level (whether on or off), bitwise "and" the rawvalue with 255. On or Off status: if(ph_and(rawvalue,256) > 0,"On","Off"). Brightness level: ph_and(rawvalue,255).
For color settings for individual devices (Unit 1) or groups (Unit 3), Philips Hue devices that support color can do so using one or more methods of XY, Hue/Sat, or CT (Color Temperature). PowerHome supports all 3 methods for the setting of color values as well as the storing of the color values in the rawvalue field. PowerHome also supports the setting of colors using standard RGB color values for devices or groups. If a device or group is set using an RGB color value, it is first converted to XY color values before being sent to the Hue bridge. Rather than using an RGB color value to set a color, you would typically want to set color values using one of the three Philips Hue methods (XY, Hue/Sat, CT) since RGB color values are converted to XY values before sending to the Hue bridge. When the device or group is "polled", the reported color value will be in XY mode and that is the value that will be used to represent the color status in the Analog IO rawvalue.
When "polling" the Hue bridge for the current color values of devices and groups, the value will be retrieved into PowerHome using Hue bridge "colormode" parameter which will be set to the method (XY, Hue/Sat, CT) that was last used to update the device or group.
Color values for setting and referencing are encoded into the rawvalue. Bits 536870912 and 268435456 control how the value is interpreted. If both of these bits are clear, then rawvalue is in RGB mode. If bit 268435456 is set, then the rawvalue is in XY mode. If bit 536870912 is set, then the rawvalue is in CT mode. If both bits 536870912 and 268435456 are set, then the rawvalue is in Hue/Sat mode.
For Unit 1 and Unit 3 color settings, you can set an RGB color value simply by setting the rawvalue to the RGB value. No conversions are necessary. This RGB value will be stored in the Analog IO rawvalue column and will remain at this value until the next time the light or group is "polled" at which time the color rawvalue will be updated to the equivalent XY color setting.
To set an XY color value for a Unit 1 or Unit 3, take the X value (a decimal from 0 to 1) and multiply by 10,000 and truncate any remaining decimal portion. Next take the Y value (a decimal from 0 to 1) and multiply by 10,000 and then multiply by 16,384. Truncate any remaining decimal portion. Add the new X and Y values together and then add 268435456. This is the rawvalue for setting color using a Philips Hue XY color. If you were retrieving the status of a rawvalue, you would first bitwise "and" the rawvalue with 536870912 + 268435456 (total value: 805306368) and then divide by 268435456. The resulting value will be 0 (RGB), 1 (XY), 2 (CT), or 3 (Hue/Sat). If this value is 1, then to get the X value, use the following formula: ph_and(rawvalue,16383) / 10000. To get the Y value, use this formula: ph_and(rawvalue,268419072) / 16384 / 10000.
To set a CT (Mired Color Temperature) value for a Unit 1 or Unit 3, start with the color temperature in degrees Kelvin (typically between 2000K and 6500K). Take the value 1,000,000 and divide it by the color temperature and truncate any decimal remainder. If you wanted to set a color temperature value of 6500K then the calculation would look like: long(1000000 / 6500) which would be equal to 153. Take the resulting value and add 536870912. If we were to use our example of 6500K, then the rawvalue would be 536871065. To reverse this process and get the data out of the rawvalue field, first execute: ph_and(rawvalue,805306368) / 268435456. If the result is 2, then we know the color value in rawvalue is stored in CT mode. To extract the color temperature, use this formula: long(1000000 / ph_and(rawvalue,16383)) which will result in 6535.
To set a color value using Hue/Sat for a Unit 1 or Unit 3, start with values supported by the Philips Hue bridge. The bridge expects Hue values to be in the range of 0 to 65535 and Saturation values in the range of 0 to 254. Take the Sat value and multiply it by 65536 and then add in the Hue value (0 - 65535). To this sum, add the value 805306368 to set the bits to indicate the value is a Hue/Sat mode color value. Extracting the value is the reverse of the process and similar to the other reverse methods above. First determine the mode that the value is stored in using this formula: ph_and(rawvalue,805306368) / 268435456. If the result is 3, then the rawvalue contains a color value in Hue/Sat mode. To extract the Hue, use this formula: ph_and(rawvalue,65535). To extract the Saturation, use this formula: ph_and(rawvalue,16711680) / 65536.
A Unit 4 Input/Output device allows for the activation of a scene selected from a list that was created as a User Range. In order to utilize this Unit 4 device, you must first create a User Range and associate rawvalues (the actual value is not really relevant other than it must be unique within the range) with a Philips Hue scene ID (and alphanumeric value that will be entered into the "Alpha Value (Optional)" field). You would also enter an appropriate Calc Value as the text representation of the scene. To activate a scene in a Unit 4 device, the rawvalue will be looked up in the User Range table and the associated Hue scene ID will then be sent to the Hue bridge.
A Unit 5 IOT Input / IOT Output device allows for the activation of the single scene associated with the device. You do NOT have to create a User Range for this scene activation method as the unique scene ID is entered into the "ROM ID / IP / Topic / Channel" column. You activate this device scene by setting the rawvalue to any value.
The PowerHome Philips Hue controller also exposes a controller command that allows you to send any Hue API command you desire to the Hue bridge. This can be achieved by calling the ph_ctlrcmd ( ) function with a "command" value of 999. Parm1 is a number from 0 to 3 that equates to the following HTTP methods used by the Hue API protocol: GET, PUT, POST, and DELETE. A value of 0 would be GET, etc. Parm2 is also a number from 0 to 3. A parm2 value of 0 will return the raw JSON returned by the Hue bridge as a result of the command. A parm2 value of 1, 2, or 3 will pass the raw JSON through the ph_flattenjson ( ) function with a type of 0, 1, or 2 respectively. Parm3 is the actual Hue API command you wish to send to the bridge. Parm4 is the JSON data that you wish to pass as part of the command.
The following formulas demonstrate the 999 controller
command and allow you to query the Hue bridge for configuration for lights, groups,
and scenes. These formulas are very useful as some of this information is
needed to properly configure PowerHome for control of lights, groups, and
scenes:
This formula will query the connected Philips Hue controller for
a list of defined lights and their status. Substitute the first parameter "HUE"
for the PowerHome ID of your Hue controller:
ph_ctlrcmd("HUE",999,0,1,"/lights","")
This formula will return the
defined groups: ph_ctlrcmd("HUE",999,0,1,"/groups","")
This formula will
return the defined scenes: ph_ctlrcmd("HUE",999,0,1,"/scenes","")
To
get the detailed information associated with a particular scene, use the previous formula
to get the unique scene ID and then substitute that for the "XXX" in the
5th parameter: ph_ctlrcmd("HUE",999,0,1,"/scenes/XXX","")