ESPTOOL.PY(1)

📦
version 4.7.0 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing

💖 ESPTOOL.PY(1) 💖

okay bestie, sit DOWN. this is the esptool.py manual page, straight out of the User Commands section, and it's literally the whole vibe for talking to ESP8266 and ESP32 chips. 🦋

✨ NAME ✨

esptool — ESP8266 and ESP32 ROM Bootloader Utility 🔥

🌸 DESCRIPTION 🌸

the usage is, and i quote, this exact thing:

esptool [OPTION] COMMAND

🎀 command arguments 🎀

if you want the deets on any single command, run esptool {command} -h for additional help. periodt.

  • load_ram — download an image to RAM and execute it. yes, straight into memory, no flash required ✨
  • dump_mem — dump arbitrary memory to disk
  • read_mem — read an arbitrary memory location
  • write_mem — read-modify-write to an arbitrary memory location
  • write_flash — write a binary blob to flash
  • run — run application code in flash
  • image_info — dump headers from a binary file (bootloader or application)
  • make_image — create an application image from binary files
  • elf2image — create an application image from an ELF file
  • read_mac — read MAC address from OTP ROM
  • chip_id — read Chip ID from OTP ROM
  • flash_id — read SPI flash manufacturer and device ID
  • read_flash_status — read the SPI flash status register
  • write_flash_status — write the SPI flash status register
  • read_flash — read SPI flash content
  • verify_flash — verify a binary blob against flash
  • erase_flash — perform Chip Erase on SPI flash 🧹
  • erase_region — erase a region of the flash
  • merge_bin — merge multiple raw binary files into a single file for later flashing
  • get_security_info — get some security-related data 🔐
  • version — print esptool version

💅 options 💅

  • -h, --help — show this help message and exit
  • --chip {auto,CHIP} — target chip type
  • --port PORT, -p PORT — serial port device
  • --baud BAUD, -b BAUD — serial port baud rate used when flashing/reading
  • --before {default_reset,usb_reset,no_reset,no_reset_no_sync} — what to do before connecting to the chip
  • --after, -a {hard_reset,soft_reset,no_reset,no_reset_stub} — what to do after esptool is finished
  • --no-stub — disable launching the flasher stub, only talk to the ROM bootloader. some features will not be available. 💀
  • --trace, -t — enable trace-level output of esptool interactions
  • --override-vddsdio — override ESP32 VDDSDIO internal voltage regulator (use with care 🫶)
  • --connect-attempts CONNECT_ATTEMPTS — number of attempts to connect, negative or 0 for infinite. Default: 7.

🌈 EXAMPLES 🌈

display device features, SPI flash manufacturer and device ID:

esptool flash_id

flash ESP8266 Espressif AT v1.6.2 firmware to an ESP-WROOM-02 board:

esptool write_flash --flash_mode dio --flash_size 4MB-c1 0x00 boot_v1.7.bin 0x1000 at/1024+1024/user1.2048.new.5.bin 0xfe000 blank.bin 0x3fc000 esp_init_data_default_v08.bin 0x3fe000 blank.bin

flash ESP32 Espressif AT v1.1.1 firmware to an ESP-WROOM-32 board:

esptool write_flash --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x20000 at_customize.bin 0x21000 customized_partitions/ble_data.bin 0x24000 customized_partitions/server_cert.bin 0x26000 customized_partitions/server_key.bin 0x28000 customized_partitions/server_ca.bin 0x2a000 customized_partitions/client_cert.bin 0x2c000 customized_partitions/client_key.bin 0x2e000 customized_partitions/client_ca.bin 0xf000 phy_init_data.bin 0x100000 esp-at.bin 0x8000 partitions_at.bin

display ESP32 efuse state summary:

espefuse --port /dev/ttyUSB0 summary

generate a flash encryption key:

espsecure generate_flash_encryption_key key.bin

burn the key to the device (WARNING: one time only operation 😭 do NOT mess this up):

espefuse --port /dev/ttyUSB1 burn_key flash_encryption key.bin

encrypt flash data:

espsecure encrypt_flash_data --keyfile key.bin --address 0x10000 -o my-app-encrypted.bin my-app.bin

👑 AUTHOR 👑

esptool.py was started by Fredrik Ahlberg as an unofficial community project, currently maintained by Angus Gratton and supported by Espressif Systems (Shanghai) PTE LTD. this manual page has been produced by Milan Kupcevic <milan@debian.org> for the Debian project and can be used by others. iconic behavior honestly 💜

🙈 REPORTING BUGS 🙈

Copyright © 2014-2017 Fredrik Ahlberg, Angus Gratton, Espressif Systems (Shanghai) PTE LTD, other contributors as noted. License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

fr fr, no warranty. read it again. 😭

🦋 SEE ALSO 🦋

esptool(1), espefuse(1), espsecure(1)

and that's the whole page bestie!! this was esptool.py version 4.7.0, dated January 2024, and yeah it lives in the ESPTOOL.PY(1) corner of your man pages. go flash something slay ✨💅🎀

📦 where this page comes from