From 9e95c507b1e5de667f58fbf85642c23c1ecde50e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kuba=20Szczodrzy=C5=84ski?= Date: Tue, 17 Jan 2023 18:56:15 +0100 Subject: [PATCH] [docs] Refactor docs structure, add project upload guides --- SUMMARY.md | 51 ++++----- docs/flashing/SUMMARY.md | 10 ++ docs/{getting-started => flashing}/adr.md | 0 .../cloudcutter.md | 12 ++- docs/flashing/esphome.md | 42 ++++++++ docs/flashing/inc/ota-cloudcutter.md | 8 ++ docs/flashing/inc/ota-openbeken.md | 5 + docs/flashing/inc/uart-info.md | 1 + docs/flashing/inc/uart-ltchiptool.md | 6 ++ docs/flashing/ltchiptool.md | 100 ++++++++++++++++++ docs/flashing/platformio.md | 30 ++++++ docs/getting-started/README.md | 33 +++--- docs/getting-started/uploading.md | 8 -- docs/libs-3rd-party.md | 10 +- docs/libs-built-in.md | 8 +- docs/ota/README.md | 17 ++- docs/platform/beken-72xx/flashing.md | 2 +- docs/platform/realtek-ambz/flashing.md | 2 +- docs/platform/realtek/debugging.md | 14 +-- docs/projects/esphome.md | 52 ++++----- docs/reference/config.md | 35 +++--- docs/reference/lt-api.md | 12 +-- docs/requirements.txt | 1 + docs/status/arduino.md | 2 +- docs/status/supported.md | 12 +-- examples/PinScan/README.md | 8 +- examples/SUMMARY.md | 3 + 27 files changed, 342 insertions(+), 142 deletions(-) create mode 100644 docs/flashing/SUMMARY.md rename docs/{getting-started => flashing}/adr.md (100%) rename docs/{getting-started => flashing}/cloudcutter.md (82%) create mode 100644 docs/flashing/esphome.md create mode 100644 docs/flashing/inc/ota-cloudcutter.md create mode 100644 docs/flashing/inc/ota-openbeken.md create mode 100644 docs/flashing/inc/uart-info.md create mode 100644 docs/flashing/inc/uart-ltchiptool.md create mode 100644 docs/flashing/ltchiptool.md create mode 100644 docs/flashing/platformio.md delete mode 100644 docs/getting-started/uploading.md create mode 100644 examples/SUMMARY.md diff --git a/SUMMARY.md b/SUMMARY.md index 5346c12..2190db1 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,40 +1,29 @@ * [Home](README.md) -* 😊 Getting started - * [Start here](docs/getting-started/README.md) - * [Uploading](docs/getting-started/uploading.md) - * [Options & config](docs/reference/config.md) - * Examples - * [PinScan](examples/PinScan/README.md) - * [ESPHome port](docs/projects/esphome.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 - * Beken BK72xx - * [General info](docs/platform/beken-72xx/README.md) - * [Flashing](docs/platform/beken-72xx/flashing.md) - * [Dumping](docs/platform/beken-72xx/dumping.md) - * Realtek AmebaZ Series - * [General info](docs/platform/realtek/README.md) - * [Flashing (AmebaZ)](docs/platform/realtek-ambz/flashing.md) - * [Dumping (AmebaZ)](docs/platform/realtek-ambz/dumping.md) - * [Debugging](docs/platform/realtek/debugging.md) - * [Exception decoder](docs/platform/realtek/exception-decoder.md) - * C library - * [Built-in functions](docs/platform/realtek-ambz/stdlib.md) - * [Memory management](docs/platform/realtek-ambz/memory-management.md) - * [All supported boards](boards/) -* API & libraries - * [Options & config](docs/reference/config.md) - * [LibreTuya API](docs/reference/lt-api.md) +* [😊 Getting started](docs/getting-started/README.md) +* [📲 Flashing/dumping](docs/flashing/) +* [💻 Supported boards & chips](docs/status/supported.md) +* 📖 Reference + * [🔧 LT configuration](docs/reference/config.md) + * [✔️ Implementation status](docs/status/arduino.md) + * [🔌 Boards documentation](boards/) + * [🔋 Examples](examples/) + * Chip families + * [Beken BK72xx](docs/platform/beken-72xx/README.md) + * Realtek AmebaZ Series + * [General info](docs/platform/realtek/README.md) + * [Debugging](docs/platform/realtek/debugging.md) + * [Exception decoder](docs/platform/realtek/exception-decoder.md) + * C library + * [Built-in functions](docs/platform/realtek-ambz/stdlib.md) + * [Memory management](docs/platform/realtek-ambz/memory-management.md) + * [📖 LibreTuya API](docs/reference/lt-api.md) * [LT class reference](ltapi/class_libre_tuya.md) * [Common methods](ltapi/_libre_tuya_a_p_i_8h.md) * [Wiring custom methods](ltapi/_libre_tuya_custom_8h.md) * [Logger](ltapi/lt__logger_8h.md) * [Chip & family IDs](ltapi/_chip_type_8h_source.md) * [POSIX utilities](ltapi/lt__posix__api_8h.md) - * Common API + * 📖 Common API * [FS](ltapi/classfs_1_1_f_s.md) * [Preferences](ltapi/class_i_preferences.md) * [SoftwareSerial](ltapi/class_software_serial.md) @@ -42,7 +31,7 @@ * [TCP Client](ltapi/class_i_wi_fi_client.md) * [SSL Client](ltapi/class_i_wi_fi_client_secure.md) * [TCP Server](ltapi/class_i_wi_fi_server.md) - * [LibreTuya libraries](docs/libs-built-in.md) + * [📖 LibreTuya libraries](docs/libs-built-in.md) * [base64](ltapi/classbase64.md) * [Flash](ltapi/class_flash_class.md) * [HTTPClient](ltapi/class_h_t_t_p_client.md) diff --git a/docs/flashing/SUMMARY.md b/docs/flashing/SUMMARY.md new file mode 100644 index 0000000..25a2361 --- /dev/null +++ b/docs/flashing/SUMMARY.md @@ -0,0 +1,10 @@ +# Flashing/dumping methods & guides + +* [Flashing PlatformIO projects](platformio.md) +* [Flashing ESPHome](esphome.md) +* [Using ltchiptool GUI](ltchiptool.md) +* [Using tuya-cloudcutter](cloudcutter.md) +* Chip connection guide + * [Beken BK72xx](../platform/beken-72xx/flashing.md) + * [Realtek RTL8710Bx](../platform/realtek-ambz/flashing.md) +* [Auto-download-reboot](adr.md) diff --git a/docs/getting-started/adr.md b/docs/flashing/adr.md similarity index 100% rename from docs/getting-started/adr.md rename to docs/flashing/adr.md diff --git a/docs/getting-started/cloudcutter.md b/docs/flashing/cloudcutter.md similarity index 82% rename from docs/getting-started/cloudcutter.md rename to docs/flashing/cloudcutter.md index e181f84..bf0bf52 100644 --- a/docs/getting-started/cloudcutter.md +++ b/docs/flashing/cloudcutter.md @@ -1,10 +1,12 @@ # 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. +!!! note + This currently applies to BK7231T and BK7231N only. `tuya-cloudcutter` can't be used for other chips. -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. +[`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 disassembling it. -**Currently, `tuya-cloudcutter` works for BK7231T and BK7231N only.** +!!! warning + This guide might be outdated. For an up-to-date guide, always refer to [tuya-cloudcutter/INSTRUCTIONS.md](https://github.com/tuya-cloudcutter/tuya-cloudcutter/blob/main/INSTRUCTIONS.md). 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. @@ -22,11 +24,11 @@ If your device doesn't have a profile yet, it will probably not work. You can co 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. +3. Put it in the `custom-firmware` directory of tuya-cloudcutter. ### Pairing and flashing -1. Run `./run_flash.sh` from the cloudcutter directory. +1. Run `./tuya-cloudcutter.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. diff --git a/docs/flashing/esphome.md b/docs/flashing/esphome.md new file mode 100644 index 0000000..92e0e7f --- /dev/null +++ b/docs/flashing/esphome.md @@ -0,0 +1,42 @@ +# Flashing ESPHome + +ESPHome can be flashed in few different ways, depending on your needs. + +## Built-in flasher + +The flasher program built-in LibreTuya is also available for ESPHome. + +- use `python -m esphome run yourdevice.yml` to recompile AND upload the firmware +- use `python -m esphome upload yourdevice.yml` to upload without recompiling + +{% + include-markdown "inc/uart-info.md" +%} + +If your device is already running ESPHome, refer to the OTA guide below. + +## Other methods + +!!! abstract + All binary files generated by ESPHome will be in `.esphome/build//.pioenvs//`. The methods described below may require you to get a file from that directory. + + This path will be referred to as **build directory**. + +## Over-the-Air (OTA) + +This method requires having ESPHome already installed on your device. + +- If you've added the Web Server component, navigate to the device's IP address (or `.local` name) in your web browser. Grab `firmware.uf2` from the build directory and drop it on the "OTA Update" field. +- You can also use ESPHome CLI to flash via OTA. Add a `--device` argument to the command, as such: `python -m esphome upload yourdevice.yml --device yourdevice.local` + +{% + include-markdown "inc/uart-ltchiptool.md" +%} + +{% + include-markdown "inc/ota-cloudcutter.md" +%} + +{% + include-markdown "inc/ota-openbeken.md" +%} diff --git a/docs/flashing/inc/ota-cloudcutter.md b/docs/flashing/inc/ota-cloudcutter.md new file mode 100644 index 0000000..d78b0be --- /dev/null +++ b/docs/flashing/inc/ota-cloudcutter.md @@ -0,0 +1,8 @@ +## Converting devices with tuya-cloudcutter + +!!! note + This currently applies to BK7231T and BK7231N only. `tuya-cloudcutter` can't be used for other chips. + +Grab the `bk7231x_app.ota.ug.bin` file from the build directory - take care to choose the correct file. It must have "OTA" and "UG" in its name. + +Next, refer to [Using tuya-cloudcutter](../cloudcutter.md) guide. diff --git a/docs/flashing/inc/ota-openbeken.md b/docs/flashing/inc/ota-openbeken.md new file mode 100644 index 0000000..55b8ea3 --- /dev/null +++ b/docs/flashing/inc/ota-openbeken.md @@ -0,0 +1,5 @@ +## Migrating from OpenBeken (OTA) + +[OpenBeken](https://github.com/openshwprojects/OpenBK7231T_App) is a custom, Tasmota-like firmware for non-ESP chips. Currently, this part of the guide applies to BK7231 only, as that's the only chip supported both by LT and OBK. + +OBK is compatible with standard Beken OTA packages, but the web panel does a filename check to prevent chip type mismatch. Grab the `bk7231x_app.ota.bin` file from build directory (note: without "UG" in the name!), rename it to something like `OpenBK7231T_esphome.rbl` (change T to N depending on the chip type), and drop it on the OTA panel. diff --git a/docs/flashing/inc/uart-info.md b/docs/flashing/inc/uart-info.md new file mode 100644 index 0000000..0b16fa9 --- /dev/null +++ b/docs/flashing/inc/uart-info.md @@ -0,0 +1 @@ +The device needs to be connected to your PC with a UART-TTL adapter. Refer to chip connection guides (see: menu on the left) to learn how to connect your device. diff --git a/docs/flashing/inc/uart-ltchiptool.md b/docs/flashing/inc/uart-ltchiptool.md new file mode 100644 index 0000000..22215e1 --- /dev/null +++ b/docs/flashing/inc/uart-ltchiptool.md @@ -0,0 +1,6 @@ +## Using ltchiptool (wired, via UART) + +You can use the [ltchiptool](https://github.com/libretuya/ltchiptool) GUI or CLI to manually flash the firmware. Grab the `firmware.uf2` file from the build directory. Then, follow the [ltchiptool usage guide](../ltchiptool.md) to flash it to the device. + +!!! tip + The UF2 file may have a different name, depending on the project you're building. Usually it's best to grab the latest (sorted by date) file with UF2 extension from the build directory. diff --git a/docs/flashing/ltchiptool.md b/docs/flashing/ltchiptool.md new file mode 100644 index 0000000..00a3fc8 --- /dev/null +++ b/docs/flashing/ltchiptool.md @@ -0,0 +1,100 @@ +# ltchiptool + +ltchiptool is a universal, easy-to-use GUI flashing/dumping tool for BK7231, RTL8710B and RTL8720C. It also contains some CLI utilities for binary firmware manipulation. + +## Installation + +### GUI package (Windows only) + +Download the latest release .EXE from the [GitHub Releases page](https://github.com/libretuya/ltchiptool/releases/latest). Open the file, and you're ready to go! + +The GUI executable works on Windows 7 and newer. + +### GUI or CLI (Windows/Linux/etc.) + +Install the package from PyPI, using `pip install ltchiptool`. + +This will install `ltchiptool` and `uf2tool` packages. You can start the GUI by typing `python -m ltchiptool gui`. + +## GUI Usage + +The main window is somewhat similar to [NodeMCU PyFlasher](https://github.com/marcelstoer/nodemcu-pyflasher). + +- For dumping, choose `Read flash`. If you've previously chosen an input or output file, it will generate a dump filename with the current timestamp and chip type. Otherwise, click `Browse` and choose the output file. By default, the tool will attempt to read the entire flash chip (usually 2 MiB). +- For flashing, choose `Write flash`. Click `Browse` and select *any* valid firmware file. The file type and chip type will be auto-detected, along with correct flash offset and length. No need to worry about overwriting the bootloader anymore! + - If the file you're selecting is `Unrecognized` or `Not flashable`, it's most likely not a valid firmware file. Refer to usage guides of the custom firmware project of choice, to find which file is meant for flashing. +- **It's best to leave `Auto-detect advanced parameters` checked**. If you're an experienced user and want to flash custom areas of the flash, uncheck the box and specify the parameters manually. +- When you're ready, hit `Start`. The tool will try to connect to the chip on the selected UART port. The black log window will print any warnings/errors, as well as **a short guide on how to put the chip in download mode**. + +!!! info + LibreTuya generates multiple firmware files in the build directory. **You usually want to flash the `.uf2` file**, but since ltchiptool can detect file types, you can choose a different firmware file and it'll tell you if that works. + +## CLI Usage + +!!! note + If you're here to learn how to flash or dump firmware files, use the instructions above. + + The content below serves as a short documentation page for [`ltchiptool`](https://github.com/libretuya/ltchiptool) and is mostly meant for advanced users. + +```shell +$ ltchiptool --help +Usage: ltchiptool [OPTIONS] COMMAND [ARGS]... + + Tools for working with LT-supported IoT chips + +Options: + -v, --verbose Output debugging messages (repeat to output more) + -T, --traceback Print complete exception traceback + -t, --timed Prepend log lines with timing info + -r, --raw-log Output logging messages with no additional styling + -i, --indent INTEGER Indent log messages using graph lines + -V, --version Show the version and exit. + -h, --help Show this message and exit. + +Commands: + dump Capture or process device dumps + elf2bin Generate firmware binaries from ELF file + flash Flashing tool - reading/writing + link2bin Link code to binary format + list List boards, families, etc. + soc Run SoC-specific tools + uf2 Work with UF2 files +``` + +### Flashing/dumping + +There are three main commands used for flashing: + +- `ltchiptool flash file ` - detect file type based on its contents (i.e. chip from which a dump was acquired), similar to Linux `file` command +- `ltchiptool flash read ` - make a full flash dump of the connected device; specifying the family is required +- `ltchiptool flash write ` - upload a file to the device; detects file type automatically (just like the `file` command above) + +Supported device families can be checked using `ltchiptool list families` command. In the commands above, you can use any of the family names (name/code/short name/etc). + +The upload UART port and baud rate is detected automatically. To override it, use `-d COMx` or `-d /dev/ttyUSBx`. To change the target baud rate, use `-b 460800`. +Note that the baud rate is changed after linking. Linking is performed using chip-default baud rate. + +It's not required to specify chip family for writing files - `ltchiptool` tries to recognize contents of the file, and chooses the best settings automatically. +If you want to flash unrecognized/raw binaries (or fine-tune the flashing parameters), specify `-f ` and `-s `. + +### UF2 Example + +```shell +$ ltchiptool uf2 info ./arduinotest_22.08.01_wb2l_BK7231T_lt0.8.0.uf2 +Family: BK7231T / Beken 7231T +Tags: + - BOARD: wb2l + - DEVICE_ID: d80e20c2 + - LT_VERSION: 0.8.0 + - FIRMWARE: arduinotest + - VERSION: 22.08.01 + - OTA_VERSION: 01 + - DEVICE: LibreTuya + - BUILD_DATE: 6d08e862 + - LT_HAS_OTA1: 01 + - LT_HAS_OTA2: 00 + - LT_PART_1: app + - LT_PART_2: +Data chunks: 1871 +Total binary size: 478788 +``` diff --git a/docs/flashing/platformio.md b/docs/flashing/platformio.md new file mode 100644 index 0000000..7dd4d5d --- /dev/null +++ b/docs/flashing/platformio.md @@ -0,0 +1,30 @@ +# Flashing PlatformIO projects + +PlatformIO projects developed with LibreTuya can be flashed just like any other PIO project. + +## Built-in flasher + +LibreTuya has a built-in firmware uploader, based on [ltchiptool](ltchiptool.md). Pressing `Upload` in PlatformIO IDE does all the work for you. + +If you have more than one COM port,configure your PIO project first: + +```ini +[env:my_board] +monitor_port = COM96 +upload_port = COM96 +``` + +{% + include-markdown "inc/uart-info.md" +%} + +## Other methods + +!!! abstract + All binary files generated by PlatformIO will be in `.pio/build//`. The methods described below may require you to get a file from that directory. + + This path will be referred to as **build directory**. + +{% + include-markdown "inc/uart-ltchiptool.md" +%} diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index d3f4e9c..ed03791 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -13,16 +13,9 @@ Using LibreTuya is simple, just like every other PlatformIO development platform - Click on the board name. From the documentation page, note the board code. - Use this code to create a PlatformIO project. -## GPIO usage +## Run community projects -!!! important - This can be confusing at first, so make sure to read this part carefully to understand it. - - Input/output pin numbers in Arduino code (i.e. `digitalWrite()`) use Arduino pin numbers - for example `D1`, `D3`. This is the same as simply `1` or `3`, but it cannot be confused with CPU GPIO numbers. - - On the board pinout page, the purple blocks represent Arduino pins, while the dark red blocks refer to GPIO numbers. - - Projects like ESPHome also use Arduino pin numbering. +LibreTuya was developed with popular community projects in mind. Currently, unofficial [ESPHome port](../projects/esphome.md) is available ([the PR](https://github.com/esphome/esphome/pull/3509) will hopefully be merged into upstream at some point). ## Develop your own project @@ -31,8 +24,24 @@ If you're developing your own embedded software, and want it to run on LibreTuya - use PlatformIO IDE (PIO Home -> Open -> New Project) - run `pio project init` in your desired project directory -Next, read [Uploading](uploading.md) guide to run your project! +Next, read one of the [flashing guides](../flashing/SUMMARY.md) to run your project! -## Run community projects +### LT configuration -LibreTuya was developed with popular community projects in mind. Currently, unofficial [ESPHome port](../projects/esphome.md) is available ([the PR](https://github.com/esphome/esphome/pull/3509) will hopefully be merged into upstream at some point). +LibreTuya has a few configuration options that change its behavior or features. Refer to [LT configuration](../reference/config.md) for details. + +### GPIO usage + +!!! important + This can be confusing at first, so make sure to read this part carefully to understand it. + + Input/output pin numbers in Arduino code (i.e. `digitalWrite()`) use Arduino pin numbers - for example `D1`, `D3`. This is the same as simply `1` or `3`, but it cannot be confused with CPU GPIO numbers. + + On the board pinout page, the purple blocks represent Arduino pins, while the dark red blocks refer to GPIO numbers. + +### Examples + +{% + include-markdown "../../examples/SUMMARY.md" + start="# Examples\n" +%} diff --git a/docs/getting-started/uploading.md b/docs/getting-started/uploading.md deleted file mode 100644 index 277e0e6..0000000 --- a/docs/getting-started/uploading.md +++ /dev/null @@ -1,8 +0,0 @@ -# Uploading - -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/libs-3rd-party.md b/docs/libs-3rd-party.md index 4de6127..3706f99 100644 --- a/docs/libs-3rd-party.md +++ b/docs/libs-3rd-party.md @@ -3,11 +3,11 @@ A page outlining 3-rd party libraries compatible with LibreTuya. !!! note - To use some (most? (all?)) of these, a flag in `platformio.ini` is required to disable compatibility checks (because most libs are meant for ESP32/Arduino official framework): - ```ini - [env:my_board] - lib_compat_mode = off - ``` + To use some (most? (all?)) of these, a flag in `platformio.ini` is required to disable compatibility checks (because most libs are meant for ESP32/Arduino official framework): + ```ini + [env:my_board] + lib_compat_mode = off + ``` ## MQTT Tested with `realtek-ambz`. diff --git a/docs/libs-built-in.md b/docs/libs-built-in.md index cdf1c29..beded9d 100644 --- a/docs/libs-built-in.md +++ b/docs/libs-built-in.md @@ -26,15 +26,15 @@ Utilities and common classes related to network. - [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WebServer/src): ESP32 Arduino Core - [Reference](../ltapi/class_web_server.md) - Examples: - - [HelloServer](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/HelloServer/HelloServer.ino) - - [MultiHomedServers](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/MultiHomedServers/MultiHomedServers.ino) + - [HelloServer](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/HelloServer/HelloServer.ino) + - [MultiHomedServers](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/MultiHomedServers/MultiHomedServers.ino) ## WiFiMulti - [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi/src): ESP32 Arduino Core - [Reference](../ltapi/class_wi_fi_multi.md) - [Docs](https://docs.espressif.com/projects/arduino-esp32/en/latest/api/wifi.html#wifimulti) - Examples: - - [WiFiMulti](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiMulti/WiFiMulti.ino) - - [WiFiClientBasic](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino) + - [WiFiMulti](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiMulti/WiFiMulti.ino) + - [WiFiClientBasic](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino) Class for selecting best available AP from a list of several ones. diff --git a/docs/ota/README.md b/docs/ota/README.md index ea1387f..72900e1 100644 --- a/docs/ota/README.md +++ b/docs/ota/README.md @@ -3,7 +3,7 @@ LibreTuya's OTA updating is based on [Microsoft's UF2 specification](https://microsoft.github.io/uf2/). Some aspects of the process, such as OTA1/2 support and target partition selection, have been customized with extension tags. !!! note - Just like in UF2, all values in this format are little-endian. + Just like in UF2, all values in this format are little-endian. ## Firmware images @@ -29,7 +29,7 @@ For easier understanding, these update types will be referred to in this documen ## Custom family IDs {% - include-markdown "../status/supported_families.md" + include-markdown "../status/supported_families.md" %} ## Extension tags @@ -84,17 +84,12 @@ OTA2 images are not stored directly, as that would needlessly double the UF2 fil There can be at most one binpatch tag in a UF2 block. It has the following format: - opcode (1 byte) - operation type: - - - `DIFF32` (0xFE) - difference between 32-bit values - + - `DIFF32` (0xFE) - difference between 32-bit values - length (1 byte) - data length - data (`length` bytes) - - - for `DIFF32`: - - - difference value (signed int 32-bit) - - - offset table (`length-4` bytes) + - for `DIFF32`: + - difference value (signed int 32-bit) + - offset table (`length-4` bytes) The presented structure can be repeated in a single binpatch tag. diff --git a/docs/platform/beken-72xx/flashing.md b/docs/platform/beken-72xx/flashing.md index 9de4980..eab5101 100644 --- a/docs/platform/beken-72xx/flashing.md +++ b/docs/platform/beken-72xx/flashing.md @@ -41,7 +41,7 @@ upload_port = COM96 ## Manually - using `uf2upload` {% - include-markdown "../../ota/flashing.md" + include-markdown "../../ota/flashing.md" %} ## Manually - using raw binaries/BkWriter diff --git a/docs/platform/realtek-ambz/flashing.md b/docs/platform/realtek-ambz/flashing.md index 23b4023..0c57709 100644 --- a/docs/platform/realtek-ambz/flashing.md +++ b/docs/platform/realtek-ambz/flashing.md @@ -23,7 +23,7 @@ upload_port = COM60 ## Manually - using `uf2upload` {% - include-markdown "../../ota/flashing.md" + include-markdown "../../ota/flashing.md" %} ## Manually - using raw binaries/BkWriter diff --git a/docs/platform/realtek/debugging.md b/docs/platform/realtek/debugging.md index 78671ff..4f8c207 100644 --- a/docs/platform/realtek/debugging.md +++ b/docs/platform/realtek/debugging.md @@ -28,13 +28,13 @@ Check out [RPi BCM2711 GPIOs](https://elinux.org/RPi_BCM2711_GPIOs) to read more TL;DR: Install OpenOCD. Conenct A14 to BCM GPIO#11, A15 to BCM GPIO#25. Remember to join GND together. Refer to [boards/](../../../boards/) for pinouts. !!! note - On Raspberry Pi 4, additional config might be needed: - ``` - bcm2835gpio peripheral_base 0xFE000000 - bcm2835gpio speed_coeffs 236181 60 - ``` - Save the lines to a .cfg file, and pass it to OpenOCD using `-f file.cfg`. - Read more [here](https://forums.raspberrypi.com/viewtopic.php?p=1541631&sid=915e8d039f24301b85c060318a44b7f0#p1541631). + On Raspberry Pi 4, additional config might be needed: + ``` + bcm2835gpio peripheral_base 0xFE000000 + bcm2835gpio speed_coeffs 236181 60 + ``` + Save the lines to a .cfg file, and pass it to OpenOCD using `-f file.cfg`. + Read more [here](https://forums.raspberrypi.com/viewtopic.php?p=1541631&sid=915e8d039f24301b85c060318a44b7f0#p1541631). Start OpenOCD like this (you also need your config file in the working directory): ```shell diff --git a/docs/projects/esphome.md b/docs/projects/esphome.md index 0a25ae6..39f3401 100644 --- a/docs/projects/esphome.md +++ b/docs/projects/esphome.md @@ -1,31 +1,32 @@ # ESPHome !!! important - Read [Getting started](../getting-started/README.md) first. + Read [Getting started](../getting-started/README.md) first - most importantly, the first part about installation. - **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**. + **It is very important that you have the latest version of LibreTuya installed** (not `libretuya-esphome` - this is a different thing!) **so that you don't face issues that are already resolved**. -## Install ESPHome +## Download 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) +2. `git clone https://github.com/kuba2k2/libretuya-esphome` +3. `cd` into the newly created `libretuya-esphome` directory. +4. Check if it works by typing `python -m esphome` -!!! note +!!! tip For Linux users (or if `python -m esphome` doesn't work for you): - - unistall ESPHome first: `pip uninstall esphome` + - uninstall ESPHome first: `pip uninstall esphome` - install the forked version: `pip install -e .` ## Create your device config -1. Go to [Boards & CPU list](../status/supported/), click on your board and remember your board code. +1. Go to [Boards & CPU list](../status/supported/), click on your board and remember the **`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 esphome: @@ -50,7 +51,25 @@ Assuming you have PlatformIO, git and Python installed: password: "Dv2hZMGZRUvy" ``` -## Configuration options +## Add components + +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**. + + 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 + +The command `python -m esphome compile yourdevice.yml` will compile ESPHome. + +You probably want to 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. All options from [Options & config](../reference/config.md) can be customized in the `libretuya:` block: @@ -81,18 +100,3 @@ libretuya: 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: - - 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`](../getting-started/cloudcutter.md). diff --git a/docs/reference/config.md b/docs/reference/config.md index 44fd4d3..5312298 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -15,7 +15,7 @@ custom_fw_version = 1.2.0 ## LibreTuya options !!! note - See [LibreTuyaConfig.h](../../ltapi/_libre_tuya_config_8h_source.md) for most options and their defaults. + See [LibreTuyaConfig.h](../../ltapi/_libre_tuya_config_8h_source.md) for most options and their defaults. All options are configurable via C++ defines in PlatformIO project file. For example: ```ini @@ -24,8 +24,8 @@ build_flags = -D LT_LOGLEVEL=LT_LEVEL_DEBUG ``` -!!! hint - Values in parentheses represent the defaults for the config options. +!!! tip + Values in parentheses represent the defaults for the config options. ### Logger @@ -64,16 +64,16 @@ To see debug messages from i.e. OTA, loglevel must also be changed. - `LT_DEBUG_LWIP` (0) - enables `LWIP_DEBUG`, provides `LWIP_PLATFORM_DIAG`; per-module options (i.e. `TCP_DEBUG`) are off by default and need to be enabled separately - `LT_DEBUG_LWIP_ASSERT` (0) - enables assertions within lwIP (doesn't need `LT_DEBUG_LWIP`) -!!! hint - Enabling `LT_DEBUG_ALL` doesn't mean that *every* debugging message will be printed. If loglevel is i.e. `WARN`, debug messages won't be visible anyway. +!!! tip + Enabling `LT_DEBUG_ALL` doesn't mean that *every* debugging message will be printed. If loglevel is i.e. `WARN`, debug messages won't be visible anyway. - This can be used, for example, to enable only "important" messages: - ```ini - [env:my_board] - build_flags = - -D LT_LOGLEVEL=LT_LEVEL_WARN - -D LT_DEBUG_ALL=1 # will print only warnings and errors from all modules - ``` + This can be used, for example, to enable only "important" messages: + ```ini + [env:my_board] + build_flags = + -D LT_LOGLEVEL=LT_LEVEL_WARN + -D LT_DEBUG_ALL=1 # will print only warnings and errors from all modules + ``` ### Serial output @@ -86,20 +86,23 @@ Options for controlling default UART log output. - `LT_UART_SILENT_ALL` (0) - disable all SDK output (LT output and logger still work) !!! info - Values 0, 1 and 2 correspond to physical UART port numbers (refer to board pinout for the available ports). + Values 0, 1 and 2 correspond to physical UART port numbers (refer to board pinout for the available ports). - Serial class instances (`Serial0`, `Serial1`, `Serial2`) use the respective port numbers for printing. + Serial class instances (`Serial0`, `Serial1`, `Serial2`) use the respective port numbers for printing. - 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). + 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) +- `LT_AUTO_DOWNLOAD_REBOOT` (1) - automatically reboot into "download mode" after detecting a flashing protocol command; [read more](../flashing/adr.md) ### Family feature config +!!! bug "Warning" + These options are not meant for end-users. They're provided here as a reference for developers. + 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. The `LT_ARD_*` options are only used with Arduino frameworks. diff --git a/docs/reference/lt-api.md b/docs/reference/lt-api.md index ed829d9..f051c1e 100644 --- a/docs/reference/lt-api.md +++ b/docs/reference/lt-api.md @@ -3,19 +3,19 @@ ## Class functions {% - include-markdown "../../ltapi/class_libre_tuya.md" + include-markdown "../../ltapi/class_libre_tuya.md" start="(class_libre_tuya.md)\n" end="[More...]" %} {% - include-markdown "../../ltapi/class_libre_tuya.md" + include-markdown "../../ltapi/class_libre_tuya.md" start="# Detailed Description\n" end="## Public Functions Documentation\n" %} {% - include-markdown "../../ltapi/class_libre_tuya.md" + include-markdown "../../ltapi/class_libre_tuya.md" start="## Public Functions\n" end="# Detailed Description\n" %} @@ -23,7 +23,7 @@ ## Common methods {% - include-markdown "../../ltapi/_libre_tuya_a_p_i_8h.md" + include-markdown "../../ltapi/_libre_tuya_a_p_i_8h.md" start="## Public Functions\n" end="## Public Functions Documentation\n" heading-offset=1 @@ -32,7 +32,7 @@ ## Wiring custom methods {% - include-markdown "../../ltapi/_libre_tuya_custom_8h.md" + include-markdown "../../ltapi/_libre_tuya_custom_8h.md" start="## Public Functions\n" end="## Macros\n" %} @@ -40,7 +40,7 @@ ## Logger {% - include-markdown "../../ltapi/lt__logger_8h.md" + include-markdown "../../ltapi/lt__logger_8h.md" start="## Public Functions\n" end="## Public Functions Documentation\n" heading-offset=1 diff --git a/docs/requirements.txt b/docs/requirements.txt index ad95c26..097d523 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +mkdocs-material mkdocs-same-dir mkdocs-literate-nav mkdocs-section-index diff --git a/docs/status/arduino.md b/docs/status/arduino.md index 43602d6..041b3d4 100644 --- a/docs/status/arduino.md +++ b/docs/status/arduino.md @@ -1,7 +1,7 @@ # Implementation status {% - include-markdown "../../README.md" + include-markdown "../../README.md" start="\n## Arduino Core support status\n" end="\n## License\n" %} diff --git a/docs/status/supported.md b/docs/status/supported.md index d831d8f..3aed119 100644 --- a/docs/status/supported.md +++ b/docs/status/supported.md @@ -3,7 +3,7 @@ ## Board list {% - include-markdown "supported_boards.md" + include-markdown "supported_boards.md" %} \* I/O count includes GPIOs, ADCs, PWM outputs and UART, but doesn't count CEN/RST and power pins. @@ -13,7 +13,7 @@ Chips currently supported by the project: {% - include-markdown "supported_chips.md" + include-markdown "supported_chips.md" %} This list is not exhaustive, i.e. a similar chip (but different package) might work just fine, but there's no board definition for it yet. @@ -24,12 +24,12 @@ If you have an unsupported chip, feel free to reach out using Issues or on the D A list of chip families currently supported by this project. !!! note - The term *family* was chosen over *platform*, in order to reduce possible confusion between LibreTuya supported "platforms" and PlatformIO's "platform", as an entire package. *Family* is also more compatible with the UF2 term. + The term *family* was chosen over *platform*, in order to reduce possible confusion between LibreTuya supported "platforms" and PlatformIO's "platform", as an entire package. *Family* is also more compatible with the UF2 term. The following list corresponds to UF2 OTA format family names, and is also [available as JSON](../../families.json). The IDs are also present in [ChipType.h](../../ltapi/_chip_type_8h_source.md). {% - include-markdown "supported_families.md" + include-markdown "supported_families.md" %} ## Unsupported boards @@ -37,8 +37,8 @@ The following list corresponds to UF2 OTA format family names, and is also [avai ### Tuya Inc. !!! note - Only modules featuring at least Wi-Fi are included in the table. (TY)JW, (TY)WE and (TY)LC Series are omitted, as they contain Espressif chips. + Only modules featuring at least Wi-Fi are included in the table. (TY)JW, (TY)WE and (TY)LC Series are omitted, as they contain Espressif chips. {% - include-markdown "unsupported_boards_tuya_all.md" + include-markdown "unsupported_boards_tuya_all.md" %} diff --git a/examples/PinScan/README.md b/examples/PinScan/README.md index 444ea6a..56cd313 100644 --- a/examples/PinScan/README.md +++ b/examples/PinScan/README.md @@ -36,7 +36,7 @@ Switching to another UART port is possible (for example if the default port is o By setting `USE_WIFI` in `main.h` to 1, a Telnet server is enabled on port 23. This allows to test I/O pins without having physical, wired access to the device (i.e. using OTA). Make sure to specify correct WiFi credentials. -!!! hint +!!! tip If your board isn't supported by LT yet, use one of the generic boards. If your board doesn't even have a known pinout, use `d`/`s` commands of PinScan to ease the mapping of all board pins. @@ -65,7 +65,7 @@ Commands: Screen contents will update when voltage on one of the pins changes. Pins marked with `--` mean the currently used UART port (which can be changed using `s` command; after reboot). -!!! tldr +!!! abstract "TL;DR" Try pressing a button to see which pin changes. ### Read one pin continuously @@ -81,7 +81,7 @@ Enter the pin number, it will be probed until you press `q`. A pin will be toggled every 500ms, starting with D0. Type `n` to move to the next pin. -!!! tldr +!!! abstract "TL;DR" Go through the pins to see which lights up an LED. ### Write HIGH/LOW to a pin @@ -94,7 +94,7 @@ Outputs can be toggled by using internal pull-up/pull-down resistors, or by simp This affects scan and write high/low commands. -!!! tldr +!!! abstract "TL;DR" Use `write` output mode (carefully) if there's an LED which doesn't light up with default pull mode. ## Analog pins diff --git a/examples/SUMMARY.md b/examples/SUMMARY.md new file mode 100644 index 0000000..3732739 --- /dev/null +++ b/examples/SUMMARY.md @@ -0,0 +1,3 @@ +# Examples + +* [PinScan](PinScan/README.md)