klab-pytest-toolkit-embedded 1.1.0__tar.gz

klab_pytest_toolkit_embedded-1.1.0/.gitignore

@@ -0,0 +1,178 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python
+# Edit at https://www.toptal.com/developers/gitignore?templates=python
+
+### Custom ###
+pytest.xml
+pytest-coverage.txt
+tmp/
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+.ms-playwright

klab_pytest_toolkit_embedded-1.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,198 @@
+# 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/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "klab-pytest-toolkit-embedded"
+dynamic = ["version"]
+description = "Pytest embedded testing fixtures for the Klab Pytest Toolkit"
+authors = [{ name = "Burak Kizilkaya", email = "burak.kizilkaya@outlook.com" }]
+requires-python = ">=3.11,<4"
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "esptool>=5.1.0",
+    "pyserial>=3.5",
+    "pytest>=8.3.5",
+]
+
+[project.urls]
+Changelog = "https://github.com/klab365/klab-pytest-toolkit/blob/main/CHANGELOG.md"
+Repository = "https://github.com/klab365/klab-pytest-toolkit"
+Issues = "https://github.com/klab365/klab-pytest-toolkit/issues"
+
+[project.entry-points.pytest11]
+klab_pytest_toolkit_embedded = "klab_pytest_toolkit_embedded.plugin"
+
+[tool.hatch.version]
+path = "src/klab_pytest_toolkit_embedded/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "tests",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = [
+  "."
+]

klab_pytest_toolkit_embedded-1.1.0/src/klab_pytest_toolkit_embedded/__init__.py

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

klab_pytest_toolkit_embedded-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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