ESP32 Flashing Cheat Sheet

Practical commands for flashing and recovering ESP32 boards in this repo on Windows.

Tool Check

python -m esphome version
python -m esptool version
python -m serial.tools.list_ports

On this machine, ESPHome is available via python -m esphome and esptool via python -m esptool. Checked locally on 2026-03-21: ESPHome 2025.12.2, esptool 5.1.0.

Find The COM Port

List serial ports:

python -m serial.tools.list_ports

More detail from Windows:

Get-CimInstance Win32_SerialPort | Select-Object DeviceID, Name, Description

Quick before/after method:

1. Unplug the ESP32.
2. Run python -m serial.tools.list_ports.
3. Plug the ESP32 in.
4. Run it again.
5. The new port is your board, for example COM16.

Repo Commands

Validate config only:

python -m esphome config firmware/esphome/hvac_base_flash.yml

First USB flash:

python -m esphome run firmware/esphome/hvac_base_flash.yml --device COM16

Flash zone firmware over USB:

python -m esphome run firmware/esphome/zone_control_from_pcb_v3.yml --device COM16

Flash over OTA once the board is online:

python -m esphome run firmware/esphome/zone_control_from_pcb_v3.yml --device 192.168.1.50

Use the repo helper script:

.\scripts\flash\flash_device.ps1 COM16 firmware/esphome/hvac_base_flash.yml

Use the clean-environment helper if Git Bash or MSYS is interfering:

.\scripts\flash\flash_clean.ps1 COM16 firmware/esphome/hvac_base_flash.yml

Log flashing output to a file:

.\scripts\flash\flash_with_log.bat COM16 firmware\esphome\hvac_base_flash.yml

ESPHome Commands

Compile without uploading:

python -m esphome compile firmware/esphome/hvac_base_flash.yml

Upload the latest build without recompiling:

python -m esphome upload firmware/esphome/hvac_base_flash.yml --device COM16

View logs over serial:

python -m esphome logs firmware/esphome/hvac_base_flash.yml --device COM16

View logs over IP:

python -m esphome logs firmware/esphome/hvac_base_flash.yml --device 192.168.1.50

Clean build files:

python -m esphome clean firmware/esphome/hvac_base_flash.yml

Low-Level esptool Commands

Read chip info:

python -m esptool -p COM16 chip-id
python -m esptool -p COM16 flash-id
python -m esptool -p COM16 read-mac

Erase the whole flash:

python -m esptool -p COM16 erase-flash

Use a slower baud rate if uploads are unstable:

python -m esptool -p COM16 -b 115200 erase-flash

If auto-reset is not working and the board is already in bootloader mode:

python -m esptool --before no-reset --after hard-reset -p COM16 chip-id

Serial Console

Simple serial monitor with PySerial:

python -m serial.tools.miniterm COM16 115200

Exit miniterm with Ctrl+].

Manual Bootloader Mode

Use this when flashing says Failed to connect or the board does not auto-enter download mode.

1. Hold BOOT.
2. Tap EN or RESET.
3. Keep holding BOOT.
4. Start the flash command.
5. Release BOOT when the tool starts connecting or writing.

If the board has no EN button, unplug USB, hold BOOT, plug USB back in, then start flashing.

Common Recovery Flow

1. Identify the board port:python -m serial.tools.list_ports
2. Erase if the device is in a bad state:python -m esptool -p COM16 erase-flash
3. Flash base firmware:python -m esphome run firmware/esphome/hvac_base_flash.yml --device COM16
4. Watch logs for Wi-Fi and IP:python -m esphome logs firmware/esphome/hvac_base_flash.yml --device COM16
5. Move to full firmware over OTA:python -m esphome run firmware/esphome/zone_control_from_pcb_v3.yml --device 192.168.1.50

Common Problems

port busy:

• Close Arduino Serial Monitor, ESPHome logs, PuTTY, VS Code serial monitor, or any other app holding the COM port.

failed to connect:

• Try manual bootloader mode.
• Try a slower speed if needed:

python -m esphome run firmware/esphome/hvac_base_flash.yml --device COM16 --upload_speed 115200

Board powers up but no new COM port appears:

• Use a known data USB cable, not a charge-only cable.
• Try another USB port.
• Check the USB-to-UART driver for the board.

OTA fails:

• Use direct IP instead of .local.
• Do one recovery flash over USB first.

Useful Addresses And Files In This Repo

• Base flash config: firmware/esphome/hvac_base_flash.yml
• Zone firmware: firmware/esphome/zone_control_from_pcb_v3.yml
• Flash helper scripts: scripts/flash/
• Network scan helper: scripts/network/scan_esphome.ps1
• Setup guide: docs/new-users/SETUP_ONE_PAGER_HA_ESPHOME.md

Sources

• ESPHome CLI: https://esphome.io/guides/cli/
• Esptool docs: https://docs.espressif.com/projects/esptool/en/latest/esp32/