espressif

Converting a Tasmota smart plug to ESPHome

by
A photo of a Coosa smart plug, originally running Tuya firmware, and a USB to UART converter. This now runs ESPHome firmware.

Back in June, I flashed some old Tuya Wi-Fi smart plugs with Tasmota firmware. I’ve now re-flashed one of them with ESPHome, an alternative firmware by the Open Home Foundation who are the same people as Home Assistant. In this blog post, I’m going to outline:

  • Why the change from Tasmota to ESPHome
  • How to build a YAML file for ESPHome
  • The flashing process

This is a longer blog post, so if you want to skip the explanations for each section of the YAML file and just want to go ahead and do this yourself, you can download my pre-made YAML file from GitHub, and then follow these instructions.

Why the change from Tasmota to ESPHome

If you’re starting out with custom firmware for your existing devices, then I would still recommend Tasmota. It’s much easier to set up, as you install it first, and then configure it. There’s also a much more extensive repository of supported devices, so you shouldn’t need to do much manual tinkering once Tasmota is installed.

ESPHome, by contrast, requires you to configure it first, and then install it. Furthermore, rather than offering a web interface for configuring your devices, instead you have to do this in a YAML file. And then you have to compile the firmware specifically for your device and upload it.

That being said, ESPHome is much more powerful. You can build automations into it that run on the device itself, rather than through, say, Home Assistant. And as each firmware binary is compiled for each device, it’s much smaller, which allows for easier updates. On some Tasmota devices, you have to install a ‘minimal’ version of the firmware before you can upgrade. By contrast, with ESPHome, your device should be able to update directly to new firmware versions.

As you would expect, ESPHome integrates better with Home Assistant. Indeed, one reason for me changing to ESPHome is that the Tasmota integration takes a while to start up and is one of those slowing Home Assistant down. Firmware updates are also offered through Home Assistant, so you don’t need something like TasmoAdmin to manage firmware updates for multiple Tasmota devices.

Building the YAML file

I’m going to go through each section of the YAML file, to explain what it does, and why it’s necessary. Some of these are specific to the plugs that I’m using, and may not transfer to other devices.

Firstly, with Tasmota still running, open the Configuration screen and choose Template. This will give you a list of the GPIO pins, and what they currently do in Tasmota. You’ll need to note these, so that you can tell ESPHome what pins to use. On mine, these were the ones in use:

  • GPIO4 – LED
  • GPIO5 – Relay
  • GPIO13 – Button

The LED is the light on the smart plug, the relay is what controls whether the power is on or not, and the button is the physical button on the smart plug that controls the relay. Whilst the relay is the most important, to preserve the device’s full functionality, we need to tell ESPHome about all of them.

The ESPHome section

Here’s the first bit of the YAML file:

esphome:
  name: $name
  friendly_name: $friendly_name

esp8266:
  board: esp01_1m

If you use the wizard in the ESPHome Device Builder, then these will have been created for you and filled out with whatever name you’ve chosen. The second block tells ESPHome that the device has an ESP8266 chip, and it’s a generic board. This was the default selection and seemed to work fine for me.

Logging, API, OTA, Wi-Fi

Next, we have the following:

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: $key

ota:
  - platform: esphome
    password: $password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "esphome-smartplug"
    password: $fallbackpassword

captive_portal:

The logger means that the device will keep logs. It’s up to you whether you keep this in, but as I was coming up with this myself, I decided it would be best to help debugging.

Because I’ll be using this smart plug with Home Assistant, we need to include the ‘api:‘ section. Again, the ESPHome device builder should have filled out an API key here.

The ‘ota:‘ section allows for ‘over the air’ updates. This means that your device can update to new versions of ESPHome without needing to be plugged in to a device, either over USB or a UART connection.

In the ‘wifi:‘ section, this includes references to the ESPHome Device Builder’s secrets file which should have your Wi-Fi network SSID and password. If the smart plug can’t connect using these details, then, as a fallback, it’ll create its own access point. This is where we also need the ‘captive_portal:‘ section, which allows the user to select a Wi-fi network if the one we’ve pre-programmed can’t be found.

Web server

Next, we have this section:

web_server:
  port: 80

This is optional, but it creates a Tasmota-like web app that you can connect to. This will allow you to press the button on the smart plug, view the logs, and upload firmware. We don’t need it, but it partially replicates the functionality of the previous Tasmota firmware, and helps with debugging.

Binary sensor

This is the section that enables the hardware button on the smart plug to work:

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO13
      mode: INPUT_PULLUP
      inverted: True
    use_interrupt: True
    name: "Power Button"
    id: "smartplug_button"
    on_press:
      - switch.toggle: "smartplug_relay"
    disabled_by_default: True

We’re telling ESPHome that the button is attached to GPIO pin 13, and, when the button is pressed, to toggle the relay on or off. I’ve also added the ‘disabled_by_default: True‘ line so that it doesn’t show in Home Assistant.

Switch

Now, we need to configure the relay, and make it available to Home Assistant:

switch:
  - platform: gpio
    name: "Switch"
    id: "smartplug_relay"
    pin: GPIO5
    on_turn_on:
      - output.turn_on: led
    on_turn_off:
      - output.turn_off: led
    restore_mode: RESTORE_DEFAULT_ON

So, we’re telling Home Assistant that the relay is connected to GPIO pin 5. We’re also telling it to turn on the LED when the relay is turned on, and off again when it’s turned off. The ‘restore_mode: RESTORE_DEFAULT_ON‘ tells ESPHome what to do when the device boots up, perhaps after a power cut. I’ve set it to try to restore the status that it had before, but if it can’t, to turn the relay on.

LED

Here’s our final block, to tell ESPHome that there’s an LED

output:
  - platform: gpio
    pin: GPIO4
    inverted: true
    id: led

Again, we tell ESPHome that it’s connected to GPIO pin 4. The YAML code in the Switch section tells ESPHome when to turn the LED on or off.

So, now we have a YAML configuration file. This should be added as a new device in the ESPHome Device Builder.

The flashing process

The good news is that switching from Tasmota to ESPHome is easier than from the original Tuya firmware. You probably won’t have to get out a UART converter and cables, unless you accidentally brick your device. Instead, you just need to follow these instructions, which involve manually downloading the firmware binary, and then uploading it to Tasmota. When the device restarts, it’ll be running ESPHome instead.

Flashing Tuya smart plugs with Tasmota

by
A photo of a Coosa smart plug, originally running Tuya firmware, and a USB to UART converter. This now runs ESPHome firmware.

Last year, I wrote about using a tool called tuya-convert to replace the firmware on my Tuya smart plugs. The firmware in question is Tasmota, which is an open source replacement firmware for devices with Espressif ESP chips. All my Tuya smart plugs have an ESP8266 chip, which can take custom firmware.

There are two ways of flashing Tasmota onto Tuya devices – an easy way, and a harder way.

There’s also a kind-of third ‘super-easy’ way, that I’ll mention towards the end.

tuya-convert – the easy way

I mentioned tuya-convert, which is a command line tool that exploits a vulnerability in older Tuya firmware to install Tasmota. You’ll need a computer such as a Raspberry Pi that has both Wi-Fi and Ethernet, and a smartphone. The tuya-convert tool then creates a hotspot that your Tuya devices can connect to when in pairing mode, and deploys the firmware wirelessly.

The key thing to emphasise here is that it only works with older firmware. Tuya patched the vulnerability in an update that came out some years ago, and indeed I’d already installed this on my smart plugs. That meant that tuya-convert could see the smart plugs, but couldn’t deploy the Tasmota firmware. So, I had to do it the hard way.

A photo of my hand holding some wires whilst flashing Tasmota onto a Tuya smart plug

Using a UART converter – the hard way

As you may have guessed from the photo above, the only way I was able to flash Tasmota onto these smart plugs was by taking one apart, and using a USB to UART converter with some jumper cables. If tuya-convert doesn’t work, then this is what you’ll need to do. You’ll need the following:

  • A USB to UART converter – I bought this one from AliExpress for the princely sum of £1.35.
  • Some Dupont Jumper cables – again, I bought these from AliExpress for £2.40. I picked up a big bag of male-male, female-female and male-female cables, but you only really need male-female cables if you want to save a few pence.
  • A computer with a USB port

