RegisterStatusChangeCB

Purpose

HomeSeer has the ability to trigger events based on a device changing.  It may be useful to run a script when a device changes.  The RegisterStatusChangeCB function can be used to register your script with HomeSeer.  When a device changes, your script will be called.  The script is passed the code of the device that changed, the address of the device that changed, as well as the value the device changed to and the reference ID of the device.

To remove the callback script, call hs.UnRegisterStatusChangeCB.  There are no parameters with this call.

Remarks

When a device changes status, the given script is called as follows:

script_name( parm )

The parms parameter is an array of parameters.  The following parameters are available:

parm(0)  =  Code part of the Address of the device that changed status
parm(1)  =  Full Address of the device that changed status (including Code if present)
parm(2)  =  The New value of the device that changed status.
parm(3)  =  The Old value of the device that changed status.
parm(4)  =  The device reference ID number.  Can be used with GetDeviceByRef to find the DeviceClass of the specific device.

Note that since a function can be called in the callback script, the registration and actual callback can all reside in the same script file.

Parameters

Parameter: Script
Type: String
Description: This is the file name of the script to run.  Do not include the path in the script name; the script is assumed to be in the scripts directory (C:\Program Files\HomeSeer HS3\Scripts by default).

Parameter: Function
Type: String
Description: This is the function in the script to run, such as Main.

Returns

Return: Result
Type: Boolean
Description: If True, the registration of the script succeeded. 

Example

' register a callback script 

    Sub Main(ByVal Parms As Object)       

        hs.RegisterStatusChangeCB("Stat_Change.vb", "StatusChangeCB") 

    End Sub



' the actual status change script that is called when a device changes status given the above register call


    Sub StatusChangeCB(ByVal Parm As Object()) 

        If Parm Is Nothing Then Exit Sub
        If Parm.Length < 5 Then Exit Sub
 
        Dim Code As String = ""
        Dim Address As String = ""
        Dim OldVal As Double
        Dim NewVal As Double
        Dim Ref As Integer
 
        Try
            Code = Parm(0).ToString
            Address = Parm(1).ToString
            NewVal = Parm(2)
            OldVal = Parm(3)
            Ref = Parm(4)
        Catch ex As Exception
            hs.WriteLog("Stat_Change.VB", "Error, Exception parsing Parm: " & ex.Message)
            Exit Sub
        End Try
 
        hs.WriteLog("Change", hs.DeviceName(Ref) & " changed from " & OldVal.ToString & " to " & _
                                       NewVal.ToString & " (" & Address & ")")

     End Sub