This guide was written to cover how to succesfully flash ESPHome onto a Tuya device, build the required configuration file which then is used in ESPHome. Then program the default functionality for Home Assistant to use.
This guide assumes that the reader has already configured the following:
- Home Assistant (Supervised) for more information on installation see here.
- Tuya-Convert setup and running on a device that has a wifi card supported/ enabled.
- ESPHome or ESPHome(Dev) is installed. This can be installed via the Supervisor section of Home Assistant (Supervisor).
What does this guide cover?
- Understanding ESPHome and creating a configuration file for a device.
- Setting up and Understanding Tuya-Convert on a Raspberry Pi.
- Understanding the available resources to reference a close/ accurate configration within ESPHome.
- Understanding the concepts around the ESP chips and how Tuya fits into the picture.
What is ESPHome?
ESPHome is a system which controls a microchip that has a full wifi network stack and microcontroller. ESPHome sends simple communication via powerful configuration files which tells the chip to execute an output like turning on or off a relay.
This chip is generally refered to as an ESP chip and is made by Espressif Systems*. ESP chips come in many different sizes and varients. Most notably there are three version of the chip that are most commonly used. The ESP8266, ESP32 and the TYWES2 (Tuya based) which is a varient of the ESP8266.
As a general rule of thumb, most devices run on the TYWES2 platform as the TYWES2 was designed as a type of industrial/ commercial version of the ESP32 or ESP8266.
More information about ESPhome can be found here.
The Tuya-Convert Project
The Tuya-Convert project provides users with an ability to re-flash ESP chips with custom firmware like ESPHome. Tuya-Convert is the only solution at the time of writing which will see most devices and allow the flash to take place. There are still scenarios where Tuya-Convert will not work with some devices and unfortunatley flashing via serial is then potneitally required.
Flashing via serial will be covered in a post soon.
More information Tuya-Convert can be found here.
Getting Ready to flash ESPHome to a device
There are 3 methods to flashing ESPHome using Tuya-Convert;
- Raspberry Pi (recommended)
- Linux device like Ubuntu or Debian
- Possibly a Mac (untested)
I have had the best outcome by using a Raspberry Pi. This has nearly always worked for me and I have never had any problems. I have attempted to also use Ubuntu 20.10 LTS however I had run into issues where some wireless cards will not go into AP mode.
The following steps below assumes that the Raspberry Pi has been setup using the Raspberry Pi OS with desktop or Raspberry Pi OS Lite.
|Install Git via terminal||
|Change directory to your home directory.||
|Using git, clone the
|Once the clone has completed, change directory into the
|Next, you will need to install the prerequisites.||
We next need to prep our ESPHome configuration file. It is ALWAYS recomended to create a minimal configuration file to push to the device you are flashing. Once you get the firmware onto the device, you can always reflash over the air (OTA).
Creating the basic ESPHome Configuration File
The configuration file is created from with ESPHome which is running inside Home Assistant. The user will need to do some prior reasearch about the device they are flashing to determine which chip type is suitable to specify within the ESPHome configuration file. Generally googling the device with ESPHome in the search should show some results and also referencing the ESPHome website here.
The following steps below will assume that the user is flashing a Arlec Security Flood Light. It was found that this spotlight is running on the ESP8266 platform with a possible board type of ESP01_1m. The information was located on searching google and here. Try to match the board type as close as you can if possible. In some cases where information is not great, your best guess and/or if you able to see the chip will help.
Prior to making any changes to the device determine the full amount of features of the device. Using the example above I know I can turn the spotlight on and off but also control how bright the spotlight is as well.
|From inside ESPHome, click the green
|Type the name of the device you want to add. In this case i'll set fl052ha_flood_light as the name. Click
|Here we will need to set a device type. We will leave it as default as
|Next, we will need to enter in our Wifi SSID, and also provide a connection password to perform Over the Air updates via ESPHome. Enter these details in as per your setup.|
|Finally click on Submit. This will create a device configuration file ready for you to use. Click
|You should now see the configuration file. Note that this is written in
ESPHome Configuration File
esphome: name: fl052ha_flood_light platform: ESP8266 board: esp01_1m wifi: ssid: "Wifi SSID" password: "Password" # Enable fallback hotspot (captive portal) in case wifi connection fails ap: ssid: "Fl052Ha Flood Light" password: "password" captive_portal: # Enable logging logger: # Enable Home Assistant API api: password: "Password" ota: password: "Password"
The ESPHome configuration file is written in
yaml. This is important to remember as indentations you create must not be created by using
tab but instead using
Lets take a look at the configuration file. At its most simplest form, the configuration file can be easily read.
After 1 minute of unsuccessful WiFi connection attempts, the ESP will start a WiFi hotspot (with the credentials from your configuration).
There are many more things that can be specified in the configuration file, however its always best to start small and then add once you have your device successfully flashed.
If you would like to see what other parameters that can be added to this configuration file see here.
Flashing the Device
- Ensure that you have changed your directory into the Tuya-Convert Folder. It should still be in this directory from the previous steps above.
- To start the Tuya-Convert flash process, run the following command:
- It is likely that the Raspberry Pi will request that you stop some services in order to process the work. Simply enter
yfor each one and once the script has finished everything will be restored.
- If everything is succesful, you will be presented with the 3 step Tuya-Convert instructions.
- Tuya-Convert will create a wireless network called
vtrust-flashusing the wifi adapter. In order for the exploit to work we need to connect an additional device to this access point. I generally just used my android phone. Any device can connect just as long as it remains connect to the wifi network long enough to start the live flashing process.
- Put the device (Arlec Spotlight) into flash mode. Generally for lighting devices, powering them on/ off 3 times will put it into flashing mode.
- Starting the flash: Once you have a phone connected to the wifi and have the device into flashing mode hit
enter. This will now begin the flash process on the device.
- It is important that you do not get impatient. This can sometimes take a little while to process. The main thing is that you do not touch anything. If the operation times out with the
Device did not appear with the intermediate firmwareerror, just power cycle the device and repeat.
- Sometime you can also come across devices that cannot be flashed. Some Tuya devices have recieved a recent update which is refered to by the ESPHome community as the new
PSK format. Further information can be found here. Devices running this version of the Tuya firmware cannot be flashed via this method, and must be flashed via serial.
- Firmware Backup: Once the device has sucesfully communicated and been recognised, a backup of the original firmware can be captured. It will take a moment while it pulls this original firmware.
- Choose your Firmware: You should now see the devices firmware-xyz.bin file show in the list. This is the file we created earlier inside ESPHome, and copied to the files directory. Make sure you select the corresponding number to flash that firmware. Ensure you press the correct one!
- You will be presented with the final confirmation, at this stage it is the point of no return. You have been warned, enter
Yand wait for the flash to finish.
- If everything is succesfull, you have taken the device off the Tuya cloud and onto your own internal cloud via Home Assistant.
Bringing the ESPHome flashed device into Home Assistant
WIP: MORE TO COME SOON. 20/02/2021