As promised, here are some simple scripting examples of how to manage devices with CAPI.
First a disclaimer. I am no expert on any of this, I've just spent some time poking around and trying out some of the new HS3 scripting functions. HS3 is still a work in progress, and there is some discussion between plug-in developers and HST on developing some standards, and possibly additional scripting functions to make this all easier to work with.
CAPI is an interface for controlling devices. As far as I can tell, it is not intended to be an interface for determining device status (although that is what some of the examples below do).
So be warned that you need to do some homework, and nothing is guaranteed.
Any device in HS3 can have any number of CAPIControl objects associated with it. The full definition of the CAPIControl object can be found in the HS3 scripting documentation (but that does not tell the whole story). Basically it is an array of objects, with labels, such as "On" or "Off" and associated device values. The value of those labels, and associated values, are defined by the plug-in or script that creates the devices.
Here are some basic examples:
For a Z-Wave device, there are at least two objects. A label of "On", value 255 and label of "Off", value 0. For dimmable devices, there are entries from "Dim 1%" to "Dim 99%", but only every other value, so Dim 1%, 3%, 5%, 7%, 9%... 99%, with associated values of 1, 3, 5, 7, 9 through 99.
So you can't directly dim to 50%, it will not do anything, as that is not defined.
X-10 devices are similar, but "On" is 101 and "Off" is -1.
For a device added from the Device Manager, "On" is 100 and "Off" is 0.
Note that setting a device to the CAPIControl object value does not do anything. For the owning plug-in to actually turn a device on, off, or set some other status, the hs.CAPIControlHandler function call must be used.
But that does not mean that you can't define your own devices that only hold "status" based on their on/off/dim values.
This script will write some information about a device, including any CAPI objects to the log. To get a better feel for the CAPI objects, I'd suggest running this on various devices in your own system. It is set up to take a string device ref so that it can be easily run from an event.
Here are the IsOn and IsOff replacements. This assumes that the device has an "On" or "Off" object defined (the check is not case sensitive). For ByName variations, use hs.GetDeviceRefByName. For example: IsOnCAPI(hs.GetDeviceRefByName("Room1 Device1")). Also note that a device is not "On" if it is dimmed. It might make more sense to use Not IsOffCAPI rather than IsOnCAPI, if the device is dimmable.
Here is a more generic IsCAPI function that requires the full text of the CAPI label. IsCAPI(devref, "On") or IsCAPI(devref, "Dim 13%") for example.
This is the function that most closely replaces ExecX10 and requires the full text of the CAPI label. Samples: CallCAPI(devref, "On"), CallCAPI(devref, "dim 51%")
This function will try to approximate a dim level. So if CAPI only defines dim levels of 5%, 10%, etc. you can call this function with a value of 8 and it will find the closest dim level that is defined (it should choose 10). The third parameter limits the search to within +- of that value, a value of 0 will only work on an exact match. This has only been tested with Z-Wave and X-10 devices with the current plug-ins.
First a disclaimer. I am no expert on any of this, I've just spent some time poking around and trying out some of the new HS3 scripting functions. HS3 is still a work in progress, and there is some discussion between plug-in developers and HST on developing some standards, and possibly additional scripting functions to make this all easier to work with.
CAPI is an interface for controlling devices. As far as I can tell, it is not intended to be an interface for determining device status (although that is what some of the examples below do).
So be warned that you need to do some homework, and nothing is guaranteed.
Any device in HS3 can have any number of CAPIControl objects associated with it. The full definition of the CAPIControl object can be found in the HS3 scripting documentation (but that does not tell the whole story). Basically it is an array of objects, with labels, such as "On" or "Off" and associated device values. The value of those labels, and associated values, are defined by the plug-in or script that creates the devices.
Here are some basic examples:
For a Z-Wave device, there are at least two objects. A label of "On", value 255 and label of "Off", value 0. For dimmable devices, there are entries from "Dim 1%" to "Dim 99%", but only every other value, so Dim 1%, 3%, 5%, 7%, 9%... 99%, with associated values of 1, 3, 5, 7, 9 through 99.
So you can't directly dim to 50%, it will not do anything, as that is not defined.
X-10 devices are similar, but "On" is 101 and "Off" is -1.
For a device added from the Device Manager, "On" is 100 and "Off" is 0.
Note that setting a device to the CAPIControl object value does not do anything. For the owning plug-in to actually turn a device on, off, or set some other status, the hs.CAPIControlHandler function call must be used.
But that does not mean that you can't define your own devices that only hold "status" based on their on/off/dim values.
This script will write some information about a device, including any CAPI objects to the log. To get a better feel for the CAPI objects, I'd suggest running this on various devices in your own system. It is set up to take a string device ref so that it can be easily run from an event.
Code:
Imports HomeSeerAPI Sub Main(ByVal strDevRef As String) Dim objDev As Object Dim intDevRef as Integer Dim intCount As Integer intDevRef = CInt(strDevRef) objDev = hs.GetDevicebyRef(intDevRef) If objDev Is Nothing Then hs.WriteLog("DevInfo","Invalid device ref: " & strDevRef) Else hs.WriteLog("DevInfo", "Ref=" & strDevRef & "; Name=" & objDev.Name(hs) & "; Location=" & objDev.Location(hs) & "; Location2=" & objDev.Location2(hs) & "; Address=" & objDev.Address(hs)) intCount = 0 For Each objCAPIControl As CAPIControl In hs.CAPIGetControl(intDevRef) hs.WriteLog("DevInfo", ".CCIndex=" & CStr(objCAPIControl.CCIndex) & "; Label=" & objCAPIControl.Label) & "; ControlType=" & CStr(objCAPIControl.ControlType) & "; ControlValue=" & CStr(objCAPIControl.ControlValue) & "; ControlString=" & objCAPIControl.ControlString) intCount = intCount + 1 Next If intCount = 0 Then hs.WriteLog("DevInfo", "No CAPIControl objects defined for this device") End If End Sub
Code:
Function IsOnCAPI(ByVal intDevRef As Integer) As Boolean Dim intValue = hs.DeviceValueEx(intDevRef) IsOnCAPI = False For Each objCAPIControl As CAPIControl In hs.CAPIGetControl(intDevRef) If intValue = objCAPIControl.ControlValue Then If LCase(objCAPIControl.Label) = "on" Then IsOnCAPI = True End If Exit For End If Next End Function Function IsOffCAPI(ByVal intDevRef As Integer) As Boolean Dim intValue = hs.DeviceValueEx(intDevRef) IsOffCAPI = False For Each objCAPIControl As CAPIControl In hs.CAPIGetControl(intDevRef) If intValue = objCAPIControl.ControlValue Then If LCase(objCAPIControl.Label) = "off" Then IsOffCAPI = True End If Exit For End If Next End Function
Code:
Function IsCAPI(ByVal intDevRef As Integer, ByVal strDevCmd As String) As Boolean Dim intValue = hs.DeviceValueEx(intDevRef) IsCAPI = False For Each objCAPIControl As CAPIControl In hs.CAPIGetControl(intDevRef) If intValue = objCAPIControl.ControlValue Then If LCase(objCAPIControl.Label) = LCase(strDevCmd) Then IsCAPI = True End If Exit For End If Next End Function
Code:
Function CallCAPI(ByVal intDevRef As Integer, ByVal strDevCmd As String) As CAPIControlResponse CallCAPI = CAPIControlResponse.Indeterminate For Each objCAPIControl As CAPIControl In hs.CAPIGetControl(intDevRef) If LCase(objCAPIControl.Label) = LCase(strDevCmd) Then CallCAPI = hs.CAPIControlHandler(objCAPIControl) Exit For End If Next End Function
Code:
Function DimCAPI(ByVal intDevRef As Integer, ByVal intDimValue As Integer, ByVal intOffSetMax As Integer) As CAPIControlResponse Dim blnMatch As Boolean Dim intOffset As Integer Dim intStartPos As Integer Dim strDimVal As String Dim intDimVal As Integer DimCAPI = CAPIControlResponse.Indeterminate blnMatch = False intOffSet = 0 While True For Each objCAPIControl As CAPIControl In hs.CAPIGetControl(intDevRef) If Len(objCAPIControl.Label) > 5 Then If LCase(Left(objCAPIControl.Label, 4)) = "dim " Then intStartPos = InStr(4, objCAPIControl.Label, "%") If intStartPos > 5 Then strDimVal = Mid(objCAPIControl.Label, 5, intStartPos - 5) If IsNumeric(strDimVal) Then intDimVal = CInt(strDimVal) If ((intDimVal - intOffSet) = intDimValue) Or ((intDimVal + intOffSet) = intDimValue) Then DimCAPI = hs.CAPIControlHandler(objCAPIControl) blnMatch = True 'hs.WriteLog("DimCAPI", "Dim match found. Requested=" & CStr(intDimValue) & ". Matched=" & strDimVal) Exit For End If End If End If End If End If Next If blnMatch Then Exit While intOffSet = intOffSet + 1 If intOffSet > intOffSetMax Then Exit While End While End Function
Comment