klab-pytest-toolkit-embedded 1.1.0__py3-none-any.whl

klab_pytest_toolkit_embedded/__init__.py

@@ -0,0 +1,4 @@
+"""Klab Pytest Toolkit - Embedded package."""
+
+__version__ = "1.1.0"
+__all__ = []

klab_pytest_toolkit_embedded/board.py

@@ -0,0 +1,107 @@
+import re
+import time
+
+from klab_pytest_toolkit_embedded.communicators import CommunicatorInterface
+from klab_pytest_toolkit_embedded.debug_probes import DebugProbe
+
+
+class Board:
+    """Main class for the orchestration of board operations.
+
+    This class uses a debug probe to program and reset the board,
+    and a communication interface to send and receive data.
+
+    It could be, that both functionalities are provided by the same physical device,
+    but this is abstracted away by using separate interfaces.
+    """
+
+    def __init__(
+        self,
+        debug_probe: DebugProbe,
+        communicator: CommunicatorInterface,
+    ):
+        """Initialize the board.
+
+        Args:
+            debug_probe: Debug probe instance (e.g., EspTool)
+            communication_interface: Communication interface instance (e.g., SerialCommunicator)
+        """
+        self._debug_probe = debug_probe
+        self._communicator = communicator
+
+    def program(self, fw_image: str) -> None:
+        """Flash the firmware image to the board.
+
+        Args:
+            fw_image (str): Path to the firmware image.
+        """
+        self._debug_probe.program(fw_image)
+
+    def reset(self) -> None:
+        """Reset the board."""
+        self._debug_probe.reset()
+
+    def receive_some(self, num_bytes: int = 1024) -> bytes:
+        """Receive some data from the communication interface.
+
+        Args:
+            num_bytes (int, optional): Number of bytes to receive. Defaults to 1024.
+
+        Returns:
+            bytes: Received data.
+        """
+        return self._communicator.receive(num_bytes)
+
+    def send(self, data: bytes) -> None:
+        """Send data to the device through the communication interface.
+
+        Args:
+            data: Bytes to send
+        """
+        self._communicator.send(data)
+
+    def wait_for_regex_in_line(self, regex, timeout_s=20, log=True) -> bool:
+        """Wait for a line matching the regex from the communication interface.
+
+        Args:
+            regex: Regular expression to match.
+            timeout_s (int, optional): Timeout in seconds. Defaults to 20.
+            log (bool, optional): Whether to log the output. Defaults to True.
+
+        Returns:
+            bool: True if a matching line is found, False otherwise.
+        """
+        received = b""  # Start with bytes, not string
+        start_time = time.time()
+        while True:
+            # Check for timeout
+            if time.time() - start_time > timeout_s:
+                raise TimeoutError(f"Timeout waiting for regex: {regex}")
+
+            # Check in already received data
+            lines = received.splitlines(keepends=True)
+
+            for _, line in enumerate(lines):
+                regex_search = re.search(
+                    regex,
+                    line.replace(b"\r", b"").replace(b"\n", b"").decode("utf-8", errors="ignore"),
+                )
+                if regex_search:
+                    return True
+
+            # Receive more data
+            chunk = self.receive_some()
+
+            if log:
+                print(chunk.replace(b"\r", b"").decode("utf-8", errors="ignore"), end="")
+
+            received = received + chunk
+
+    def __enter__(self):
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Exit context manager."""
+        self._communicator.close()
+        self._debug_probe.close()

klab_pytest_toolkit_embedded/communicators/__init__.py

@@ -0,0 +1,4 @@
+from klab_pytest_toolkit_embedded.communicators.interface import CommunicatorInterface
+from klab_pytest_toolkit_embedded.communicators.serial import SerialCommunicator
+
+__all__ = ["CommunicatorInterface", "SerialCommunicator"]

klab_pytest_toolkit_embedded/communicators/interface.py

@@ -0,0 +1,22 @@
+"""Communication interface definition for embedded boards."""
+
+import abc
+
+
+class CommunicatorInterface(abc.ABC):
+    """Abstract interface for MCU communication."""
+
+    @abc.abstractmethod
+    def send(self, data: bytes) -> None:
+        """Send data to the device."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def receive(self, num_bytes: int) -> bytes:
+        """Receive data from the device."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Close the communication channel."""
+        raise NotImplementedError

