mpflash 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

mpflash/list.py

@@ -0,0 +1,88 @@
+from typing import List
+
+from rich import print
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn, track
+from rich.table import Column, Table
+
+from mpflash.mpremoteboard import MPRemoteBoard
+
+from .config import config
+from .logger import console
+
+rp_spinner = SpinnerColumn(finished_text="✅")
+rp_text = TextColumn("{task.description} {task.fields[device]}", table_column=Column())
+rp_bar = BarColumn(bar_width=None, table_column=Column())
+
+
+def list_mcus(bluetooth: bool = False):
+    """
+    Retrieves information about connected microcontroller boards.
+
+    Returns:
+        List[MPRemoteBoard]: A list of MPRemoteBoard instances with board information.
+    Raises:
+        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]
+
+    # a lot of boilerplate to show a progress bar with the comport currenlty scanned
+    with Progress(rp_spinner, rp_text, rp_bar, TimeElapsedColumn()) as progress:
+        tsk_scan = progress.add_task("[green]Scanning", visible=False, total=None)
+        progress.tasks[tsk_scan].fields["device"] = "..."
+        progress.tasks[tsk_scan].visible = True
+        progress.start_task(tsk_scan)
+        try:
+            for mcu in conn_mcus:
+                progress.update(tsk_scan, device=mcu.serialport.replace("/dev/", ""))
+                try:
+                    mcu.get_mcu_info()
+                except ConnectionError as e:
+                    print(f"Error: {e}")
+                    continue
+        finally:
+            # transient
+            progress.stop_task(tsk_scan)
+            progress.tasks[tsk_scan].visible = False
+    return conn_mcus
+
+
+def show_mcus(
+    conn_mcus: List[MPRemoteBoard],
+    title: str = "Connected boards",
+    refresh: bool = True,
+):  # sourcery skip: extract-duplicate-method
+    """Show the list of connected boards in a nice table"""
+    table = Table(
+        title=title,
+        title_style="magenta",
+        header_style="bold magenta",
+        collapse_padding=True,
+        width=110,
+    )
+    table.add_column("Serial", overflow="fold")
+    table.add_column("Family")
+    table.add_column("Port")
+    table.add_column("Board", overflow="fold")
+    # table.add_column("Variant") # TODO: add variant
+    table.add_column("CPU")
+    table.add_column("Version")
+    table.add_column("build", justify="right")
+
+    for mcu in track(conn_mcus, description="Updating board info", transient=True, update_period=0.1):
+        if refresh:
+            try:
+                mcu.get_mcu_info()
+            except ConnectionError:
+                continue
+        description = f"[italic bright_cyan]{mcu.description}" if mcu.description else ""
+        table.add_row(
+            mcu.serialport.replace("/dev/", ""),
+            mcu.family,
+            mcu.port,
+            f"{mcu.board}\n{description}".strip(),
+            # mcu.variant,
+            mcu.cpu,
+            mcu.version,
+            mcu.build,
+        )
+    console.print(table)

mpflash/mpboard_id/{api.py → __init__.py}

@@ -1,9 +1,17 @@
+"""
+Access to the micropython port and board information that is stored in the board_info.json file 
+that is included in the module.
+
+"""
+
 import json
 from functools import lru_cache
 from pathlib import Path
 from typing import List, Optional, Tuple, TypedDict, Union
 
-from mpflash.common import PORT_FWTYPES, clean_version
+from mpflash.errors import MPFlashError
+from mpflash.common import PORT_FWTYPES
+from mpflash.vendor.versions import clean_version
 
 
 # Board  based on the dataclass Board but changed to TypedDict
@@ -22,27 +30,27 @@ class Board(TypedDict):
 
 
 @lru_cache(maxsize=None)
-def read_boardinfo() -> List[Board]:
+def read_stored_boardinfo() -> List[Board]:
     """Reads the board_info.json file and returns the data as a list of Board objects"""
     with open(Path(__file__).parent / "board_info.json", "r") as file:
         return json.load(file)
 
 
-def known_mp_ports() -> List[str]:
+def local_mp_ports() -> List[str]:
     # TODO: Filter for Version
-    mp_boards = read_boardinfo()
+    mp_boards = read_stored_boardinfo()
     # select the unique ports from info
     ports = set({board["port"] for board in mp_boards if board["port"] in PORT_FWTYPES.keys()})
     return sorted(list(ports))
 
 
-def get_mp_boards_for_port(port: str, versions: Optional[List[str]] = None):
+def get_stored_boards_for_port(port: str, versions: Optional[List[str]] = None):
     """
     Returns a list of boards for the given port and version(s)
 
     port : str : The Micropython port to filter for
     versions : List[str] : The Micropython versions to filter for (actual versions required)"""
-    mp_boards = read_boardinfo()
+    mp_boards = read_stored_boardinfo()
 
     # filter for 'preview' as they are not in the board_info.json
     # instead use stable version
@@ -60,30 +68,29 @@ def get_mp_boards_for_port(port: str, versions: Optional[List[str]] = None):
     return mp_boards
 
 
-def known_mp_boards(port: str, versions: Optional[List[str]] = None) -> List[Tuple[str, str]]:
+def known_stored_boards(port: str, versions: Optional[List[str]] = None) -> List[Tuple[str, str]]:
     """
     Returns a list of tuples with the description and board name for the given port and version
 
     port : str : The Micropython port to filter for
     versions : List[str] : The Micropython versions to filter for (actual versions required)
     """
-    mp_boards = get_mp_boards_for_port(port, versions)
+    mp_boards = get_stored_boards_for_port(port, versions)
 
-    boards = set(
-        {(f'{board["description"]} [board["board"]] {board["version"]}', board["board"]) for board in mp_boards}
-    )
+    boards = set({(f'{board["version"]} {board["description"]}', board["board"]) for board in mp_boards})
     return sorted(list(boards))
 
 
-def find_mp_board(board: str) -> Board:
-    """Find the board for the given board"""
-    info = read_boardinfo()
+@lru_cache(maxsize=20)
+def find_stored_board(board_id: str) -> Board:
+    """Find the board for the given board_ID or 'board description' and return the board info as a Board object"""
+    info = read_stored_boardinfo()
     for board_info in info:
-        if board_info["board"] == board:
+        if board_id in (board_info["board"], board_info["description"]):
             if "cpu" not in board_info or not board_info["cpu"]:
                 if " with " in board_info["description"]:
                     board_info["cpu"] = board_info["description"].split(" with ")[-1]
                 else:
                     board_info["cpu"] = board_info["port"]
             return board_info
-    raise LookupError(f"Board {board} not found")
+    raise MPFlashError(f"Board {board_id} not found")

mpflash/mpboard_id/board_id.py

@@ -2,44 +2,62 @@
 Translate board description to board designator
 """
 
