microcontroller.reset() causes board to hang indefinitely on subsequent restart

[grgrant]

CircuitPython version and board name

Adafruit CircuitPython 10.2.0-rc.0 on 2026-04-16; Adafruit Feather ESP32-S2 TFT with ESP32S2
Adafruit CircuitPython 10.2.0-rc.0 on 2026-04-16; TinyS2 with ESP32S
Adafruit CircuitPython 10.2.0-rc.0 on 2026-04-16; Adafruit Feather ESP32S3 4MB Flash 2MB PSRAM with ESP32S3

Code/REPL

import microcontroller
microcontroller.reset()

Behavior

Behavior

Upon execution the board resets and then hangs at the boot.py execution before code.py is executed. The last thing shown on the TFT display is 'boot.py output:'. Subsequently neither reset nor a power cycle will get the board past the 'boot.py output' line. No output whatsoever shows on the USB serial console nor is any Control-C or Carriage Return input acknowledged.

Prerequisites

Brand new install with the following files:

boot.py

import storage
storage.disable_usb_drive()

settings.toml

# To auto-connect to Wi-Fi
CIRCUITPY_WIFI_SSID="MySSID"
CIRCUITPY_WIFI_PASSWORD="SSIDPass"

# To enable modifying files from the web. Change this too!
# Leave the User field blank when you type the password into the browser.
CIRCUITPY_WEB_API_PASSWORD="mypass"
CIRCUITPY_WEB_API_PORT=80

Description

This is a bug since 10.1.4 since this configuration just loops as expected under 10.1.4 resetting the board over and over and can be interrupted with a control-c via USB serial or via reset without hanging the board.

• I tested with two different brands of Access Points to ensure my TP-Link main AP was not causing this
• I tried without WiFi and WebWorkflow settings.toml entries and the bug doesn't happen
• I believe the storage.disable_usb_drive() is the bigger culprit because one has to restart the board from safe mode without that to get it back into working state.
• Otherwise the system continues to stop at the 'boot.py output:' line and be unresponsive.

Additional information

To ensure that a 'normal program' causes the problem I wrote a program that reads a BMP581's temperature and prints to console in a loop. After a minute or two of readings the loop calls microcontroller.reset() and the board is put into the hanged state described in this bug report. As before safe mode is required and a reset with the boot.py disabled is required to return to normal operation.

Originally logged with the Watchdog reset issue #10054 but this issue was only exposed by the end of that issue's test code (the microcontroller.reset() to undo/reset the #10054 bug).

[grgrant]

I've done some additional troubleshooting and found that boot.py finishes but code.py does not start. I put some print statements before and after the storage.disable_usb_drive() and they print on my TFT display.

In normal operation the boot.py output: line is followed by REPL instructions and then a 'code.py output:' line. Neither of those show after the microcontroller.reset() has wedged the board. Stuck in this condition even after power cycle so some state is saved by the processor in NVM.

Additionally if there is a wifi.radio.enabled=False placed in boot.py after enabling Web Workflow and WiFi in settings.toml the bug does not happen. So having WiFi (and perhaps Web Workflow) is indeed a prerequisite for microcontroller.reset() hanging the board before code.py executes.

[dhalbert]

I did a bisect on this. Troubles start appearing at the update to ESP-IDF v.5.5.3: #10840. I was testing on a Metro ESP32-S3 with this simple test. CIRCUITPY_WIFI_SSID and CIRCUITPY_WIFI_PASSWORD are set to the local WLAN in settings.toml.
code.py

import microcontroller
import time

time.sleep(5)
print("resetting in 5 seconds")
time.sleep(5)
microcontroller.reset()

It appears that with 10.2.0-rc.0, things are worse when CIRCUITPY_WEB_API_PASSWORD is enabled, but the test above boot loops and prints nothing the first time with #10840 and after. Between #10840 and 10.2.0-rc.0, there are some variations about how things run. The boot-looping is visible in the serial console on as you get closer to 10840.

#10892 also is due to the ESP-IDF update. It crashes on C6 only. But that may just be a manifestation of the same underlying problem, in a different way.

[grgrant]

Ok, just documenting very strange behavior. I was testing on three boards that needed boot.py disable_usb_drive and that didn't exhibit the error without. On my TinyS2 I even did a storage.erase_filesystem and the bug behavior would not exhibit. I then rewrote the 0.35.0 tiny uf2 bootloader and then loaded rc0 and copied back the code.py and settings.toml and I can now trigger without boot.py. Crazy...

To not spam this too much, I found an empty boot.py causes it to trigger and renaming the empty boot.py to boot_dis.py causes it to not trigger. Apparently there is a code path that sees a boot.py and trys to execute even empty and that triggers for me.

[grgrant]

@dhalbert I found that a QtPy ESP32-S3 N4R2 doesn't need the boot.py I need with my TinyS2 to trigger the error. With the QtPY S3 I get your exact behavior, Dan. Yay!

All Adafruit tested boards both ESP32-S2 and S3 exhibit the error without boot.py. However the UM TinyS2 requires boot.py to be present to trigger the error -- no idea why but I'm now going to await any need for a second tester when new releases are made.