From b8eee999e23b2235224d449e50216a79db341048 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kuba=20Szczodrzy=C5=84ski?= Date: Thu, 15 Sep 2022 11:47:25 +0200 Subject: [PATCH] [docs] Add remaining config options, add warning about latest version --- SUMMARY.md | 3 ++- docs/getting-started/README.md | 2 +- docs/getting-started/adr.md | 18 ++++++++++++++++++ docs/{ => getting-started}/cloudcutter.md | 2 +- docs/getting-started/uploading.md | 2 ++ docs/ota/flashing.md | 7 +++---- docs/platform/beken-72xx/dumping.md | 6 +++++- docs/platform/beken-72xx/flashing.md | 3 +++ docs/projects/esphome.md | 6 ++++-- docs/reference/config.md | 10 ++++++---- 10 files changed, 45 insertions(+), 14 deletions(-) create mode 100644 docs/getting-started/adr.md rename docs/{ => getting-started}/cloudcutter.md (96%) diff --git a/SUMMARY.md b/SUMMARY.md index 59018e9..5346c12 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -6,7 +6,8 @@ * Examples * [PinScan](examples/PinScan/README.md) * [ESPHome port](docs/projects/esphome.md) - * [Using tuya-cloudcutter](docs/cloudcutter.md) + * [Using tuya-cloudcutter](docs/getting-started/cloudcutter.md) + * [Auto-download-reboot](docs/getting-started/adr.md) * [💻 Boards & CPU list](docs/status/supported.md) * [✔️ Implementation status](docs/status/arduino.md) * Supported chip families diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 442768c..d3f4e9c 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -3,7 +3,7 @@ Using LibreTuya is simple, just like every other PlatformIO development platform. 1. [Install PlatformIO](https://platformio.org/platformio-ide) -2. `platformio platform install https://github.com/kuba2k2/libretuya` +2. `platformio platform install -f https://github.com/kuba2k2/libretuya` ## Board selection diff --git a/docs/getting-started/adr.md b/docs/getting-started/adr.md new file mode 100644 index 0000000..8ae6a7e --- /dev/null +++ b/docs/getting-started/adr.md @@ -0,0 +1,18 @@ +# Auto-download-reboot + +*(CEN-less uploading)* + +This feature allows to upload code using UART, without needing to ground the CEN wire or power-cycle the device. + +It is enabled by default (using the `LT_AUTO_DOWNLOAD_REBOOT` option). It works by listening to incoming UART data, and checking if it matches a command that the flashing program would send. If it does, a chip reboot is performed and the uploading process starts. + +!!! note + ADR will only work if there's already a recent build of LibreTuya flashed to the device (and if the device doesn't bootloop or freeze immediately). + +## Beken 72xx + +The code listens on UART1 for a link-check command (`01 E0 FC 01 00`). The baudrate configured on the serial port has to be 115200 - it is configured automatically upon booting, but ADR won't work anymore if you change the baudrate manually. Because BK72xx doesn't have a dedicated "persistent" download mode, a normal reboot is performed and the chip waits a few hundred milliseconds for another link-check command. + +## Realtek AmebaZ + +This is not yet implemented. diff --git a/docs/cloudcutter.md b/docs/getting-started/cloudcutter.md similarity index 96% rename from docs/cloudcutter.md rename to docs/getting-started/cloudcutter.md index d188db3..e181f84 100644 --- a/docs/cloudcutter.md +++ b/docs/getting-started/cloudcutter.md @@ -20,7 +20,7 @@ If your device doesn't have a profile yet, it will probably not work. You can co ### Firmware building -1. [Compile ESPHome](projects/esphome.md), or your custom firmware based on LibreTuya. +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. diff --git a/docs/getting-started/uploading.md b/docs/getting-started/uploading.md index 8823b37..277e0e6 100644 --- a/docs/getting-started/uploading.md +++ b/docs/getting-started/uploading.md @@ -4,3 +4,5 @@ The uploading/flashing procedure is different for every chip family: - BK72xx / BK7231 - [click here](../platform/beken-72xx/flashing.md) - Realtek AmebaZ (RTL8710BN/BX) - [click here](../platform/realtek-ambz/flashing.md) + +Also see [Auto-download-reboot](adr.md) for an easier way of uploading code. diff --git a/docs/ota/flashing.md b/docs/ota/flashing.md index 66755c5..f02241e 100644 --- a/docs/ota/flashing.md +++ b/docs/ota/flashing.md @@ -1,5 +1,4 @@ -It is possible to upload firmware binaries manually, using the provided command-line tool `uf2upload`. For this, you need the `.uf2` file generated after compilation (usually found in `.pio/build/my_board/`). +It is possible to upload firmware binaries manually, using the command-line tool `ltchiptool`. For this, you need the `.uf2` file generated after compilation (usually found in `.pio/build/my_board/`). -1. Open a command prompt/terminal and `cd` into your home directory (`c:\Users\username` on Windows, `/home/username` on Linux). -2. `cd .platformio/platforms/libretuya/tools/upload` -3. `python uf2upload.py my_firmware.uf2 uart COM96` (replace `my_firmware.uf2` with your file name and `COM96` with your upload port). +1. Install Python. Afterwards, run `pip install ltchiptool`. +2. `ltchiptool uf2 upload my_firmware.uf2 uart COM96` (replace `my_firmware.uf2` with your file name and `COM96` with your upload port). diff --git a/docs/platform/beken-72xx/dumping.md b/docs/platform/beken-72xx/dumping.md index 3c33571..4a40c4d 100644 --- a/docs/platform/beken-72xx/dumping.md +++ b/docs/platform/beken-72xx/dumping.md @@ -12,9 +12,13 @@ Dumping is also done using UART (TX1/RX1). - Clone bk7231tools: `git clone https://github.com/notkmhn/bk7231tools` - `cd bk7231tools` - Run dumping: `python bk7231tools.py read_flash -d COM96 -b 230400 -s 0 -c 512 dump.bin`. Change the port (`-p`) and baudrate (`-b`) if you want. + !!! note The `--no-verify-checksum` is not required on BK7231N in latest versions of `bk7231tools`, despite the readme saying otherwise. + It's advised to run without that option, to make sure the dump is valid. + - You have 10 seconds to reset the chip (pull CEN to GND, or power-cycle the board) after running the command. The program will then begin dumping. + !!! note - If you need, you can increase the linking timeout using `--timeout` parameter. + If you need to, you can increase the linking timeout using `--timeout` parameter. diff --git a/docs/platform/beken-72xx/flashing.md b/docs/platform/beken-72xx/flashing.md index 08f9cb5..9de4980 100644 --- a/docs/platform/beken-72xx/flashing.md +++ b/docs/platform/beken-72xx/flashing.md @@ -2,6 +2,7 @@ - [Flashing (Tuya manual)](https://developer.tuya.com/en/docs/iot/burn-and-authorize-wb-series-modules?id=Ka78f4pttsytd) - [BkWriter v1.6.0](https://images.tuyacn.com/smart/bk_writer1.60/bk_writer1.60.exe) +- [hid_download_py](https://github.com/OpenBekenIOT/hid_download_py) Downloading is done using UART. For best experience, you should have two USB<->UART adapters plugged in (for UART1 and UART2). @@ -10,6 +11,8 @@ Downloading is done using UART. For best experience, you should have two USB<->U If you're not using auto-reset, you'll have to reset the chip manually when upload starts (you have 10 seconds to do that). + If you have a recent version of LibreTuya installed on the chip, you can use [Auto-download-reboot](../../getting-started/adr.md) to reboot the chip automatically. + - UART1 is used for uploading the code. This adapter will be used by PlatformIO. - UART2 allows for log output. You can have a terminal session continuously open on this adapter. diff --git a/docs/projects/esphome.md b/docs/projects/esphome.md index f3eb98f..6917e4f 100644 --- a/docs/projects/esphome.md +++ b/docs/projects/esphome.md @@ -1,8 +1,10 @@ # ESPHome -!!! note +!!! important Read [Getting started](../getting-started/README.md) first. + **It is very important that you have the latest version of LibreTuya installed** (not `libretuya-esphome`) **so that you don't face issues that are already resolved**. + ## Install ESPHome Because ESPHome does not natively support running on non-ESP chips, you need to use a fork of the project. @@ -93,4 +95,4 @@ libretuya: Refer to your board README to find appropriate flashing instructions. - Or [flash with `tuya-cloudcutter`](../cloudcutter.md). + Or [flash with `tuya-cloudcutter`](../getting-started/cloudcutter.md). diff --git a/docs/reference/config.md b/docs/reference/config.md index d135156..f0bb39f 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -92,6 +92,12 @@ Options for controlling default UART log output. If `LT_UART_DEFAULT_LOGGER` is not set, it is chosen by the family code - whichever port is most appropriate (i.e. LOG_UART (2) on Realtek, RX2/TX2 on Beken). +### Misc options + +- `LT_USE_TIME` (0) - enables implementation of `gettimeofday()` and `settimeofday()`; checks for `millis()` overflows periodically +- `LT_MICROS_HIGH_RES` (1) - count runtime microseconds using a high-resolution timer; disable if your application doesn't need `micros()` +- `LT_AUTO_DOWNLOAD_REBOOT` (1) - automatically reboot into "download mode" after detecting a flashing protocol command; [read more](../getting-started/adr.md) + ### Family feature config These options are selectively set by all families, as part of the build process. They are used for enabling LT core API parts, if the family has support for it. @@ -107,7 +113,3 @@ The meaning of most flags is as follows: - `LT_ARD_HAS_MD5` - MD5 library implemented, `MD5Impl.h` available - `LT_ARD_HAS_WIFI` - WiFi library implemented, `WiFiData.h` available - `LT_HEAP_FUNC` - function name used to get available heap size (for `LT_HEAP_I()`) - -### Misc options - -- `LT_USE_TIME` - enables implementation of `gettimeofday()` and `settimeofday()`; checks for `millis()` overflows periodically