Skip to content

Add download mode FAQ section #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SergioGasquez merged 2 commits into from
Mar 25, 2026
Merged

Add download mode FAQ section #238

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
472fb26
docs: Add download mode FAQ section
SergioGasquez Mar 24, 2026
efd0752
fix: Header capitalization
SergioGasquez Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions src/frequently-asked-questions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,22 @@ The [Cargo Book][cargo-book] and the [Embassy Documentation][embassy-documentati
## Can I Use `mem::forget` on Drivers?

The `mem::forget` function should be avoided, as forgetting drivers may result in unintended consequences. Peripheral drivers provide `Drop` implementations which return the peripheral to its default, unconfigured state, and if necessary cancel any Direct Memory Access (DMA) transactions which are current in progress. Forgetting a driver may result in erroneously configured peripherals and/or DMA transactions which run indefinitely and never complete.

## Entering/Exiting Download Mode

Download mode is a boot mode used for firmware programming and debugging. In this mode, the chip does not boot the application from Flash, instead, it waits to receive new firmware data through interfaces such as UART or USB, and writes it to Flash.

### Selecting Boot Mode

When a reset ocurs, the ROM bootloader reads the state of specific strapping pins and selects the boot mode based on their levels at that moment:
Copy link
Copy Markdown
Contributor

@bugadani bugadani Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When a reset ocurs, the ROM bootloader reads the state of specific strapping pins and selects the boot mode based on their levels at that moment:
When a reset occurs, the ROM bootloader reads the state of specific strapping pins and selects the boot mode based on their levels at that moment:

- If the boot strapping pin is high → the chip enters SPI Boot mode (runs the application from Flash).
- If the boot strapping pin is low → the chip enters Download mode (waits for firmware).
See more information about boot mode selection in [ESP-IDF documentation][esp-idf-bootmode]

When the device is on download mode you will see the following serial output: "waiting for download". See [ESP-IDF Download Mode documentation][esp-idf-downloadmode]

After flashing the chip, the chip needs to return to SPI Boot mode to run the new firmware. This can be achieved by reseting the target, causing the strapping pins to be re-sampled, and the chip boots normally or by using the `--after watchdog-reset` option of `espflash` and `esptool` when in USB-Serial/JTAG Mode, see [ESP-IDF Troubleshooting][esp-idf-troubleshooting].

[esp-idf-bootmode]: https://docs.espressif.com/projects/esptool/en/latest/esp32c6/advanced-topics/boot-mode-selection.html
[esp-idf-downloadmode]: https://docs.espressif.com/projects/esp-techpedia/en/latest/esp-friends/get-started/try-firmware/try-firmware-troubleshooting.html#download-mode
[esp-idf-troubleshooting]: https://docs.espressif.com/projects/esptool/en/latest/esp32c6/troubleshooting.html#leaving-download-mode-in-usb-serial-jtag-mode
Loading