[docs] Update ESPHome docs, add cloudcutter guide
This commit is contained in:
Kuba Szczodrzyński
@@ -65,8 +65,8 @@ NVS / Preferences | ❌ | ❌
|
||||
SPIFFS | ❌ | ❌
|
||||
BLE | - | ❌
|
||||
NTP | ❌ | ❌
|
||||
OTA | ✔️ | ❌
|
||||
MDNS | ✔️ | ❗
|
||||
OTA | ✔️ | ✔️
|
||||
MDNS | ✔️ | BK7231T only
|
||||
MQTT | ✅ | ❌
|
||||
SD | ❌ | ❌
|
||||
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
* Examples
|
||||
* [PinScan](examples/PinScan/README.md)
|
||||
* [ESPHome port](docs/projects/esphome.md)
|
||||
* [Using tuya-cloudcutter](docs/cloudcutter.md)
|
||||
* [💻 Boards & CPU list](docs/status/supported.md)
|
||||
* [✔️ Implementation status](docs/status/arduino.md)
|
||||
* Supported chip families
|
||||
|
||||
40
docs/cloudcutter.md
Normal file
40
docs/cloudcutter.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Flashing with tuya-cloudcutter
|
||||
|
||||
[`tuya-cloudcutter`](https://github.com/tuya-cloudcutter/tuya-cloudcutter) is a tool that disconnects IoT devices from the Tuya cloud, while also allowing **remote firmware flashing**. This means you can flash ESPHome without even connecting USB-UART to the device.
|
||||
|
||||
This is an unofficial guide, that worked for me during testing. The steps may not work for every device; you should also refer to the cloudcutter's manual pages.
|
||||
|
||||
**Currently, `tuya-cloudcutter` works for BK7231T and BK7231N only.**
|
||||
|
||||
If your device doesn't have a profile yet, it will probably not work. You can contribute by [taking a device dump](https://github.com/tuya-cloudcutter/tuya-cloudcutter#device-dumps) and posting it on cloudcutter's issues page.
|
||||
|
||||
## Instructions
|
||||
|
||||
### Preparation
|
||||
|
||||
1. Get a laptop (or a PC with Wi-Fi) with Linux and Docker installed. This was tested on Ubuntu 20.04, but you should be able to use another Debian-based distribution with NetworkManager.
|
||||
- To install Docker, run `sudo apt-get install docker.io`. When it completes, run `sudo adduser <your username> docker` and reboot the machine.
|
||||
- This was also successfully performed on a VirtualBox VM, with a USB Wi-Fi adapter redirected to the VM.
|
||||
2. Install `git`, if you haven't already (`sudo apt-get install git`).
|
||||
3. `git clone https://github.com/tuya-cloudcutter/tuya-cloudcutter`
|
||||
|
||||
### Firmware building
|
||||
|
||||
1. [Compile ESPHome](projects/esphome.md), or your custom firmware based on LibreTuya.
|
||||
2. Get the firmware binary, named `bk7231x_app.ota.ug.bin` from the build directory (`.pio/build/<board>/` or `.esphome/build/<board>/.pioenvs/<board>/`).
|
||||
3. Put the file to `custom-firmware` of tuya-cloudcutter.
|
||||
|
||||
### Pairing and flashing
|
||||
|
||||
1. Run `./run_flash.sh` from the cloudcutter directory.
|
||||
2. Answer questions about the desired firmware file, the device vendor and profile.
|
||||
3. Put the device to AP mode: (**)
|
||||
- Bulbs (devices without buttons) usually need to be power-cycled a few times, until they start blinking slowly.
|
||||
- Switches, plugs, relays (devices with buttons) usually enable AP after pressing the button for a few seconds.
|
||||
- If the device (bulb or switch LED) is blinking quickly (~2 times per second), do the procedure again.
|
||||
4. Cloudcutter will scan for APs, connect to the device and send a payload to it.
|
||||
5. The device will most likely hang (not respond). Reboot it again to AP mode (just like in step 9).
|
||||
6. Cloudcutter will scan for APs again, configure the device to talk to it, then begin the OTA update.
|
||||
7. After around 30 seconds, the device will boot new firmware 👏
|
||||
|
||||
\*\* Use a smartphone with the Wi-Fi screen open and scanning, so that you can see if AP mode got enabled.
|
||||
@@ -3,15 +3,26 @@
|
||||
!!! note
|
||||
Read [Getting started](../getting-started/README.md) first.
|
||||
|
||||
## 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)
|
||||
3. Go to [Boards & CPU list](https://kuba2k2.github.io/libretuya/docs/supported/), click on your board and remember your board code.
|
||||
4. 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
|
||||
|
||||
!!! 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](https://kuba2k2.github.io/libretuya/docs/supported/), 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:
|
||||
```yaml
|
||||
@@ -36,10 +47,44 @@ Assuming you have PlatformIO, git and Python installed:
|
||||
ssid: "Yourdevice Fallback Hotspot"
|
||||
password: "Dv2hZMGZRUvy"
|
||||
```
|
||||
5. Compile and upload ESPHome:
|
||||
- `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
|
||||
|
||||
## Configuration options
|
||||
|
||||
All options from [Options & config](../reference/config.md) can be customized in the `libretuya:` block:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
@@ -47,3 +92,5 @@ Assuming you have PlatformIO, git and Python installed:
|
||||
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`](../cloudcutter.md).
|
||||
|
||||
Reference in New Issue
Block a user