HS4 Changes Affecting Scripting

UPDATE: HS4 version 4.1.14.0 now provides an hs4 object of class IHsController, eliminating the need for tenScripting4 to replace hs4 with hs when exporting your scripts.  This also resolves several conflicts where IHSApplication and IHsController contained the same member names and signatures.  While the hs object in HS4 scripting is still of class hsapplication, and contains MOST members from IHSApplication and IHsController, the best practice is to use hs for IHSApplication members  (HS3 functionality) and hs4 for IHsController members (additional HS4 functionality).  Both work the same now in both tenScripting4 and HS4 scripting.

HS4 version 4.1.14.0 also adds a reference to PluginSDK.dll, so there is no longer a need to add it to the ScriptingReferences= in settings.ini.

hs Scripting Object

HomeSeer provides access to the hs object for scripts. hs methods and properties are used to interact with the HomeSeer environment. 

The hs object is instantiated from the HomeSeer hsapplication class.

 In HS3, the hsapplication class provides the same functionality as the HomeSeerAPI.IHSApplication class.  Documentation for these HS3 scripting capabilities are found here. 

In HS4, additional functionality was introduced that is provided by the HomeSeer.PluginSdk.IHsController class. Documentation of this class can be found here.

In HS4, the hs object (expanded hsapplication class) is a combination of the methods and properties of both HomeSeerAPI.IHSApplication and HomeSeer.PluginSdk.IHsController classes.

hs Object Implications to tenScripting4

The HS4 scripting engine provides the legacy functionality of IHSApplication and the additional functionality of IHsController combined as methods and properties of the single hs object.  tenScripting4 runs as an HS4 plugin.  While the plugin environment provides access to both the IHSApplication and IHsController classes that can be instantiated by a plugin, there is currently no way to instantiate a single object that combines the functionality of both (as is the case for the hs object in the scripting environment).

tenScripting4 provides two scripting objects to accommodate these differences. The hs object is of class IHSApplication and is essentially the same as tenScripting3.  Additionally, the hs4 object of class IHsController is provided for the additional HS4 functionality.  For example, you could write to the HS log using the legacy method as:  hs.WriteLog("Type","Message").  To retrieve a list of all defined Categories, you could use  Categories = hs4.GetAllCategories().

When running the script under HS, the hs4 object will not be defined, so when you Export a script from tenScripting4 to HomeSeer, all occurrences of hs4. will be replaced with hs. .

This is handled similarly for C# scripts.

HS4 Does Not Provide Access to the Full HomeSeer.PluginSdk Namespace

There is more functionality provided by the HomeSeer.PluginSdk namespace than just the HomeSeer.PluginSdk.IHsController class. The hsapplication class that is instantiated as hs in the HS4 scripting environment is essentially a concatenation of IHsController and IHSApplication classes.  This leaves out some important HS4 functionality that is provided by the HomeSeer.PluginSdk namespace.  Most importantly, are the necessary Enums to effectively use the IHsController class methods.  For instance, the following:
d = hs4.GetPropertyByRef(DevRef, HomeSeer.PluginSdk.Devices.EProperty.Value)
will successfully retrieve a device's value in tenScripting4.  The equivalent in the scripting environment:
d = hs.GetPropertyByRef(DevRef, HomeSeer.PluginSdk.Devices.EProperty.Value)
will fail. The GetPropertyByRef method is found, but there is no way to reference the enum EProperty in the HomeSeer.PluginSdk namespace.

This can be solved by simply adding a reference to PluginSDK.dll (found in the HS4\Bin\homeseer folder) to the ScriptingReferences key in the HS4 settings.ini file.  You can edit this file manually, or you can have tenScripting4 do this for you.  You will find this function under the Help Menu.

You can find documentation of the HomeSeer.PluginSDK at https://homeseer.github.io/Plugin-SDK-Docs/api/HomeSeer.PluginSdk.html