ESPFLASH — ESP32 Flashing Reference

SUPPORTED BOARDS

WAVESHARE ESP32-S3 AMOLED

1.8" AMOLED · RM67162 · USB-C · 8MB PSRAM

PARAM	VALUE
Chip	ESP32-S3R8
Flash	16MB QIO
USB Mode	USB-CDC (native)
Boot pin	GPIO0 — hold on power

# Flash Marauder / custom firmware

esptool.py --chip esp32s3 --port COM? \

  --baud 921600 write_flash -z \

  --flash_mode dio --flash_freq 80m \

  --flash_size detect 0x0 firmware.bin

T-DONGLE S3

LilyGo USB dongle · ST7735 TFT · SD slot

PARAM	VALUE
Chip	ESP32-S3
Flash	16MB QIO
USB Mode	USB-CDC
Boot	Slide switch to FLASH pos

esptool.py --chip esp32s3 --port COM? \

  --baud 921600 write_flash -z \

  --flash_mode qio --flash_freq 80m \

  --flash_size 16MB 0x0 firmware.bin

BAGUETTE S3 (Adafruit)

ESP32-S3 · No PSRAM · USB-C · 4MB flash

PARAM	VALUE
Chip	ESP32-S3
Flash	4MB QIO
USB Mode	USB-CDC native
Boot	Hold BOOT + tap RESET

esptool.py --chip esp32s3 --port COM? \

  --baud 460800 write_flash \

  --flash_mode dio --flash_size 4MB \

  0x0 firmware.bin

ESP32 WROOM / WROVER

Generic ESP32 · 4MB · Classic dual-core

PARAM	VALUE
Chip	ESP32 (Xtensa)
Flash	4MB DIO
USB	CP2102 / CH340 UART bridge
Boot	GPIO0 LOW on reset

esptool.py --chip esp32 --port COM? \

  --baud 115200 write_flash \

  --flash_mode dio --flash_size 4MB \

  0x1000 bootloader.bin \

  0x8000 partitions.bin \

  0x10000 app.bin

ESPTOOL QUICK REFERENCE

INSTALL

pip install esptool pip install esptool --upgrade

DETECT / INFO

# Identify chip on port

esptool.py --port COM? chip_id

esptool.py --port COM? flash_id

ERASE

# Full erase before reflash

esptool.py --port COM? erase_flash

READ BACK

# Dump current firmware

esptool.py --port COM? \

  read_flash 0x0 0x400000 backup.bin

BAUD RATES (try in order if failing)

RATE	RELIABILITY
115200	Most reliable — old boards
460800	Good balance
921600	Fast — S3 native USB only
2000000	S3 native USB max

FLASH MODES

MODE	WHEN TO USE
dio	Default — most boards
qio	Newer boards w/ QIO flash
dout	Compatibility fallback

FLASH SIZES

SIZE	FLAG
4MB	--flash_size 4MB
8MB	--flash_size 8MB
16MB	--flash_size 16MB
Auto	--flash_size detect

ESP32 MARAUDER

WEB FLASHER (easiest)

Browser-based · Chrome/Edge only · No esptool needed

Use https://esp.huhn.me or the official Marauder web flasher. Connect board in USB-CDC mode, select binary, flash. Works on Windows, Linux, Android Chrome.

Select the correct .bin for your exact hardware revision. Wrong variant = no display output but may still function.

MANUAL FLASH — S3 BOARDS

Waveshare AMOLED / T-Dongle / Baguette

# Download from Marauder releases

# Pick: esp32_marauder_[board]_[ver].bin



esptool.py --chip esp32s3 \

  --port COM? --baud 921600 \

  write_flash -z \

  --flash_mode dio \

  --flash_freq 80m \

  --flash_size detect \

  0x0 esp32_marauder_[board].bin

MARAUDER BOOT MODES

Force DFU / bootloader mode

BOARD	METHOD
Waveshare AMOLED	Hold GPIO0 button while plugging USB
T-Dongle S3	Slide FLASH switch, plug in, slide back
Baguette S3	Hold BOOT, tap RESET, release BOOT
Generic WROOM	GPIO0 → GND, reset, release GPIO0

In DFU mode the board appears as a generic USB device with no COM port. esptool detects it automatically on the correct port.

MARAUDER OTA UPDATE

Update over WiFi without USB

# Marauder must be running w/ WiFi active

# Navigate to Marauder IP in browser

# Upload .bin via OTA page

http://[marauder-ip]/update

OTA partition must be present in flash — this is the default for most Marauder builds. Confirm partition scheme before relying on OTA.

CIRCUITPYTHON / MICROPYTHON

CIRCUITPYTHON (S3)

# 1. Download .bin from circuitpython.org

# 2. Erase first

esptool.py --chip esp32s3 \

  --port COM? erase_flash



# 3. Flash

esptool.py --chip esp32s3 \

  --port COM? --baud 460800 \

  write_flash -z 0x0 \

  adafruit-circuitpython-[board]-*.bin

After flash, board appears as CIRCUITPY USB drive. Edit code.py directly.

MICROPYTHON (classic ESP32)

# Download from micropython.org/download/esp32

# Erase

esptool.py --chip esp32 \

  --port COM? erase_flash



# Flash

esptool.py --chip esp32 \

  --port COM? --baud 460800 \

  write_flash -z 0x1000 \

  esp32-micropython-*.bin

Connect via any serial terminal at 115200 baud. REPL prompt is >>>

BADUSB / DUCKYSCRIPT (Pico + ESP32 COMBO)

WIFI DUCK SETUP (ESP32 + Pico)

COMPONENT	FIRMWARE	ROLE
Raspberry Pi Pico	WiFi Duck Pico .uf2	USB HID emulation — appears as keyboard/mouse
ESP32	WiFi Duck ESP32 .bin	WiFi AP + script delivery to Pico via UART

# Flash ESP32 partner firmware

esptool.py --chip esp32 --port COM? \

  write_flash 0x0 wifi_duck_esp8266.bin



# Pico: drag .uf2 to BOOTSEL drive (see PICOREF)

TROUBLESHOOTING

FAILED TO CONNECT

CAUSE	FIX
Wrong boot mode	Hold BOOT before connecting, release after esptool starts
Wrong COM port	Device Manager / ls /dev/tty* to find correct port
Driver missing	Install CP2102 or CH340 driver for UART bridge boards
USB cable	Try a different cable — many are charge-only
S3 native USB	May not enumerate until DFU mode entered

FLASH VERIFY ERRORS

SYMPTOM	FIX
MD5 mismatch	Lower baud rate, use --no-compress
Invalid head	Wrong flash_mode — try dio instead of qio
Size error	Specify --flash_size explicitly, don't use detect
Partial flash	Erase full flash first, reflash from 0x0

Always erase before flashing Marauder — leftover partitions from previous firmware cause boot loops.

WINDOWS DRIVER QUICK REF

CHIP	DRIVER	SOURCE
CP2102 / CP2104	Silicon Labs VCP	silabs.com/developers/usb-to-uart-bridge-vcp-drivers
CH340 / CH341	WCH CH340 driver	wch-ic.com/downloads/CH341SER_EXE.html
ESP32-S3 native USB	Built into Windows 10+	No driver needed — appears as USB serial CDC
ESP32 USB JTAG	Zadig / WinUSB	zadig.akeo.ie — select USB JTAG/serial debug unit