Global Methods for HomeSeer Scripting

Overview

For any serious programming effort, there are usually many functions that are used repeatedly throughout a project.  Most programming environments provide an easy solution to create and implement programming functions that can be used by many other components.  A shortcoming of the HomeSeer scripting environment is that there is no easy way to develop and deploy scripting functions that can be used by other scripts to perform often-used logic.

One approach is to code, compile, build, and deploy shared functions within a Class Library and then add a reference to this library to HS4.  This all may be beyond the effort casual script writers are willing to undertake.

How tenScripting can help

A new facility has been added to tenScripting4 (Version 4.5 in 2021) to make this process much simpler.  If you are currently using tenScripting to write, debug, and deploy your HomeSeer scripts, then you should be very comfortable with doing the same for your reusable script functions.

An additional VS Project (tenGlobalMethods) has been added to the tenScripting4 solution that contains global methods (functions and subroutines.)  Several useful examples are provided with the installation, and you can easily add your own global methods to this project.  As with scripts, you can take full advantage of Visual Studio editing and debugging capabilities.  Any of your scripts coded within tenScripting4 can reference these global methods.  When you export your global methods to HS4, they are then available to any HS script. 

In order to make the shared functions available in HS4, you must copy the tenGlobalMethods.dll file created by tenScripting4 to the root HomeSeer HS4 folder, and add an entry to the ScriptingReferences key in settings.ini.  tenScripting provides an easy tool to make this change to settings.ini (tenScripting4 Tools menu).

 It is now fairly easy to develop and debug global methods using tenScripting4.

Creating your own Global Method

Let's create a simple Global Method that simply turns ON the office light. 

Open tenScripting4 in Visual Studio and then find the tenGlobalMethods project and open the tenMethods.vb file.  What you see are multple methods that make up the HS Scripting Extensions that are available from tenWare. Note how these methods are defined:   Project=tenGlobalMethods, File=tenMethods.vb,   Module=ten, Methods=ToggleDevice, ToggleDeviceOnOff,  etc.  DO NOT CHANGE ANYTHING IN FILE tenMethods.vb.

You do not want to add your global methods to the tenMethods.vb file because they will be overwritten when you install an upgrade to tenScripting4. We are going to add a new file MyMethods.vb to the tenGlobalMethods project, add module mine to MyMethods.vb, and then add the new method OfficeOn to the module.

It should look something like this: 

We have now defined:   Project=tenGlobalMethods,  File=MyMethods.vb, Module=mine, Method= OfficeOn.

We have a single method OfficeOn that simply issues a CAPI command to turn the office ceiling light ON.  Note that you must pass the hs object to your method, and the module and method must be declard as Public.

To turn the office light ON from any of your HS scripts, you simply need the following statements:

Imports tenGlobalMethods
OfficeON(hs)

If OfficeON is ambiguous because there is another method defined with the same name (not likely in this case) then reference it in your script as:

mine.OfficeON(hs)

Before you deploy your global method to HS, you probably want to test it under tenScripting4 first.  Here is a script defined in tenScripting that will test this global method:



After your global method has been tested in tenScripting, you just need to copy the following file: tenScripting4\tenGlobalMethods\bin\Debug\tenGlobalMethods.dll
to your HS4 root folder.  You must stop HS4 first, copy the file, and then restart HS4.

You must also add an entry to the HS4 file Config\settings.ini to define a reference to the tenGlobalMethods.dll file.  You can do this manually, but tenScripting4 provides a Tool to edit the ScriptingReferences key in settings.ini for you.  Use the Tools/Update HS ScriptingReferences menu item to display this dialog:




The ScriptingReferences entry only needs to be updated one time, but every time you make changes to your global methods in tenScripting4 you must copy the tenGlobalMethods.dll to the HS4 root folder (while HS4 is not running).