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 <angus@redyak.com.au>

57 files changed, 267 insertions, 755 deletions

diff --git a/ports/esp32/README.md b/ports/esp32/README.md
index a8bada751..bc24e5cd7 100644
--- a/ports/esp32/README.md
+++ b/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
diff --git a/ports/esp32/boards/ARDUINO_NANO_ESP32/board.json b/ports/esp32/boards/ARDUINO_NANO_ESP32/board.json
index 77aa19295..9d0016017 100644
--- a/ports/esp32/boards/ARDUINO_NANO_ESP32/board.json
+++ b/ports/esp32/boards/ARDUINO_NANO_ESP32/board.json
@@ -2,6 +2,9 @@
     "deploy": [
         "deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/ARDUINO_NANO_ESP32/deploy.md b/ports/esp32/boards/ARDUINO_NANO_ESP32/deploy.md
index bb32ba755..36836da91 100644
--- a/ports/esp32/boards/ARDUINO_NANO_ESP32/deploy.md
+++ b/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.
diff --git a/ports/esp32/boards/ESP32_GENERIC/board.json b/ports/esp32/boards/ESP32_GENERIC/board.json
index 130f6b88c..81c38a6ad 100644
--- a/ports/esp32/boards/ESP32_GENERIC/board.json
+++ b/ports/esp32/boards/ESP32_GENERIC/board.json
@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/ESP32_GENERIC_C3/board.json b/ports/esp32/boards/ESP32_GENERIC_C3/board.json
index 4a81d227a..fd20cb51b 100644
--- a/ports/esp32/boards/ESP32_GENERIC_C3/board.json
+++ b/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",
diff --git a/ports/esp32/boards/ESP32_GENERIC_C6/board.json b/ports/esp32/boards/ESP32_GENERIC_C6/board.json
index cf644f903..7363333f8 100644
--- a/ports/esp32/boards/ESP32_GENERIC_C6/board.json
+++ b/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",
diff --git a/ports/esp32/boards/ESP32_GENERIC_S2/board.json b/ports/esp32/boards/ESP32_GENERIC_S2/board.json
index 6ebf16be1..fde04d9c4 100644
--- a/ports/esp32/boards/ESP32_GENERIC_S2/board.json
+++ b/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",
diff --git a/ports/esp32/boards/ESP32_GENERIC_S3/board.json b/ports/esp32/boards/ESP32_GENERIC_S3/board.json
index c9794dba8..fd0c9edce 100644
--- a/ports/esp32/boards/ESP32_GENERIC_S3/board.json
+++ b/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",
diff --git a/ports/esp32/boards/LILYGO_TTGO_LORA32/board.json b/ports/esp32/boards/LILYGO_TTGO_LORA32/board.json
index 525551df3..d68a9baad 100644
--- a/ports/esp32/boards/LILYGO_TTGO_LORA32/board.json
+++ b/ports/esp32/boards/LILYGO_TTGO_LORA32/board.json
@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/LOLIN_C3_MINI/board.json b/ports/esp32/boards/LOLIN_C3_MINI/board.json
index c9b91641e..dd47862d9 100644
--- a/ports/esp32/boards/LOLIN_C3_MINI/board.json
+++ b/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",
diff --git a/ports/esp32/boards/LOLIN_S2_MINI/board.json b/ports/esp32/boards/LOLIN_S2_MINI/board.json
index a45d0434d..a7098c9af 100644
--- a/ports/esp32/boards/LOLIN_S2_MINI/board.json
+++ b/ports/esp32/boards/LOLIN_S2_MINI/board.json
@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "../deploy_s2.md"
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "External Flash",
diff --git a/ports/esp32/boards/LOLIN_S2_PICO/board.json b/ports/esp32/boards/LOLIN_S2_PICO/board.json
index 6c72e60f8..724f47e1a 100644
--- a/ports/esp32/boards/LOLIN_S2_PICO/board.json
+++ b/ports/esp32/boards/LOLIN_S2_PICO/board.json
@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "../deploy_s2.md"
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "Display",
diff --git a/ports/esp32/boards/M5STACK_ATOM/board.json b/ports/esp32/boards/M5STACK_ATOM/board.json
index 4b6c09db3..3a1e7ce35 100644
--- a/ports/esp32/boards/M5STACK_ATOM/board.json
+++ b/ports/esp32/boards/M5STACK_ATOM/board.json
@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "External Flash",
diff --git a/ports/esp32/boards/M5STACK_ATOMS3_LITE/board.json b/ports/esp32/boards/M5STACK_ATOMS3_LITE/board.json
index d00bb673b..fe0e97f9f 100644
--- a/ports/esp32/boards/M5STACK_ATOMS3_LITE/board.json
+++ b/ports/esp32/boards/M5STACK_ATOMS3_LITE/board.json
@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "https://docs.m5stack.com/en/core/AtomS3%20Lite",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/M5STACK_ATOMS3_LITE/deploy.md b/ports/esp32/boards/M5STACK_ATOMS3_LITE/deploy.md
deleted file mode 100644
index 9a20a6a43..000000000
--- a/ports/esp32/boards/M5STACK_ATOMS3_LITE/deploy.md
+++ /dev/null
@@ -1,22 +0,0 @@
-Program your board using the `esptool.py` program, found
-[here](https://github.com/espressif/esptool).
-
-To place the board in _bootloader mode_ - so `esptool`` can be used - press and
-hold the reset button for two seconds. A green LED will flash behind the reset
-button when the bootloader mode has been activated.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-From then on program the firmware starting at address 0:
-
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0 board-20240105-v1.22.1.bin
-```
-
-After the firmware has been deployed, press the reset button to reset the device
-and start the new firmware.
diff --git a/ports/esp32/boards/M5STACK_NANOC6/board.json b/ports/esp32/boards/M5STACK_NANOC6/board.json
index 15654341b..087851ae5 100644
--- a/ports/esp32/boards/M5STACK_NANOC6/board.json
+++ b/ports/esp32/boards/M5STACK_NANOC6/board.json
@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "deploy_nanoc6.md"
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/M5STACK_NANOC6/deploy_nanoc6.md b/ports/esp32/boards/M5STACK_NANOC6/deploy_nanoc6.md
deleted file mode 100644
index d8c212c5d..000000000
--- a/ports/esp32/boards/M5STACK_NANOC6/deploy_nanoc6.md
+++ /dev/null
@@ -1,18 +0,0 @@
-Program your board using the esptool.py program, found
-[here](https://github.com/espressif/esptool).
-
-To put the NanoC6 into 'update mode', hold the button while connecting the USB
-cable. It can be released after the connection is made.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-```bash
-esptool.py --chip esp32c6 --port /dev/ttyUSB0 erase_flash
-```
-
-From then on program the firmware starting at address 0x0:
-
-```bash
-esptool.py --chip esp32c6 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x0 M5STACK_NANOC6-20240602-v1.24.0.bin
-```
diff --git a/ports/esp32/boards/OLIMEX_ESP32_EVB/board.json b/ports/esp32/boards/OLIMEX_ESP32_EVB/board.json
index de7a74d8a..3eb9a5e0a 100644
--- a/ports/esp32/boards/OLIMEX_ESP32_EVB/board.json
+++ b/ports/esp32/boards/OLIMEX_ESP32_EVB/board.json
@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/OLIMEX_ESP32_POE/board.json b/ports/esp32/boards/OLIMEX_ESP32_POE/board.json
index e62b960cc..cda26178d 100644
--- a/ports/esp32/boards/OLIMEX_ESP32_POE/board.json
+++ b/ports/esp32/boards/OLIMEX_ESP32_POE/board.json
@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/SIL_WESP32/board.json b/ports/esp32/boards/SIL_WESP32/board.json
index 50dd2cc66..53a50f328 100644
--- a/ports/esp32/boards/SIL_WESP32/board.json
+++ b/ports/esp32/boards/SIL_WESP32/board.json
@@ -2,6 +2,9 @@
     "deploy": [
         "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_FEATHERS2/board.json b/ports/esp32/boards/UM_FEATHERS2/board.json
index 4de9a7d4f..b6cacf8c5 100644
--- a/ports/esp32/boards/UM_FEATHERS2/board.json
+++ b/ports/esp32/boards/UM_FEATHERS2/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "Battery Charging",
diff --git a/ports/esp32/boards/UM_FEATHERS2/deploy.md b/ports/esp32/boards/UM_FEATHERS2/deploy.md
deleted file mode 100644
index 24bced3cd..000000000
--- a/ports/esp32/boards/UM_FEATHERS2/deploy.md
+++ /dev/null
@@ -1,50 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your FeatherS2, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-```bash
-esptool.py --chip esp32s2 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s2 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options
-below, then use the following command to program the firmware starting at address
-0x1000, remembering to replace `feathers2-micropython-firmware-version.bin` with the
-name of the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 write_flash -z 0x1000 feathers2-micropython-firmware-version.bin
-```
-
-### Mac
-```bash
-esptool.py --chip esp32s2 --port /dev/cu.usbmodem01 write_flash -z 0x1000 feathers2-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s2 --port COM(X) write_flash -z 0x1000 feathers2-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_FEATHERS2NEO/board.json b/ports/esp32/boards/UM_FEATHERS2NEO/board.json
index 5b79d3195..5b9a1935c 100644
--- a/ports/esp32/boards/UM_FEATHERS2NEO/board.json
+++ b/ports/esp32/boards/UM_FEATHERS2NEO/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "Battery Charging",
diff --git a/ports/esp32/boards/UM_FEATHERS2NEO/deploy.md b/ports/esp32/boards/UM_FEATHERS2NEO/deploy.md
deleted file mode 100644
index b1a116e80..000000000
--- a/ports/esp32/boards/UM_FEATHERS2NEO/deploy.md
+++ /dev/null
@@ -1,50 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your FeatherS2 Neo, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-```bash
-esptool.py --chip esp32s2 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s2 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x1000,
-remembering to replace `feathers2neo-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 write_flash -z 0x1000 feathers2neo-micropython-firmware-version.bin
-```
-
-### Mac
-```bash
-esptool.py --chip esp32s2 --port /dev/cu.usbmodem01 write_flash -z 0x1000 feathers2neo-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s2 --port COM(X) write_flash -z 0x1000 feathers2-feathers2neo-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_FEATHERS3/board.json b/ports/esp32/boards/UM_FEATHERS3/board.json
index 235d52a12..19d2eb105 100644
--- a/ports/esp32/boards/UM_FEATHERS3/board.json
+++ b/ports/esp32/boards/UM_FEATHERS3/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_FEATHERS3/deploy.md b/ports/esp32/boards/UM_FEATHERS3/deploy.md
deleted file mode 100644
index 3a6a21a52..000000000
--- a/ports/esp32/boards/UM_FEATHERS3/deploy.md
+++ /dev/null
@@ -1,52 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your FeatherS3, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `feathers3-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 feathers3-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 feathers3-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 feathers3-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_FEATHERS3NEO/board.json b/ports/esp32/boards/UM_FEATHERS3NEO/board.json
index 053158200..178219ce2 100644
--- a/ports/esp32/boards/UM_FEATHERS3NEO/board.json
+++ b/ports/esp32/boards/UM_FEATHERS3NEO/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_FEATHERS3NEO/deploy.md b/ports/esp32/boards/UM_FEATHERS3NEO/deploy.md
deleted file mode 100644
index ea9bb56db..000000000
--- a/ports/esp32/boards/UM_FEATHERS3NEO/deploy.md
+++ /dev/null
@@ -1,52 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your FeatherS3 Neo, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `feathers3neo-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 feathers3neo-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 feathers3neo-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 feathers3neo-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_NANOS3/board.json b/ports/esp32/boards/UM_NANOS3/board.json
index 958f9adf5..3da4b33c1 100644
--- a/ports/esp32/boards/UM_NANOS3/board.json
+++ b/ports/esp32/boards/UM_NANOS3/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "./deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "Battery Charging",
diff --git a/ports/esp32/boards/UM_NANOS3/deploy.md b/ports/esp32/boards/UM_NANOS3/deploy.md
deleted file mode 100644
index 4285b0275..000000000
--- a/ports/esp32/boards/UM_NANOS3/deploy.md
+++ /dev/null
@@ -1,53 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your NANOS3, you have to first put it into download mode.
-NANOS3 doesn't include buttons for RESET and IO0, which should be provided by adding external buttons via a carrier board or other method.
-To put the NANOS3 into download, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `nanos3-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 nanos3-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 nanos3-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 nanos3-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_NANOS3/deploy_flashmode.md b/ports/esp32/boards/UM_NANOS3/deploy_flashmode.md
new file mode 100644
index 000000000..b20097040
--- /dev/null
+++ b/ports/esp32/boards/UM_NANOS3/deploy_flashmode.md
@@ -0,0 +1,9 @@
+To flash or erase your NANOS3, you have to first put it into download mode.
+NANOS3 doesn't include buttons for RESET and IO0, which should be provided by adding external buttons via a carrier board or other method.
+To put the NANOS3 into download, follow these steps:
+
+- Press and hold the [BOOT] button
+- Press and release the [RESET] button
+- Release the [BOOT] button
+
+Now the board is in download mode and the native USB will have enumerated as a serial device.
diff --git a/ports/esp32/boards/UM_OMGS3/board.json b/ports/esp32/boards/UM_OMGS3/board.json
index 7e976ad63..4b3cd9b8f 100644
--- a/ports/esp32/boards/UM_OMGS3/board.json
+++ b/ports/esp32/boards/UM_OMGS3/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "./deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "Battery Charging",
diff --git a/ports/esp32/boards/UM_OMGS3/deploy.md b/ports/esp32/boards/UM_OMGS3/deploy.md
deleted file mode 100644
index 09f2ef8c2..000000000
--- a/ports/esp32/boards/UM_OMGS3/deploy.md
+++ /dev/null
@@ -1,53 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your OMGS3, you have to first put it into download mode.
-OMGS3 doesn't include buttons for RESET and IO0, which should be provided by adding external buttons via a carrier board or other method.
-To put the OMGS3 into download, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `omgs3-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 omgs3-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 omgs3-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 omgs3-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_OMGS3/deploy_flashmode.md b/ports/esp32/boards/UM_OMGS3/deploy_flashmode.md
new file mode 100644
index 000000000..93e28d227
--- /dev/null
+++ b/ports/esp32/boards/UM_OMGS3/deploy_flashmode.md
@@ -0,0 +1,8 @@
+To flash or erase your OMGS3, you have to first put it into download mode.
+
+OMGS3 doesn't include buttons for RESET and IO0, which should be provided by adding external buttons via a carrier board or other method.
+To put the OMGS3 into download, follow these steps:
+
+- Press and hold the [BOOT] button
+- Press and release the [RESET] button
+- Release the [BOOT] button
diff --git a/ports/esp32/boards/UM_PROS3/board.json b/ports/esp32/boards/UM_PROS3/board.json
index 8efc4e5ab..3d168b250 100644
--- a/ports/esp32/boards/UM_PROS3/board.json
+++ b/ports/esp32/boards/UM_PROS3/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_PROS3/deploy.md b/ports/esp32/boards/UM_PROS3/deploy.md
deleted file mode 100644
index d35d7a02f..000000000
--- a/ports/esp32/boards/UM_PROS3/deploy.md
+++ /dev/null
@@ -1,52 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your ProS3, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `pros3-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 pros3-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 pros3-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 pros3-pros3-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_RGBTOUCH_MINI/board.json b/ports/esp32/boards/UM_RGBTOUCH_MINI/board.json
index 6b3ec0f06..4e3940005 100644
--- a/ports/esp32/boards/UM_RGBTOUCH_MINI/board.json
+++ b/ports/esp32/boards/UM_RGBTOUCH_MINI/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_RGBTOUCH_MINI/deploy.md b/ports/esp32/boards/UM_RGBTOUCH_MINI/deploy.md
deleted file mode 100644
index afe1ff1de..000000000
--- a/ports/esp32/boards/UM_RGBTOUCH_MINI/deploy.md
+++ /dev/null
@@ -1,52 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your RGB Touch Mini, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `rgbtouch_mini-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 rgbtouch_mini-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 rgbtouch_mini-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 rgbtouch_mini-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_TINYC6/board.json b/ports/esp32/boards/UM_TINYC6/board.json
index 122b411a3..7bf920d64 100644
--- a/ports/esp32/boards/UM_TINYC6/board.json
+++ b/ports/esp32/boards/UM_TINYC6/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy_tinyc6.md"
+        "deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "Battery Charging",
diff --git a/ports/esp32/boards/UM_TINYC6/deploy_flashmode.md b/ports/esp32/boards/UM_TINYC6/deploy_flashmode.md
new file mode 100644
index 000000000..5dc696a24
--- /dev/null
+++ b/ports/esp32/boards/UM_TINYC6/deploy_flashmode.md
@@ -0,0 +1,2 @@
+To put the TinyC6 into 'download mode', hold the _BOOT_ button while connecting
+the USB cable. It can be released after the connection is made.
diff --git a/ports/esp32/boards/UM_TINYC6/deploy_tinyc6.md b/ports/esp32/boards/UM_TINYC6/deploy_tinyc6.md
deleted file mode 100644
index 4e0603a10..000000000
--- a/ports/esp32/boards/UM_TINYC6/deploy_tinyc6.md
+++ /dev/null
@@ -1,18 +0,0 @@
-Program your board using the esptool.py program, found
-[here](https://github.com/espressif/esptool).
-
-To put the TinyC6 into 'download mode', hold the _BOOT_ button while connecting
-the USB cable. It can be released after the connection is made.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-```bash
-esptool.py --chip esp32c6 --port /dev/ttyUSB0 erase_flash
-```
-
-From then on program the firmware starting at address 0x0:
-
-```bash
-esptool.py --chip esp32c6 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x0 UM_TINYC6-20240602-v1.24.0.bin
-```
diff --git a/ports/esp32/boards/UM_TINYPICO/board.json b/ports/esp32/boards/UM_TINYPICO/board.json
index 5ec7913c4..06584832b 100644
--- a/ports/esp32/boards/UM_TINYPICO/board.json
+++ b/ports/esp32/boards/UM_TINYPICO/board.json
@@ -1,7 +1,10 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_TINYPICO/deploy.md b/ports/esp32/boards/UM_TINYPICO/deploy.md
deleted file mode 100644
index 8c15d4d41..000000000
--- a/ports/esp32/boards/UM_TINYPICO/deploy.md
+++ /dev/null
@@ -1,46 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-Your TinyPICO has an auto-reset circuit on it, so there is no need to put it into a
-download mode first to erase or flash it.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
-```
-
-### Mac
-```bash
-esptool.py --chip esp32 --port /dev/tty.SLAB_USBtoUART erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x1000,
-remembering to replace `tinypico-micropython-firmware-version.bin` with the name of the
-firmware you just downloaded:
-
-From then on program the firmware starting at address 0x1000:
-
-### Linux
-```bash
-esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 write_flash -z 0x1000 tinypico-micropython-firmware-version.bin
-```
-
-### Mac
-```bash
-esptool.py --chip esp32 --port /dev/tty.SLAB_USBtoUART --baud 921600 write_flash -z 0x1000 tinypico-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32 --port COM(X) --baud 921600 write_flash -z 0x1000 tinypico-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_TINYS2/board.json b/ports/esp32/boards/UM_TINYS2/board.json
index 9bbf9058b..9077ca6bb 100644
--- a/ports/esp32/boards/UM_TINYS2/board.json
+++ b/ports/esp32/boards/UM_TINYS2/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0x1000"
+    },
     "docs": "",
     "features": [
         "Battery Charging",
diff --git a/ports/esp32/boards/UM_TINYS2/deploy.md b/ports/esp32/boards/UM_TINYS2/deploy.md
deleted file mode 100644
index a46bc9bd1..000000000
--- a/ports/esp32/boards/UM_TINYS2/deploy.md
+++ /dev/null
@@ -1,50 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your TinyS2, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-```bash
-esptool.py --chip esp32s2 --port /dev/cu.usbmodem01 erase_flash
-```
-
-#### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s2 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x1000,
-remembering to replace `tinys2-micropython-firmware-version.bin` with the name of the
-firmware you just downloaded:
-
-#### Linux
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 write_flash -z 0x1000 tinys2-micropython-firmware-version.bin
-```
-
-#### Mac
-```bash
-esptool.py --chip esp32s2 --port /dev/cu.usbmodem01 write_flash -z 0x1000 tinys2-micropython-firmware-version.bin
-```
-
-#### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s2 --port COM(X) write_flash -z 0x1000 tinys2-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_TINYS3/board.json b/ports/esp32/boards/UM_TINYS3/board.json
index 27ae46a24..5fea9e3a4 100644
--- a/ports/esp32/boards/UM_TINYS3/board.json
+++ b/ports/esp32/boards/UM_TINYS3/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_TINYS3/deploy.md b/ports/esp32/boards/UM_TINYS3/deploy.md
deleted file mode 100644
index d65014e01..000000000
--- a/ports/esp32/boards/UM_TINYS3/deploy.md
+++ /dev/null
@@ -1,52 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your TinyS3, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `tinys3-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 tinys3-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 tinys3-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 tinys3-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/UM_TINYWATCHS3/board.json b/ports/esp32/boards/UM_TINYWATCHS3/board.json
index 61dadcfb6..d1330239f 100644
--- a/ports/esp32/boards/UM_TINYWATCHS3/board.json
+++ b/ports/esp32/boards/UM_TINYWATCHS3/board.json
@@ -1,7 +1,11 @@
 {
     "deploy": [
-        "deploy.md"
+        "../deploy_flashmode.md",
+        "../deploy_nativeusb.md"
     ],
+    "deploy_options": {
+        "flash_offset": "0"
+    },
     "docs": "",
     "features": [
         "BLE",
diff --git a/ports/esp32/boards/UM_TINYWATCHS3/deploy.md b/ports/esp32/boards/UM_TINYWATCHS3/deploy.md
deleted file mode 100644
index bad7d7c7d..000000000
--- a/ports/esp32/boards/UM_TINYWATCHS3/deploy.md
+++ /dev/null
@@ -1,52 +0,0 @@
-Program your board using the latest version of the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-To flash or erase your TinyWATCH S3, you have to first put it into download mode.
-To do this, follow these steps:
-
-- Press and hold the [BOOT] button
-- Press and release the [RESET] button
-- Release the [BOOT] button
-
-Now the board is in download mode and the native USB will have enumerated as a serial device.
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 erase_flash
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) erase_flash
-```
-
-Now download the version of the firmware you would like to install from the options below,
-then use the following command to program the firmware starting at address 0x0,
-remembering to replace `tinywatchs3-micropython-firmware-version.bin` with the name of
-the firmware you just downloaded:
-
-### Linux
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0x0 tinywatchs3-micropython-firmware-version.bin
-```
-
-### Mac
-Please do a `ls /dev/cu.usbm*` to determine the port your board has enumerated as.
-```bash
-esptool.py --chip esp32s3 --port /dev/cu.usbmodem01 write_flash -z 0x0 tinywatchs3-micropython-firmware-version.bin
-```
-
-### Windows
-Change (X) to whatever COM port is being used by the board
-```bash
-esptool --chip esp32s3 --port COM(X) write_flash -z 0x0 tinywatchs3-micropython-firmware-version.bin
-```
diff --git a/ports/esp32/boards/deploy.md b/ports/esp32/boards/deploy.md
index 64e683edf..aa86a3721 100644
--- a/ports/esp32/boards/deploy.md
+++ b/ports/esp32/boards/deploy.md
@@ -1,14 +1,54 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
+Program your board using the esptool.py program, found [here](https://docs.espressif.com/projects/esptool/en/latest/{mcu}/).
+
+*Windows users:* You may find the installed program is called `esptool` instead of `esptool.py`.
+
+### Erasing
 
 If you are putting MicroPython on your board for the first time then you should
 first erase the entire flash using:
 
 ```bash
-esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
+esptool.py erase_flash
 ```
 
-From then on program the firmware starting at address 0x1000:
+`esptool.py` will try to detect the serial port with the ESP32 automatically,
+but if this fails or there might be more than one Espressif-based device
+attached to your computer then pass the `--port` option with the name of the
+target serial port. For example:
 
 ```bash
-esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x1000 esp32-20190125-v1.10.bin
+esptool.py --port PORTNAME erase_flash
 ```
+
+* On Linux, the port name is usually similar to `/dev/ttyUSB` or `/dev/ttyACM0`.
+* On Mac, the port name is usually similar to `/dev/cu.usbmodem01`.
+* On Windows, the port name is usually similar to `COM4`.
+
+### Flashing
+
+Then deploy the firmware to the board, starting at address {deploy_options[flash_offset]}:
+
+```bash
+esptool.py --baud 460800 write_flash {deploy_options[flash_offset]} ESP32_BOARD_NAME-DATE-VERSION.bin
+```
+
+Replace `ESP32_BOARD_NAME-DATE-VERSION.bin` with the `.bin` file downloaded from this page.
+
+As above, if `esptool.py` can't automatically detect the serial port
+then you can pass it explicitly on the command line instead. For example:
+
+```bash
+esptool.py --port PORTNAME --baud 460800 write_flash {deploy_options[flash_offset]} ESP32_BOARD_NAME-DATE-VERSION.bin
+```
+
+### Troubleshooting
+
+If flashing starts and then fails partway through, try removing the `--baud
+460800` option to flash at the slower default speed.
+
+If these steps don't work, consult the [MicroPython ESP32 Troubleshooting
+steps](https://docs.micropython.org/en/latest/esp32/tutorial/intro.html#troubleshooting-installation-problems)
+and the [esptool
+documentation](https://docs.espressif.com/projects/esptool/en/latest/{mcu}/esptool/basic-options.html).
+
+**Important**: From the options below, download the ``.bin`` file for your board.
diff --git a/ports/esp32/boards/deploy_c3.md b/ports/esp32/boards/deploy_c3.md
deleted file mode 100644
index 016ba7cab..000000000
--- a/ports/esp32/boards/deploy_c3.md
+++ /dev/null
@@ -1,14 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-```bash
-esptool.py --chip esp32c3 --port /dev/ttyUSB0 erase_flash
-```
-
-From then on program the firmware starting at address 0x0:
-
-```bash
-esptool.py --chip esp32c3 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x0 esp32c3-20220117-v1.18.bin
-```
diff --git a/ports/esp32/boards/deploy_c6.md b/ports/esp32/boards/deploy_c6.md
deleted file mode 100644
index 941c69cde..000000000
--- a/ports/esp32/boards/deploy_c6.md
+++ /dev/null
@@ -1,14 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-```bash
-esptool.py --chip esp32c6 --port /dev/ttyUSB0 erase_flash
-```
-
-From then on program the firmware starting at address 0x0:
-
-```bash
-esptool.py --chip esp32c6 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x0 ESP32_GENERIC_C6-20240602-v1.24.0.bin
-```
diff --git a/ports/esp32/boards/deploy_flashmode.md b/ports/esp32/boards/deploy_flashmode.md
new file mode 100644
index 000000000..ff7cbf9a4
--- /dev/null
+++ b/ports/esp32/boards/deploy_flashmode.md
@@ -0,0 +1,9 @@
+To flash or erase your {product}, you have to first put it into download mode.
+
+To put the {product} into download, follow these steps:
+
+- Press and hold the [BOOT] button
+- Press and release the [RESET] button
+- Release the [BOOT] button
+
+Now the board is in download mode and the native USB will have enumerated as a serial device.
diff --git a/ports/esp32/boards/deploy_nativeusb.md b/ports/esp32/boards/deploy_nativeusb.md
new file mode 100644
index 000000000..c653330ca
--- /dev/null
+++ b/ports/esp32/boards/deploy_nativeusb.md
@@ -0,0 +1,51 @@
+Program your board using the esptool.py program, found [here](https://docs.espressif.com/projects/esptool/en/latest/{mcu}/).
+
+*Windows users:* You may find the installed program is called `esptool` instead of `esptool.py`.
+
+### Erasing
+
+If you are putting MicroPython on your board for the first time then you should
+first erase the entire flash using:
+
+```bash
+esptool.py erase_flash
+```
+
+`esptool.py` will try to detect the serial port with the ESP32 automatically,
+but if this fails or there might be more than one Espressif-based device
+attached to your computer then pass the `--port` option with the name of the
+target serial port. For example:
+
+```bash
+esptool.py --port PORTNAME erase_flash
+```
+
+* On Linux, the port name is usually similar to `/dev/ttyACM0`.
+* On Mac, the port name is usually similar to `/dev/cu.usbmodem01`.
+* On Windows, the port name is usually similar to `COM4`.
+
+### Flashing
+
+Then deploy the firmware to the board, starting at address {deploy_options[flash_offset]}:
+
+```bash
+esptool.py write_flash {deploy_options[flash_offset]} ESP32_BOARD_NAME-DATE-VERSION.bin
+```
+
+Replace `ESP32_BOARD_NAME-DATE-VERSION.bin` with the `.bin` file downloaded from this page.
+
+As above, if `esptool.py` can't automatically detect the serial port
+then you can pass it explicitly on the command line instead. For example:
+
+```bash
+esptool.py --port PORTNAME write_flash {deploy_options[flash_offset]} ESP32_BOARD_NAME-DATE-VERSION.bin
+```
+
+### Troubleshooting
+
+If these steps don't work, consult the [MicroPython ESP32 Troubleshooting
+steps](https://docs.micropython.org/en/latest/esp32/tutorial/intro.html#troubleshooting-installation-problems)
+and the [esptool
+documentation](https://docs.espressif.com/projects/esptool/en/latest/{mcu}/esptool/basic-options.html).
+
+**Important**: From the options below, download the ``.bin`` file for your board.
diff --git a/ports/esp32/boards/deploy_s2.md b/ports/esp32/boards/deploy_s2.md
deleted file mode 100644
index 5b3057087..000000000
--- a/ports/esp32/boards/deploy_s2.md
+++ /dev/null
@@ -1,14 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 erase_flash
-```
-
-From then on program the firmware starting at address 0x1000:
-
-```bash
-esptool.py --chip esp32s2 --port /dev/ttyACM0 write_flash -z 0x1000 board-20210902-v1.17.bin
-```
diff --git a/ports/esp32/boards/deploy_s3.md b/ports/esp32/boards/deploy_s3.md
deleted file mode 100644
index 7f564a95e..000000000
--- a/ports/esp32/boards/deploy_s3.md
+++ /dev/null
@@ -1,14 +0,0 @@
-Program your board using the esptool.py program, found [here](https://github.com/espressif/esptool).
-
-If you are putting MicroPython on your board for the first time then you should
-first erase the entire flash using:
-
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 erase_flash
-```
-
-From then on program the firmware starting at address 0:
-
-```bash
-esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0 board-20210902-v1.17.bin
-```
diff --git a/tools/autobuild/build-downloads.py b/tools/autobuild/build-downloads.py
index d6f6d0324..f7411f598 100755
--- a/tools/autobuild/build-downloads.py
+++ b/tools/autobuild/build-downloads.py
@@ -91,7 +91,18 @@ def main(repo_path, output_path):
                 f.write("\n\n## Installation instructions\n")
             for deploy in blob["deploy"]:
                 with open(os.path.join(board_dir, deploy), "r") as fin:
-                    f.write(fin.read())
+                    body = fin.read()
+                    # any key in the board.json file can be substituted via Python str.format()
+                    try:
+                        body = body.format(**blob)
+                    except Exception as e:
+                        raise RuntimeError(
+                            "Failed to format deploy file {} according to {}: {}".format(
+                                fin.name, board_json, e
+                            )
+                        )
+                    f.write(body)
+                    f.write("\n")
 
     # Write the full index for the website to load.
     with open(os.path.join(output_path, "index.json"), "w") as f: