ESPHome
Tip
See the Cloudcutter video guide for a complete tutorial on flashing with Cloudcutter and installing LibreTiny-ESPHome. Includes Home Assistant Add-On setup.
Because ESPHome does not natively support running on non-ESP chips, you need to use a fork of the project.
There are three basic ways to install and use LibreTiny-ESPHome. You can choose the option that best suits you:
- ESPHome Dashboard (GUI) - for new users, might be an easy way to go; config management & compilation using web-based dashboard
- command line (CLI) - for more experienced users; compilation using CLI commands, somewhat easier to troubleshoot
- Home Assistant Add-On - using LibreTiny-ESPHome in Home Assistant, alongside your normal ESPHome installation - click the link for more info
Tip
You can use LibreTiny-ESPHome for ESP32/ESP8266 compilation as well - the forked version extends the base, and doesn't remove any existing features. Keep in mind that you might not have latest ESPHome updates until the fork gets updated (which usually happens at most every few weeks).
Find your device's board
Go to Boards & CPU list, find your board (chip model), click on it and remember the Board code
. This will be used later, during config creation.
If your board isn't listed, use one of the Generic boards, depending on the chip type of your device.
Download ESPHome
For this, you need Docker, Docker Compose and Python installed. After running the commands, you'll have a running ESPHome Dashboard interface that you can connect to.
- Open a terminal/cmd.exe.
-
Create a
docker-compose.yml
file in a directory of choice:docker-compose.ymlversion: "3" services: esphome: container_name: esphome-libretiny image: docker pull ghcr.io/libretiny-eu/libretiny-esphome-docker:latest volumes: - ./configs:/config:rw # (1)! - /etc/localtime:/etc/localtime:ro restart: always privileged: false network_mode: host
- You can change
./configs
to another path, in which your ESPHome configs will be stored.
- You can change
-
Start the container using
docker-compose up
. You should be able to open the GUI on http://localhost:6052/.
Important
Read Getting started first - most importantly, the first part about installation.
It is very important that you have the latest version of LibreTiny installed (not libretiny-esphome
- this is a different thing!) so that you don't face issues that are already resolved.
Assuming you have PlatformIO, git and Python installed:
- Open a terminal/cmd.exe, create
esphome
directory andcd
into it. git clone https://github.com/libretiny-eu/libretiny-esphome
cd
into the newly createdlibretiny-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
- Open the GUI on http://localhost:6052/ (or a different IP address if you're running on a Pi).
- Go through the wizard steps:
New Device
Continue
- enter name and WiFi details
- choose
LibreTiny
- choose the board that you found before
- select
Skip
- A new config file will be added. Press
Edit
and proceed to the next section.
- 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:
yourdevice.yml
esphome: name: yourdevice bk72xx: # adjust accordingly: bk72xx or rtl87xx board: cb2s # 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"
- use
Automatically generate config
Instead of adding components manually and writing everything from scratch, you can use UPK2ESPHome to generate a working config (for supported BK7231 devices only). If your device has a Cloudcutter profile, there's a high chance it can have a generated config.
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.
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
Close the config editor. Press the three dots icon and select Install
. Choose Manual download
and Modern format
. The firmware will be compiled and a UF2 file will be downloaded automatically.
The command python -m esphome compile yourdevice.yml
will compile ESPHome.
Now, 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 LibreTiny block:
bk72xx:
framework:
version: latest
lt_config:
LT_LOG_HEAP: 1
LT_UART_DEFAULT_PORT: 2
LT_UART_SILENT_ALL: 0
Additionally, few options have their dedicated keys:
bk72xx:
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