Mac Home Automation

The xUnit Class

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:

write log (xtShowDimmableControls of xUnit “my group”) as text

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.

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

see also: set address

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.

if (xtBlocked of xUnit “unit name”) then
  write log “the unit is blocked, cannot change its value!”
else
  write log “it is safe to continue to update the value”
end if

see also: block, unblock, remove all blocks

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.

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

set lastMotion to xtLastMemberTimestamp of xUnit “all motion sensors group”
write log “the most recent motion in the house was: “ & (lastMotion as text)

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.

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.

  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

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.

write log “the unit was last updated at” & (xtTimestamp of xUnit “name”) as text

set xtTimestamp of xUnit “name” to ((current date) - 5 * hours)

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.

Mac Home Automation

User Tools

Site Tools

Sidebar

The xUnit Class

Unit Information Verbs

Page Tools