micropython-stubber 1.17.5__py3-none-any.whl → 1.19.0__py3-none-any.whl

mpflash/mpflash/mpremoteboard/__init__.py

@@ -0,0 +1,208 @@
+"""
+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.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
+HERE = Path(__file__).parent
+
+OK = 0
+ERROR = -1
+RETRIES = 3
+###############################################################################################
+
+
+class MPRemoteBoard:
+    """Class to run mpremote commands"""
+
+    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.firmware = {}
+
+        self.connected = False
+        self.path: Optional[Path] = None
+        self.family = "unknown"
+        self.description = ""
+        self.version = ""
+        self.port = ""
+        self.board = ""
+        self.cpu = ""
+        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(bluetooth: bool = False) -> List[str]:
+        """
+        Get a list of connected boards.
+
+        Parameters:
+        - bluetooth (bool): Whether to include Bluetooth ports. Default is False.
+
+        Returns:
+        - List[str]: A list of connected board ports.
+        """
+        ports = serial.tools.list_ports.comports()
+
+        if not bluetooth:
+            # filter out bluetooth ports
+            ports = [p for p in ports if "bluetooth" not in p.description.lower()]
+            ports = [p for p in ports if "BTHENUM" not in p.hwid]
+
+        return sorted([p.device for p in ports])
+
+    @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.
+
+        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,
+            timeout=timeout,
+        )
+        if rc != OK:
+            raise ConnectionError(f"Failed to get mcu_info for {self.serialport}")
+        # Ok we have the info, now parse it
+        s = result[0].strip()
+        if s.startswith("{") and s.endswith("}"):
+            info = eval(s)
+            self.family = info["family"]
+            self.version = info["version"]
+            self.build = info["build"]
+            self.port = info["port"]
+            self.cpu = info["cpu"]
+            self.arch = info["arch"]
+            self.mpy = info["mpy"]
+            self.description = descr = info["board"]
+            pos = descr.rfind(" with")
+            short_descr = descr[:pos].strip() if pos != -1 else ""
+            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.
+
+        Returns:
+        - bool: True if successfully disconnected, False otherwise.
+        """
+        if not self.connected:
+            return True
+        if not self.serialport:
+            log.error("No port connected")
+            self.connected = False
+            return False
+        log.info(f"Disconnecting from {self.serialport}")
+        result = self.run_command(["disconnect"])[0] == OK
+        self.connected = False
+        return result
+
+    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(2), reraise=True)
+    def run_command(
+        self,
+        cmd: Union[str, List[str]],
+        *,
+        log_errors: bool = True,
+        no_info: bool = False,
+        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.
+        - 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"]
+        if self.serialport:
+            prefix += ["connect", self.serialport]
+        # if connected add resume to keep state between commands
+        if self.connected:
+            prefix += ["resume"]
+        cmd = prefix + cmd
+        log.debug(" ".join(cmd))
+        result = run(cmd, timeout, log_errors, no_info, **kwargs)
+        self.connected = result[0] == OK
+        return result
+
+    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(1))
+    def mip_install(self, name: str) -> bool:
+        """
+        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/mpflash/mpremoteboard/mpy_fw_info.py

@@ -0,0 +1,141 @@
+# %%micropython
+import os
+import sys
+
+
+def _build(s):
+    # extract build from sys.version or os.uname().version if available
+    # sys.version: 'MicroPython v1.23.0-preview.6.g3d0b6276f'
+    # sys.implementation.version: 'v1.13-103-gb137d064e'
+    if not s:
+        return ""
+    s = s.split(" on ", 1)[0] if " on " in s else s
+    if s.startswith("v"):
+        if not "-" in s:
+            return ""
+        b = s.split("-")[1]
+        return b
+    if not "-preview" in s:
+        return ""
+    b = s.split("-preview")[1].split(".")[1]
+    return b
+
+
+def _version_str(version: tuple):  #  -> str:
+    v_str = ".".join([str(n) for n in version[:3]])
+    if len(version) > 3 and version[3]:
+        v_str += "-" + version[3]
+    return v_str
+
+
+def _info():  # type:() -> dict[str, str]
+    # sourcery skip: use-contextlib-suppress, use-fstring-for-formatting, use-named-expression
+    info = dict(
+        {
+            "family": sys.implementation[0],  # type: ignore
+            "version": "",
+            "build": "",
+            "ver": "",
+            "port": "stm32" if sys.platform.startswith("pyb") else sys.platform,  # port: esp32 / win32 / linux / stm32
+            "board": "GENERIC",
+            "cpu": "",
+            "mpy": "",
+            "arch": "",
+        }
+    )
+    try:
+        info["version"] = _version_str(sys.implementation.version)
+    except AttributeError:
+        pass
+    try:
+        machine = sys.implementation._machine if "_machine" in dir(sys.implementation) else os.uname().machine
+        info["board"] = machine.strip()
+        info["cpu"] = machine.split("with")[-1].strip() if "with" in machine else ""
+        info["mpy"] = (
+            sys.implementation._mpy
+            if "_mpy" in dir(sys.implementation)
+            else sys.implementation.mpy if "mpy" in dir(sys.implementation) else ""
+        )
+    except (AttributeError, IndexError):
+        pass
+
+    try:
+        if hasattr(sys, "version"):
+            info["build"] = _build(sys.version)
+        elif hasattr(os, "uname"):
+            info["build"] = _build(os.uname()[3])
+            if not info["build"]:
+                # extract build from uname().release if available
+                info["build"] = _build(os.uname()[2])
+    except (AttributeError, IndexError):
+        pass
+    # avoid  build hashes
+    if info["build"] and len(info["build"]) > 5:
+        info["build"] = ""
+
+    if info["version"] == "" and sys.platform not in ("unix", "win32"):
+        try:
+            u = os.uname()
+            info["version"] = u.release
+        except (IndexError, AttributeError, TypeError):
+            pass
+    # detect families
+    for fam_name, mod_name, mod_thing in [
+        ("pycopy", "pycopy", "const"),
+        ("pycom", "pycom", "FAT"),
+        ("ev3-pybricks", "pybricks.hubs", "EV3Brick"),
+    ]:
+        try:
+            _t = __import__(mod_name, None, None, (mod_thing))
+            info["family"] = fam_name
+            del _t
+            break
+        except (ImportError, KeyError):
+            pass
+
+    if info["family"] == "ev3-pybricks":
+        info["release"] = "2.0.0"
+
+    if info["family"] == "micropython":
+        if (
+            info["version"]
+            and info["version"].endswith(".0")
+            and info["version"] >= "1.10.0"  # versions from 1.10.0 to 1.20.0 do not have a micro .0
+            and info["version"] <= "1.19.9"
+        ):
+            # drop the .0 for newer releases
+            info["version"] = info["version"][:-2]
+
+    # spell-checker: disable
+    if "mpy" in info and info["mpy"]:  # mpy on some v1.11+ builds
+        sys_mpy = int(info["mpy"])
+        # .mpy architecture
+        arch = [
+            None,
+            "x86",
+            "x64",
+            "armv6",
+            "armv6m",
+            "armv7m",
+            "armv7em",
+            "armv7emsp",
+            "armv7emdp",
+            "xtensa",
+            "xtensawin",
+        ][sys_mpy >> 10]
+        if arch:
+            info["arch"] = arch
+        # .mpy version.minor
+        info["mpy"] = "v{}.{}".format(sys_mpy & 0xFF, sys_mpy >> 8 & 3)
+    # simple to use version[-build] string avoiding f-strings for backward compat
+    info["ver"] = (
+        "v{version}-{build}".format(version=info["version"], build=info["build"])
+        if info["build"]
+        else "v{version}".format(version=info["version"])
+    )
+
+    return info
+
+
+print(_info())
+del _info, _build, _version_str

{stubber/bulk → mpflash/mpflash/mpremoteboard}/runner.py

@@ -11,6 +11,7 @@ from loguru import logger as log
 
 LogTagList = List[str]
 
+
 @dataclass
 class LogTags:
     reset_tags: LogTagList
@@ -26,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,
@@ -55,13 +57,24 @@ def run(
         The return code and the output as a list of strings
     """
     if not reset_tags:
