pytest-embedded-serial-esp 1.18.2__py3-none-any.whl

pytest_embedded_serial_esp/__init__.py

@@ -0,0 +1,9 @@
+"""Make pytest-embedded plugin work with Espressif target boards."""
+
+from .serial import EspSerial
+
+__all__ = [
+    'EspSerial',
+]
+
+__version__ = '1.18.2'

pytest_embedded_serial_esp/serial.py

@@ -0,0 +1,213 @@
+import contextlib
+import functools
+import logging
+import subprocess
+import warnings
+from typing import List, Optional
+from warnings import warn
+
+import esptool
+from esptool import __version__ as ESPTOOL_VERSION
+from esptool.targets import CHIP_LIST as ESPTOOL_CHIPS
+from pexpect import TIMEOUT
+from pytest_embedded.log import MessageQueue, PexpectProcess, live_print_call
+from pytest_embedded.utils import Meta
+from pytest_embedded_serial.dut import Serial
+
+
+def _is_port_mac_verified(pexpect_proc: PexpectProcess, port: str, port_mac: str, msg_queue) -> bool:
+    try:
+        live_print_call(['esptool.py', '--port', port, 'read_mac'], msg_queue=msg_queue)
+    except subprocess.CalledProcessError:
+        return False
+    else:
+        try:
+            pexpect_proc.expect(f'MAC: {port_mac.lower()}', timeout=0.1)
+        except TIMEOUT:
+            return False
+        else:
+            return True
+
+
+class EsptoolArgs:
+    """
+    fake args object, this is a hack until esptool Python API is improved
+    """
+
+    def __init__(self, **kwargs):
+        warnings.warn('EsptoolArgs is deprecated and will be removed in 2.0 release.', DeprecationWarning)
+
+        for key, value in kwargs.items():
+            self.__setattr__(key, value)
+
+
+class EspSerial(Serial):
+    """
+    Serial class for ports connected to espressif products
+    """
+
+    ESPTOOL_DEFAULT_BAUDRATE = 921600
+
+    def __init__(
+        self,
+        pexpect_proc: PexpectProcess,
+        msg_queue: MessageQueue,
+        target: Optional[str] = None,
+        beta_target: Optional[str] = None,
+        port: Optional[str] = None,
+        port_serial_number: Optional[str] = None,
+        port_mac: Optional[str] = None,
+        baud: int = Serial.DEFAULT_BAUDRATE,
+        esptool_baud: int = ESPTOOL_DEFAULT_BAUDRATE,
+        esp_flash_force: bool = False,
+        skip_autoflash: bool = False,
+        erase_all: bool = False,
+        meta: Optional[Meta] = None,
+        ports_to_occupy: List[str] = (),
+        **kwargs,
+    ) -> None:
+        self._meta = meta
+        filters = {}
+        if port_serial_number:
+            filters['serials'] = [s.strip() for s in port_serial_number.split(',') if s.strip()]
+
+        esptool_target = beta_target or target or 'auto'
+        if port is None or port.endswith('*'):
+            port_filter = port.strip('*') if port else ''
+            available_ports = [_p for _p in esptool.get_port_list(**filters) if port_filter in _p]
+            ports = list(set(available_ports) - set(self.occupied_ports.keys()) - set(ports_to_occupy))
+
+            # sort to make /dev/ttyS* ports before /dev/ttyUSB* ports
+            # esptool will reverse the list
+            ports.sort()
+            if port_mac:
+                for port in ports:
+                    if _is_port_mac_verified(pexpect_proc, port, port_mac, msg_queue):
+                        ports = [port]
+                        break
+                else:
+                    raise ValueError(f'The specified MAC address {port_mac} cannot be found.')
+
+            # prioritize the cache recorded target port
+            if esptool_target and self._meta:
+                ports.sort(key=lambda x: self._meta.hit_port_target_cache(x, esptool_target))
+
+            logging.debug(f'Detecting ports from {", ".join(ports)}')
+        else:
+            if port_mac:
+                if _is_port_mac_verified(pexpect_proc, port, port_mac, msg_queue):
+                    ports = [port]
+                else:
+                    raise ValueError(f'The specified MAC address {port_mac} binds with different port, not with {port}')
+            else:
+                ports = [port]
+
+        # normal loader
+        if esptool_target not in ['auto', *ESPTOOL_CHIPS]:
+            raise ValueError(
+                f'esptool version {ESPTOOL_VERSION} not support target {esptool_target}\n'
+                f'Supported targets: {ESPTOOL_CHIPS}'
+            )
+
+        with contextlib.redirect_stdout(msg_queue):
+            self.esp = esptool.get_default_connected_device(
+                ports,
+                port=port,
+                connect_attempts=3,
+                initial_baud=baud,
+                chip=esptool_target,
+            )
+
+        if not self.esp:
+            raise ValueError('Couldn\'t auto detect chip. Please manually specify with "--port"')
+
+        target = self.esp.CHIP_NAME.lower().replace('-', '')
+        logging.info('Target: %s, Port: %s', target, self.esp.serial_port)
+
+        self.target = target
+
+        self.skip_autoflash = skip_autoflash
+        self.erase_all = erase_all
+        self.esptool_baud = esptool_baud
+        self.esp_flash_force = esp_flash_force
+
+        super().__init__(
+            msg_queue=msg_queue, port=self.esp._port, baud=baud, meta=meta, ports_to_occupy=ports_to_occupy, **kwargs
+        )
+
+    def _post_init(self):
+        if self._meta:
+            self._meta.set_port_target_cache(self.port, self.target)
+
+        if self.erase_all:
+            esptool.main(['erase_flash'], esp=self.esp)
+
+        super()._post_init()
+
+    def use_esptool(hard_reset_after: Optional[bool] = None, no_stub: Optional[bool] = None):
+        """
+        1. tell the redirect serial thread to stop reading from the `pyserial` instance
+        2. esptool reuse the `pyserial` instance and call `esptool.main()` to do the actual work
+        3. tell the redirect serial thread to continue reading from serial
+
+        Args:
+            hard_reset_after: run hard reset after (deprecated)
+            no_stub: disable launching the flasher stub (deprecated)
+        """
+        if hard_reset_after is not None:
+            warn(
+                "The 'hard_reset_after' parameter is now read directly from `flasher_args.json` "
+                'and does not need to be explicitly set. This parameter will be removed in 2.0 release.',
+                DeprecationWarning,
+            )
+
+        if no_stub is not None:
+            warn(
+                "The 'no_stub' parameter is now read directly from `flasher_args.json` "
+                'and does not need to be explicitly set. This parameter will be removed in 2.0 release.',
+                DeprecationWarning,
+            )
+
+        def decorator(func):
+            @functools.wraps(func)
+            def wrapper(self, *args, **kwargs):
+                with self.disable_redirect_thread():
+                    with contextlib.redirect_stdout(self._q):
+                        settings = self.proc.get_settings()
+                        self.esp.connect()
+                        ret = func(self, *args, **kwargs)
+                        self.proc.apply_settings(settings)
+                return ret
+
+            return wrapper
+
+        return decorator
+
+    def _start(self):
+        self.hard_reset()
+
+    def hard_reset(self):
+        """Hard reset your espressif device"""
+        self.esp.hard_reset()
+
+    @use_esptool()
+    def erase_flash(self, force: bool = False) -> None:
+        """Erase the complete flash"""
+        logging.info('Erasing the flash')
+        options = ['erase_flash']
+
+        if force or self.esp_flash_force:
+            options.append('--force')
+
+        esptool.main(options, esp=self.esp)
+
+        if self._meta:
+            self._meta.drop_port_app_cache(self.port)
+
+    @property
+    def stub(self):
+        warn(
+            'Please use `self.esp` instead of `self.stub`. `self.stub` will be removed in 2.0 release.',
+            DeprecationWarning,
+        )
+        return self.esp

pytest_embedded_serial_esp-1.18.2.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: pytest-embedded-serial-esp
+Version: 1.18.2
+Summary: Make pytest-embedded plugin work with Espressif target boards.
+Author-email: Fu Hanxi <fuhanxi@espressif.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Testing
+License-File: LICENSE
+Requires-Dist: pytest-embedded-serial~=1.18.2
+Requires-Dist: esptool~=4.9
+Project-URL: changelog, https://github.com/espressif/pytest-embedded/blob/main/CHANGELOG.md
+Project-URL: documentation, https://docs.espressif.com/projects/pytest-embedded/en/latest/
+Project-URL: homepage, https://github.com/espressif/pytest-embedded
+Project-URL: repository, https://github.com/espressif/pytest-embedded
+
+### pytest-embedded-serial-esp
+
+pytest embedded service for testing espressif boards via serial ports
+
+Extra Functionalities:
+
+- `serial`: detect and confirm target and port by `esptool` automatically.
+

pytest_embedded_serial_esp-1.18.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+pytest_embedded_serial_esp/__init__.py,sha256=vwxKZ3_npv1g_22hDERb7iMjQgDSYXASLgsdKp9KUNI,156
+pytest_embedded_serial_esp/serial.py,sha256=_6V6QhIVLadfjoSbhzEIYPjZPh0GqT7zU_9wZiAe4rI,7485
+pytest_embedded_serial_esp-1.18.2.dist-info/licenses/LICENSE,sha256=_Um-MzeKCR0JCDg5Ac_WFmZEfsPTd7PNlNi9JF1GBX8,1094
+pytest_embedded_serial_esp-1.18.2.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pytest_embedded_serial_esp-1.18.2.dist-info/METADATA,sha256=d5DvuoiJOILBNUQ8RbXAm3cvr3AgVJmhixsT3m1se40,1658
+pytest_embedded_serial_esp-1.18.2.dist-info/RECORD,,

pytest_embedded_serial_esp-1.18.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_embedded_serial_esp-1.18.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Espressif Systems (Shanghai) Co. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.