tasmota

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.

Tasmota firmware upgrade failing due to lack of storage space

by
A screenshot of the Tasmota firmware upgrade screen on the web interface

Once you’ve switched your ESP devices from the stock proprietary firmware to Tasmota, the good news is that future firmware upgrades to newer Tasmota versions should be straightforward. You just need to open your device’s web interface, and do an over-the-air (OTA) upgrade, or use something like TasmoAdmin to bulk-upgrade multiple devices. At least, that’s how it works in theory.

What you may find is that the update fails, due to a lack of storage space. So today, I’m going to outline four possible workarounds that you could try if your Tasmota firmware upgrades fail.

Why is there a lack of storage space?

Firstly, a bit about why this happens. You’re most likely to encounter this error with devices that use the ESP8266 chip. Some of these chips come with as little as one single megabyte of flash memory storage, and the standard build of Tasmota is 656 kilobytes (as of version 15.0.1 which is the latest at the time of writing). There simply isn’t enough space for both the current firmware and the new firmware to sit side-by-side ahead of the update process.

Now that we understand why the problem occurs, we can try some solutions.

Solution 1: gzipped binaries

As long as you’re upgrading from a version newer than Tasmota 8.2 (which came out over five years ago now), you can use the smaller gzipped binaries. This reduces the standard Tasmota 15.0.1 release binary down to 469 kilobytes.

However, on some of my devices, that was still too big – 656 plus 469 is more than 1024 kilobytes and exceeds the capacity of the 1 MB flash storage.

Solution 2: install tasmota-minimal first

There are a couple of slimmed down versions of Tasmota:

  • tasmota-lite – a cut-down version of Tasmota without many of the sensors or drivers included
  • tasmota-minimal – the bare-minimum of Tasmota which can’t do anything apart from be upgraded to the full firmware

What you can do is install the latest version of tasmota-minimal first, and then the latest standard version of Tasmota. tasmota-minimal is only 265 kilobytes, and so it’s small enough to fit alongside the standard firmware. Once installed, there’s then space for the full version to be installed.

When you do an OTA upgrade, this is the process that should happen – tasmota-minimal gets installed first, and then the full version. But if it doesn’t, you can do this manually yourself. Your device settings, such as the GPIO mappings and MQTT settings, will be retained during the process.

Solution 3: tethered firmware update

A tethered update is where you use another device, such as a PC, to update the firmware. This means physically connecting the device to the PC. It gets around the storage limitation as the firmware doesn’t need to be downloaded to the device running Tasmota first.

How easy this will be will depend on the device, and where it is. If you’re running Tasmota on a development board, such as a Wemos D1 or m5stack Atom, then you can plug in into your PC with a standard USB cable (as long as it’s a data and power cable). However, if your device is buried away somewhere inaccessible, or is a consumer device that requires disassembly and a USB to UART converter, then you may not want to do this every time a new version is released.

Solution 4: Compile Tasmota yourself

The standard builds of Tasmota cover most common use cases. However, as Tasmota is open source, you can compile it yourself. That way, you can create a smaller, customised build for your device that doesn’t include any extra functions that aren’t needed. There are tools available to do this, but this is really only for advanced users – especially as you’ll need to recompile the binaries for each release.

Solution 5: Switch to a different firmware

As I mentioned last month, Tasmota is not the only game in town. If you also use Home Assistant, then consider replacing Tasmota with ESPHome.

ESPHome has a higher learning curve, due to its use of YAML configuration files. But, once this is set up, it’s easier to compile new binaries each time a new version of ESPHome is released. And, if you’re lucky, you’ll be able to download a pre-built YAML file from the ESPHome Device Repository. Just be aware that it’s not as extensive as the Tasmota Supported Devices Repository – the ESPHome repository has details of around 600 devices compared to almost 3000 for Tasmota. I wasn’t able to find an exact match for ESPHome for my smart plugs, for example.

ESPHome has some other advantages. For example, you can edit the YAML configuration to tell Home Assistant what type of device is plugged in, say a light. That means it’ll appear in Home Assistant as a light, rather than a switch, without needing to use the Change device type of a switch helper.

