Differences

This shows you the differences between two versions of the page.

--- supported_hardware:hue [2017/04/17 15:09] – external edit 127.0.0.1
+++ supported_hardware:hue [2023/02/13 14:52] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-==Phillips Hue==
+=====Phillips Hue=====
+Note that this page is for the new Hue plugin that was released with XTension version 9.4.17 on 4/20/2019. For information on the original Hue plugin please see [[supported_hardware:hue_old|this page]].
 {{:supported_hardware:phillipshue.png?400 |}} XTension has full support for the [[http://www.meethue.com/|Phillips Hue Hub]] supporting the full color suite as well as the color temperature suite for all supported bulbs and lamps. XTension also supports any remotes, sensors and “clip” sensors that you may have attached to your hub.
-XTension also supports the commands for color looping as well as flashing the bulbs or temporarily flashing a color by way of alerting you in response to some input to the system.
+Color looping and performing alerts are also supported.
-One thing I never cared for with CF and LED bulbs was that they didn’t get warmer when they dimmed like traditional bulbs (though the new Warm Glow lamps also from Phillips do a great job of simulating that on a regular dimmer) you can now simulate that change with the color temperature value for these lamps.
+====Connecting to the Bridge from XTension====
+{{:supported_hardware:hue2_preferences.png?550 |}}
-==What You Need==
+If you have not set a static IP address or made a DHCP reservation for your hub you can leave the Address field blank and the plugin will attempt to find the Hub via UPnP. If you have set an IP for it then enter it there. Connecting via a static IP is faster. A static IP is required if you have more than one Hub on your local network as otherwise you will randomly connect to one or the other. Note that the UPnP discovery does not use the meethue service and so no internet connection is necessary.
-You will need at least the phillips bridge and one bulb. They come in a starter pack with the bridge and 3 bulbs. As I write this it is possible to add the phillips color bulbs to other ZigBee hubs such as the [[supported_hardware:vera|Vera]] however they don’t yet offer control over the color or support the other features of the bulb. If you have the Phillips hub you’ll definitely want to connect that to XTension.
-==Setting up the Bridge==
+The Port should generally be 80 unless you’re connecting to a remote hub via port mapping on a remote machine.
-Follow Phillips instructions for the initial setup and linking the lights with the bridge (they should come out of the starter pack all linked and ready to go) Though it's not strictly necessary it will save you problems later if you dig deeper into the configuration and set up the bridge with a static IP, or do a DHCP reservation in your airport or other internet router so that the bridge will always get the same IP on your local network.
-==Connecting to the Bridge from XTension==
+The Default Ramp Rate is the fade time in seconds that will be included with any commands for which you do not specifically specify a ramp rate. The Hue hub’s internal default is 0.4 seconds but if you wish the lights to by default move faster or slower you can enter that here.
-{{:supported_hardware:huepreferences.png?550 |}}In XTension's Interface window create a new interface and set it's type to "phillips hue bridge" if you dont know the IP address of the bridge you can click the "Search For Bridge" button which will go out to Phillips cloud service and ask it what the registered local IP of your bridge is. This is how all the IOS apps find a bridge to talk to on your local network but I have found it's not always updated if you change things. If you have multiple Hue hubs on the local network you will be provided with a link which will popup a menu to select the one who’s address you wish to use.
-Next you need to create a user in the bridge for XTension, so that it knows it's supposed to accept commands from us. Click the "create user" button and XTension will verify that it can talk to the bridge and then ask you to press the button on the center of the bridge. After pressing the button XTension will tell you that it's successfully setup and you can click save and then enable the interface and start it up by clicking the checkbox in the Interface list.
+Should you have any temperature sensors connected to the hub you can then select the format you wish the temperature to be reported to XTension in. The Hue motion sensors also include a temperature and light sensor. All temperature units created will show the temperature in this format.
-Once the Interface is enabled you can come back to this window to add devices to the Hub. You can place the hub into add units mode with that button, and if a lamp is having trouble joining you can enter it’s serial number directly here to look for that particular lamp. You can also put the hub into “touchlink” mode. This was also called “lamp stealer” and there was a separate app that set this up on older firmware versions. XTension now supports this for the latest firmware version. This is not only useful but vital if you’re going to be allowed to link a lamp that thinks it’s linked to a different network. The light must be powered on and almost physically touching the hub for this work but it’s often the only way to add a new lamp to the Hub.
+At this point you can save the interface and enable it from the Interface window. If this is the first time you’ve started up the interface it will write to the log that you need to press the button on the top of the hub. Once you’ve done that the status line in the Interface window will change from “press the hub button” to “Connected” if all is well and any devices you have connected to the hub should be created automatically in XTension. With the exception of Buttons on any remotes, see below for more info on the use of remotes like the Hue Tap or other remotes.
-==Making the XTension units==
+Once the interface is enabled and has a user created by your pressing the button you will also be able to use the “Touchlink” button to steal a lamp from another network. This requires that the interface be already setup and connected and will be greyed out if the interface isn’t running. This lets you assign a lamp to this network that has previously been assigned to a different network or that the Hue won’t connect to for some reason with it’s regular add new lamps functions. Normally you would add new lamps via the Hue app, but they don’t seem to have an obvious interface to the Touchlink feature so I’ve added it here. In order to work the lamp must be powered on and physically touching the top of the hue hub. This is a very  low power transmission so that you can’t steal your neighbors lights. You may also have to do a factory reset on the lamp in question before this will work. For some lamps it’s turning on and off the light 5 times once a second, you should look up the proper method in the documentation for the lamp. After clicking the button it will write to the log that touchlink is active, or the error if a problem occurred instead.
-As of XTension 9.2 any units found on the Hue Hub will be created automatically in XTension so you no longer have to create them manually.
-==Controlling Color==
-The hue bulbs have 2 ways of setting their color, a hue/saturation number or an x/y coordinate system. XTension also supports a conversion from standard web colors expressed in the standard notation of 6 characters of hex for red green and blue. "RRGGBB" format. The hue bulbs seem heavy on the red so to get the colors to match what you see on a swatch you'll need to reduce the amount of red you're sending somewhat. XTension lets you use any of these ways to set the color. A color change must accompany a turnon command or a dim command, but the brightness of the bulb is inherent in the color, so the current brightness level of the lamp may change to be different from the dim or the current value you have set.
-  turn on "hue device" rgb color "AAFF22"
+====Controlling Color====
+{{:supported_hardware:deailed_hue_control.png?250 |}}
-sets a reasonable yellow. The other forms of sending color are via hue/saturation or the x/y like this:
+One of the advantages of the new Hue plugin is that it uses the proper gamut corrections for the various lamp types as reported by the hub so color representations should be more accurate than in older versions. This plugin supports non-dimmable hue devices, dimmable only devices, color temperature only devices, color only devices and the most common type which support both color and color temperature. When controlling a bulb manually from either the web interface or the local interface the proper controls will be displayed based on the capabilities of the lamp allowing you to select colors, color presets or color temperature.
-  turn on "hue device" hue 45032 saturation 200
+Click on the Jewel in any list to bring up the detailed control window. On top are the standard light and brightness controls that are available for all dimmable devices. Below that will be the color selection controls and below that the color temperature control section. This is now standardized for Hue and other lights. Though the hue does not use the actual color temperature value to set it’s color XTension will translate between the two and will show you a standard mired color temperature slider.
+The current color or color temperature are displayed at the top of the window next to the dimmer. A small “w” will be displayed if the current color is a color temperature. A small “c” will be displayed if the current mode is displaying a color. You can click this control to being up the standard system color picker to choose a specific color.
+A color panel is displayed and you can click anywhere in this to select a color to display. On the web interface this is simplified with fewer choices so as to be easier to tap on something specific.
+Below that are the color preset selections. They also display the “c” or “w” to show which mode of color they represent. In order to save a color preset from the current setting of the lamp control click on the preset you wish to program and select “Set preset from the current color”. You can also set a color preset from the Edit Unit window for the Unit. The help tag for the presets will display either the RGB values of the color they are set to or the color temperature in °K. hover your mouse over one to see that.
+The color temperature slider will let you select a color temperature to send to the lamp. Selecting a color temperature will change the lamp’s mode to color temperature from color if it was previously displaying a color.
+Below that are some controls that are specific to the Hue bulbs. If the lamp supports color you will see the “Start ColorLoop” and “Stop ColorLoop” buttons. All Hue bulbs support the “Alert” and “Long Alert” functions. Alert changes the brightness of the bulb for a second or so and then returns to the preset brightness. Long Alert will do that over and over for 15 seconds.
+====Scripting Color and Color Temperature====
+All XTension verbs that you would use to control a lamp will also accept a color temperature or color value. The standard way of expressing colors in XTension is via their HTML format as “RRGGBB” so “FF0000” would be full red, “00FF00” would be full green and so forth. Additionally you can include hue/saturation and x/y values though these may be less accurate in their translation to the physical devices. The RGB values are specifically tuned to the individual devices. When possible you should use the RGB values.
+for all color interactions the brightness is taken from the brightness of the bulb not the brightness of the color. For instance turning on a lamp with a color of “0000FF” will result in exactly the same color display as turning on the bulb with the color “000033” as the brightness of the color will be the current value of the lamp and not the value inherent in the color. This is also why the “value” for hue/saturation/value is missing from the verbs below as it is taken from the value of the device.
+<code>
+  turn on “hue device” rgb color “AAFF22”
+</code>
+returns the bulb to the last level that XTension knows about and sets the color.
+<code>
+  brighten “hue device” to 75 rgb color “AAFF22”
+</code>
+sets the value to a specific level and sets the color
+<code>
+  brighten “hue device” to 100 color temperature 2700
+</code>
+will change the lamp to white or color temperature mode and set the color temperature to 2700. Note that previous Hue plugins required you to use the internal numerical value that the Hue bulbs used to represent color temperature, this is no longer the case and all color temperature values for all devices should be passed in actual °K.
+If you wish to use hue/sat or x/y values to set colors that format is below. All hue, and x,y values should be decimals between 0 and 1.
+<code>
+  turn on "hue device" hue 0.1234 saturation 200
   turn on "hue device" xValue 0.134 yValue 0.441
+</code>
-You can set the color in XTension also by control clicking on the unit in any list and selecting "set color" which brings up a standard system color picker that you can choose from.
-As of XTension build 850 and later the color data as XTension knows it will always be sent with any on or dim command. This is useful since the bulbs do not remember their color state when the power goes out and will return to white. It also adds the ability to change what this stored value is while the light is off using the sim preset command like:
-  sim preset "hue device" to 100 rgb color "AAFF22"
+If the bulb is off and you wish to change what the color or color temperature that will be displayed the next time the bulb is turned on without specifying these values you can use the sim preset command:
-if the light is off that will not cause the light to go on, but the next time you issue an on without color data specified it will pass that level and color to the bulb.
-{{:supported_hardware:hue_properties.png |}}You can see what color the bulb is current set to, or get a good color you like out that you've set from some separate controller by control clicking on the unit and selecting "edit unit properties" you'll get a display that looks like this. The "color mode" will tell you which values are actually being used right now. "hs" means that the Hue and Saturation values are the ones you're seeing, if it says xy then those numbers are currently active. If it says "ct" then the bulb is in "white" mode and the Color Temperature value is what is being displayed. You can read out these values and send them in verbs to get the same color later from XTension.
+<code>
+  sim preset "hue device" to 100 rgb color "AAFF22”
+</code>
-==White Color Temperature==
-You can change the color temperature of the white being displayed by using the "color temperature" parameter of the turn on or dim verb like:
-  turn on "hue device" color temperature 300
+==Scripting Alerts and Color Loops==
-will produce a good warm white. The valid range is from 153 for a very cool white up to 500 for something that looks more like orange to me. So I can have cool white when I"m working with sunlight adding to the room light and then warm things up in the evening when it's dark outside and the cool would look grey. This is really a nice adjustment to make.
-==alerts and color fades==
+Note that these are different from the original plugin which used the Blink verb. The Blink verb is supported for backwards compatibility but for new scripts you should use these functions.
-The phillips bulbs support some alert and color fade modes accessed via the "blink" verb in XTension.
-  blink "hue device" rate "select"
+To preform a short alert via a script:
-produces a single flash.
-  blink "hue device" rate "lselect"
+<code>
+  tell xUnit “hue device” to shortAlert()
-for "long select" will flash the bulb for 30 seconds. And can be canceled by you at any time by running the command again and passing "none"
+</code>
-  blink "hue device" rate "colorloop"
+and a longer 15 seconds alert:
+<code>
+  tell xUnit “hue device” to longAlert()
+</code>
+To cancel a long alert that is in progress:
+<code>
+  tell xUnit “hue device” to stopAlert()
+</code>
+to start and stop the color looping feature via a script:
+<code>
+  tell xUnit “hue device” to startLoop()
-starts the bulb slowly cycling through all it's colors and can be cancelled by setting it to a specific color or white or running the command again and passing "none" There seem to be some holdover from other commands as to how deeply saturated the color loop colors are and the rate at which they change. This doesn't appear to be documented so some experimentation might be necessary to get the effect you want here. It seems that you can issue other color change while the loop is running to change the saturation and brightness.
+  tell xUnit “hue device” to stopLoop()
+</code>
-==Other Scripting and Examples==
+====Adding Ramp Rates====
-all the commands support the "rate" parameter. So you can fade very slowly from one color or white temperature by adding "rate 500" to the end of the command or make the change happen immediately by setting 0.
-you can script a flash to a color in XTension even though the Hub doesn’t support this directly by using standard XTension commands such as:
+All the commands support the “rate” paramter. You can fade slowly by specifying a longer number of seconds, or very quickly by specifying 0 or 0.1. If you wish to send a value less than a second, or including fractions of a second you may include a decimal fraction of a second.
 <code>
-  brighten “hue device” to 100 rgb color “FF2222” for 2
+   TurnOn “hue device” rgb color “55FF22” rate 5
 </code>
-which will turn the bulb on full bright to red for 2 seconds and then return to the previous state or color.
+would take 5 seconds to change from the currently displayed color to the new color. Or you can fade from a warmer color color temperature to a cooler one at some point in the day:
+<code>
+   brighten “hue device” to 100 color temperature 3500 rate 30
+</code>
+Note that previous versions of the plugin used the low level value in 0.1 seconds that the hue uses internally so to fade over the course of 1 second you would have had to specify a rate of 10. That is no longer the case, the new plugin uses the XTension default of seconds and will handle that conversion for you.
+====Hue Sensors====
+Any motion or temperature sensors added to the Hub should just show up in XTension without any other configuration needed. If the sensor supports multiple sensor values they will each get their own unit in XTension. For example the Motion sensor also has a temperature and a light sensor in it. That device will create 3 units in XTension for Motion, or presence, temperature and light level.
+====Hue Remotes====
+All remotes will create a “parent” unit with the address of the remote. This unit is necessary to send the button events to the proper button units but will not otherwise change state. Adding code to it’s on/off scripts will not be executed. The unit will however display the battery level and error status of the device and can be used for that.
+If you wish to use your remote directly in XTension without having it linked to any hue devices directly there is a way to set it up to do that. Normally a remote button must be linked to at least one group or scene or lamp in the hue hub. During the setup of a new device in the Hue app however there is an option at the bottom to “setup in separate app” that will leave it unconnected to any specific hue devices. The units in XTension will still receive the events and you can use those scripts to control non-hue devices then, If you have already setup the device in the hue and wish to remove it’s direct association with all hue devices there is a button for “reset” in the setup for the remote, after that you can select the “setup in separate app” button and it will function normally in XTension while not controlling anything in the hub.
+====Conversion from old plugin====
+The documentation for the old plugin is [[supported_hardware:hue_old|here]]
+As of this first release there is no attempt to convert units automatically from the old system to the new one. If you wish to convert an existing install you should change the interface type from the old plugin to the new. After doing that but before enabling the interface you can edit each unit and change the device type popup from the older values to one of the new unit types. It should be obvious which corresponds to which but there are more device types now than there were as we support more lamp types and there is a new unit type for remote button. After selecting the proper values for the units you should be able to enable the interface and have it pick up on any existing units. The addresses should not be any different from the old plugin to the new plugin, only the unit type has changed.
-==Hue Sensors==
+Note that controlling the lamps via scripting may have changed. The Blink verb is no longer used for alerts and color looping but the specific commands shown above. The color temperature no longer is the low level internal value that Hue uses, but a standard mired color temperature in °K so you may have to change any verbs that you used to set those with the old plugin.
-Any motion or temperature sensors added to the Hub should just show up in XTension without any other configuration needed.
+Color selection is now much more accurate than it was with the previous plugin. You can still use hue/sat to set the colors, but you should verify that they are still the same as you like and switch to RGB for any new commands that you might write as those are better converted internally and adjusted for the specific hue lamps.
-==Hue Remotes==
+Ramp rate values are now in fractions of a second. Previously the plugin required that you enter multiples of the low level hue interval of 100 ms. It’s now standardized on seconds. To perform a fade over 2.5 seconds just specify a rate of 2.5 to fade over 2 minutes use the standard applescript notation like "rate 2 * minutes”
-As of this writing there are 2 different remotes that can be used with a Hue hub. Phillips “tap” battery less device and the dimmer remote which does require a battery and can be either mounted to the wall or used as a hand held remote. These units will also be created automatically in XTension. Each one will create a unit in XTension for each button on the remotes. They may not receive off events, but will receive ON events when the buttons are pushed.
-Whats not immediately obvious is how to create the remote in the Hue hub and yet not assign anything to it in the hub. The default is that it always controls at least one lamp somewhere. In my case I didn’t want the hub to directly control any lamps when the remotes were used, I wanted to link those things to other events in XTension. I was able to do this by creating a new room with a single lamp. Setting up the remote to control that room and then remote the lamp from that room. The remote remains pointed to that room, but there are no lights in it for it to control. After doing that I was able to get the remote events in XTension without having it directly control any Hue devices.