diff --git a/ports/esp32/README.md b/ports/esp32/README.md
index a8bada7510..bc24e5cd71 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 77aa192959..9d0016017f 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 bb32ba7559..36836da919 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 130f6b88c8..81c38a6ad4 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 4a81d227a0..fd20cb51bc 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 cf644f9038..7363333f86 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 6ebf16be1a..fde04d9c4b 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 c9794dba86..fd0c9edce0 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 525551df3b..d68a9baadd 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 c9b91641e5..dd47862d9f 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 a45d0434d9..a7098c9afa 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 6c72e60f80..724f47e1a9 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 4b6c09db3a..3a1e7ce359 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 d00bb673be..fe0e97f9f9 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 9a20a6a43d..0000000000
--- 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 15654341b4..087851ae5e 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 d8c212c5d2..0000000000
--- 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 de7a74d8a8..3eb9a5e0a7 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 e62b960ccd..cda26178d7 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 50dd2cc660..53a50f3286 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 4de9a7d4f7..b6cacf8c5c 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 24bced3cda..0000000000
--- 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 5b79d3195a..5b9a1935c9 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 b1a116e807..0000000000
--- 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 235d52a12d..19d2eb105f 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 3a6a21a522..0000000000
--- 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 0531582007..178219ce25 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 ea9bb56dbf..0000000000
--- 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 958f9adf51..3da4b33c12 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 4285b02753..0000000000
--- 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 0000000000..b200970409
--- /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 7e976ad630..4b3cd9b8fa 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 09f2ef8c23..0000000000
--- 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 0000000000..93e28d2275
--- /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 8efc4e5ab5..3d168b2505 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 d35d7a02fe..0000000000
--- 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 6b3ec0f067..4e3940005e 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 afe1ff1de8..0000000000
--- 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 122b411a30..7bf920d64c 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 0000000000..5dc696a24f
--- /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 4e0603a107..0000000000
--- 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 5ec7913c42..06584832bb 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 8c15d4d413..0000000000
--- 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 9bbf9058bb..9077ca6bb4 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 a46bc9bd1a..0000000000
--- 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 27ae46a249..5fea9e3a46 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 d65014e012..0000000000
--- 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 61dadcfb64..d1330239f1 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 bad7d7c7d8..0000000000
--- 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 64e683edfc..aa86a37215 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 016ba7cabb..0000000000
--- 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 941c69cdef..0000000000
--- 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 0000000000..ff7cbf9a46
--- /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 0000000000..c653330ca8
--- /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 5b3057087d..0000000000
--- 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 7f564a95e3..0000000000
--- 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 d6f6d03246..f7411f5980 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: