boot.py, main.py and a layout that survives resets

Save a main.py that crashes on its first line and then resets the board, and the board starts again, crashes and resets, over and over, dropping off your computer’s USB each time. Every MicroPython board starts the same way after a reset, and two files you control, boot.py and main.py, decide whether that start leads to a working app, a prompt or a loop.

This lesson follows the start of a board step by step, lays out a project so that a reset never runs stale code, compares what soft and hard resets keep, and ends with a main.py that cannot lock you out, whatever the app does.

Every reset runs the same start: boot.py, main.py, then the REPL

Copy a main.py that prints hello to a Pico, open its REPL and press Ctrl-D: hello appears, and only then the prompt. Whatever starts the board, a hard resethard reset: A complete reset of the microcontroller, as at power-on: all hardware state is cleared, except that the RTC may keep its time. machine.reset(), the reset button and a watchdog cause one. such as power-on or a soft resetsoft reset: A restart of the MicroPython interpreter without resetting the chip: Python objects, imports and most peripheral set-up are cleared, then the boot files run again. Ctrl-D at an empty prompt does one. such as Ctrl-D, the firmware runs the same sequence. Step through it:

boot.py is for set-up that must happen before anything else and then finish, such as configuring hardware that starts with a different setting. The documentation adds a warning for some ports, the rp2 port among them: USB starts only after boot.py exits, so what it prints may not reach your terminal. Many projects need no boot.py at all and put the set-up at the top of main.py. main.py is the app. It may loop forever, and both files share one set of globals, which is easy to forget when a name in main.py seems to come from nowhere.

The next program models three starts of a board by the rules of the rp2 port’s main loop: after a normal reset, after a boot.py that raises, and after a soft reset from the raw REPLraw REPL: The REPL's mode for programs, entered with Ctrl-A: it echoes nothing, runs the code it received when Ctrl-D arrives, and frames every reply with OK and two 0x04 bytes. More in “Install firmware and use the REPL”, the way mpremote resets a board:

"""The start of a board, three times, by the rules of the rp2 port's main loop (ports/rp2/main.c).

After the frozen _boot.py the firmware runs boot.py, then main.py, all in one set of globals. main.py runs only when
boot.py raised no error and the board is in the friendly REPL; a soft reset from the raw REPL skips it. Here the two
files are strings and exec() stands in for the firmware's runner.
"""

FILES = {
    "boot.py": "wifi_ssid = 'lab-net'\nprint('boot.py ran')\n",
    "main.py": "print('main.py ran; wifi_ssid is', wifi_ssid)\n",
}


def run_file(name, files, scope):
    """Run one file in the board's globals; return True if it raised no exception (a missing file counts as one)."""
    if name not in files:
        return True
    try:
        exec(files[name], scope)
        return True
    except Exception as e:
        print(f"  {name} raised {e!r}")
        return False


def start(files, raw_repl=False):
    scope = {"__name__": "__main__"}
    boot_ok = run_file("boot.py", files, scope)
    if boot_ok and not raw_repl:
        run_file("main.py", files, scope)
    else:
        print("  main.py skipped")
    shared = sorted(k for k in scope if not k.startswith("__"))
    print(f"  REPL starts, with the globals {shared}")


print("1. A reset:")
start(FILES)
print("2. A reset after a broken boot.py:")
start({**FILES, "boot.py": "raise OSError('SD card not found')\n"})
print("3. A soft reset from the raw REPL, as mpremote does:")
start(FILES, raw_repl=True)

1. A reset:
boot.py ran
main.py ran; wifi_ssid is lab-net
  REPL starts, with the globals ['wifi_ssid']
2. A reset after a broken boot.py:
  boot.py raised OSError('SD card not found')
  main.py skipped
  REPL starts, with the globals []
3. A soft reset from the raw REPL, as mpremote does:
boot.py ran
  main.py skipped
  REPL starts, with the globals ['wifi_ssid']

The second start is the trap: an error in boot.py costs you main.py, without any message of its own beyond the traceback. The third explains a puzzle from the previous lesson: mpremote soft-reset resets in raw mode, so your new main.py does not start. To watch it start, reset with mpremote reset, or press Ctrl-D in mpremote repl, which soft-resets from the friendly REPL.

A thin main.py, with the app’s modules in /lib

The reset and boot page suggests a main.py that only imports the app and starts it, import my_app and my_app.main(). The app itself lives in modules, and those belong in /lib. On the Pico, sys.path is ['', '.frozen', '/lib'], from MicroPython’s runtime and the rp2 port’s main loop: the current folder first, which is / after a normal start, then the frozen modulesfrozen module: A module compiled into the firmware image when the firmware is built. On most ports its bytecode runs straight from flash, so it takes no RAM for the code. More in “What MicroPython is and where it runs” inside the firmware, then /lib. In each folder name.py is tried before name.mpy, and the first match wins. The next program applies those rules to a board with a tidy /lib and one stray file at the root:

"""Which file an import finds on a Pico, by the rules MicroPython documents.

sys.path on the rp2 port is ['', '.frozen', '/lib']: the current folder (/ after a normal boot), then the modules
frozen into the firmware, then /lib. In each folder name.py is tried before name.mpy, and the first match wins.
"""

SYS_PATH = ["", ".frozen", "/lib"]
# Frozen into the RPI_PICO firmware by its manifest (ports/rp2/boards/manifest.py).
FROZEN = {"asyncio", "dht", "ds18x20", "neopixel", "onewire"}
# The board's files in this example: a tidy /lib, plus a stray old sensor.py left at the root.
BOARD = {
    "/main.py", "/sensor.py",
    "/lib/app.py", "/lib/sensor.py", "/lib/neopixel.py",
    "/lib/config.py", "/lib/config.mpy", "/lib/units.mpy",
}


def find(name, cwd="/"):
    """The file that `import name` loads, or None for an ImportError."""
    for entry in SYS_PATH:
        if entry == ".frozen":
            if name in FROZEN:
                return f"{name}, frozen into the firmware"
            continue
        folder = cwd if entry == "" else entry
        for ext in (".py", ".mpy"):
            path = folder.rstrip("/") + "/" + name + ext
            if path in BOARD:
                return path
    return None


for name in ["app", "sensor", "neopixel", "config", "units", "logging"]:
    print(f"import {name:<9} -> {find(name) or 'ImportError: no module named ' + repr(name)}")

import app       -> /lib/app.py
import sensor    -> /sensor.py
import neopixel  -> neopixel, frozen into the firmware
import config    -> /lib/config.py
import units     -> /lib/units.mpy
import logging   -> ImportError: no module named 'logging'

Two results surprise. import sensor finds the old /sensor.py at the root, because the current folder comes before /lib, so the new /lib/sensor.py is never used. And import neopixel never reaches /lib/neopixel.py, because the Pico firmware freezes a neopixel module of its own, and .frozen comes before /lib.

A layout that avoids both traps puts nothing but the boot files at the root:

With the root down to the two boot files and folders, nothing there can shadow /lib, and replacing the app means replacing files in /lib while main.py stays the same.

Keep main.py itself as source. The reset and boot page mentions precompiled main.mpy and boot.mpy files, but the main loops of the rp2 and esp32 ports in 1.29.0 look for boot.py and main.py by those names only, so a main.mpy on the filesystem never runs at a reset. Precompile the modules in /lib that main.py imports instead.

Soft and hard resets keep different things

The two kinds of reset run the same sequence, but they start from different states. The reset and boot documentation lists what each leaves behind:

machine.reset_cause() returns the cause of the last reset that the port can tell, for example machine.PWRON_RESET or machine.WDT_RESET, so an app can log why it restarted. Ports tell different things: the esp32 port returns machine.SOFT_RESET after a soft reset, while the rp2 port knows only those two causes, so after Ctrl-D a Pico still reports the hard reset that came before.

