Differences

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

--- dictionary:unitinformation:index [2017/08/30 15:49]
127.0.0.1 external edit
+++ dictionary:unitinformation:index [2019/09/06 19:24] (current)
James Sentman rewrote entirely as it was a very awkward page before. Also added new group properties
@@ Line 1: / Line 1: @@
-====Getting Unit Information====
+====The xUnit Class====
-===Using the xUnit Class===
-Most of the data that is available via the information verbs below can also be accessed via AppleScript object model properties. Some things can only be accessed through the object model. This is a list of unit class properties that are of use separately from the regular access verbs:
-===Time Stamp===
+Some unit properties are available via individual verbs as listed below. Others are available for getting or setting via the Apple Script object model using the format “set (name of property) of xUnit (name of the unit) to (the new value)” or for reading them out via something like “set myValue to (name of property) of xUnit (name of unit)” If you wish to write the property to the log be sure to add the “as text” phrase at the end of the log line like:
- **xtTimeStamp** returns the same value as the [[dictionary:unitinformation:lasttimestamp|last timestamp]] verb. The unit property is read/write and so you can adjust or set the last activity of the unit through this property:
+<code>
+write log (xtShowDimmableControls of xUnit “my group”) as text
+</code>
+or you will just get an unreadable portion of the raw Apple Event data written to the log instead.
+The most commonly used unit data is available via the information verbs listed below. Others can only be accessed via AppleScript object model properties. Original properties are accessed via a simple name, newer properties have the prefix “xt” added to them to avoid colliding with the base AppleScript scripting terminology.
+----
+**xtAddress** (read/write, string) get or set the address of a unit. The verb will return an error if the address is already in use on this interface for this specific device type.
 <code>
- set xtTimeStamp of xUnit “my sensor of something” to (current date) - 4 * days
+write log (xtAddress of xUnit “unit name”)
+try
+  set xtAddress of xUnit “unit name” to “F13”
+on error
+  write log “unable to set the address of unit name to F13, that address is already in use” color red
+end try
 </code>
-This has implications for saving this in [[:xtdb|XTdb]] XTdb will refuse to save a change of the last activity date of a unit if the new date is before the current last timestamp of the unit as that would require re-indexing the data file. As long as the new time stamp you’re setting is after the current last time stamp the database will be updated to reflect the new date.
+see also: [[dictionary:unitinformation:setaddress|set address]]
-===Display Labels===
-**xtCurrentLabel** returns the current label, if any, being displayed by the unit based on it’s state.
-\\
-**xtOnLabel** and **xtOffLabel** can be set via this property to display something other than ON/OFF or the numerical value. For instance HVAC mode unit may be more useful to display “idle”, “heat”, “cool”, “EM Heat” rather than 0, 1, 2, 3
-These labels support [[xtension_manual:advancedlabel|Advanced Label Syntax]]
+----
+**xtBatteryLevel:** (read/write integer) gets or sets the battery level percent for a unit. Valid values are from 0 to 100. For a unit that does not support a battery level it will always return 0. For a unit that does support a battery level it will return whatever percent the device is sending to the controller. Set the value to -1 to clear a low battery warning. Setting a value to the property for a unit or a pseudo that would normally not support a battery level display will cause the battery display to enable for this unit in all displays and lists.
+----
+**xtBlocked:** (read/write boolean) returns true if the unit is blocked. Set to true or false to block or unblock a unit.
 <code>
-set xtOnLabel of xUnit “HVAC Mode” to “cool”
+if (xtBlocked of xUnit “unit name”) then
-write log “current state of the HVAC is “ & xtCurrentLabel of xUnit “HVAC Mode"
+  write log “the unit is blocked, cannot change its value!”
+else
+  write log “it is safe to continue to update the value”
+end if
 </code>
-===Last Group Member Timestamp===
+see also: [[dictionary:unitcontrol:block|block]], [[dictionary:unitcontrol:unblock|unblock]], [[dictionary:unitcontrol:removeallblocks|remove all blocks]]
-**xtLastMemberTimestamp** if the unit is a group this property will return the most recent timestamp of all the units contained in the group.
-===Unique ID===
-**xtID** returns a numerical unique ID for a specific unit. You can use this in place of the unit name in any script or verb that requires a unit name if you wish.
-===Unit Of Measure or Value Suffix===
+----
-**xtUnitOfMeasure** returns or sets the suffix that is always appended to the unit value in any display.
+**xtDescription:** (read/write string) get or set the description of a unit. Changing this value will trigger the “on descriptionChanged( newValue)” event in the unit’s On Script if it is there.
-===Formatted Value===
+see also: [[dictionary:unitinformation:setdescription|set description]], [[dictionary:unitinformation:descriptionof|description of]]
-**xtFormattedValue** returns the actual display string for the value including any labels, numerical formatting or unit of measure suffix.
-===Numerical Format String===
-**xtFormatString** gets or sets the numerical formatting string used to format the numerical value. For example setting the number of decimal places of the display. The format for this value can be found [[dictionary:more:formatnumber|here]].
-===Display Colors===
+----
-**xtOnColor** and **xtOffColor** get and set the HTML style color value displayed in the interfaces when the unit is on or off. The default colors are red for on and green for off but you can reverse these or display any other color that is meaningful for the unit. The format of the string is “RRGGBB”
+**xtDevice:** (DEPRECATED) used before the plugin API to set the device type of a unit. This is not functional at the moment and must be updated in order to properly set the unit type of a plugin unit. Let me know if you need this sooner and I will move it up the list.
+----
+**xtDimmable:** (read/write boolean) returns or sets the value of the “dimmable” checkbox in the Edit Unit dialog. This can only be set for units, not for groups. To set a groups dimmable and other settings use the xtShowDimmableControls parameter below.
+----
+**xtFlags:** (DEPRECATED, read only, string) a legacy parameter containing some of the unit flags in a sting of numbers, The first 3 characters are the battery level or just “000” if no battery level is supported for that unit. For example if a unit has a battery level of 56% the first three characters of this string will be “056”. The 4th character will be a “1” if the unit is blocked and a “0” if the unit is not blocked. The 5th character will be a “1” if the unit has an On Script. The 6th character will be a “1” if the unit has an Off Script. The 7th character will be a “1” if the unit has an error.
+The xtFlags parameter is deprecated and included only for legacy compatibility with older scripts. It should not be used for new script development,
+----
+**xtFormatString:** (read/write, string) gets or sets the value of the “Format” text field of the Edit Unit dialog. This is standard syntax used for the underlying Format() command. The specifics of the syntax is the same as for the [[dictionary:xtension:formatnumber|Format Number]] verb.
+----
+**xtFormattedValue:** (read only, string) instead of the numerical value of the unit this returns the formatted value as it would be displayed in any value display in XTension. Taking into account the format string, the suffix/unit of measure and any on/off labels that may have been set for the unit.
+----
+**xtGroup:** (read only, boolean) returns true if the unit is a group.
+----
+**xtGroupBehavior:** (read/write, enumerated) Only valid for a Group. Will return an error if used on a Unit that is not a group. gets or sets the group behavior. This is the same as the similarly named popup in the Edit Group dialog. Valid values are “manual”, “on when all units are on”, and “on when any units are on”
+see also the xtScriptsRunWhenAutochanged property
+----
+**xtHardOff:** (read/write, boolean) This remains for support of X10 devices. If an X10 device had received an actual OFF command then it is hard off and cannot be brightened to a new value without jumping to 100% first. The so called “nova” effect. If the last command to the unit was an OFF then this will be true. If the last command to the unit was a dim to 0, any other dim command or an on command then this will return false.
+----
+**xtHasAddress:** (DEPRECATED, read only, boolean) returns true if the unit has an address and false if the unit has no address and is therefore a psudo. This parameter is deprecated because of changes to the database that have allowed pseudos to have an address so this is no longer a reliable way to tell them apart.
+----
+**xtID:** (read/write string) returns or sets the uniqueID of the unit. This is used extensively internally for all object access. In any script you can substitute this for the unit name and all the verbs will function normally. If you do so then simply changing the name will not cause any scripts that access that unit to break. However if you delete that unit and create a new one giving it the same name THEN the scripts will fail as the unique ID will be different. You can also change the unique ID via this property but this will have many implications such as breaking any other references to the unit that are not in a script, for example any scheduled events that reference this unit will then break as they store the unique id of the unit and not the unit name.
+----
+**xtIgnoreClicks:** (read/write, boolean) gets or sets the value of the “Ignore Clicks” checkbox in the Edit Unit dialog. If this is set to true then a single click or double click in a unit list or view will never cause the unit to toggle. It will also make the Unit Toggle control in views or in the Controls column of a List to display the value, state or current label centered in the display and no paddle for clicking. This is to protect important units from inadvertent clicks, or to give you better choices than just on/off for dimmable units. If this is set you can still control the unit through the Detailed Unit Controls, the control panel or any verb. Click the jewel or set the double click parameters of a list to bring up the detailed controls and control the unit from there.
+----
+**xtInterface:** (read/write string) gets or sets the name of the Interface/plugin instance that the unit is assigned to. If setting this will cause a re-index of the unit on the new interface and an error will be returned if the unit cannot be assigned to the new interface due to an address space collision. Additionally if the unit does not have a valid unit type selected then the unit will not be accessible by the new interface until you also set that to a valid value.
+----
+**xtLastError:** (read/write, integer) If the unit is in an error state, with the error icon displaying in the Flags column of the List window and elsewhere then this will be a non-zero number. You can force a unit or a pseudo to show or clear an error by setting this value to 1 or 0.
+----
+**xtLastErrorDate:** (read/write, date) The date when the xtLastError property was last set to a non-zero value.
+----
+**xtLastErrorMessage:** (read/write, string) the error message, if any, that was included with the last error being set for the unit.
+----
+**xtLastMemberTimestamp:** (read only, date) This value is only valid for a Group. It will return the timestamp from the group member whos timestamp is most recent.
 <code>
-set xtOnColor of xUnit “my temp sensor” to “2222FF”
+set lastMotion to xtLastMemberTimestamp of xUnit “all motion sensors group”
+write log “the most recent motion in the house was: “ & (lastMotion as text)
 </code>
-would set the on color of the unit to a nice blue perhaps showing that it’s cold outside.
-===Battery Level===
-**xtBatteryLevel** get and set the battery level. If the unit reports a battery level then it will be available here. If you wish to control the battery display through scripting you can set this value to any number between 0 and 100. A unit with no value will not display a battery level as they are not applicable to all device types. Once you set a battery level in a script the battery icon will continue to display until you clear it by setting the level to -1.
-===Previous Values===
-By default the last 5 values changes of each unit are available through the **xtPreviousValues** property. It will return a list of numerical values. The number of items in the list is controlled from the Advanced tab of the edit unit dialog and is the same as the average value count setting. Even if averaging is not turned on for the unit the values will still be saved and be available to you here.
-For large reports or historical values beyond the last few updates please use the query verbs available in [[:xtdb|XTdb]]
+----
+**xtLastMessageDate:** (read only, date) The date when the last message of any kind was received for this unit. The Last Timestamp will only update if the newly received value is different than the current value. This value will update with every reception. So even if a temperature sensor is sending the exact same temperature with each reading and therefore not updating the Last Timestamp, each reception will update this value. This is the same value that is used for the “alert on inactivity” settings in the Advanced Tab of the Edit Unit Dialog. It can let you know if you stop receiving new values for a battery operated unit or a similar situation.
-===Error Handling===
-**xtLastError** gets or sets the last error number. As of v9.1 only 0 for no error or 1 for error is supported. This value will be set automatically if a no activity timeout has been reached or if a [[supported_hardware:vera|Vera]] interface is reporting a problem communicating with a unit. You can also set and clear this value from any script and it will control the showing of the alert icon in unit lists, views and the web interface.
-\\
-**xtLastErrorDate** gets or sets the date that the last error was turned on. If you’re setting the xtLastError property in a script it will not automatically update the last Error Date so you should also change this value to the current date or whatever date makes sense for the error.
-\\
-**xtLastErrorMessage** gets or sets the message associated with the last error.
-===Last Message Received Date===
-**xtLastMessageDate** will return the date/time that the unit last received any message at all. In the case of units like temperature sensors and security devices they may send an update with the same value that the device previously had registered. In those cases the Last Activity date will not update unless there is a new value, but the **xtLastMessageDate** value will update. (this xUnit property was added in XTension version 9.3.4)
+----
+**name or xtName:** (read/write string) get or set the name of the unit. When setting if the name is already in use an error will be returned.
+<code>
+  write log “name of the unit is: “ & (xtName of xUnit “name of the unit”)
+  try
+    set xtName of xUnit “current name” to “new name"
+  on error
+    write log “the name changed failed as it is already in use"
+  end try
+</code>
+see also: [[dictionary:unitinformation:setname|set unit name]]
+----
+**xtOffColor:** (read/write string) gets or sets the color used by the unit to display it’s list jewels and other status elements when the unit is off. This is an HTML formatted string the same as if setting a color in any HTML or CSS element but without the “#” at the beginning. The format is 6 hex characters like “RRGGBB” where each group of 2 represents Red, Green and Blue. So for an all red you would set it to “FF0000” or an all blue would be “0000FF”
+see also the xtOnColor property.
+----
+**xtOffLabel:** (read/write string) gets or sets the Off Label of the Unit. This is the optional string that is displayed in any unit value display. For example you may wish for the unit to display “open” or “closed” rather than “on” and “off” if so you can set them here. This field also supports [[xtension_manual:advancedlabel|Advanced Unit Label Syntax]].
+see also the xtOnLabel and xtCurrentLabel properties.
+----
+**xtOffScriptText:** (read/write string) gets or sets the text of the Units OFF script. When setting the Off script an error will be returned if the script does not compiler. Note that you may have to escape any quotes in order to include them in the string being sent.
+<code>
+set xtOffScriptText of xUnit “unit name” to “say \”this unit is turning off!\””
+</code>
+see also the xtOnScriptText property.
+----
+**xtOnColor:** (read/write string) gets or sets the color used by the unit to display it’s list jewels and other status elements when the unit is on. This is an HTML formatted string the same as if setting a color in any HTML or CSS element but without the “#” at the beginning. The format is 6 hex characters like “RRGGBB” where each group of 2 represents Red, Green and Blue. So for an all red you would set it to “FF0000” or an all blue would be “0000FF”
+see also the xtOffColor property.
+----
+**xtOnLabel:** (read/write string) gets or sets the On Label of the Unit. This is the optional string that is displayed in any unit value display. For example you may wish for the unit to display “open” or “closed” rather than “on” and “off” if so you can set them here. This field also supports [[xtension_manual:advancedlabel|Advanced Unit Label Syntax]].
+see also the xtOffLabel and xtCurrentLabel properties.
+----
+**xtOnScriptText:** (read/write string) gets or sets the text of the Units ON script. When setting the On script an error will be returned if the script does not compile.
+<code>
+set xtOnScripText of xUnit “unit name” to “say \”this unit is being turned on!\””
+</code>
+see also the xtOffscriptText property
+----
+**xtPreviousValues:** (read only, list of floats) By default the last 5 values of the unit are saved and available here. This is the same as the value list used for the “average the last...” setting in the Advanced Tab of the edit unit. These values are available here even if you do not have the averaging turned on. To store more values here increase the number of values to average in the Edit Unit Dialog. For very long term storage of values please use XTdb and do a standard query against it’s database.
+----
+**xtReceiveOnly:** (read/write boolean) sets or returns the value of the “receive only” checkbox from the Edit Unit Dialog. If this is turned on the unit will behave and display normally in XTension but will not actually transmit any data. See also the xtIgnoreClicks parameter above.
+----
+**xtReversed:** (read/write, boolean) sets or returns the state of the “reverse logic” checkbox in the edit unit dialog.
+----
+**xtScriptsRunWhenAutochanged:** (read/write, boolean) Only valid for Groups. Will return an error if used on a Unit that is not a Group. Gets or sets the value of the “Scripts Run When Autochanged” checkbox from the edit group dialog. If true then when a group changes it’s state due to the “On when any member is on” or “on when all members are on” properties of the group then the On script and Off script will also run. If this is off then the scripts will not run when the group changes it’s state due to those properties but only when you control the group specifically either through the interface or via a script.
+----
+**xtShowColorControls:** (read/write, boolean) Only valid for Groups. Gets or sets the value of the Checkbox with the same name in the Edit Group dialog. Setting this to true requires that the Group also have the “xtShowDimmableControls” turned on. With this on when controlling the group you’ll be presented with all the standard color selection controls that would be displayed for any color capable unit and any color data you specify that way or through any of the verbs will be forwarded on to all the units in the group. Useful for creating groups of lights that might be in the same room or in the same fixture that you wish to be controlled together.
+----
+**xtShowColorTempControls:** (read/write, boolean) Only valid for Groups. Gets or sets the value of the Checkbox with the same name in the Edit Group dialog. Setting this to true requires that the Group also have the “xtShowDimmableControls” property turned on. Setting this to true will show the standard color temperature selection controls in all control dialogs for the unit and will also forward on any color temperature data sent in any scripts on to all the units in the group. Useful for creating groups of lights that might be in the same room or in the same fixture that you wish to be controlled together.
+----
+**xtShowDimmableControls:** (read/write, boolean) Only valid for Groups. Gets or sets the value of the Checkbox with the same name in the Edit Group dialog. If true then the group is treated as dimmable. When being controlled from any interface it will show the dimmable unit controls and will also allow using the dim and brighten commands via any script. When this is turned off the Group is treated as “discrete” and will ignore dim commands and respond only to on/off commands.
+----
+**xtSimPreset:** (read/write boolean) gets or sets the dimmable type of the unit to “simulated.” Note that this does not return the current sim preset value, but rather the state of the dimmable behavior type for the unit.
+----
+**xtSmart:** (read/write boolean) gets or sets the dimmable type of the unit to “smart.”
+----
+**xtTimestamp:** (read/write date) get or set the last timestamp of the unit. Setting the timestamp does update any displays of the date but does not change the value of the last update stored in XTdb or the previous values in the unit.
+<code>
+write log “the unit was last updated at” & (xtTimestamp of xUnit “name”) as text
+set xtTimestamp of xUnit “name” to ((current date) - 5 * hours)
+</code>
+see also: [[dictionary:unitinformation:lasttimestamp|last timestamp]], [[dictionary:unitinformation:timedelta|time delta]]
+----
+**xtTreatAsRadioButons:** (read/write boolean) Valid only for Groups. If on then the Group will only allow one group member to be On at a time. If another group member turns on the Group will turn off any other members that are currently On.
+----
+**xtUnitOfMeasure:** (read/write string) gets or sets the “unit of measure” or the suffix that is appended to the end of any value displays. This is the value from the “Suffix” field of the Edit Unit dialog. For example you may wish to display “mph” after a wind speed, or “°F” after a temperature reading.
+----
+**value or xtValue:** (read/write float) get or set the current value of the unit. For non dimmable units a value returned of 0 is off and any non-zero return is on.
+<code>
+set xtValue of xUnit “my counter” to (xtValue of xUnit “my counter”) + 1
+write log (xtValue of xUnit “my counter”)
+</code>
+see also: [[dictionary:unitinformation:setvalueof|set Value]], [[dictionary:unitinformation:valueof|value of]], [[dictionary:unitinformation:statusof|status of]]
+----
 ====Unit Information Verbs====
 Commands to get and set other information about a Unit or Group. All control of unit values and state are done through these verbs and not through the xUnit Class above. Most information about the units are available via these verbs as well as the xUnit class, but not all. More recently added unit information is made accessible through the xUnit class where that makes sense or via verbs where that makes more sense.
+{{indexmenu>:dictionary/unitinformation#2|js#doku}}
-{{indexmenu>dictionary/unitinformation#2|js#IndexMenu+ajax}}

Mac Home Automation

User Tools

Site Tools

Differences

Page Tools