Homeseer Software Development

HomeSeer Development was discontinued in 2022, simply because in the history of development we had only ever sold 4 licenses.

The good news is that the software is still available to download from the homeseer store, and it *should* be free (We have made several requests to Homeseer to make this so for all our plugins).

The plugins we developed support some fantastic IOT hardware including Sonoff and KMTronic, well worth a look if you are interested in home automation.

When we ceased development, we open-sourced these plugins to on Github for anyone to use and modify as needed. Links are below:



The only restriction on the use of our source, is that you must not sell it for financial gain.


Below are the original use instructions from the old website, converted as much as possible for the new site:


KMTronic Instructions

You can purchase both of these excellent devices from KMTronic Ltd in Bulgaria. If you use coupon code ST2708K46 then you will get 20% discount on your order which is outstanding value. 

There are currently two version of the Web Relay unit

These are high quality, reliable and cost effective units for load control over Ethernet. We can offer you a 20% discount on these units so please contact us (via this site or on the HS3 Forum) for a discount code. 


There is currently only one version of the Temperature Module and it works like this


Both of these devices require 12V DC to power them. You can use an AC Adapter, DIN Rail PSU, or if you prefer use POE with the addition of a TRENDNet TPE-104S or similar. Personally I use the TPE-104S and power everything over ethernet. 


The Plug-In

The KMT Plug-in can be found in the HomeSeer Plug-ins directory under "Analog & Digital Input/Output Device". 


Note: These instructions are for Version 1.055 and later (shown in HS3 as 1.0.5.5). If your using an earlier plug-in then please update before proceeding. 


Configuring the Plug-in

Unlike some plug-ins, GEN plug-in's don't create or delete any devices themselves. Device creation, renaming, deleting and modifying is entirely up to you. Its done like this because in my relatively short time of using Homeseer I've found that plug-ins which create/delete their devices have two things in common, firstly they delete and re-create devices after an update, config change, or just for no reason at all which breaks all my events, and secondly because some plug-ins create a mountain of devices most of which I don't want to see. Having complete control over my devices and knowing they aren't going to change ref and mess up all my events is the reason its done like this. If you'd prefer the plug-in create the devices for you then feel free to make that known as nothing's fixed in stone. 


Creating Binary (ON / OFF) devices for the KMT Plugin

The 8 Channel Web Relay Board from KMTronic support binary (on/off) controls for each of the 8 outputs. These outputs are numbers 1 through 8. You can create all 8 devices or just the ones you need and add more in the future. In this example here we're going to create a device that relates to the first relay on a device at 192.168.1.8. You should of course substitute your IP address of the web relay and relay number when creating devices yourself. 


Firstly login to Homeseer's Web Interface and select View and Device Management. Then click the Green + symbol at the top right and you should get the screen below. 


Give your device a name, it matters not what it is but it should describe the device or purpose to some degree. In our example we're going to call it Side Light. Give it a Floor and Room as usual. If you want this device to be controlled by voice then tick the Voice Command box. If you want to give it a picture then click "Select Device Image" and give it one. Now move onto the Advanced Tab


In the Advanced Tab click the "Device Type (String)" Box and the usual Edit Value box will be shown. This is where the magic happens. In our example we're going to be talking to the first relay (relay 1) on a device at 192.168.1.8. To configure this we enter a Device Type (String) as 


KMT:192.168.1.8/output1


As below


The Device Type (String) is the key to this working. The format is KNT: followed by the IP Address you gave the device, a forward slash /output and finally the relay number, which in this case is 1. Its important to get the KNT: in upper case or it won't work. Press OK and now move onto the Status Graphics Page. 


And your all done so click DONE and your device will be created.


Repeat the above steps to create devices for all your units and relays. Here's an example of all 8 relays setup, albeit with different IP's. You can see that I've named some of the relays something useful and the rest are unused but I've still created them for the future. 


The only part here that matters is the TYPE column (Device String) and you can see that we've got a device here at 10.1.0.33 with relays from output1 through 8 setup. 


