tenWare Software


   Scripting Extensions


Overview

Extension Reference

Installation







 tenWare Support




 Cystic Fibrosis Foundation

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 hs object to the method.  In the following reference, some methods will show an hs parameter, and some will show an hs4 parameter.  If your script is running within HS4 (called by an Event), then you should enter hs for both the hs and hs4 parameters.  If you are testing under tenScripting4, then hs must be hs and hs4 must be hs4.  When you Export your script from tenScripting4 to the HS4 script folder, the reference to hs4 will be replaced with hs.

Index to Extension Methods Reference

DeviceOn

DeviceOff

ToggleDeviceOnOff

ToggleDevice

GetCategoriesByRef

GetRefsByCategoryName

GetRefsInBothLists

GetFeatureRefByFullname

 

DeviceOn(hs, DevRef as Integer) as String
DeviceOn(hs, DevRefs as List(Of Integer) as String

Issues CAPI commands to turn on an individual device (DevRef), or all devices in a list of devices (DevRefs).  All of the devices must have the ControlUse_On property defined.  Returns "" if OK, or Error Message if something failed.

Examples

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

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

 

 

DeviceOff(hs, DevRef as Integer) as String
DeviceOff(hs, DevRefs as List(Of Integer) as String

Issues CAPI commands to turn off an individual device (DevRef), or all devices in a list of devices (DevRefs).  All of the devices must have the ControlUse_Off property defined.  Returns "" if OK, or Error Message if something failed.

Examples

Dim s1 As String = DeviceOff(hs, 174) 'turn OFF device with ref 174

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

 

 

ToggleDeviceOnOff(hs, DevRef as Integer) as String

Using CAPI, if this device 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(hs, 174)  'toggle device with ref 174

 

 

 

ToggleDevice(hs, DevRef as Integer, Value1 as Double, Value2 as Double) as String

Using CAPI, 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 devices' Status/Graphics pairs.  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(hs, 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

 

 

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(hs, 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(hs, List3) 'turn ON devices that in both Office and Lights categories

         OR 

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

 

 

 

GetFeatureRefByFullname(hs, DeviceName As String, FeatureName As String) 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.

Examples

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