The difference between the two resets matters in tests: a board that passes after a power cycle can fail after Ctrl-D, because a pin still drives the value the last run left on it, or because a network connection the app expects to open is already open.

So the kind of reset before a test decides what the test proves. A test that only ever follows a power cycle never meets a pin that the previous run left high, or a Wi-Fi connection that is already up. Run start-up checks after both kinds of reset, and after the raw-mode soft reset that mpremote does, before you rely on them.

A recovery path keeps a crashing app from locking you out

The reset and boot page shows a main.py that runs the app inside try, prints any exception with sys.print_exception() and then calls machine.reset(). That is a good start, because a board in the field should restart rather than sit at a prompt nobody reads. It has one weakness: an app that fails at every start makes the board reset forever, and a hard reset takes USB down each time, so a terminal loses the board at every reset. The next program models such a board: five starts under that main.py, and five under one that counts its restarts in a small file:

"""Five boots of a board whose app always fails at start, under two versions of main.py.

The first is the pattern of MicroPython's reset and boot page: print the error, then machine.reset(). The second
counts its restarts in a small file that survives a reset, resets at most three times and then stays at the REPL.
Here the board is simulated: Reset stands for machine.reset(), and the dict `flash` for the file in its flash.
"""


class Reset(Exception):
    """Stands for machine.reset(): this boot ends, and the next one starts from the top."""


def app_main():
    raise OSError("sensor not found on the I2C bus")


def main_reset_always(flash):
    try:
        app_main()
    except Exception as e:
        print("  Fatal error in main:", repr(e))
    raise Reset


def main_bounded(flash, limit=3):
    try:
        app_main()
        flash["restarts"] = 0
    except Exception as e:
        print("  crash:", repr(e))
        if flash["restarts"] < limit:
            flash["restarts"] += 1
            print(f"  restart {flash['restarts']} of {limit}")
            raise Reset
        print("  too many restarts: staying at the REPL")


for main in (main_reset_always, main_bounded):
    print(main.__name__)
    flash = {"restarts": 0}
    for boot in range(1, 6):
        try:
            main(flash)
            print(f"boot {boot}: main.py ended, the REPL starts")
            break
        except Reset:
            print(f"boot {boot}: reset")
    print()

main_reset_always
  Fatal error in main: OSError('sensor not found on the I2C bus')
boot 1: reset
  Fatal error in main: OSError('sensor not found on the I2C bus')
boot 2: reset
  Fatal error in main: OSError('sensor not found on the I2C bus')
boot 3: reset
  Fatal error in main: OSError('sensor not found on the I2C bus')
boot 4: reset
  Fatal error in main: OSError('sensor not found on the I2C bus')
boot 5: reset

main_bounded
  crash: OSError('sensor not found on the I2C bus')
  restart 1 of 3
boot 1: reset
  crash: OSError('sensor not found on the I2C bus')
  restart 2 of 3
boot 2: reset
  crash: OSError('sensor not found on the I2C bus')
  restart 3 of 3
boot 3: reset
  crash: OSError('sensor not found on the I2C bus')
  too many restarts: staying at the REPL
boot 4: main.py ended, the REPL starts

The first main.py never stops resetting. The second resets three times, which gives a passing fault, such as a sensor that needed a moment, its chances, and then stays at the REPL with the error printed. Step through the decisions of that second main.py, with a recovery button checked before anything else:

The button is your own safe modesafe mode: A start that skips the app, and on some ports boot.py and main.py as well, and goes straight to the REPL, so that a board whose code fails at start can be repaired.. Some ports offer one of their own, a start that skips boot.py and main.py, but the reset and boot page lists only port-specific instructions, and for the rp2 and esp32 ports those are factory resets that erase everything. A button you check yourself costs one pin and keeps your files.

If a board is already soft-brickedsoft-bricked: A board that is not damaged but no longer reaches a usable prompt at start, for example because boot.py never ends or the code takes over the REPL's serial port., try the gentle ways first. mpremote stops a running main.py with Ctrl-C and resets in raw mode, which skips it, so mpremote rm :main.py works on a board whose main.py loops or hangs; in a reset loop it may take a few tries to catch the board between two resets. At a prompt, import os and os.remove('main.py') do the same. Only when no prompt can be reached does the factory reset remain: erase the whole flash, install the firmware again and copy your files back.

