[docs] Refactor docs structure, add project upload guides

SUMMARY.md

@@ -1,40 +1,29 @@
 * [Home](README.md)
-* 😊 Getting started
+* [😊 Getting started](docs/getting-started/README.md)
-	* [Start here](docs/getting-started/README.md)
+* [📲 Flashing/dumping](docs/flashing/)
-	* [Uploading](docs/getting-started/uploading.md)
+* [💻 Supported boards & chips](docs/status/supported.md)
-	* [Options & config](docs/reference/config.md)
+* 📖 Reference
-	* Examples
+	* [🔧 LT configuration](docs/reference/config.md)
-		* [PinScan](examples/PinScan/README.md)
+	* [✔️ Implementation status](docs/status/arduino.md)
-	* [ESPHome port](docs/projects/esphome.md)
+	* [🔌 Boards documentation](boards/)
-	* [Using tuya-cloudcutter](docs/getting-started/cloudcutter.md)
+	* [🔋 Examples](examples/)
-	* [Auto-download-reboot](docs/getting-started/adr.md)
+	* Chip families
-* [💻 Boards & CPU list](docs/status/supported.md)
+		* [Beken BK72xx](docs/platform/beken-72xx/README.md)
-* [✔️ Implementation status](docs/status/arduino.md)
+		* Realtek AmebaZ Series
-* Supported chip families
+			* [General info](docs/platform/realtek/README.md)
-	* Beken BK72xx
+			* [Debugging](docs/platform/realtek/debugging.md)
-		* [General info](docs/platform/beken-72xx/README.md)
+			* [Exception decoder](docs/platform/realtek/exception-decoder.md)
-		* [Flashing](docs/platform/beken-72xx/flashing.md)
+			* C library
-		* [Dumping](docs/platform/beken-72xx/dumping.md)
+				* [Built-in functions](docs/platform/realtek-ambz/stdlib.md)
-	* Realtek AmebaZ Series
+				* [Memory management](docs/platform/realtek-ambz/memory-management.md)
-		* [General info](docs/platform/realtek/README.md)
+	* [📖 LibreTuya API](docs/reference/lt-api.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)
 		* [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)

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)

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/<board>/` or `.esphome/build/<board>/.pioenvs/<board>/`).
-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.

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/<yourdevice>/.pioenvs/<yourdevice>/`. 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"
+%}

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.

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.

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.

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.

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 <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 <FAMILY> <FILE>` - make a full flash dump of the connected device; specifying the family is required
+- `ltchiptool flash write <FILE>` - 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 <FAMILY>` and `-s <START OFFSET>`.
+
+### 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
+```

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/<my_board>/`. 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"
+%}

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
+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).
-	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.
 
 ## 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"
+%}

docs/getting-started/uploading.md

@@ -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.

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):
+	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
+	```ini
-    [env:my_board]
+	[env:my_board]
-    lib_compat_mode = off
+	lib_compat_mode = off
-    ```
+	```
 
 ## MQTT
 Tested with `realtek-ambz`.

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)
+	- [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)
+	- [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)
+	- [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)
+	- [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.

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`:
-  - for `DIFF32`:
+		- difference value (signed int 32-bit)
-
+		- offset table (`length-4` bytes)
-    - difference value (signed int 32-bit)
-
-	- offset table (`length-4` bytes)
 
 The presented structure can be repeated in a single binpatch tag.
 

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

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

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:
+	On Raspberry Pi 4, additional config might be needed:
-    ```
+	```
-    bcm2835gpio peripheral_base 0xFE000000
+	bcm2835gpio peripheral_base 0xFE000000
-    bcm2835gpio speed_coeffs 236181 60
+	bcm2835gpio speed_coeffs 236181 60
-    ```
+	```
-    Save the lines to a .cfg file, and pass it to OpenOCD using `-f file.cfg`.
+	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).
+	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

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).

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
+!!! tip
-    Values in parentheses represent the defaults for the config options.
+	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
+!!! 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.
+	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:
+	This can be used, for example, to enable only "important" messages:
-    ```ini
+	```ini
-    [env:my_board]
+	[env:my_board]
-    build_flags =
+	build_flags =
-      -D LT_LOGLEVEL=LT_LEVEL_WARN
+	  -D LT_LOGLEVEL=LT_LEVEL_WARN
-      -D LT_DEBUG_ALL=1 # will print only warnings and errors from all modules
+	  -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.

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

docs/requirements.txt

@@ -1,3 +1,4 @@
+mkdocs-material
 mkdocs-same-dir
 mkdocs-literate-nav
 mkdocs-section-index

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"
 %}

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"
 %}

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

examples/SUMMARY.md

@@ -0,0 +1,3 @@
+# Examples
+
+* [PinScan](PinScan/README.md)