Differences

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

--- dictionary:unitcontrol:dim [2016/03/14 15:21] – external edit 127.0.0.1
+++ dictionary:unitcontrol:dim [2023/02/13 14:52] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 ====Dim or Brighten====
-Set an analog device to a level between 0 and 100
+Set an analog/dimmable device to a level between 0 and 100
 ===Usage:===
-**dim** "name of the unit or group"\\
+**dim** "name of the unit or group”
 **brighten** "name of the unit or group”\\
 ===Optional Parameters:===
-**to** (integer value between 0 and 100)\\
+  * **to** (number) the value you wish to set the unit to. While this accepts a decimal most device types will not accept a fractional dim level. For most devices this should be a value between 0 and 100. If the device requires different value ranges the min/max values for that unit may be set in the Advanced tab of the Edit Unit Dialog. You must specify either the **to** parameter or the **by** parameter.
-**by** (integer, change the current level by this value, an integer between -100 and 100)\\
+  * **by** (integer) change the current value by this amount. Can be positive or negative. You must specify either the **to** or **by** param.
-(you must include either the **to** value or the **by** value)\\
+  * **in** (integer: seconds) If specified an event is created that will apply the new values in this number of seconds.
-\\
+  * **at** (date) Like the **in** param but a specific date at which the event will be created.
+  * **for** (integer: seconds) If specified an event will be created to return the unit to it’s current settings after this many seconds.
-**in** (integer, create a scheduled event to perform this dim in this many seconds.)\\
+  * **until** (date) Like the **for** param but a specific date at which to return to the current settings.
-**at** (date, like in, the applescript date at which the dim should happen.)\\
+  * **with no script** Will not run the unit’s on or off script.
-\\
+  * **with no transmit** The XTension database will be updated with the new value but no command will be sent.
-**for** (integer, create a scheduled event to return the unit to it's current value in this many seconds.)\\
-**until** (date, like for, the applescript date at which the lamp should return to the current value.)\\
-\\
-**with no script** (dont run the unit script)\\
-**with no transmit** (update the database and run the script, but dont actually send any commands)\\
 ===Color Support===
-Many color capable bulbs are now available for ZWave and ZigBee via the [[supported_hardware:hue|Phillips Hue]] hub. XTension can also create an “RGB Pseudo” that groups any 3 other units as the red, green and blue channels of a single fixture. Even if your device is not directly supported as an individual color lamp the channels are usually available separately. This is normally the case with ZWave 3 channel controllers. There are several optional parameters to this command for setting color. Some are specific to the hue bulbs, others will work for any color capable device.
+  * **rgb color** (text: html color)a standard HTML color string with each 2 characters being 00 to FF a hex representation of the level of that color in the mix. This is the normal way to set the color of a bulb. “FF0000” would be full red, “0000FF” would be full blue.
+  * **color temperature** (integer) The Mired color temperature you wish to display. The available range is specific to the device but will be in the range of 2000 to 50000. 2700 would be a “warm” white. 3500 would be a “bright” or halogen white. 5000 to 6000 would be a “daylight” white. Not all devices support a color temperature setting.
-**rgb color** (text, a standard HTML color string with each 2 characters being 00 to FF a hex representation of the level of that color in the mix. All color devices support the rgb color command. This is the normal way to set the color of a bulb. “FF0000” would be full red, “0000FF” would be full blue.)\\
+  * **hue/saturation** (number) An alternative method of setting the color. You must specify both the **hue** and **saturation** the value is taken from the level of the unit.
-**hue/saturation** (integer, if using a Phillips Hue bulb you can set the color by passing the hue and saturation. If using this you must pass both the hue and saturation values.)\\
+  * **xvalue/yvalue** (number) Another alternative method of setting the color. You must specify both the **xvalue** and **yvalue** the z value or level is taken from the level of the unit.
-**xvalue/yvalue** (number, another method of sending color to a Phillips Hue bulb. If using this you must pass both the x and y coordinate values.)\\
+  * **color preset** (number, 1-8) sets the color or color temperature to the preset indicated that you have saved in the Edit Unit Dialog.
-**color temperature** (integer, currently supported only for Phillips Hue bulbs this number corresponds to the color temperature. For the hue bulbs this is not the actual color temperature in kelvin, but a number from 153 to 500 with larger numbers being warmer. As other bulbs become more commonly available that support changes in color temperature support will be added for those.)\\
-**color preset** (number, 1-8, all color capable devices can have 8 colors or color temperatures set as presets. You can recall one by passing the color preset number to this parameter.)
-===Color Handling===
-If you are using a color capable device keep in mind that the level that the lamp displays the color at is separate from the brightness of the color that you are passing. For example, dimming a lamp to 10% with an rgb color of “FF0000” would result in a color at the lamp that is really “190000” So if you wish a dimmer red, you can just pass the full on along with a lower dim level. Color presets are handled in the same way. This can be a little confusing when just reading about it, but it does seem to make the most sense when actually using the lamp. You have your lamp at a specific color and you wish to change it to another color, you don’t wish the level to change dramatically along with that color preset change. This is how the Phillips Hue bulbs handle color changes natively and how XTension handles the RGB pseudo internally.
-RGB colors on the computer screen do not correspond perfectly to the color displayed by the bulb. A lot of work was done to support the specific transforms necessary for the Phillips hue bulbs and as long as you are choosing a color that the bulb can actually generate the color display is pretty close. For RGB Pseudo devices there could be considerable differences between what is displayed on your screen and what is shown at the lamp. Many less expensive devices seem to have an underpowered red channel and so you may have to boost the red above what you need to see the proper color on the screen in order to see the proper color on the lamp itself.
 ===Examples:===
@@ Line 60: / Line 47: @@
 The "by" clause is intended for "relative" changes.\\
 \\
-As an aid in preventing limit errors in such "relative" changes, Xtension will limit the range of the command to values between 0 and 100 for real units. Thus if you try to dim a lamp below 0 XTension will limit it to zero. Likewise, if you try to brighten a lamp above 100, XTension will limit it to 100.
+As an aid in preventing limit errors in such "relative" changes, Xtension will limit the range of the command to values between 0 and 100 for real units. If the unit has it’s **use min/max** turned on in the Advanced tab of the Edit Unit window those values will be used instead.