docs: add manual esptool flashing instructions

This commit is contained in:
Michael Holzmann 2026-11-14 15:42:53 +00:00
parent 98eaf718b1
commit 593a426d4f
1 changed files with 63 additions and 0 deletions

View File

@ -226,6 +226,69 @@ Everything is written to the hidden `.pio/build/esp32dev/` directory:
- Board not detected — hold **BOOT** while the upload starts (needed on some
ESP32-C3 SuperMini boards).
#### Manual flashing with esptool
`pio run -t upload` drives esptool internally. For recovery, a board without
PlatformIO, or a machine that only has the pre-built images, flash the three
partitions yourself.
```bash
pip install esptool # esptool 5.x installs the command as `esptool`
```
Port names: Linux `/dev/ttyUSB0`, macOS `/dev/cu.usbserial-XXXX`, Windows `COM5`.
Linux / macOS:
```bash
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash \
0x1000 .pio/build/esp32dev/bootloader.bin \
0x8000 .pio/build/esp32dev/partitions.bin \
0x10000 .pio/build/esp32dev/firmware.bin
```
Windows PowerShell (backtick continues the line):
```powershell
esptool.py --chip esp32 --port COM5 --baud 460800 write_flash `
0x1000 .pio\build\esp32dev\bootloader.bin `
0x8000 .pio\build\esp32dev\partitions.bin `
0x10000 .pio\build\esp32dev\firmware.bin
```
Erase the whole flash first if the board is in a bad state or has a different
partition table:
```bash
esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
```
Optional: merge everything into one factory image (handy for archiving or
sharing a known-good build):
```bash
esptool.py --chip esp32 merge_bin \
--flash_mode dio --flash_freq 40m --flash_size 4MB \
-o factory.bin \
0x1000 .pio/build/esp32dev/bootloader.bin \
0x8000 .pio/build/esp32dev/partitions.bin \
0x10000 .pio/build/esp32dev/firmware.bin
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 factory.bin
```
Notes:
- These offsets assume the default PlatformIO `esp32dev` 4 MB layout. If you
changed the partition table, flash `partitions.bin` and `firmware.bin` using
the offsets from that table instead.
- 921600 baud works on most boards; drop to 460800 or 115200 for flaky CH340
clones.
- If esptool reports `Failed to connect`, hold **BOOT** while it tries, and
make sure the serial monitor is closed.
- `firmware.bin` alone is what an OTA update expects; the bootloader and
partition table are only written over USB.
---
## MQTT topics