[docs] Update chip flashing guides, fix mkdocs building

SUMMARY.md

@@ -1,5 +1,6 @@
 * [Home](README.md)
 * [😊 Getting started](docs/getting-started/README.md)
+	* [ESPHome](docs/projects/esphome.md)
 * [📲 Flashing/dumping](docs/flashing/)
 * [💻 Supported boards & chips](docs/status/supported.md)
 * 📖 Reference
@@ -53,6 +54,5 @@
 	* [✈️ OTA format](docs/ota/README.md)
 		* [uf2ota.py tool](docs/ota/uf2ota.md)
 		* [uf2ota.h library](docs/ota/library.md)
-		* [uf2ota.h reference](ltapi/uf2ota_8h.md)
 * [📓 TODO](TODO.md)
 * [🔗 Resources](docs/resources.md)

docs/flashing/SUMMARY.md

@@ -3,7 +3,7 @@
 * [Flashing PlatformIO projects](platformio.md)
 * [Flashing ESPHome](esphome.md)
 * [Using ltchiptool GUI](ltchiptool.md)
-* [Using tuya-cloudcutter](cloudcutter.md)
+* [Converting with tuya-cloudcutter](cloudcutter.md)
 * Chip connection guide
 	* [Beken BK72xx](../platform/beken-72xx/flashing.md)
 	* [Realtek RTL8710Bx](../platform/realtek-ambz/flashing.md)

docs/flashing/cloudcutter.md

@@ -1,4 +1,4 @@
-# Flashing with tuya-cloudcutter
+# Converting with tuya-cloudcutter
 
 !!! note
 	This currently applies to BK7231T and BK7231N only. `tuya-cloudcutter` can't be used for other chips.

docs/flashing/ltchiptool.md

@@ -1,6 +1,6 @@
 # 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.
