MPFLASH

mpflash is a command-line tool for working with MicroPython firmware. It provides features to help you flash and update Micropython on one or more attached microcontrollers.

This tool was initially created to be used in a CI/CD pipeline to automate the process of downloading and flashing MicroPython firmware to multiple boards, but it has been extend with a TUI to be used for manual downloadig, flashing and development.

The interactive prompts use rich-inquirer for a modern, keyboard-navigable TUI experience that integrates visually with Rich terminal output. Selection lists, fuzzy search, and multi-select are all rendered with Rich styling. A standard terminal (VT100-compatible) is required; redirected or non-interactive stdin (e.g. CI pipelines) will automatically skip interactive prompts.

mpflash has been tested on:

OS: Windows x64, Linux X64, and macOS.
Micropython (hardware) ports:
- rp2, using .uf2, using filecopy
- samd, using .uf2, using filecopy
- esp32, using .bin, using esptool,
- esp8266, using .bin, using esptool
- stm32, using .dfu, using pydfu (also in Windows)

Not yet implemented: nrf, cc3200, mimxrt, renesas

Release v1.25.0(.post2)

This release includes several new features and improvements:

New features:
- Added support for --variant option to specify a specific variant of the board when flashing.
- mpflash now uses a slqlite database to store information on all possible micropython firmwares, and the management of the downloaded firmware files.
- This allows for a better identification of boards, and matches to the correct firmware.
- Use the MicroPython v1.25.0 sys.implementation._build to as board_id when avaialable
- Automatically try to download firmware if not yet available locally. No lonmger need to specify the --download option.
- Restructured mpboard_id to use a SQLite db to be able to ID more boards and variants
- vendored and adapted board_database.py from mpflash, kudos @mattytrentini

⚠️ Breaking API Changes (v1.26+)

Important for Library Users: The worklist module API has been completely refactored with breaking changes. Legacy worklist functions have been removed.

Removed Functions: auto_update_worklist(), manual_worklist(), manual_board(), single_auto_worklist(), full_auto_worklist(), filter_boards()
New API: Modern interface with create_worklist(), FlashTask dataclass, and WorklistConfig objects
CLI Unchanged: Command-line interface remains fully compatible

See API Documentation for complete migration guide.

Features

List the connected boards including their firmware details, in a tabular or json format
Download MicroPython firmware for versions, and matching a specified board or matches your current attached board.
Flash one or all connected MicroPython boards with a specific firmware or version.

Installation

To install mpflash, you can use either of the following commands:

uv tool install mpflash
pipx install mpflash
pip install mpflash

Basic usage

You can use mpflash to perform various operations on your MicroPython boards. Here is an example of basic usage:

| Command | Description | |---------|-------------| | mpflash list | List the connected board(s) including their firmware details | | mpflash flash | Flash the latest stable firmware to the connected board(s), downloading the firmware if needed | | mpflash download | Download the MicroPython firmware(s) for the connected board(s) |

Listing connected boards:
mpflash list will list all connected boards in a table , including their serial port, family, board name, CPU, version and build number. Options are available to list the boards in a json format, or to filter the list by serial port or board type.

Flashing boards with new firmware:
mpflash flash will flash the latest stable firmware to all connected boards, downloading the firmware if needed. It will try to determine the current micropython borad and variant, download the firmware if needed, and flash the correct firmware to each board.

Common options are:

--version to specify the version of the firmware to flash, defaults to the latest stable version.
--serial to specify the serial port(s) to flash, defaults to all connected boards.
--board to specify which firmware to flash to a single board
--variant to specify a specific variant of the board

Downloading firmware: mpflash download will download the latest stable firmware for all connected boards, or a specific board if specified. It will download the firmware from the official MicroPython website and save it in your Downloads/firmware directory.
When a board is specified for which multiple variants are available, all variants will be downloaded.

Common options are:

--version to specify the version of the firmware to download, defaults to the latest stable version. (e.g. stable, preview, x.y.z)
--serial to specify the serial port(s) to flash, defaults to all connected boards.
--board to specify which firmware to flash to a single board

Setting the Firmware Files and Database Location

You can override the default location for firmware files and the MPFlash database by setting the MPFLASH_FIRMWARE environment variable. For example, in a Bash shell:

export MPFLASH_FIRMWARE="/path/to/custom/firmware"

When this variable is set, mpflash will use that location to store firmware files and estabish it's database.

Selecting or ignoring specific serial ports

You can use the --serial option to select a specific serial port(s) to flash,
Or you can use the --ignore option to ignore a specific serial port(s).

Either option can be specified multiple times, can be globs (e.g. COM*) or exact port names (e.g. /dev/ttyUSB0). To permenently ignore a port, you can set the MPFLASH_IGNORE environment variable to a space-separated list of serial ports or globs.

In addition there is a --bluetooth option to simplify ignoring bluetooth ports, where the default is to ignore bluetooth ports.

--serial,--serial-port      -s      SERIALPORT  Serial port(s) (or globs) to list. [default: *]                                                                                                                                                                           > > --ignore                    -i      SERIALPORT  Serial port(s) (or globs) to ignore. Defaults to MPFLASH_IGNORE.                                                                                                                                                          │
--bluetooth/--no-bluetooth  -b/-nb              Include bluetooth ports in the list [default: no-bluetooth]

Distinguishing similar boards

The mpflash list command will list all connected boards, but sometimes you have multiple boards of the same type connected. To help you identify the boards, you can add a board_info.toml file to the top/default folder for the board. This file can contain a description of the board, which will be shown in the list and json output.

description = "Blue Norwegian actuator"

If you want the board to be ignored by mpflash, no matter which serial port it is connected to, you can add the following to the board_info.toml file:

description = "Blue Norwegian actuator"
[mpflash]
ignore = true

Linux permissions to access usb devices

In order to flash the firmware to the board, you need to have the correct permissions to access the USB devices. On Windows this will not be an issue, but on Linux you can use udev rules to give non-root users access to the USB devices. See the stm32_permissions documentation for more information.

Use MPFlash in your own project

MPFlash can be used as a library in your own project. mpflash is used in micropython-stubber to download and flash the firmware to the connected boards.

⚠️ API Changes: The worklist module API has been completely refactored in v1.25.1+. Legacy functions have been removed. See API Documentation for the new interface.

# Modern API example
from mpflash.flash.worklist import create_worklist
from mpflash.connected import get_connected_comports

# Get connected boards and create worklist
boards = get_connected_comports()
tasks = create_worklist("1.25.0", connected_comports=boards)

# Process tasks
for task in tasks:
    if task.is_valid:
        print(f"{task.board.serialport} -> {task.firmware_version}")

The interface is documented in:

API Reference - Complete programming interface
API Examples - Jupyter notebook with examples

Detailed usage

You can list the connected boards using the following command:

$> mpflash list
                                               Connected boards
┏━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━┓
┃ Serial  ┃Family       ┃Port  ┃Board                                      ┃CPU     ┃Version          ┃build ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━┩
│ COM21   │micropython  │rp2   │RPI_PICO                                   │RP2040  │v1.23.0-preview  │  236 │
│         │             │      │Raspberry Pi Pico with RP2040              │        │                 │      │
│ COM23   │micropython  │rp2   │RPI_PICO_W

Mpflash

Install / Use

README