What is Tuya Cloud Cutter?

Tuya Cloud Cutter is a software tool/method developed by tjclement, notkmhn, kuba2k2, troy-f and Cossid that allows individuals to flash alternative firmware onto Tuya-based smart devices.

Tuya Cloud Cutter gained attention in the DIY smart home community because it enabled users to take control of their Tuya-compatible devices by replacing the manufacturer’s firmware with custom firmware like Tasmota or ESPHome.

This allowed for greater flexibility and control over how these devices functioned, potentially removing any cloud-dependency and privacy concerns associated with the manufacturer’s default firmware.

What devices suport Tuya Cloud Cutter?

As of now the grand majority of Tuya devices can be taken off the cloud with Tuya Cloud cloud cutter.

Devices that have a variant of the cip bk7231 can be jailbroken.

But there is a catch here: if the device has a firmware that is newer then February 2022 it may not be compatible with the exploit.

But you may be still able to flash the device via USB to Serial.

Tuya Cloud Cutter Device list

A list of devices that support Tuya Cloud Cutter can be found here.

How to use Tuya Cloud Cutter

First you need to have a Ubuntu 22.04 installed on your machine and a WIFI adapter.

Im using a cheap USB WIFI adapter from Tplink that has the cip Realtek RTL8188EU. This cip model is used by a lot of networking enthusiasts because it support AP mode.

Also if you have a Raspberry Pi this will work also on Raspberry Pi Os

Now we need to install the Network Manager package (in theory it should be preinstalled on Ubuntu)

Open a Terminal window and type.

sudo apt update && sudo apt install network-manager

And edit this file /etc/dhcpcd.conf with the command below.

sudo nano /etc/dhcpcd.conf

After the file is opened in Nano, add the line: denyinterfaces wlan0 save the file by Pressing CTRL+O hit Enter then CTRL+X and hit Enter.

Now edit the NetworkManager.conf file with the command.

[main]
plugins=ifupdown,keyfile
dhcp=internal

[ifupdown]
managed=true

Save the file by Pressing CTRL+O hit Enter then CTRL+X and hit Enter.

Now reboot your system with the command: sudo reboot

Tuya Cloud Cutter runs inside Docker, so we need to install Docker in order to be able to run the script.

To install Docker use the following command.

curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh

Now pull the latest Tuya-cloud cutter repo.

git clone https://github.com/tuya-cloudcutter/tuya-cloudcutter

Now everything should be set and ready, now the last thing to do is to run the exploit.

First CD into tuya-cloud cutter (the folder)

cd tuya-cloudcutter

And to start the script use:

sudo ./tuya-cloudcutter.sh -r

Docker will start building the container then it loads the exploid.

Now use the following options in the script:

• Select the option number 2: Flash 3rd Party Firmware
• Select Manufacturer/Device name if your device is listed here or select Firmware version (i will advise to use Firmware version first, that you can check in the Tuya app at the device settings window)
• Now choose the ESPHome-Kickstart firmware
• Now confirm any changes requested by the script by typing „Y” then hitting Enter on your keyboard
• The next part is making the device to enter Slow Blinking Mode. First host the pairing button for a few seconds (if there is one) then after the device start blinking fast hold it again. If you have a light bulb, turn the light bulb on/off 3 times after de devices stars to blink fast turn the light bulb on/off again 3 to 4 times.
• Now an AP should be discovered and the exploiting process will start
• In the end you should see a message that says „Flashing should be complete” and a device mac address.
• Now wait a few seconds and try to scan for a new WIFI AP called something like: Kickstart-bk7231
• Connect to it and enter the IP 192.168.4.1 in the browser. Now you should see the ESPhome Server

Now the device has flashed on it a custom ESPhome firmware.

But in order to get all the functionality from it, you need a configuration file that maps out the correct PIN layout of the board and here respective functions.

Do to this we need a tool for Windows called ltchiptool that you can get it from here.

Open it and Click UPK2ESPHome and after that click Grab from EspHome-Kickstart enter the IP of the ESP-Kickstart 192.168.4.1 and hit Ok.

A config file will be generated, copy the configuration file and head over to Home Assistant.

Add the repository for the custom ESPHome Addon for Home Assistant.

Right now Libretiny (the board for Tuya Based devices) is not officialy suported by ESPHome, so we need this custom addon.

Head over to this URL https://github.com/libretiny-eu/esphome-hass-addon and click the blue Add Repository button in order to Add the Addon in Home Assistant.

You need Home Assistant OS or Home Assistant Supervised for this to work

Now go Settings în Home Assistant, then click on Addons then click the Blue Add-on Store Button and scroll down and you will se LibreTiny ESPHome click on it then Install.

After the installation is completed, start the Addon and make sure Start on boot, Watchdog, Auto update and Show in sidebar is enabled.

Now click on Open Web Ui and click the green New device button from the button right corner.

Click Continue and type a device name click Next then select the device type as LibreTiny then select the LibreTiny board that you will find in the config generated by ltchiptool click Next and after that click Skip on the next prompt.

Now Edit the newly created device and paste the .yaml configuration generated by ltchiptool.

In the Yaml configuration file make sure to:

• define a static IP of the device see here
• define the WIFI secret password and AP name
• write also the line web_server:
• also setup a WIFI AP
• and where it says in the config: libretiny: delete all that and add the code as follows

See an example configuration here: https://github.com/dany547/PMI-wp800-plug-esphome

bk72xx: #this will be your board name and chip family
  board: generic-bk7231t-qfn32-tuya
  framework:
    version: dev

Done! Now Save the config and click the Install button on the top right corner and select Manual download.

After the files is compiled, download it to your PC then acces your devices IP and flash the new configuration file.

The device will restart and should show up as Online in the Addon.

That’s basically it, if you have questions or if you having difficulties let me know in the comment section below.

Now i will list some common issues that you may have and how to solve them.

The ESPHome device shows offline

First make sure to assign a static IP to the device in your router control panel. Then define the IP in the configuration file. After installing the new config on the device, it should appare in the LibreTiny ESPHome addon.

If the device is still not showing up and cannot connect to its logs. Open the log and see if you can spot a local DNS address. Something like: yourdevice.local you need to assign the IP address of the device to that specific local address.