klab_pytest_toolkit_embedded/communicators/serial.py

@@ -0,0 +1,113 @@
+"""Serial communication implementation for embedded boards."""
+
+import serial
+
+from klab_pytest_toolkit_embedded.communicators.interface import CommunicatorInterface
+
+
+class SerialCommunicator(CommunicatorInterface):
+    """Serial port communication interface for UART/USB connections."""
+
+    def __init__(
+        self,
+        port: str,
+        baudrate: int = 115200,
+        timeout: float = 1.0,
+        bytesize: int = serial.EIGHTBITS,
+        parity: str = serial.PARITY_NONE,
+        stopbits: float = serial.STOPBITS_ONE,
+    ):
+        """Initialize serial communication.
+
+        Args:
+            port: Serial port path (e.g., '/dev/ttyUSB0', 'COM3')
+            baudrate: Communication speed in bits per second (default: 115200)
+            timeout: Read timeout in seconds (default: 1.0)
+            bytesize: Number of data bits (default: 8)
+            parity: Parity checking mode (default: None)
+            stopbits: Number of stop bits (default: 1)
+        """
+        self.port = port
+        self.baudrate = baudrate
+        self._serial: serial.Serial | None = None
+
+        # Open the serial connection
+        self._serial = serial.Serial(
+            port=port,
+            baudrate=baudrate,
+            timeout=timeout,
+            bytesize=bytesize,
+            parity=parity,
+            stopbits=stopbits,
+        )
+
+    def send(self, data: bytes) -> None:
+        """Send data to the device.
+
+        Args:
+            data: Bytes to send
+
+        Raises:
+            RuntimeError: If serial port is not open
+        """
+        if not self._serial or not self._serial.is_open:
+            raise RuntimeError("Serial port is not open")
+
+        self._serial.write(data)
+        self._serial.flush()
+
+    def receive(self, num_bytes: int) -> bytes:
+        """Receive data from the device.
+
+        Args:
+            num_bytes: Maximum number of bytes to receive
+
+        Returns:
+            Received bytes (may be less than num_bytes if timeout occurs)
+
+        Raises:
+            RuntimeError: If serial port is not open
+        """
+        if not self._serial or not self._serial.is_open:
+            raise RuntimeError("Serial port is not open")
+
+        return self._serial.read(num_bytes)
+
+    def close(self) -> None:
+        """Close the serial connection."""
+        if self._serial and self._serial.is_open:
+            self._serial.close()
+
+    def flush_input(self) -> None:
+        """Flush input buffer, discarding all pending data."""
+        if self._serial and self._serial.is_open:
+            self._serial.reset_input_buffer()
+
+    def flush_output(self) -> None:
+        """Flush output buffer, waiting for all data to be transmitted."""
+        if self._serial and self._serial.is_open:
+            self._serial.reset_output_buffer()
+
+    def bytes_available(self) -> int:
+        """Get number of bytes available in the input buffer.
+
+        Returns:
+            Number of bytes available to read
+        """
+        if not self._serial or not self._serial.is_open:
+            return 0
+
+        return self._serial.in_waiting
+
+    def __enter__(self) -> "SerialCommunicator":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit - ensures cleanup."""
+        self.close()
+
+    def __repr__(self) -> str:
+        """String representation."""
+        status = "open" if (self._serial and self._serial.is_open) else "closed"
+        return f"<SerialCommunicator(port='{self.port}', baudrate={self.baudrate}, {status})>"

klab_pytest_toolkit_embedded/debug_probes/__init__.py

@@ -0,0 +1,4 @@
+from klab_pytest_toolkit_embedded.debug_probes.interface import DebugProbe
+from klab_pytest_toolkit_embedded.debug_probes.esp import EspTool
+
+__all__ = ["DebugProbe", "EspTool"]

klab_pytest_toolkit_embedded/debug_probes/esp.py

@@ -0,0 +1,48 @@
+from klab_pytest_toolkit_embedded.debug_probes.interface import DebugProbe
+
+import esptool
+
+
+class EspTool(DebugProbe):
+    """ESP debug probe using esptool.py."""
+
+    def __init__(self, port: str, baudrate: int = 1500000, address: str = "0x0"):
+        self._port = port
+        self._baudrate = baudrate
+        self._address = address
+
+    def program(self, fw_image: str) -> None:
+        cmd = [
+            "--chip",
+            "esp32",
+            "--port",
+            self._port,
+            "--baud",
+            str(self._baudrate),
+            "--after",
+            "hard_reset",
+            "write_flash",
+            "-e",
+            self._address,
+            fw_image,
+        ]
+
+        esptool.main(cmd)
+
+    def reset(self) -> None:
+        cmd = [
+            "--chip",
+            "esp32",
+            "--port",
+            self._port,
+            "--baud",
+            str(self._baudrate),
+            "reset",
+        ]
+
+        esptool.main(cmd)
+
+    def close(self) -> None:
+        """Close the debug probe connection."""
+        # esptool does not maintain a persistent connection, so nothing to close.
+        pass

klab_pytest_toolkit_embedded/debug_probes/interface.py

@@ -0,0 +1,26 @@
+"""Debug probe interface definition for embedded boards."""
+
+import abc
+
+
+class DebugProbe(abc.ABC):
+    """Abstract base class for debug probes."""
+
+    @abc.abstractmethod
+    def program(self, fw_image: str) -> None:
+        """Flash the firmware image to the target device.
+
+        Args:
+            fw_image (str): Path to the firmware image.
+        """
+        raise NotImplementedError("program method must be implemented by subclasses")
+
+    @abc.abstractmethod
+    def reset(self) -> None:
+        """Reset the target device."""
+        raise NotImplementedError("reset method must be implemented by subclasses")
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Close the debug probe connection."""
+        raise NotImplementedError("close method must be implemented by subclasses")

