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

mpflash/common.py

@@ -1,14 +1,12 @@
 import os
 import time
-from functools import lru_cache
 from typing import TypedDict
 
 from github import Auth, Github
-from loguru import logger as log
-from packaging.version import parse
 from rich.progress import track
 
-from mpflash.mpremoteboard import MPRemoteBoard
+from mpflash.errors import MPFlashError
+# from mpflash.mpremoteboard import MPRemoteBoard
 
 PORT_FWTYPES = {
     "stm32": [".dfu"],  # need .dfu for pydfu.py - .hex for cube cli/GUI
@@ -38,125 +36,3 @@ class FWInfo(TypedDict):
     preview: bool
     version: str
     build: str
-
-
-#############################################################
-# Version handling copied from stubber/utils/versions.py
-#############################################################
-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.info(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]
-
-
-#############################################################
-def wait_for_restart(mcu: MPRemoteBoard, 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:
-            mcu.get_mcu_info()
-            break
-        except ConnectionError:
-            pass

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

mpflash/downloaded.py

@@ -0,0 +1,108 @@
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import jsonlines
+from loguru import logger as log
+
+from mpflash.common import FWInfo
+from mpflash.vendor.versions import clean_version
+
+from .config import config
+
+
+# #########################################################################################################
+def downloaded_firmwares(fw_folder: Path) -> List[FWInfo]:
+    """Load a list of locally downloaded firmwares from the jsonl file"""
+    firmwares: List[FWInfo] = []
+    try:
+        with jsonlines.open(fw_folder / "firmware.jsonl") as reader:
+            firmwares.extend(iter(reader))
+    except FileNotFoundError:
+        log.error(f"No firmware.jsonl found in {fw_folder}")
+    # sort by filename
+    firmwares.sort(key=lambda x: x["filename"])
+    return firmwares
+
+
+def find_downloaded_firmware(
+    *,
+    board_id: str,
+    version: str = "",
+    port: str = "",
+    variants: bool = False,
+    fw_folder: Optional[Path] = None,
+    trie: int = 1,
+    selector: Optional[Dict[str, str]] = None,
+) -> List[FWInfo]:
+    if selector is None:
+        selector = {}
+    fw_folder = fw_folder or config.firmware_folder
+    # Use the information in firmwares.jsonl to find the firmware file
+    fw_list = downloaded_firmwares(fw_folder)
+    if not fw_list:
+        log.error("No firmware files found. Please download the firmware first.")
+        return []
+    # filter by version
+    version = clean_version(version, drop_v=True)
+    fw_list = filter_downloaded_fwlist(fw_list, board_id, version, port, variants, selector)
+
+    if not fw_list and trie < 3:
+        log.info(f"Try ({trie+1}) to find a firmware for the board {board_id}")
+        if trie == 1:
+            # ESP board naming conventions have changed by adding a PORT refix
+            if port.startswith("esp") and not board_id.startswith(port.upper()):
+                board_id = f"{port.upper()}_{board_id}"
+            # RP2 board naming conventions have changed by adding a _RPIprefix
+            if port == "rp2" and not board_id.startswith("RPI_"):
+                board_id = f"RPI_{board_id}"
+        elif trie == 2:
+            board_id = board_id.replace("_", "-")
+
+        fw_list = find_downloaded_firmware(
+            fw_folder=fw_folder,
+            board_id=board_id,
+            version=version,
+            port=port,
+            trie=trie + 1,
+            selector=selector,
+        )
+        # hope we have a match now for the board
+    # sort by filename
+    fw_list.sort(key=lambda x: x["filename"])
+    return fw_list
+
+
+def filter_downloaded_fwlist(
+    fw_list: List[FWInfo],
+    board_id: str,
+    version: str,
+    port: str,
+    # preview: bool,
+    variants: bool,
+    selector: dict,
+) -> List[FWInfo]:
+    """Filter the downloaded firmware list based on the provided parameters"""
+    if "preview" in version:
+        # never get a preview for an older version
+        fw_list = [fw for fw in fw_list if fw["preview"]]
+    else:
+        fw_list = [fw for fw in fw_list if fw["version"] == version]
+
+    # filter by port
+    if port:
+        fw_list = [fw for fw in fw_list if fw["port"] == port]
+
+    if board_id:
+        if variants:
+            # any variant of this board_id
+            fw_list = [fw for fw in fw_list if fw["board"] == board_id]
+        else:
+            # the firmware variant should match exactly the board_id
+            fw_list = [fw for fw in fw_list if fw["variant"] == board_id]
+    if selector and port in selector:
+        fw_list = [fw for fw in fw_list if fw["filename"].endswith(selector[port])]
+    return fw_list
+
+
+# #########################################################################################################
+#

mpflash/errors.py

@@ -0,0 +1,5 @@
+"""Custom exceptions for the MPFlash package."""
+
+
+class MPFlashError(Exception):
+    pass

mpflash/flash.py

@@ -1,150 +1,55 @@
 import time
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
 
-import jsonlines
 from loguru import logger as log
 
+from mpflash.common import PORT_FWTYPES
 from mpflash.mpremoteboard import MPRemoteBoard
 
-from .common import FWInfo, clean_version
-from .config import config
+from .flash_esp import flash_esp
+from .flash_stm32 import flash_stm32
+from .flash_uf2 import flash_uf2
+from .worklist import WorkList
 
 # #########################################################################################################
-WorkList = List[Tuple[MPRemoteBoard, FWInfo]]
 
 
-# #########################################################################################################
-def local_firmwares(fw_folder: Path) -> List[FWInfo]:
-    """Load a list of locally available  firmwares from the jsonl file"""
-    firmwares: List[FWInfo] = []
-    try:
-        with jsonlines.open(fw_folder / "firmware.jsonl") as reader:
-            firmwares.extend(iter(reader))
-    except FileNotFoundError:
-        log.error(f"No firmware.jsonl found in {fw_folder}")
-    # sort by filename
-    firmwares.sort(key=lambda x: x["filename"])
-    return firmwares
-
-
-def find_firmware(
-    *,
-    board: str,
-    version: str = "",
-    port: str = "",
-    variants: bool = False,
-    fw_folder: Optional[Path] = None,
-    trie: int = 1,
-    selector: Optional[Dict[str, str]] = None,
-) -> List[FWInfo]:
-    if selector is None:
-        selector = {}
-    fw_folder = fw_folder or config.firmware_folder
-    # Use the information in firmwares.jsonl to find the firmware file
-    fw_list = local_firmwares(fw_folder)
-    if not fw_list:
-        log.error("No firmware files found. Please download the firmware first.")
-        return []
-    # filter by version
-    version = clean_version(version, drop_v=True)
-    fw_list = filter_fwlist(fw_list, board, version, port, variants, selector)
-
-    if not fw_list and trie < 2:
-        board_id = board.replace("_", "-")
-        # ESP board naming conventions have changed by adding a PORT refix
-        if port.startswith("esp") and not board_id.startswith(port.upper()):
-            board_id = f"{port.upper()}_{board_id}"
-        # RP2 board naming conventions have changed by adding a _RPIprefix
-        if port == "rp2" and not board_id.startswith("RPI_"):
-            board_id = f"RPI_{board_id}"
-
-        log.info(f"Try ({trie}) to find a firmware for the board {board_id}")
-        fw_list = find_firmware(
-            fw_folder=fw_folder,
-            board=board_id,
-            version=version,
-            port=port,
-            trie=trie + 1,
-            selector=selector,
-        )
-        # hope we have a match now for the board
-    # sort by filename
-    fw_list.sort(key=lambda x: x["filename"])
-    return fw_list
-
-
-def filter_fwlist(
-    fw_list: List[FWInfo],
-    board: str,
-    version: str,
-    port: str,
-    # preview: bool,
-    variants: bool,
-    selector: dict,
-) -> List[FWInfo]:
-    """Filter the firmware list based on the provided parameters"""
-    if "preview" in version:
-        # never get a preview for an older version
-        fw_list = [fw for fw in fw_list if fw["preview"]]
-    else:
-        fw_list = [fw for fw in fw_list if fw["version"] == version]
-
-    # filter by port
-    if port:
-        fw_list = [fw for fw in fw_list if fw["port"] == port]
-
-    if board:
-        if variants:
-            fw_list = [fw for fw in fw_list if fw["board"] == board]
-        else:
-            # the variant should match exactly the board name
-            fw_list = [fw for fw in fw_list if fw["variant"] == board]
-    if selector and port in selector:
-        fw_list = [fw for fw in fw_list if fw["filename"].endswith(selector[port])]
-    return fw_list
-
-
-# #########################################################################################################
-#
-
-
-def auto_update(
-    conn_boards: List[MPRemoteBoard],
-    target_version: str,
+def flash_list(
+    todo: WorkList,
     fw_folder: Path,
-    *,
-    selector: Optional[Dict[str, str]] = None,
-) -> WorkList:
-    """Builds a list of boards to update based on the connected boards and the firmware available"""
-    if selector is None:
-        selector = {}
-    wl: WorkList = []
-    for mcu in conn_boards:
-        if mcu.family != "micropython":
-            log.warning(
-                f"Skipping {mcu.family} {mcu.port} {mcu.board} on {mcu.serialport} as it is a MicroPython firmware"
-            )
-            continue
-        board_firmwares = find_firmware(
-            fw_folder=fw_folder,
-            board=mcu.board,
-            version=target_version,
-            port=mcu.port,
-            selector=selector,
-        )
-
-        if not board_firmwares:
-            log.error(f"No {target_version} firmware found for {mcu.board} on {mcu.serialport}.")
+    erase: bool,
+    bootloader: bool,
+):
+    """Flash a list of boards with the specified firmware."""
+    flashed = []
+    for mcu, fw_info in todo:
+        fw_file = fw_folder / fw_info["filename"]  # type: ignore
+        if not fw_file.exists():
+            log.error(f"File {fw_file} does not exist, skipping {mcu.board} on {mcu.serialport}")
             continue
-        if len(board_firmwares) > 1:
-            log.debug(f"Multiple {target_version} firmwares found for {mcu.board} on {mcu.serialport}.")
+        log.info(f"Updating {mcu.board} on {mcu.serialport} to {fw_info['version']}")
+        updated = None
+        # try:
+        if mcu.port in [port for port, exts in PORT_FWTYPES.items() if ".uf2" in exts] and fw_file.suffix == ".uf2":
+            # any .uf2 port ["samd", "rp2", "nrf"]:
+            if bootloader:
+                enter_bootloader(mcu)
+            updated = flash_uf2(mcu, fw_file=fw_file, erase=erase)
+        elif mcu.port in ["stm32"]:
+            if bootloader:
+                enter_bootloader(mcu)
+            updated = flash_stm32(mcu, fw_file, erase=erase)
+        elif mcu.port in ["esp32", "esp8266"]:
+            #  bootloader is handled by esptool for esp32/esp8266
+            updated = flash_esp(mcu, fw_file=fw_file, erase=erase)
+        else:
+            log.error(f"Don't (yet) know how to flash {mcu.port}-{mcu.board} on {mcu.serialport}")
 
-        # just use the last firmware
-        fw_info = board_firmwares[-1]
-        log.info(f"Found {target_version} firmware {fw_info['filename']} for {mcu.board} on {mcu.serialport}.")
-        wl.append((mcu, fw_info))
-    return wl
+        if updated:
+            flashed.append(updated)
+        else:
+            log.error(f"Failed to flash {mcu.board} on {mcu.serialport}")
+    return flashed
 
 
 def enter_bootloader(mcu: MPRemoteBoard, timeout: int = 10, wait_after: int = 2):

mpflash/flash_esp.py

@@ -10,11 +10,9 @@ from typing import List, Optional
 import esptool
 from loguru import logger as log
 
-from mpflash.mpboard_id.api import find_mp_board
+from mpflash.mpboard_id import find_stored_board
 from mpflash.mpremoteboard import MPRemoteBoard
 
-from .common import wait_for_restart
-
 
 def flash_esp(mcu: MPRemoteBoard, fw_file: Path, *, erase: bool = True) -> Optional[MPRemoteBoard]:
     if mcu.port not in ["esp32", "esp8266"] or mcu.board in ["ARDUINO_NANO_ESP32"]:
@@ -24,27 +22,24 @@ def flash_esp(mcu: MPRemoteBoard, fw_file: Path, *, erase: bool = True) -> Optio
     log.info(f"Flashing {fw_file} on {mcu.board} on {mcu.serialport}")
     if not mcu.cpu:
         # Lookup CPU based on the board name
-        mcu.cpu = find_mp_board(mcu.board)["cpu"]
+        mcu.cpu = find_stored_board(mcu.board)["cpu"]
 
-    if mcu.port == "esp8266":
-        baud_rate = str(460_800)
-    else:
-        baud_rate = str(512_000)
-        # baud_rate = str(115_200)
     cmds: List[List[str]] = []
     if erase:
         cmds.append(f"esptool --chip {mcu.cpu} --port {mcu.serialport} erase_flash".split())
 
-    if mcu.cpu.upper() in ("ESP32", "ESP32S2"):
-        start_addr = "0x1000"
-    elif mcu.cpu.upper() in ("ESP32S3", "ESP32C3"):
-        start_addr = "0x0"
     if mcu.cpu.upper().startswith("ESP32"):
+        baud_rate = str(921_600)
+        if mcu.cpu.upper() in ("ESP32", "ESP32S2"):
+            start_addr = "0x1000"
+        elif mcu.cpu.upper() in ("ESP32S3", "ESP32C3"):
+            start_addr = "0x0"
         cmds.append(
             f"esptool --chip {mcu.cpu} --port {mcu.serialport} -b {baud_rate} write_flash --compress {start_addr}".split()
             + [str(fw_file)]
         )
     elif mcu.cpu.upper() == "ESP8266":
+        baud_rate = str(460_800)
         start_addr = "0x0"
         cmds.append(
             f"esptool --chip {mcu.cpu} --port {mcu.serialport} -b {baud_rate} write_flash --flash_size=detect {start_addr}".split()
@@ -59,6 +54,6 @@ def flash_esp(mcu: MPRemoteBoard, fw_file: Path, *, erase: bool = True) -> Optio
         return None
 
     log.info("Done flashing, resetting the board and wait for it to restart")
-    wait_for_restart(mcu)
-    log.success(f"Flashed {mcu.version} to {mcu.board}")
+    mcu.wait_for_restart()
+    log.success(f"Flashed {mcu.serialport} to {mcu.board} {mcu.version}")
     return mcu

mpflash/flash_stm32.py

@@ -4,8 +4,6 @@ from pathlib import Path
 
 from loguru import logger as log
 
-from mpflash.common import wait_for_restart
-
 # from .flash_stm32_cube import flash_stm32_cubecli
 from .flash_stm32_dfu import dfu_init, flash_stm32_dfu
 from mpflash.mpremoteboard import MPRemoteBoard
@@ -21,6 +19,6 @@ def flash_stm32(mcu: MPRemoteBoard, fw_file: Path, *, erase: bool, stm32_dfu: bo
     #     log.info("Using STM32CubeProgrammer CLI")
     #     updated = flash_stm32_cubecli(mcu, fw_file=fw_file, erase=erase)
 
-    wait_for_restart(mcu)
+    mcu.wait_for_restart()
     log.success(f"Flashed {mcu.version} to {mcu.board}")
     return updated

mpflash/flash_stm32_cube.py

@@ -16,7 +16,6 @@
 # from rich.progress import track
 # from strip_ansi import strip_ansi
 
-# from .common import wait_for_restart
 # from .mpremoteboard.mpremoteboard import MPRemoteBoard
 
 # STM32_CLI_WIN = "C:\\Program Files\\STMicroelectronics\\STM32Cube\\STM32CubeProgrammer\\bin\\STM32_Programmer_CLI.exe"

mpflash/flash_stm32_dfu.py

@@ -8,7 +8,12 @@ from mpflash.mpremoteboard import MPRemoteBoard
 
 
 def init_libusb_windows() -> bool:
-    # on windows we need to initialze the libusb backend with the correct dll
+    """
+    Initializes the libusb backend on Windows.
+
+    Returns:
+        bool: True if the initialization is successful, False otherwise.
+    """
     import libusb  # type: ignore
     import usb.backend.libusb1 as libusb1
 
@@ -21,12 +26,15 @@ def init_libusb_windows() -> bool:
 
 
 try:
-    from .vendored import pydfu as pydfu
+    from .vendor import pydfu as pydfu
 except ImportError:
     pydfu = None
 
 
 def dfu_init():
+    """
+    Initializes the DFU (Device Firmware Upgrade) process.
+    """
     if not pydfu:
         log.error("pydfu not found")
         return None
@@ -40,11 +48,17 @@ def flash_stm32_dfu(
     *,
     erase: bool = True,
 ) -> Optional[MPRemoteBoard]:
+    """
+    Flashes the STM32 microcontroller using DFU (Device Firmware Upgrade).
 
-    # if sys.platform == "win32":
-    #     log.error(f"OS {sys.platform} not supported")
-    #     return None
+    Args:
+        mcu (MPRemoteBoard): The remote board to flash.
+        fw_file (Path): The path to the firmware file (.dfu).
+        erase (bool, optional): Whether to erase the memory before flashing. Defaults to True.
 
+    Returns:
+        Optional[MPRemoteBoard]: The flashed remote board if successful, None otherwise.
+    """
     if not pydfu:
         log.error("pydfu not found, please install it with 'pip install pydfu' if supported")
         return None

mpflash/flash_uf2.py

@@ -56,6 +56,6 @@ def flash_uf2(mcu: MPRemoteBoard, fw_file: Path, erase: bool) -> Optional[MPRemo
     log.success("Done copying, resetting the board and wait for it to restart")
     if sys.platform in ["linux", "darwin"]:
         dismount_uf2()
-    for _ in track(range(5 + 2)):
+    for _ in track(range(5 + 2), description="Waiting for the board to restart", transient=True):
         time.sleep(1)  # 5 secs to short on linux
     return mcu