+import functools
+import json
 from pathlib import Path
 from typing import Optional
 
+from mpflash.errors import MPFlashError
+from mpflash.vendor.versions import clean_version
+
 ###############################################################################################
-# TODO : make this a bit nicer
 HERE = Path(__file__).parent
 ###############################################################################################
 
 
-def find_board_designator(descr: str, short_descr: str, board_info: Optional[Path] = None) -> Optional[str]:
+def find_board_id(
+    descr: str, short_descr: str, board_info: Optional[Path] = None, version: str = "stable"
+) -> Optional[str]:
     # TODO: use the json file instead of the csv and get the cpu
-    return find_board_designator_csv(descr, short_descr, board_info)
+    boards = find_board_by_description(
+        descr=descr,
+        short_descr=short_descr,
+        board_info=board_info,
+        version=clean_version(version),
+    )
+    return boards[-1]["board"]
 
 
-def find_board_designator_csv(descr: str, short_descr: str, board_info: Optional[Path] = None) -> Optional[str]:
+@functools.lru_cache(maxsize=20)
+def find_board_by_description(*, descr: str, short_descr: str, version="v1.21.0", board_info: Optional[Path] = None):
     """
     Find the MicroPython BOARD designator based on the description in the firmware
-    using the pre-built board_info.csv file
+    using the pre-built board_info.json file
     """
     if not board_info:
-        board_info = HERE / "board_info.csv"
+        board_info = HERE / "board_info.json"
     if not board_info.exists():
         raise FileNotFoundError(f"Board info file not found: {board_info}")
 
