Differences

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

--- xtension_manual:controllingunits [2018/04/10 02:43] – James Sentman
+++ xtension_manual:controllingunits [2023/02/13 14:52] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 =====Controlling Units From Lists=====
-The [[xtension_manual:lists|List]] is the main interface element in XTension for controlling of units. It offers many options and keystroke shortcuts for sending the command or setting the value that you wish.
+The [[xtension_manual:lists|List]] is the main display, control and organizational feature of XTension. All your units will always be in the Master List and you can create any number of other lists. Those lists can each have different display options and layouts. They can be displayed either in the App or on the [[:webremote|Web Interface]].
-{{ :xtension_manual:masterlist_9.4.png?direct&600 |}}
+{{ :xtension_manual:masterlist_9.4.png?direct&700 |}}
-For a simple toggle of the Unit you can use the default toggle control which will display in the Control column, If the unit has it’s [[xtension_manual:editunitdialog|Ignore Clicks In List]] setting turned on then the toggle will not display a paddle for you to click on, but just the current value or value label of the unit. This stops you from accidentally clicking on a unit that should not be directly controlled.
+====List Control Types====
-{{:xtension_manual:hvac_popup_control.png?300 |}}For some units a toggle might not make sense. You can change the control type displayed for a unit by changing the list control type in the Edit Unit dialog, or just control click on the Unit in any list and select a different a different List Control Type. The "buttons” control type lets you send an On or an Off regardless of the current state of the unit, The Text Field displays the current value of the unit and clicking on the table cell lets you enter a new value for the number. Pressing return, clicking away or tabbing away from the field sends the new value to the unit, pressing escape closes the edit field without sending the new value. The Popup Menu type lets you select from a list of possible values. You can define the list in the Edit Unit dialog. This is useful for devices for which text names for the different values make more sense than just a numerical value. For example a thermostat mode unit might be able to be set to Off, Heat or AC. The values you have to set that to might be 0, 1 and 2, but that doesn’t make for easy control. By creating a list of 3 entries in an HVAC Mode unit you can select from a popup of the valid values. Lastly you can also select “none” and then that unit will not display any control in this column. You can hide or show the entire control column by control clicking on the headers of the list and using the contextual menu entries for managing columns.
+By default a new List window will show the Control column in the first column of the window. You can add or hide the column by control-clicking in the headers of the List and selecting the show or hide menu items for the column you wish to add or hide. You can drag it to a new position or resize it like any other column. You could drag the control column so wide that the toggles look silly, don’t do that. If you have hidden the Control column you can still control the unit. Double clicking any row will toggle the unit. Clicking on the Value column or the jewel status display in the Name Column will bring up the Detailed Unit Controls with more control and timing options. (see below)
-All of these features work the same way on the Web Interface with the exception currently of editing the layout of the list. Setup your lists the way you wish them in the App and they will be presented in the same way when you’re accessing remotely via the web remote.
+By default Units will display with the Toggle control type. You can change to any of the other types or None by control clicking on the unit row and selecting the “Set Control Type” menu or by selecting the control type for that unit in the [[xtension_manual:editunitdisplay|Edit Unit Dialog]].
-\\
-You can bring up a more detailed control window for a unit in several ways. Clicking on the background of the Toggle control, on the Value column or on the unit jewel in the Name column will open the detailed controls dialog for that window. The controls displayed will depend on the capabilities of the unit and if you’ve fully expanded the window to show all controls via the disclosure triangle on the upper left hand side.
+===Toggles===
-\\
+For a Discrete (non-dimmable) Unit a toggle control will show the “On” and “Off” labels. If you set On Label or Off Labels in the [[xtension_manual:editunitdisplay|Edit Unit Dialog]] then those labels will be shown instead. If the unit is dimmable the value, along with any formatting and suffix options you have setup for the unit will be used for the display. If the On or Off Labels are set in a dimmable unit they will display instead of the numerical value.
-\\
-{{:xtension_manual:hudnondimmable.png |}} From this window you can immediately send an ON or OFF for the Unit. You can also Block or UNBlock a unit. A blocked unit will refuse to send any commands from XTension unless you use the [[dictionary:unitcontrol:forceon|Force On]] or [[dictionary:unitcontrol:forceoff|Force Off]] scripting commands. It can’t stop the unit from receiving and responding to commands generated from other devices or NON-XTension interfaces to your system however, so if commands are received the state in the database is updated but no Unit Scripts will be executed for a blocked unit. By clicking the Edit button or by clicking on the Name of the Unit XTension will switch you to the [[xtension_manual:editunitdialog|Edit Unit Window]] for this Unit. After clicking the ON or OFF button the command is sent immediately and the window is closed.
+<block 100%>
-\\
+{{:xtension_manual:toggles.png?300 |}}
+Clicking the grey paddle of the control will toggle the state of the unit. Clicking in the background of the toggle, not on the paddle, will cause the detailed unit controls to popup for that unit offering more control options. (see below)
+</block>
-{{ :xtension_manual:huddimmable.png|}} Opening the popup control window for a Unit that is dimmable opens a similar window but with additional controls for setting the value. A vertical slider is added to the window for quickly sending a new dim value. The new value is sent as soon as you let go of the slider but no attempt is made to send continual commands as you drag it up and down. For most dimmable units the slider limits are 0 and 100%. If the Unit is a “Register” type with a min/max value set or other Unit type that supports the min/max settings then those will be reflected in the sliders top and bottom values. For more precise value entry, perhaps for a thermostat setpoint, or one that requires a decimal point you can type directly into the Value field and click the Set button or press Return.
 \\
-{{:xtension_manual:detailed_controls_with_popup.png?325 |}} If you have set the list control type to a popup, then instead of the standard value field you’ll get a popup of the value choices you entered on the edit unit dialog page.
+<block 100%>
-\\
+{{:xtension_manual:togglesignoreclicks.png?290 |}} If a unit has it’s [[xtension_manual:editunitdialog|Ignore Clicks In List]] setting turned on then first level clicks in the list control will not immediately toggle the unit. This is to keep accidental clicks from turning on or off important units. It’s also useful for devices that you wish to display in the control column but that cannot actually be controlled like a temperature sensor. The Paddle of the toggle is not shown and the label or value is displayed centered in the paddle background. Clicking on the background will bring up the Detailed Unit Controls and from there you can control the unit even with the Ignore Clicks setting selected.
-\\
+</block>
-\\
-\\
-\\
+===Buttons===
-\\
-\\
+<block 100%>
+{{:xtension_manual:togglesandbuttons.png?300 |}} For some units it may make more sense to be able to specifically send an on or off regardless of the current state of the unit. Some devices might be locally controlled and have not sent an update or been polled in which case the database might not reflect the true state of the unit. With a toggle you’d have to click it twice to get the device into the desired state in this case. The button control will display the current state, but you can click either button to send an On or Off regardless.
+</block>
 \\
