mpflash 0.5.0__tar.gz → 0.6.0__tar.gz

{mpflash-0.5.0 → mpflash-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mpflash
-Version: 0.5.0
+Version: 0.6.0
 Summary: Flash and download tool for MicroPython firmwares
 Home-page: https://github.com/Josverl/micropython-stubber/blob/main/src/mpflash/README.md
 License: MIT
@@ -48,7 +48,7 @@ mpflash has been tested on Windows x64, Linux X64 and ARM64, but not (yet) macOS
  1. List the connected boards including their firmware details, in a tabular or json format
  2. Download MicroPython firmware for specific boards and versions.
  3. Flash one or all connected MicroPython boards with a specific firmware or version.
-    Tested ports: rp2, samd, esp32, esp32s3, esp8266 and stm32 (requires cubeprogrammer)
+    Tested ports: rp2, samd, esp32, esp32s3, esp8266 and stm32
  
 ## Installation
 To install mpflash, you can use pip: `pip install mpflash`
@@ -63,10 +63,10 @@ You can use mpflash to perform various operations on your MicroPython boards. He
 | `mpflash flash` | Flash the latest stable firmware to the connected board(s) |
 
 
-## Linux permissions for usb devices 
+## Linux permissions to access usb devices 
 In order to flash the firmware to the board, you need to have the correct permissions to access the USB devices.
 On Windows this will not be an issue, but on Linux you can use  udev rules to give non-root users access to the USB devices.
-[See thestm32_permissions documentation](./stm32_udev_rules.md) for more information.
+[See the stm32_permissions documentation](./stm32_udev_rules.md) for more information.
 
 
 ## Advanced use

{mpflash-0.5.0 → mpflash-0.6.0}/README.md

@@ -9,7 +9,7 @@ mpflash has been tested on Windows x64, Linux X64 and ARM64, but not (yet) macOS
  1. List the connected boards including their firmware details, in a tabular or json format
  2. Download MicroPython firmware for specific boards and versions.
  3. Flash one or all connected MicroPython boards with a specific firmware or version.
-    Tested ports: rp2, samd, esp32, esp32s3, esp8266 and stm32 (requires cubeprogrammer)
+    Tested ports: rp2, samd, esp32, esp32s3, esp8266 and stm32
  
 ## Installation
 To install mpflash, you can use pip: `pip install mpflash`
@@ -24,10 +24,10 @@ You can use mpflash to perform various operations on your MicroPython boards. He
 | `mpflash flash` | Flash the latest stable firmware to the connected board(s) |
 
 
-## Linux permissions for usb devices 
+## Linux permissions to access usb devices 
 In order to flash the firmware to the board, you need to have the correct permissions to access the USB devices.
 On Windows this will not be an issue, but on Linux you can use  udev rules to give non-root users access to the USB devices.
-[See thestm32_permissions documentation](./stm32_udev_rules.md) for more information.
+[See the stm32_permissions documentation](./stm32_udev_rules.md) for more information.
 
 
 ## Advanced use

mpflash-0.6.0/mpflash/ask_input.py

@@ -0,0 +1,234 @@
+"""
+Interactive input for mpflash.
+
+Note: The prompts can use "{version}" and "{action}" to insert the version and action in the prompt without needing an f-string.
+The values are provided from the answers dictionary.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Sequence, Tuple, Union
+
+from loguru import logger as log
+
+from mpflash.config import config
+from mpflash.mpboard_id import known_stored_boards, local_mp_ports
+from mpflash.mpremoteboard import MPRemoteBoard
+from mpflash.vendor.versions import micropython_versions
+
+
+@dataclass
+class Params:
+    ports: List[str] = field(default_factory=list)
+    boards: List[str] = field(default_factory=list)
+    versions: List[str] = field(default_factory=list)
+    fw_folder: Path = Path()
+
+
+@dataclass
+class DownloadParams(Params):
+    clean: bool = False
+    force: bool = False
+
+
+@dataclass
+class FlashParams(Params):
+    # TODO: Should Serial port be a list?
+    serial: str = ""
+    erase: bool = True
+    bootloader: bool = True
+    cpu: str = ""
+
+
+ParamType = Union[DownloadParams, FlashParams]
+
+
+def ask_missing_params(
+    params: ParamType,
+    action: str = "download",
+) -> ParamType:
+    """
+    Asks the user for parameters that have not been supplied on the commandline and returns the updated params.
+
+    Args:
+        params (ParamType): The parameters to be updated.
+        action (str, optional): The action to be performed. Defaults to "download".
+
+    Returns:
+        ParamType: The updated parameters.
+    """
+    if not config.interactive:
+        # no interactivity allowed
+        return params
+    # import only when needed to reduce load time
+    import inquirer
+
+    questions = []
+    answers = {"action": action}
+    if isinstance(params, FlashParams):
+        if not params.serial or "?" in params.serial:
+            ask_serialport(questions, action=action)
+        else:
+            answers["serial"] = params.serial
+
+    if not params.versions or "?" in params.versions:
+        ask_versions(questions, action=action)
+    else:
+        # versions is used to show only the boards for the selected versions
+        answers["versions"] = params.versions  # type: ignore
+
+    if not params.boards or "?" in params.boards:
+        ask_port_board(questions, action=action)
+
+    answers = inquirer.prompt(questions, answers=answers)
+    if not answers:
+        # input cancelled by user
+        return []  # type: ignore
+    # print(repr(answers))
+    if isinstance(params, FlashParams) and "serial" in answers:
+        params.serial = answers["serial"]
+    if "port" in answers:
+        params.ports = [answers["port"]]
+    if "boards" in answers:
+        params.boards = answers["boards"] if isinstance(answers["boards"], list) else [answers["boards"]]
+    if "versions" in answers:
+        # make sure it is a list
+        params.versions = answers["versions"] if isinstance(answers["versions"], list) else [answers["versions"]]
+
+    log.debug(repr(params))
+
+    return params
+
+
+def filter_matching_boards(answers: dict) -> Sequence[Tuple[str, str]]:
+    """
+    Filters the known boards based on the selected versions and returns the filtered boards.
+
+    Args:
+        answers (dict): The user's answers.
+
+    Returns:
+        Sequence[Tuple[str, str]]: The filtered boards.
+    """
+    # if version is not asked ; then need to get the version from the inputs
+    if "versions" in answers:
+        _versions = list(answers["versions"])
+        if "stable" in _versions:
+            _versions.remove("stable")
+            _versions.append(micropython_versions()[-2])  # latest stable
+        if "preview" in _versions:
+            _versions.remove("preview")
+            _versions.extend((micropython_versions()[-1], micropython_versions()[-2]))  # latest preview and stable
+
+        some_boards = known_stored_boards(answers["port"], _versions)  #    or known_mp_boards(answers["port"])
+    else:
+        some_boards = known_stored_boards(answers["port"])
+
+    if some_boards:
+        # Create a dictionary where the keys are the second elements of the tuples
+        # This will automatically remove duplicates because dictionaries cannot have duplicate keys
+        unique_dict = {item[1]: item for item in some_boards}
+        # Get the values of the dictionary, which are the unique items from the original list
+        some_boards = list(unique_dict.values())
+    else:
+        some_boards = [("No boards found", "")]
+    return some_boards
+
+
+def ask_port_board(questions: list, *, action: str):
+    """
+    Asks the user for the port and board selection.
+
+    Args:
+        questions (list): The list of questions to be asked.
+        action (str): The action to be performed.
+
+    Returns:
+        None
+    """
+    # import only when needed to reduce load time
+    import inquirer
+
+    # TODO: if action = flash, Use Inquirer.List for boards
+    inquirer_ux = inquirer.Checkbox if action == "download" else inquirer.List
+    questions.extend(
+        (
+            inquirer.List(
+                "port",
+                message="Which port do you want to {action} " + "to {serial} ?" if action == "flash" else "?",
+                choices=local_mp_ports(),
+                autocomplete=True,
+            ),
+            inquirer_ux(
+                "boards",
+                message=(
+                    "Which {port} board firmware do you want to {action} " + "to {serial} ?"
+                    if action == "flash"
+                    else "?"
+                ),
+                choices=filter_matching_boards,
+                validate=lambda _, x: True if x else "Please select at least one board",  # type: ignore
+            ),
+        )
+    )
+
+
+def ask_versions(questions: list, *, action: str):
+    """
+    Asks the user for the version selection.
+
+    Args:
+        questions (list): The list of questions to be asked.
+        action (str): The action to be performed.
+
+    Returns:
+        None
+    """
+    # import only when needed to reduce load time
+    import inquirer
+
+    input_ux = inquirer.Checkbox if action == "download" else inquirer.List
+    mp_versions: List[str] = micropython_versions()
+    mp_versions = [v for v in mp_versions if "preview" not in v]
+    mp_versions.append("preview")
+    mp_versions.reverse()  # newest first
+    questions.append(
+        input_ux(
+            # inquirer.List(
+            "versions",
+            message="Which version(s) do you want to {action} " + ("to {serial} ?" if action == "flash" else "?"),
+            # Hints would be nice , but needs a hint for each and every option
+            # hints=["Use space to select multiple options"],
+            choices=mp_versions,
+            autocomplete=True,
+            validate=lambda _, x: True if x else "Please select at least one version",  # type: ignore
+        )
+    )
+
+
+def ask_serialport(questions: list, *, action: str):
+    """
+    Asks the user for the serial port selection.
+
+    Args:
+        questions (list): The list of questions to be asked.
+        action (str): The action to be performed.
+
+    Returns:
+        None
+    """
+    # import only when needed to reduce load time
+    import inquirer
+
+    serialports = MPRemoteBoard.connected_boards()
+    questions.append(
+        inquirer.List(
+            "serial",
+            message="Which serial port do you want to {action} ?",
+            choices=serialports,
+            other=True,
+            validate=lambda _, x: True if x else "Please select or enter a serial port",  # type: ignore
+        )
+    )
+
+    return questions

{mpflash-0.5.0 → mpflash-0.6.0}/mpflash/cli_download.py

@@ -4,8 +4,10 @@ from pathlib import Path
 from typing import List, Tuple
 
 import rich_click as click
+from loguru import logger as log
 
-from mpflash.common import clean_version
+from mpflash.mpboard_id import find_stored_board
+from mpflash.vendor.versions import clean_version
 
 from .ask_input import DownloadParams, ask_missing_params
 from .cli_group import cli
@@ -14,13 +16,6 @@ from .config import config
 from .download import download
 
 
-def connected_ports_boards() -> Tuple[List[str], List[str]]:
-    mpr_boards = list_mcus()
-    ports = list({b.port for b in mpr_boards})
-    boards = list({b.board for b in mpr_boards})
-    return ports, boards
-
-
 @cli.command(
     "download",
     help="Download MicroPython firmware for specific ports, boards and versions.",
@@ -49,7 +44,7 @@ def connected_ports_boards() -> Tuple[List[str], List[str]]:
     "-b",
     "boards",
     multiple=True,
-    default=["?"],
+    default=[],
     show_default=True,
     help="The board(s) to download the firmware for.",
     metavar="BOARD_ID or ?",
@@ -71,16 +66,21 @@ def cli_download(
     **kwargs,
 ):
     params = DownloadParams(**kwargs)
-
-    if not params.boards:
-        # nothing specified - detect connected boards
+    params.versions = list(params.versions)
+    params.boards = list(params.boards)
+    if params.boards:
+        pass
+        # TODO Clean board - same as in cli_flash.py
+    else:
+        # no boards specified - detect connected boards
         params.ports, params.boards = connected_ports_boards()
-    # ask for any remaining parameters
+
     params = ask_missing_params(params, action="download")
+    if not params:  # Cancelled by user
+        exit(1)
+    params.versions = [clean_version(v, drop_v=True) for v in params.versions]
     assert isinstance(params, DownloadParams)
 
-    params.versions = [clean_version(v, drop_v=True) for v in params.versions]  # remove leading v from version
-
     download(
         params.fw_folder,
         params.ports,
@@ -89,3 +89,19 @@ def cli_download(
         params.force,
         params.clean,
     )
+
+
+def connected_ports_boards() -> Tuple[List[str], List[str]]:
+    """
+    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.
+
+    Returns:
+        A tuple containing two lists:
+            - A list of unique ports where MCUs are connected.
+            - A list of unique board names of the connected MCUs.
+    """
+    mpr_boards = [b for b in list_mcus() if b.connected]
+    ports = list({b.port for b in mpr_boards})
+    boards = list({b.board for b in mpr_boards})
+    return ports, boards

mpflash-0.6.0/mpflash/cli_flash.py

@@ -0,0 +1,165 @@
+from pathlib import Path
+
+import rich_click as click
+from loguru import logger as log
+
+from mpflash.errors import MPFlashError
+from mpflash.mpboard_id import find_stored_board
+from mpflash.vendor.versions import clean_version
+
+from .ask_input import FlashParams, ask_missing_params
+from .cli_download import connected_ports_boards
+from .cli_group import cli
+from .cli_list import show_mcus
+from .config import config
+from .flash import flash_list
+from .worklist import WorkList, full_auto_worklist, manual_worklist, single_auto_worklist
+
+# #########################################################################################################
+# CLI
+# #########################################################################################################
+
+
+@cli.command(
+    "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(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    default=config.firmware_folder,
+    show_default=True,
+    help="The folder to retrieve the firmware from.",
+)
+@click.option(
+    "--version",
+    "-v",
+    "version",  # single version
+    default="stable",
+    multiple=False,
+    show_default=True,
+    help="The version of MicroPython to flash.",
+    metavar="SEMVER, 'stable', 'preview' or '?'",
+)
+@click.option(
+    "--serial",
+    "--serial-port",
+    "-s",
+    "serial",
+    default="auto",
+    show_default=True,
+    help="Which serial port(s) to flash",
+    metavar="SERIAL_PORT",
+)
+@click.option(
+    "--port",
+    "-p",
+    "ports",
+    help="The MicroPython port to flash",
+    metavar="PORT",
+    default=[],
+    multiple=True,
+)
+@click.option(
+    "--board",
+    "-b",
+    "board",  # single board
+    multiple=False,
+    help="The MicroPython board ID to flash. If not specified will try to read the BOARD_ID from the connected MCU.",
+    metavar="BOARD_ID or ?",
+)
+@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",
+)
+@click.option(
+    "--erase/--no-erase",
+    default=True,
+    show_default=True,
+    help="""Erase flash before writing new firmware. (Not supported on UF2 boards)""",
+)
+@click.option(
+    "--bootloader/--no-bootloader",
+    default=True,
+    is_flag=True,
+    show_default=True,
+    help="""Enter micropython bootloader mode before flashing.""",
+)
+def cli_flash_board(**kwargs):
+    # version to versions, board to boards
+    kwargs["versions"] = [kwargs.pop("version")] if kwargs["version"] != None else []
+    if kwargs["board"] is None:
+        kwargs["boards"] = []
+        kwargs.pop("board")
+    else:
+        kwargs["boards"] = [kwargs.pop("board")]
+
+    params = FlashParams(**kwargs)
+    if not params.boards or params.boards == []:
+        # nothing specified - detect connected boards
+        params.ports, params.boards = connected_ports_boards()
+    else:
+        for board_id in params.boards:
+            if board_id == "":
+                params.boards.remove(board_id)
+                continue
+            if " " in board_id:
+                try:
+                    info = find_stored_board(board_id)
+                    if info:
+                        log.info(f"Resolved board description: {info['board']}")
+                        params.boards.remove(board_id)
+                        params.boards.append(info["board"])
+                except Exception as e:
+                    log.warning(f"unable to resolve board description: {e}")
+
+    # Ask for missing input if needed
+    params = ask_missing_params(params, action="flash")
+    if not params:  # Cancelled by user
+        exit(1)
+    # TODO: Just in time Download of firmware
+
+    assert isinstance(params, FlashParams)
+
+    if len(params.versions) > 1:
+        log.error(f"Only one version can be flashed at a time, not {params.versions}")
+        raise MPFlashError("Only one version can be flashed at a time")
+    if len(params.boards) > 1:
+        log.error(f"Only one board can be flashed at a time, not {params.boards}")
+        raise MPFlashError("Only one board can be flashed at a time")
+
+    params.versions = [clean_version(v) for v in params.versions]
+    worklist: WorkList = []
+    # if serial port == auto and there are one or more specified/detected boards
+    if params.serial == "auto" and params.boards:
+        worklist = full_auto_worklist(version=params.versions[0], fw_folder=params.fw_folder)
+    elif params.versions[0] and params.boards[0] and params.serial:
+        # A single serial port including the board / variant
+        worklist = manual_worklist(
+            params.versions[0],
+            params.fw_folder,
+            params.serial,
+            params.boards[0],
+        )
+    else:
+        # just this serial port on auto
+        worklist = single_auto_worklist(
+            serial_port=params.serial,
+            version=params.versions[0],
+            fw_folder=params.fw_folder,
+        )
+
+    if flashed := flash_list(
+        worklist,
+        params.fw_folder,
+        params.erase,
+        params.bootloader,
+    ):
+        log.info(f"Flashed {len(flashed)} boards")
+        show_mcus(flashed, title="Updated boards after flashing")

mpflash-0.6.0/mpflash/cli_list.py

@@ -0,0 +1,41 @@
+import json
+
+import rich_click as click
+from rich import print
+
+from .cli_group import cli
+from .list import list_mcus, show_mcus
+from .logger import make_quiet
+
+
+@cli.command("list", help="List the connected MCU boards.")
+@click.option(
+    "--json",
+    "-j",
+    "as_json",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="""Output in json format""",
+)
+@click.option(
+    "--progress/--no-progress",
+    "progress",
+    is_flag=True,
+    default=True,
+    show_default=True,
+    help="""Show progress""",
+)
+def cli_list_mcus(as_json: bool, progress: bool = True):
+    """List the connected MCU boards, and output in a nice table or json."""
+    if as_json:
+        # avoid noise in json output
+        make_quiet()
+
+    conn_mcus = list_mcus()
+    if as_json:
+        print(json.dumps([mcu.__dict__ for mcu in conn_mcus], indent=4))
+        progress = False
+    if progress:
+        show_mcus(conn_mcus, refresh=False)
+    return conn_mcus

{mpflash-0.5.0 → mpflash-0.6.0}/mpflash/cli_main.py

@@ -15,8 +15,12 @@ def mpflash():
     cli.add_command(cli_list_mcus)
     cli.add_command(cli_download)
     # cli(auto_envvar_prefix="MPFLASH")
-    cli()
+    try:
+        exit(cli())
+    except AttributeError as e:
+        print(f"Error: {e}")
+        exit(-1)
 
 
-# if __name__ == "__main__":
-mpflash()
+if __name__ == "__main__":
+    mpflash()

mpflash-0.6.0/mpflash/common.py

@@ -0,0 +1,38 @@
+import os
+import time
+from typing import TypedDict
+
+from github import Auth, Github
+from rich.progress import track
+
+from mpflash.errors import MPFlashError
+# from mpflash.mpremoteboard import MPRemoteBoard
+
+PORT_FWTYPES = {
+    "stm32": [".dfu"],  # need .dfu for pydfu.py - .hex for cube cli/GUI
+    "esp32": [".bin"],
+    "esp8266": [".bin"],
+    "rp2": [".uf2"],
+    "samd": [".uf2"],
+    "mimxrt": [".hex"],
+    "nrf": [".uf2"],
+    "renesas-ra": [".hex"],
+}
+
+# Token with no permissions to avoid throttling
+# https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#getting-a-higher-rate-limit
+PAT_NO_ACCESS = (
+    "github_pat" + "_11AAHPVFQ0qAkDnSUaMKSp" + "_ZkDl5NRRwBsUN6EYg9ahp1Dvj4FDDONnXVgimxC2EtpY7Q7BUKBoQ0Jq72X"
+)
+PAT = os.environ.get("GITHUB_TOKEN") or PAT_NO_ACCESS
+GH_CLIENT = Github(auth=Auth.Token(PAT))
+
+
+class FWInfo(TypedDict):
+    filename: str
+    port: str
+    board: str
+    variant: str
+    preview: bool
+    version: str
+    build: str

{mpflash-0.5.0 → mpflash-0.6.0}/mpflash/download.py

@@ -46,6 +46,9 @@ def get_board_urls(page_url: str) -> List[Dict[str, str]]:
     """
     Get the urls to all the board pages listed on this page.
     Assumes that all links to firmware  have "class": "board-card"
+
+    Args:
+        page_url (str): The url of the page to get the board urls from.
     """
     downloads_html = get_page(page_url)
     soup = BeautifulSoup(downloads_html, "html.parser")
@@ -57,8 +60,17 @@ def get_board_urls(page_url: str) -> List[Dict[str, str]]:
     return [{"board": board, "url": page_url + board} for board in boards]
 
 
-def firmware_list(board_url: str, base_url: str, ext: str) -> List[str]:
-    """Get the urls to all the firmware files for a board."""
+def board_firmware_urls(board_url: str, base_url: str, ext: str) -> List[str]:
+    """
+    Get the urls to all the firmware files for a board.
+    Args:
+        page_url (str): The url of the page to get the board urls from.
+    ??? base_url (str): The base url to join the relative urls to.
+        ext (str): The extension of the firmware files to get. (with or withouth leading .)
+
+    the urls are relative urls to the site root
+
+    """
     html = get_page(board_url)
     soup = BeautifulSoup(html, "html.parser")
     # get all the a tags:
@@ -109,7 +121,7 @@ def get_boards(ports: List[str], boards: List[str], clean: bool) -> List[Firmwar
             # add a board to the list for each firmware found
             firmwares = []
             for ext in PORT_FWTYPES[port]:
-                firmwares += firmware_list(board["url"], MICROPYTHON_ORG_URL, ext)
+                firmwares += board_firmware_urls(board["url"], MICROPYTHON_ORG_URL, ext)
 
             for _url in firmwares:
                 board["firmware"] = _url