Safety first. Many Tuya devices (plugs, wall switches, bulbs, relays) run on mains voltage. Never open a device or attach a serial adapter while it is plugged in or wired to mains. Power it only from your USB-serial adapter's 3.3 V during flashing. If you are not qualified to work on mains devices, choose a local-control option instead. Flashing can also brick the device and voids warranties.
Step 1: identify the chip
Old guides assume an ESP8266. Most current Tuya Wi-Fi products use other chips. Find the module name (printed on the module or visible in teardown photos and device databases):
Module-to-chip mappings below are common examples; confirm your exact module in a device database before flashing.
| Module family (examples) | Chip | Options |
|---|---|---|
| older ESP-based modules (e.g. TYWE3S) | ESP8266 / ESP8285 | Tasmota, ESPHome, tuya-convert only if the firmware is unpatched |
| WB2S, WB3S, WB3L | Beken BK7231T | tuya-cloudcutter (unpatched firmware), OpenBeken, ESPHome via LibreTiny |
| CB2S, CB3S, CB3L, CBU | Beken BK7231N | same as above |
| WR-series | Realtek RTL87xx | LibreTiny / ESPHome, OpenBeken, some supported by cloudcutter |
Step 2: choose a tool
- tuya-convert (over-the-air, no soldering): only for ESP82xx devices and only with unpatched firmware. Tuya patched it long ago and many devices ship patched; the project says there is no workaround for those.
- tuya-cloudcutter (over-the-air): for BK7231T/N and some Realtek devices. It either detaches the device from the cloud or flashes custom firmware. It does not work on firmware built against Tuya's SDK patched as of February 2022; check its list of known patched firmware. Afterwards you can't use Tuya's apps and servers.
- Serial (UART) flashing: works regardless of Tuya firmware version, but means opening the device and connecting to the module's pins. Tools: the OpenBeken easy-flash tool,
ltchiptoolfor LibreTiny.
Step 3: choose the firmware
- OpenBeken: Tasmota-like, runs on BK7231T/N and many other chips, MQTT with Home Assistant discovery, OTA updates after the first flash.
- ESPHome via LibreTiny: if you already use ESPHome; supports BK72xx, RTL87xx and LN882x, but support is still in development, so some components may be missing.
Before you flash
- Back up the original firmware if your tool supports it.
- Look up your exact device in the OpenBeken or LibreTiny/ESPHome device databases for pin mappings.
- Expect to lose Tuya app access permanently. If you want to keep the app, use local control instead.