micropython-stubber 1.20.4__py3-none-any.whl → 1.20.6__py3-none-any.whl

mpflash/mpflash/downloaded.py

@@ -1,129 +1,129 @@
-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 = [FWInfo.from_dict(item) for item in 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 clean_downloaded_firmwares(fw_folder: Path) -> None:
-    """
-    Remove duplicate entries from the firmware.jsonl file, keeping the latest one
-    uniqueness is based on the filename
-    """
-    firmwares = downloaded_firmwares(fw_folder)
-    if not firmwares:
-        return
-    # keep the latest entry
-    unique_fw = {fw.filename: fw for fw in firmwares}
-    with jsonlines.open(fw_folder / "firmware.jsonl", "w") as writer:
-        for fw in unique_fw.values():
-            writer.write(fw.to_dict())
-    log.info(f"Removed duplicate entries from firmware.jsonl in {fw_folder}")
-
-
-def find_downloaded_firmware(
-    *,
-    board_id: str,
-    version: str = "",  # v1.2.3
-    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
-    log.debug(f"{trie}] Looking for firmware for {board_id} {version} ")
-    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)
-    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 prefix
-            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 _RPI prefix
-            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,  # v1.2.3
-    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:
-        # FWInfo version has no v1.2.3 prefix
-        _version = {clean_version(version, drop_v=True), clean_version(version, drop_v=False)}
-        fw_list = [fw for fw in fw_list if fw.version in _version]
-    log.trace(f"Filtering firmware for {version} : {len(fw_list)} found.")
-    # filter by port
-    if port:
-        fw_list = [fw for fw in fw_list if fw.port == port]
-        log.trace(f"Filtering firmware for {port} : {len(fw_list)} found.")
-
-    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]
-        log.trace(f"Filtering firmware for {board_id} : {len(fw_list)} found.")
-    if selector and port in selector:
-        fw_list = [fw for fw in fw_list if fw.filename.endswith(selector[port])]
-    return fw_list
-
-
-# #########################################################################################################
-#
+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 = [FWInfo.from_dict(item) for item in 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 clean_downloaded_firmwares(fw_folder: Path) -> None:
+    """
+    Remove duplicate entries from the firmware.jsonl file, keeping the latest one
+    uniqueness is based on the filename
+    """
+    firmwares = downloaded_firmwares(fw_folder)
+    if not firmwares:
+        return
+    # keep the latest entry
+    unique_fw = {fw.filename: fw for fw in firmwares}
+    with jsonlines.open(fw_folder / "firmware.jsonl", "w") as writer:
+        for fw in unique_fw.values():
+            writer.write(fw.to_dict())
+    log.info(f"Removed duplicate entries from firmware.jsonl in {fw_folder}")
+
+
+def find_downloaded_firmware(
+    *,
+    board_id: str,
+    version: str = "",  # v1.2.3
+    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
+    log.debug(f"{trie}] Looking for firmware for {board_id} {version} ")
+    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)
+    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 prefix
+            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 _RPI prefix
+            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,  # v1.2.3
+    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:
+        # older FWInfo version has no v1.2.3 prefix
+        either = [clean_version(version, drop_v=False), clean_version(version, drop_v=True)]
+        fw_list = [fw for fw in fw_list if fw.version in either]
+    log.trace(f"Filtering firmware for {version} : {len(fw_list)} found.")
+    # filter by port
+    if port:
+        fw_list = [fw for fw in fw_list if fw.port == port]
+        log.trace(f"Filtering firmware for {port} : {len(fw_list)} found.")
+
+    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]
+        log.trace(f"Filtering firmware for {board_id} : {len(fw_list)} found.")
+    if selector and port in selector:
+        fw_list = [fw for fw in fw_list if fw.filename.endswith(selector[port])]
+    return fw_list
+
+
+# #########################################################################################################
+#

mpflash/mpflash/errors.py