-    short_hit = ""
+    info = _read_board_info(board_info)
+
+    # filter for matching version
+    if version == "preview":
+        # TODO: match last stable
+        version = "v1.22.2"
+    version_matches = [b for b in info if b["version"].startswith(version)]
+    if not version_matches:
+        raise MPFlashError(f"No board info found for version {version}")
+    matches = [b for b in version_matches if b["description"] == descr]
+    if not matches and short_descr:
+        matches = [b for b in version_matches if b["description"] == short_descr]
+    if not matches:
+        raise MPFlashError(f"No board info found for description {descr}")
+    return sorted(matches, key=lambda x: x["version"])
+
+
+@functools.lru_cache(maxsize=20)
+def _read_board_info(board_info):
     with open(board_info, "r") as file:
-        while 1:
-            line = file.readline()
-            if not line:
-                break
-            descr_, board_ = line.split(",")[0].strip(), line.split(",")[1].strip()
-            if descr_ == descr:
-                return board_
-            if short_descr and descr_ == short_descr:
-                if "with" in short_descr:
-                    # Good enough - no need to trawl the entire file
-                    # info["board"] = board_
-                    return board_
-                # good enough if not found in the rest of the file (but slow)
-                short_hit = board_
-    return short_hit or None
+        info = json.load(file)
+    return info

mpflash/mpremoteboard/__init__.py

@@ -3,16 +3,18 @@ Module to run mpremote commands, and retry on failure or timeout
 """
 
 import sys
+import time
 from pathlib import Path
 from typing import List, Optional, Union
 
 import serial.tools.list_ports
 from loguru import logger as log
+from rich.progress import track
 from tenacity import retry, stop_after_attempt, wait_fixed
 
-from mpflash.mpboard_id.board_id import find_board_designator
-
-from .runner import run
+from mpflash.errors import MPFlashError
+from mpflash.mpboard_id.board_id import find_board_id
+from mpflash.mpremoteboard.runner import run
 
 ###############################################################################################
 # TODO : make this a bit nicer
@@ -27,9 +29,15 @@ RETRIES = 3
 class MPRemoteBoard:
     """Class to run mpremote commands"""
 
-    def __init__(self, serialport: str = ""):
+    def __init__(self, serialport: str = "", update: bool = False):
+        """
+        Initialize MPRemoteBoard object.
+
+        Parameters:
+        - serialport (str): The serial port to connect to. Default is an empty string.
+        - update (bool): Whether to update the MCU information. Default is False.
+        """
         self.serialport = serialport
-        # self.board = ""
         self.firmware = {}
 
         self.connected = False
@@ -43,18 +51,50 @@ class MPRemoteBoard:
         self.arch = ""
         self.mpy = ""
         self.build = ""
+        if update:
+            self.get_mcu_info()
 
     def __str__(self):
+        """
+        Return a string representation of the MPRemoteBoard object.
+
+        Returns:
+        - str: The string representation of the object.
+        """
         return f"MPRemoteBoard({self.serialport}, {self.family} {self.port}, {self.board}, {self.version})"
 
     @staticmethod
-    def connected_boards():
-        """Get a list of connected boards"""
-        devices = [p.device for p in serial.tools.list_ports.comports()]
-        return sorted(devices)
+    def connected_boards(bluetooth: bool = False) -> List[str]:
+        # TODO: rename to connected_comports
+        """
+        Get a list of connected comports.
+
+        Parameters:
+        - bluetooth (bool): Whether to include Bluetooth ports. Default is False.
+
+        Returns:
+        - List[str]: A list of connected board ports.
+        """
+        comports = serial.tools.list_ports.comports()
+
+        if not bluetooth:
+            # filter out bluetooth ports
+            comports = [p for p in comports if "bluetooth" not in p.description.lower()]
+            comports = [p for p in comports if "BTHENUM" not in p.hwid]
+
+        return sorted([p.device for p in comports])
+
+    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(1), reraise=True)  # type: ignore ## retry_error_cls=ConnectionError,
+    def get_mcu_info(self, timeout: int = 2):
+        """
+        Get MCU information from the connected board.
+
+        Parameters:
+        - timeout (int): The timeout value in seconds. Default is 2.
 
-    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(1), retry_error_cls=ConnectionError)  # type: ignore
-    def get_mcu_info(self, timeout: int = 6):
+        Raises:
+        - ConnectionError: If failed to get mcu_info for the serial port.
+        """
         rc, result = self.run_command(
             ["run", str(HERE / "mpy_fw_info.py")],
             no_info=True,
@@ -76,13 +116,18 @@ class MPRemoteBoard:
             self.description = descr = info["board"]
             pos = descr.rfind(" with")
             short_descr = descr[:pos].strip() if pos != -1 else ""
-            if board_name := find_board_designator(descr, short_descr):
+            if board_name := find_board_id(descr, short_descr):
                 self.board = board_name
             else:
                 self.board = "UNKNOWN"
 
     def disconnect(self) -> bool:
-        """Disconnect from a board"""
+        """
+        Disconnect from a board.
+
+        Returns:
+        - bool: True if successfully disconnected, False otherwise.
+        """
         if not self.connected:
             return True
         if not self.serialport:
@@ -94,7 +139,7 @@ class MPRemoteBoard:
         self.connected = False
         return result
 
-    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(2))
+    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(2), reraise=True)
     def run_command(
         self,
         cmd: Union[str, List[str]],
@@ -104,21 +149,23 @@ class MPRemoteBoard:
         timeout: int = 60,
         **kwargs,
     ):
-        """Run mpremote with the given command
-        Parameters
-        ----------
-        cmd : Union[str,List[str]]
-            The command to run, either a string or a list of strings
-        check : bool, optional
-            If True, raise an exception if the command fails, by default False
-        Returns
-        -------
-        bool
-            True if the command succeeded, False otherwise
+        """
+        Run mpremote with the given command.
+
+        Parameters:
+        - cmd (Union[str, List[str]]): The command to run, either a string or a list of strings.
+        - log_errors (bool): Whether to log errors. Default is True.
+        - no_info (bool): Whether to skip printing info. Default is False.
+        - timeout (int): The timeout value in seconds. Default is 60.
+
+        Returns:
+        - bool: True if the command succeeded, False otherwise.
         """
         if isinstance(cmd, str):
             cmd = cmd.split(" ")
-        prefix = [sys.executable, "-m", "mpremote", "connect", self.serialport] if self.serialport else ["mpremote"]
+        prefix = [sys.executable, "-m", "mpremote"]
+        if self.serialport:
+            prefix += ["connect", self.serialport]
         # if connected add resume to keep state between commands
         if self.connected:
             prefix += ["resume"]
@@ -130,9 +177,33 @@ class MPRemoteBoard:
 
     @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(1))
     def mip_install(self, name: str) -> bool:
-        """Install a micropython package"""
+        """
+        Install a micropython package.
+
+        Parameters:
+        - name (str): The name of the package to install.
+
+        Returns:
+        - bool: True if the installation succeeded, False otherwise.
+        """
         # install createstubs to the board
         cmd = ["mip", "install", name]
         result = self.run_command(cmd)[0] == OK
         self.connected = True
         return result
+
+    def wait_for_restart(self, timeout: int = 10):
+        """wait for the board to restart"""
+        for _ in track(
+            range(timeout),
+            description="Waiting for the board to restart",
+            transient=True,
+            get_time=lambda: time.time(),
+            show_speed=False,
+        ):
+            time.sleep(1)
+            try:
+                self.get_mcu_info()
+                break
+            except (ConnectionError, MPFlashError):
+                pass

mpflash/mpremoteboard/runner.py

