Posted on 9 Comments

#44: Over-the-Air Tasmota conversion with Tuya-Convert

This is part 2 of the mini-series “The definitive guide to Tuya Tasmota conversion”.

The easiest and safest way to convert a Tuya device to Tasmota is using Tuya-Convert.

This clever utility uses a security loophole to trick your Tuya device into thinking that it’s installing an updated version of itself, when in fact it’s replacing itself with Tasmota. This means you can do the conversion without any electrical connection to the device: you don’t need a serial connection, and you don’t need to open the case.

This is great because there’s no risk of electrocution and it can be safely done by anyone.

Resources

Parts required

  • Raspberry Pi which has both WiFi and Ethernet
  • Micro SD card
  • Ethernet cable
  • A device with WiFi such as a phone or tablet

Check module compatibility

To use Tuya-Convert, three things need to be true:

  1. Your Tuya device must use a module based on an Espressif ESP8266 / ESP8285 processor. This includes the TYWE1S, TYWE2S, TYWE2L, TYWE3S, TYWE3L, TYLC4, TYLC5, and TYWE5P modules. There is also an ESP32-based module called the TYWE3SE but I don’t think it can be converted with Tuya-Convert.
  2. The device must not have been updated to new Tuya firmware that closes the security hole required for Tuya-Convert to work. If you have a device you want to convert, do not allow it to connect to your WiFi or pair with the app before you do the conversion. That may cause it to do an update and lock you out.
  3. You must be able to put the device into “EZ Mode” manually. Usually this is done by holding down the primary power button for 5 seconds, but it can vary between devices. For devices like smart lights that don’t have a power button, it can sometimes be done by turning its power on, off, on, off, on and then waiting a few seconds.

If your device doesn’t meet these requirements, you can’t use Tuya-Convert and the rest of this tutorial isn’t any use to you. However, you may still be able to convert it using one of the other methods that I’ll show in the next two videos.

Sometimes manufacturers change from one type of Tuya module to another, without making any external changes to their product or the packaging. You can buy a device one day and it has an ESP8266-based Tuya module in it, and buy the same product a week later only to find it now has a Realtek-based Tuya module instead.

To be absolutely sure, you can open the product and check if the module is one of the ESP8266 or ESP8285 versions:

“EZ Mode” is one of the two possible methods that Tuya provide for pairing a device with their app and connecting it to your home network.

With EZ Mode, the device broadcasts a message asking if there is an existing network that it can connect to. Tuya-Convert listens for this broadcast and responds to it, allowing the device to connect to it.

The other mode is “AP Mode”, where the device starts its own WiFi network and then you need to connect to its network to configure it. Tuya-Convert doesn’t work with this mode.

Tuya themselves publish a brief explanation of these two methods in their developer documentation.

Set up Raspberry Pi

You can run Tuya-Convert in a docker container or on a laptop or PC if you prefer, but for this tutorial I’m going to do a clean setup on a Raspberry Pi. This has the advantage that you can set up everything you need on an SD card, run your Pi while doing the conversion, and then take the SD card out and store it safely for future use.

Next time you want to convert a Tuya device, you can find a handy Raspberry Pi, pop in the SD card, power it up, and in about a minute you’re ready to go.

Install Raspberry Pi OS

Download the official Raspberry Pi Imager software on your Mac, PC, or Linux machine, insert your SD card, and install the default Raspberry Pi Desktop. The process is very simple and there are instructions on the Raspberry Pi site.

Once the SD card is ready, plug it into your Raspberry Pi, use the Ethernet cable to connect your Pi to your network, and turn it on.

Note that you must use a cabled Ethernet connection. You can’t use WiFi to connect your Pi to the Internet because it needs to use its onboard WiFi hardware to create a special network for the Tuya device.

With your Raspberry Pi running and connected to your Ethernet network, open the “Terminal” program directly on the Pi or connect to it by SSH.

Set WiFi region

Configure your geographic region in Raspberry Pi OS so that it will use the correct WiFi frequencies.

Launch Raspi-Config:

sudo raspi-config

Go through the menus to select “Localisation Options“, then “WLAN Country“, then choose your country. Select “OK”, then “OK” again, then “Finish”, and let your Pi reboot.

Once it has finished rebooting, log back in.

Update Raspberry Pi OS

Make sure the operating system is fully up to date:

sudo apt update
sudo apt dist-upgrade

Raspberry Pi OS usually includes Git pre-installed, but just to make sure you can run this command. It’s safe to run even if Git is already installed:

sudo apt install git

Set up Tuya-Convert

