[How To] integrate a Tasmota device in Home Assistant using MQTT

QIoT technology to allow you to explore potential IoT business opportunities.
Smart home/Smart building/Smart City/
Post Reply
User avatar
Experience counts
Posts: 1103
Joined: Tue May 19, 2009 2:08 am
Location: Norway, Oslo

[How To] integrate a Tasmota device in Home Assistant using MQTT

Post by oyvindo » Thu Sep 19, 2019 10:08 pm

There are many hardware devices available in the market capable of switching mains (110V/220V) on/off in a Smart Home in order to remotely control various appliances.
But, regretfully - the two most popular brands - Phillips Hue and IKEA Tradfri - does not offer a device like this.
(Well, to be quite honest, IKEA does have one, but so far only in a bundle with their own Zigbee wall switch)
Among the many brands to chose from, I haven't been able to find anything compatible with either Phillips or IKEA using the Zigbee standard.
But I have found several based on ZWave and WiFi.
Long story short: My final choice was the Chinese brand Sonoff. They have many low cost devices, and my favorite is the Sonoff Basic switch; https://www.itead.cc/wiki/Sonoff.
The only disadvantage with this brand, is that this manufacturer - just as most others - tries to lock you in as a customer, to use only their products - and become a user in their Cloud offering.
But you can relatively easy break out of this straitjacket by replacing the firmware in the Sonoff device with the open source firmware named Tasmota. This firmware allows you to integrate the Sonoff switch into your own Smart Home platform, independently of the manufacturers limitations. There are lots of Youtube video's and tutorials on the internet on how to flash the Sonoff with the Tasmota firmware, but the objective of this guide is not to explain this. If you are interested in how to do it, the Tasmota Wiki on GitHub is a good place to start; https://github.com/arendst/Sonoff-Tasmota/wiki

Remote control of the Sonoff switch with Tasmota firmware, is mainly done via MQTT.

If you are like me - a passionate fan of Internet of Things (IoT), you may already be running some kind of Smart Home server platform.
I use Home Assistant (HA) and I run it inside Container Station (CS). My objective was to get started with a very simple integration of a single Sonoff switch into HA.
I tried first usingt Belkin WeMo Emulation, which is supposed to be supported by Tasmota, but apparently it is only intended for use with Alexa. The same goes for the Phillips Hue Bridge emulation. So none of those options were usable.
That leaves you with MQTT - which can be very intimidating for a beginner like myself. Every article and How-To Guide I've found, assumes that you know a lot about Linux, command line, JSON and YAML in order to perform even the simplest task (just to mention a few).

So, here is how I did it;
I must make som assumptions/prerequisites - otherwise this guide would be a book, and note just a forum post.

1. I assume you already have Home Assistant v0.98 or later, running on your NAS - preferably in a Docker container in CS, and that you know where and how to edit your configuration.yaml file.
2. I assume you have a Sonoff Basic device ready flashed with Tasmoto 6.6.0 firmware (or later).
3. I assume that you have been able to connect your Sonoff device to your WiFi (WLAN) network and found it's IP address.

First step; Install an MQTT broker in a new container on your NAS.
MQTT serves as a "middle man" sitting between your physical devices and your Home Assistant platform. MQTT is designed to interface with any IP connected device on your LAN/WLAN. It does not support other protocols like Zigbee or ZWave. It has become wide spread due to its flexibility and strong community support, but at the same time it has grown in complexity. But still, it is possible to get started in a very simple way.
MQTT is open source and can be found in many different flavors and versions. You install and run the MQTT broker as a server on your NAS just like any other software.


I my system, I have chosen to install MQTT in a Docker Container in CS.
As you will find out, there are many docker images available to choose from. I chose to use the one from Eclipse named Mosquitto v1.6.6 which you will find on the Docker HUB.
I am not going through the basics of how to install a docker image in CS here - there are plenty guides around on how to do that, but the specifics for this particular image is here:

a) Create a folder somewhere on your NAS, i.e. under Public, and name it whatever you want. This will be the place where you store all your MQTT config, log and settings data - outside the container itself. It's not a good idea to store this inside the container, as it it will be lost if you ever have to reload a new image. Keep in mind that QNAP use the term Shared Folder in several ways. Using File Manager, Shared Folder means a folder which is shared on your network, but when installing a container, Shared Folder means a folder which is shared between your NAS and CS.
b) Inside this new folder you just created, you need to add another folder and name it config and finally, inside the config folder, you should create a dummy text file named mosquitto.conf. Remember that everything from now on is case sensitive!
c) Inside CS search and find the Mosquitto MQTT v.1.6.6 image on GitHub and install it.
d) During installation, go into Advanced Settings in CS
e) Select Network Mode = Host
f) Define the following Shared Folder: Volume from host - browse to the config folder you created in step b). Mount point - should be /config

That's all. Your MQTT container should automatically start after installation. Just now, nothing more will happen. MQTT doesn't have a web front end that you can visit.

Second step; configure your Sonoff device to talk to the MQTT broker.
The Tasmota firmware in your Sonoff must be told (configured) how to find and talk to the MQTT broker. This is how:

i) Direct your browser to the IP address of your Sonoff device, that you found in step 3) above and you should see the opening Webpage.
ii) Click on Configuration and then on Configure MQTT
iii) In the following table, insert from the top: The IP address of your NAS. Set port number = 1883, and in the Topic field, type a name of your choice (avoid using spaces, hyphens and other special characters). Leave all other fields as they are with default values.
iv) Click Save and the Sonoff should restart automatically.
v) Now you should be able to see in the Console windows in CS on your NAS that the Sonoff is connecting (you may have to restart MQTT). It should look something similar to this:

