diff --git a/README.md b/README.md index 060d14e..45b9830 100644 --- a/README.md +++ b/README.md @@ -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