mpflash 1.28.1.dev2__tar.gz → 1.28.3__tar.gz

mpflash-1.28.3/.env

@@ -0,0 +1,43 @@
+# Python .env file ..
+
+# PYTHONPYCACHEPREFIX=__my_pycache
+
+JUPYTER_PLATFORM_DIRS=1
+PYDEVD_DISABLE_FILE_VALIDATION=1
+# Allow tests to find sources
+PYTHONPATH = src
+
+# give 20 secs to complete : subprocess.getstatusoutput
+PYDEVD_WARN_EVALUATION_TIMEOUT = 20
+
+# stop nagging for updates
+PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# stop neggin during debug
+JUPYTER_PLATFORM_DIRS=1
+PYDEVD_DISABLE_FILE_VALIDATION=1
+
+
+MPFLASH_FIRMWARE=./scratch
+MICROPY_DIR=~/micropython
+
+# -----------------------------------------------------------------------------------------------
+# HIL testing 
+# -----------------------------------------------------------------------------------------------
+# UF2 - RPI Pico2 on WSL
+# MPFLASH_HW_UF2_PORT=/dev/ttyACM1
+# MPFLASH_HW_UF2_FW=/mnt/c/Users/jos_v/Downloads/firmware/rp2/RPI_PICO2-v1.28.0.uf2
+
+# # DFU - PYBV11 on WSL
+# MPFLASH_HW_DFU_PORT=/dev/ttyACM0
+# MPFLASH_HW_DFU_FW=/mnt/c/Users/jos_v/Downloads/firmware/stm32/PYBV11-DP-v1.28.0.dfu
+
+# # PYOCD - PYBV11 on WSL
+# # MPFLASH_HW_PYOCD_PROBE=066CFF514949877187244446
+# MPFLASH_HW_PYOCD_PROBE=auto
+# MPFLASH_HW_PYOCD_PORT=/dev/ttyACM1
+# MPFLASH_HW_PYOCD_FW=/mnt/c/Users/jos_v/Downloads/firmware/stm32/PYBV11-DP-v1.28.0.hex
+
+# # esptool - ESP32 on WSL
+# MPFLASH_HW_ESP_PORT=/dev/ttyUSB0
+# MPFLASH_HW_ESP_FW=/mnt/c/Users/jos_v/Downloads/firmware/esp32/ESP32_GENERIC-SPIRAM-v1.28.0.bin

{mpflash-1.28.1.dev2 → mpflash-1.28.3}/.github/workflows/copilot-setup-steps.yml

@@ -26,7 +26,7 @@ jobs:
     # If you do not check out your code, Copilot will do this for you.
     steps:
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v7
         with:
           version: "latest"
 

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

@@ -53,12 +53,12 @@ jobs:
             # uv is not in the default image
             #----------------------------------------------
             - name: Install the latest version of uv
-              uses: astral-sh/setup-uv@v8.2.0
+              uses: astral-sh/setup-uv@v7
               with:
                   version: "latest"
 
             - name: Set up Python ${{ matrix.python-version }}
-              uses: actions/setup-python@v6
+              uses: actions/setup-python@v7
               with:
                   python-version: ${{ matrix.python-version }}
                   #   cache: "poetry"
@@ -66,14 +66,14 @@ jobs:
             #----------------------------------------------
             # install project
             #----------------------------------------------
-            - name: Install mpflash & test dependencies
-              run: uv sync --extra test
+            - name: Install mpflash & test dependencies (all extras)
+              run: uv sync --all-extras
 
             - name: Test mpflash
               run: |
                   # run once to bootstrap database (test hack)
                   uv run mpflash download --board RPI_PICO
-                  uv run pytest --cov --cov-branch --cov-report=xml
+                  uv run pytest --cov --cov-branch --cov-report=xml --junitxml=results/junit.xml
 
             #----------------------------------------------
             # upload coverage stats
@@ -81,13 +81,18 @@ jobs:
             #----------------------------------------------
 
             - name: Upload coverage-mpflash-*.xml to Codecov
-              if: always() # ignore errors
+              if:  ${{ !cancelled() }}
               continue-on-error: true
               uses: codecov/codecov-action@v7
               with:
-                  token: ${{ secrets.CODECOV_TOKEN }}
-                  # fail_ci_if_error: false
-                  # file: results/coverage-mpflash-${{ matrix.python-version }}-${{ matrix.os }}.xml
-                  # flags: mpflash
+                token: ${{ secrets.CODECOV_TOKEN }}
+                fail_ci_if_error: false
 
+            - name: Upload test results to Codecov
+              if: ${{ !cancelled() }}
+              uses: codecov/test-results-action@v1
+              with:
+                token: ${{ secrets.CODECOV_TOKEN }}
+                files: results/junit.xml
+                fail_ci_if_error: false
 

{mpflash-1.28.1.dev2 → mpflash-1.28.3}/.github/workflows/release.yml

@@ -11,10 +11,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.14"
           enable-cache: true
@@ -23,7 +23,7 @@ jobs:
         run: uv build
 
       - name: Upload distribution artefacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -42,7 +42,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artefacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -56,13 +56,13 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # Full history so --generate-notes can resolve the previous tag.
           fetch-depth: 0
 
       - name: Download distribution artefacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{mpflash-1.28.1.dev2 → mpflash-1.28.3}/.vscode/settings.json

@@ -36,13 +36,20 @@
         "statusBar.background": "#b30a60",
         "statusBar.foreground": "#e7e7e7",
         "statusBarItem.hoverBackground": "#e30d7a",
-        "statusBarItem.remoteBackground": "#b30a60",
+        "statusBarItem.remoteBackground": "#101e02",
         "statusBarItem.remoteForeground": "#e7e7e7",
         "tab.activeBorder": "#e30d7a",
         "titleBar.activeBackground": "#b30a60",
         "titleBar.activeForeground": "#e7e7e7",
         "titleBar.inactiveBackground": "#b30a6099",
-        "titleBar.inactiveForeground": "#e7e7e799"
+        "titleBar.inactiveForeground": "#e7e7e799",
+        "activityBarTop.activeBackground": "#e30d7a",
+        "activityBarTop.background": "#e30d7a",
+        "activityBarTop.foreground": "#e7e7e7",
+        "activityBarTop.inactiveForeground": "#e7e7e799",
+        "commandCenter.foreground": "#e7e7e7",
+        "statusBar.debuggingBackground": "#b30a60",
+        "statusBar.debuggingForeground": "#e7e7e7"
     },
     "python.terminal.activateEnvInCurrentTerminal": true,
     "todo-tree.filtering.ignoreGitSubmodules": true,

{mpflash-1.28.1.dev2 → mpflash-1.28.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpflash
-Version: 1.28.1.dev2
+Version: 1.28.3
 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
@@ -40,6 +40,7 @@ Requires-Dist: platformdirs>=4.2.0
 Requires-Dist: psutil<8.0.0,>=7.0.0
 Requires-Dist: pygithub>=2.1.1
 Requires-Dist: pytest-cov>=7.0.0
+Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyusb>=1.2.1
 Requires-Dist: pywin32>=310; sys_platform == 'win32'
 Requires-Dist: questionary>=2.0.0
@@ -48,8 +49,14 @@ Requires-Dist: rich-click>=1.8.1
 Requires-Dist: tenacity==9.1.4
 Requires-Dist: tomli-w>=1.2.0
 Requires-Dist: tomli>=2.2.1
+Provides-Extra: build
+Requires-Dist: mpbuild<1.0.0,>=0.5.0; (python_version < '3.12') and extra == 'build'
+Requires-Dist: mpbuild>=1.0.0; (python_version >= '3.12') and extra == 'build'
 Provides-Extra: dev
 Requires-Dist: keyring>=25.6.0; extra == 'dev'
+Provides-Extra: pyocd
+Requires-Dist: libusb-package==1.0.26.1; (python_version >= '3.14') and extra == 'pyocd'
+Requires-Dist: pyocd>=0.44.1; extra == 'pyocd'
 Provides-Extra: test
 Requires-Dist: coverage<8.0.0,>=6.4.3; extra == 'test'
 Requires-Dist: distro>=1.8.0; extra == 'test'

{mpflash-1.28.1.dev2 → mpflash-1.28.3}/docs/contributing.md

@@ -527,18 +527,28 @@ To add support for a new hardware platform:
 
 ## Release Process
 
-### Version Bumping
+### Version Bumping & Tagging
 
-MPFlash uses semantic versioning:
+MPFlash uses semantic versioning and releases are automated via GitHub Actions.
+Pushing a `v*` tag triggers [`.github/workflows/release.yml`](../.github/workflows/release.yml),
+which builds the sdist + wheel, publishes to PyPI (trusted publishing) and creates
+a GitHub release with generated notes.
+
+Use the `just release` recipe to cut a release. It runs in the safe order - tests
+first, then version bump and tag push:
 
 ```bash
-# Update version in pyproject.toml manually
-# Or use a tool like bump2version:
-# bump2version patch   # for bug fixes
-# bump2version minor   # for new features  
-# bump2version major   # for breaking changes
+just release           # next patch version (default)
+just release dev       # next dev prerelease
+just release minor     # next minor version
+just release major     # next major version
 ```
 
+This runs `uv run pytest`, then `uv version --bump <bump>`, commits the change,
+creates an annotated `vX.Y.Z` tag and pushes it with `git push --follow-tags`.
+Accepted bump values: `major`, `minor`, `patch`, `stable`, `alpha`, `beta`, `rc`,
+`post`, `dev`.
+
 ### Changelog
 
 Update the changelog for releases:
@@ -564,13 +574,14 @@ Update the changelog for releases:
 
 ### Pre-release Checklist
 
-Before releasing:
+Before running `just release`:
 
-- [ ] All tests passing
 - [ ] Documentation updated
-- [ ] Version bumped appropriately
 - [ ] Changelog updated
-- [ ] No breaking changes without major version bump
+- [ ] Correct bump chosen (no breaking changes without a major version bump)
+- [ ] On the branch you intend to release from
+
+`just release` then runs the tests, bumps the version and pushes the tag for you.
 
 ## Getting Help
 

{mpflash-1.28.1.dev2 → mpflash-1.28.3}/docs/developer.md

@@ -447,26 +447,47 @@ Use the configured tasks for development:
 
 ## Release Process
 
-### Version Management
-```bash
-# Update version in pyproject.toml using either
-uv version <new_version>  
-uv version --bump patch 
+Releases are automated through GitHub Actions. Pushing a `v*` tag triggers
+[`.github/workflows/release.yml`](../.github/workflows/release.yml), which:
+
+1. Builds the sdist and wheel with `uv build`
+2. Publishes them to PyPI using **trusted publishing** (OIDC, no token required)
+3. Creates a GitHub release with auto-generated notes
+
+### Cutting a release
+
+The `just release` recipe drives the whole local flow in the safe order - it runs
+the tests first, and only then bumps the version and pushes the tag:
 
-# Recommended: update the included boards & description information
+```bash
+# 1. (optional) refresh the bundled boards & descriptions before releasing
 uv run mpflash/db/gather_boards.py --mpy-path ../micropython
 
-# Build package
-uv build
+# 2. run tests, bump the version, commit, tag and push (triggers the PyPI release)
+just release           # next patch version (default)
+just release dev       # next dev prerelease
+just release minor     # next minor version
+```
 
-# Publish to PyPI
-# set token in environment variable
+`just release` performs, in order:
 
-```pwsh
-uv install keyring
-$env:UV_PUBLISH_TOKEN=(python -m keyring get pypi uv_publish
-del env:UV_PUBLISH_TOKEN
+1. `uv run pytest` - abort the release if any test fails
+2. `uv version --bump <bump>` - update `pyproject.toml` and re-lock
+3. `git commit` the version change
+4. `git tag -a vX.Y.Z` and `git push --follow-tags`
+
+The accepted bump values are `major`, `minor`, `patch` (default), `stable`,
+`alpha`, `beta`, `rc`, `post` and `dev`.
+
+### Manual fallback
+
+Only if the GitHub Actions publish is unavailable:
+
+```bash
+just build     # or: uv build
+just publish   # or: uv publish   (requires PyPI credentials)
 ```
+
 ### Documentation Updates
 - Update README.md with new features
 - Add changelog entries

{mpflash-1.28.1.dev2 → mpflash-1.28.3}/docs/stm32_udev_rules.md

@@ -1,24 +1,47 @@
-## Linux permissions for usb devices 
+## Linux permissions for USB devices
 
-In order to flash the firmware to the board, you need to have the correct permissions to access the USB devices.
-The details will depend on the specific USB device and the operating system you are using.
+In order to flash STM32 boards in DFU mode without `sudo`, your user needs
+permission on the DFU USB device node.
 
-You can use the following udev rules to give non-root users access to the USB devices.
+Ready-to-use rule file in this repository:
+
+- `mpflash/udev_rules/65-mpflash-stm32-dfu.rules`
+
+### Install (copy/paste)
 
-File: `/etc/udev/rules.d/65-mpflash.rules`
 ```bash
-# allow non-root users to access to stm32 device in dfu mode (bootloader)
-SUBSYSTEM=="usb", ACTION=="add", ATTR{product}=="STM32  BOOTLOADER", GROUP="plugdev", MODE="0660"
+sudo cp mpflash/udev_rules/65-mpflash-stm32-dfu.rules /etc/udev/rules.d/65-mpflash-stm32-dfu.rules
+sudo udevadm control --reload-rules
+sudo udevadm trigger
 ```
-reload the udev rules with the following command:
+
+Then unplug/replug the STM32 board (or re-enter DFU mode).
+
+### Rule contents
+
+```udev
+# mpflash STM32 DFU access rule
+# Device: STMicroelectronics STM Device in DFU Mode (0483:df11)
+SUBSYSTEM=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="df11", MODE="0660", GROUP="plugdev", TAG+="uaccess"
+```
+
+### Verify
+
+```bash
+lsusb | grep -i "0483:df11"
+groups
+```
+
+If your user is not in `plugdev`, add it and log out/in once:
+
 ```bash
-sudo udevadm control --reload
+sudo usermod -aG plugdev "$USER"
 ```
-Unplug and replug the usb device to apply the new rules.
 
 
-## to check 
-Enter the stm32 bootloader mode
+## To check
+
+Enter STM32 bootloader mode:
 ``` bash
 mpremote bootloader 
 ```
@@ -49,14 +72,14 @@ List usb devices
         ID 8087:0aaa Intel Corp. Bluetooth 9460/9560 Jefferson Peak (JfP)
         /sys/bus/usb/devices/1-10  /dev/bus/usb/001/003
 ```
-Lookup the stm32 device device path ( /dev/bus/usb/001/022),  
-and check if the group `plugdev` is granted access using `ll`
+Lookup the STM32 device path (`/dev/bus/usb/001/022`), and check if group
+`plugdev` is granted access:
 ```bash
 (.venv) jos@jvnuc:~/projects/mpflash$ ll /dev/bus/usb/001/022
 crw-rw-r-- 1 root plugdev 189, 21 mrt 11 22:38 /dev/bus/usb/001/022
 ```
 
-Check `groups` to see if user is in plugdev group
+Check `groups` to see if user is in `plugdev`:
 ```
 (.venv) jos@jvnuc:~/projects/mpflash$ groups
 jos adm disk dialout cdrom sudo dip plugdev kvm lpadmin lxd sambashare usb

mpflash-1.28.3/justfile

@@ -0,0 +1,87 @@
+
+# Set shell for Windows OSs:
+set windows-shell := ["pwsh.exe", "-NoLogo", "-Command"]
+
+# Show recipes
+help:
+  @just --list
+
+# install project in edi mode and install dev dependencies
+sync: 
+  uv sync --extra dev,test,pyocd
+
+init:
+  @just sync
+
+# run full pytest suite
+test: 
+  uv run pytest -v
+
+# create coverage report, build html report
+coverage:
+  uv run pytest --cov --cov-report=term-missing
+  coverage html
+  start coverage/index.html
+
+# bump mpflash's version [major, minor, patch, stable, alpha, beta, rc, post, dev]
+bump bump="patch":
+  uv version --bump {{bump}}
+
+# build the project for distribution
+build:
+  uv build
+
+# -----------------------------------------------------------------------------------------------
+# Release process
+# Pushing a `v*` tag triggers .github/workflows/release.yml, which builds the sdist + wheel,
+# publishes to PyPI using trusted publishing (OIDC, no token) and creates a GitHub release
+# with auto-generated notes. Use `just release` to cut a release; do not publish manually.
+# -----------------------------------------------------------------------------------------------
+
+# run tests, bump the version, then commit, tag and push - triggering the PyPI release
+# bump = major | minor | patch (default) | stable | alpha | beta | rc | post | dev
+[confirm("Run tests, bump the version and push a new tag? This triggers a PyPI release. Continue?")]
+release bump="patch":
+  uv run pytest
+  uv version --bump {{bump}}
+  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
+
+# 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?")]
+publish : build
+  uv publish
+
+# delete and regen the lockfile - useful in merge conficts
+lock:
+  del uv.lock -erroraction ignore
+  uv lock
+
+# -----------------------------------------------------------------------------------------------
+# HIL testing 
+# Configure environment for the port and firmware selection in the .env file, then run the test suite 
+# -----------------------------------------------------------------------------------------------
+# export LOGURU_LEVEL := "TRACE"
+export LOGURU_LEVEL := "INFO"
+
+hil_uf2_pico2:
+    uv run pytest -m hw_uf2 tests/hw -v
+
+hil_dfu_pybv11:
+    uv run pytest -m hw_dfu tests/hw -v
+
+hil_pyocd_pybv11:
+  uv run pytest -m hw_pyocd tests/hw -v
+
+hil_esptool_esp32:
+  uv run pytest -m hw_esptool tests/hw -v
+
+# [script('python')]
+# python:
+#   print('Hello from python!')
+#   from pathlib import Path
+#   print(f'Current directory: {Path.cwd()}')
+
+

mpflash-1.28.3/mpflash/bootloader/activate.py

@@ -0,0 +1,118 @@
+"""Drive a board into bootloader mode using pluggable activators.
+
+The orchestration walks the ordered list of activators returned by
+:func:`mpflash.bootloader.registry.resolve_methods`, calling each in turn
+and confirming with :func:`mpflash.bootloader.detect.in_bootloader` (which
+delegates to the flash backend's ``is_board_ready`` when one is supplied).
+
+Built-in activators register themselves on import; flash plugins can
+contribute additional activators by calling
+:func:`mpflash.bootloader.registry.register`.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from mpflash.bootloader.detect import backend_for_port, in_bootloader
+from mpflash.bootloader.registry import get_activator, resolve_methods
+from mpflash.common import BootloaderMethod
+from mpflash.errors import MPFlashError
+from mpflash.logger import log
+from mpflash.mpremoteboard import MPRemoteBoard
+from mpflash.flash.base import FlashBackend
+
+
+def enter_bootloader(
+    mcu: MPRemoteBoard,
+    method: BootloaderMethod = BootloaderMethod.MPY,
+    timeout: int = 10,
+    wait_after: int = 2,
+    *,
+    backend: Optional[FlashBackend] = None,
+) -> bool:
+    """Put the board into bootloader mode.
+
+    Args:
+        mcu: The target board.
+        method: Which BootloaderMethod to try first. AUTO walks the
+            backend's preferred order. NONE skips activation entirely.
+        timeout: Per-attempt timeout in seconds.
+        wait_after: Seconds to wait between an activator call and the
+            readiness check.
+        backend: Optional flash backend used to look up the preferred
+            activator order and to confirm readiness via
+            ``backend.is_board_ready``. When omitted, the flash registry is
+            consulted for a backend matching ``mcu.port``.
+
+    Returns:
+        True when the board is reported in bootloader mode, False if every
+        attempted activator failed.
+    """
+    if method == BootloaderMethod.NONE:
+        # No bootloader requested — assume it is OK to flash.
+        return True
+
+    if backend is None:
+        backend = backend_for_port(mcu.port)
+    preferred = list(backend.get_preferred_bootloaders(mcu)) if backend else []
+    method_list = resolve_methods(method.value, preferred)
+    if not method_list:
+        log.debug(
+            f"No bootloader activators resolved for {mcu.port} (method={method.value})"
+        )
+        return True
+
+    log.info(
+        f"Entering bootloader on {mcu.serialport} using methods {method_list}"
+    )
+
+    result = False
+    for name in method_list:
+        activator = get_activator(name)
+        if activator is None:
+            log.debug(f"Unknown bootloader activator {name!r}; skipping")
+            continue
+        try:
+            result = bool(activator.activate(mcu, timeout=timeout))
+        except MPFlashError as e:
+            log.warning(
+                f"Failed to enter bootloader on {mcu.serialport} using {name}"
+            )
+            log.exception(e)
+            result = False
+        if not result:
+            continue
+
+        # todo - check every second or so for up to max wait time
+        time.sleep(wait_after)
+        if in_bootloader(mcu, backend=backend):
+            return True
+
+        serialport = mcu.serialport
+        if serialport and serialport.lower() != "auto":
+            try:
+                connected = {port.casefold() for port in MPRemoteBoard.connected_comports()}
+            except OSError:
+                connected = {serialport.casefold()}
+            if serialport.casefold() not in connected:
+                # The serial port vanished, so the board reset into its UF2
+                # bootloader. Do not fall through to touch-1200 (which would
+                # try to open a port that no longer exists). Give the UF2
+                # volume extra time to mount and confirm it is actually there
+                # before reporting success — otherwise the flash backend will
+                # abort with "Board is not in bootloader mode".
+                log.debug(
+                    f"Serial port {serialport} disappeared after {name}; "
+                    "waiting for the UF2 drive to mount"
+                )
+                if in_bootloader(mcu, backend=backend):
+                    return True
+                log.warning(
+                    f"{serialport} reset into bootloader but the UF2 drive "
+                    "was not detected"
+                )
+                continue
+
+    return False

mpflash-1.28.3/mpflash/bootloader/base.py

@@ -0,0 +1,55 @@
+"""Abstract base class for pluggable bootloader activators.
+
+An *activator* knows one way to put a board into firmware-update / bootloader
+mode (e.g. send ``machine.bootloader()``, open the port at 1200 baud, or ask
+the user to press a button). Built-ins live in
+``mpflash.bootloader.builtins`` and register themselves at import time;
+third-party flash plugins can call :func:`mpflash.bootloader.registry.register`
+to contribute additional activators.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mpflash.mpremoteboard import MPRemoteBoard
+
+
+class BootloaderActivator(ABC):
+    """Contract every bootloader activator must implement.
+
+    Subclasses are typically singletons; the registry instantiates each
+    activator once. The ``name`` attribute must match the corresponding
+    :class:`mpflash.common.BootloaderMethod` enum *value* for the built-in
+    activators (``"mpy"``, ``"touch1200"``, ``"manual"``); plugin-supplied
+    activators may use any unique string.
+    """
+
+    #: Short identifier (matches ``BootloaderMethod.value`` for built-ins).
+    name: str = ""
+
+    def is_available(self, mcu: "MPRemoteBoard") -> bool:
+        """Runtime availability check for this MCU.
+
+        Default returns ``True``. Activators with environmental
+        prerequisites (USB drivers, GUI prompts on a headless host, …)
+        should override.
+        """
+        return True
+
+    @abstractmethod
+    def activate(self, mcu: "MPRemoteBoard", *, timeout: int = 10) -> bool:
+        """Attempt to put ``mcu`` into bootloader mode.
+
+        Returns ``True`` if the activator believes the attempt succeeded;
+        the caller is responsible for confirming readiness afterwards.
+        """
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}({self.name})"
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} name={self.name!r}>"