Force arg missing (ESPTOOL-1201)

[LeBellier]

esptool/esptool/cmds.py

Line 724 in 785a3db

erase_flash(esp)

In write_flash(), arg force is not forward to erase_flash(), So if you need to force and erase_all, it's not possible.

[github-actions]

Hi @LeBellier! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Thank you for raising this issue. Based on the official Espressif documentation for esptool's Python module API, the write_flash() function does accept both the erase_all and force keyword arguments. However, the documentation does not specify whether the force argument is actually forwarded to the underlying erase_flash() call when erase_all=True is used. This could indeed result in a situation where forced erasure is not possible via write_flash() if the device has Secure Boot or Flash Encryption enabled, since erase_flash() requires force=True to bypass these protections.

Here is the relevant documentation excerpt for write_flash():

Keyword Arguments:

• erase_all (bool) – Erase the entire flash before writing.
• force (bool) – Ignore safety checks (e.g., overwriting bootloader, flash size).
  ...
  esptool.cmds.write_flash documentation

And for erase_flash():

esptool.cmds.erase_flash(esp: ESPLoader, force: bool = False) → None
Erase the SPI flash memory of the ESP device.

• force – Bypass the security checks for flash encryption and secure boot.
  ...
  esptool.cmds.erase_flash documentation

The documentation does not explicitly confirm that force is passed from write_flash() to erase_flash(). If you have found in the code that this is not the case, your observation is valid and this could be a limitation for users needing to force an erase as part of a write_flash() operation.

Recommendation:
If you require a forced erase with erase_all, you may need to call erase_flash(force=True) manually before invoking write_flash() as a workaround, until this is addressed in esptool.

If you would like this behavior to be changed, it would be helpful to open a feature request or pull request on the esptool repository, referencing this limitation and the relevant documentation.

Let me know if you need further clarification or assistance!

[LeBellier]

I understand, but if you want to keep this behaviour i think you should edit the documentation for force arg in write_flash

[radimkarnis]

@LeBellier thanks for the ticket!
It's true the force arg should be passed as well, we'll fix this.