HomeSeer Plug-in Architecture and Design

26110 sq 1

Homeseer is a great system, stable and reliable written for Windows with .net as its core. The architecture of HS3 is based on a core engine and a series of plug-ins which communicate bi-directionally with HS3's core. The API for these plug-ins is fairly comprehensive allowing a wide range of interfaces to be developed. Each Plug-in that registers with the HS3 core then receives (if configured to do so) a stream of events generates by all other plug-ins and the core. These events can be filtered for those we're interested in and then actions can be performed. Communication to HS3 allows device control as well as Timers, Events and of course Logging. Because of the way HS3 has been developed, each plug-in has the option to register functions that can then be exposed to other plug-ins and to script running locally. This functionality really pushes HS3 out ahead of the rest allowing virtually any configuration to be achieved with a little code. 


As the plug-in starts it will connect to HS3 over an IP Socket, which is facilitated by managed code DLL's that we include. Once the connection is established a number of requests to functions is made by HS3 to obtain various configuration parameters such as licensing, features, and so on. From this point forward the plug-in is connected to HS3 although a developer should always be mindfull of connection monitroing and handling connection loss. During this start-up process its important that we return data to HS3 as quickly as possible so we're not holding up HS3 which doesn't seem to dedicate a thread to each plug-in. 

In order to interface with some device(s) we need to know when HS3 initiates a device change, such as an ON or OFF, DIM % or even Parameter Change such as HEAT or COOL. This can be handled in two ways, and both have advantages and disadvantages.

Event Stream

Using the event stream allows the plug-in to have a function that is called for every single event on the HS3 system. This local function would trhen need to inspect the events, look for those that are directed to us and then take some aciton. One caveat is that we must not delay in processing and returning from the function or the stability of HS3 will be effected. The method used in all our plug-ins is to push commands into a queue that can then be handled in the background on another thread. An example of this would be a command ON which our plug-in would detect is directed at a device we're managing and would then push an entry to the queue like { DeviceID: 100, Action: ON }. A seperate and isolated thread would then pull commands from this queue and undertake the command execution. Likewise changes in the device(s) we manage can be added to the queue and then changes updated in HS3 in the background. 


Another method to monitor device changes is to poll HS3 every x seconds looking for changes in our devices. This method is ok for small numbers of devices but can take a toll on HS3 when you exceed that. The benefit of this method is that your not dealing with every change everywhere so your event handling code can be quieter, but the drag on HS3 for a large number of queries together with an increaed delay in action makes this method only useful when your looking for a few devices or to monitor something else in HS3 such as plug-in status, Health, and so on. I wrote a plug-in recently which monitored CPU, MEMORY and HD space on the HS3 machine and then populated 3 devices with this data every minute. In this case there was no need for any event processing as the communcations is one way. 


Microsoft .net makes it really easy to have independent processes running on different threads and communication between them and this should be embraced for plug-in development. In our plug-ins we use several threads universally; One thread is the main thread, named [MAIN] and this handles the top leve stuff including monitoring HS3 connections and handling catastrophic failures (such as HS3 going away). [Plugin] is a thread which deals with the HS3 <-> Plug-in communcation. [Hardware] is a low level thread tasked with talking to whatever hardware we're managing. (In the TasMQTT Plug-in [Hardware] is replaced by [MQTT] since our interface to the hardware is solely via MQTT). [QPROC] is the thread that walks the queue and handles events, despatching other threads to do the low level work such as instruct devices and update HS3. [Web] Handles the configuration pages available via the HS3 web interface.

Logging and Diagnostics

When your plug-in isn't behaving as it should or maybe it is but the devices its controling are not then the ability to quickly identify an issue is critical. Accurate Logging is required and this should be handled by another thread that writes to the HS3 eventlog and optionally to a debug file. It makes sense to have a series of 'levels' for each debug message so that we can normally just see the important stuff, but optionally can increase the detail walking down into lower level operatoins when needed. In our plug-ins the level of the debug message is shown in square brackets, e.g. KMT[5] which indicates that the plug-in KMT is outputting a log message at level 5. Level 5 is the normal level for all our plug-ins with levels down to zero being available should they be needed. In our plug-ins the logging level can be set from the Config/Debug Tab AND in the .ini file as DebugLevel=x where x is from 0 to 5. 

Handling the unexpected

For any plug-in that is expected to work non-stop without issue its important that we consider all the scenario's that could cause failure and address them with some automated remedial actions. A good example would be loss of connection to our managed devices, or loss of connection to HS3. Low memory, Disk space, excessive Log file size and so on should all be monitored and corrective actions defined. In our plug-ins when we loose connection with HS3 we close down safely and exit. When we detect issues with our managed devices we attempt reconnection and/or recovery options. This phase of testing is often called the Alpha test, and is done only in-house. 

Beta Testing

Any good software requires testing in real world scenarios and this is where beta testing comes in. The BETA Phase of development is where you co-opt others to take your plug-in and test it in their environments for a period with full debug and logging to iron out any potental issues. A bug tracker is deployed to collect and manage these issues to ensure they are identified, and rectified before the product is launched to the world. 

Our Services

You know this was coming at some point. As a development house of some 25 years we have the skillset and knowledge to undertake any software design and development programme. If you have a hardware (or software) device that you need to interface with HS3 then we're more than happy to quote for the work either outright or with a profit share from plug-in sales. If your looking for advanced setup and event programming then we can do that too, just ask us for a quote.


Development and Support for this plug-ins is free or charge. If you appreciate our work then please consider a small donation.