diff --git a/README.md b/README.md index 9c913d9..5061aa6 100644 --- a/README.md +++ b/README.md @@ -65,8 +65,8 @@ NVS / Preferences | ❌ | ❌ SPIFFS | ❌ | ❌ BLE | - | ❌ NTP | ❌ | ❌ -OTA | ✔️ | ❌ -MDNS | ✔️ | ❗ +OTA | ✔️ | ✔️ +MDNS | ✔️ | BK7231T only MQTT | ✅ | ❌ SD | ❌ | ❌ diff --git a/SUMMARY.md b/SUMMARY.md index 8927186..393478c 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -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 diff --git a/docs/cloudcutter.md b/docs/cloudcutter.md new file mode 100644 index 0000000..d188db3 --- /dev/null +++ b/docs/cloudcutter.md @@ -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 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//` or `.esphome/build//.pioenvs//`). +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. diff --git a/docs/projects/esphome.md b/docs/projects/esphome.md index 7f8ac77..f3eb98f 100644 --- a/docs/projects/esphome.md +++ b/docs/projects/esphome.md @@ -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).