ESPHome

!!! important Read Getting started first - most importantly, the first part about installation.

**It is very important that you have the latest version of LibreTuya installed** (not `libretuya-esphome` - this is a different thing!) **so that you don't face issues that are already resolved**.

Download ESPHome

Because ESPHome does not natively support running on non-ESP chips, you need to use a fork of the project.

Assuming you have PlatformIO, git and Python installed:

Open a terminal/cmd.exe, create esphome directory and cd into it.
git clone https://github.com/kuba2k2/libretuya-esphome
cd into the newly created libretuya-esphome directory.
Check if it works by typing python -m esphome

!!! tip For Linux users (or if python -m esphome doesn't work for you):

- uninstall ESPHome first: `pip uninstall esphome`
- install the forked version: `pip install -e .`

Create your device config

Go to Boards & CPU list, click on your board and remember the Board code.

Create a YAML config file for your device. You can either:

use python -m esphome wizard yourdevice.yml - type answers to the six questions the wizard asks, OR:

write a config file manually:

esphome:
  name: yourdevice

libretuya:
  board: wr3  # THIS IS YOUR BOARD CODE
  framework:
  	version: latest

logger:
api:
  password: ""
ota:
  password: ""

wifi:
  ssid: "YourWiFiSSID"
  password: "SecretPa$$w0rd"
  ap:
    ssid: "Yourdevice Fallback Hotspot"
    password: "Dv2hZMGZRUvy"

Add components

Now, just like with standard ESPHome on ESP32/ESP8266, you need to add components for your device. Visit ESPHome homepage to learn about YAML configuration. If you want, you can upload an "empty" config first, and add actual components later.

!!! danger "Important" It's highly recommended to always include the web_server and captive_portal components - even in your first "empty" upload.

Adding these two components will safeguard you against accidentally soft-bricking the device, by e.g. entering invalid Wi-Fi credentials. The Web Server provides an easy way to flash a new image over-the-air, and the Captive Portal allows to easily open the Web Server on a fallback AP.

Build & upload

The command python -m esphome compile yourdevice.yml will compile ESPHome.

You probably want to refer to the flashing guide to learn how to upload ESPHome to your device. There's also info on using tuya-cloudcutter in that guide.

Advanced: LT configuration

!!! note This part is for advanced users. You'll probably be fine with the default options.

All options from Options & config can be customized in the libretuya: block:

libretuya:
  framework:
    version: latest
  lt_config:
    LT_LOG_HEAP: 1
	LT_UART_DEFAULT_PORT: 2
	LT_UART_SILENT_ALL: 0

(this is only an example)

Additionally, few options have their dedicated keys:

libretuya:
  framework:
    version: latest
  # verbose/trace/debug/info/warn/error/fatal
  loglevel: warn
  # suppress chip's SDK log messages
  # (same as LT_UART_SILENT_ALL above)
  sdk_silent: true
  # disable SWD/JTAG so that all GPIOs can be used
  # set to false if you want to attach a debugger
  gpio_recover: true

(these values are defaults)

3.5 KiB Raw Blame History