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