tools/autobuild,esp32: Template the generation of esp32 port deploy.md.

Allows two source files (ports/esp32/boards/deploy.md and
deploy_nativeusb.md for boards with only native USB) for all esp32
installation steps, with templated chip name and flash offset inserted via
string formatting.

The new files add more text to explain the esptool.py port auto-detection,
remove the unnecessary -z feature (already enabled by default), and add
a bit of troubleshooting and port detection info.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

Author: projectgus

ports/esp32/README.md

@@ -229,6 +229,15 @@ files that configure ESP-IDF settings.  Some standard `sdkconfig` files are
 provided in the `boards/` directory, like `boards/sdkconfig.ble`.  You can
 also define custom ones in your board directory.
 
+Deployment instructions usually invoke the `boards/deploy.md` file (for boards
+with a USB/Serial converter connection), or the `boards/deploy_nativeusb.md`
+file (for boards with only a native USB port connection). These files are
+formatted for each board using template strings found in the `boards.json`
+files. You can also include the common `boards/deploy_flashmode.md` file if you
+have a board which requires manual resetting via the RESET and BOOT buttons.
+Boards with unique flashing steps can include custom `deploy.md` file(s).
+Existing `board.json` files contain examples of all of these combinations.
+
 See existing board definitions for further examples of configuration.
 
 Configuration

ports/esp32/boards/ARDUINO_NANO_ESP32/board.json

@@ -2,6 +2,9 @@
     "deploy": [
         "deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",

ports/esp32/boards/ARDUINO_NANO_ESP32/deploy.md

@@ -11,3 +11,5 @@ Please note that the DFU bootloader comes factory flashed. Should you for any re
 entire flash, the DFU bootloader will have to be re-installed. Please follow the instructions
 [here](https://support.arduino.cc/hc/en-us/articles/9810414060188-Reset-the-Arduino-bootloader-on-the-Nano-ESP32)
 to do so.
+
+**Important** From the options below, download the `.app-bin` file for your board.

ports/esp32/boards/ESP32_GENERIC/board.json

@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",

ports/esp32/boards/ESP32_GENERIC_C3/board.json

@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "../deploy_c3.md"
+        "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",

ports/esp32/boards/ESP32_GENERIC_C6/board.json

@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "../deploy_c6.md"
+        "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",

ports/esp32/boards/ESP32_GENERIC_S2/board.json

@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "../deploy_s2.md"
+        "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "External Flash",

ports/esp32/boards/ESP32_GENERIC_S3/board.json

@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "../deploy_s3.md"
+        "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",

ports/esp32/boards/LILYGO_TTGO_LORA32/board.json

@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",

ports/esp32/boards/LOLIN_C3_MINI/board.json

@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "../deploy_c3.md"
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",