Install firmware and use the REPL

MicroPython’s download pages list separate firmware files for the Pico and the Pico W, five builds for one ESP32 board, and preview builds of the next release beside every release. Pick the wrong file and the board may still start, then fail the first time your code touches Wi-Fi, which is a confusing place to discover a download mistake.

This lesson installs the right file on a Pico with a file copy and on an ESP32 with esptool, then teaches the prompt you get afterwards, the REPLREPL: Read-eval-print loop: the interactive >>> prompt that MicroPython runs on a board's USB serial port or UART. Each line you type is compiled, run, and its result printed.: the keys that stop, restart and paste, and the raw mode that tools such as mpremote use to run your code, byte by byte.

The firmware file must match your board, not only its chip

The Pico and the Pico W share the RP2040 chip, and the Pico firmware runs on both. Only the Pico W file, though, includes the network module and the driver for the board’s Wi-Fi chip, so on a Pico W with the Pico file, import network raises ImportError. An ESP32 module needs the same care: the ESP32_GENERIC download page offers a plain build and four variants, and tells you which board each one is for.

Every file name has the same parts: the board, an optional variant, an eight-digit build stamp, the version and the file type, .uf2 for the Pico boards and .bin for an ESP32. The program below splits six names into those parts and checks each against the board it is meant for:

"""Split MicroPython firmware file names into their parts, and check each one against the board it is meant for.

The names follow the pattern of MicroPython's download pages: BOARD, an optional -VARIANT, an eight-digit build
stamp, -v and the version, an optional preview suffix, then the file type.
"""

import re

NAME = re.compile(
    r"^(?P<board>[A-Z0-9_]+?)(?:-(?P<variant>[A-Z0-9]+))?-(?P<stamp>\d{8})"
    r"-v(?P<version>\d+\.\d+\.\d+)(?P<preview>-preview\.[0-9a-z.]+)?\.(?P<kind>uf2|bin|app-bin)$"
)

# For each board: its firmware name and the file type its download page installs.
BOARDS = {
    "Pico": ("RPI_PICO", "uf2"),
    "Pico W": ("RPI_PICO_W", "uf2"),
    "Pico 2 W": ("RPI_PICO2_W", "uf2"),
    "ESP32 WROOM": ("ESP32_GENERIC", "bin"),
    "ESP32 WROVER": ("ESP32_GENERIC", "bin"),
}
# Builds whose firmware includes the network module (the Wi-Fi boards).
NETWORK = {"RPI_PICO_W", "RPI_PICO2_W", "ESP32_GENERIC"}


def check(file_name, board):
    """The problems of installing file_name on board, as a list of sentences (empty: the file fits)."""
    parts = NAME.match(file_name)
    if parts is None:
        return ["not named like a MicroPython firmware file"]
    want, kind = BOARDS[board]
    problems = []
    if parts["board"] != want:
        problems.append(f"built for {parts['board']}, not {want}")
        if want in NETWORK and parts["board"] not in NETWORK:
            problems.append("that build has no network module, so Wi-Fi code fails with ImportError")
    if parts["kind"] == "app-bin":
        problems.append("not the .bin file that the download page says to install")
    elif parts["kind"] != kind:
        problems.append(f"a .{parts['kind']} file, but this board installs a .{kind} file")
    if parts["preview"]:
        problems.append("a preview build of the next release, not a release")
    return problems


CASES = [
    ("RPI_PICO-20260824-v1.29.0.uf2", "Pico"),
    ("RPI_PICO-20260824-v1.29.0.uf2", "Pico W"),
    ("RPI_PICO2_W-RISCV-20260824-v1.29.0.uf2", "Pico 2 W"),
    ("ESP32_GENERIC-SPIRAM-20260824-v1.29.0.bin", "ESP32 WROVER"),
    ("ESP32_GENERIC-20260824-v1.29.0.app-bin", "ESP32 WROOM"),
    ("RPI_PICO_W-20261016-v1.30.0-preview.147.g9e348d293c.uf2", "Pico W"),
]

for file_name, board in CASES:
    parts = NAME.match(file_name)
    print(file_name)
    print(f"  board {parts['board']}, variant {parts['variant'] or '-'}, version {parts['version']}")
    problems = check(file_name, board)
    print(f"  on the {board}: {'fits' if not problems else '; '.join(problems)}")

RPI_PICO-20260824-v1.29.0.uf2
  board RPI_PICO, variant -, version 1.29.0
  on the Pico: fits
RPI_PICO-20260824-v1.29.0.uf2
  board RPI_PICO, variant -, version 1.29.0
  on the Pico W: built for RPI_PICO, not RPI_PICO_W; that build has no network module, so Wi-Fi code fails with ImportError