In your home directory, download the latest version of Tuya-Convert, change into its directory, and then run the provided script to install the prerequisites:

cd ~
git clone https://github.com/ct-Open-Source/tuya-convert
cd tuya-convert
sudo ./install_prereq.sh

Running the script will take a few minutes. Once it has finished, your Pi will be fully set up to run Tuya-Convert. You don’t need to do any of the previous steps again. Each time you boot up your Pi, it will be ready to go.

Prepare for conversion

With all the software already installed by the previous steps, start Tuya-Convert on your Pi. If you’ve just completed the installation steps above, you will already be in the “tuya-convert” directory. This pair of commands makes sure you’re in the correct directory in case you set up your Pi previously and have logged in again:

cd ~/tuya-convert
sudo ./start_flash.sh

Tuya-Convert gives you step by step instructions as it runs.

It will start by asking you whether it should terminate dnsmasq and mosquitto. Say yes (“y”) to both questions.

Next it will come to a screen with 3 steps listed. At this point you need to have your phone or tablet handy.

When Tuya-Convert starts, it creates a WiFi network called “vtrust-flash”. Use your mobile phone or tablet to connect to this network, and use the password “flashmeifyoucan“.

Because the network doesn’t have Internet access, your phone or tablet may complain and say that it wants to switch back to your normal WiFi network. If necessary, tell it to stay on the vtrust-flash network.

Your setup should now look like this, with your Pi connected to the Internet via Ethernet and your phone or tablet connected to the Pi via WiFi:

Put your phone or tablet aside. It doesn’t do anything for the rest of the process: it’s only there so that there is always at least 1 device connected to the vtrust-flash network, to keep it active.

Your Pi should still be waiting patiently with the 3 steps listed in the terminal, and it’s now ready to convert as many devices as you want.

Run conversion

Plug in your Tuya device, and then put it into EZ Mode. Usually this is done by pressing the main “power” button on the device for at least 5 seconds, but some devices require you to turn its power on, off, on, off, on and then waiting a few seconds.

If your Tuya device has a status LED, it will then start flashing to indicate that it’s in EZ Mode.

In the terminal on the Pi, press ENTER to tell Tuya-Convert that you’re ready to proceed.

Tuya-Convert will then pair with your Tuya device, and take a backup of the existing firmware. It saves this backup on your Pi and you can use it later if you want to restore your Tuya device to its original factory setup, but don’t rely on that! After this point it’s best to assume that your device is never going back to its original setup.

You’re now faced with a list of options. The terminal will say:

Available options:
0) return to stock
1) flash espurna.bin
2) flash tasmota.bin
q) quit; do nothing
Please select 0-2:

You can bail out at this point by typing “q”, and your device will be left untouched.

This is the point of no return! To install Tasmota, press 2.

After all the setup that you’ve already done, actually flashing Tasmota to the Tuya device only takes about 9 seconds.

Congratulations! Your Tuya device now has Tasmota installed.

Tuya-Convert will now ask if you want to convert any more devices.

If you only had one device to convert, you can say “N” (or just press ENTER) and Tuya-Convert will exit. You’re now ready to follow the normal Tasmota setup and configure your device.

If you have more devices to convert, you can unplug the device you just converted, plug in your next device, put it into EZ Mode, and select “y” in the terminal. Repeat this cycle as many times as you like to convert all your devices.

Once you’ve finished converting devices, don’t forget to switch your phone or tablet back to your normal WiFi.

If you think you may want to convert more Tuya devices in future, shut down the Pi cleanly and then put the SD card aside. This saves you going through the long setup process of installing Raspberry Pi OS, Tuya-Convert, and all the required software. It will be ready to go next time you need it.

I keep my collection of SD cards in small envelopes, with the purpose of the SD card (including the username and password) written on the envelope. That saves me trying to remember what’s on each of my SD cards, or how to log into them.

Configure Tasmota on your device

Tuya-Convert installs a very basic Tasmota binary that will allow your device to connect to WiFi, but it may not be the specific Tasmota build that your device requires for its features to work.

Power up your device, and then follow the usual Tasmota setup process to connect your phone or tablet to its network. Then you can open its web interface, and if necessary you can install a different build of Tasmota that suits your device.

The best place to get information about specific devices is the Tasmota Device Templates Repository. Look up your device there to find out what Tasmota build you need to install, and how it should be configured.

Finally, if you’ve found Tuya-Convert to be useful, please consider supporting the project by making a small financial contribution. Links for that can be found on the Tuya-Convert page.

And if you’ve found this tutorial to be useful, please consider supporting SuperHouse. Thanks!