-{{:xtension_manual:hudlarge.png |}} If you click the disclosure triangle in the upper left hand corner of the popup control window it will show even more controls for the Unit. First you’ll notice a more detailed status display at the top with the last activity of the unit, it’s current value and it’s description, if any is set. Below that there are more buttons for quickly controlling to a specific level in just a single click or increasing and decreasing the values by specific amounts. The expanded or hidden value for these controls is remembered on a Unit by Unit value for each List so if you always control a unit with the expanded popup display it will remember that but you won’t have to see all the extra controls for units for which you rarely use them. The next time you open the Popup Control window for a unit it will be in the same state you last used it. \\
-\\
+===Text Field===
-The next set of controls is for creating events that will set the Units value at some point in the future or for some period of time. These are basically the same as the optional “in” and “for” parameters of the [[dictionary:unitinformation:setvalueof|Set Value]], [[dictionary:unitcontrol:turnon|Turn On]] and [[dictionary:unitcontrol:turnoff|Turn Off]] verbs. Each value has a time field where you can enter some number and a time descriptor popup that tells XTension what the number in the first field corresponds to. The values are seconds, minutes, hours and days for each. If you set either or both of these controls and then click the ON/OFF or SET buttons above one or more Scheduled Events will be created for the Unit that will perform the requested action in the requested amount of time. If you also specify a “For” parameter then a second event is created that returns the Unit to the state it is **right now** in the requested interval. If the unit is already on and you use this to turn on in 10 seconds for 10 seconds the return event will return this this state, which is already on, so nothing will actually happen as far as the light is concerned.\\
+<block 100%>
+{{:xtension_manual:editfieldcontrol.png?300 |}} The Text Field control will display the raw numerical value of the unit. If you click once in it the field will change to a regular edit field and you can quickly type in a new value. Press return, click or tab away from the field to send the new value. Press Escape to stop editing without sending the new value.
+</block>
 \\
