Flashing Guide

There are three ways to flash ESP-Claw firmware to your board. Choose the method that suits your workflow.

Method 1: Browser Flasher (Easiest)

Our web-based flasher uses the Web Serial API to flash firmware directly from Chrome or Edge. No software installation required.

1. Connect your board via USB
2. Open the Install page in Chrome 89+ or Edge 89+
3. Select your board type (ESP32-S3 or ESP32-C3)
4. Click “Connect & Flash”
5. Select your USB device in the browser popup
6. Wait ~30 seconds for the flash to complete

This method flashes the latest stable release. If you need a specific version or custom build, use Method 2 or 3.

Entering Download Mode

If the browser doesn’t detect your board, you may need to enter download mode manually:

1. Hold the BOOT button on your board
2. While holding BOOT, press and release the RESET button
3. Release the BOOT button
4. The board is now in download mode — try connecting again

Some boards (like the ESP32-C3 SuperMini) enter download mode automatically through the USB-CDC interface and don’t need this step.

Method 2: esptool.py (Command Line)

esptool.py is Espressif’s official command-line flash tool. It works on all operating systems and gives you full control over the flashing process.

Install esptool.py

pip install esptool

Download Firmware

Download the latest release binary from the GitHub Releases page. Each release includes:

• bootloader.bin — Bootloader (chip-specific)
• partition-table.bin — Partition layout
• espclaw.bin — Application firmware
• spiffs.bin — Filesystem image (SOUL.md, config)

Flash Command

For ESP32-S3:

esptool.py --chip esp32s3 --port /dev/ttyUSB0 --baud 460800 \
  write_flash \
  0x0 bootloader.bin \
  0x8000 partition-table.bin \
  0x10000 espclaw.bin \
  0x310000 spiffs.bin

For ESP32-C3:

esptool.py --chip esp32c3 --port /dev/ttyUSB0 --baud 460800 \
  write_flash \
  0x0 bootloader.bin \
  0x8000 partition-table.bin \
  0x10000 espclaw.bin \
  0x210000 spiffs.bin

Flash Options Explained

Option	Description
--chip	Target chip (esp32s3, esp32c3, esp32c6)
--port	Serial port (/dev/ttyUSB0, /dev/cu.usbmodem*, COM3)
--baud	Flash speed. 460800 is fast and reliable. Use 115200 if you get errors.
write_flash	Command to write binary files to specific flash addresses

Erasing Flash First

If you’re having issues or upgrading from a different firmware, erase the flash before writing:

esptool.py --chip esp32s3 --port /dev/ttyUSB0 erase_flash

This clears all stored data including Wi-Fi credentials and SOUL.md. You’ll need to reconfigure after flashing.

Method 3: ESP-IDF (From Source)

If you’ve built the firmware from source, flash directly with idf.py:

idf.py -p /dev/ttyUSB0 flash

To also open a serial monitor after flashing:

idf.py -p /dev/ttyUSB0 flash monitor

The ESP-IDF build system handles all flash addresses and partition offsets automatically.

Verifying the Flash

After flashing, the board should restart automatically. You can verify success by:

1. LED indicator: The built-in LED blinks rapidly during boot, then:

   • Slow pulse = searching for Wi-Fi
   • Solid = connected
   • Three quick blinks = AP mode (first setup)

2. Serial monitor: Connect with any serial terminal at 115200 baud:

   # Using screen
   screen /dev/ttyUSB0 115200
   
   # Using minicom
   minicom -D /dev/ttyUSB0 -b 115200
   
   # Using idf.py
   idf.py -p /dev/ttyUSB0 monitor

   You should see boot messages including the firmware version, chip type, and memory status.

Troubleshooting

“Failed to connect”: The board isn’t in download mode. Try the BOOT+RESET sequence described above. Also verify your USB cable is a data cable (not charge-only).

“Wrong chip detected”: You’re using the wrong --chip argument. Check your board’s chip type — look at the markings on the metal RF shield.

“Flash write failed at offset 0x…”: Try reducing the baud rate to 115200. If that doesn’t help, the flash chip may be damaged. Try a different board.

“MD5 mismatch”: The binary was corrupted during download. Re-download and try again. Verify the SHA256 checksum if available.

macOS: “Permission denied”: Go to System Settings, Privacy & Security, and allow access to the USB device. You may need to restart your terminal.

Linux: “Permission denied”: Add your user to the dialout group: sudo usermod -a -G dialout $USER, then log out and back in.

Windows: Board not detected: Install the correct USB driver. ESP32-C3 SuperMini uses CH340, some ESP32-S3 boards use CP2102. Check the chip near the USB connector for the model number.