You should be familiar with the following topics before developing a plugin for the HomeSeer platform:
Create a new console app project targeting .NET Framework 4.6.2 in your choice of language. (Examples are provided in C# and VB)
The project's root namespace and assembly name must start with HSPI_ For example: HomeSeerSamplePlugin should be HSPI_HomeSeerSamplePlugin |
The PluginSDK is available through NuGet for inclusion into your plugin projects.
The list of currently installed NuGet packages for your project should look like this:
In some older versions of Visual Studio, the default NuGet package source is not configured. Make sure the following package source is configured: https://api.nuget.org/v3/index.json |
The HomeSeer platform utilizes reflection to facilitate communication between plugins and the system. When HomeSeer connects to a plugin, it looks for an HSPI class defined at the root of the assembly namespace.
Create a new class in your project called HSPI that inherits from AbstractPlugin.
using HomeSeer.PluginSdk; namespace HSPI_HomeSeerSamplePlugin { class HSPI : AbstractPlugin { } } |
Imports HomeSeer.PluginSdk Public Class HSPI Inherits AbstractPlugin End Class |
Override all of the required methods and properties in your HSPI class. Delete the default code in the three overridden methods that throw exceptions, and return true in OnSettingsChange. You will define these later on in the plugin development process.
protected override void Initialize() { } protected override bool OnSettingChange(string pageId, AbstractView currentView, AbstractView changedView) { return true; } protected override void BeforeReturnStatus() { } public override string Id { get; } public override string Name { get; } |
Protected Overrides Sub Initialize() End Sub Protected Overrides Function OnSettingChange(pageId As String, currentView As AbstractView, changedView As AbstractView) As Boolean Return True End Function Protected Overrides Sub BeforeReturnStatus() End Sub Public Overrides ReadOnly Property Id As String Public Overrides ReadOnly Property Name As String |
The Name of the plugin is what is shown to users on the HomeSeer platform. It should be unique and represent what your plugin does.
Do not use any special characters in the name of your plugin except "-", ".", or " " (space), and please aim for 16 characters or less to ensure the name displays correctly on all display sizes. |
public override string Name { get; } = "HomeSeer Sample Plugin"; |
Public Overrides ReadOnly Property Name As String Get Return "HomeSeer Sample Plugin" End Get End Property |
The Id property on the HSPI class is used by HomeSeer as the unique identifier for your plugin. It is recommended to use the name of your plugin, removing any special characters, and removing spaces or replacing them with dashes. Case is ignored. See the AbstractPlugin.Id Property documentation for more information.
public override string Id { get; } = "HomeSeerSamplePlugin"; |
Public Overrides ReadOnly Property Id As String Get Return "HomeSeerSamplePlugin" End Get End Property |
This is all that is necessary to create and start a plugin on the HomeSeer platform. Your HSPI class should look like the class below.
using HomeSeer.Jui.Views; using HomeSeer.PluginSdk; namespace HSPI_HomeSeerSamplePlugin { public class HSPI : AbstractPlugin { protected override void Initialize() { } protected override bool OnSettingChange(string pageId, AbstractView currentView, AbstractView changedView) { return true; } protected override void BeforeReturnStatus() { } public override string Id { get; } = "HomeSeerSamplePlugin"; public override string Name { get; } = "HomeSeer Sample Plugin"; } } |
Imports HomeSeer.Jui.Views Imports HomeSeer.PluginSdk Public Class HSPI Inherits AbstractPlugin Protected Overrides Sub Initialize() End Sub Protected Overrides Function OnSettingChange(pageId As String, currentView As AbstractView, changedView As AbstractView) As Boolean Return True End Function Protected Overrides Sub BeforeReturnStatus() End Sub Public Overrides ReadOnly Property Id As String Get Return "HomeSeerSamplePlugin" End Get End Property Public Overrides ReadOnly Property Name As String Get Return "HomeSeer Sample Plugin" End Get End Property End Class |
The last thing to do to get the plugin ready to build, is initialize and start the plugin in the application's Program.Main method. All of the code needed to start a connection between the plugin and HomeSeer is already taken care of in the AbstractPlugin.Connect Method; so the only thing you need to do in Program.Main is initialize an instance of the HSPI class and call Connect.
namespace HSPI_HomeSeerSamplePlugin { internal static class Program { private static HSPI _plugin; public static void Main(string[] args) { _plugin = new HSPI(); _plugin.Connect(args); } } } |
Module Program Dim _plugin As HSPI Sub Main(ByVal args As String()) _plugin = New HSPI() _plugin.Connect(args) End Sub End Module |
All plugins must include an application config file to help in locating dependent assemblies. Without this file, your plugin may not work correctly. This is discussed in more detail in Plugin Packaging.
Add a new file to the project called app.config with the code below, using the Id of your plugin in the privatePath attribute of the probing tag.
<?xml version="1.0" encoding="utf-8"?> <configuration> <startup> <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6.2"/> </startup> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <probing privatePath="bin/HomeSeerSamplePlugin;bin/homeseer"/> </assemblyBinding> </runtime> </configuration> |
See the Microsoft docs on Configuring Apps by using Configuration Files for more information on the available tags. |
HomeSeer probes its install directory for EXE files that begin with HSPI_ (which should automatically be the name of the application file produced by your project). There are a couple of different ways to go build and deploy a plugin to begin testing it with HomeSeer. You can build the project and then manually copy all of the files to their respective locations in the HomeSeer install directory, run your plugin remotely, configure the project build process to automatically copy everything to the HomeSeer install directory, or a combination of any of these methods; whichever works best for you. Prior to publishing your plugin though, it is always recommended to test a replicate user experience by deploying the plugin directly to the HomeSeer install directory and letting HomeSeer initialize the connection just like if you installed it from the store to your system for the first time.
There is currently a bug in assembly management when it comes to facilitating custom liquid tags in HTML feature pages that prevents a plugin EXE from being deleted or overwritten unless the HomeSeer system is stopped. |
To manually deploy your plugin to the HomeSeer install directory:
To run your plugin remotely:
To set up direct deployment:
Within the project element, and underneath the first import element, add a new PropertyGroup element with a Label of "HomeSeer Properties" that includes two child elements called HomeSeerRoot and PluginId. The HomeSeerRoot element should be a relative path from the plugin project to the HomeSeer install directory, and the PluginId element should be the Id of your plugin without any HSPI_ prefix.
<PropertyGroup Label="HomeSeer Properties"> <PluginId>HomeSeerSamplePlugin</PluginId> <HomeSeerRoot>..\Homeseer\Homeseer\</HomeSeerRoot> </PropertyGroup> |
Change the OutputPath element content to $(HomeSeerRoot)
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'DirectToHs|AnyCPU' "> <PlatformTarget>AnyCPU</PlatformTarget> <DebugType>none</DebugType> <Optimize>false</Optimize> <OutputPath>$(HomeSeerRoot)</OutputPath> <ErrorReport>prompt</ErrorReport> <WarningLevel>4</WarningLevel> <Prefer32Bit>false</Prefer32Bit> <DebugSymbols>false</DebugSymbols> </PropertyGroup> |
Scroll down to the bottom of the project file, and, at the end of the ItemGroup elements, add a new ItemGroup that points to the local HTML folder for your project
<ItemGroup> <HtmlFiles Include="html\*"> <InProject>false</InProject> </HtmlFiles> </ItemGroup> |
Finally, as the last item in the Project element, add a Target element that handles copying the HTML files to the HomeSeer html folder as expected like so
<Target Name="AfterBuild" Condition=" '$(Configuration)|$(Platform)' == 'DirectToHs|AnyCPU' "> <Copy SourceFiles="@(HtmlFiles)" DestinationFolder="$(OutputPath)\html\$(PluginId)" /> </Target> |
Now that you have built and deployed your plugin to HomeSeer, you can start it up and see it run alongside HomeSeer on the Manage Plugins page in the web UI. The plugin currently doesn't do anything in its current state, but, what it does from here, is entirely up to you.