is only available in CircuitPython 8.1.0 and later. Runs When Safe Mode Occurs

Normally, safe mode indicates some serious problem, and you might want to investigate that problem. However, if you are running a program that is unattended, you may want start it up again, despite getting a serious safe mode error. The file lets you do that.

When safe mode occurs, and are not run. However, if and only if safe mode occurs, and a file named exists, that file is executed.

Like, is run before any connection is made via USB, or via the WiFi or BLE workflow. Anything printed by is not written anywhere (unlike, which writes to boot_out.txt).

Doing a Reset in

The main use of is to decide automatically when to leave safe mode and restart normally, with a hard reset. For instance, if you're running a long-lived program that uses WiFi, fatal errors can sometimes occur due to various bugs. So if you want to just ignore safe mode and try again, this simple will leave safe mode and do a reset, as if you pressed the RESET button. 

import microcontroller


Conditional Resetting in

In other cases, you may want to restart only on certain safe mode problems. For instance, you may want to protect only against power outages, and restart automatically if they occur. In that case you can check the reason the safe mode happened in

import microcontroller
import supervisor

if supervisor.runtime.safe_mode_reason == supervisor.SafeModeReason.BROWNOUT:
    microcontroller.reset()    # Reset and start over.
# Otherwise, do nothing. The safe mode reason will be printed in the
# console, and nothing will run.

Sleeping in

Another reason for a power brownout is that you may, for instance, have a solar-powered battery charger. When the battery is low, it may be just enough to start the microcontroller, but not enough to continue running. So you might want to sleep after a brownout, and try again later. You could do that in after checking the battery voltage. Or you could sleep for a few minutes in and then reset to try again:

import alarm
import microcontroller
import supervisor
import time

if supervisor.runtime.safe_mode_reason == supervisor.SafeModeReason.BROWNOUT:
    # Sleep for ten minutes and then run again.
    time_alarm = alarm.time.TimeAlarm(monotonic_time = time.monotonic + 10*60)

Manual (USER) Safe Mode Skips

When you force safe mode by pressing one or more buttons, is not run. The reasoning is that you are present, and you have decided not to run anything at all. For instance, you may need to fix an error in itself. So when supervisor.runtime.safe_mode_reason == USER, is skipped.

This guide was first published on Mar 01, 2023. It was last updated on Mar 08, 2024.

This page ( was last updated on Mar 08, 2024.

Text editor powered by tinymce.