Scripting Extensions Reference

Following is a list of all of the extension methods included in this product distribution.  Most of these methods access HS functions, and as a result, you must pass the hs4 object, or in some cases the hs object to the method.  In the following reference, some methods will show an hs4 parameter, and some will show an hs parameter. 

Index to Extension Methods Reference

DeviceOn

DeviceOff

DeviceDim

ToggleDeviceOnOff

ToggleDevice

IsOff, AreAllOff

GetCategoriesByRef

GetRefsByCategoryName

GetRefsInBothLists

GetRefsInEitherList

GetFeatureRefByFullname

GetFullnameByRef

SaveDeviceStates, RestoreDeviceStates, RemoveDeviceStates

 

DeviceOn(hs4, FeatureRef as Integer, Optional CheckFirst as Boolean = False) as String
DeviceOn(hs4, FeatureRefs as List(Of Integer), Optional CheckFirst as Boolean = False) as String
DeviceOn(hs4, Category as String, Optional CheckFirst as Boolean = False) as String
DeviceOn(hs4, Categories() as String, Optional CheckFirst as Boolean = False) as String

Issues HS commands to turn ON an individual device (FeatureRef), all devices in a list of devices (FeatureRefs), all devices that belong to single category (Category), or all devices that belong to any of the specified categories (Categories()).  If the optional CheckFirst parameter is set to True then a command to turn any device ON will not be issued if it is already ON. Returns "" if OK, or Error Message if something failed.

Examples

Dim s1 As String = DeviceOn(h4, 174)   'turn ON device with ref 174

Dim s2 As String = DeviceOn(hs4, GetRefsByCategoryName(hs4, "Kitchen"))     'Turn ON all devices in category Kitchen

Dim s3 as String = DeviceOn(hs4, "Kitchen")   'turn ON all devices in category Kitchen

Dim s4 as String = DeviceOn(hs4,{"Kitchen","Office"},True)   'turn ON all devices in either the Kitchen or Office categories

 

DeviceOff(hs4, FeatureRef as Integer, Optional CheckFirst as Boolean = False) as String
DeviceOff(hs4, FeatureRefs as List(Of Integer), Optional CheckFirst as Boolean = False) as String
DeviceOff(hs4, Category as String, Optional CheckFirst as Boolean = False) as String
DeviceOff(hs4, Categories() as String, Optional CheckFirst as Boolean = False) as String

DeviceOff  has the same calling sequences and functions the same as DeviceOn - with the exception that the devices are turned OFF instead of ON.

 

DeviceDim(hs4, FeatureRef As Integer, Percent As Double) as String
DeviceDim(hs4, FeatureRefs As List(Of Integer), Percent As Double) as String
DeviceDim(hs4, Category As String, Percent As Double) as String
DeviceDim(hs4, Categories() As String, Percent As Double) as String

DeviceDim will DIM one or more Devices to the level specified as Percent.  Percent must be a value from 0.0 to 100.0. The actual DIM level applied will be calculated based upon the range of values defined for the Device's DIM control.  Returns a String of "" if no errors are encountered, or an error message if an error occurs.

ToggleDeviceOnOff(hs4, FeatureRef as Integer) as String

If this device/feature is OFF, it will turn it ON; otherwise, it will turn it OFF (i.e. if it is DIM, it will turn it OFF).  The device must have the ControlUse_Off  and ControlUse_ON properties defined.  Returns "" if OK, or Error Message if something failed.

Examples

Dim s1 As String = ToggleDeviceOnOff(hs4, 174)  'toggle device with ref 174

 

 

 

ToggleDevice(hs4, FeatureRef as Integer, Value1 as Double, Value2 as Double) as String

If this device has a value of Value1, it will set its value to Value2; otherwise, it will set its value to Value1.  Both Value1 and Value2 must be valid as defined for the device's Status/Graphics pairs.  This method does not just change the device's value, but issues HS commands to execute the associated function for that value.  Returns "" if OK, or Error Message if something failed.  For many devices ToggleDeviceOnOff(hs, 174) would do the same as ToggleDevice(hs, 174, 0, 100).

Examples

Dim s1 As String = ToggleDevice(hs4, 174, 0, 100)  'toggle device with ref 174

 

 

GetCategoriesByRef(hs4, DevRef as Integer) as List(Of String)

Returns a List of strings that contains the names of all of the Categories in which  the specified device is included.  Returns Nothing if hs4 is invalid, returns an empty list if either the device is not included in any Category or if there is an error.  If there is an error, a message is written to the HS4 log.

Examples

Dim Cats As System.Collections.Generic.List(Of String)
Cats = GetCategoriesByRef(hs4, 174)    'a list of all Categories for device 174

Dim s1 as string = DeviceOff(hs4,Cats)   'turn OFF all lights in these categories

 

 

GetRefsByCategoryName(hs4, CatName as String) as List(Of Integer)

Returns a List of device refs that are in the Category with a name of CatName.  Returns Nothing if hs4 is invalid, returns an empty list if either the Category contains no devices, or if there is an error.  If there is an error, a message is written to the HS4 log.

Examples

Dim Refs As System.Collections.Generic.List(Of Integer)
Refs = GetRefsByCategoryName(hs4, "Kitchen")  'get refs of all devices in Category Kitchen