@@ -27,6 +27,7 @@ def run(
     log_errors: bool = True,
     no_info: bool = False,
     *,
+    log_warnings: bool = False,
     reset_tags: Optional[LogTagList] = None,
     error_tags: Optional[LogTagList] = None,
     warning_tags: Optional[LogTagList] = None,
@@ -93,7 +94,8 @@ def run(
 
     def timed_out():
         proc.kill()
-        log.warning(f"Command {cmd} timed out after {timeout} seconds")
+        if log_warnings:
+            log.warning(f"Command {cmd} timed out after {timeout} seconds")
 
     timer = Timer(timeout, timed_out)
     try:
@@ -123,6 +125,8 @@ def run(
                     continue
                 else:
                     if not no_info:
+                        if line.startswith(("INFO  : ", "WARN  : ", "ERROR : ")):
+                            line = line[8:].lstrip()
                         log.info(line)
         if proc.stderr and log_errors:
             for line in proc.stderr:

mpflash/vendor/versions.py

@@ -0,0 +1,113 @@
+"""
+#############################################################
+# Version handling copied from stubber/utils/versions.py
+#############################################################
+"""
+
+from functools import lru_cache
+
+from loguru import logger as log
+from packaging.version import parse
+
+V_PREVIEW = "preview"
+"Latest preview version"
+
+SET_PREVIEW = {"preview", "latest", "master"}
+
+
+def clean_version(
+    version: str,
+    *,
+    build: bool = False,
+    patch: bool = False,
+    commit: bool = False,
+    drop_v: bool = False,
+    flat: bool = False,
+):
+    "Clean up and transform the many flavours of versions"
+    # 'v1.13.0-103-gb137d064e' --> 'v1.13-103'
+    if version in {"", "-"}:
+        return version
+    if version.lower() == "stable":
+        _v = get_stable_mp_version()
+        if not _v:
+            log.warning("Could not determine the latest stable version")
+            return "stable"
+        version = _v
+        log.trace(f"Using latest stable version: {version}")
+    is_preview = "-preview" in version
+    nibbles = version.split("-")
+    ver_ = nibbles[0].lower().lstrip("v")
+    if not patch and ver_ >= "1.10.0" and ver_ < "1.20.0" and ver_.endswith(".0"):
+        # remove the last ".0" - but only for versions between 1.10 and 1.20 (because)
+        nibbles[0] = nibbles[0][:-2]
+    if len(nibbles) == 1:
+        version = nibbles[0]
+    elif build and not is_preview:
+        version = "-".join(nibbles) if commit else "-".join(nibbles[:-1])
+    else:
+        # version = "-".join((nibbles[0], LATEST))
+        # HACK: this is not always right, but good enough most of the time
+        if is_preview:
+            version = "-".join((nibbles[0], V_PREVIEW))
+        else:
+            version = V_PREVIEW
+    if flat:
+        version = version.strip().replace(".", "_").replace("-", "_")
+    else:
+        version = version.strip().replace("_preview", "-preview").replace("_", ".")
+
+    if drop_v:
+        version = version.lstrip("v")
+    elif not version.startswith("v") and version.lower() not in SET_PREVIEW:
+        version = "v" + version
+    if version in SET_PREVIEW:
+        version = V_PREVIEW
+    return version
+
+
+@lru_cache(maxsize=10)
+def micropython_versions(minver: str = "v1.20"):
+    """Get the list of micropython versions from github tags"""
+    try:
+        gh_client = GH_CLIENT
+        repo = gh_client.get_repo("micropython/micropython")
+        versions = [tag.name for tag in repo.get_tags() if parse(tag.name) >= parse(minver)]
+    except Exception:
+        versions = [
+            "v9.99.9-preview",
+            "v1.22.2",
+            "v1.22.1",
+            "v1.22.0",
+            "v1.21.1",
+            "v1.21.0",
+            "v1.20.0",
+            "v1.19.1",
+            "v1.19",
+            "v1.18",
+            "v1.17",
+            "v1.16",
+            "v1.15",
+            "v1.14",
+            "v1.13",
+            "v1.12",
+            "v1.11",
+            "v1.10",
+        ]
+        versions = [v for v in versions if parse(v) >= parse(minver)]
+    return sorted(versions)
+
+
+def get_stable_mp_version() -> str:
+    # read the versions from the git tags
+    all_versions = micropython_versions(minver="v1.17")
+    return [v for v in all_versions if not v.endswith(V_PREVIEW)][-1]
+
+
+def get_preview_mp_version() -> str:
+    # read the versions from the git tags
+    all_versions = micropython_versions(minver="v1.17")
+    return [v for v in all_versions if v.endswith(V_PREVIEW)][-1]
+
+
+#############################################################