I would also recommend the following:

  • Some electrical tape to hold things down
  • A USB extension cable

For the plugs that I was working with, I didn’t need a soldering iron, but some others may require it.

Disassembly and what’s inside

Firstly, it is very, very important that your smart plugs are not plugged into the mains while you do this, unless you want to burn yourself and/or your house down. We’ll be providing power via a different method, so make sure your device is not plugged in via the usual method. With my smart plugs, the positioning of the screws means it’s impossible for them to be plugged into the mains anyway.

Next, remove the screws from the plug. There were five on mine – the central one had to be removed first, and then the remaining four. Once that was done, I carefully separated the top and bottom of the housing.

The bottom part includes the high voltage AC circuitry. We’re not concerned with this and can leave it alone. What we’re interested in is the ancillary circuit board in the top part. It’s held in place by two small screws – you can remove these if you wish, but you can easily access the five pin holes that we need with the board still screwed in place.

The pin holes are as follows, with the first closest to the edge:

  • RX – data in
  • TX – data out
  • GND – ground
  • GPI00 – the pin hole that puts the smart plug into flashing mode
  • 5V – the 5 volt power input pin hole

Normally, ESP chips work at 3.3 volts, but there’s a converter chip elsewhere on the circuit board for these specific smart plug. Yours may be different, so check first to see if it’s 3.3 volts or 5 volts. The UART to USB converter that I have offers both, so we’ll use five volts for this.

Connecting the wires

Firstly, make sure your USB to UART converter is not plugged in to the computer. You’ll need to get your Dupont cables and connect them from your converter to the board. The pins on the converter should be labelled, so you need to connect them as follows:

  • From RX on the board to TXD on the converter
  • From TX on the board to RXD on the converter
  • From 5V on the board to 5V on the converter
  • From both GND and GPI00 on the board to GND on the converter

For this last one, I used three cables – two male-male cable from each of the GND and GPI00 ports on the board, and one female-male cable from the GND port on the converter – and then taped the pins at the end of the wires together. If it helps, there’s a standard wiring diagram on the Tasmota Getting Started page – although we’re connecting one additional wire (GPI00).

Getting read to flash Tasmota

Now that we’ve linked the converter to board, we can do the fun bit – flashing the device. There are several ways you can do this, of which I would recommend two:

  • Tasmotizer – this is a simple Windows program for flashing. The key advantage is that it can optionally download and backup the previous firmware, just in case you want to restore it later.
  • Tasmota Web Installer – this allows you to install Tasmota through your web browser, using WebSerial. As it stands, only desktop versions of Chrome, Edge and Opera support it, so you can’t use Firefox or Safari.

Personally, I had a better experience with the Web Installer, so this is what I used. Once you’ve opened your flashing tool, plug the USB to UART converter into your computer and then click ‘Connect’. Your browser will ask for your permission to link the web page with the COM port created by the converter, so you’ll need to grant permission.

Note: sometimes the COM port wouldn’t show for me in the browser. If this happens to you, try opening Device Manager, if using Windows, to ensure that the driver has installed correctly. If not, asking Device Manager to simply update the drivers should be enough. I had the most success if I opened the web page, connected the USB to UART converter and then clicked ‘Connect’ in that order.

If all is well, the web flasher will connect to your device, erase the existing firmware and then upload Tasmota. It’s a quick process – the binary file for Tasmota version 15 is only 655 kilobytes, so it’ll only take a couple of minutes at most.

If you get a connection error, try swapping the RX and TX cables over and then try again, and make sure that the light on the circuit board isn’t on or flashing. If the light is on, it’s a sign that you’ve not connected the GPI00 pin correctly.

Assuming that the flashing worked, you can take the jumper cables out and reassemble your device and plug it back in to the mains.

Configuring Tasmota

So, now that your device has been flashed, you need to configure Tasmota on the device. Get your phone out, and go to Wi-Fi settings. You should see a new Wi-Fi hotspot called ‘tasmota-something-something’, where the somethings are an alphanumeric string – connect to it. A hotspot login box should appear – if not, go to http://192.168.4.1/ in your phone’s web browser.