When the plug-in loads, it will search all your devices for those with KNT: in the device string. When it finds these it will add them to its list of managed devices and create associations between HS3 and the web relays. 


You can always check the Web Relays have been detected successfully by selecting Plugins then KMT then Config from the HS3 web interface. This will bring up a screen similar to the one below:


Creating Sensor devices for the KMT Plug-in

So each LAN-DS1820 device can support up to 4 temperature sensors but you need only configure the ones you're using. In our case we've used 3 of the 4 sensors. 


Firstly login to Homeseer's Web Interface and select View and Device Management. Then click the Green + symbol at the top right. Give the device a sensible name and give it the usual room and floor and then TICK the "Status Only Device" box, and untick "Voice Command" then move onto the Advanced Tab. 


In the Advanced Tab click the "Device Type (String)" Box and the usual Edit Value box will be shown. In our example we're going to be reading from the first sensor on a device at 192.168.1.9. To configure this we enter a Device Type (String) as 


KNT:192.168.1.9/sensor1

As below


Now move onto the Status Graphic Tab which is actually more important about how we represent the value from the sensor. You'll need to remove anything currently in there and then add a New Range Value


Give it a sensible range, in my case its -50 to 50 which covers any reading we're likely to get from the sensor. My suffix is "c" and I want two decimal places and then click STATUS under Status Control. 


Now add a New Range Graphic. In this case the choice is yours how you want this shown, and in this example we're just going for one graphic for the whole range (-50 to 50) but you can of course have a blue icon from -50 to 0, then a green icon from 1 to 20 and a red icon from 21 to 50 but here we're keeping it simple and I'm going to use a graphic from the OMNI plugin which I do like. 


And now you can go ahead and click DONE. When you've setup all your sensor devices your going to see something like this


You'll notice that our icon and temperature are formatted perfectly, but you can of course change this to meet your requirements.


The Scale for Temperature measurement can be selected in the CONFIG section of the Plug-in. Change the scale and then SAVE. After SAVE is confirmed, then disable and re-enable the plugin for the changes to take effect. 


Now re-load the plug-in and you should see in the plug-ins Config Tab all your newly created devices along with their type and state. If you find one or more of your configured devices missing then re-check the Device String on the Advanced Tab is correctly formatted. 


IMPORTANT: Application Note; The KMTronic Web Relay is designed for resistive loads such as lights and heaters. If your going to use it with Motors then an additional capacitor (600V 680nF) should be fitted between the Output and Neutral to ensure long life of the relays. Be sure to insulate the legs of the capacitor with heat shrink where exposed. 


For some background and an overview of Design and Development Follow this link


Sonoff / Tasmota Instructions

Unlike some HomeSeer plug-ins, GEN plug-in's don't create or delete any devices themselves. Device creation, renaming, deleting and modifying is entirely up to you. Its done like this because in my relatively short time of using Homeseer I've found that plug-ins which create/delete their devices have two things in common, firstly they delete and re-create devices after an update, config change, or just for no reason at all which breaks all my events, and secondly because some plug-ins create a mountain of devices most of which I don't want to see. Having complete control over my devices and knowing they aren't going to change ref and mess up all my events is the reason its done like this. If you'd prefer the plug-in create the devices for you then feel free to make that known as nothing's fixed in stone. 


Creating Binary (ON / OFF) devices for the TasMQTT Plugin

