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

mpflash/mpflash/ask_input.py

@@ -1,226 +1,236 @@
-"""
-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 typing import List, Sequence, Tuple, Union
-
-from loguru import logger as log
-
-from .common import DownloadParams, FlashParams, ParamType
-from .config import config
-from .mpboard_id import get_known_boards_for_port, get_known_ports, known_stored_boards
-from .mpremoteboard import MPRemoteBoard
-from .vendor.versions import micropython_versions
-
-
-def ask_missing_params(
-    params: ParamType,
-) -> 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.
-
-    Returns:
-        ParamType: The updated parameters.
-    """
-    import inquirer
-
-    log.trace(f"ask_missing_params: {params}")
-
-    # if action flash,  single input
-    # if action download, multiple input
-    multi_select = isinstance(params, DownloadParams)
-    action = "download" if isinstance(params, DownloadParams) else "flash"
-    if not config.interactive:
-        # no interactivity allowed
-        return params
-
-    questions = []
-    answers: dict[str, Union[str, List]] = {"action": action}
-    if not multi_select:
-        if not params.serial or "?" in params.serial:
-            questions.append(ask_serialport(multi_select=False, bluetooth=False))
-        else:
-            answers["serial"] = params.serial
-
-    if params.versions == [] or "?" in params.versions:
-        questions.append(ask_mp_version(multi_select=multi_select, 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:
-        questions.extend(ask_port_board(multi_select=multi_select, action=action))
-    if questions:
-        answers = inquirer.prompt(questions, answers=answers)  # type: ignore
-    if not answers:
-        # input cancelled by user
-        return []  # type: ignore
-    log.trace(f"answers: {answers}")
-    if isinstance(params, FlashParams) and "serial" in answers:
-        if isinstance(answers["serial"], str):
-            answers["serial"] = [answers["serial"]]
-        params.serial = [s.split()[0] for s in answers["serial"]]  # split to remove the description
-    if "port" in answers:
-        params.ports = [p for p in params.ports if p != "?"]  # remove the "?" if present
-        params.ports.extend(answers["port"])
-    if "boards" in answers:
-        params.boards = [b for b in params.boards if b != "?"]  # remove the "?" if present
-        params.boards.extend(answers["boards"] if isinstance(answers["boards"], list) else [answers["boards"]])
-    if "versions" in answers:
-        params.versions = [v for v in params.versions if v != "?"]  # remove the "?" if present
-        # make sure it is a list
-        if isinstance(answers["versions"], (list, tuple)):
-            params.versions.extend(answers["versions"])
-        else:
-            params.versions.append(answers["versions"])
-    # remove duplicates
-    params.ports = list(set(params.ports))
-    params.boards = list(set(params.boards))
-    params.versions = list(set(params.versions))
-    log.trace(f"ask_missing_params returns: {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.
-    """
-    versions = None
-    # 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
-        elif "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"])
-
-    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 = [(f"No {answers['port']} boards found for version(s) {versions}", "")]
-    return some_boards
-
-
-def ask_port_board(*, multi_select: bool, 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
-
-    # if action flash,  single input
-    # if action download, multiple input
-    inquirer_ux = inquirer.Checkbox if multi_select else inquirer.List
-    return [
-        inquirer.List(
-            "port",
-            message="Which port do you want to {action} " + "to {serial} ?" if action == "flash" else "?",
-            choices=get_known_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_mp_version(multi_select: bool, 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:
-
-    """
-    # import only when needed to reduce load time
-    import inquirer
-    import inquirer.errors
-
-    input_ux = inquirer.Checkbox if multi_select else inquirer.List
-
-    mp_versions: List[str] = micropython_versions()
-    mp_versions.reverse()  # newest first
-
-    # remove the versions for which there are no known boards in the board_info.json
-    # todo: this may be a little slow
-    mp_versions = [v for v in mp_versions if "preview" in v or get_known_boards_for_port("stm32", [v])]
-
-    def at_least_one_validation(answers, current) -> bool:
-        if not current:
-            raise inquirer.errors.ValidationError("", reason="Please select at least one version")
-        if isinstance(current, list) and not any(current):
-            raise inquirer.errors.ValidationError("", reason="Please select at least one version")
-        return True
-
-    message = "Which version(s) do you want to {action} " + ("to {serial} ?" if action == "flash" else "?")
-    q = input_ux(
-        # inquirer.List(
-        "versions",
-        message=message,
-        # 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=at_least_one_validation,  # type: ignore
-    )
-    return q
-
-
-def ask_serialport(*, multi_select: bool = False, bluetooth: bool = False):
-    """
-    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
-
-    comports = MPRemoteBoard.connected_boards(bluetooth=bluetooth, description=True)
-    return inquirer.List(
-        "serial",
-        message="Which serial port do you want to {action} ?",
-        choices=comports,
-        other=True,
-        validate=lambda _, x: True if x else "Please select or enter a serial port",  # type: ignore
-    )
+"""
+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 typing import List, Sequence, Tuple, Union
+
+from loguru import logger as log
+
+from .common import DownloadParams, FlashParams, ParamType
+from .config import config
+from .mpboard_id import (get_known_boards_for_port, get_known_ports,
+                         known_stored_boards)
+from .mpremoteboard import MPRemoteBoard
+from .vendor.versions import micropython_versions
+
+
+def ask_missing_params(
+    params: ParamType,
+) -> 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.
+
+    Returns:
+        ParamType: The updated parameters.
+    """
+    if not config.interactive:
+        # no interactivity allowed
+        log.info("Interactive mode disabled. Skipping ask for user input.")
+        return params
+
+    import inquirer
+
+    log.trace(f"ask_missing_params: {params}")
+
+    # if action flash,  single input
+    # if action download, multiple input
+    multi_select = isinstance(params, DownloadParams)
+    action = "download" if isinstance(params, DownloadParams) else "flash"
+
+    questions = []
+    answers: dict[str, Union[str, List]] = {"action": action}
+    if not multi_select:
+        if not params.serial or "?" in params.serial:
+            questions.append(ask_serialport(multi_select=False, bluetooth=False))
+        else:
+            answers["serial"] = params.serial
+
+    if params.versions == [] or "?" in params.versions:
+        questions.append(ask_mp_version(multi_select=multi_select, 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:
+        questions.extend(ask_port_board(multi_select=multi_select, action=action))
+    if questions:
+        answers = inquirer.prompt(questions, answers=answers)  # type: ignore
+    if not answers:
+        # input cancelled by user
+        return []  # type: ignore
+    log.trace(f"answers: {answers}")
+    if isinstance(params, FlashParams) and "serial" in answers:
+        if isinstance(answers["serial"], str):
+            answers["serial"] = [answers["serial"]]
+        params.serial = [s.split()[0] for s in answers["serial"]]  # split to remove the description
+    if "port" in answers:
+        #  params.ports = [p for p in params.ports if p != "?"]  # remove the "?" if present
+        if isinstance(answers["port"], str):
+            params.ports.append(answers["port"])
+        elif isinstance(answers["port"], list): # type: ignore
+            params.ports.extend(answers["port"])
+        else:
+            raise ValueError(f"Unexpected type for answers['port']: {type(answers['port'])}")
+        
+    if "boards" in answers:
+        params.boards = [b for b in params.boards if b != "?"]  # remove the "?" if present
+        params.boards.extend(answers["boards"] if isinstance(answers["boards"], list) else [answers["boards"]])
+    if "versions" in answers:
+        params.versions = [v for v in params.versions if v != "?"]  # remove the "?" if present
+        # make sure it is a list
+        if isinstance(answers["versions"], (list, tuple)):
+            params.versions.extend(answers["versions"])
+        else:
+            params.versions.append(answers["versions"])
+    # remove duplicates
+    params.ports = list(set(params.ports))
+    params.boards = list(set(params.boards))
+    params.versions = list(set(params.versions))
+    log.trace(f"ask_missing_params returns: {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.
+    """
+    versions = None
+    # 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
+        elif "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"])
+
+    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 = [(f"No {answers['port']} boards found for version(s) {versions}", "")]
+    return some_boards
+
+
+def ask_port_board(*, multi_select: bool, 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
+
+    # if action flash,  single input
+    # if action download, multiple input
+    inquirer_ux = inquirer.Checkbox if multi_select else inquirer.List
+    return [
+        inquirer.List(
+            "port",
+            message="Which port do you want to {action} " + "to {serial} ?" if action == "flash" else "?",
+            choices=get_known_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=at_least_one_validation,  # type: ignore
+            # validate=lambda _, x: True if x else "Please select at least one board",  # type: ignore
+        ),
+    ]
+
+def at_least_one_validation(answers, current) -> bool:
+    import inquirer.errors
+    if not current:
+        raise inquirer.errors.ValidationError("", reason="Please select at least one item.")
+    if isinstance(current, list) and not any(current):
+        raise inquirer.errors.ValidationError("", reason="Please select at least one item.")
+    return True
+
+def ask_mp_version(multi_select: bool, 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:
+
+    """
+    # import only when needed to reduce load time
+    import inquirer
+    import inquirer.errors
+
+    input_ux = inquirer.Checkbox if multi_select else inquirer.List
+
+    mp_versions: List[str] = micropython_versions()
+    mp_versions.reverse()  # newest first
+
+    # remove the versions for which there are no known boards in the board_info.json
+    # todo: this may be a little slow
+    mp_versions = [v for v in mp_versions if "preview" in v or get_known_boards_for_port("stm32", [v])]
+
+    message = "Which version(s) do you want to {action} " + ("to {serial} ?" if action == "flash" else "?")
+    q = input_ux(
+        # inquirer.List(
+        "versions",
+        message=message,
+        # 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=at_least_one_validation,  # type: ignore
+    )
+    return q
+
+
+def ask_serialport(*, multi_select: bool = False, bluetooth: bool = False):
+    """
+    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
+
+    comports = MPRemoteBoard.connected_boards(bluetooth=bluetooth, description=True)
+    return inquirer.List(
+        "serial",
+        message="Which serial port do you want to {action} ?",
+        choices=comports,
+        other=True,
+        validate=lambda _, x: True if x else "Please select or enter a serial port",  # type: ignore
+    )

mpflash/mpflash/bootloader/__init__.py

@@ -0,0 +1,37 @@
+import time
+
+from mpflash.common import BootloaderMethod
+from mpflash.errors import MPFlashError
+from mpflash.logger import log
+from mpflash.mpremoteboard import MPRemoteBoard
+
+from .manual import enter_bootloader_manual
+from .micropython import enter_bootloader_mpy
+from .touch1200 import enter_bootloader_cdc_1200bps
+
+
+def enter_bootloader(
+    mcu: MPRemoteBoard,
+    method: BootloaderMethod = BootloaderMethod.MPY,
+    timeout: int = 10,
+    wait_after: int = 2,
+):
+    """Enter the bootloader mode for the board"""
+    if method == BootloaderMethod.NONE:
+        # NO bootloader requested, so must be OK to flash
+        return True
+
+    log.info(f"Entering bootloader on {mcu.board} on {mcu.serialport} using method: {method.value}")
+    if method == BootloaderMethod.MPY:
+        result = enter_bootloader_mpy(mcu, timeout=timeout)
+    elif method == BootloaderMethod.MANUAL:
+        result = enter_bootloader_manual(mcu, timeout=timeout)
+    elif method == BootloaderMethod.TOUCH_1200:
+        result = enter_bootloader_cdc_1200bps(mcu, timeout=timeout)
+    else:
+        raise MPFlashError(f"Unknown bootloader method {method}")
+    if result:
+        time.sleep(wait_after)
+    else:
+        log.error(f"Failed to enter bootloader on {mcu.serialport}")
+    return result

mpflash/mpflash/bootloader/manual.py

@@ -0,0 +1,102 @@
+"""Manual bootloader mode entry for various MCUs."""
+
+from click.exceptions import Abort
+from rich.console import Console
+from rich.highlighter import RegexHighlighter
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.theme import Theme
+
+# from mpflash.logger import console, log
+from mpflash.mpremoteboard import MPRemoteBoard
+
+
+class MCUHighlighter(RegexHighlighter):
+    """Apply style to anything that looks like an email."""
+
+    base_style = "mcu."
+    highlights = [
+        r"(?P<bold>Method[\s\d\:]*)",
+        r"(?P<bold> \d.)",  # numbered items
+        r"(?P<bold> - )",  # bullets
+        r"(?P<pad>GPIO[\d]*)",
+        r"(?P<pad>GPI[\d]*)",
+        r"(?P<pad>IO[\d]*)",
+        r"(?P<pad>RUN)",
+        r"(?P<pad>GND)",
+        r"(?P<pad>VCC)",
+        r"(?P<pad>3.3V)",
+        r"(?P<pad>5V)",
+        # buttons
+        r"(?P<button>BOOTSEL)",
+        r"(?P<button>RESET)",
+        r"(?P<button>reset)",
+        # other
+        r"(?P<cable>USB)",
+        # r"(?P<mcu>SAMD[\d]*)",
+        # r"(?P<mcu>ESP[\d]*)",
+        # r"(?P<mcu>rp2)",
+        # r"(?P<mcu>rp2040)",
+    ]
+
+
+# https://rich.readthedocs.io/en/stable/appendix/colors.html?highlight=colors#standard-colors
+mcu_theme = Theme(
+    {
+        "mcu.bold": "orange3",
+        "mcu.mcu": "orange3",
+        "mcu.button": "bold green",
+        "mcu.pad": "dodger_blue2",
+        "mcu.cable": "dodger_blue2",
+    }
+)
+
+
+def enter_bootloader_manual(mcu: MPRemoteBoard, timeout: int = 10):
+
+    message: str
+    if mcu.port == "rp2":
+        message = f"""\
+Please put your {" ".join([mcu.port,mcu.board])} device into bootloader mode by either:
+Method 1:
+  1. Unplug the USB cable, 
+  2. Press and hold the BOOTSEL button on the device, 
+  3. Plug the USB cable back in.
+  4. Release the BOOTSEL button.
+    
+Method 2:
+  1. Press and hold the BOOTSEL button on the device, 
+  2. Reset the device by either: 
+    - pressing the RESET button on the device 
+    - by power-cycling the device,
+    - by briefly connecting the RUN pin to GND
+  3. Release the BOOTSEL button.
+"""
+    elif mcu.port == "samd":
+        message = f"""\
+Please put your {mcu.port.upper()} device into bootloader mode by:
+  - Pressing or sliding the RESET button twice in fast succession
+"""
+    else:
+        message = f"""\
+Please put your {mcu.port.upper()} device into bootloader mode by:
+  - Pressing the RESET button on the device
+"""
+
+    # todo: would be nice to re-use the console instance from logger
+    console = Console(highlighter=MCUHighlighter(), theme=mcu_theme)
+    message += "\nIf you are unsure how to enter bootloader mode, please refer to the device documentation."
+    console.print(
+        Panel(
+            message,
+            highlight=True,
+            title="Manual Bootloader",
+            title_align="left",
+            expand=False,
+        )
+    )
+    try:
+        answer = Confirm.ask("Press Enter to continue", default="y")
+    except Abort:
+        return False
+    return answer in ["y", "Y", True]

mpflash/mpflash/bootloader/micropython.py

@@ -0,0 +1,10 @@
+"""Module for handling the bootloader mode for micropython boards"""
+
+from mpflash.mpremoteboard import MPRemoteBoard
+
+
+def enter_bootloader_mpy(mcu: MPRemoteBoard, timeout: int = 10):
+    """Enter the bootloader mode for the board using mpremote and micropython on the board"""
+    mcu.run_command("bootloader", timeout=timeout)
+    # todo: check if mpremote command was successful
+    return True