RPI_PICO2_W-RISCV-20260824-v1.29.0.uf2
  board RPI_PICO2_W, variant RISCV, version 1.29.0
  on the Pico 2 W: fits
ESP32_GENERIC-SPIRAM-20260824-v1.29.0.bin
  board ESP32_GENERIC, variant SPIRAM, version 1.29.0
  on the ESP32 WROVER: fits
ESP32_GENERIC-20260824-v1.29.0.app-bin
  board ESP32_GENERIC, variant -, version 1.29.0
  on the ESP32 WROOM: not the .bin file that the download page says to install
RPI_PICO_W-20261016-v1.30.0-preview.147.g9e348d293c.uf2
  board RPI_PICO_W, variant -, version 1.30.0
  on the Pico W: a preview build of the next release, not a release

The second case is the mistake of the opening: the RPI_PICO file on a Pico W runs, and fails at the first import network. The fifth is a trap of the ESP32 page, which lists an .app-bin file beside each .bin. The page says to download the .bin file, which is the combined image that the esp32 port’s README describes: a bootloader, a partition table and MicroPython itself.

Keep a record of what you installed: the file name and its SHA-256SHA-256: A hash function that turns any file into a 256-bit fingerprint, written as 64 hexadecimal digits. Two files with the same SHA-256 have the same content, so comparing hashes shows which files changed. More in “mpremote: run, copy, mount and sync”, which you can compute without uploading the file anywhere. With them you can install the same firmware again on a replacement board, or tell two boards apart when one behaves differently.

A Pico installs by copying a file; an ESP32 through esptool

Pico boards install firmware as a UF2 fileUF2 file: A firmware file made of 512-byte blocks that a board's bootloader writes to flash when the file is copied onto the USB drive it shows. Pico boards install MicroPython this way.. Their chip has a built-in bootloaderbootloader: A small program that runs at reset, before the firmware, and can receive new firmware: the RP2040's USB drive mode and the ESP32's serial ROM bootloader are two. that shows the board to your computer as a USB drive, and copying a .uf2 file onto that drive installs it. Step through a first install:

The last step is the one to check. The prompt appears on a USB serial port, and once it does, two lines tell you exactly what you installed:

• import sys and then sys.implementation show the version, (1, 29, 0, ''), and the build, _build='RPI_PICO_W' on a Pico W, as the previous lesson decoded.
• If _build names another board than yours, install the right file again: the next copy simply replaces it.

An original ESP32 chip has no USB of its own, so it cannot appear as a drive: boards reach it through a USB-serial converter. Espressif’s esptool talks to the chip’s ROM bootloader over that serial connection, and the download page gives two commands, an erase and a write. Step through them, and through what happens when the erase is skipped:

The erase matters for a first install only. The esp32 port’s first-boot code checks that the block where the filesystem goes is empty before it formats it; on a board that held other firmware it may not be, and MicroPython then refuses to touch it. Updating a board that already runs MicroPython is different: the reset and boot documentation notes that installing new firmware usually keeps the filesystem, so your files survive an update.

Three keys stop, restart and paste at the REPL

mpremote with no arguments, or any serial terminal, opens the prompt: it connects to the first USB serial device it finds, and Ctrl-] or Ctrl-X leaves it again. At the >>> prompt a few control keys do more than edit text. MicroPython reads them as commands only when the line is still empty, which the firmware’s line editor checks for each key:

While a program runs, the key that counts is Ctrl-C: it raises KeyboardInterrupt inside the program, which stops it and brings back the prompt unless the program catches that exception. Two habits follow from the table. Before you paste a block of code, press Ctrl-E on an empty line: in normal mode the REPL indents each new line after a colon by itself, so pasted code that is already indented gets indented twice and fails with IndentationError. And after an expression, the special variable _ holds its value, so x = _ keeps a result you forgot to name.

The raw REPL is the same prompt, framed for programs

The friendly REPL is made for people: it echoes keys, indents, and prints a prompt after each line. A program that sends code needs something stricter, and that is 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.. Ctrl-A switches to it, the board stops echoing, and each block of code ends with Ctrl-D. Every reply has the same frame: OK, the output, a 0x04 byte, the error output, a second 0x04 and the > prompt, so a tool can tell where output ends and a traceback starts. Step through one run of print(6 * 7):

The next program does what mpremote’s serial transport does: it switches the board into raw mode, sends two programs and splits each reply. Its board is fake_board.py, a stand-in written from the firmware’s own raw REPL loop that runs the code with your computer’s Python, so it shows the bytes of the protocol, not MicroPython’s own results:

"""A stand-in for a MicroPython board's REPL, written from the firmware's own loop (shared/runtime/pyexec.c).

It answers the raw REPL the way the firmware does, and the few keys of the friendly REPL that a tool sends to reach
it. It runs the code it receives with the Python of this computer, so it shows the protocol, not MicroPython's own
results.
"""

import contextlib
import io

BANNER = b"raw REPL; CTRL-B to exit\r\n"


class FakeBoard:
    def __init__(self):
        self.raw = False          # False: the friendly REPL, with its >>> prompt
        self.line = bytearray()   # what the host has typed since the last Ctrl-D
        self.sent = bytearray()   # bytes the board has sent and the host has not read yet
        self.globals = {"__name__": "__main__"}

    def write(self, data):
        """Bytes from the host, one at a time, as they arrive over USB serial."""
        for byte in data:
            if self.raw:
                self._raw_key(byte)
            else:
                self._friendly_key(byte)

    def read(self):
        """Everything the board has sent since the last read."""
        data = bytes(self.sent)
        self.sent.clear()
        return data

    def _friendly_key(self, byte):
        if byte == 0x01:            # Ctrl-A at an empty prompt: switch to the raw REPL
            self.sent += b"\r\n" + BANNER + b">"
            self.raw = True
        elif byte in (0x0D, 0x03):  # Enter, or Ctrl-C, at an empty prompt: a new prompt
            self.sent += b"\r\n>>> "

    def _raw_key(self, byte):
        if byte == 0x01:            # Ctrl-A: start the raw REPL again
            self.line.clear()
            self.sent += BANNER + b">"
        elif byte == 0x02:          # Ctrl-B: back to the friendly REPL (a board then prints its banner)
            self.raw = False
            self.sent += b"\r\n"
        elif byte == 0x03:          # Ctrl-C: throw away the code typed so far
            self.line.clear()
        elif byte == 0x04:          # Ctrl-D: run what was typed
            self.sent += b"OK"
            self._run(bytes(self.line).decode())
            self.line.clear()
            self.sent += b">"
        else:                       # anything else is code, and nothing is echoed
            self.line.append(byte)

    def _run(self, source):
        out = io.StringIO()
        error = ""
        try:
            with contextlib.redirect_stdout(out):
                exec(compile(source, "<stdin>", "exec"), self.globals)
        except Exception as e:
            tb = e.__traceback__
            while tb.tb_next is not None:
                tb = tb.tb_next
            # The traceback in the form MicroPython prints it.
            error = (
                "Traceback (most recent call last):\n"
                f'  File "<stdin>", line {tb.tb_lineno}, in <module>\n'
                f"{type(e).__name__}: {e}\n"
            )
        self.sent += out.getvalue().replace("\n", "\r\n").encode()
        self.sent += b"\x04"
        self.sent += error.replace("\n", "\r\n").encode()
        self.sent += b"\x04"

"""Drive a board's raw REPL the way mpremote's serial transport does, and print every byte that crosses the cable.

The board here is fake_board.py, a stand-in that answers as the firmware does. mpremote sends the same bytes over a
real serial port, and reads until it sees each marker it expects: the raw REPL banner, OK, and the two Ctrl-D bytes.
"""

from fake_board import FakeBoard


def enter_raw_repl(board):
    board.write(b"\r\x03")   # Enter and Ctrl-C: stop whatever is running
    board.read()             # throw away the prompts that come back
    board.write(b"\r\x01")   # Enter and Ctrl-A: switch to the raw REPL
    reply = board.read()
    if not reply.endswith(b"raw REPL; CTRL-B to exit\r\n>"):
        raise RuntimeError(f"could not enter the raw REPL: {reply!r}")
    return reply


def exec_raw(board, code):
    """Send code, then Ctrl-D; return what it printed and its error output, as the board framed them."""
    board.write(code.encode() + b"\x04")
    reply = board.read()
    if not reply.startswith(b"OK"):
        raise RuntimeError(f"the board did not accept the code: {reply!r}")
    out, err, prompt = reply[2:].split(b"\x04")
    return reply, out, err


board = FakeBoard()
print("Ctrl-A     ->", enter_raw_repl(board))
for code in ["print(6 * 7)", "reading = None\nif reading is None:\n    raise ValueError('sensor not found')"]:
    reply, out, err = exec_raw(board, code)
    print("code       ->", code.encode() + b"\x04")
    print("reply      <-", reply)
    print("  output:  ", out)
    print("  error:   ", err)

