tenWare Software
Skip Navigation LinkstenWare Home > HomeSeer Programs > HS4 Scripting Extensions


   Scripting Extensions


Overview

Extension Reference

Installation







 tenWare Support




 Cystic Fibrosis Foundation

HS4 Scripting Extensions

These Scripting Extensions add additional global methods that can be called from any HS4 script, providing easy to use extensions of the standard HS4 scripting environment. These new methods add the following capabilities:

 

Device Control

 Methods like DeviceOn, DeviceOff, DeviceDim, and ToggleDeviceOnOff are easier to use than making CAPI calls.  You can make a single method call to control a single Device, a list of Devices, or Devices that belong to one or more HS Categories.

 

HS4 Categories

HS4 introduced Categories that can be used to group Devices in multiple ways.  HS did not however provide an easy to use set of scripting methods to take advantage of the new Categories.  For instance, in order to obtain a list of all of the Devices belonging to a Category, you had to know the unique ID of the Category (not the Name associated with the Category).  The Scripting Extensions provide methods like GetFeatureRefsByCategoryName and GetCategoriesByRef.  In addition, you can provide one or more Categories to the DeviceOn and DeviceOff methods to operate on all of the Devices belonging to these Categories.

Device Lists

The GetRefsInBothLists and GetRefsInEitherList methods have been provided to merge and combine Lists of Device Refs to extend the flexibility of the Device control methods. For example, to turn OFF all lights that belong to both the Kitchen and the Lights Categories  (ie, all kitchen lights):

DeviceOff(hs4, GetRefsInBothLists(GetRefsByCategoryName(hs4, "Kitchen"), GetRefsByCategoryName(hs4, "Lights")))

 

Check Device State

Method IsOff returns True if the specified Device is OFF.

Method AreAllOff returns False if any of the specified Devices are NOT OFF (ON or DIM).  You can specify a list of Device Refs, or one or more Categories to check.

 

Device/Feature Fullnames

In HS3, most fully-qualified Device names (that is, Location2+Location+Name or "fqn") were unique and you could depend on GetDeviceRefByName. With the HS4 scheme of Device/Feature, many Features have duplicate fully-qualifed names. What is usually unique is the combination of Device (root) fqn and Feature (child) fqn.  The Scripting Extensions provide GetFullnameByRef which returns the fqn for the root and the fqn for the child for the specified Ref.  GetFeatureRefByFullname will return the Ref for the specified Fullname (that is, the fqn of the root and the fqn of the child).

 

Save/Restore Device States

Several methods are provided that will save the state (Value) of a list of Devices/Features and then later restore these devices to the saved states.  SaveDeviceStates will save to non-volatile storage (INI file) the current state of a list of Devices/Features.  You can provide a list of Refs, or one or more Categories of Refs.  Later, call RestoreDeviceStates to set the saved Refs to their saved states. An example scenario is turning ON multiple lights before you run Roomba.  After cleaning, you don't want to just turn these lights OFF, but set them back to where they were before running Roomba.  You would do something like:

  • SaveDeviceStates for all the lights in the room being cleaned and in rooms in the path to get to the room to be cleaned. 
  • Run roomba to clean a room.
  • When roomba is finished, RestoreDeviceStates.

In my house, I just say the following to any Echo speaker: "Alexa, clean the kitchen" to perform all of these actions.  Saving and restoring the Device states is essential.

 

See the Extension Reference for details.