The first step is to connect Tasmota to your Wi-Fi network. Choose the network, or type it in, and provide the password. Tasmota will then connect, and, if successful, will redirect to its new IP address which it’ll display on screen. I suggest making a note of this.

You’ll now need to navigate to Tasmota’s new IP address in a web browser – you can do this on any device, not just your phone. The first thing we need to do is tell Tasmota what kind of device it has been installed on. The easiest way to do this is with a Template, and there are a huge range of templates listed here. I couldn’t find an exact match for mine, but the closest was this one, which gave me the following template code:

{"NAME":"Anoop SP15","GPIO":[0,0,0,0,56,21,0,0,0,17,0,0,0],"FLAG":0,"BASE":18}

To paste this template into Tasmota, I used this guide. From the Tasmota home screen, I clicked ‘Configuration’, then ‘Configure Other’, and pasted the whole string into the ‘Template’ field at the top. Tick the box that says ‘Activate’, and then the green Save button at the bottom. Tasmota will restart, and then you’ll find that your smart plug now works. Huzzah!

Integrating Tasmota with Home Assistant

If you want your newly Tasmotised smart plug to appear in Home Assistant, then there are a couple more steps that we need to take. Tasmota communicated with other devices using MQTT, so if you don’t already have MQTT set up in Home Assistant, you’ll need to do this. The easiest way is to install the Mosquitto addon; this will then suggest the MQTT integration for you.

Next, we need to create a user account for Tasmota to use with MQTT. In Home Assistant, open Settings, and then People. At the top, select ‘Users’, and then click the blue ‘add user’ button. Give them a username and password, and then save these details somewhere safe for the next step.

Back to Tasmota. Firstly, we need to change a setting to allow Home Assistant to automatically discover your new Tasmota device. From the Tasmota home screen, choose ‘Console’, and input the following command:

SetOption19 0

Press enter. Next, go back to the Tasmota home screen, and into ‘Configuration’ again. Select the ‘Configure MQTT’ option. In the first box, you’ll need to enter the IP address or local hostname for your Home Assistant installation. If you use Home Assistant OS, this is most likely to be ‘homeassistant.local’.

Next, we’ll need to enter the username and password for the MQTT account we created earlier. The rest of the fields can be left with their default values, unless you want to customise the name.

Back to Home Assistant. If this is your first Tasmota device, then you should receive a notification that a new Tasmota device was found, and that you need to install the Tasmota integration. Do this, and your device will now be available. If you add any further devices, these will automatically appear in the Tasmota integration once their MQTT settings have been configured.

And that’s it. You should now be able to control your devices without needing to use Tuya’s cloud services.

The super-easy way – pre-flashed Tasmota devices

If you don’t already own a suitable smart plug, but want to use Tasmota, my advice would be to buy a smart plug with Tasmota already flashed. Local Bytes sell pre-flashed Tasmota smart plugs, so you can skip the disassembly and flashing sections of this guide. Alternatively, try eBay, where these plugs can also be bought pre-flashed.

Personally, if I was in the market for a new smart plug, I would buy one that supports Zigbee or Matter. I’ve previously reviewed some Onvis Thread/Matter smart plugs, and some Meross Wi-Fi/Matter smart plugs.

That being said, I’m pleased to have been able to flash Tasmota on these smart plugs. I’m currently only using one of them, but I’ve been able to give them a new lease of life with about £5 of materials and an hour or so of my time. Indeed, the spare ones may well end up on eBay in due course for someone else to use. It’s far better than letting them become yet more e-waste.

What’s next

Last year I bought a Sonoff Wi-Fi RF Bridge, but was disappointed that it wouldn’t work the way that I expected it to. And getting it to work with Home Assistant was a bit of a pain, requiring a custom integration from HACS or an addon. I’ve already installed Tasmota on it, so it too has local control, and I’m looking at flashing the RF chip with a different custom firmware to make it more useful. That will probably require soldering and is for another future blog post, however.