How To Use Tuya Convert On Raspberry Pi (Step-by-step Guide)

Looking to flash Tasmota, ESPHome or some other firmware on your Tuya device but not quite sure how to use it?

This guide will explain the steps to easily remove your device from the cloud!

Tuya Convert is written for Linux systems so you can of course run it on Linux systems such as Ubuntu. However this tutorial will focus on using it with the ubiquitous Raspberry Pi.

Table of Contents

1. Prerequisite
2. Connect to the Raspberry Pi
3. Update the system
4. Enable WiFi
5. Install Git
6. Install Tuya-Convert
7. Flashing Your Device
   1. Stop services
   2. Connect to the vtrust-flash
   3. Put your device in pairing mode
   4. Start flashing
   5. Firmware backup
   6. Choose your firmware
8. Conclusion

Prerequisite

First and foremost you will need a device to flash! Most Tuya devices are based on the ESP WiFi chip and are therefore compatible with Tuya Convert.

You can check the Blakadder Tasmota repository to see if your device is listed if you wanted to make sure. You can also see some devices that have been confirmed not to work due to using a different hardware.

I would also recommend using a Raspberry Pi running the latest version of Raspbian. Check out this article if you need to know how to install the operating system and access it over SSH.

Any Raspberry Pi should work so long as it has WiFi access and the WiFi adapter supports AP mode. The Raspberry Pi 3 and 4 have a built-in WiFi adapter which is compatible. You can add WiFi to the Raspberry Pi 2 using this dongle.

Disclaimer: this process is an exploit and has the potential to brick your device, therefore I accept no responsibility for any malfunctioning devices as a result for this tutorial. Proceed at your own risk.

Connect to the Raspberry Pi

If you are using your Raspberry Pi as a desktop machine then go ahead and open up a terminal window.

If you want to access your Raspberry Pi remotely, you will need to connect to it using SSH. However you must not use the WiFi adapter wlan0 as this is required for the Tuya Convert exploit. The easiest way is to plug the Raspberry Pi into an ethernet port, then follow the SSH section of this guide to connect.

Update the system

First we should make sure everything on the system is up to date by entering the following commands. If you are prompted for your password then go ahead and enter it. Don’t forget that you will not see the password characters!

sudo apt-get update

sudo apt-get upgrade

You may be prompted to perform some updates, simply enter ‘y’ and allow the updates to install. Once complete you will be returned to the command prompt.

Enable WiFi

If you already have your WiFi adapter setup and have been using it to access the network or internet, you can skip this step.

If you are usingOtherwise go ahead and enter the following command to enter the Raspberry Pi configuration menu.

sudo raspi-config

You will be presented with the configuration menu, go ahead and select network options. Note that if you are using a third party WiFi adapter, you may need to configure it manually first.

Next you need to select WiFi and enter your location and credentials.

Once done select finish and it will return you back to the command prompt. You may also need to unblock the WiFi by entering the following command.

rfkill unblock wifi

Install Git

Next we will need to install Git if you don’t already have it on your Pi (Raspbian Lite, for example). We will use Git to download and install Tuya Convert, so go ahead and enter the following command.

sudo apt-get install git

Install Tuya-Convert

Next, you will need to navigate to the location where you wish to install Tuya-Convert. If you are unsure then I would recommend the user home directory, you can navigate there by typing the following.

cd ~

Now we need to download Tuya-Convert by cloning the Git repository, simply enter the following command.

git clone https://github.com/ct-Open-Source/tuya-convert

Once the Tuya-Convert repository has been cloned to your machine, we need to install the prerequisites. There is an installation script provided that makes it very easy! Simply switch to the Tuya-Convert directory and run the script by typing the following commands.

cd tuya-convert

sudo ./install_prereq.sh

Flashing Your Device

Now that everything is installed, we can begin the flashing process. To start Tuya-Convert, simply type the following command whilst in the Tuya-Convert directory.

sudo ./start_flash.sh

Stop services

It is likely that your system will request that you stop some services in order for the process to work. Simply enter ‘y’ for each one and once the script has finished, everything will be restored.

If everything is successful, you will be presented with the 3 step Tuya-Convert instructions.

1. Connect any other device (a smartphone or something) to the WIFI vtrust-flash
   This step is IMPORTANT otherwise the smartconfig may not work!
2. Put your IoT device in autoconfig/smartconfig/pairing mode (LED will blink fast). This is usually done by pressing and holding the primary button of the device
   Make sure nothing else is plugged into your IoT device while attempting to flash.
3. Press ENTER to continue

Connect to the vtrust-flash

Tuya Convert will create a wireless access point called vtrust-flash using the Raspberry Pi WiFi adapter. In order for the exploit to work we need to connect a device to this access point.

It does not matter what device we use, so long as it will remain connected long enough to start the flashing process. The easiest way is to just connect a mobile phone.

Alternatively if you have an ESP device like the Wemos D1 Mini, you can use the DigiBlur Donor Device sketch for Arduino.

Put your device in pairing mode

Next we will need to put our Tuya device in to ‘EZ pairing mode.’ It is common for bulbs to be switched on-off-on-off-on in order to put them in EZ mode however this step is specific to your device, therefore you should consult the manual for your specific device.

Please note that the device must be in EZ pairing mode and not in AP mode. Some bulbs can take a moment to switch from being fully illuminated to quickly flashing to signify that they are in EZ pairing mode.

Start flashing

Now we are ready to flash! Press ENTER and Tuya-Convert will begin to look for the device.

Patience is key here, it can take a while. If the operation times out with the “Device did not appear with the intermediate firmware” error, just power cycle your device and repeat.

Firmware backup

Once your device has been successfully recognised, a backup of the existing firmware will be performed. It will take a moment to complete so perhaps go grab yourself a nice beverage.

Choose your firmware

Finally when completed you will be presented with the option for the firmware you wish to flash. You can choose any of the firmware options, but if you do not specifically want to install a different firmware then I would recommend starting with Tasmota.

If you want to flash a custom .bin file, you can put it in the /tuya-convert/files directory. Alternatively once you have flashed Tasmota, you can use the Tasmota interface to flash a new custom firmware over the air.

You will be presented with a final confirmation, at this stage it is the point of no return, you have been warned! Enter ‘y’ and wait for the flashing to complete.

Conclusion

Congratulations! You have now taken your Tuya device out of the cloud and successfully installed Tasmota.

Now you are ready to configure Tasmota, so head on over to the Tasmota configuration guide.

If you are unable to get the over the air method to work with your device, you can have a go at flashing it with a wired connection, assuming you can access the PCB.