Ctrl-A     -> b'\r\n>>> \r\nraw REPL; CTRL-B to exit\r\n>'
code       -> b'print(6 * 7)\x04'
reply      <- b'OK42\r\n\x04\x04>'
  output:   b'42\r\n'
  error:    b''
code       -> b"reading = None\nif reading is None:\n    raise ValueError('sensor not found')\x04"
reply      <- b'OK\x04Traceback (most recent call last):\r\n  File "<stdin>", line 3, in <module>\r\nValueError: sensor not found\r\n\x04>'
  output:   b''
  error:    b'Traceback (most recent call last):\r\n  File "<stdin>", line 3, in <module>\r\nValueError: sensor not found\r\n'

The first reply is OK42\r\n\x04\x04>: the output, an empty error part between the two 0x04 bytes, and the prompt. The second program fails, so its output part is empty and the traceback, in the form MicroPython prints it, sits in the error part. That split is how mpremote exec can print your output and then exit with an error status when your code raised an exception.

mpremote and the project’s own pyboard.py tool drive boards this way, and since version 1.27 the unix port answers the raw REPL too, because its REPL now uses the same loop as the boards. mpremote first asks for raw-paste mode, a variant of the raw REPL with flow control: the board says how many bytes it can take at once, and the tool waits for room before it sends more, which makes long programs arrive safely.

Practise: split a raw REPL reply

A tool that drives boards needs one small, careful function: the one that cuts a reply into output and error, and refuses a reply that is not complete. The sample tests include a traceback and output that contains > characters:

def split_raw_reply(data):
    """Return (output, error) of a raw REPL reply: b"OK" + output + b"\x04" + error + b"\x04" + b">"."""
    return (b"", b"")

from reply import split_raw_reply


def raises_value_error(data):
    try:
        split_raw_reply(data)
    except ValueError:
        return True
    return False


def test_output():
    """splits a reply with output and no error"""
    assert split_raw_reply(b"OK42\r\n\x04\x04>") == (b"42\r\n", b"")


def test_traceback():
    """returns the traceback as the error part"""
    tb = b'Traceback (most recent call last):\r\n  File "<stdin>", line 1, in <module>\r\nValueError: no sensor\r\n'
    assert split_raw_reply(b"OKstart\r\n\x04" + tb + b"\x04>") == (b"start\r\n", tb)


def test_empty_program():
    """handles a program that printed nothing"""
    assert split_raw_reply(b"OK\x04\x04>") == (b"", b"")


def test_prompt_signs_in_output():
    """keeps > characters that the program printed"""
    assert split_raw_reply(b"OK>>> 3 > 2\r\n\x04\x04>") == (b">>> 3 > 2\r\n", b"")


def test_bad_frames():
    """refuses replies that are not complete frames"""
    assert raises_value_error(b"raw REPL; CTRL-B to exit\r\n>")
    assert raises_value_error(b"OK42\r\n\x04")
    assert raises_value_error(b"OK42\r\n\x04\x04")
    assert raises_value_error(b"OK42\r\n\x04\x04>>")

Then review the four ideas of this lesson, from the firmware file to the raw REPL. The self-check starts where your answers so far are weakest, and it explains every choice the moment you make it:

Interview questions

Warm-up (fresher): At the MicroPython REPL, what do Ctrl-C and Ctrl-D do, and when does Ctrl-D not reset?

Ctrl-C interrupts: it raises KeyboardInterrupt in the running program, which stops it and returns to the prompt unless the program catches the exception, and at the prompt it cancels the line being typed. Ctrl-D at an empty prompt does a soft reset: the interpreter restarts, every variable and imported module is cleared, and the boot files run again, while the USB serial connection stays open. Ctrl-D does not reset when the line holds text, because the control keys of the REPL work as commands only on an empty line, and in paste mode, where it ends the paste and runs the code. In the raw REPL, Ctrl-D after code runs that code, and Ctrl-D with no code is the soft reset that mpremote uses before its first command.

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

Key takeaways

• The firmware file must match the board: RPI_PICO runs on a Pico W but has no network module, and an ESP32 needs the variant for its RAM, flash and cores.
• A Pico installs by copying a .uf2 file to the drive its bootloader shows; an original ESP32 installs with esptool, an erase and a write at 0x1000.
• sys.implementation confirms what was installed, and a record of the file name and its SHA-256 lets you install the same firmware again.
• At an empty prompt Ctrl-C gives a new prompt, Ctrl-D soft-resets and Ctrl-E opens paste mode; while a program runs, Ctrl-C stops it with KeyboardInterrupt.
• The raw REPL frames every reply as OK, the output, 0x04, the error output, 0x04 and >, which lets mpremote and editors run code and tell output from errors.