Guide: ESPHome/ Tuya-Flash and integration into Home Assistant

Guide: ESPHome/ Tuya-Flash and integration into Home Assistant

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.
graph TD A[Home Assistant] --> B[ESPHome] B -->|Configuration file from ESPHome| C[ESP Chip] C -->|Send status eg. On/ Off | A

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;

  1. Raspberry Pi (recommended)
  2. Linux device like Ubuntu or Debian
  3. Possibly a Mac (untested)

Raspberry Pi

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.

Instruction Illustration
Install Git via terminal sudo apt install git -y
Change directory to your home directory. cd $home
Using git, clone the Tuya-Convert repo. git clone https://github.com/ct-Open-Source/tuya-convert
Once the clone has completed, change directory into the Tuya-Convert directory. cd tuya-convert
Next, you will need to install the prerequisites. sudo ./install_prereq.sh

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.

Steps:

Instruction Illustration
From inside ESPHome, click the green + button to start the wizard. Screenshot-from-2021-02-20-18-13-27
Type the name of the device you want to add. In this case i'll set fl052ha_flood_light as the name. Click Next Screenshot-from-2021-02-20-18-15-33
Here we will need to set a device type. We will leave it as default as Generic ESP8266 (for example Sonoff). Click Next Screenshot-from-2021-02-20-18-16-46
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. Screenshot-from-2021-02-20-18-18-09
Finally click on Submit. This will create a device configuration file ready for you to use. Click Edit Screenshot-2021-02-20-182658
You should now see the configuration file. Note that this is written in YAML. Screenshot-2021-02-20-182951

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 space.

Lets take a look at the configuration file. At its most simplest form, the configuration file can be easily read.

The esphome: section contributes the type of device ESPHome will be controlling. There is not too much here apart from the Platform and board. YOu can also add other parameter based on requirements if needed. Screenshot-2021-02-20-191403
The wifi: section is pretty straight forwards. This area is exactly the output as requested via the wizard interface. There are also additional parameters that can be used here. Screenshot-2021-02-20-191427
captive_portal: The captive portal component in ESPHome is a fallback mechanism for when connecting to the configured WiFi fails.

After 1 minute of unsuccessful WiFi connection attempts, the ESP will start a WiFi hotspot (with the credentials from your configuration).
Screenshot-2021-02-20-192126
logger: as the name suggests logs information from the ESP chip to ESPHome Screenshot-2021-02-20-192157
api: allows Home Assistant to succesfully connect via a API password and then operate the device. Screenshot-2021-02-20-192622
Finally ota: is for allowing ESPHome to flash the ESP chip over wifi with new config. If you ever need to make a change, or add some new logic you will use the OTA flash. Screenshot-2021-02-20-192724

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

Steps:

  • 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: sudo ./start_flash.sh
  • It is likely that the Raspberry Pi will request that you stop some services in order to process the work. Simply enter y for 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 waiting for a device to connect to the wifi and for you to enter pairing on the device your about to flash. 
  • Tuya-Convert will create a wireless network called vtrust-flash using 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.
Flashing the Alrec Spotlight
  • 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 firmware error, 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.
Backup of 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!
By default the above firmwares are built into the Tuya-Convert project for use. Add your own ESPHome .bin files into the ./tuya-convert/files directory. 
  • You will be presented with the final confirmation, at this stage it is the point of no return. You have been warned, enter Y and wait for the flash to finish.
Final point of no return.
  • 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