jepler/circuitpython
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

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

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

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>
This commit is contained in:
Angus Gratton 2025-01-07 14:19:11 +11:00 committed by Damien George
parent b6649b922e
commit d89e71e6c0
57 changed files with 267 additions and 755 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
ports/esp32/README.md
View file

@ -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

3
ports/esp32/boards/ARDUINO_NANO_ESP32/board.json
View file

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

2
ports/esp32/boards/ARDUINO_NANO_ESP32/deploy.md
View file

@ -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.

3
ports/esp32/boards/ESP32_GENERIC/board.json
View file

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

5
ports/esp32/boards/ESP32_GENERIC_C3/board.json
View file

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

5
ports/esp32/boards/ESP32_GENERIC_C6/board.json
View file

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

5
ports/esp32/boards/ESP32_GENERIC_S2/board.json
View file

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

5
ports/esp32/boards/ESP32_GENERIC_S3/board.json
View file

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

3
ports/esp32/boards/LILYGO_TTGO_LORA32/board.json
View file

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

5
ports/esp32/boards/LOLIN_C3_MINI/board.json
View file

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

5
ports/esp32/boards/LOLIN_S2_MINI/board.json
View file

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

5
ports/esp32/boards/LOLIN_S2_PICO/board.json
View file

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

3
ports/esp32/boards/M5STACK_ATOM/board.json
View file

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

5
ports/esp32/boards/M5STACK_ATOMS3_LITE/board.json
View file

@ -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",

22
ports/esp32/boards/M5STACK_ATOMS3_LITE/deploy.md
View file

@ -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.

5
ports/esp32/boards/M5STACK_NANOC6/board.json
View file

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

18
ports/esp32/boards/M5STACK_NANOC6/deploy_nanoc6.md
View file

@ -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
```

3
ports/esp32/boards/OLIMEX_ESP32_EVB/board.json
View file

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

3
ports/esp32/boards/OLIMEX_ESP32_POE/board.json
View file

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

3
ports/esp32/boards/SIL_WESP32/board.json
View file

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

6
ports/esp32/boards/UM_FEATHERS2/board.json
View file

@ -1,7 +1,11 @@
{
"deploy": [
"deploy.md"
"../deploy_flashmode.md",
"../deploy_nativeusb.md"
],
"deploy_options": {
"flash_offset": "0x1000"
},
"docs": "",
"features": [
"Battery Charging",

50
ports/esp32/boards/UM_FEATHERS2/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_FEATHERS2NEO/board.json
View file

@ -1,7 +1,11 @@
{
"deploy": [
"deploy.md"
"../deploy_flashmode.md",
"../deploy_nativeusb.md"
],
"deploy_options": {
"flash_offset": "0x1000"
},
"docs": "",
"features": [
"Battery Charging",

50
ports/esp32/boards/UM_FEATHERS2NEO/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_FEATHERS3/board.json
View file

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

52
ports/esp32/boards/UM_FEATHERS3/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_FEATHERS3NEO/board.json
View file

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

52
ports/esp32/boards/UM_FEATHERS3NEO/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_NANOS3/board.json
View file

@ -1,7 +1,11 @@
{
"deploy": [
"deploy.md"
"./deploy_flashmode.md",
"../deploy_nativeusb.md"
],
"deploy_options": {
"flash_offset": "0"
},
"docs": "",
"features": [
"Battery Charging",

53
ports/esp32/boards/UM_NANOS3/deploy.md
View file

@ -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
```

9
ports/esp32/boards/UM_NANOS3/deploy_flashmode.md Normal file
View file

@ -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.

6
ports/esp32/boards/UM_OMGS3/board.json
View file

@ -1,7 +1,11 @@
{
"deploy": [
"deploy.md"
"./deploy_flashmode.md",
"../deploy_nativeusb.md"
],
"deploy_options": {
"flash_offset": "0"
},
"docs": "",
"features": [
"Battery Charging",

53
ports/esp32/boards/UM_OMGS3/deploy.md
View file

@ -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
```

8
ports/esp32/boards/UM_OMGS3/deploy_flashmode.md Normal file
View file

@ -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

6
ports/esp32/boards/UM_PROS3/board.json
View file

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

52
ports/esp32/boards/UM_PROS3/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_RGBTOUCH_MINI/board.json
View file

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

52
ports/esp32/boards/UM_RGBTOUCH_MINI/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_TINYC6/board.json
View file

@ -1,7 +1,11 @@
{
"deploy": [
"deploy_tinyc6.md"
"deploy_flashmode.md",
"../deploy_nativeusb.md"
],
"deploy_options": {
"flash_offset": "0"
},
"docs": "",
"features": [
"Battery Charging",

2
ports/esp32/boards/UM_TINYC6/deploy_flashmode.md Normal file
View file

@ -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.

18
ports/esp32/boards/UM_TINYC6/deploy_tinyc6.md
View file

@ -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
```

5
ports/esp32/boards/UM_TINYPICO/board.json
View file

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

46
ports/esp32/boards/UM_TINYPICO/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_TINYS2/board.json
View file

@ -1,7 +1,11 @@
{
"deploy": [
"deploy.md"
"../deploy_flashmode.md",
"../deploy_nativeusb.md"
],
"deploy_options": {
"flash_offset": "0x1000"
},
"docs": "",
"features": [
"Battery Charging",

50
ports/esp32/boards/UM_TINYS2/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_TINYS3/board.json
View file

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

52
ports/esp32/boards/UM_TINYS3/deploy.md
View file

@ -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
```

6
ports/esp32/boards/UM_TINYWATCHS3/board.json
View file

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

52
ports/esp32/boards/UM_TINYWATCHS3/deploy.md
View file

@ -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
```

48
ports/esp32/boards/deploy.md
View file

@ -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.

14
ports/esp32/boards/deploy_c3.md
View file

@ -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
```

14
ports/esp32/boards/deploy_c6.md
View file

@ -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
```

9
ports/esp32/boards/deploy_flashmode.md Normal file
View file

@ -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.

51
ports/esp32/boards/deploy_nativeusb.md Normal file
View file

@ -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.

14
ports/esp32/boards/deploy_s2.md
View file

@ -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
```

14
ports/esp32/boards/deploy_s3.md
View file

@ -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
```

13
tools/autobuild/build-downloads.py
View file

@ -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: