User Tools

Site Tools



Getting Unit Information

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

xtTimeStamp returns the same value as the 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:

 set xtTimeStamp of xUnit “my sensor of something” to (current date) - 4 * days

This has implications for saving this in 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.

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 Advanced Label Syntax

set xtOnLabel of xUnit “HVAC Mode” to “cool”
write log “current state of the HVAC is “ & xtCurrentLabel of xUnit “HVAC Mode"

Last Group Member Timestamp

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.

Formatted Value

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 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”

set xtOnColor of xUnit “my temp sensor” to “2222FF” 

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

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 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)

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.

dictionary/unitinformation/index.txt · Last modified: 2017/10/15 16:04 by James Sentman