From a8f5c392c9baee1dd517cb0732b9d8471cfedcaa Mon Sep 17 00:00:00 2001 From: Cossid Date: Sat, 16 Dec 2023 10:09:47 -0600 Subject: [PATCH] Update ESPHome documentation --- docs/projects/esphome.md | 188 +++++++++++++++++++++++---------------- 1 file changed, 110 insertions(+), 78 deletions(-) diff --git a/docs/projects/esphome.md b/docs/projects/esphome.md index 1c5364acb..6d0ca23f4 100644 --- a/docs/projects/esphome.md +++ b/docs/projects/esphome.md @@ -1,18 +1,15 @@ # ESPHome !!! tip - See the [Cloudcutter video guide](https://www.youtube.com/watch?v=sSj8f-HCHQ0) for a complete tutorial on flashing with [Cloudcutter](https://github.com/tuya-cloudcutter/tuya-cloudcutter) and installing LibreTiny-ESPHome. **Includes Home Assistant Add-On setup.** + See the [Cloudcutter video guide](https://www.youtube.com/watch?v=sSj8f-HCHQ0) for a complete tutorial on flashing with [Cloudcutter](https://github.com/tuya-cloudcutter/tuya-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. +LibreTiny is now natively supported by ESPHome in versions 2023.9.0 and later. -There are three basic ways to install and use LibreTiny-ESPHome. You can choose the option that best suits you: +There are three basic ways to install and use 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](https://github.com/libretiny-eu/esphome-hass-addon/pkgs/container/libretiny-esphome-hassio) - 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). +- [Home Assistant Add-On] - using ESPHome in Home Assistant as an add-on ## Find your device's board @@ -24,89 +21,89 @@ If your board isn't listed, use one of the **Generic** boards, depending on the === "GUI" - 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. + 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. - 1. Open a terminal/cmd.exe. - 2. Create a `docker-compose.yml` file in a directory of choice: + 1. Open a terminal/cmd.exe. + 2. Create a `docker-compose.yml` file in a directory of choice: - ```yaml title="docker-compose.yml" - version: "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 - ``` + ```yaml title="docker-compose.yml" + version: "3" + services: + esphome: + container_name: esphome + image: docker pull ghcr.io/esphome/esphome:latest + volumes: + - ./configs:/config:rw # (1)! + - /etc/localtime:/etc/localtime:ro + restart: always + privileged: false + network_mode: host + ``` - 1. You can change `./configs` to another path, in which your ESPHome configs will be stored. - 3. Start the container using `docker-compose up`. You should be able to open the GUI on [http://localhost:6052/](http://localhost:6052/). - -=== "CLI" + 1. You can change `./configs` to another path, in which your ESPHome configs will be stored. - !!! important - Read [Getting started](../getting-started/README.md) first - most importantly, the first part about installation. + 3. Start the container using `docker-compose up`. You should be able to open the GUI on [http://localhost:6052/](http://localhost:6052/). - **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**. +=== "CLI" - Assuming you have PlatformIO, git and Python installed: + !!! important + Read [Getting started](../getting-started/README.md) first - most importantly, the first part about installation. - 1. Open a terminal/cmd.exe, create `esphome` directory and `cd` into it. - 2. `git clone https://github.com/libretiny-eu/libretiny-esphome` - 3. `cd` into the newly created `libretiny-esphome` directory. - 4. Check if it works by typing `python -m esphome` + Assuming you have PlatformIO, git and Python installed: - !!! tip - For Linux users (or if `python -m esphome` doesn't work for you): + 1. Open a terminal/cmd.exe + 2. `git clone https://github.com/esphome/esphome` + 3. `cd` into the newly created `esphome` directory. + 4. Check if it works by typing `python -m esphome` - - uninstall ESPHome first: `pip uninstall esphome` - - install the forked version: `pip install -e .` + !!! tip + You can alternately install ESPhome CLI using pip with `pip install esphome` ## Create your device config === "GUI" - 1. Open the GUI on [http://localhost:6052/](http://localhost:6052/) (or a different IP address if you're running on a Pi). - 2. Go through the wizard steps: - - `New Device` - - `Continue` - - enter name and WiFi details - - choose `LibreTiny` - - choose the board that you found before - - select `Skip` - 3. A new config file will be added. Press `Edit` and proceed to the next section. + 1. Open the GUI on [http://localhost:6052/](http://localhost:6052/) (or a different IP address if you're running on a Pi). + 2. Go through the wizard steps: + + - `New Device` + - `Continue` + - enter name and WiFi details (first time only) + - LibreTiny will not currently be listed as an option, choose any of the boards and you will overwrite them later + - select `Skip` + + 3. A new config file will be added. Press `Edit` and proceed to the next section. + 4. Delete the entire generated configuration and replace it with the example configuration below or one generated by [UPK2ESPHome](https://upk.libretiny.eu/) === "CLI" - 1. 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: - ```yaml title="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" - ``` + 1. 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: see Example configuration below + +## Example configuration + +```yaml title="yourdevice.yml" +esphome: + name: yourdevice + +bk72xx: # adjust accordingly: bk72xx or rtl87xx + board: cb2s # THIS IS YOUR BOARD CODE + framework: + version: latest + +logger: +api: +web_server: +captive_portal: +ota: + +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + ap: +``` ## Automatically generate config @@ -117,26 +114,26 @@ Instead of adding components manually and writing everything from scratch, you c Now, just like with standard ESPHome on ESP32/ESP8266, you need to add components for your device. Visit [ESPHome homepage](https://esphome.io/) 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`](https://esphome.io/components/web_server.html) and [`captive_portal`](https://esphome.io/components/captive_portal.html) components - **even in your first "empty" upload**. + It's highly recommended to **always** include the [`web_server`](https://esphome.io/components/web_server.html) and [`captive_portal`](https://esphome.io/components/captive_portal.html) 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. + 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 === "GUI" - 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. + 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. === "CLI" - The command `python -m esphome compile yourdevice.yml` will compile ESPHome. + The command `python -m esphome compile yourdevice.yml` will compile ESPHome. Now, refer to the [flashing guide](../flashing/esphome.md) 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. + This part is for advanced users. You'll probably be fine with the default options. All options from [Options & config](../dev/config.md) can be customized in the LibreTiny block: @@ -149,6 +146,7 @@ bk72xx: LT_UART_DEFAULT_PORT: 2 LT_UART_SILENT_ALL: 0 ``` + (this is only an example) Additionally, few options have their dedicated keys: @@ -166,4 +164,38 @@ bk72xx: # set to false if you want to attach a debugger gpio_recover: true ``` + (these values are defaults) + +## Advanced: Using development versions with ESPHome + +There are a two ways to use development versions of LibreTiny with ESPHome +`version` is a required field, and must match a specific format, it is recommended to use `"0.0.0"` for custom development +`source` must point to where your development version of LibreTiny resides. + +=== "Git" + +```yaml +bk72xx: + framework: + version: "0.0.0" + source: "github://libretiny-eu/libretiny" +``` + +Source can be post-fixed to modify branch or include open Pull Requests + +- Branch: add `@branch_name` (ex: `source: "github://libretiny-eu/libretiny@experimental_branch_name"`) +- Pull Requests: add `#pr_number` (ex: `source: "github://libretiny-eu/libretiny#1"`) + +Note: `https` sources are also fine if you are not using or cannot access github. + +=== "Local" + +Check out with git or download and extract a copy of LibreTiny to your local file system running ESPHome. + +```yaml +bk72xx: + framework: + version: "0.0.0" + source: "/local_path_to_libretiny" +```