A binary Sonoff (or ESP8266) running Tasmota Firmware version 5 or above has a specific command and control format in MQTT. You will need to know the device name (the one you configured on the device itself either by building your own firmware or by using the TTL serial commands or Web Interface. You will also need to know how many outputs it has. The Sonoff Basic for example has one output whereas the Sonoff 4CH has 4. 


Firstly login to Homeseer's Web Interface and select View and Device Management. Then click the Green + symbol at the top right and you should get the screen below. 


Give your device a name, it matters not what it is but it should describe the device or purpose to some degree. In our example we're going to call it Side Light. Give it a Floor and Room as usual. If you want this device to be controlled by voice then tick the Voice Command box. If you want to give it a picture then click "Select Device Image" and give it one. Now move onto the Advanced Tab


In the Advanced Tab click the "Device Type (String)" Box and the usual Edit Value box will be shown. This is where the magic happens. In our example we're going to be connecting a device we've named sonoff4 and its a Sonoff Basic with one output. To configure this we enter a Device Type (String) as 


MQTT:sonoff4/POWER


The Device Type (String) is the key to this workng. The format is MQTT: followed by the name you gave the device, a forward slash / and finally the name of the output, which in this case is POWER. The entire string is case sensitive so Sonoff4 is not the same as sonoff4 and Power is not the same as POWER. Get it wrong and it won't work. Press OK and now move onto the Status Graphics Page. 


We need to change the 'On' value from 100 to 1 as shown below. 


Offline State (Optional)


If you want to be able to tell if the Sonoff device has gone offline (been powered off, lost connection to Wifi etc) then you can do this by adding another Status Value Pair for the Value 2. To do this click Add New Single Value, which should be added as 2. Click 'Change me' and enter OFFLINE and leave control use as Not Specified. If you wish you can go ahead and add a graphic for this value 2. I've used the Homeseer built in image status/custom.gif as below


And your all done so click DONE and your device will be created.


Repeat the above steps to create devices for all your Sonoff Tasmota units. As a general rule devices with only one output will call it POWER whereas devices with more than one call them POWER1, POWER2, etc. A Sonoff 4CH for example has 4 outputs named POWER1, POWER2, POWER3 and POWER4 whereas a Sonoff DUAL has two outputs named POWER1 and POWER2.  


Creating Sensor Devices for the TasMQTT Plug-in

In the same way that we need to create devices for Binary Outputs we can create devices to receive sensor data from your Sonoff's. A good example would be the Sonoff TH16 which sends Temperature and Humidity Data, or the Sonoff POW which sends power usage data. Because your creating the devices and not the plug-in then you choose what you want to receive. We're going to setup a device here for receiving the Temperature reading of a Sonoff TH16 but the process is the same for any sensor value. Firstly, we need to create a virtual device using the Green + in the top right. We're going to call our device Livingroom Temperature but you can call it anything you like. 


Once you've given the device a name, selected a room and floor then move on to the Advanced Tab and enter the Device Type (String) in the format MQTT:sonoffth1/Temperature as below


Now move on to the Status Graphics Page. As this is your device you can customise this to suit your needs but for a Temperature reading we're going to probably want to see the value to two decimal places and with a 'c' or 'f' after it. To do this delete the single values 0 and 100 and remove the status graphics. Now create a New Range Value and give it a sensible range -99 to 99. Set the prefix to nothing, the suffix to " c " or " F " and click Status under "Status-Control". Now you can add a "New Range Graphic" and add some icons to the range. Your screen should look something like this


You can of course customse this to your needs. For example here you could have three ranges, -99 to 0 which could be a 'freeze' icon, 1 to 20 which could be a normal icon and 21 to 99 which could be a Hot icon. Its your device so configure it how you see fit. The plug-in simple needs to have somewhere to store the value, the rest is up to you. 


Now click DONE and repeat the steps above for any additional sensors you want to setup. 


Remember, you create devices for the sensor values you want and only the ones you want. The Sonoff POW for example has a range of values but the only one I want to see is the current Wattage. 


KEY FACT: The plug-in looks for a topic which has "POWER" in it, if it finds that then it assumes its a binary on/off device, otherwise I assumes its a sensor. For example here in the Sonoff POW you could have two devices MQTT:sonoffpow/POWER which is considered ON/OFF and MQTT:sonoffpow/Power which is a sensor for Power used. 


Sonoff Tasmota Outputs and Sensor Names

Sonoff Device Output/Sensor Name
Sonoff Basic POWER
Sonoff DUAL

POWER1

POWER2

Sonoff TH16

POWER

Temperature

Humidity

Sonoff 4CH

POWER1

POWER2

POWER3

POWER4

 Sonoff SC (Socket)  
 Sonoff Touch

POWER1

POWER2

POWER3

 Sonoff POW

POWER

Total

Yesterday

Today

Period

Power

Factor

Voltage

Current

A few weeks ago I downloaded a trial of Homeseer whilst investigating replacements for our ageing HAI OmniPro II and temperamental Contorl4 System. Homeseer has a lot of positives and a few negatives but the real power comes from the fact that (a) the product allows you to write VB script to control just about anything and (b) via Plug-ins you can interface with pretty much any IP based device fairly easily. After about 4 weeks of using Homeseer it became clear that whilst the power is there to interface with the world there are a limited number of 'Plug-ins' available and some of those appear to be no longer maintained. Regardless its still a great system for anyone who likes getting down and dirty with the code to achieve exactly what they want for HA. This article describes how to connect Sonoff devices (or any device with Tasmota or similar firmware) to Homseer via a Broker. This guide assumes you have some basic electronics and programming knowledge. 


Sonoff

ITEAD from Shenzhen China have been around for a while now and their Sonoff range of control devices are not only cheap but actually pretty good. When you look at the Sonoff Basic, which is essentially a power supply, ESP8266 and a relay then you have a neat wifi switch in a small package. If you actually add up the cost of the components its hard to make one for the price of these units but that's the china effect I guess. Anyway, since the 'basic' ITEAD now have a comprehensive range of Sonoff devices, from the Basic, the Dual and the 4 Channel to the elegant touch wall switches and we'd be crazy not to want to hook these up to our HA system. 


Out of the box the Sonoff device comes with custom firmware that requires an 'app', Internet access and a service that's hosted in China. Whilst this is ok for some, being able to link these directly to our Homeseer is a preferred option. I have now received, flashed and integrated every Sonoff variant and all work just fine which is nice. 


Tasmota 

Developed by Theo Arends, the Tasmota firmware runs on the ESP8266 and connects your Sonoff devices to MQTT. The firmware is GPL and full source is available for those (like me) who want to tinker with it to support other devices quickly and easily such as NodeMCU. Flashing your Sonoff device depends on which device but most can be flashed 'over the air' using SonOTA but others require a direct connection to the conveniently placed programming connections. Personally, even though I've used SonOTA, I still prefer the hard wired approach. I won't go over the flashing process here because there are enough guides on the Web covering this. 


MQTT

Back in 1999 IBM came up with MQ Telemetry Transport Protocol to allow for lightweight communication between devices such as sensors in a queue-able and reliable manner. Since then its been developing and is now an accepted standard at version 3.1.1. MQTT is a service provided by a Broker such as Mosquitto which is open source, multi-platform and very stable but there are many more and the choice is very much yours. You'll need to install and test a MQTT broker on your local network in order to make any of this work. 


The premise of MQTT is simple; There are publishers (devices that send information) and subscribers (devices that listen for information). Devices can be both publishers and subscribers and this is often the way it works out. 


Hanging it all together

Once you have your Sonoff devices flashed with Tasmota, have them on the network, can access them and have given them a unique name then you should be able to control them directly from MQTT with a tool like MQTT.fx. Once your connected to your newly installed MQTT Broker, from MQTT.fx subscribe to # and you should start seeing telemetry from your Sonoff's in the subscription tab. 


In Tasmota, each Sonoff is given a unique name such as sonoffsw1 or sonoff1 as above. These names (or Topics) are CaSe SeNsItIve so be aware. These devices subscribe to cmnd / The unique device name / Output name. In the example above our device sonoff1 has an output called POWER (its a Sonoff Basic) to to turn it on we'd publish cmnd/sonoff1/POWER = 1. To turn it off cmnd/sonoff1/POWER = 0. 


You can 'publish' from the MQTT.fx app to test that you can turn your sonoff devices on and off. Sonoff devices with more than one output name them POWER1, POWER2, etc, whereas the Sonoff basic is just POWER. You'll also notice that for every publish that changes one of the Sonoff outputs, the Sonoff will publish a stat/ or Status message in the form stat/sonoff1/POWER for example confirming the change. This isn't really important for the Sonoff Basic, but for the touch switches then we need to know if someone has pressed the touch switch so we can keep Homeseer up to date with the current status of the devices. 


The Plug-In (Windows Only - For now)

Once you have all your Sonoff's flashed, on the network, connected to your broker and working in MQTT.fx then its time to install and setup the plug-in. Installation is simple:


For the current Release


  1. You will find the TasMQTT plug-in in the homeseer web interface under PLUG-INS / Manage and then Additional Interfaces, Lighting & Primary Technology. Select it and install it. 
  2. Enable it
  3. Browse to PLUG-INS / Manage / TasMQTT / Config
  4. Setup your MQTT Broker IP and optionally username/password. 
  5. Select SAVE

For BETA Releases


  1. Download and extract the software from the URL you were given. 
  2. Copy the HSPI_TasMQTT.exe and M2Mqtt.net.dll into the "C:\Program Files (x86)\Homeseer HS3" directory (or Wherever you installed Homeseer). 
  3. Copy the TasMQTT.ini file into the "C:\Program Files (x86)\Homeseer HS3\Config" directory (or \Config under the homeseer directory if you installed homeseer elsewhere). 
  4. Edit the TasMQTT.ini file and change the MQTTBroker to be the IP Address of your local broker. If your using authentication then also fill in the MQTTUsername and MQTTPassword. Leave DebugLevel at 2 for now. 

Checking its installed


Now its installed and configured. You should be able to see the TasMQTT plug-in in Plug-ins/Manage from the Homeseer web interface. You can go ahead and enable it and make sure it loads ok. 


and that's the install complete. If it fails to start or errors are shown in the homeseer 'Log' then double check your settings in rtMQTT.ini are correct. If they are then move on to Debug later in this article. 


Configuration

A separate page is dedicated to creating HS devices for use with the Plug-In. The page can be found TasMQTT Plug-in - Creating Devices. Return to this page once you've created them. 


Activate 


The Plug-in currently only checks for devices when it starts up (this will change in later versions) so for now you need to go to Plug-ins, De-enable the plugin, give it 10 seconds to quit and then re-enable it. During the start up the plug-in scans all your devices and looks for MQTT: in the device string. When its found it adds this device to the list of devices it needs to control. 


[Update: From Version 1.093b a RELOAD button is available on the Status Tab of the TasMQTT Config page]


Assuming start up is good and the Homeseer log shows "[5] Plugin : Ready" then we're good to go. 


Using the Homeseer web interface, in Device Management turn your Sonoff devices on and off and verify they do in fact turn on and off. You'll notice in the Homeseer Log TasMQTT Published X to sonoffname/POWERx to show its received the command and send it to the broker. 


Debug

If its not working, then here are the steps to debug the issue. Firstly we need to consider if the Plug-in Started up correctly and to do that check the Homeseer Log (View / Log) and look to see if the plugin logged TasMQTT[5] MQTT Reports Ready ? If so then your MQTT Broker and your TasMQTT.ini configuration are correct otherwise go back and check the MQTT broker is running, the configuration is correct both on the Broker and the TasMQTT.ini is in the Config directory under Homeseer HS3. From Version 1.093b onwards, MQTT Config can now be done in the Config tab of the plug-ins web page. 


The 'Status' Page under Plug-ins / TasMQTT / Config in the Homeseer Web interface is a good place too start and will show all the devices you setup and their current status. You can use Refresh to refresh the data. Be sure to check the Device Name and Target are correct as these are Case Sensitive, that is Sonoff4 is not the same as sonoff4. Devices should be 'online' as long as the plug-in can talk to the device and receive telemetry. 


If the plug-in starts up ok and you get the TasMQTT[5] Ready in the Homeseer log and your devices look to be configured ok in the config page, yet its not controlling your devices then we need to look deeper into the workings of the plug-in. This can be done by checking out the Debug tab of the TasMQTT plug-in page. The debug shows deeper levels of debug messages and may give a clue as to the problem. Assuming connection to MQTT is successful then you'll need to look at the messages to and from the Sonoff Tasmota devices. There is a great deal of 'chatter' between plug-in and devices so look beyond that to the real action which is where the plug-in sees a change in a HS3 device and then issues a command to the device, and where the device changes state and the plug-in updates HS3. 


If you want to log this info to a file, which can really help when you have many devices you can do this by :


Either edit the TasMQTT.ini file in the Homeseer/Config directory and add a line "LogFile=C:\temp\TasMQTT.log" or use the Config Tab from the TasMQTT web page to set a log file to "C:\temp\TasMQTT.log" or any log file location and name of your choice. 


Now De-enable the Plug-in, wait for it to close, then re-enable it. 


Now in the HomeSeer log you will see an entry confirming the Plugin has opened its log file...


Apr-14 12:00:26 TasMQTT[5] Opened Log C:\Temp\MQTT.log

Typical Logfiles 

Plug-in Start up


08/03/2018 14:39:14:[5] Main : Starting Plug-in Version 1.033a
08/03/2018 14:39:14:[5] Main : Connecting to server at 127.0.0.1...
08/03/2018 14:39:14:[5] Main : Connected to Version 3
08/03/2018 14:39:14:[5] Main : Connected, waiting to be initialized
08/03/2018 14:39:14:[5] Plugin : Starting initializiation.
08/03/2018 14:39:15:[5] Plugin : Debug Level 2
08/03/2018 14:39:15:[5] Plugin : Ready


If this looks ok then try and control one of your devices via the Homeseer web interface. You should see something like this...


08/03/2018 14:42:43:[2] HSPI : Ignored the previous 566 events
08/03/2018 14:42:43:[3] HSPI : Device 388 = 1 and isOn=True Queued
08/03/2018 14:42:45:[3] QPROC : Command [cmnd] Topic [sonoffdual1/power2] PayLoad [1]
08/03/2018 14:42:45:[2] MQTTPub : Publishing 1 to cmnd/sonoffdual1/power2
08/03/2018 14:42:45:[2] MQTT : Received sonoffdual1/result [stat/sonoffdual1/RESULT] ={"POWER2":"ON"}
08/03/2018 14:42:45:[2] MQTT : Received sonoffdual1/power2 [stat/sonoffdual1/POWER2] =ON
08/03/2018 14:42:45:[5] MQTT : Found our device changed sonoffdual1/power2 in Device 388
08/03/2018 14:42:47:[3] QPROC : Command [stat] Topic [388] PayLoad [1]
08/03/2018 14:42:47:[2] QPROC : Device 388 = True
08/03/2018 14:42:47:[5] QPROC : No Change needed in HS


This shows that the plug-in received the change, published the change to the MQTT Broker and received the response from the Sonoff to show the change. This should hopefully give you enough to figure it out, but if not then raise an issue at the BugTrack and we'll help. 


INI File Settings


Configuration for the plug-in is stored in the TasMQTT.ini file which resides in the Config folder under the HS3 main directory. There are a bunch of settings in here most of which you can set from the CONFIG tab of the plug-in but some you cannot. 


  • MQTTBroker = 10.1.2.3   <-- This is the MQTT Broker IP
  • MQTTUsername = Fred <-- This is the username for authenticating with the broker, blank of missing if anonymous
  • MQTTPassword = Pass  <- This is the password for authenticating with the broker, blank or missing if anonymous
  • DebugLevel=5  <- The amount of debugging to be produced, Defaults to 5
  • LogFile=C:\temp\log.txt  <- If exists will log debug to the given log file. 
  • DoUpdate=false  <- By default changes made at devices DO NOT trigger HS3 events. Set this to true to have HS3 events triggered by local device changes (buttons on devices pushed) 

Enhanced Debug

The Debug Tab shows the last 100 lines of plug-in logging at a deep level but there is an 'enhanced debug' check box that turns on ALL the debug. This can blow up the log file with a huge volume of data so don't leave it enabled past testing. There are no normal situations where enhanced debug would be needed except where we've asked you to turn it on to track down an issue with HS3 -> plugin communications.  



Index v1.028 Standard v1.114   Copyright © 2024 GEN Partnership. All Rights Reserved, Content Policy, E&OE.   ^sales^  0115 933 9000  Privacy Notice   238 Current Users, 457 Hits