Code: Select all

1568892265: New connection from on port 1883.                                                                                               
1568892265: New client connected from as DVES_7CAC60 (p2, c1, k30, u'DVES_USER').
Third step; Configure Home Assistant to detect and talk to your Sonoff through the MQTT broker.
There are basically two ways to set up integrations in Home Assistant; One is to manually define it in the configuration.yaml file, and the other is to use the Lovelace front end and add it using the Integration option under the configuration menu. I tried both, and it's up to you which method you prefer. Using integration and automatic discovery is definitely easier. I will explain both methods below.
If you have tried the integration method, and for some reason it failed, remember to delete the configuration before you move on to the manual method. It's important to remember that in HA, the automatic integration takes precedence over manual entries in the configuration.yaml file. You cannot use both.

Integration and auto-discovery [IA]
IA1) Open up the web deamon in your Tasmotized Sonoff switch by typing its IP address into your favorite web browser, typically ; http://192.168.0.XX
Once you get to the main menu, click on the button that says Console and the console window should open up. Here you can watch all Sonoff events as they occur in real time inthe upper part, and below is a command line where you can type in any and all commands supported by the Tasmota Firmware, inluding those not available in the GUI.
On the command line, type the following:

Code: Select all

setoption19 on
Then watch as the firmware automatically reconfigures itself for autodiscovery and then restarts the Sonoff.
If everything goes well, your Sonoff should come back online and you can return to the main menu.

IA2) Now go to you Home Assistant web GUI.
Assuming that you haven't entered anything in your configuration.yaml file related to a Sonoff switch (If you have, then clean your configuration file before you continue), and choose configuration > integration and then click on the big + icon in the lower right corner of the GUI. On the popup-box, just type the IP address of the NAS where your MQTT broker is running, and finally tick off the Discovery box and save your setting. Make sure your Sooff device has power and is online, and it should automatically appear in Home Assistant with the name you gave it in iii) above.
Now jump to HA3) below.

Manual setup in the config file
Only perform these instructions if you decided not to use the Integration and auto-discovery above. You cannot do both.
HA1) Open up your configuration.yaml file, where ever you might have stored it, and add the following section anywhere suitable in that file:

Code: Select all

#Mosquitto MQTT 
  broker: NAS-IP

#Sonoff Switch
  - platform: mqtt
    name: name_of _your_switch
    state_topic: "stat/name_of _your_switch/RESULT"
    value_template: "{{ value_json.POWER }}"
    command_topic: "cmnd/name_of _your_switch/POWER"
Make sure you don't already have a section named switch in this file. (You cannot have more then one instance of each section)
The name_of_your_switch must be replaced with the name you gave your Sonoff switch iii) above.

HA2) Save the configuration.yaml file and in your Home Assistant under Configuration - Server Control, click CHECK CONFIG and then if it's ok, restart the server under Server Management. You should never restart Home Assistant directly from CS unless something is wrong and it is no longer responding (hanging).

HA3) Once HA is again up'n'running, you should be able to see your newly achieved accomplishment in the Lovelace Overview page by clicking the three dots in the upper right corner and selecting Unused Entities. You should also be able to find under States in the Developer Tools section. Look for the keyword Switch.

If you've successfully got this far, you can now test the functionality by toggeling the switch in one of three possible ways:

* Directly using the button on the switch itself
* Through the Toggle button in the Tasmota Web interface
* Or by clicking the horisontal slider in the HA Switch entity

No matter which one you choose - they should follow one another.
Well done!
Your next step will be to learn advanced MQTT configuration and scripting, create HA Automation scripts which includes the Sonoff switch, and add security according to your own requirements.

Now run along and buy a lot of Sonoff cheap quality devices (I am not sponsored by anyone - I just like cheap stuff that works) :lol:
Last edited by oyvindo on Sat Nov 02, 2019 1:54 am, edited 4 times in total.

New here
Posts: 2
Joined: Wed Nov 30, 2011 7:43 pm

Re: [How To] integrate a Tasmota device in Home Assistant using MQTT

Post by Rotjong » Mon Sep 30, 2019 1:59 am

Nice !! This one helped a lot !!

I was struggeling for month now to find a tutorial like this.

I used the flashing tutorial on https://github.com/arendst/Sonoff-Tasmota/wiki/Flashing.

With this turorial I could add a couple of devices to the home assistant.

Thanx !!

User avatar
Experience counts
Posts: 1103
Joined: Tue May 19, 2009 2:08 am
Location: Norway, Oslo

Re: [How To] integrate a Tasmota device in Home Assistant using MQTT

Post by oyvindo » Mon Sep 30, 2019 5:56 am

I'm glad to hear that :P
Thanks for the feedback.

First post
Posts: 1
Joined: Sat Oct 22, 2016 11:30 am

Re: [How To] integrate a Tasmota device in Home Assistant using MQTT

Post by mikemor22 » Mon Mar 09, 2020 7:00 am

I’m pretty late to the HA party - but this guide has answered so many questions for me. Many, many thanks 🙂
QNAP TS-453Be 16Gb
4x4Tb RAID5 + HS
QTS 4.4.1
Running Plex, Resilio, UniFi controller, ITunes Server

QNAP TS-251+ with 8Gb
2x2Tb RAID 1
QTS 4.4.1
Docker installs of Home Assistant and Eclipse MQTT

User avatar
Experience counts
Posts: 1103
Joined: Tue May 19, 2009 2:08 am
Location: Norway, Oslo

Re: [How To] integrate a Tasmota device in Home Assistant using MQTT

Post by oyvindo » Mon Mar 09, 2020 2:42 pm

Better late than never :)
You are most welcome!

Post Reply

Return to “QIoT”