docs: use esptool 5.x hyphenated commands

- write-flash / erase-flash / merge-bin instead of the deprecated
  write_flash / erase_flash / merge_bin
- esptool instead of esptool.py
- hyphenated --flash-mode/--flash-freq/--flash-size for merge-bin
- note that esptool 4.x still works but prints the deprecation warning
This commit is contained in:
Michael Holzmann 2026-11-14 15:53:56 +00:00
parent 593a426d4f
commit 83683de27c
1 changed files with 13 additions and 8 deletions

View File

@ -197,7 +197,7 @@ Everything is written to the hidden `.pio/build/esp32dev/` directory:
- `pio run -t upload` flashes all three images automatically at the usual - `pio run -t upload` flashes all three images automatically at the usual
offsets: `bootloader.bin` at `0x1000`, `partitions.bin` at `0x8000`, offsets: `bootloader.bin` at `0x1000`, `partitions.bin` at `0x8000`,
`firmware.bin` at `0x10000`. `firmware.bin` at `0x10000`.
- For OTA updates or a manual `esptool.py` write, `firmware.bin` is the image - For OTA updates or a manual `esptool` write, `firmware.bin` is the image
you need. you need.
- `firmware.elf` is used to decode crash backtraces, e.g. - `firmware.elf` is used to decode crash backtraces, e.g.
`xtensa-esp32-elf-addr2line -pfiaC -e .pio/build/esp32dev/firmware.elf <addr>`, `xtensa-esp32-elf-addr2line -pfiaC -e .pio/build/esp32dev/firmware.elf <addr>`,
@ -233,15 +233,20 @@ PlatformIO, or a machine that only has the pre-built images, flash the three
partitions yourself. partitions yourself.
```bash ```bash
pip install esptool # esptool 5.x installs the command as `esptool` pip install esptool
``` ```
esptool **5.x** installs the `esptool` command and uses hyphenated subcommands
(`write-flash`, `erase-flash`, `merge-bin`). The older esptool **4.x** used
`esptool.py` with underscores (`write_flash`); that still works but prints
`Command 'write_flash' is deprecated`, so prefer the 5.x form below.
Port names: Linux `/dev/ttyUSB0`, macOS `/dev/cu.usbserial-XXXX`, Windows `COM5`. Port names: Linux `/dev/ttyUSB0`, macOS `/dev/cu.usbserial-XXXX`, Windows `COM5`.
Linux / macOS: Linux / macOS:
```bash ```bash
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash \ esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash \
0x1000 .pio/build/esp32dev/bootloader.bin \ 0x1000 .pio/build/esp32dev/bootloader.bin \
0x8000 .pio/build/esp32dev/partitions.bin \ 0x8000 .pio/build/esp32dev/partitions.bin \
0x10000 .pio/build/esp32dev/firmware.bin 0x10000 .pio/build/esp32dev/firmware.bin
@ -250,7 +255,7 @@ esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash \
Windows PowerShell (backtick continues the line): Windows PowerShell (backtick continues the line):
```powershell ```powershell
esptool.py --chip esp32 --port COM5 --baud 460800 write_flash ` esptool --chip esp32 --port COM5 --baud 460800 write-flash `
0x1000 .pio\build\esp32dev\bootloader.bin ` 0x1000 .pio\build\esp32dev\bootloader.bin `
0x8000 .pio\build\esp32dev\partitions.bin ` 0x8000 .pio\build\esp32dev\partitions.bin `
0x10000 .pio\build\esp32dev\firmware.bin 0x10000 .pio\build\esp32dev\firmware.bin
@ -260,21 +265,21 @@ Erase the whole flash first if the board is in a bad state or has a different
partition table: partition table:
```bash ```bash
esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash esptool --chip esp32 --port /dev/ttyUSB0 erase-flash
``` ```
Optional: merge everything into one factory image (handy for archiving or Optional: merge everything into one factory image (handy for archiving or
sharing a known-good build): sharing a known-good build):
```bash ```bash
esptool.py --chip esp32 merge_bin \ esptool --chip esp32 merge-bin \
--flash_mode dio --flash_freq 40m --flash_size 4MB \ --flash-mode dio --flash-freq 40m --flash-size 4MB \
-o factory.bin \ -o factory.bin \
0x1000 .pio/build/esp32dev/bootloader.bin \ 0x1000 .pio/build/esp32dev/bootloader.bin \
0x8000 .pio/build/esp32dev/partitions.bin \ 0x8000 .pio/build/esp32dev/partitions.bin \
0x10000 .pio/build/esp32dev/firmware.bin 0x10000 .pio/build/esp32dev/firmware.bin
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 factory.bin esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash 0x0 factory.bin
``` ```
Notes: Notes: