mpflash 1.25.0rc4__py3-none-any.whl → 1.25.2__py3-none-any.whl

mpflash/basicgit.py

@@ -135,6 +135,25 @@ def get_local_tags(repo: Optional[Path] = None, minver: Optional[str] = None) ->
     return sorted(tags)
 
 
+def get_current_branch(repo: Optional[Union[Path, str]] = None) -> Optional[str]:
+    """
+    Get the current branch name of a local repository.
+
+    Args:
+        repo: Path to the repository directory
+
+    Returns:
+        Current branch name or None if error
+    """
+    cmd = ["git", "branch", "--show-current"]
+    result = _run_local_git(cmd, repo=repo, expect_stderr=True)
+    if not result:
+        return None
+
+    branch = result.stdout.strip()
+    return branch if branch else None
+
+
 @cachetools.func.ttl_cache(maxsize=16, ttl=60)  # 60 seconds
 def get_tags(repo: str, minver: Optional[str] = None) -> List[str]:
     """

mpflash/cli_add.py

@@ -0,0 +1,131 @@
+"""CLI to add a custom MicroPython firmware."""
+
+from pathlib import Path
+from typing import Union
+
+import rich_click as click
+from loguru import logger as log
+
+from mpflash.connected import connected_ports_boards_variants
+from mpflash.custom import Firmware, add_firmware, custom_fw_from_path
+from mpflash.downloaded import clean_downloaded_firmwares
+from mpflash.errors import MPFlashError
+from mpflash.mpboard_id import find_known_board
+from mpflash.mpboard_id.alternate import add_renamed_boards
+from mpflash.versions import clean_version
+
+from .ask_input import ask_missing_params
+from .cli_group import cli
+from .config import config
+from .download import download
+
+
+@cli.command(
+    "add",
+    help="Add a custom MicroPython firmware.",
+)
+# @click.option(
+#     "--version",
+#     "-v",
+#     "versions",
+#     default=["stable"],
+#     multiple=False,
+#     show_default=True,
+#     help="The version of MicroPython to to download.",
+#     metavar="SEMVER, 'stable', 'preview' or '?'",
+# )
+@click.option(
+    "--path",
+    "-p",
+    "fw_path",
+    multiple=False,
+    default="",
+    show_default=False,
+    help="a local path to the firmware file to add.",
+    metavar="FIRMWARE_PATH",
+)
+@click.option(
+    "--description",
+    "-d",
+    "description",
+    default="",
+    help="An Optional description for the firmware.",
+    metavar="TXT",
+)
+# @click.option(
+#     "--board",
+#     "-b",
+#     "boards",
+#     multiple=True,
+#     default=[],
+#     show_default=True,
+#     help="The board(s) to download the firmware for.",
+#     metavar="BOARD_ID or ?",
+# )
+# @click.option(
+#     "--serial",
+#     "--serial-port",
+#     "-s",
+#     "serial",
+#     default=["*"],
+#     show_default=True,
+#     multiple=True,
+#     help="Which serial port(s) (or globs) to flash",
+#     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(
+#     "--clean/--no-clean",
+#     default=True,
+#     show_default=True,
+#     help="""Remove dates and hashes from the downloaded firmware filenames.""",
+# )
+@click.option(
+    "--force",
+    "-f",
+    default=False,
+    is_flag=True,
+    show_default=True,
+    help="""Overwrite existing firmware.""",
+)
+def cli_add_custom(
+    fw_path: Union[Path, str],
+    force: bool = False,
+    description: str = "",
+) -> int:
+    """Add a custom MicroPython firmware from a local file."""
+    if not fw_path:
+        log.error("No firmware path provided. Use --path to specify a firmware file.")
+        return 1
+    fw_path = Path(fw_path).expanduser().resolve()
+    if not fw_path.exists():
+        log.error(f"Firmware file does not exist: {fw_path}")
+        return 1
+
+    try:
+        fw_dict = custom_fw_from_path(fw_path)
+        if description:
+            fw_dict["description"] = description
+        if add_firmware(
+            source=fw_path,
+            fw_info=fw_dict,
+            custom=True,
+            force=force,
+        ):
+            log.success(f"Added custom firmware: {fw_dict['custom_id']} for {fw_dict['firmware_file']}")
+            return 0
+        else:
+            return 1
+    except MPFlashError as e:
+        log.error(f"{e}")
+        return 1

mpflash/cli_download.py

@@ -2,10 +2,11 @@
 
 from pathlib import Path
 
+from pytest import param
 import rich_click as click
 from loguru import logger as log
 
-from mpflash.connected import connected_ports_boards
+from mpflash.connected import connected_ports_boards_variants
 from mpflash.downloaded import clean_downloaded_firmwares
 from mpflash.errors import MPFlashError
 from mpflash.mpboard_id import find_known_board
@@ -23,15 +24,6 @@ from .download import download
     "download",
     help="Download MicroPython firmware for specific ports, boards and versions.",
 )
-@click.option(
-    "--destination",
-    "-d",
-    "fw_folder",
-    type=click.Path(file_okay=False, dir_okay=True, path_type=Path),
-    default=None,
-    show_default=False,
-    help="The folder to download the firmware to.",
-)
 @click.option(
     "--version",
     "-v",
@@ -94,9 +86,6 @@ def cli_download(**kwargs) -> int:
     params.boards = list(params.boards)
     params.serial = list(params.serial)
     params.ignore = list(params.ignore)
-    if params.fw_folder: 
-        config.firmware_folder = Path(params.fw_folder)
-    # all_boards: List[MPRemoteBoard] = []
     if params.boards:
         if not params.ports:
             # no ports specified - resolve ports from specified boards by resolving board IDs
@@ -109,7 +98,7 @@ def cli_download(**kwargs) -> int:
                         log.error(f"{e}")
     else:
         # no boards specified - detect connected ports and boards
-        params.ports, params.boards, _ = connected_ports_boards(include=params.serial, ignore=params.ignore)
+        params.ports, params.boards, _ , _ = connected_ports_boards_variants(include=params.serial, ignore=params.ignore)
 
     params = ask_missing_params(params)
     if not params:  # Cancelled by user

mpflash/cli_flash.py

@@ -1,4 +1,3 @@
-from pathlib import Path
 from typing import List
 
 import rich_click as click
@@ -7,11 +6,10 @@ from loguru import logger as log
 import mpflash.download.jid as jid
 import mpflash.mpboard_id as mpboard_id
 from mpflash.ask_input import ask_missing_params
-from mpflash.cli_download import connected_ports_boards
+from mpflash.cli_download import connected_ports_boards_variants
 from mpflash.cli_group import cli
 from mpflash.cli_list import show_mcus
-from mpflash.common import BootloaderMethod, FlashParams, Params
-from mpflash.config import config
+from mpflash.common import BootloaderMethod, FlashParams, filtered_comports
 from mpflash.errors import MPFlashError
 from mpflash.flash import flash_list
 from mpflash.flash.worklist import WorkList, full_auto_worklist, manual_worklist, single_auto_worklist
@@ -27,15 +25,6 @@ from mpflash.versions import clean_version
     "flash",
     short_help="Flash one or all connected MicroPython boards with a specific firmware and version.",
 )
-@click.option(
-    "--firmware",
-    "-f",
-    "fw_folder",
-    type=click.Path(file_okay=False, dir_okay=True, path_type=Path),
-    default=None,
-    show_default=False,
-    help="The folder to retrieve the firmware from.",
-)
 @click.option(
     "--version",
     "-v",
@@ -95,7 +84,7 @@ from mpflash.versions import clean_version
 )
 @click.option(
     "--variant",
-    "-var",
+    "--var",
     "variant",  # single board
     multiple=False,
     help="The board VARIANT to flash or '-'. If not specified will try to read the variant from the connected MCU.",
@@ -104,7 +93,6 @@ from mpflash.versions import clean_version
 @click.option(
     "--cpu",
     "--chip",
-    "-c",
     "cpu",
     help="The CPU type to flash. If not specified will try to read the CPU from the connected MCU.",
     metavar="CPU",
@@ -134,12 +122,20 @@ from mpflash.versions import clean_version
 )
 @click.option(
     "--flash_mode",
-    "-fm",
+    "--fm",
     type=click.Choice(["keep", "qio", "qout", "dio", "dout"]),
     default="keep",
     show_default=True,
     help="""Flash mode for ESP boards. (default: keep)""",
 )
+@click.option(
+    "--custom",
+    "-c",
+    default=False,
+    is_flag=True,
+    show_default=True,
+    help="""Flash a custom firmware""",
+)
 def cli_flash_board(**kwargs) -> int:
     # version to versions, board to boards
     kwargs["versions"] = [kwargs.pop("version")] if kwargs["version"] is not None else []
@@ -164,16 +160,18 @@ def cli_flash_board(**kwargs) -> int:
             # No bard specified
             params.boards = ["?"]
 
-    if params.fw_folder: 
-        config.firmware_folder = Path(params.fw_folder)
     # Detect connected boards if not specified,
     # and ask for input if boards cannot be detected
     all_boards: List[MPRemoteBoard] = []
     if not params.boards:
         # nothing specified - detect connected boards
-        params.ports, params.boards, all_boards = connected_ports_boards(
-            include=params.ports, ignore=params.ignore, bluetooth=params.bluetooth
+        params.ports, params.boards, variants, all_boards = connected_ports_boards_variants(
+            include=params.ports,
+            ignore=params.ignore,
+            bluetooth=params.bluetooth,
         )
+        if variants and len(variants) >= 1:
+            params.variant = variants[0]
         if params.boards == []:
             # No MicroPython boards detected, but it could be unflashed or in bootloader mode
             # Ask for serial port and board_id to flash
@@ -197,11 +195,27 @@ def cli_flash_board(**kwargs) -> int:
     params.versions = [clean_version(v) for v in params.versions]
     worklist: WorkList = []
 
+    if len(params.versions) == 1 and len(params.boards) == 1 and params.serial == ["*"]:
+        # A one or more serial port including the board / variant
+        comports = filtered_comports(
+            ignore=params.ignore,
+            include=params.serial,
+            bluetooth=params.bluetooth,
+        )
+        board_id = f"{params.boards[0]}-{params.variant}" if params.variant else params.boards[0]
+        log.info(f"Flashing {board_id} {params.versions[0]} to {len(comports)} serial ports")
+        log.info(f"Target ports: {', '.join(comports)}")
+        worklist = manual_worklist(
+            comports,
+            board_id=board_id,
+            version=params.versions[0],
+            custom=params.custom,
+        )
     # if serial port == auto and there are one or more specified/detected boards
-    if params.serial == ["*"] and params.boards:
+    elif params.serial == ["*"] and params.boards:
         if not all_boards:
             log.trace("No boards detected yet, scanning for connected boards")
-            _, _, all_boards = connected_ports_boards(include=params.ports, ignore=params.ignore)
+            _, _, _, all_boards = connected_ports_boards_variants(include=params.ports, ignore=params.ignore)
         # if variant id provided on the cmdline, treat is as an override
         if params.variant:
             for b in all_boards:
@@ -215,8 +229,13 @@ def cli_flash_board(**kwargs) -> int:
         )
     elif params.versions[0] and params.boards[0] and params.serial:
         # A one or more serial port including the board / variant
+        comports = filtered_comports(
+            ignore=params.ignore,
+            include=params.ports,
+            bluetooth=params.bluetooth,
+        )
         worklist = manual_worklist(
-            params.serial[0],
+            comports,
             board_id=params.boards[0],
             version=params.versions[0],
         )
@@ -226,7 +245,8 @@ def cli_flash_board(**kwargs) -> int:
             serial=params.serial[0],
             version=params.versions[0],
         )
-    jid.ensure_firmware_downloaded(worklist, version=params.versions[0], force=params.force)
+    if not params.custom:
+        jid.ensure_firmware_downloaded(worklist, version=params.versions[0], force=params.force)
     if flashed := flash_list(
         worklist,
         params.erase,
@@ -239,5 +259,3 @@ def cli_flash_board(**kwargs) -> int:
     else:
         log.error("No boards were flashed")
         return 1
-
-

mpflash/cli_group.py

@@ -14,6 +14,7 @@ from .logger import log, make_quiet, set_loglevel
 set_loglevel("INFO")
 config.verbose = False
 
+
 def cb_verbose(ctx, param, value):
     """Callback to set the log level to DEBUG if verbose is set"""
     if value and not config.quiet:

mpflash/cli_list.py

@@ -86,6 +86,8 @@ def cli_list_mcus(serial: List[str], ignore: List[str], bluetooth: bool, as_json
         if mcu.family == "circuitpython":
             # CircuitPython boards need a special reset command
             mcu.run_command(["exec", "--no-follow", "import microcontroller,time;time.sleep(0.01);microcontroller.reset()"], resume=False)
+        elif mcu.family == "unknown":
+            continue
         else:
             mcu.run_command("reset")
     return 0 if conn_mcus else 1

mpflash/cli_main.py

@@ -5,6 +5,9 @@ import os
 import click.exceptions as click_exceptions
 from loguru import logger as log
 
+from mpflash.errors import MPFlashError
+
+from .cli_add import cli_add_custom
 from .cli_download import cli_download
 from .cli_flash import cli_flash_board
 from .cli_group import cli
@@ -19,6 +22,7 @@ def mpflash():
     cli.add_command(cli_list_mcus)
     cli.add_command(cli_download)
     cli.add_command(cli_flash_board)
+    cli.add_command(cli_add_custom)
 
     # cli(auto_envvar_prefix="MPFLASH")
     if False and os.environ.get("COMPUTERNAME").upper().startswith("JOSVERL"):
@@ -37,6 +41,9 @@ def mpflash():
         except click_exceptions.Abort:
             # Aborted - Ctrl-C
             exit(-3)
+        except MPFlashError as e:
+            log.error(f"MPFlashError: {e}")
+            exit(-4)
 
 
 if __name__ == "__main__":

mpflash/common.py

@@ -4,7 +4,6 @@ import os
 import platform
 from dataclasses import dataclass, field
 from enum import Enum
-from pathlib import Path
 from typing import List, Optional, Union
 
 from serial.tools import list_ports
@@ -36,7 +35,6 @@ class Params:
     boards: List[str] = field(default_factory=list)
     variant: str = ""
     versions: List[str] = field(default_factory=list)
-    fw_folder: Optional[Path] = None
     serial: List[str] = field(default_factory=list)
     ignore: List[str] = field(default_factory=list)
     bluetooth: bool = False
@@ -66,6 +64,7 @@ class FlashParams(Params):
     bootloader: BootloaderMethod = BootloaderMethod.NONE
     cpu: str = ""
     flash_mode: str = "keep"  # keep, qio, qout, dio, dout
+    custom: bool = False
 
     def __post_init__(self):
         if isinstance(self.bootloader, str):
@@ -79,11 +78,24 @@ def filtered_comports(
     ignore: Optional[List[str]] = None,
     include: Optional[List[str]] = None,
     bluetooth: bool = False,
+) -> List[str]:
+    """
+    Get a list of filtered comports using the include and ignore lists.
+    both can be globs (e.g. COM*) or exact port names (e.g. COM1)
+    """
+    return [p.device for p in filtered_portinfos(ignore, include, bluetooth)]
+
+
+def filtered_portinfos(
+    ignore: Optional[List[str]] = None,
+    include: Optional[List[str]] = None,
+    bluetooth: bool = False,
 ) -> List[ListPortInfo]:  # sourcery skip: assign-if-exp
     """
     Get a list of filtered comports using the include and ignore lists.
     both can be globs (e.g. COM*) or exact port names (e.g. COM1)
     """
+    log.trace(f"filtered_portinfos: {ignore=}, {include=}, {bluetooth=}")
     if not ignore:
         ignore = []
     elif not isinstance(ignore, list):  # type: ignore

mpflash/config.py

@@ -7,6 +7,8 @@ from typing import List, Optional
 
 import platformdirs
 
+from mpflash.errors import MPFlashError
+
 
 def get_version():
     name = __package__ or "mpflash"
@@ -44,7 +46,18 @@ class MPFlashConfig:
     def firmware_folder(self) -> Path:
         """The folder where firmware files are stored"""
         if not self._firmware_folder:
-            self._firmware_folder = platformdirs.user_downloads_path() / "firmware"
+            from mpflash.logger import log
+
+            # Check if MPFLASH_FIRMWARE environment variable is set
+            env_firmware_path = os.getenv("MPFLASH_FIRMWARE")
+            if env_firmware_path:
+                firmware_path = Path(env_firmware_path).expanduser().resolve()
+                if firmware_path.exists() and firmware_path.is_dir():
+                    self._firmware_folder = firmware_path
+                else:
+                    log.warning(
+                        f"Environment variable MPFLASH_FIRMWARE points to invalid directory: {env_firmware_path}. Using default location."
+                    )
             # allow testing in CI
             if Path(os.getenv("GITHUB_ACTIONS", "")).as_posix().lower() == "true":
                 workspace = os.getenv("GITHUB_WORKSPACE")
@@ -53,6 +66,13 @@ class MPFlashConfig:
                     ws_path.mkdir(parents=True, exist_ok=True)
                     print(f"Detected GitHub Actions environment. Using workspace path: {ws_path}")
                     self._firmware_folder = ws_path
+            if not self._firmware_folder:
+                self._firmware_folder = platformdirs.user_downloads_path() / "firmware"
+            if not self._firmware_folder.exists():
+                log.info(f"Creating firmware folder at {self._firmware_folder}")
+                self._firmware_folder.mkdir(parents=True, exist_ok=True)
+            if not self._firmware_folder.is_dir():
+                raise MPFlashError(f"Firmware folder {self._firmware_folder} is not a directory.")
         return self._firmware_folder
 
     @firmware_folder.setter
@@ -67,6 +87,7 @@ class MPFlashConfig:
     def db_path(self) -> Path:
         """The path to the database file"""
         return self.firmware_folder / "mpflash.db"
+
     @property
     def db_version(self) -> str:
         return "1.24.1"

mpflash/connected.py

@@ -4,13 +4,13 @@ from rich import print
 from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
 from rich.table import Column
 
-from mpflash.common import filtered_comports, find_serial_by_path
+from mpflash.common import filtered_portinfos, find_serial_by_path
 from mpflash.mpremoteboard import MPRemoteBoard
 
 
-def connected_ports_boards(
+def connected_ports_boards_variants(
     *, include: List[str], ignore: List[str], bluetooth: bool = False
-) -> Tuple[List[str], List[str], List[MPRemoteBoard]]:
+) -> Tuple[List[str], List[str], List[str], List[MPRemoteBoard]]:
     """
     Returns a tuple containing lists of unique ports and boards from the connected MCUs.
     Boards that are physically connected, but give no tangible response are ignored.
@@ -21,13 +21,15 @@ def connected_ports_boards(
             - A list of unique board names of the connected MCUs.
             - A list of MPRemoteBoard instances of the connected MCUs.
     """
+    # conn_mcus = [b for b in list_mcus(include=include, ignore=ignore, bluetooth=bluetooth)]
     conn_mcus = [b for b in list_mcus(include=include, ignore=ignore, bluetooth=bluetooth) if b.connected]
     # ignore boards that have the [mpflash] ignore flag set
     conn_mcus = [item for item in conn_mcus if not (item.toml.get("mpflash", {}).get("ignore", False))]
 
     ports = list({b.port for b in conn_mcus})
     boards = list({b.board for b in conn_mcus})
-    return (ports, boards, conn_mcus)
+    variants = list({b.variant for b in conn_mcus if b.variant})
+    return (ports, boards, variants, conn_mcus)
 
 
 # #########################################################################################################
@@ -46,8 +48,8 @@ def list_mcus(*, ignore: List[str], include: List[str], bluetooth: bool = False)
         ConnectionError: If there is an error connecting to a board.
     """
     # conn_mcus = [MPRemoteBoard(sp) for sp in MPRemoteBoard.connected_boards(bluetooth) if sp not in config.ignore_ports]
-
-    comports = filtered_comports(
+    vid_pid = True
+    comports = filtered_portinfos(
         ignore=ignore,
         include=include,
         bluetooth=bluetooth,