From d89e71e6c08b7dff21967868887f4503fc8ac5aa Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 7 Jan 2025 14:19:11 +1100 Subject: [PATCH] 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 --- ports/esp32/README.md | 9 ++++ .../boards/ARDUINO_NANO_ESP32/board.json | 3 ++ .../esp32/boards/ARDUINO_NANO_ESP32/deploy.md | 2 + ports/esp32/boards/ESP32_GENERIC/board.json | 3 ++ .../esp32/boards/ESP32_GENERIC_C3/board.json | 5 +- .../esp32/boards/ESP32_GENERIC_C6/board.json | 5 +- .../esp32/boards/ESP32_GENERIC_S2/board.json | 5 +- .../esp32/boards/ESP32_GENERIC_S3/board.json | 5 +- .../boards/LILYGO_TTGO_LORA32/board.json | 3 ++ ports/esp32/boards/LOLIN_C3_MINI/board.json | 5 +- ports/esp32/boards/LOLIN_S2_MINI/board.json | 5 +- ports/esp32/boards/LOLIN_S2_PICO/board.json | 5 +- ports/esp32/boards/M5STACK_ATOM/board.json | 3 ++ .../boards/M5STACK_ATOMS3_LITE/board.json | 5 +- .../boards/M5STACK_ATOMS3_LITE/deploy.md | 22 -------- ports/esp32/boards/M5STACK_NANOC6/board.json | 5 +- .../boards/M5STACK_NANOC6/deploy_nanoc6.md | 18 ------- .../esp32/boards/OLIMEX_ESP32_EVB/board.json | 3 ++ .../esp32/boards/OLIMEX_ESP32_POE/board.json | 3 ++ ports/esp32/boards/SIL_WESP32/board.json | 3 ++ ports/esp32/boards/UM_FEATHERS2/board.json | 6 ++- ports/esp32/boards/UM_FEATHERS2/deploy.md | 50 ----------------- ports/esp32/boards/UM_FEATHERS2NEO/board.json | 6 ++- ports/esp32/boards/UM_FEATHERS2NEO/deploy.md | 50 ----------------- ports/esp32/boards/UM_FEATHERS3/board.json | 6 ++- ports/esp32/boards/UM_FEATHERS3/deploy.md | 52 ------------------ ports/esp32/boards/UM_FEATHERS3NEO/board.json | 6 ++- ports/esp32/boards/UM_FEATHERS3NEO/deploy.md | 52 ------------------ ports/esp32/boards/UM_NANOS3/board.json | 6 ++- ports/esp32/boards/UM_NANOS3/deploy.md | 53 ------------------- .../boards/UM_NANOS3/deploy_flashmode.md | 9 ++++ ports/esp32/boards/UM_OMGS3/board.json | 6 ++- ports/esp32/boards/UM_OMGS3/deploy.md | 53 ------------------- .../esp32/boards/UM_OMGS3/deploy_flashmode.md | 8 +++ ports/esp32/boards/UM_PROS3/board.json | 6 ++- ports/esp32/boards/UM_PROS3/deploy.md | 52 ------------------ .../esp32/boards/UM_RGBTOUCH_MINI/board.json | 6 ++- ports/esp32/boards/UM_RGBTOUCH_MINI/deploy.md | 52 ------------------ ports/esp32/boards/UM_TINYC6/board.json | 6 ++- .../boards/UM_TINYC6/deploy_flashmode.md | 2 + ports/esp32/boards/UM_TINYC6/deploy_tinyc6.md | 18 ------- ports/esp32/boards/UM_TINYPICO/board.json | 5 +- ports/esp32/boards/UM_TINYPICO/deploy.md | 46 ---------------- ports/esp32/boards/UM_TINYS2/board.json | 6 ++- ports/esp32/boards/UM_TINYS2/deploy.md | 50 ----------------- ports/esp32/boards/UM_TINYS3/board.json | 6 ++- ports/esp32/boards/UM_TINYS3/deploy.md | 52 ------------------ ports/esp32/boards/UM_TINYWATCHS3/board.json | 6 ++- ports/esp32/boards/UM_TINYWATCHS3/deploy.md | 52 ------------------ ports/esp32/boards/deploy.md | 48 +++++++++++++++-- ports/esp32/boards/deploy_c3.md | 14 ----- ports/esp32/boards/deploy_c6.md | 14 ----- ports/esp32/boards/deploy_flashmode.md | 9 ++++ ports/esp32/boards/deploy_nativeusb.md | 51 ++++++++++++++++++ ports/esp32/boards/deploy_s2.md | 14 ----- ports/esp32/boards/deploy_s3.md | 14 ----- tools/autobuild/build-downloads.py | 13 ++++- 57 files changed, 267 insertions(+), 755 deletions(-) delete mode 100644 ports/esp32/boards/M5STACK_ATOMS3_LITE/deploy.md delete mode 100644 ports/esp32/boards/M5STACK_NANOC6/deploy_nanoc6.md delete mode 100644 ports/esp32/boards/UM_FEATHERS2/deploy.md delete mode 100644 ports/esp32/boards/UM_FEATHERS2NEO/deploy.md delete mode 100644 ports/esp32/boards/UM_FEATHERS3/deploy.md delete mode 100644 ports/esp32/boards/UM_FEATHERS3NEO/deploy.md delete mode 100644 ports/esp32/boards/UM_NANOS3/deploy.md create mode 100644 ports/esp32/boards/UM_NANOS3/deploy_flashmode.md delete mode 100644 ports/esp32/boards/UM_OMGS3/deploy.md create mode 100644 ports/esp32/boards/UM_OMGS3/deploy_flashmode.md delete mode 100644 ports/esp32/boards/UM_PROS3/deploy.md delete mode 100644 ports/esp32/boards/UM_RGBTOUCH_MINI/deploy.md create mode 100644 ports/esp32/boards/UM_TINYC6/deploy_flashmode.md delete mode 100644 ports/esp32/boards/UM_TINYC6/deploy_tinyc6.md delete mode 100644 ports/esp32/boards/UM_TINYPICO/deploy.md delete mode 100644 ports/esp32/boards/UM_TINYS2/deploy.md delete mode 100644 ports/esp32/boards/UM_TINYS3/deploy.md delete mode 100644 ports/esp32/boards/UM_TINYWATCHS3/deploy.md delete mode 100644 ports/esp32/boards/deploy_c3.md delete mode 100644 ports/esp32/boards/deploy_c6.md create mode 100644 ports/esp32/boards/deploy_flashmode.md create mode 100644 ports/esp32/boards/deploy_nativeusb.md delete mode 100644 ports/esp32/boards/deploy_s2.md delete mode 100644 ports/esp32/boards/deploy_s3.md 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: