From e99c6124e70bbe10378287151bee237f8c4d70c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kuba=20Szczodrzy=C5=84ski?= Date: Thu, 13 Jul 2023 21:19:04 +0200 Subject: [PATCH] [docs] Add video guide link, use ready Docker images --- SUMMARY.md | 5 +- docs/flashing/esphome.md | 5 +- docs/flashing/tools/cloudcutter.md | 3 + docs/getting-started/README.md | 3 + docs/projects/esphome.md | 89 ++++++++++++++++-------------- 5 files changed, 61 insertions(+), 44 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index 51d4179..d083323 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,9 +2,12 @@ * [](SUMMARY.md) * [😊 Getting started](docs/getting-started/README.md) * [➡️ Info on accessing GPIOs](docs/getting-started/gpio.md) +* [📺 Cloudcutter & HA video guide](https://www.youtube.com/watch?v=sSj8f-HCHQ0) * [💡 ESPHome setup guide](docs/projects/esphome.md) +* [🛖 ESPHome Home Assistant Add-On](https://github.com/libretiny-eu/esphome-hass-addon/pkgs/container/libretiny-esphome-hassio) +* [](SUMMARY.md) * [📲 Flashing/dumping guide](docs/flashing/) -* [🔌 How to connect the chip in download mode?](docs/flashing/chip-connection/) +* [🔌 How to flash/enter download mode?](docs/flashing/chip-connection/) * [💻 Supported chips](docs/status/supported.md) * [All boards](boards/) * [](SUMMARY.md) diff --git a/docs/flashing/esphome.md b/docs/flashing/esphome.md index d4958fa..d50494a 100644 --- a/docs/flashing/esphome.md +++ b/docs/flashing/esphome.md @@ -1,5 +1,8 @@ # Flashing 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](../projects/esphome.md). **Includes Home Assistant Add-On setup.** + ESPHome can be flashed in few different ways, depending on your needs. !!! abstract @@ -30,7 +33,7 @@ ESPHome can be flashed in few different ways, depending on your needs. The built-in flasher is not yet available in the GUI. Here are your options: - OTA, using the downloaded UF2 file (if you're already running ESPHome) - - wired (also UF2), using ltchiptool + - wired (also UF2), using [ltchiptool](tools/ltchiptool.md) - wirelessly, using tuya-cloudcutter Read below for more details on each of these methods. diff --git a/docs/flashing/tools/cloudcutter.md b/docs/flashing/tools/cloudcutter.md index 3e1ae56..a7108e7 100644 --- a/docs/flashing/tools/cloudcutter.md +++ b/docs/flashing/tools/cloudcutter.md @@ -1,5 +1,8 @@ # Converting with tuya-cloudcutter +!!! 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](../../projects/esphome.md). **Includes Home Assistant Add-On setup.** + !!! note This currently applies to BK7231T and BK7231N only. `tuya-cloudcutter` can't be used for other chips. diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index ce21485..113d413 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -5,6 +5,9 @@ Using LibreTiny is simple, just like every other PlatformIO development platform 1. [Install PlatformIO](https://platformio.org/platformio-ide) 2. `platformio platform install -f https://github.com/kuba2k2/libretiny` +!!! 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](../projects/esphome.md). **Includes Home Assistant Add-On setup.** + ## Board selection - Go to [Boards & CPU list](../status/supported.md). diff --git a/docs/projects/esphome.md b/docs/projects/esphome.md index c1fab89..61f3f08 100644 --- a/docs/projects/esphome.md +++ b/docs/projects/esphome.md @@ -1,11 +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.** + Because ESPHome does not natively support running on non-ESP chips, you need to use a fork of the project. -There are two 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 LibreTiny-ESPHome. You can choose the option that best suits you: -- command line (CLI) - for more experienced users; compilation using CLI commands, somewhat easier to troubleshoot - 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). @@ -18,6 +22,30 @@ If your board isn't listed, use one of the **Generic** boards, depending on the ## Download ESPHome +=== "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. + + 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 + ``` + + 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" !!! important @@ -38,34 +66,19 @@ If your board isn't listed, use one of the **Generic** boards, depending on the - uninstall ESPHome first: `pip uninstall esphome` - install the forked version: `pip install -e .` +## Create your device config + === "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. - - 1. `git clone https://github.com/kuba2k2/libretiny-esphome` (or download the .ZIP and unpack it, not recommended) - 2. Open a terminal/cmd.exe in the cloned directory (`libretiny-esphome`). - 3. `python docker/build.py --tag libretiny --arch amd64 --build-type docker build` - this will build the Docker image of ESPHome. Change `amd64` to something else if you're using a Raspberry Pi. - 4. Create a `docker-compose.yml` file in the same directory: - - ```yaml title="docker-compose.yml" - version: "3" - services: - esphome: - container_name: esphome-libretiny - image: esphome/esphome-amd64:libretiny # (2)! - 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. - 2. Ensure the architecture (`amd64`) matches the one you selected in step 3. - 5. Start the container - `docker-compose up`. You should be able to open the GUI on [http://localhost:6052/](http://localhost:6052/). - -## Create your device config + 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. === "CLI" @@ -95,17 +108,9 @@ If your board isn't listed, use one of the **Generic** boards, depending on the password: "Dv2hZMGZRUvy" ``` -=== "GUI" +## Automatically generate config - 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. +Instead of adding components manually and writing everything from scratch, you can use [UPK2ESPHome](https://upk.libretiny.eu/) 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 @@ -118,14 +123,14 @@ Now, just like with standard ESPHome on ESP32/ESP8266, you need to add component ## Build & upload -=== "CLI" - - The command `python -m esphome compile yourdevice.yml` will compile ESPHome. - === "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. +=== "CLI" + + 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