Practise: write the supervisor

Write the function that the second main.py calls at every start: the button check, the app inside try, the log line, and a restart count that stops after three. The sample tests use a fake board that records what it is asked to do:

def supervise(app, log, reset, button_pressed, state, max_restarts=3):
    """Run app once for this boot; return "safe", "ended", "reset" or "stopped"."""
    app()
    return "ended"

from supervisor import supervise


class Board:
    """Records what supervise asked the board to do."""

    def __init__(self, held=False):
        self.lines = []
        self.resets = 0
        self.held = held

    def log(self, text):
        self.lines.append(text)

    def reset(self):
        self.resets += 1

    def button(self):
        return self.held


def failing():
    raise OSError("no sensor")


def test_safe_mode():
    """starts nothing while the button is held"""
    board, ran = Board(held=True), []
    result = supervise(lambda: ran.append(1), board.log, board.reset, board.button, {"restarts": 0})
    assert result == "safe" and ran == [] and board.resets == 0
    assert board.lines == ["safe mode: app not started"]


def test_app_ends():
    """clears the restart count when the app returns"""
    board, state = Board(), {"restarts": 2}
    assert supervise(lambda: None, board.log, board.reset, board.button, state) == "ended"
    assert state["restarts"] == 0 and board.resets == 0


def test_crash_resets():
    """logs a crash and resets while restarts are left"""
    board, state = Board(), {"restarts": 0}
    assert supervise(failing, board.log, board.reset, board.button, state) == "reset"
    assert board.lines == ["crash: OSError: no sensor"]
    assert board.resets == 1 and state["restarts"] == 1


def test_stops_at_limit():
    """stays at the REPL once max_restarts is used up"""
    board, state = Board(), {"restarts": 3}
    assert supervise(failing, board.log, board.reset, board.button, state, max_restarts=3) == "stopped"
    assert board.resets == 0 and state["restarts"] == 3
    assert board.lines == ["crash: OSError: no sensor", "too many restarts: staying at the REPL"]


def test_ctrl_c_reaches_the_repl():
    """lets KeyboardInterrupt through"""
    board = Board()

    def interrupted():
        raise KeyboardInterrupt

    try:
        supervise(interrupted, board.log, board.reset, board.button, {"restarts": 0})
    except KeyboardInterrupt:
        assert board.resets == 0
        return
    raise AssertionError("KeyboardInterrupt was swallowed")

Then try the self-check on the start sequence, the layout, the two resets and recovery. It picks the topic where your answers have been weakest, and each answer you pick is followed by its reason:

Interview questions

Warm-up (fresher): What belongs in boot.py, and what belongs in main.py?

boot.py runs first after every reset and is for set-up that must happen before anything else and then end: setting up a piece of hardware, or on some boards the network. It must not loop, because the start goes on only after it ends, and on ports such as rp2 even USB starts only after boot.py, so its prints may not be seen. An exception in boot.py also makes the firmware skip main.py. main.py is the app: it runs next, may loop forever, and shares its globals with boot.py. A good main.py stays short, imports the app from /lib and starts it inside a try block, and many projects need no boot.py at all.

Two longer interview questions of this module start from this lesson:

Key takeaways

• After every reset the firmware runs _boot.py, boot.py and main.py, then the REPL; an error in boot.py and a soft reset from the raw REPL both skip main.py.
• On the Pico, sys.path is the current folder, then .frozen, then /lib, so a stray root file or a frozen module of the same name wins over your file in /lib.
• A soft reset clears Python and most peripherals but keeps network connections, pin modes and the REPL; a hard reset clears almost everything, and machine.reset_cause() reports why the board last reset, as far as its port can tell.
• A main.py that checks a recovery button, logs crashes and limits its restarts with a count in flash can never lock you out of the board.