mpflash 1.28.3__tar.gz → 1.28.4__tar.gz

{mpflash-1.28.3 → mpflash-1.28.4}/.github/workflows/pytest_mpflash.yml

@@ -90,8 +90,9 @@ jobs:
 
             - name: Upload test results to Codecov
               if: ${{ !cancelled() }}
-              uses: codecov/test-results-action@v1
+              uses: codecov/codecov-action@v7
               with:
+                report_type: test_results
                 token: ${{ secrets.CODECOV_TOKEN }}
                 files: results/junit.xml
                 fail_ci_if_error: false

mpflash-1.28.4/CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+All notable changes to mpflash are documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- **`--format` option for `mpflash flash`** — reformats the board's filesystem after
+  flashing, recreating an empty filesystem of the same type (`VfsLfs2` or `VfsFat`) via
+  the MicroPython block device. Supported on `rp2`, `esp32`, `esp8266`, `samd`, `stm32`,
+  `nrf` and `mimxrt`. The mount point and filesystem type are detected at runtime using
+  the same `vfs.mount()` enumeration as `mpremote df`.
+- **`mpflash format` command** — reformats the filesystem of connected boards without
+  flashing new firmware. Asks for confirmation before erasing (skip with `--yes`) and
+  supports the same ports as `flash --format`.
+- **`mpflash erase` command** — erases the filesystem of connected boards via the
+  MicroPython block device and reboots them, without flashing new firmware. Reuses the
+  `flash --erase` implementation. Asks for confirmation before erasing (skip with
+  `--yes`). Supported on `rp2`, `samd` and `nrf`.
+
+## [1.28.3] - 2026-07-26
+
+This release is a major internal refactor of how mpflash flashes boards and enters
+bootloaders, turning both into pluggable, port-agnostic backends — plus two big new
+capabilities: local firmware builds via [**mpbuild**](https://github.com/mattytrentini/mpbuild#mpbuild) and SWD/JTAG flashing via [**pyOCD**](https://pyocd.io/).
+
+### Highlights
+
+- **Pluggable flash backends and bootloader activation** shared across MicroPython ports (UF2, DFU, esptool, pyOCD).
+- **mpbuild integration** — build firmware locally right before flashing. *(Andrew Leech & Jos Verlinde)*
+- **pyOCD integration** — flash STM32 / RP2040 / SAMD over a debug probe. *(Andrew Leech & Jos Verlinde)*
+- **`--erase` now uses the MicroPython block device** instead of vendored flash-nuke images.
+
+### Flash backend architecture
+
+The monolithic flash logic (`mpflash/flash/stm32.py`, `esp.py`, `uf2/`) has been
+reorganized into a registry of self-describing backends under `mpflash/flash/builtins/`
+(`uf2_backend`, `dfu_backend`, `esptool_backend`, `pyocd_backend`), each declaring the
+ports and firmware formats it supports and a priority. New `flash/registry.py`,
+`flash/base.py`, `flash/context.py` and `flash/services.py` provide the shared plumbing,
+and `flash_mcu(..., method=FlashMethod.<X>)` selects a backend automatically.
+
+- New **`mpflash plugins`** command lists every registered backend and its support matrix (`--format table|plain`).
+- `FlashMethod` enum added to `common.py`; `--method / --flash-method` gains `auto` (default) and `pyocd`.
+- Third-party backends can register via entry points.
+
+### Bootloader activation plugins
+
+Bootloader entry has been refactored into a plugin structure (`bootloader/registry.py`,
+`bootloader/base.py`, `bootloader/builtins/` with `manual`, `touch1200` and a new `mpy`
+MicroPython-reset activator). Detection (`bootloader/detect.py`) was reworked, and a bug
+was fixed where, if the serial port disappeared after an activator (board already reset
+into its UF2 bootloader), mpflash would incorrectly fall through to a touch-1200 on a
+now-missing port — it now re-checks bootloader state and waits for the UF2 volume to
+mount before reporting success.
+
+### mpbuild integration (build firmware locally) — *Andrew Leech & Jos Verlinde*
+
+New `mpflash/build.py` with a `BuildManager` that builds MicroPython firmware on demand:
+
+- New flash flags: **`--build`** (build with mpbuild before flashing) and **`--clean`** (run `mpbuild clean` first).
+- Build caching, dependency validation (checks for mpbuild + Docker), and per-port
+  preferred output formats (e.g. `.bin` for esptool, `.uf2` for UF2, `.dfu/.bin` for DFU,
+  `.bin/.hex/.elf/.axf` for pyOCD).
+- Built artifacts are imported into the mpflash firmware database and a ready-to-run
+  `mpflash flash …` command is printed so you can re-flash without rebuilding.
+
+### pyOCD integration (SWD/JTAG flashing) — *Andrew Leech & Jos Verlinde*
+
+Flash STM32, RP2040 and SAMD boards through a CMSIS-DAP / ST-Link / J-Link probe
+(`flash/builtins/pyocd/`):
+
+- New flash options: **`--method pyocd`**, **`--probe / --probe-id`**, **`--target`**
+  (explicit pyOCD target override) and **`--auto-install-packs / --no-auto-install-packs`** (default on).
+- Probe discovery, MCU-info parsing with fuzzy target matching, dynamic target detection,
+  and automatic CMSIS pack installation for missing targets.
+- New commands: **`mpflash list-probes`**, **`mpflash pyocd-info`**, **`mpflash pyocd-targets`**
+  (with `--board-filter` / `--target-filter`).
+- ESP32/ESP8266 are intentionally excluded (use esptool).
+- Extensive unit tests with mocked hardware so the suite runs without a probe or pyOCD installed.
+
+### Filesystem erase via serial block device
+
+`--erase` no longer relies on  `universal_flash_nuke.uf2` for rp2xxx boards, or a post-flash
+`rm -r :` on others. Instead `mpremoteboard/erase_bdev.py` erases the filesystem block
+device using `mpremoteboard/erase_bdev.py` and calls `machine.reset()`, leaving the board with a
+fresh filesystem. Bootloader entry is now a separate, explicit step, and `flash_uf2` only
+copies firmware. 
+The previously vendored pico-universal-flash-nuke image by @Gadgetoid is no longer needed.
+
+### UF2 reliability fixes
+
+- **Windows drive detection** uses `psutil.disk_partitions(all=True)` and polls twice per
+  second so a freshly-mounted removable volume isn't filtered out or missed.
+- **`wait_for_restart()` now returns a bool** via a bounded quiet probe, so callers can
+  detect when a board never reconnects.
+- **No more false "copy failed" retries**: mpflash stopped copying file metadata to UF2
+  destinations — the bootloader could consume the firmware and disconnect before the
+  metadata step, causing a false failure and three useless retries.
+
+### Board & port detection
+
+- Added `best_matching_port` and a `sys_platform` attribute to `MPRemoteBoard`, improving
+  reconnection to the correct serial port after a reset.
+- Additional known-board mappings.
+
+### Configuration & environment
+
+- Loads environment variables from a **`.env`** file and expands `~` in user-supplied paths.
+
+### Linux / udev rules
+
+- Bundled udev rules for ST-Link v2 / v2-1 / v3, WCH-Link, CMSIS-DAP, picoprobe and STM32
+  DFU (`mpflash/udev_rules/`, with a README), and expanded `docs/stm32_udev_rules.md` to
+  cover the debug probes needed by pyOCD.
+
+### Security & quality
+
+- Removed use of `eval()` in favor of safe parsing, plus reformatting/cleanups.
+
+### Tooling, CI & docs
+
+- **Automated release process**: pushing a `v*` tag triggers build + PyPI trusted
+  publishing + GitHub release; new `just release` recipe runs tests, bumps the version,
+  tags and pushes. Documented in `docs/developer.md` and `docs/contributing.md`.
+- CI installs all extras and uploads coverage + JUnit test results to Codecov; new **HIL
+  testing** support (`--HIL <port>` pytest option and `just hil_*` targets) with a hardware
+  filesystem-erase test.
+- Dependency bumps: `actions/checkout` 4→7, `actions/setup-python` 6→7,
+  `actions/upload-artifact` 4→7, `actions/download-artifact` 4→8, `astral-sh/setup-uv` 6→7.
+
+### Dependencies
+
+- Added `python-dotenv>=1.0.0`.
+- New optional **`pyocd`** extra: `pyocd>=0.44.1`, `mpbuild>=1.0.0` (Python ≥ 3.12) /
+  `mpbuild>=0.5.0,<1.0.0` (Python < 3.12). Install with `uv sync --extra pyocd` or
+  `pip install "mpflash[pyocd]"`.
+
+### Upgrade notes / breaking changes
+
+- **Internal flash modules moved** under `mpflash/flash/builtins/…` (e.g. `flash/stm32.py`
+  → `flash/builtins/dfu/`, `flash/esp.py` → `flash/builtins/esp/`, `flash/uf2/` →
+  `flash/builtins/uf2/`). Use the public `mpflash.flash.flash_mcu(method=…)` entry point
+  rather than importing these paths directly.
+- **`--erase` is now a serial block-device erase** (board must be reachable on
+  MicroPython), not a flash-nuke image; the vendored `universal_flash_nuke.uf2` was removed.
+
+## [1.26.0] - Breaking API changes
+
+**Important for library users**: the worklist module API was completely refactored, with
+breaking changes. Legacy worklist functions were **removed**.
+
+### Removed
+
+- `auto_update_worklist()`, `manual_worklist()`, `manual_board()`,
+  `single_auto_worklist()`, `full_auto_worklist()`, `filter_boards()`.
+
+### Changed
+
+- New modern interface with `create_worklist()`, the `FlashTask` dataclass and
+  `WorklistConfig` objects. See `docs/api-reference.md` for the migration guide.
+- The command-line interface remains fully compatible.
+
+## [1.25.0.post2]
+
+### Added
+
+- `--variant` option to select a specific board variant when flashing.
+- SQLite database storing information on all possible MicroPython firmwares and the
+  management of downloaded firmware files, for better board identification and firmware matching.
+- Use the MicroPython v1.25.0 `sys.implementation._build` as `board_id` when available.
+- Automatic firmware download when not yet available locally (no longer need the `--download` option).
+
+### Changed
+
+- Restructured `mpboard_id` to use a SQLite database to identify more boards and variants.
+- Vendored and adapted `board_database.py` from mpflash — kudos @mattytrentini.
+

{mpflash-1.28.3 → mpflash-1.28.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpflash
-Version: 1.28.3
+Version: 1.28.4
 Summary: Flash and download tool for MicroPython firmwares
 Project-URL: Homepage, https://github.com/Josverl/mpflash
 Project-URL: Documentation, https://github.com/Josverl/mpflash/blob/main/README.md
@@ -92,38 +92,23 @@ The interactive prompts use [**rich-inquirer**](https://pypi.org/project/rich-in
     - `esp32`, using `.bin`, using esptool,
     - `esp8266`, using `.bin`, using esptool
     - `stm32`, using ` .dfu`, using pydfu (also in Windows) 
+    - `nrf`, using `.uf2`, using filecopy
 
-Not yet implemented: `nrf`, `cc3200`, `mimxrt`, `renesas`
+Not yet implemented: `alif`, `mimxrt`, `psoc-edge`, `renesas-ra`, `zephyr`
+Not planned: `cc3200`, `pic16bit`
 
-## 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
+## Features
 
-See [API Documentation](docs/api-reference.md) for complete migration guide.
+ - **List connected boards** — show firmware details for all attached boards in a table or JSON format.
+ - **Download firmware** — fetch MicroPython firmware for a version, matched to a specified board or your attached board(s).
+ - **Flash boards** — flash one or all connected boards with a specific firmware or version, downloading it if needed.
+ - **Flash via a debug probe (pyOCD)** — program `stm32`, `rp2` and `samd` targets over SWD/JTAG using a CMSIS-DAP / ST-Link / J-Link probe with `mpflash flash --method pyocd`. CMSIS packs for missing targets are installed automatically. Install with `pip install "mpflash[pyocd]"`.
+ - **Build firmware locally (mpbuild)** — use `mpflash flash --build` to compile MicroPython with [mpbuild](https://pypi.org/project/mpbuild/) (requires Docker) right before flashing.
+ - **Pluggable flash & bootloader backends** — flashing and bootloader activation are selectable, port-agnostic plugins, and third-party backends can register their own. List them with `mpflash plugins`.
+ - **Filesystem erase over serial** — `--erase` wipes the MicroPython filesystem via its block device.
+ - **Filesystem format over serial** — `--format` recreates an empty MicroPython filesystem after flashing, keeping the same filesystem type (`VfsLfs2` or `VfsFat`).
+ - **Probe & target info** — inspect probes and supported targets with `mpflash list-probes`, `mpflash pyocd-info` and `mpflash pyocd-targets`.
 
- 
-## Features
- 1. List the connected boards including their firmware details, in a tabular or json format
- 2. Download MicroPython firmware for versions, and matching a specified board or matches your current attached board.
- 3. 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`
@@ -138,6 +123,8 @@ You can use mpflash to perform various operations on your MicroPython boards. He
 | `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) |
+| `mpflash format` | Reformat the filesystem of the connected board(s) without flashing new firmware |
+| `mpflash erase` | Erase the filesystem of the connected board(s) and reboot, without flashing new firmware |
 
 **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.

{mpflash-1.28.3 → mpflash-1.28.4}/README.md

@@ -18,38 +18,23 @@ The interactive prompts use [**rich-inquirer**](https://pypi.org/project/rich-in
     - `esp32`, using `.bin`, using esptool,
     - `esp8266`, using `.bin`, using esptool
     - `stm32`, using ` .dfu`, using pydfu (also in Windows) 
+    - `nrf`, using `.uf2`, using filecopy
 
-Not yet implemented: `nrf`, `cc3200`, `mimxrt`, `renesas`
+Not yet implemented: `alif`, `mimxrt`, `psoc-edge`, `renesas-ra`, `zephyr`
+Not planned: `cc3200`, `pic16bit`
 
-## 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
+## Features
 
-See [API Documentation](docs/api-reference.md) for complete migration guide.
+ - **List connected boards** — show firmware details for all attached boards in a table or JSON format.
+ - **Download firmware** — fetch MicroPython firmware for a version, matched to a specified board or your attached board(s).
+ - **Flash boards** — flash one or all connected boards with a specific firmware or version, downloading it if needed.
+ - **Flash via a debug probe (pyOCD)** — program `stm32`, `rp2` and `samd` targets over SWD/JTAG using a CMSIS-DAP / ST-Link / J-Link probe with `mpflash flash --method pyocd`. CMSIS packs for missing targets are installed automatically. Install with `pip install "mpflash[pyocd]"`.
+ - **Build firmware locally (mpbuild)** — use `mpflash flash --build` to compile MicroPython with [mpbuild](https://pypi.org/project/mpbuild/) (requires Docker) right before flashing.
+ - **Pluggable flash & bootloader backends** — flashing and bootloader activation are selectable, port-agnostic plugins, and third-party backends can register their own. List them with `mpflash plugins`.
+ - **Filesystem erase over serial** — `--erase` wipes the MicroPython filesystem via its block device.
+ - **Filesystem format over serial** — `--format` recreates an empty MicroPython filesystem after flashing, keeping the same filesystem type (`VfsLfs2` or `VfsFat`).
+ - **Probe & target info** — inspect probes and supported targets with `mpflash list-probes`, `mpflash pyocd-info` and `mpflash pyocd-targets`.
 
- 
-## Features
- 1. List the connected boards including their firmware details, in a tabular or json format
- 2. Download MicroPython firmware for versions, and matching a specified board or matches your current attached board.
- 3. 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`
@@ -64,6 +49,8 @@ You can use mpflash to perform various operations on your MicroPython boards. He
 | `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) |
+| `mpflash format` | Reformat the filesystem of the connected board(s) without flashing new firmware |
+| `mpflash erase` | Erase the filesystem of the connected board(s) and reboot, without flashing new firmware |
 
 **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.

{mpflash-1.28.3 → mpflash-1.28.4}/justfile

@@ -47,7 +47,7 @@ release bump="patch":
   git add pyproject.toml uv.lock
   git commit -m "Release v$(uv version --short)"
   git tag -a "v$(uv version --short)" -m "Release v$(uv version --short)"
-  git push --follow-tags
+  git push --follow-tags --force
 
 # manual fallback: publish to PyPI directly (normally handled by GitHub Actions on tag push)
 [confirm("Are you sure you want to publish to PyPI directly? This is normally handled by GitHub Actions on tag push. Continue?")]

{mpflash-1.28.3 → mpflash-1.28.4}/mpflash/basicgit.py

@@ -99,6 +99,11 @@ def get_local_tag(repo: Optional[Union[str, Path]] = None, abbreviate: bool = Tr
     tag = tag.replace("\r", "").replace("\n", "")
     if not abbreviate or "-" not in tag:
         return tag
+    # A dirty working tree (e.g. modified git submodules) is a working-tree state
+    # marker added by `git describe --dirty`, not part of the version. Drop it so a
+    # checkout that is exactly on a tag is not misread as a dev/preview build.
+    if tag.endswith("-dirty"):
+        tag = tag[: -len("-dirty")]
     if "-preview" in tag:
         tag = tag.split("-preview")[0] + "-preview"
     return tag

mpflash-1.28.4/mpflash/cli_erase.py

@@ -0,0 +1,114 @@
+"""CLI command to erase the filesystem of connected MicroPython boards.
+
+Reuses the ``--erase`` filesystem implementation: it runs the on-device erase
+script via ``mpremote`` on each selected board, wiping the filesystem block
+device and rebooting the board (``machine.reset()``) without flashing firmware.
+"""
+
+from typing import List
+
+import rich_click as click
+
+from .cli_group import cli
+from .config import config
+from .logger import log
+
+
+@cli.command(
+    "erase",
+    short_help="Erase the filesystem of connected MicroPython boards and reboot (erases all files).",
+)
+@click.option(
+    "--serial",
+    "--serial-port",
+    "-s",
+    "serial",
+    default=["*"],
+    multiple=True,
+    show_default=True,
+    help="Which serial port(s) (or globs) to erase.",
+    metavar="SERIALPORT",
+)
+@click.option(
+    "--ignore",
+    "-i",
+    is_eager=True,
+    help="Serial port(s) to ignore. Defaults to MPFLASH_IGNORE.",
+    multiple=True,
+    default=[],
+    envvar="MPFLASH_IGNORE",
+    show_default=True,
+    metavar="SERIALPORT",
+)
+@click.option(
+    "--bluetooth/--no-bluetooth",
+    "--bt/--no-bt",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="""Include bluetooth ports in the list""",
+)
+@click.option(
+    "--yes",
+    "-y",
+    "assume_yes",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="""Do not ask for confirmation before erasing.""",
+)
+@click.pass_context
+def cli_erase_board(
+    ctx: click.Context,
+    serial: List[str],
+    ignore: List[str],
+    bluetooth: bool,
+    assume_yes: bool,
+) -> int:
+    """Erase the filesystem of connected MicroPython boards and reboot, without flashing firmware."""
+    from rich.prompt import Confirm
+
+    from .connected import list_mcus
+    from .flash.builtins.uf2.erase import SUPPORTED_PORTS, erase_filesystem
+    from .list import show_mcus
+
+    serial = list(serial)
+    ignore = list(ignore)
+
+    conn_mcus = [mcu for mcu in list_mcus(ignore=ignore, include=serial, bluetooth=bluetooth) if mcu.connected]
+    # ignore boards that have the [mpflash] ignore flag set
+    conn_mcus = [mcu for mcu in conn_mcus if not (mcu.toml.get("mpflash", {}).get("ignore", False))]
+
+    if not conn_mcus:
+        log.error("No connected MicroPython boards found to erase.")
+        ctx.exit(1)
+
+    # Only boards on a port with a known filesystem block device can be erased.
+    to_erase = [mcu for mcu in conn_mcus if mcu.port in SUPPORTED_PORTS]
+    for mcu in conn_mcus:
+        if mcu.port not in SUPPORTED_PORTS:
+            log.warning(f"Skipping {mcu.board} on {mcu.serialport}: erase is not supported for port {mcu.port!r}")
+
+    if not to_erase:
+        log.error(f"None of the connected boards support erasing (supported: {', '.join(sorted(SUPPORTED_PORTS))}).")
+        ctx.exit(1)
+
+    show_mcus(to_erase, title="Boards to erase", refresh=False)
+
+    if not assume_yes and config.interactive:
+        if not Confirm.ask("Erasing wipes ALL files on the selected board(s) and reboots it. Continue?", default=False):
+            log.info("Erase cancelled by user.")
+            ctx.exit(2)
+
+    erased = []
+    for mcu in to_erase:
+        if erase_filesystem(mcu):
+            erased.append(mcu)
+        else:
+            log.error(f"Failed to erase {mcu.board} on {mcu.serialport}")
+
+    if erased:
+        log.info(f"Erased {len(erased)} board(s)")
+        ctx.exit(0)
+    log.error("No boards were erased")
+    ctx.exit(1)

{mpflash-1.28.3 → mpflash-1.28.4}/mpflash/cli_flash.py

@@ -105,6 +105,13 @@ from mpflash.versions import clean_version
     show_default=True,
     help="""Erase flash before writing new firmware.""",
 )
+@click.option(
+    "--format/--no-format",
+    "format_fs",
+    default=False,
+    show_default=True,
+    help="""Reformat the board's filesystem after flashing (erases all files).""",
+)
 @click.option(
     "--bootloader",
     "--bl",
@@ -263,6 +270,10 @@ def cli_flash_board(ctx: click.Context, **kwargs) -> int:
     params.bootloader = BootloaderMethod(params.bootloader)
     reflash_commands: List[str] = []
 
+    # --erase and --format are mutually exclusive; only one makes sense at a time.
+    if params.erase and params.format_fs:
+        raise click.UsageError("--erase and --format cannot be used together; specify only one.")
+
     # make it simple for the user to flash one board by asking for the serial port if not specified
     if params.boards == ["?"] or params.serial == "?":  #  or params.variant == "?":
         params.serial = ["?"]
@@ -474,6 +485,7 @@ def cli_flash_board(ctx: click.Context, **kwargs) -> int:
         params.erase,
         params.bootloader,
         method=flash_method,
+        format_fs=params.format_fs,
         probe_id=probe_id,
         auto_install_packs=auto_install_packs,
         target_override=pyocd_target,

mpflash-1.28.4/mpflash/cli_format.py

@@ -0,0 +1,115 @@
+"""CLI command to reformat the filesystem of connected MicroPython boards.
+
+Runs the on-device format script via ``mpremote`` on each selected board,
+recreating an empty filesystem of the same type without flashing new firmware.
+"""
+
+from typing import List
+
+import rich_click as click
+
+from .cli_group import cli
+from .config import config
+from .errors import MPFlashError
+from .logger import log
+
+
+@cli.command(
+    "format",
+    short_help="Reformat the filesystem of connected MicroPython boards (erases all files).",
+)
+@click.option(
+    "--serial",
+    "--serial-port",
+    "-s",
+    "serial",
+    default=["*"],
+    multiple=True,
+    show_default=True,
+    help="Which serial port(s) (or globs) to format.",
+    metavar="SERIALPORT",
+)
+@click.option(
+    "--ignore",
+    "-i",
+    is_eager=True,
+    help="Serial port(s) to ignore. Defaults to MPFLASH_IGNORE.",
+    multiple=True,
+    default=[],
+    envvar="MPFLASH_IGNORE",
+    show_default=True,
+    metavar="SERIALPORT",
+)
+@click.option(
+    "--bluetooth/--no-bluetooth",
+    "--bt/--no-bt",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="""Include bluetooth ports in the list""",
+)
+@click.option(
+    "--yes",
+    "-y",
+    "assume_yes",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="""Do not ask for confirmation before formatting.""",
+)
+@click.pass_context
+def cli_format_board(
+    ctx: click.Context,
+    serial: List[str],
+    ignore: List[str],
+    bluetooth: bool,
+    assume_yes: bool,
+) -> int:
+    """Reformat the filesystem of connected MicroPython boards without flashing firmware."""
+    from rich.prompt import Confirm
+
+    from .connected import list_mcus
+    from .flash.format_fs import SUPPORTED_FORMAT_PORTS, format_filesystem
+    from .list import show_mcus
+
+    serial = list(serial)
+    ignore = list(ignore)
+
+    conn_mcus = [mcu for mcu in list_mcus(ignore=ignore, include=serial, bluetooth=bluetooth) if mcu.connected]
+    # ignore boards that have the [mpflash] ignore flag set
+    conn_mcus = [mcu for mcu in conn_mcus if not (mcu.toml.get("mpflash", {}).get("ignore", False))]
+
+    if not conn_mcus:
+        log.error("No connected MicroPython boards found to format.")
+        ctx.exit(1)
+
+    # Only boards on a port with a known filesystem block device can be formatted.
+    to_format = [mcu for mcu in conn_mcus if mcu.port in SUPPORTED_FORMAT_PORTS]
+    for mcu in conn_mcus:
+        if mcu.port not in SUPPORTED_FORMAT_PORTS:
+            log.warning(f"Skipping {mcu.board} on {mcu.serialport}: format is not supported for port {mcu.port!r}")
+
+    if not to_format:
+        log.error(f"None of the connected boards support formatting (supported: {', '.join(sorted(SUPPORTED_FORMAT_PORTS))}).")
+        ctx.exit(1)
+
+    show_mcus(to_format, title="Boards to format", refresh=False)
+
+    if not assume_yes and config.interactive:
+        if not Confirm.ask("Formatting erases ALL files on the selected board(s). Continue?", default=False):
+            log.info("Format cancelled by user.")
+            ctx.exit(2)
+
+    formatted = []
+    for mcu in to_format:
+        try:
+            if format_filesystem(mcu):
+                formatted.append(mcu)
+        except MPFlashError as e:
+            log.error(f"Failed to format {mcu.board} on {mcu.serialport}: {e}")
+
+    if formatted:
+        log.info(f"Formatted {len(formatted)} board(s)")
+        ctx.exit(0)
+    log.error("No boards were formatted")
+    ctx.exit(1)

{mpflash-1.28.3 → mpflash-1.28.4}/mpflash/cli_main.py

@@ -21,7 +21,9 @@ from mpflash.errors import MPFlashError
 
 from .cli_add import cli_add_custom
 from .cli_download import cli_download
+from .cli_erase import cli_erase_board
 from .cli_flash import cli_flash_board
+from .cli_format import cli_format_board
 from .cli_group import cli
 from .cli_list import cli_list_mcus
 from . import cli_pyocd  # noqa: F401 - registers pyOCD subcommands via @cli.command
@@ -37,6 +39,8 @@ def mpflash():
     cli.add_command(cli_download)
     cli.add_command(cli_flash_board)
     cli.add_command(cli_add_custom)
+    cli.add_command(cli_format_board)
+    cli.add_command(cli_erase_board)
 
     # cli(auto_envvar_prefix="MPFLASH")
     if False and os.environ.get("COMPUTERNAME").upper().startswith("JOSVERL"):

{mpflash-1.28.3 → mpflash-1.28.4}/mpflash/common.py

@@ -72,6 +72,7 @@ class FlashParams(Params):
     """Parameters for flashing a board"""
 
     erase: bool = True
+    format_fs: bool = False
     bootloader: BootloaderMethod = BootloaderMethod.NONE
     cpu: str = ""
     flash_mode: str = "keep"  # keep, qio, qout, dio, dout

{mpflash-1.28.3 → mpflash-1.28.4}/mpflash/flash/__init__.py

@@ -62,6 +62,7 @@ def flash_tasks(
     erase: bool,
     bootloader: BootloaderMethod,
     method: FlashMethod = FlashMethod.AUTO,
+    format_fs: bool = False,
     **kwargs,
 ):
     """Flash every entry in ``tasks`` and return the updated boards."""
@@ -236,6 +237,13 @@ def flash_tasks(
                 else:
                     mcu.toml["mpflash"].pop("custom_id", None)
                 mcu.set_board_info_toml()
+            if format_fs:
+                from mpflash.flash.format_fs import format_filesystem
+
+                try:
+                    format_filesystem(updated)
+                except MPFlashError as e:
+                    log.error(f"Failed to format filesystem on {mcu.serialport}: {e}")
             flashed.append(updated)
         else:
             log.error(f"Failed to flash {mcu.board} on {mcu.serialport}")