Tuya Convert OS

• Sad Note
• About
• Fair Warning
• Requirements
• Procedure
• Troubleshooting

---

Sad Note

😞 Starting from versions around mid 2020, Tuya firmware can no longer be upgraded using the method described in this document. You'll need to disassemble your device and use the USB To Serial Adapter method to flash the espQToggle firmware.

About

Tuya is a Chinese smart devices platform that offers cloud services for, among others, ESP8266/ESP8285-based devices. They supply their proprietary firmware that runs on these devices and connects them to the Tuya cloud.

Tuya Convert OS helps replacing this proprietary Tuya firmware with a custom firmware, without disassembling the device. Needless to say, Tuya Convert OS will only work for Tuya-based devices.

Tuya Convert OS is in fact a customized Raspbian OS image that runs Tuya Convert with a friendly user interface. Here are some screenshots, if you want to see it in action.

Fair Warning

⚠️ This procedure is not guaranteed to succeed. Moreover, if something goes wrong, you may be required to disassemble the device and use a USB-to-serial adapter to flash it from scratch.

⚠️ Be aware that you use this software at your own risk so none of the direct or indirect contributors to this tool can be held accountable for any damage done or loss of functionality.

Requirements

• a Raspberry Pi 3 or 4 board (any model)
• a micro SD card (any size above 2GB will do)

You could temporarily repurpose a Raspberry Pi board for Tuya conversion, as once the conversion is completed, you won't need this setup anymore. Swapping the SD card with a Tuya Convert OS one, when needed, should be enough.

Procedure

1. Download the Tuya Convert OS image from the latest release page.

2. Extract the compressed image.

3. Follow these instructions to write the OS image on your SD card.

4. Connect the Raspberry Pi to your local network, using an ethernet cable. Don't use your Wi-Fi network, as the Wi-Fi adapter will be used for the conversion.

5. Boot your Raspberry Pi with the freshly written SD card. Find its IP address using one of the following methods (the hostname you should be looking for is tuya-convert):

   • smart phone apps like Fing to scan your network
   • looking through your router's DHCP leases
   • an attached display will show the IP address
   • accessing tuya-convert.local may work on your local network

6. Point your favorite browser to http://ipaddress (http://tuya-convert.local may also work). If you're using your smartphone, make sure you're connected to your local Wi-Fi network. You should now see the web user interface.

7. Power the device by plugging it into an AC outlet or connecting it to mains. However, do not attempt to set it up using the Tuya Smart Home app or connect it to the network in any way.

8. Put your device into "pairing" mode. This mode is usually indicated by a blue blinking led. If the device does not automatically enter the pairing mode when powered, press and hold the device button for 5-10 seconds.

9. In the Tuya Convert OS user interface, press the Convert button. Wait until conversion completes. It should take around 1-2 minutes. In case of error, see Troubleshooting.

10. In the Tuya Convert OS user interface, press the Flash Firmware button and select the URL option.

11. Go to the latest release page and copy the link to the firmware.bin file corresponding to your device. Look for your device model on the Supported Devices page and make note of its flash parameters; use them to identify the firmware.bin you should be flashing. Paste the link into the URL input box from previous step. Make sure you choose the correct firmware. Flashing the wrong firmware may brick your device!

12. In the Tuya Convert OS user interface, leave the flash parameters as they are (they should be automatically detected) and press the Start Flash button. Wait until flashing completes. It should take less than a minute. In case of error, see Troubleshooting.

13. Disconnect your device from AC and reconnect it back. It should now run the espQToggle firmware. Follow the initial setup instructions to connect the device to Wi-Fi and add it to your qToggle system.

Troubleshooting

In case the conversion or the flashing process fails, here are a few ideas:

• Repeat the procedure a couple of times, as it may not succeed the first time.
• Ensure the device is powered.
• Ensure that the device is in pairing mode.
• Ensure that you only convert one device at a time.
• Connect a secondary USB Wi-Fi adapter to your Raspberry Pi and reboot it. This will ensure another client is connected to the temporary access point, facilitating packet broadcasting in some cases.

If the device simply cannot be converted, your only choice is to disassemble it, connect a a USB-to-serial adapter and follow the flashing procedure to install the firmware file.