ESPEFUSE.PY(1)

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

💅 espefuse.py — the manual page bestie

okay so. this is the manual page for espefuse.py, which lives in section 1 of the manual, and it's part of the whole esptool situation. if you're here, you're about to mess with eFuses, and bestie, eFuses are permanent. like, no takebacks. so let's read the whole thing together, mwah 🫶

✨ NAME ✨

espefuse — the ESP32 efuse get/set tool. that's it, that's the whole name, and honestly? iconic.

🌸 DESCRIPTION 🌸

the vibe is:

espefuse [OPTION] COMMAND

so it's a tool, you give it options, then you give it a command, and it does the thing. no cap. 💖

🎀 command arguments

run espefuse {command} -h if you want extra help for any single command. go ask, she doesn't mind.
  • burn_efuse — burn the efuse with the specified name 🔥
  • read_protect_efuse — disable readback for the efuse with the specified name. so like, nobody can read it anymore 🙈
  • write_protect_efuse — disable writing to the efuse with the specified name
  • burn_block_data — burn non-key data to EFUSE blocks.
do NOT use this command to burn key data for Flash Encryption or ESP32 Secure Boot V1, because the byte order of keys is swapped in there (use burn_key instead). literally just use burn_key, i'm begging 💀
  • burn_bit — burn bit in the efuse block.
  • adc_info — display information about ADC calibration data stored in efuse.
  • dump — dump raw hex values of all efuses
  • summary — print human-readable summary of efuse values ✨
  • execute_scripts — executes scripts to burn at one time.
  • check_error — checks eFuse errors
  • burn_key — burn a 256-bit key to EFUSE: BLOCK1, flash_encryption, BLOCK2, secure_boot_v1, secure_boot_v2, BLOCK3
  • burn_key_digest — parse a RSA public key and burn the digest to eFuse for use with Secure Boot V2
  • set_flash_voltage — permanently set the internal flash voltage regulator to either 1.8V, 3.3V or OFF. this means GPIO12 can be high or low at reset without changing the flash voltage. periodt.
  • burn_custom_mac — burn a 48-bit Custom MAC Address to EFUSE BLOCK3.
  • get_custom_mac — prints the Custom MAC Address.

🌈 options

  • -h, --help — show this help message and exit
  • --chip {auto,CHIP} — target chip type
  • --baud BAUD, -b BAUD — serial port baud rate used when flashing/reading
  • --port PORT, -p PORT — serial port device
  • --before {default_reset,usb_reset,no_reset,no_reset_no_sync} — what to do before connecting to the chip
  • --debug, -d — show debugging information (loglevel=DEBUG) 🔍
  • --virt — for host tests, the tool will work in the virtual mode (without connecting to a chip).
  • --path-efuse-file PATH_EFUSE_FILE — for host tests, saves efuse memory to file.
  • --do-not-confirm — do not pause for confirmation before permanently writing efuses.
use with caution. this is the "skip the safety net" button and it is giving main character energy in the worst way 😭

⭐ EXAMPLES ⭐

display device features, SPI flash manufacturer and device ID:

esptool flash_id

flash ESP8266 Espressif AT v1.6.2 firmware to 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 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):

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, and it's currently maintained by Angus Gratton, 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. giving credit where credit is due, always 💜

🦋 REPORTING BUGS 🦋

found a bug? tell the people, bestie, don't suffer in silence 🙈

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.

"no warranty" is not a vibe, it's a legal fact. read it, feel it, respect it 💅

🌟 SEE ALSO 🌟

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

and that's the whole page, bestie!! this one's from <strong>esptool.py 4.7.0</strong>, dated <strong>January 2024</strong>, and it's filed under <strong>ESPEFUSE.PY(1)</strong> in the manual. go forth and burn responsibly — and remember, eFuses don't come with an undo button 🎀✨

📦 where this page comes from