-Lastly this also adds the “Remove Events” button. This will remove any events that were added to the unit via the “in” and “for” interface elements or via the “in” or “for” parameters of the unit control verbs. It will not remove scheduled events created specifically for the unit, only those created automatically via this mechanism.\\
-\\
+===Popup Menu===
-{{ :xtension_manual:hudcolor.png|}} If the Unit you’re controlling has other supported features the controls for those will also be displayed in the popup control window. In this example we’re controlling a [[supported_hardware:hue|Phillips Hue Color Bulb]] through our connection to a Hue Hub. All the color controls are available. You’ll see a best approximation of the current color of the bulb in the upper right of the window. There will also be an indication if the bulb is in Color Temperature mode as in the case of the example a small “w” is displayed to show this is a white color temperature. If a color is being displayed then a small “c” will be drawn in the same place. Clicking on this color will bring up the system color picked for you to choose a new color for the lamp. By hovering your mouse over the color a tool tip will display that shows either the RGB color information or the approximate color temperature that the bulb is displaying.\\
-\\
+<block 100%>
-Below the “in” and “for” section a color control section will be displayed for color capable devices. Changes to the RGB sliders will be sent immediately to the lamp when you let go of the slider. To the right of those are the color presets for the Unit. They will also indicate if they are storing a color by showing a small “c” in the corner or a white color temperature by displaying a “w”. If the device is not capable of both kinds of color no indicator will be displayed. Clicking the color preset sends that color to the device. If you have changed the color of the bulb via the RGB sliders or the color temperature slider you can program the new value into a preset by control or right clicking on the preset you wish to change and selecting “set this preset from the current color” from the contextual menu. Most color capable devices process color separate from value and so the color as displayed in the preset may not accurately reflect what is actually coming from the device. An RGB color value includes the brightness level, but only the color is actually sent to the device and the brightness will remain as it’s currently set so the color may be different. While this may not immediately be the obvious way it should work on further reflection I agree with it. If you have a light level set dim and you select a color you really don’t want the bulb to go to full brightness, you want it to change the color and remain at approximately the same brightness level. You can always dim or brighten the bulb to a new level after sending the color, of if you’re setting the state from a script you can include the brightness and color at the same time via the [[dictionary:unitcontrol:dim|Dim]] command.\\
+{{:xtension_manual:hvac_popup_control.png?300 |}} Creating a popup menu makes sense for units that require more states than just on and off but isn’t truly dimmable. You might want to use the popup control for the Mode of a Thermostat. Normally a thermostat mode unit is dimmable, but only a few numerical values make any sense. 0 for Off, 1 for Heat, 2 for AC, etc. In the [[xtension_manual:editunitdisplay|Edit Unit Dialog]] you can enter a comma delimited list of values that will display in the popup. To generate the popup shown to the left you’d enter “Off,Heat,Cool”.
-\\
-If the device supports changing color temperature then the color temperature slider will be displayed next. Changes to the bulb color are sent immediately as soon as you let go of the slider.
+{{ :xtension_manual:popupmenusetup.png?400 |}}
+You might also create a pseudo unit for the Mode of a room. Create a popup with the values “Off,Nightlight,Low,Normal,Full” and in the On script of the pseudo unit check the [[dictionary:unitinformation:futurevalue|Future Value]] and setup the values of the various lights based on the value that was selected.
+</block>
+<WRAP clear/>
+====Detailed Unit Controls====
+{{:xtension_manual:huddimmable.png?direct&300 |}}
+More control possibilities are exposed by the Detailed Unit Controls window. You can open this window for any unit by clicking in the background of a Toggle Switch control, by clicking the jewel status indicator in the Name column or by clicking on the Value column for that unit. If you are navigating with the keyboard pressing the left arrow key will bring up this window for the selected unit.
+What is displayed in the Detailed Controls window depends on the capabilities of the Unit. If the unit is dimmable you’ll see the value field and the dimmer slider. If not you’ll only see the On/Off controls. All Units will get the [[dictionary:unitcontrol:block|Block]]/[[dictionary:unitcontrol:unblock|UnBlock]]buttons as well as the [[dictionary:events:removeunitevents|Remove Unit Events]] button.
+<WRAP clear/>
+{{:xtension_manual:detailed_controls_with_popup.png?300 |}}
+If you have the List Control Type for the unit set to Popup then the same values you have configured for that will be offered in the Detailed Controls window. Making a change to the popup sends the new value immediately.
+<WRAP clear/>
+====Time Frame for Commands====
+{{:xtension_manual:hudlarge.png |}}
+By clicking the disclosure triangle in the upper left of the window you can expose yet more information and controls. In addition to displaying the Description of the unit you’ll also get some quick click buttons for incrementing the value or jumping to a specific value.
+You can create timed events to send values using the In/For selection here. The In fields holds the time before the action is performed. The For field will return the unit to it’s current value after that amount of time. To include a time frame with a command set the values that you wish and then perform the action and the time frame will be included. You can include a time frame for an On, Off, Set Value and Block/Unblock command. When setting a value use the Value field and click the Set button once you’ve setup the time frame fields. Using the slider sends the value instantly regardless of the in/for settings.
+When using the For field remember that the unit will return to it’s current value at the end of that time. If you turn on the unit for 10 minutes and the unit is already on then nothing will appear to happen at all as it’s already on, and will return to being on after the timeout. If you want the unit to turn off in 10 minutes send it an Off command In 10 minutes and not a turn on For 10 minutes.
+In/For commands automatically create unit events. If you’ve created several such events and want to remove them so you can be sure what the Unit will do you can use the “Remove Events” button. That will remove any automatically created events for the unit, that is any event that was created via the In/For parameters. This includes automatic events that were created by scripts or other sources and not just your session in this interface.
+<WRAP clear/>
+====Color and Color Temperature Control====
+{{:xtension_manual:colorcontrolhudwindow.png?direct&300 |}}
+If the Unit you’re controlling has color or color temperature support then additional controls will be displayed in the Detailed Controls Window.
+In this example the Unit is controlling a [[supported_hardware:hue|Phillips Hue Color Bulb]] so is displaying both the Color and Color Temperature controls. A best approximation of the color currently being shown by the device will be displayed at the top of the window. By clicking on that swatch the system color picker will be presented and you can pick a new color from that. You can also use the color pallet to select from a range of colors.
+If the device is capable of both color and color temperature then the swatches will display a “c” if it’s a color preset or a “w” if it’s a color temperature that is being shown right now.
+If you like the current color being displayed by the swatch and the bulb you can control click on any of the color preset swatches to save that color to it. Presets can hold both color or color temperature values. Clicking on a preset will recall that color or color temperature to the bulb.
+====History====
+  * Controls in the list window were added in XTension version 9.4