Dim s2 As String = DeviceOff(hs4, Refs)   'Turn OFF all devices in Category Kitchen

 

 

GetRefsInBothLists(List1 As List(Of Integer), List2 As List(Of Integer)) As List(Of Integer)

Returns a List of device refs that are in BOTH List1 and List2. 

Examples

Dim List1 As List(Of Integer) = GetRefsByCategoryName(hs4, "Office")   'devices in category Office
Dim List2 As List(Of Integer) = GetRefsByCategoryName(hs4, "Lights")   'devices in category Lights
Dim List3 As List(Of Integer) = GetRefsInBothLists(List1, List2)   'devices in both categories
Dim Result As String = DeviceOn(hs4, List3)   'turn ON devices that are in both Office and Lights categories

         OR 

Dim Result as String = DeviceOn(hs4, GetRefsInBothLists(GetRefsByCategoryName(hs4, "Office"), GetRefsByCategoryName(hs4, "Lights")))

 

 

GetRefsInEitherList(List1 As List(Of Integer), List2 As List(Of Integer)) As List(Of Integer)

Returns a List of device refs that are in EITHER List1 or List2. 

Examples

Dim List1 As List(Of Integer) = GetRefsByCategoryName(hs4, "Office")   'devices in category Office
Dim List2 As List(Of Integer) = GetRefsByCategoryName(hs4, "Lights")   'devices in category Lights
Dim List3 As List(Of Integer) = GetRefsInEitherList(List1, List2)   'devices in either category
Dim Result As String = DeviceOn(hs4, List3)   'turn ON all devices that are in the  Office or Lights categories

         OR 

Dim Result as String = DeviceOn(hs4, GetRefsInEitherList(GetRefsByCategoryName(hs4, "Office"), GetRefsByCategoryName(hs4, "Lights")))

 

 

 

GetFeatureRefByFullname(hs, DeviceName As String, FeatureName As String, Optional FeatureNameOnly as Boolean=False) As Integer

In HS4, with the introduction of the Device/Feature approach, there are many features that are defined with a duplicate name to features from other devices.  In HS3, the method hs.GetDeviceRefbyName was fairly reliable, but not in HS4.  However, the combination of root device name and the feature name is pretty unique.  GetFeatureRefByFullname will look for the DeviceName (root) and its features for a matching FeatureName, and return the device reference for that Feature.  If you are looking for a device that is Root Only (HS3 legacy), specify "" for FeatureName.  Returns 0 if a matching feature is not found.

By default, both the DeviceName and FeatureName must be fully-qualified, requiring the inclusion of Location, Location2, and Name.  If the optional parameter FeatureNameOnly is set to True, the the FeatureName should be set to only the Name, no Location or Location2.

Example

Dim DevRef As Integer
DevRef = GetFeatureRefByFullname(hs, "JowiHue JowiHue Outlet Repeater 1", "JowiHue JowiHue Outlet Repeater 1 (On/Off/Dim)")
ToggleDeviceOnOff(hs, DevRef)

 

 

 

GetFullnameByRef(hs4, DevRef as Integer) as String()

Returns a String array containing the full Devicename and the full Featurename

Example

Dim s1 As String(), i1 as Integer
s1 = GetFullnameByRef(hs4, 174)  'Get Devicename and Featurename
i1 = GetFeatureRefByFullname(hs, s1(0), s1(1))  'Now, get DevRef (174) from Devicename/Featurename

 

 

 

IsOff(hs4, FeatureRef as Integer) as Boolean
AreAllOff(hs4, FeatureRefs as List(Of Integer)) as Boolean
AreAllOff(hs4, Category as String) as Boolean
AreAllOff(hs4, Categories() as String) as Boolean

IsOff returns True if FeatureRef is OFF.  AreAllOff returns False if any of the devices included in FeatureRefs, Category, or Categories are ON (including DIM).

Example

If IsOff(hs4, 170) Then DeviceOn(hs4, 170)   'Turn device ON if it is OFF

DeviceOn(hs4,170, True)   'This is equivalent

 

 

SaveDeviceStates(hs4, SaveName as String, DevRefs as List(Of Integer)) as String
SaveDeviceStates(hs4, SaveName as String, Category as String) as String
SaveDeviceStates(hs4, SaveName as String, Categories() as String) as String
RestoreDeviceStates(hs4, SaveName as String, Optional Clear as Boolean = False) as String
RemoveDeviceStates(hs4, SaveName as String) as String

SaveDeviceStates saves the current state of all of the devices specified by DevRefs, Category, or Categories.  The device states are saved in non-volatile storage (INI file) using the unique SaveName provided. The saved devices can later be returned to their saved states using RestoreDeviceStates. If Clear is True for RestoreDeviceStates, then the saved Device states will be removed after the Devices are restored to their saved state.  RemoveDeviceStates will remove the specified saved states.

Example

Dim s as String = SaveDeviceStates(hs4,"BeforeRoomba", "Kitchen")   'save states of all of the lights in the Kitchen category

((Run Roomba to clean the Kitchen floor))

Dim s2 as String = RestoreDeviceStates(hs4, "BeforeRoomba")   'put Kitchen lights back to their prior state