As with solution four, having a smaller firmware binary will make future OTA updates easier, and these updates can be managed through Home Assistant.

TasmoAdmin: manage multiple Tasmota devices

by
A screenshot of the TasmoAdmin interface

Now that I have multiple Tasmota devices, I went to look for a tool to manage them collectively, and found TasmoAdmin. It’s a web-based app that can monitor the status of your Tasmota devices.

The easiest way to install it is with Docker, and it’s also available as a Home Assistant addon. You can also install it manually on an existing local web server with PHP available. Once installed, you’ll need to create a user account, and then you can start adding your devices by IP address.

Once all your devices are in there, you’ll get a nice list, with their IP address and their current version of the Tasmota firmware. You can then jump quickly into the standard Tasmota configuration for your device, but you can also configure many settings from within the TasmoAdmin interface. This includes things like the MQTT and Wi-Fi settings.

You can also use TasmoAdmin to perform bulk actions on multiple devices at once. For example, you can trigger backups or firmware updates in bulk. The ‘Start’ page in TasmoAdmin also lets you, for example, turn all of your switches on or off at once.

It’s a handy tool. Bear in mind that if you run TasmoAdmin as a Home Assistant addon, it doesn’t currently support ‘ingress’ and so you can’t open it within the Home Assistant interface. This also means that you might not be able to access the dashboard remotely. TasmoAdmin may also work with OpenBeken devices, but I haven’t tried this myself.

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.

Converting Tuya devices to Tasmota

by
Screenshot of the Tasmota web site

I’ve mentioned that I have a few Tuya smart plug sockets around the home. It’s possible to convert these to run on open source firmware called Tasmota, to gain some additional features, and it’s something I’ve been considering.

The logic boards for many Tuya devices are from the Espressif ESP family, which can easily be flashed with different firmware. Tasmota is one such provider, as is ESPHome which is a sister project to Home Assistant.

What’s wrong with Tuya?

Tuya mostly manufacture ‘white label’ devices that are then sold under a variety of brands. Mine are branded ‘Coosa’ but I’ve seen others called ‘Hey!’ being advertised. Often, they come with their own branded app, but you can use them with Tuya’s own app as well.

I bought them a few years ago because they work well with Google Assistant and IFTTT (which I no longer use). They also work well with Home Assistant (especially since last month). They don’t work with Apple HomeKit natively but can be bridged in using Home Assistant or Homebridge. The other advantage was that you didn’t need a separate hub for them to work – they connect directly to your home Wifi network.

However, Tuya is a Chinese company. Though they claim to have servers in the EU, it could be that every time I use their switches, my request goes via China. In Home Assistant, there are a couple of custom integrations in HACS called LocalTuya and TuyaLocal that can issue commands locally on your home network. But if you use Google Assistant, the commands get sent across the web.

Local control with Tasmota

The Tasmota project offers a tool called Tuya Convert, which replaces Tuya’s official firmware and allows for local control. It mainly uses the MQTT protocol, which is openly documented and used by a variety of different Internet of Things devices. Once flashed onto your devices, they can be controlled locally and don’t need to communicate with external servers. Home Assistant has extensive MQTT support and an official Tasmota integration.

They also work well with Alexa devices, by emulating a Belkin WeMo or Philips Hue device.

This all sounds good to me, but I haven’t gone ahead and done it. Unfortunately, whilst Amazon Alexa is supported, Tasmota doesn’t easily interact with Google Assistant. And once I’ve flashed a device with Tasmota, it may be difficult or impossible to go back to the official Tuya firmware.

Of course, I can configure Home Assistant to work with Google Assistant. I haven’t yet, even though there are two ways to do it:

  1. Sign up for Home Assistant Cloud from Nabu Casa, which costs £6.50 per month
  2. Set up Google Assistant manually with Home Assistant, which is lengthy and may need to be reconfigured every 30 days.

I suppose if we used Amazon Echo devices instead of Google Home, this would be a no-brainer.

In the long run, replacing these smart plugs with ones that use Matter would be better and cheaper. My Home Assistant install is pretty-much Matter ready, with no need for an additional hub. Matter, like Zigbee, mostly works locally, and therefore doesn’t have the privacy implications of my current web-based Tuya plugs.