siliconrig 0.2.0__tar.gz

siliconrig-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

siliconrig-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.egg
+.*
+!.gitignore
+!.github/

siliconrig-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RAWS Consulting
+
+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.

siliconrig-0.2.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: siliconrig
+Version: 0.2.0
+Summary: Python SDK and pytest fixtures for siliconrig hardware-in-the-loop testing
+Project-URL: Homepage, https://siliconrig.dev
+Project-URL: Documentation, https://siliconrig.dev/docs/guides/python-sdk
+Project-URL: Repository, https://github.com/siliconrig/srig-python
+Author: RAWS Consulting
+License-Expression: MIT
+License-File: LICENSE
+Keywords: HIL,MCU,embedded,hardware-in-the-loop,pytest,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: websockets<15,>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# siliconrig
+
+Python SDK for [siliconrig](https://siliconrig.dev) — remote access to MCU development boards.
+
+Use it in scripts, automation, or as a pytest plugin for hardware-in-the-loop testing.
+
+## Install
+
+```bash
+pip install siliconrig
+```
+
+## Quick start
+
+```python
+from siliconrig import Client
+
+client = Client()
+
+with client.session(board="esp32s3") as session:
+    session.flash("firmware.bin")
+    session.serial.expect("Ready", timeout=10)
+    session.serial.send("status\n")
+    print(session.serial.read_until("OK", timeout=5))
+```
+
+Or use the `Board` shorthand:
+
+```python
+from siliconrig import Board
+
+with Board("esp32-s3", firmware="build/app.bin") as board:
+    board.expect("System ready", timeout=5)
+    board.send("gpio set 4 1\n")
+    board.expect("GPIO4=HIGH", timeout=2)
+```
+
+## pytest plugin
+
+The package includes a pytest plugin that registers automatically. Use it with custom fixtures:
+
+```python
+import pytest
+from siliconrig import Board
+
+@pytest.fixture
+def board():
+    with Board("esp32-s3", firmware="build/app.bin") as b:
+        yield b
+
+def test_boot_ok(board):
+    assert board.expect("System ready", timeout=5)
+```
+
+Or use the built-in `siliconrig_board` fixture via CLI options:
+
+```bash
+pytest --siliconrig-board esp32s3 --siliconrig-firmware build/app.bin tests/hil/
+```
+
+## Authentication
+
+Set your API key via environment variable:
+
+```bash
+export SRIG_API_KEY=key_...
+```
+
+Or pass it directly:
+
+```python
+client = Client(api_key="key_...")
+```
+
+## Documentation
+
+- [Python SDK guide](https://siliconrig.dev/docs/guides/python-sdk)
+- [CI/CD integration](https://siliconrig.dev/docs/guides/cicd)

siliconrig-0.2.0/README.md

@@ -0,0 +1,78 @@
+# siliconrig
+
+Python SDK for [siliconrig](https://siliconrig.dev) — remote access to MCU development boards.
+
+Use it in scripts, automation, or as a pytest plugin for hardware-in-the-loop testing.
+
+## Install
+
+```bash
+pip install siliconrig
+```
+
+## Quick start
+
+```python
+from siliconrig import Client
+
+client = Client()
+
+with client.session(board="esp32s3") as session:
+    session.flash("firmware.bin")
+    session.serial.expect("Ready", timeout=10)
+    session.serial.send("status\n")
+    print(session.serial.read_until("OK", timeout=5))
+```
+
+Or use the `Board` shorthand:
+
+```python
+from siliconrig import Board
+
+with Board("esp32-s3", firmware="build/app.bin") as board:
+    board.expect("System ready", timeout=5)
+    board.send("gpio set 4 1\n")
+    board.expect("GPIO4=HIGH", timeout=2)
+```
+
+## pytest plugin
+
+The package includes a pytest plugin that registers automatically. Use it with custom fixtures:
+
+```python
+import pytest
+from siliconrig import Board
+
+@pytest.fixture
+def board():
+    with Board("esp32-s3", firmware="build/app.bin") as b:
+        yield b
+
+def test_boot_ok(board):
+    assert board.expect("System ready", timeout=5)
+```
+
+Or use the built-in `siliconrig_board` fixture via CLI options:
+
+```bash
+pytest --siliconrig-board esp32s3 --siliconrig-firmware build/app.bin tests/hil/
+```
+
+## Authentication
+
+Set your API key via environment variable:
+
+```bash
+export SRIG_API_KEY=key_...
+```
+
+Or pass it directly:
+
+```python
+client = Client(api_key="key_...")
+```
+
+## Documentation
+
+- [Python SDK guide](https://siliconrig.dev/docs/guides/python-sdk)
+- [CI/CD integration](https://siliconrig.dev/docs/guides/cicd)

siliconrig-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "siliconrig"
+dynamic = ["version"]
+description = "Python SDK and pytest fixtures for siliconrig hardware-in-the-loop testing"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "RAWS Consulting" }]
+keywords = ["embedded", "testing", "hardware-in-the-loop", "HIL", "pytest", "MCU"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+    "Topic :: System :: Hardware",
+]
+dependencies = [
+    "websockets>=13.0,<15",
+    "httpx>=0.27,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+]
+
+[project.urls]
+Homepage = "https://siliconrig.dev"
+Documentation = "https://siliconrig.dev/docs/guides/python-sdk"
+Repository = "https://github.com/siliconrig/srig-python"
+
+[project.entry-points.pytest11]
+siliconrig = "siliconrig.plugin"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/siliconrig"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 99

siliconrig-0.2.0/src/siliconrig/__init__.py

@@ -0,0 +1,21 @@
+"""siliconrig — Python SDK for hardware-in-the-loop testing."""
+
+from siliconrig.client import Client
+from siliconrig.board import Board
+from siliconrig.exceptions import (
+    SiliconrigError,
+    AuthError,
+    SessionError,
+    FlashError,
+    SerialTimeout,
+)
+
+__all__ = [
+    "Client",
+    "Board",
+    "SiliconrigError",
+    "AuthError",
+    "SessionError",
+    "FlashError",
+    "SerialTimeout",
+]

siliconrig-0.2.0/src/siliconrig/board.py

@@ -0,0 +1,118 @@
+"""High-level Board convenience wrapper."""
+
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Self
+
+from siliconrig.client import Client
+from siliconrig.session import Session
+
+
+class Board:
+    """Convenience wrapper that creates a client, session, and flashes firmware.
+
+    Designed for concise pytest fixtures::
+
+        @pytest.fixture
+        def board():
+            with Board("esp32-s3", firmware="build/app.bin") as b:
+                yield b
+
+        def test_boot(board):
+            assert board.expect("Ready", timeout=5)
+
+    Serial methods (``send``, ``read``, ``read_until``, ``expect``, ``flush``)
+    are available directly on the Board instance for convenience.
+    """
+
+    def __init__(
+        self,
+        board_type: str,
+        firmware: str | Path | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        self._board_type = board_type
+        self._firmware = firmware
+        self._api_key = api_key
+        self._base_url = base_url
+        self._client: Client | None = None
+        self._session: Session | None = None
+        self._ctx: Any = None
+
+    def __enter__(self) -> Self:
+        self._client = Client(api_key=self._api_key, base_url=self._base_url)
+        self._ctx = self._client.session(board=self._board_type)
+        self._session = self._ctx.__enter__()
+
+        if self._firmware:
+            self._session.flash(self._firmware)
+
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._ctx:
+            self._ctx.__exit__(exc_type, exc_val, exc_tb)
+        if self._client:
+            self._client.close()
+
+    # -- proxied serial methods -----------------------------------------------
+
+    def send(self, data: str) -> None:
+        """Send data to the board's UART."""
+        assert self._session is not None
+        self._session.serial.send(data)
+
+    def read(self, n: int = 4096, timeout: float = 5.0) -> str:
+        """Read up to *n* characters."""
+        assert self._session is not None
+        return self._session.serial.read(n, timeout=timeout)
+
+    def read_until(self, pattern: str, timeout: float = 10.0) -> str:
+        """Read until *pattern* appears."""
+        assert self._session is not None
+        return self._session.serial.read_until(pattern, timeout=timeout)
+
+    def expect(self, pattern: str, timeout: float = 10.0) -> str:
+        """Assert that *pattern* appears within *timeout* seconds."""
+        assert self._session is not None
+        return self._session.serial.expect(pattern, timeout=timeout)
+
+    def flush(self) -> None:
+        """Clear the serial receive buffer."""
+        assert self._session is not None
+        self._session.serial.flush()
+
+    # -- proxied session methods ----------------------------------------------
+
+    def flash(self, firmware: str | Path, timeout: float = 120.0) -> None:
+        """Flash firmware to the board."""
+        assert self._session is not None
+        self._session.flash(firmware, timeout=timeout)
+
+    def reset(self) -> None:
+        """Power-cycle the board."""
+        assert self._session is not None
+        self._session.reset()
+
+    def info(self) -> dict[str, Any]:
+        """Get session details."""
+        assert self._session is not None
+        return self._session.info()
+
+    @property
+    def serial(self):
+        """Access the underlying Serial instance."""
+        assert self._session is not None
+        return self._session.serial
+
+    @property
+    def session(self) -> Session:
+        """Access the underlying Session instance."""
+        assert self._session is not None
+        return self._session

siliconrig-0.2.0/src/siliconrig/client.py

@@ -0,0 +1,108 @@
+"""siliconrig API client."""
+
+import os
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+import httpx
+
+from siliconrig.exceptions import AuthError, SessionError
+from siliconrig.session import Session
+
+DEFAULT_BASE_URL = "https://api.srig.io"
+DEFAULT_TIMEOUT = 30.0
+
+
+class Client:
+    """Client for the siliconrig REST API.
+
+    Args:
+        api_key: API key (``key_...``). Falls back to
+            the ``SRIG_API_KEY`` environment variable.
+        base_url: Coordinator base URL. Falls back to ``SRIG_BASE_URL``
+            or ``https://api.srig.io``.
+        timeout: Default HTTP timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("SRIG_API_KEY")
+        if not self.api_key:
+            raise AuthError(
+                "No API key provided. Pass api_key= or set SRIG_API_KEY."
+            )
+
+        self.base_url = (
+            base_url or os.environ.get("SRIG_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"X-API-Key": self.api_key},
+            timeout=timeout,
+        )
+
+    # -- public helpers -------------------------------------------------------
+
+    def boards(self) -> list[dict[str, Any]]:
+        """List available board types with real-time availability."""
+        resp = self._http.get("/v1/boards")
+        _check(resp)
+        return resp.json()
+
+    @contextmanager
+    def session(
+        self,
+        board: str,
+        base_image_id: str | None = None,
+    ) -> Generator[Session, None, None]:
+        """Create a hardware session and yield it as a context manager.
+
+        The session is automatically ended when the block exits.
+
+        Args:
+            board: Board type identifier (e.g. ``"esp32s3"``).
+            base_image_id: Optional base image to pre-flash.
+        """
+        body: dict[str, Any] = {"board_type": board}
+        if base_image_id:
+            body["base_image_id"] = base_image_id
+
+        resp = self._http.post("/v1/sessions", json=body)
+        _check(resp)
+        data = resp.json()
+        session_id: str = data["id"]
+
+        session = Session(
+            session_id=session_id,
+            data=data,
+            http=self._http,
+            base_url=self.base_url,
+            api_key=self.api_key,
+        )
+        try:
+            yield session
+        finally:
+            session.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+
+def _check(resp: httpx.Response) -> None:
+    """Raise a typed exception for non-2xx responses."""
+    if resp.is_success:
+        return
+    try:
+        detail = resp.json().get("error", resp.text)
+    except Exception:
+        detail = resp.text
+    if resp.status_code in (401, 403):
+        raise AuthError(detail)
+    raise SessionError(f"[{resp.status_code}] {detail}")

siliconrig-0.2.0/src/siliconrig/exceptions.py

@@ -0,0 +1,21 @@
+"""siliconrig exception hierarchy."""
+
+
+class SiliconrigError(Exception):
+    """Base exception for all siliconrig errors."""
+
+
+class AuthError(SiliconrigError):
+    """Authentication or authorization failure."""
+
+
+class SessionError(SiliconrigError):
+    """Session lifecycle error (create, end, not found)."""
+
+
+class FlashError(SiliconrigError):
+    """Firmware flashing failed."""
+
+
+class SerialTimeout(SiliconrigError):
+    """Serial read/expect timed out."""

siliconrig-0.2.0/src/siliconrig/plugin.py

@@ -0,0 +1,63 @@
+"""pytest plugin — auto-registered via the ``pytest11`` entry point.
+
+Provides the ``siliconrig_board`` fixture and CLI options.
+"""
+
+import pytest
+
+from siliconrig.board import Board
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("siliconrig", "siliconrig hardware-in-the-loop testing")
+    group.addoption(
+        "--siliconrig-board",
+        dest="siliconrig_board",
+        default=None,
+        help="Board type to use for siliconrig sessions (e.g. esp32s3).",
+    )
+    group.addoption(
+        "--siliconrig-firmware",
+        dest="siliconrig_firmware",
+        default=None,
+        help="Path to firmware binary to flash before tests.",
+    )
+    group.addoption(
+        "--siliconrig-api-key",
+        dest="siliconrig_api_key",
+        default=None,
+        help="API key (overrides SRIG_API_KEY env var).",
+    )
+    group.addoption(
+        "--siliconrig-base-url",
+        dest="siliconrig_base_url",
+        default=None,
+        help="Coordinator base URL (overrides SRIG_BASE_URL env var).",
+    )
+
+
+@pytest.fixture(scope="session")
+def siliconrig_board(request: pytest.FixtureRequest):
+    """Session-scoped fixture that provides a flashed, ready-to-use board.
+
+    Configure via CLI options or environment variables::
+
+        pytest --siliconrig-board esp32s3 --siliconrig-firmware build/app.bin
+
+    Or use the ``Board`` class directly in your own fixtures for more control.
+    """
+    board_type = request.config.getoption("siliconrig_board")
+    if board_type is None:
+        pytest.skip("No --siliconrig-board specified; skipping HIL tests")
+
+    firmware = request.config.getoption("siliconrig_firmware")
+    api_key = request.config.getoption("siliconrig_api_key")
+    base_url = request.config.getoption("siliconrig_base_url")
+
+    with Board(
+        board_type,
+        firmware=firmware,
+        api_key=api_key,
+        base_url=base_url,
+    ) as board:
+        yield board

siliconrig-0.2.0/src/siliconrig/serial.py

@@ -0,0 +1,141 @@
+"""Serial interface over WebSocket."""
+
+import base64
+import json
+import re
+import threading
+import time
+from collections import deque
+
+import websockets.sync.client as ws_sync
+
+from siliconrig.exceptions import SerialTimeout
+
+_WS_CLOSE_TIMEOUT = 3
+
+
+class Serial:
+    """WebSocket-backed serial console for a siliconrig session.
+
+    Connects to the coordinator's serial proxy and exposes a synchronous
+    send/read/expect API suitable for pytest tests.
+    """
+
+    def __init__(self, ws_url: str, api_key: str) -> None:
+        self._buf: deque[str] = deque()
+        self._lock = threading.Lock()
+        self._closed = False
+        self._error: Exception | None = None
+
+        headers = {"X-API-Key": api_key}
+        self._ws = ws_sync.connect(ws_url, additional_headers=headers)
+
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader.start()
+
+    # -- write ----------------------------------------------------------------
+
+    def send(self, data: str) -> None:
+        """Send a string to the board's UART."""
+        msg = json.dumps({"type": "serial_data", "data": data})
+        self._ws.send(msg)
+
+    # -- read -----------------------------------------------------------------
+
+    def read(self, n: int = 4096, timeout: float = 5.0) -> str:
+        """Read up to *n* characters from the receive buffer.
+
+        Blocks until at least one character is available or *timeout* expires.
+        """
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            with self._lock:
+                if self._buf:
+                    text = "".join(self._buf)
+                    self._buf.clear()
+                    return text[:n]
+            time.sleep(0.05)
+        raise SerialTimeout(f"No data received within {timeout}s")
+
+    def read_until(self, pattern: str, timeout: float = 10.0) -> str:
+        """Read until *pattern* appears in the accumulated output.
+
+        Returns everything up to and including the matched text.
+        Data after the match is preserved in the buffer for subsequent reads.
+        """
+        collected: list[str] = []
+        deadline = time.monotonic() + timeout
+        regex = re.compile(re.escape(pattern))
+
+        while time.monotonic() < deadline:
+            with self._lock:
+                if self._buf:
+                    collected.append("".join(self._buf))
+                    self._buf.clear()
+
+            full = "".join(collected)
+            m = regex.search(full)
+            if m:
+                # Put unmatched remainder back into the buffer.
+                remainder = full[m.end():]
+                if remainder:
+                    with self._lock:
+                        self._buf.appendleft(remainder)
+                return full[: m.end()]
+            time.sleep(0.05)
+
+        full = "".join(collected)
+        extra = ""
+        if self._error is not None:
+            extra = f" (reader thread died: {self._error})"
+        raise SerialTimeout(
+            f"Pattern {pattern!r} not found within {timeout}s.{extra} "
+            f"Received so far: {full[-200:]!r}"
+        )
+
+    def expect(self, pattern: str, timeout: float = 10.0) -> str:
+        """Assert that *pattern* appears within *timeout* seconds.
+
+        Returns the matched output (same as ``read_until``).
+        Raises ``SerialTimeout`` on failure.
+        """
+        return self.read_until(pattern, timeout=timeout)
+
+    def flush(self) -> None:
+        """Discard all buffered receive data."""
+        with self._lock:
+            self._buf.clear()
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def close(self) -> None:
+        """Disconnect the WebSocket."""
+        self._closed = True
+        try:
+            self._ws.close(timeout=_WS_CLOSE_TIMEOUT)
+        except Exception:
+            pass
+
+    # -- internal -------------------------------------------------------------
+
+    def _read_loop(self) -> None:
+        """Background thread: read WebSocket frames into the buffer."""
+        try:
+            for raw in self._ws:
+                if self._closed:
+                    return
+                try:
+                    msg = json.loads(raw)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+                if msg.get("type") == "serial_data":
+                    raw_data = msg.get("data", "")
+                    try:
+                        text = base64.b64decode(raw_data).decode("utf-8", errors="replace")
+                    except Exception:
+                        text = raw_data
+                    with self._lock:
+                        self._buf.append(text)
+        except Exception as exc:
+            if not self._closed:
+                self._error = exc

siliconrig-0.2.0/src/siliconrig/session.py

@@ -0,0 +1,123 @@
+"""Hardware session wrapper."""
+
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from siliconrig.exceptions import FlashError, SessionError
+from siliconrig.serial import Serial
+
+_FLASH_POLL_INTERVAL = 0.1
+_FLASH_DEFAULT_TIMEOUT = 120.0
+
+
+class Session:
+    """A live session on a remote board.
+
+    Created via :meth:`Client.session` — not instantiated directly.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        data: dict[str, Any],
+        http: httpx.Client,
+        base_url: str,
+        api_key: str,
+    ) -> None:
+        self.id = session_id
+        self._data = data
+        self._http = http
+        self._api_key = api_key
+        self._closed = False
+
+        ws_scheme = "wss" if base_url.startswith("https") else "ws"
+        ws_base = base_url.replace("https://", "").replace("http://", "")
+        ws_url = f"{ws_scheme}://{ws_base}/v1/sessions/{session_id}/serial"
+
+        self.serial = Serial(ws_url, api_key)
+
+    # -- firmware -------------------------------------------------------------
+
+    def flash(
+        self,
+        firmware: str | Path,
+        timeout: float = _FLASH_DEFAULT_TIMEOUT,
+    ) -> None:
+        """Upload and flash a firmware binary.
+
+        Args:
+            firmware: Path to the ``.bin`` file (max 4 MB).
+            timeout: Seconds to wait for flashing to complete.
+
+        Raises:
+            FlashError: If flashing fails or times out.
+            FileNotFoundError: If the firmware file doesn't exist.
+        """
+        path = Path(firmware)
+        if not path.exists():
+            raise FileNotFoundError(f"Firmware not found: {path}")
+
+        with open(path, "rb") as f:
+            resp = self._http.post(
+                f"/v1/sessions/{self.id}/flash",
+                files={"firmware": (path.name, f, "application/octet-stream")},
+                timeout=timeout,
+            )
+
+        if not resp.is_success:
+            try:
+                detail = resp.json().get("error", resp.text)
+            except Exception:
+                detail = resp.text
+            raise FlashError(f"Flash upload failed: {detail}")
+
+        self._wait_flash(timeout)
+
+    # -- power ----------------------------------------------------------------
+
+    def reset(self) -> None:
+        """Power-cycle the board via USB hub port control."""
+        resp = self._http.post(f"/v1/sessions/{self.id}/power-cycle")
+        if not resp.is_success:
+            raise SessionError(f"Power cycle failed: {resp.text}")
+
+    # -- info -----------------------------------------------------------------
+
+    def info(self) -> dict[str, Any]:
+        """Fetch current session details from the coordinator."""
+        resp = self._http.get(f"/v1/sessions/{self.id}")
+        if not resp.is_success:
+            raise SessionError(f"Failed to get session info: {resp.text}")
+        self._data = resp.json()
+        return self._data
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def close(self) -> None:
+        """End the session and disconnect serial."""
+        if self._closed:
+            return
+        self._closed = True
+        self.serial.close()
+        try:
+            self._http.delete(f"/v1/sessions/{self.id}")
+        except Exception:
+            pass
+
+    # -- internal -------------------------------------------------------------
+
+    def _wait_flash(self, timeout: float) -> None:
+        """Poll session info until the board is done flashing."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            data = self.info()
+            state = data.get("state", "")
+            if state in ("idle", "active"):
+                return
+            if state in ("error", "ended"):
+                raise FlashError(f"Flash failed: {data.get('end_reason', 'unknown')}")
+            time.sleep(_FLASH_POLL_INTERVAL)
+        raise FlashError(f"Flash did not complete within {timeout}s")

siliconrig-0.2.0/tests/conftest.py

@@ -0,0 +1,55 @@
+"""Shared test fixtures."""
+
+import json
+import threading
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+class FakeWebSocket:
+    """Simulates a WebSocket connection for serial testing."""
+
+    def __init__(self):
+        self._inbox: list[str] = []
+        self._sent: list[str] = []
+        self._closed = False
+        self._lock = threading.Lock()
+
+    def inject(self, msg_type: str, data: str) -> None:
+        with self._lock:
+            self._inbox.append(json.dumps({"type": msg_type, "data": data}))
+
+    def send(self, data: str) -> None:
+        self._sent.append(data)
+
+    def close(self, timeout: float = 3) -> None:
+        self._closed = True
+
+    def __iter__(self):
+        while not self._closed:
+            with self._lock:
+                if self._inbox:
+                    yield self._inbox.pop(0)
+
+
+@pytest.fixture
+def fake_ws():
+    return FakeWebSocket()
+
+
+@pytest.fixture
+def mock_http():
+    """A mocked httpx.Client that returns canned responses."""
+    client = MagicMock()
+
+    def make_response(status_code=200, json_data=None):
+        resp = MagicMock()
+        resp.status_code = status_code
+        resp.is_success = 200 <= status_code < 300
+        resp.json.return_value = json_data or {}
+        resp.text = json.dumps(json_data or {})
+        return resp
+
+    client._make_response = make_response
+    return client

siliconrig-0.2.0/tests/test_board.py

@@ -0,0 +1,62 @@
+"""Tests for siliconrig.Board convenience wrapper."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from siliconrig.board import Board
+
+
+class TestBoardContextManager:
+    @patch("siliconrig.board.Client")
+    def test_creates_session_and_flashes(self, MockClient):
+        mock_client = MockClient.return_value
+        mock_session = MagicMock()
+        mock_ctx = MagicMock()
+        mock_ctx.__enter__ = MagicMock(return_value=mock_session)
+        mock_ctx.__exit__ = MagicMock(return_value=False)
+        mock_client.session.return_value = mock_ctx
+
+        with Board("esp32s3", firmware="app.bin", api_key="sk_test") as b:
+            assert b.session is mock_session
+            mock_session.flash.assert_called_once_with("app.bin")
+
+        mock_client.close.assert_called_once()
+
+    @patch("siliconrig.board.Client")
+    def test_no_firmware_skips_flash(self, MockClient):
+        mock_client = MockClient.return_value
+        mock_session = MagicMock()
+        mock_ctx = MagicMock()
+        mock_ctx.__enter__ = MagicMock(return_value=mock_session)
+        mock_ctx.__exit__ = MagicMock(return_value=False)
+        mock_client.session.return_value = mock_ctx
+
+        with Board("esp32s3", api_key="sk_test") as b:
+            pass
+
+        mock_session.flash.assert_not_called()
+
+
+class TestBoardProxies:
+    @patch("siliconrig.board.Client")
+    def test_send_proxies_to_serial(self, MockClient):
+        mock_client = MockClient.return_value
+        mock_session = MagicMock()
+        mock_ctx = MagicMock()
+        mock_ctx.__enter__ = MagicMock(return_value=mock_session)
+        mock_ctx.__exit__ = MagicMock(return_value=False)
+        mock_client.session.return_value = mock_ctx
+
+        with Board("esp32s3", api_key="sk_test") as b:
+            b.send("test\n")
+            mock_session.serial.send.assert_called_with("test\n")
+
+            b.expect("OK")
+            mock_session.serial.expect.assert_called_with("OK", timeout=10.0)
+
+            b.flush()
+            mock_session.serial.flush.assert_called_once()
+
+            b.reset()
+            mock_session.reset.assert_called_once()

siliconrig-0.2.0/tests/test_client.py

@@ -0,0 +1,62 @@
+"""Tests for siliconrig.Client."""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from siliconrig.client import Client, _check
+from siliconrig.exceptions import AuthError, SessionError
+
+
+class TestClientInit:
+    def test_requires_api_key(self):
+        with patch.dict(os.environ, {}, clear=True):
+            os.environ.pop("SRIG_API_KEY", None)
+            with pytest.raises(AuthError, match="No API key"):
+                Client()
+
+    def test_reads_env_var(self):
+        with patch.dict(os.environ, {"SRIG_API_KEY": "sk_test_123"}):
+            c = Client()
+            assert c.api_key == "sk_test_123"
+            c.close()
+
+    def test_explicit_key_overrides_env(self):
+        with patch.dict(os.environ, {"SRIG_API_KEY": "sk_env"}):
+            c = Client(api_key="sk_explicit")
+            assert c.api_key == "sk_explicit"
+            c.close()
+
+    def test_custom_base_url(self):
+        c = Client(api_key="sk_test", base_url="http://localhost:8080")
+        assert c.base_url == "http://localhost:8080"
+        c.close()
+
+    def test_strips_trailing_slash(self):
+        c = Client(api_key="sk_test", base_url="http://localhost:8080/")
+        assert c.base_url == "http://localhost:8080"
+        c.close()
+
+
+class TestCheck:
+    def test_success_passes(self):
+        resp = MagicMock()
+        resp.is_success = True
+        _check(resp)  # should not raise
+
+    def test_401_raises_auth_error(self):
+        resp = MagicMock()
+        resp.is_success = False
+        resp.status_code = 401
+        resp.json.return_value = {"error": "invalid key"}
+        with pytest.raises(AuthError, match="invalid key"):
+            _check(resp)
+
+    def test_500_raises_session_error(self):
+        resp = MagicMock()
+        resp.is_success = False
+        resp.status_code = 500
+        resp.json.return_value = {"error": "internal"}
+        with pytest.raises(SessionError, match="internal"):
+            _check(resp)

siliconrig-0.2.0/tests/test_serial.py

@@ -0,0 +1,77 @@
+"""Tests for siliconrig.Serial."""
+
+import json
+import threading
+import time
+from unittest.mock import patch
+
+import pytest
+
+from siliconrig.exceptions import SerialTimeout
+from siliconrig.serial import Serial
+
+
+@pytest.fixture
+def serial_conn(fake_ws):
+    with patch("siliconrig.serial.ws_sync.connect", return_value=fake_ws):
+        s = Serial("ws://localhost/serial", "sk_test")
+        yield s, fake_ws
+        s.close()
+
+
+class TestSend:
+    def test_sends_json_frame(self, serial_conn):
+        serial, ws = serial_conn
+        serial.send("hello\n")
+        sent = json.loads(ws._sent[-1])
+        assert sent == {"type": "serial_data", "data": "hello\n"}
+
+
+class TestRead:
+    def test_reads_buffered_data(self, serial_conn):
+        serial, ws = serial_conn
+        ws.inject("serial_data", "boot ok\n")
+        time.sleep(0.15)
+        result = serial.read(timeout=1)
+        assert "boot ok" in result
+
+    def test_timeout_raises(self, serial_conn):
+        serial, _ = serial_conn
+        with pytest.raises(SerialTimeout):
+            serial.read(timeout=0.2)
+
+
+class TestReadUntil:
+    def test_finds_pattern(self, serial_conn):
+        serial, ws = serial_conn
+        ws.inject("serial_data", "loading... ")
+        ws.inject("serial_data", "Ready\n")
+        time.sleep(0.15)
+        result = serial.read_until("Ready", timeout=2)
+        assert "Ready" in result
+
+    def test_timeout_shows_received(self, serial_conn):
+        serial, ws = serial_conn
+        ws.inject("serial_data", "partial")
+        time.sleep(0.15)
+        with pytest.raises(SerialTimeout, match="partial"):
+            serial.read_until("NEVER", timeout=0.3)
+
+
+class TestExpect:
+    def test_expect_is_read_until(self, serial_conn):
+        serial, ws = serial_conn
+        ws.inject("serial_data", "System ready\n")
+        time.sleep(0.15)
+        result = serial.expect("ready", timeout=2)
+        assert "ready" in result
+
+
+class TestFlush:
+    def test_clears_buffer(self, serial_conn):
+        serial, ws = serial_conn
+        ws.inject("serial_data", "noise")
+        time.sleep(0.15)
+        serial.flush()
+        with pytest.raises(SerialTimeout):
+            serial.read(timeout=0.2)