Sonoff + Tasmota + MQTT + Homeseer Integration

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. 


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. 


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. 


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 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. 


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. 


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. 


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
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 =   <-- 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) 

The BugTracker

This project is using Mantis as the bugTracker. If you have a bug or issue then please report it via You can register for an account if you don't already have one. Please provide as much information as possible and include a copy of the log file either pasted or as an attachment. 

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.  

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

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