9 thoughts on “#44: Over-the-Air Tasmota conversion with Tuya-Convert

  1. Jonathan,

    Frankly, this could do with A Big finAle of how to control the Tasmota device by voice like through OK Google. ;))

    Whilst Im trying to minimize my network dependence on 3rd party internet services and convert my growing list of wifi “smart”It devices it seems that we need a way to convert a voice command to an mqtt setting which Tasmota supports.

    I’ve been taking a stepwise process of converting as many of my devices to open source as possible, so that I can progressively minimize my external dependencies. But ran up against a problem controlling Tasmota thru ok Google.

    I understand there was a service called gbridge but that was “discontinued” and have seen reference to various pathways thru home assistant and node-red.
    There is also a voice recognition possibility thru Mycroft?

    Do you have any thoughts on this?

    1. I use Alexa to control Tasmota by voice all the time. It’s surprisingly useful. People who watch my livestreams have probably seen me turn on my soldering iron by talking to it!

      I use this, and the same author makes a version for Google Home as well: https://flows.nodered.org/node/node-red-contrib-alexa-home-skill

  2. Hi Jon, thanks for all you do for the community. After years of watching your videos and dabbling around the edges we are going to do a renovation at home and I got a little small slice of the budget to do some home automation. Thanks for your videos with the focus on the Australian market, for a familiar accent and maybe I’ll run into you one day and buy you a coffee.

    1. BTW, firefox doesn’t seem to work with this page for adding comments.

  3. Hi Jonathan
    When are the next episodes getting uploaded ?
    Been hanging out with a number of Tuya devices pulled apart waiting to see how you will do it

    Cheers

  4. Read with great interest this posting. Grabbed a couple of Tuya devices from Amazon. I choose a “UseeLink Tuya WiFi Smart Power Strip Surge Protector” and a “Smart Power Strip, WiFi Surge Protector” with Yagala name on the front. They were nearly the same price, with good reason. When I got them out of the different looking boxes, I discovered they were the same part/model number SM-SO301, just with different brand labels on the top. Took one apart and was pleased to see a TYWE3S chip on the board! I started the conversion process on this part and it errored out with “Tuya patched the PSK vulnerability that we use to establish a connection.” Ok, helpful message, the github site they suggested ‘Collaboration-document-for-PSK-Identity-02’, looked pretty deep in the weeds for me, but many others have been looking at the issue. I didn’t open the other one and proceeded to try the conversion. The first time through it failed but I didn’t like the flashing light sequence, so I tried again and it took this time! I got this message “Flashed http://10.42.42.1/files/tasmota.bin successfully in 8339ms, rebooting..” and thought GREAT. But on reboot the power strip just started clicking the relays and nothing more, bricked. I took it apart and it too had a TYWE3S chip. Not a big problem but just wanted to share. Pretty clear Tuya doesn’t want their systems converted to Tasmota any longer and are willing to brick them.

  5. Update on previous post!!! Seems the clicking outlet is expected!! Just connect to the Tasmota SSID and config the home SSID info and it is back to working!

  6. Hello,
    It will be difficult to find Tuya lamps that can tolerate Tuya-convert because of Tuya’s countermeasures. Demolishing them first to see if they are still eligible is not without risk. Also, you only get one chance to enter your Wifi credentials correctly via OTA into Tasmota AP (double check).Sometimes the following trick helps : put the lamp in AP mode (search or trial and error how to do) so slow blinking starts (as opposed to EZ mode!) and now look for that Wifi network. Only 2 devices will use it, the Tuya device and the smartphone (or notebook). After a while you should see two MAC addresses: one for your computer/smartphone and one for your smart device. The smart device should say something like “Espressif” or “Espressif Inc.”. If it says something like “Tuya Smart Inc.” or “Hangzhou Aixiangji Technology”, or anything unrelated to “Espressif”, you have a Tuya device with a non-compatible WiFi MCU.
    Now the good news:
    Recently, LED colour bulbs with genuine pre-flashed ESPHome and therefore easy to convert to Tasmota have finally become available, with detailed documentation from the manufacturer itself, Kaufman Home Automation (www.kaufha.com).

    Greetings

  7. Unfortunately this method seems to work less and less. 🙁

    I have some genio/mirabella IOQ2569’s I did this successfully on a year ago, but recently bought some Alec PC399HA’s from B’nings that refuse to talk to tuya-convert. I’ve resorted to localtuya on HomeAssistant as I didn’t feel like tearing them open.

    Glen.

Leave a Reply to Trevor Cancel reply

Your email address will not be published. Required fields are marked *