Creating HS Scripts in tenScripting

HomeSeer Scripts

One of the most powerful features of the HomeSeer product is the ability to write scripts to control the home automation environment.  Since version 2.0, HomeSeer has been based upon the Microsoft .NET Framework.  Scripts can (and should) now be developed using either VB.NET or CSHARP.NET, instead of the vBasic scripting language.

Each HomeSeer .NET script is contained in it's own file with an extension of  either .vb or .cs.  These script files are stored in the HomeSeer script folder \Program Files (x86)\Homeseer HS4\scripts\.  When you want HomeSeer to run a script, usually via a HomeSeer Event, you specify the script file to run and the subroutine (method) within the file to execute.  If you do not specify a method to run, the default is Main.  Here is a typical HomeSeer Event definition that runs a script that uses the default method of Main:

If you want to pass a parameter to the script, you must specify the method along with the parameter.  Here is a typical HomeSeer Event defintion that passes a parameter to the method Main:

HomeSeer only supports passing a single parameter to a script method, and this parameter is always of type String.  A workaround is to pass multiple parameters in a single string, with each parameter separated from each other with a defined character (typically " | ").  The script must then parse the string to seperate the individual parameters (easy to do). The Event above is an example that passes multiple parameters to the method Main:

The following shows the script SpeakAndLogMultipleParms.vb from the HomeSeer script folder opened in Notepad:

Note how easy it is to parse out the two individual parameters that were passed to the script.

A typical HomeSeer script contains a single method that is executed when the script is invoked.  The default method's name is Main.  However, a single script can actually have many methods, each of which can be called from a HomeSeer Event.  The Event specifies both the filename (.vb/.cs) and the entry point (usually Main), as well as any parameters to be passed to the method.

Creating tenScripting Scripts

tenScripting is distributed with four files of sample scripts: SimpleSamples.vb, csSimpleSamples.cs, ComplexSamples.vb, and csComplexSamples.cs.  You must add your scripts to the solution to run and debug them.  You can store all of your scripts in a single .vb or .cs file, or any number of  files.  Do not add your scripts to the existing sample files.  To add a new script file to the solution, first select either the VBscripts or CSscripts project from the Solution Explorer, then click on the menu item Project and then Add and then New Item.  A dialog will open. Click on the icon for Class, change the Class name, and then click Add.  A new .vb or .cs  file has now been added to your solution.  You edit this file to add your script definitions.

You can add any number of scripts to a single .vb or .cs  file in tenScripting, each of these scripts containing one or more methods that can be called from HomeSeer Events. However, each script in HomeSeer resides in a separate .vb or .cs file. The individual scripts within the tenScripting files are identified by defining them within a Class Definition with the name of the HS script.  For VB scripts, you enclose the script definition within  Class Name and Class End statements.  For CSharp scripts, you enclose the script definition within   public class Name {   and   }   statements.  When you export a script from tenScripting to the HomeSeer script folder, each script is placed into a separate file using the name from it's Class Definition statement, and the statements defining the class in tenScripting are removed.  You can create new scripts by entering them using the Visual Studio editor, or you can import existing scripts from the HS scripts folder.  Following is a sample tenScripting file containing three VB scripts:

If you were to export all three of these scripts to the HomeSeer script folder, three separate files would be created: SpeakAndLogNoParms.vb, SpeakAndLogOneParm.vb, and SpeadkAndLogMultipleParms.vb.  Note that each of these scripts are run with the default method of Main.

 Following is a sample tenScripting file containing three C# scripts:

If you were to export all three of these scripts to the HomeSeer script folder, three separate files would be created: csSpeakAndLogNoParms.cs, csSpeakAndLogOneParm.cs, and csSpeadkAndLogMultipleParms.cs.  Note that each of these scripts are run with the default method of Main.

For C# scripts, the following statements must be added to the beginning of each script definition as shown in the above samples:

  readonly HomeSeerAPI.IHSApplication hs = CSscripts.CSinit.hsobject;  // @DONOTEXPORT

  readonly HomeSeerAPI.PluginSdk.IHsController hs4 = CSscripts.CSinit.hs4object;  // @DONOTEXPORT

When your C# script is exported, these statements will be removed.  If you import a C# script from HS, this statement will be added.  If you use the Code Snippet HsCsSnippets/HS4 New Script to create a new C# script (recommended), this statement along with the Class Definition statements will all be generated for you.

While most scripts contain a single method, usually Main, scripts can contain multiple entry points:  A single script definition (in tenScripting, a single Class Defintion), but with multiple Methods defined.   In the tenScripting example below, a single VB script TwoMethods is defined with two callable methods:  ToggleFrontPorch and ToggleBackPorch.  Each of these methods uses the same Private method ToggleDevice.  If two separate scripts were used instead of a single script with two methods, then the method ToggleDevice would have to be copied into each script and any future changes would have to be made in two places.

Two HomeSeer Events are shown below that call the two methods from above: