libretiny/docs/projects/esphome.md

ESPHome

!!! important Read Getting started first.

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

Install 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:

1. Open a terminal/cmd.exe, create esphome directory and cd into it.
2. git clone https://github.com/kuba2k2/libretuya-esphome -b platform/libretuya (you need the platform/libretuya branch)

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

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

Create your device config

1. Go to Boards & CPU list, click on your board and remember your board code.
2. 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:
   • if your board isn't available in the wizard yet, use the manual YAML method below
   • 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"
     

Configuration 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)

Compile & upload

• python -m esphome compile yourdevice.yml - this will only compile the code
• python -m esphome upload yourdevice.yml - this will upload the previously compiled code
• python -m esphome run yourdevice.yml - this will compile and upload the code

!!! info If you want to flash manually:

The binary file, ready for uploading, will be in `.esphome/build/yourdevice/.pioenvs/yourdevice/`.

Refer to your board README to find appropriate flashing instructions.

Or [flash with `tuya-cloudcutter`](../getting-started/cloudcutter.md).