klab_pytest_toolkit_embedded/plugin.py

@@ -0,0 +1,6 @@
+"""Pytest plugin for embedded testing."""
+
+
+def pytest_configure(config):
+    """Register custom markers and configuration for klab-pytest-toolkit-embedded."""
+    pass

klab_pytest_toolkit_embedded-1.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: klab-pytest-toolkit-embedded
+Version: 1.1.0
+Summary: Pytest embedded testing fixtures for the Klab Pytest Toolkit
+Project-URL: Changelog, https://github.com/klab365/klab-pytest-toolkit/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/klab365/klab-pytest-toolkit
+Project-URL: Issues, https://github.com/klab365/klab-pytest-toolkit/issues
+Author-email: Burak Kizilkaya <burak.kizilkaya@outlook.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <4,>=3.11
+Requires-Dist: esptool>=5.1.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pytest>=8.3.5
+Description-Content-Type: text/markdown
+
+# Klab Pytest Toolkit - Embedded
+
+[![PyPI](https://img.shields.io/pypi/v/klab-pytest-toolkit-embedded)](https://pypi.org/project/klab-pytest-toolkit-embedded/)
+[![Python](https://img.shields.io/pypi/pyversions/klab-pytest-toolkit-embedded)](https://pypi.org/project/klab-pytest-toolkit-embedded/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+Custom pytest fixtures for embedded systems testing.
+The goal is to allow testers to easily test embedded devices with reusable components for programming, resetting, and communicating with boards.
+
+At the moment the package provides the following components:
+
+- `Board`: Main orchestration class for managing board operations, including programming, resetting, and communication.
+- Debug Probes:
+  - `EspTool`: Debug probe implementation for ESP32 devices using `esptool`.
+- Communicators:
+  - `SerialCommunicator`: Serial port communication interface for UART/USB connections.
+
+## Installation
+
+```bash
+pip install klab-pytest-toolkit-embedded
+```
+
+## Usage
+
+### Board Class
+
+The `Board` class orchestrates board operations by combining a debug probe (for programming and resetting) with a communicator (for sending and receiving data).
+
+**Create a fixture**
+
+```python
+import pytest
+from pathlib import Path
+from typing import Generator
+from klab_pytest_toolkit_embedded.board import Board
+from klab_pytest_toolkit_embedded.debug_probes import EspTool
+from klab_pytest_toolkit_embedded.communicators import SerialCommunicator
+
+@pytest.fixture
+def dut() -> Generator[Board]:
+    """Fixture to provide a Board instance for Device Under Test (DUT)."""
+    PORT = "/dev/ttyUSB0"
+    
+    communicator = SerialCommunicator(port=PORT, baudrate=115200)
+    debug_probe = EspTool(port=PORT, baudrate=1500000, address="0x0")
+    
+    with Board(debug_probe=debug_probe, communicator=communicator) as board:
+        yield board
+```
+
+**Programming and Reset**
+
+```python
+def test_program_firmware(dut: Board):
+    """Test programming firmware to the board."""
+    firmware_file = "path/to/firmware.bin"
+    dut.program(firmware_file)
+    # Firmware is now flashed to the device
+
+def test_reset_board(dut: Board):
+    """Test resetting the board."""
+    dut.reset()
+    # Board has been reset
+```
+
+**Communication**
+
+The `Board` class provides methods for sending and receiving data:
+
+```python
+def test_send_data(dut: Board):
+    """Test sending data to the board."""
+    dut.send(b"Hello Device!\n")
+
+def test_receive_data(dut: Board):
+    """Test receiving data from the board."""
+    data = dut.receive_some(num_bytes=1024)
+    print(data.decode('utf-8', errors='ignore'))
+
+def test_wait_for_boot_message(dut: Board):
+    """Test waiting for a specific message during boot."""
+    firmware_file = "path/to/firmware.bin"
+    dut.program(firmware_file)
+    
+    # Wait for boot message with regex
+    boot_message = b"Firmware Ready!"
+    assert dut.wait_for_regex_in_line(boot_message, timeout_s=10, log=True)
+```
+
+### Serial Communicator
+
+The `SerialCommunicator` provides serial communication functionality with configurable parameters:
+
+```python
+from klab_pytest_toolkit_embedded.communicators import SerialCommunicator
+
+# Create a serial communicator
+communicator = SerialCommunicator(
+    port="/dev/ttyUSB0",
+    baudrate=115200,
+    timeout=1.0
+)
+
+# Send data
+communicator.send(b"AT\r\n")
+
+# Receive data
+data = communicator.receive(num_bytes=100)
+
+# Check available bytes
+available = communicator.bytes_available()
+
+# Flush buffers
+communicator.flush_input()
+communicator.flush_output()
+
+# Close when done
+communicator.close()
+```
+
+### ESP Debug Probe
+
+The `EspTool` class provides programming and reset functionality for ESP32 devices:
+
+```python
+from klab_pytest_toolkit_embedded.debug_probes import EspTool
+
+# Create ESP debug probe
+esp_probe = EspTool(
+    port="/dev/ttyUSB0",
+    baudrate=1500000,
+    address="0x0"
+)
+
+# Program firmware
+esp_probe.program("path/to/firmware.bin")
+
+# Reset the device
+esp_probe.reset()
+
+# Close (no persistent connection for esptool)
+esp_probe.close()
+```
+
+## Examples
+
+See the test files for comprehensive examples.
+
+## Best Practices
+
+### Use Context Managers
+
+The `Board` class supports context managers to ensure proper cleanup of resources:
+
+```python
+with Board(debug_probe=debug_probe, communicator=communicator) as board:
+    board.program(firmware_file)
+    board.wait_for_regex_in_line(b"Ready", timeout_s=10)
+    # Resources are automatically closed when exiting the context
+```
+
+### Timeout Configuration
+
+When waiting for messages from the device, always specify appropriate timeouts to prevent tests from hanging:
+
+```python
+# Wait with custom timeout
+dut.wait_for_regex_in_line(
+    regex=b"Boot complete",
+    timeout_s=30,
+    log=True  # Enable logging to see device output
+)
+```
+
+### Hardware Availability
+
+For tests that require physical hardware, use `pytest.mark.skipif` to conditionally skip tests when hardware is not available:
+
+```python
+@pytest.mark.skipif(
+    not hardware_available(),
+    reason="This test requires a physical ESP32 device connected."
+)
+def test_with_hardware(dut: Board):
+    # Test code here
+    pass
+```
+
+## Links
+
+- [Source code](https://github.com/klab365/klab-pytest-toolkit/tree/main/packages/klab-pytest-toolkit-embedded)
+- [PyPI](https://pypi.org/project/klab-pytest-toolkit-embedded/)
+- [Issue tracker](https://github.com/klab365/klab-pytest-toolkit/issues)
+
+## License
+
+MIT

klab_pytest_toolkit_embedded-1.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+klab_pytest_toolkit_embedded/__init__.py,sha256=XuKlGM4HmHN1IY-4P6b7v7hUMqnU4QpWZSc8qjds6nc,82
+klab_pytest_toolkit_embedded/board.py,sha256=ygFculAQPWVs0QUoqGqSpJPrsHD7Ok9BLO3VTym7GGA,3423
+klab_pytest_toolkit_embedded/plugin.py,sha256=jcsFRt-xUmol-6vJmHdWxyMkalE3Pkmqg8KKlgYCNS4,169
+klab_pytest_toolkit_embedded/communicators/__init__.py,sha256=aGxQIBkucDVkL2GfkUr7oMke-I8XY79GV-thCNAc1HQ,227
+klab_pytest_toolkit_embedded/communicators/interface.py,sha256=J8LKxoekqkQ2e1vYFg7LzW212QqGxDpWbm0JLF0EXag,591
+klab_pytest_toolkit_embedded/communicators/serial.py,sha256=K-Fzin_ePh4Kh-fp5yGIohJ-rfbZ-Z9SG6deMnYH9aY,3574
+klab_pytest_toolkit_embedded/debug_probes/__init__.py,sha256=Y-24bcddqoXKWKpWyz6tdNYN-cFfrJl2MaCh17ULi8U,178
+klab_pytest_toolkit_embedded/debug_probes/esp.py,sha256=B7UHM3tjqDcmVvU-OpUwC0r5M3iisyYK50QfzfQ5Syo,1147
+klab_pytest_toolkit_embedded/debug_probes/interface.py,sha256=p3h9VPdcnk-BLINOjNmwbbwdjLBCNVYGPtsGAcc95D4,810
+klab_pytest_toolkit_embedded-1.1.0.dist-info/METADATA,sha256=JBd6mW3teoq8lT09xL6ecNHkDv8yw3A8CBsDbb771u0,6267
+klab_pytest_toolkit_embedded-1.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+klab_pytest_toolkit_embedded-1.1.0.dist-info/entry_points.txt,sha256=kUVjtsOnIuuc3h6iU-rqoUD_yqrV4k2Z-JkewJT6Dbg,78
+klab_pytest_toolkit_embedded-1.1.0.dist-info/RECORD,,

klab_pytest_toolkit_embedded-1.1.0.dist-info/WHEEL

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

klab_pytest_toolkit_embedded-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+klab_pytest_toolkit_embedded = klab_pytest_toolkit_embedded.plugin