-        reset_tags = ["rst cause:1, boot mode:"]
+        reset_tags = [
+            "rst cause:1, boot mode:",
+            "rst cause:2, boot mode:",
+            "rst cause:3, boot mode:",
+            "rst cause:4, boot mode:",
+        ]
+        # 0 -> normal startup by power on
+        # 1 -> hardware watch dog reset
+        # 2 -> software watch dog reset (From an exception)
+        # 3 -> software watch dog reset system_restart (Possibly unfed watchdog got angry)
+        # 4 -> soft restart (Possibly with a restart command)
+        # 5 -> wake up from deep-sleep
     if not error_tags:
         error_tags = ["Traceback ", "Error: ", "Exception: ", "ERROR :", "CRIT  :"]
     if not warning_tags:
-        warning_tags = ["WARN  :", "TRACE :"]  # , "Module not found."
+        warning_tags = ["WARN  :", "TRACE :"]
     if not success_tags:
-        success_tags = ["Created stubs for", "Path: /remote"]
+        success_tags = []
     if not ignore_tags:
         ignore_tags = ['  File "<stdin>",']
 
@@ -81,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:
@@ -111,13 +125,16 @@ 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:
                 log.warning(line)
+    except UnicodeDecodeError as e:
+        log.error(f"Failed to decode output: {e}")
     finally:
         timer.cancel()
 
     proc.wait(timeout=1)
     return proc.returncode or 0, output
-

mpflash/mpflash/vendor/dfu.py

@@ -0,0 +1,164 @@
+# sourcery skip: require-parameter-annotation
+# sourcery skip: replace-interpolation-with-fstring
+#!/usr/bin/python
+
+# Written by Antonio Galea - 2010/11/18
+# Distributed under Gnu LGPL 3.0
+# see http://www.gnu.org/licenses/lgpl-3.0.txt
+
+import os
+import struct
+import sys
+import zlib
+from optparse import OptionParser
+
+DEFAULT_DEVICE = "0x0483:0xdf11"
+
+
+def named(tuple, names):
+    return dict(zip(names.split(), tuple))
+
+
+def consume(fmt, data, names):
+    n = struct.calcsize(fmt)
+    return named(struct.unpack(fmt, data[:n]), names), data[n:]
+
+
+def cstring(string):
+    return string.split(b"\0", 1)[0]
+
+
+def compute_crc(data):
+    return 0xFFFFFFFF & -zlib.crc32(data) - 1
+
+
+def parse(file, dump_images=False):
+    print('File: "%s"' % file)
+    data = open(file, "rb").read()
+    crc = compute_crc(data[:-4])
+    prefix, data = consume("<5sBIB", data, "signature version size targets")
+    print("%(signature)s v%(version)d, image size: %(size)d, targets: %(targets)d" % prefix)
+    for t in range(prefix["targets"]):
+        tprefix, data = consume("<6sBI255s2I", data, "signature altsetting named name size elements")
+        tprefix["num"] = t
+        if tprefix["named"]:
+            tprefix["name"] = cstring(tprefix["name"])
+        else:
+            tprefix["name"] = ""
+        print(
+            '%(signature)s %(num)d, alt setting: %(altsetting)s, name: "%(name)s", size: %(size)d, elements: %(elements)d'
+            % tprefix
+        )
+        tsize = tprefix["size"]
+        target, data = data[:tsize], data[tsize:]
+        for e in range(tprefix["elements"]):
+            eprefix, target = consume("<2I", target, "address size")
+            eprefix["num"] = e
+            print("  %(num)d, address: 0x%(address)08x, size: %(size)d" % eprefix)
+            esize = eprefix["size"]
+            image, target = target[:esize], target[esize:]
+            if dump_images:
+                out = "%s.target%d.image%d.bin" % (file, t, e)
+                open(out, "wb").write(image)
+                print('    DUMPED IMAGE TO "%s"' % out)
+        if len(target):
+            print("target %d: PARSE ERROR" % t)
+    suffix = named(struct.unpack("<4H3sBI", data[:16]), "device product vendor dfu ufd len crc")
+    print(
+        "usb: %(vendor)04x:%(product)04x, device: 0x%(device)04x, dfu: 0x%(dfu)04x, %(ufd)s, %(len)d, 0x%(crc)08x"
+        % suffix
+    )
+    if crc != suffix["crc"]:
+        print("CRC ERROR: computed crc32 is 0x%08x" % crc)
+    data = data[16:]
+    if data:
+        print("PARSE ERROR")
+
+
+def build(file, targets, device=DEFAULT_DEVICE):
+    data = b""
+    for _, target in enumerate(targets):
+        tdata = b""
+        for image in target:
+            # pad image to 8 bytes (needed at least for L476)
+            pad = (8 - len(image["data"]) % 8) % 8
+            image["data"] = image["data"] + bytes(bytearray(8)[0:pad])
+            #
+            tdata += struct.pack("<2I", image["address"], len(image["data"])) + image["data"]
+        tdata = struct.pack("<6sBI255s2I", b"Target", 0, 1, b"ST...", len(tdata), len(target)) + tdata
+        data += tdata
+    data = struct.pack("<5sBIB", b"DfuSe", 1, len(data) + 11, len(targets)) + data
+    v, d = map(lambda x: int(x, 0) & 0xFFFF, device.split(":", 1))
+    data += struct.pack("<4H3sB", 0, d, v, 0x011A, b"UFD", 16)
+    crc = compute_crc(data)
+    data += struct.pack("<I", crc)
+    open(file, "wb").write(data)
+
+
+if __name__ == "__main__":
+    usage = """
+%prog [-d|--dump] infile.dfu
+%prog {-b|--build} address:file.bin [-b address:file.bin ...] [{-D|--device}=vendor:device] outfile.dfu"""
+    parser = OptionParser(usage=usage)
+    parser.add_option(
+        "-b",
+        "--build",
+        action="append",
+        dest="binfiles",
+        help="build a DFU file from given BINFILES",
+        metavar="BINFILES",
+    )
+    parser.add_option(
+        "-D",
+        "--device",
+        action="store",
+        dest="device",
+        help="build for DEVICE, defaults to %s" % DEFAULT_DEVICE,
+        metavar="DEVICE",
+    )
+    parser.add_option(
+        "-d",
+        "--dump",
+        action="store_true",
+        dest="dump_images",
+        default=False,
+        help="dump contained images to current directory",
+    )
+    (options, args) = parser.parse_args()
+
+    if options.binfiles and len(args) == 1:
+        target = []
+        for arg in options.binfiles:
+            try:
+                address, binfile = arg.split(":", 1)
+            except ValueError:
+                print("Address:file couple '%s' invalid." % arg)
+                sys.exit(1)
+            try:
+                address = int(address, 0) & 0xFFFFFFFF
+            except ValueError:
+                print("Address %s invalid." % address)
+                sys.exit(1)
+            if not os.path.isfile(binfile):
+                print("Unreadable file '%s'." % binfile)
+                sys.exit(1)
+            target.append({"address": address, "data": open(binfile, "rb").read()})
+        outfile = args[0]
+        device = DEFAULT_DEVICE
+        if options.device:
+            device = options.device
+        try:
+            v, d = map(lambda x: int(x, 0) & 0xFFFF, device.split(":", 1))
+        except:
+            print("Invalid device '%s'." % device)
+            sys.exit(1)
+        build(outfile, [target], device)
+    elif len(args) == 1:
+        infile = args[0]
+        if not os.path.isfile(infile):
+            print("Unreadable file '%s'." % infile)
+            sys.exit(1)
+        parse(infile, dump_images=options.dump_images)
+    else:
+        parser.print_help()
+        sys.exit(1)