Tuya on Home Assistant
If you've spent any time browsing AliExpress for cheap smart devices you've probably come across Tuya devices, but what is Tuya, and how can you use them with Home Assistant in a private manner?
The definitive guide to Tuya on Home Assistant
If you've spent any time browsing AliExpress for cheap smart devices you've probably come across Tuya devices, but what is Tuya, and how can you use them with Home Assistant in a private manner?
Tuya is a Chinese company that produces software and services for the actual manufacturers. They provide a complete IoT platform that includes mobile apps, cloud services, and actual device firmware. They don't manufacture devices, but rather license their platform to companies ranging from nameless AliExpress products to well known brands, both inside and outside of China.
Device Types and Integrations
So let's have a look about the type of devices that Tuya supports, and different ways to integrate them into Home Assistant.
I got these two identical looking plugs from AliExpress, but one of them uses WiFi to talk directly to the Tuya cloud, while the other uses the Zigbee protocol which talks to some kind of hub. Normally that hub then talks to the Tuya cloud, but we can build our own hub and avoid the cloud entirely!
In this table I've laid out all the options.
First of all, the Zigbee devices get a perfect score on all accounts, since they work out of the box with the official Zigbee integration.
Next up is the official Tuya integration, which is easy to set up, well supported, but operates using the Tuya cloud and will not be discussed any further.
Next up are two nearly identical unofficial Tuya integrations that leave you at the mercy of Tuya to pair the devices and get its credentials, but work completely locally afterwards. I would recommend this option for name brand devices that you want to use in private without risk of damage.
Then we get to tuya-convert and tuya-cloudcutter which are methods to hijack the "over the air" update mechanism to load alternative firmware. These require running terminal commands and configuring your own firmware, and the exploits they use tend to get patched. If you get lucky to receive a device with an outdated firmware, this can be a pretty good option.
And finally there is serial flashing, which means taking the device apart, soldering wires to certain pads, and using a special adapter to upload new firmware. This will always work but is quite tedious and difficult and potentially even dangerous.
Local Tuya
So let's start with Tuya Local. I have this infrared heater in my bathroom by a Dutch company called Eurom that turns out to use Tuya behind the scenes. I don't really want to risk bricking this device with custom firmware, so Tuya Local seems the way to go. I tried both tuya-local and localtuya, and while localtuya has more Github stars, it seems like tuya-local has an easier installation procedure that doesn't require messing with the Tuya cloud console.
The first step is unfortunately to pair the device in the official Tuya app. To do that, install the Tuya Smart app, log in or create an account, put your device in pairing mode, and let the app discover and add it.
Next we need to install the tuya-local integration using HACS by pressing "Open HACS repository" in the readme. (Subscribe for when I get around to making a video about installing HACS) Once it opens in HACS, simply press Download in the bottom right corner, and then restart home assistant.
Then go to integrations and press "add integration" and search for Tuya Local. It will offer an advanced setup option where you manually pilfer the keys out of your device, but we'll pick the cloud assisted setup.
In the next step it will ask for an user code, which we need to obtain from the app by going to the "me" tab, the hexagon nut for settings, and then "Account and Security". Next go back to the "me" tab and press the scan icon to scan the QR code.
Then we'll actually need to configure the device itself, which should now have the device ID and local key prefilled, but you'll need to obtain the IP address from your router web interface if automatic discovery doesn't work.
Finally select the profile for your device, and give it a name, and then the device should have been added to Home Assistant.
Zigbee Home Automation
Now let's have a look at adding Tuya Zigbee devices to Home Assistant, which is really the same as adding any Zigbee device to Home Assistant since Zigbee is an open standard.
First of all you need a Zigbee dongle. In my setup I use a Raspberry Pi 4 with a Sonoff Zigbee dongle which works perfectly with the official Zigbee Home Automation integration.
Then it's as simple as adding or opening the Zigbee integration, selecting "devices" under your dongle, and then press "add device". Now you need to put your device in pairing mode, in this case by long-pressing the button, and then it will be automatically discovered and added. That's all.
OTA hacks
Next up let's look at the OTA methods. These two projects work by packaging an alternative firmware as a software update and tricking the device into installing it. This is an endless cat and mouse game between hackers and Tuya where every time a new exploit is discovered Tuya releases a fix so it no longer works.
The first one is tuya-convert which targets Espressif ESP chips. Their exploits started getting patched somewhere in 2019, and many newer Tuya devices no longer use the ESP family of chips.
The second one is tuya-cloudcutter which targets a family of Beken chips used in many newer Tuya devices. However, theirs exploits also started getting patched in 2022.
So until new exploits are discovered, these projects currently only work if you're lucky enough to receive a device with a severely outdated firmware. And the only way to find out is to try.
I'll skip over some of the details of the installation, but when I ran tuya-convert on my Tuya smart socket, it told me that the device was not an ESP chip.
Then I moved on to cloudcutter, which has a wiki page of known patched firmware versions. So I paired my socket with the official app, and sure enough my version matched one of the known patched ones.
Serial flashing
I hoped it wouldn't come to this, but since none of the OTA methods worked, the only option left to me was to open up the device to directly flash new firmware to it. It is in my opinion really not worth the hassle if you can instead buy a device with an officially supported local API, but it's definitely possible if you have the tools and skills. But whatever you do, NEVER plug in the device to mains power while its internals are all over your desk.
The process is not that complicated in theory, but just very tedious an error prone. It took me almost a whole day, and that is with an electrical engineering degree and expensive equipment.
Step one is to disassemble the device and take the PCB out. On the PCB you'll likely find a daughter board with a micro controller and a PCB antenna, which is the brains of the operation. Carefully inspect the micro controller to identify its model.
After many failed attempts, I took a hot air gun and completely removed the daughter board from the PCB. This allowed me to easily solder wires to the pads and avoid the main board interfering with serial communication.
Then you need to connect the board to your USB to serial adapter. You need to connect GND to GND, connect VCC to 3.3V, and then connect the serial pins. The TX pin of the adapter goes to the RX1 pin on the board, and the RX pin of the adapter goes to the TX1 pin on the board. There is also a CEN pin which we'll need to short to GND later.
Then you are in theory ready for flashing. After much experimentation and failure, I had the most success with the Beken GUI flash tool, once I set the right model and increased the UART timeouts slightly. Just press "do backup and flash new", touch the CEN pin to GND, and off you go. Hopefully.
The great thing about this tool is that not only will it backup the old firmware and flash OpenBeken, it will also extract the pinout from the backup. After it's done flashing it'll pop up this nice window with a description of what is connected to each pin of the daughter board.
Firmware configuration
Weather by OTA update or serial flashing, once you have uploaded custom firmware, it's now up to you to configure it correctly.
The first step is to connect to the access point that the device created. There you can go to "config" and then "Configure WiFi". Enter your WiFi credentials and hit submit.
After reconnecting to the device via your normal WiFi network, you can do two things. Either you can launch the OpenBeken web app and paste the extracted JSON there to automatically configure your device. Or you can use its OTA feature to install something else.
OpenBeken works fine and can integrate with Home Assistant through an MQTT broker, but since I'm already running several ESPHome devices, I went with that.
In your ESPHome dashboard, press "new device", pick a name, and select the correct module. Mine is a BK7231N device on a CB2S module.
The first time you install ESPHome firmware you'll have to select "manual download", but once it runs ESPHome you can update the firmware wirelessly. It'll take a while to compile, but once it's done you'll want to select the Beken OTA file format. However, if you try to upload that to OpenBeken it'll say you selected an invalid OTA file. To fix this simply change the filename to include the name of your chip. Then you can proceed to upload the firmware.
Last but not least, now you'll actually need to write an ESPHome configuration for your device. That's a bit beyond the scope of this video, but here is what I have added to mine. Unfortunately I haven't gotten the power monitor to work yet.
Conclusion
So that's it for this video. My take-away from all of this is that Zigbee devices are amazing, Tuya Local is tolerable if you have to, and flashing custom firmware is a huge can of worms that I would avoid unless I were looking for a fun challenge rather than a working smart device.
If you have enjoyed this video, consider subscribing, and if you have any questions or ideas, let me know in the comments.
More articles