+[ltchiptool](https://github.com/libretuya/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
 

docs/platform/beken-72xx/dumping.md

@@ -1,24 +0,0 @@
-# Dumping - Beken 72xx
-
-- [bk7231tools](https://github.com/notkmhn/bk7231tools)
-
-## Dumping firmware
-
-Dumping is also done using UART (TX1/RX1).
-
-- Connect power to the board: GND and 3V3 (from your UART adapter or a higher-powered source).
-- Connect an USB<->UART adapter to the chip: RX->TX1, TX->RX1.
-- Install Python and Git.
-- 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 to, you can increase the linking timeout using `--timeout` parameter.

docs/platform/beken-72xx/flashing.md

@@ -1,51 +1,70 @@
-# Flashing - Beken 72xx
+# Download mode - Beken 72xx
+
+Downloading is done using UART. For best experience, you should have two USB<->UART adapters plugged in:
+
+- One for flashing, preferably a real FT232RL or a good alternative. This connects to UART1 of the chip.
+- One for log output - BK72xx outputs messages on a separate port. You can have a terminal session continuously open on this adapter. This connects to UART2 of the chip - but it's not necessary for flashing.
+
+**Read [Using ltchiptool](../../flashing/ltchiptool.md) to learn the flashing procedure**
+
+!!! success "Wiring"
+	Connect UART1 of the BK7231 to the USB-TTL adapter:
+
+	PC  | BK7231
+	----|-----------------------
+	RX  | TX1 (GPIO11 / P11)
+	TX  | RX1 (GPIO10 / P10)
+	RTS | CEN (or RST, optional)
+	GND | GND
+
+	Make sure to use a good 3.3V power supply, otherwise the adapter might
+	lose power during chip reset. Usually, the adapter's power regulator
+	is not enough and an external power supply is needed (like AMS1117).
+
+	If you didn't connect RTS to CEN, after starting the flasher you have
+	around 20 seconds to reset the chip manually. In order to do that,
+	you need to bridge CEN to GND with a wire.
+
+Note that the download mode can only be activated when the flasher is running (there's no GPIO-strapping like on ESP8266). Additionally, BK7231T (not N) will exit the download mode when the flasher finishes its work.
+
+!!! tip
+	BK7231N can't be software-bricked, because it has a ROM that contains the download mode. **BK7231T doesn't contain the ROM, so be careful with this one**.
+
+## bk7231tools
+
+`ltchiptool`'s Beken flashing program is based on [bk7231tools](https://github.com/tuya-cloudcutter/bk7231tools). Refer to the guide for information how to use it, but keep in mind that using the ltchiptool GUI is probably just easier.
+
+## Auto-download-reboot
+
+If you have a recent version of LibreTuya installed on the chip, you can use [Auto-download-reboot](../../flashing/adr.md) to reboot the chip automatically. This is enabled by default, so you don't have to change anything.
+
+## Single-adapter usage
+
+If you only have a single adapter, or just want to use the UART1 (upload) port only, you can change the logging port.
+
+Refer to [Options & config](../../reference/config.md) (`Serial output` section). Set `LT_UART_DEFAULT_PORT` to `1`, which will use UART1 for all output.
+
+## Firmware output files
+
+These files are present in the build directory after successful compilation:
+
+File                      | Description
+--------------------------|----------------------------------------
+**firmware.uf2**          | **UF2 package for UART and OTA upload**
+bk7231t_app.ota.rbl       | Beken OTA package (e.g. OpenBeken)
+bk7231t_app.ota.ug.bin    | Tuya OTA package (incl. Cloudcutter)
+bk7231t_app_0x011000.rbl  | App partition - flashable at 0x11000
+bk7231t_app_0x011000.crc  | Encrypted app image - not for flashing
+bk7231t_app_0x129F0A.rblh | RBL header - not for flashing
+
+## SPI flashing (unbricking BK7231T)
+
+The [bk7231_spi_flasher.py](https://github.com/openshwprojects/BK7231_SPI_Flasher/blob/main/bk7231_spi_flasher.py) script can be used to put BK7231 in SPI flashing mode. Then, one can use [flashrom](https://www.flashrom.org/Flashrom) to read/write the raw flash chip.
+
+## Other tools/guides
+
+These tools are **not recommended** and are kept here for reference only. Don't use them, please.
 
 - [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)
+- [hid_download_py](https://github.com/tiancj/hid_download_py)
-
-Downloading is done using UART. For best experience, you should have two USB<->UART adapters plugged in (for UART1 and UART2).
-
-!!! hint
-	The adapter connected to UART1 (for uploading) can have RTS connected to chip's RESET or CEN - to provide auto-reset during uploading.
-
-	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.
-
-!!! hint
-	If you only have a single adapter, or just want to use the UART1 (upload) port only, you can change the logging port.
-
-	Refer to [Options & config](../../reference/config.md) (`Serial output` section). Set `LT_UART_DEFAULT_PORT` to `1`, which will use UART1 for all output.
-
-## Automatically - using PlatformIO (recommended)
-
-LibreTuya has built-in firmware uploaders. Pressing `Upload` in PlatformIO IDE does all the work for you.
-
-Although the default options work in most cases, it is recommended to configure your PIO project first:
-
-```ini
-[env:my_board]
-# default baudrate for both UARTs
-monitor_speed = 115200
-# port connected to UART2
-monitor_port = COM60
-
-# port connected to UART1
-upload_port = COM96
-```
-
-## Manually - using `uf2upload`
-
-{%
-	include-markdown "../../ota/flashing.md"
-%}
-
-## Manually - using raw binaries/BkWriter
-
-A binary file named `bk7231t_app_0x011000.rbl` is generated in `.pio/build/my_board/`. This file can be flashed to offset 0x11000, using BkWriter or other flashing tool of choice (including SPI download or flashrom).
-
-Keep in mind that BkWriter is an extremely buggy and broken tool, and simply does not work in most cases.

docs/platform/realtek-ambz/dumping.md

@@ -1,15 +0,0 @@
-# Dumping - Beken 72xx
-
-- [rtltool.py](https://github.com/libretuya/ltchiptool/blob/master/ltchiptool/soc/ambz/util/rtltool.py)
-
-## Dumping firmware
-
-Dumping is also done using UART (TX2/RX2; Log_UART).
-
-- Connect power to the board: GND and 3V3 (from your UART adapter or a higher-powered source).
-- Connect an USB<->UART adapter to the chip: RX->TX1, TX->RX1.
-- Put the chip into download mode: reset the chip, while pulling UART2_TX to GND. If successful, the chip should print few garbage characters every second.
-- Disconnect TX from GND after powering up the board.
-- Install Python.
-- Grab `rtltool.py` from the link above.
-- Run dumping: `python rtltool.py -p COM60 rf 0 0x200000 dump.bin`. Change the port (`-p`) to your adapter's port.

docs/platform/realtek-ambz/flashing.md

@@ -1,41 +1,52 @@
-# Flashing - Realtek AmebaZ
+# Download mode - Realtek AmebaZ
+
+Downloading is done using UART2 (sometimes called Log_UART). Refer to your board documentation to find the correct pins. You need a good USB<->UART adapter (preferably a real FT232RL) for the process.
+
+**Read [Using ltchiptool](../../flashing/ltchiptool.md) to learn the flashing procedure**
+
+!!! success "Wiring"
+	Connect UART2 of the Realtek chip to the USB-TTL adapter:
+
+	PC  | RTL8710B
+	----|------------------------------
+	RX  | TX2 (Log_TX / PA30)
+	TX  | RX2 (Log_RX / PA29)
+	RTS | CEN (or RST, optional)
+	DTR | TX2 (Log_TX / PA30, optional)
+	GND | GND
+
+	Make sure to use a good 3.3V power supply, otherwise the adapter might
+	lose power during chip reset. Usually, the adapter's power regulator
+	is not enough and an external power supply is needed (like AMS1117).
+
+	If you didn't connect RTS and DTR, you need to put the chip in download
+	mode manually. This is done by connecting CEN to GND, while holding TX2 (Log_TX)
+	to GND as well. After doing that, you need to disconnect TX2 from GND.
+
+	If the download mode is enabled, you'll see a few garbage characters
+	printed to the serial console every second.
+
+!!! tip
+	Because the UART uploading code is programmed in the ROM of the chip, it can't be software-bricked, even if you damage the bootloader.
+
+## Firmware output files
+
+These files are present in the build directory after successful compilation:
+
+File                    | Description
+------------------------|-------------------------------------------------------------------
+**firmware.uf2**        | **UF2 package for UART and OTA upload**
+image_0x00B000.ota1.bin | OTA 1 image, flashable to 0xB000
+image_0x0D0000.ota2.bin | OTA 2 image, flashable to 0xD0000 (the address might be different)
+
+## Other tools/guides
+
+These tools are **not recommended** and are kept here for reference only. Don't use them, please.
 
 - [Flashing (Tuya manual)](https://developer.tuya.com/en/docs/iot/burn-and-authorize-wr-series-modules?id=Ka789pjc581u8)
 - [ImageTool (AmebaZ/AmebaD)](https://images.tuyacn.com/smart/Image_Tool/Image_Tool.zip)
+- [rtltool.py](https://github.com/libretuya/ltchiptool/blob/master/ltchiptool/soc/ambz/util/rtltool.py)
 
-Downloading is done using UART2 (sometimes called Log_UART). Refer to your board documentation to find the correct pins.
+OTA1/2 files can be flashed using `ImageTool_v2.3.1_AmebaZ(8710b)`. Browse and select one of the files and enter an appropriate address. Select COM port, press `Open` and then `Download`.
-
-!!! important
-	It is required to put the chip into download mode, prior to flashing. This can be done by resetting the chip, while pulling UART2_TX to GND. If successful, the chip should print few garbage characters every second.
-
-## Automatically - using PlatformIO (recommended)
-
-LibreTuya has built-in firmware uploaders. 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 = COM60
-upload_port = COM60
-```
-
-## Manually - using `uf2upload`
-
-{%
-	include-markdown "../../ota/flashing.md"
-%}
-
-## Manually - using raw binaries/BkWriter
-
-There are two binary files in `.pio/build/my_board/`:
-
-- `image_0x00B000.ota1.bin`
-- `image_0x0D0000.ota2.bin`
-
-They can be flashed using `ImageTool_v2.3.1_AmebaZ(8710b)`. Browse and select one of the files and enter an appropriate address. Select COM port, press `Open` and then `Download`.
 
 This method is not recommended, as it requires you to know the currently enabled OTA index (1 or 2). Flashing the wrong file will either not make any changes, or upload firmware which won't run.
-
-!!! hint
-	Because the UART uploading code is programmed in the ROM of the chip, it can't be software-bricked, even if you damage the bootloader.

docs/requirements.txt

@@ -1,6 +1,6 @@
 mkdocs-material
 mkdocs-same-dir
-mkdocs-literate-nav
+mkdocs-literate-nav==0.5.0
 mkdocs-section-index
 mkdocs-include-markdown-plugin
 -e git+https://github.com/kuba2k2/mkdoxy#egg=mkdoxy