@@ -1,5 +1,9 @@
-"""Custom exceptions for the MPFlash package."""
-
-
-class MPFlashError(Exception):
-    pass
+"""Custom exceptions for the MPFlash package."""
+
+
+class MPFlashError(Exception):
+    """Base class for exceptions in this module."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)

mpflash/mpflash/flash.py

@@ -1,69 +1,52 @@
-import time
-from pathlib import Path
-
-from loguru import logger as log
-
-from mpflash.common import PORT_FWTYPES
-from mpflash.mpremoteboard import MPRemoteBoard
-
-from .flash_esp import flash_esp
-from .flash_stm32 import flash_stm32
-from .flash_uf2 import flash_uf2
-from .worklist import WorkList
-
-# #########################################################################################################
-
-
-def flash_list(
-    todo: WorkList,
-    fw_folder: Path,
-    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
-        if not fw_file.exists():
-            log.error(f"File {fw_file} does not exist, skipping {mcu.board} on {mcu.serialport}")
-            continue
-        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}")
-
-        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):
-    """Enter the bootloader mode for the board"""
-    log.info(f"Entering bootloader on {mcu.board} on {mcu.serialport}")
-    mcu.run_command("bootloader", timeout=timeout)
-    time.sleep(wait_after)
-
-
-# TODO:
-# flash from some sort of queue to allow different images to be flashed to the same board
-#  - flash variant 1
-#  - stub variant 1
-#  - flash variant 2
-#  - stub variant 2
-#
-# JIT download / download any missing firmwares based on the detected boards
+from pathlib import Path
+
+from loguru import logger as log
+
+from mpflash.bootloader import enter_bootloader
+from mpflash.common import PORT_FWTYPES, BootloaderMethod
+
+from .flash_esp import flash_esp
+from .flash_stm32 import flash_stm32
+from .flash_uf2 import flash_uf2
+from .worklist import WorkList
+
+# #########################################################################################################
+
+
+
+def flash_list(
+    todo: WorkList,
+    fw_folder: Path,
+    erase: bool,
+    bootloader: BootloaderMethod,
+):
+    """Flash a list of boards with the specified firmware."""
+    UF2_PORTS = [port for port, exts in PORT_FWTYPES.items() if ".uf2" in exts]
+    flashed = []
+    for mcu, fw_info in todo:
+        fw_file = fw_folder / fw_info.filename
+        if not fw_file.exists():
+            log.error(f"File {fw_file} does not exist, skipping {mcu.board} on {mcu.serialport}")
+            continue
+        log.info(f"Updating {mcu.board} on {mcu.serialport} to {fw_info.version}")
+        updated = None
+        # try:
+        if mcu.port in UF2_PORTS and fw_file.suffix == ".uf2":
+            if not enter_bootloader(mcu, bootloader):
+                continue
+            updated = flash_uf2(mcu, fw_file=fw_file, erase=erase)
+        elif mcu.port in ["stm32"]:
+            if not enter_bootloader(mcu, bootloader):
+                continue
+            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}")
+
+        if updated:
+            flashed.append(updated)
+        else:
+            log.error(f"Failed to flash {mcu.board} on {mcu.serialport}")
+    return flashed

mpflash/mpflash/flash_esp.py

@@ -1,59 +1,59 @@
-"""
-# #########################################################################################################
-# Flash ESP32 and ESP8266 via esptool
-# #########################################################################################################
-"""
-
-from pathlib import Path
-from typing import List, Optional
-
-import esptool
-from loguru import logger as log
-
-from mpflash.mpboard_id import find_known_board
-from mpflash.mpremoteboard import MPRemoteBoard
-
-
-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"]:
-        log.error(f"esptool not supported for {mcu.port} {mcu.board} on {mcu.serialport}")
-        return None
-
-    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_known_board(mcu.board).cpu
-
-    cmds: List[List[str]] = []
-    if erase:
-        cmds.append(f"esptool --chip {mcu.cpu} --port {mcu.serialport} erase_flash".split())
-
-    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()
-            + [str(fw_file)]
-        )
-    try:
-        for cmd in cmds:
-            log.info(f"Running {' '.join(cmd)} ")
-            esptool.main(cmd[1:])
-    except Exception as e:
-        log.error(f"Failed to flash {mcu.board} on {mcu.serialport} : {e}")
-        return None
-
-    log.info("Done flashing, resetting the board and wait for it to restart")
-    mcu.wait_for_restart()
-    log.success(f"Flashed {mcu.serialport} to {mcu.board} {mcu.version}")
-    return mcu
+"""
+# #########################################################################################################
+# Flash ESP32 and ESP8266 via esptool
+# #########################################################################################################
+"""
+
+from pathlib import Path
+from typing import List, Optional
+
+import esptool
+from loguru import logger as log
+
+from mpflash.mpboard_id import find_known_board
+from mpflash.mpremoteboard import MPRemoteBoard
+
+
+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"]:
+        log.error(f"esptool not supported for {mcu.port} {mcu.board} on {mcu.serialport}")
+        return None
+
+    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_known_board(mcu.board).cpu
+
+    cmds: List[List[str]] = []
+    if erase:
+        cmds.append(f"esptool --chip {mcu.cpu} --port {mcu.serialport} erase_flash".split())
+
+    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()
+            + [str(fw_file)]
+        )
+    try:
+        for cmd in cmds:
+            log.info(f"Running {' '.join(cmd)} ")
+            esptool.main(cmd[1:])
+    except Exception as e:
+        log.error(f"Failed to flash {mcu.board} on {mcu.serialport} : {e}")
+        return None
+
+    log.info("Done flashing, resetting the board and wait for it to restart")
+    mcu.wait_for_restart()
+    log.success(f"Flashed {mcu.serialport} to {mcu.board} {mcu.version}")
+    return mcu

mpflash/mpflash/flash_stm32.py

@@ -1,24 +1,24 @@
-"""Flash STM32 boards using either STM32CubeProgrammer CLI or dfu-util"""
-
-from pathlib import Path
-
-from loguru import logger as log
-
-# from .flash_stm32_cube import flash_stm32_cubecli
-from .flash_stm32_dfu import dfu_init, flash_stm32_dfu
-from mpflash.mpremoteboard import MPRemoteBoard
-
-
-def flash_stm32(mcu: MPRemoteBoard, fw_file: Path, *, erase: bool, stm32_dfu: bool = True):
-    # sourcery skip: lift-return-into-if
-    log.info("Using dfu-util")
-    dfu_init()
-    updated = flash_stm32_dfu(mcu, fw_file=fw_file, erase=erase)
-    # if stm32_dfu:
-    # else:
-    #     log.info("Using STM32CubeProgrammer CLI")
-    #     updated = flash_stm32_cubecli(mcu, fw_file=fw_file, erase=erase)
-
-    mcu.wait_for_restart()
-    log.success(f"Flashed {mcu.version} to {mcu.board}")
-    return updated
+"""Flash STM32 boards using either STM32CubeProgrammer CLI or dfu-util"""
+
+from pathlib import Path
+
+from loguru import logger as log
+
+# from .flash_stm32_cube import flash_stm32_cubecli
+from .flash_stm32_dfu import dfu_init, flash_stm32_dfu
+from mpflash.mpremoteboard import MPRemoteBoard
+
+
+def flash_stm32(mcu: MPRemoteBoard, fw_file: Path, *, erase: bool, stm32_dfu: bool = True):
+    # sourcery skip: lift-return-into-if
+    log.info("Using dfu-util")
+    dfu_init()
+    updated = flash_stm32_dfu(mcu, fw_file=fw_file, erase=erase)
+    # if stm32_dfu:
+    # else:
+    #     log.info("Using STM32CubeProgrammer CLI")
+    #     updated = flash_stm32_cubecli(mcu, fw_file=fw_file, erase=erase)
+
+    mcu.wait_for_restart()
+    log.success(f"Flashed {mcu.version} to {mcu.board}")
+    return updated