This accessor controls a Philips Hue lightbulb via a Hue Bridge. To use it, you need to know the IP address of the Hue Bridge, which is unfortunately, somewhat hard to find out. See below for some hints.
Upon initialization, this accessor will use the userName parameter to contact the Hue Bridge. If the userName is invalid, then the accessor will engage in a dialog with the Bridge to create a new user. This will require the user to push the button on the Hue Bridge when the alert to do so appears. The assigned userName will be recorded in the userName parameter.
Upon authenticating with the Bridge, this accessor will output a data structure that reports all the lights that have been registered with the Bridge. These lights each have a number ID, such as '1'. The state of each light will be reported in this output. The most important property of the state is the 'reachable' property. If this has value false, then the light is not reachable by the Bridge and therefore cannot be controlled.
The commands input is either a single command or an array of commands, where each command can have the following properties:
- id (required): The id of the light to manipulate, which is a number.
- on: true to turn on; false to turn off.
- bri: Brightness. 0-255.
- hue: Color, for bulbs that support color. This is a number in the range 0-65280.
- xy: Two numbers between 0.0 and 1.0 in an array, e.g. [0.4, 0.4], specifying a color according to the image at https://www.developers.meethue.com/documentation/core-concepts
- sat: Saturation, for bulbs that support color. This is a number in the range 0-255.
- ct: Color temperature. This takes values in a scale called "reciprocal megakelvin" or "mirek". Using this scale, the warmest color 2000K is 500 mirek ("ct":500) and the coldest color 6500K is 153 mirek ("ct":153).
- transitiontime: The time in ms for the bulb to make the transition.
Please see Hue docs for mapping colors to hue/saturation values: http://www.developers.meethue.com/documentation/core-concepts.
Some common colors given as xy are (for a gammut B bulb):
- orange: [0.60, 0.38]
- red: [0.67, 0.32]
- yellow: [0.54, 0.42]
- green: [0.41, 0.52]
- violet: [0.17, 0.04]
- blue: [0.17, 0.05]
- magenta: [0.41, 0.18]
- cool white: [0.28, 0.28] (about 10,000 Kelvin)
- warm white: [0.46, 0.41] (about 2,700 Kelvin)
If a light is not accessible, this accessor warns but does not error. In CapeCode, this results in a dialog box with a message. Sometimes Hue lights are transient (get unplugged, become temporarily disconnected) and may be valid in the future. Rather than terminating the model, we hope that the lights come back. A good practice is to use the lights output to determine which lights are reachable.
Discovery: Finding the IP address of the Hue Bridge is not necessarily easy. The bridge acquires its address via DHCP, so the address will typically change each time the bridge is rebooted. Moreover, the address will likely not be accessible except on the local network. The bridge responds to UPnP packets (universal plug-and-play), so it is possible to use software such as Cling to discover the bridge. Another option is to use the Discovery accessor and look for a device named philips-hue (or the name assigned to your bridge if assigned manually).
- Version:
- $$Id$$
- Source:
Inputs:
| Name | Type | Description |
|---|---|---|
commands |
JSON | JSON commands for the Hue, for example, {"id" : 1, "on" : true, "hue" : 120} |
probe |
Trigger production of a 'lights' output that gives the status of lights registered with this bridge. |
Outputs:
| Name | Type | Description |
|---|---|---|
lights |
An object with one property for each light that is registered with the bridge. The name of the property is the light ID, an integer given as a string, and the value is an object with information about the light (manufacturer, modelid, name, state, etc.). The state property has a boolean 'on' indicating whether the light is on and 'reachable' indicating whether the light is in communication with the bridge. | |
assignedUserName |
string | If a user name is automatically generated and registered with the bridge, then it will be sent on this output port. |
response |
The response from the bridge to a command. |
Parameters:
| Name | Type | Description |
|---|---|---|
bridgeIP |
string | The bridge IP address (and port, if needed). |
userName |
string | The username for logging on to the Hue Bridge. This must be at least 11 characters, or the Hue regards it as invalid. A username will be automatically generated if none is available. The assigned user name will be sent on the assignedUserName output. |
Methods
(static) initialize()
Add an input handler to react to commands. Commands will be ignored until the user is authenticated. If a bridge IP address has been given, contact the bridge to check if it is present. Next, register the user if not already registered.
(static) setup()
Define inputs and outputs.
(static) wrapup()
Turn off changed lights on wrapup.
(inner) bridgeRequestErrorHandler()
Handle an error. This will report it on the console and then retry a fixed number of times before giving up. A retry is a re-invocation of registerUser().
(inner) Hue()
Define a Hue function using a variant of the Module pattern. The function returns a hue object which offers a public connect() function. This will create an object with its own local state, allowing multiple Hue accessors to run concurrently without interfering with each other on hosts with a shared Javascript engine (such as the browser host).
An instance of the returned hue object implements the following public functions:
- connect(): Contact the bridge and register the user, if needed. Add an input handler to the trigger input to submit commands to the bridge.
- contactBridge(): Query the bridge for the status of lights registered with it. The status will be sent to the 'lights' output.
issueCommand(): Issue a command to the bridge. A command is an object that may contain the following fields:
- id (required): The id of the light to manipulate.
- on: true to turn on; false to turn off.
- bri: Brightness. 0-255.
- hue: Hue (for bulbs that support color). 0-65280.
- sat: Saturation (for bulbs that support color). 0-255.
- transitiontime: The delay before the bulb responds to the command. In ms.
For example, {"id" : 1, "on" : true, "hue" : 120}
(inner) registerUser()
Register a new user. This function repeats at registerInterval until successful or until maxRegisterAttempts. Some wait time is given between attempts for the user to click the button on the Hue bridge.