benchlab-pytools 3.0.0__py3-none-any.whl

benchlab/config/schema.py

@@ -0,0 +1,138 @@
+"""
+JSON Schema and Validation for BENCHLAB Device Configuration
+
+Defines Pydantic models for type-safe configuration handling.
+"""
+
+from typing import List, Optional, Any, Dict, Literal
+from pydantic import BaseModel, Field, field_validator
+
+
+class DeviceSelector(BaseModel):
+    """Device selection criteria."""
+    type: Literal["guid", "productId", "pipeName", "port", "any"] = Field(
+        description="How to identify the device"
+    )
+    value: Optional[Any] = Field(
+        default=None,
+        description="Selector value (null for 'any')"
+    )
+
+
+class FanConfig(BaseModel):
+    """Fan configuration for a single fan channel."""
+    fanId: int = Field(ge=0, le=8, description="Fan ID (0-8)")
+    FanMode: int = Field(ge=0, le=2, description="0=Auto, 1=Fixed, 2=Manual")
+    TempSource: int = Field(ge=0, le=5, description="Temperature sensor index")
+    Temp: List[int] = Field(
+        default=[300, 600],
+        min_length=2,
+        max_length=2,
+        description="Temperature curve points (0.1°C units)"
+    )
+    Duty: List[int] = Field(
+        default=[30, 80],
+        min_length=2,
+        max_length=2,
+        description="Duty cycle at each temp point (0-100%)"
+    )
+    RampStep: int = Field(
+        ge=0,
+        le=255,
+        default=5,
+        description="Rate of change")
+    FixedDuty: int = Field(
+        ge=0,
+        le=100,
+        default=50,
+        description="Fixed duty cycle")
+    MinDuty: int = Field(ge=0, le=100, default=20, description="Minimum duty")
+    MaxDuty: int = Field(ge=0, le=100, default=100, description="Maximum duty")
+    FanStop: int = Field(
+        ge=0,
+        le=1,
+        default=0,
+        description="0=disabled, 1=enabled")
+
+    @field_validator('Duty')
+    @classmethod
+    def validate_duty(cls, v):
+        for duty in v:
+            if not 0 <= duty <= 100:
+                raise ValueError(f"Duty values must be 0-100, got {duty}")
+        return v
+
+
+class FanProfile(BaseModel):
+    """Fan profile containing multiple fan configurations."""
+    profileId: int = Field(ge=0, le=2, description="Profile ID (0-2)")
+    fans: List[FanConfig] = Field(description="Fan configurations")
+
+
+class RGBConfig(BaseModel):
+    """RGB profile configuration."""
+    profileId: int = Field(ge=0, le=1, description="Profile ID (0-1)")
+    Mode: int = Field(ge=0, le=9, description="RGB mode")
+    Red: int = Field(ge=0, le=255, description="Red component")
+    Green: int = Field(ge=0, le=255, description="Green component")
+    Blue: int = Field(ge=0, le=255, description="Blue component")
+    Direction: int = Field(ge=0, le=1, description="Animation direction")
+    Speed: int = Field(ge=0, le=100, description="Animation speed")
+
+
+class DeviceConfig(BaseModel):
+    """Configuration for a single device."""
+    selector: DeviceSelector = Field(description="Device selection criteria")
+    deviceName: Optional[str] = Field(
+        default=None,
+        max_length=31,
+        description="Device friendly name"
+    )
+    fanProfiles: Optional[List[FanProfile]] = Field(
+        default=None,
+        description="Fan profile configurations"
+    )
+    rgbProfiles: Optional[List[RGBConfig]] = Field(
+        default=None,
+        description="RGB profile configurations"
+    )
+    calibration: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Calibration data"
+    )
+    saveToFlash: bool = Field(
+        default=False,
+        description="Save config to flash after applying"
+    )
+
+
+class ConfigFile(BaseModel):
+    """Root configuration file schema."""
+    version: str = Field(default="1.0", description="Schema version")
+    description: str = Field(
+        default="BENCHLAB Configuration",
+        description="Human-readable description"
+    )
+    devices: List[DeviceConfig] = Field(description="Device configurations")
+
+    @field_validator('devices')
+    @classmethod
+    def validate_devices(cls, v):
+        if not v:
+            raise ValueError("Configuration must contain at least one device")
+        return v
+
+
+def validate_config_file(config_dict: dict) -> ConfigFile:
+    """Validate a configuration dictionary against the schema.
+
+    Args:
+        config_dict: Dictionary loaded from JSON
+
+    Returns:
+        Validated ConfigFile object
+
+    Raises:
+        ValidationError: If validation fails
+    """
+    return ConfigFile(**config_dict)

benchlab/core/README.md

@@ -0,0 +1,154 @@
+# BENCHLAB Core - Shared Internals
+
+`benchlab/core/` is the internal library used by every BENCHLAB PyTools tool (TUI, FastAPI server, MQTT publisher, Link, HWiNFO export, VU dials, WigiDash, config tool). It provides the data-source abstraction that lets multiple tools consume telemetry without fighting over a serial port, plus supporting infrastructure: device lifecycle tracking, subprocess management, retry helpers, and statistics.
+
+This is a developer-facing internals doc. For CLI usage of individual tools, see their own READMEs (`benchlab/restapi/readme.md`, `benchlab/mqtt/README.md`, `benchlab/config/README.md`, `benchlab/link/README.md`).
+
+## Architecture Overview
+
+### The Problem
+
+Only one process can own a serial port at a time. If every tool connected directly via `benchlab_pycore`, only one tool could ever run at once.
+
+### The Solution
+
+A **DataSource abstraction layer** (`datasource.py`) with multiple implementations, all exposing the same interface. Tools pick a source type via `--source` and don't need to know how the data actually gets to them.
+
+## Components
+
+### 1. DataSource classes (`datasource.py`)
+
+`DataSource` is an abstract base class (`connect`, `disconnect`, `is_connected`, `list_devices`, `get_telemetry(uid)`, `get_device_info(uid)`, `source_type`). Concrete implementations:
+
+| Class | `source_type` | Description |
+|---|---|---|
+| `DirectDataSource` | `direct` | Connects directly to the serial port via `benchlab_pycore`. Runs its own background polling thread. Exclusive port access — only one tool. |
+| `FastAPIDataSource` | `fastapi` / `fastapi_custom` | HTTP client for the `benchlab.restapi` server. Polls `/health`, `/devices`, `/device/{uid}/telemetry`, `/device/{uid}/info` via `requests`. |
+| `MQTTDataSource` | `mqtt` / `mqtt_custom` | Subscribes to `<topic_prefix>/+/telemetry` and `<topic_prefix>/+/info` on an MQTT broker via `paho-mqtt`. Resolves `MQTT_PROTOCOL` (v3.1 / v3.1.1 / v5) via the module-level `resolve_mqtt_protocol()` helper. |
+| `NamedPipeDataSource` | `named_pipe` | Windows-only. Talks to the C# BENCHLAB Windows service over named pipes (`BenchlabDiscovery` for device listing, per-device `BenchlabSensorPipe_XX_YYY` pipes for telemetry). Normalizes the C# service's `ShortName`-keyed sensor payloads into the same flat key names Python tools expect, via the module-level `_normalise_cs_telemetry()` helper. |
+| `ServiceHttpDataSource` | `service_http` | REST client for the C# BENCHLAB service's HTTP API (default `http://localhost:8585`). Thin client only — does not start/manage the service. Same telemetry normalization as `NamedPipeDataSource`. |
+
+Each implementation validates its constructor kwargs through a Pydantic model in `config.py` (`SerialConfig`, `FastAPIConfig`, `MQTTConfig`, `NamedPipeConfig`, `ServiceHttpConfig`).
+
+The `create_datasource(source_type, **kwargs)` factory function builds the right class:
+
+```python
+from benchlab.core import create_datasource
+
+datasource = create_datasource('fastapi', base_url='http://127.0.0.1:8000')
+datasource = create_datasource('direct', port='COM3')
+datasource = create_datasource('mqtt', broker='localhost', port=1883)
+
+datasource.connect()
+devices = datasource.list_devices()
+telemetry = datasource.get_telemetry(uid)
+device_info = datasource.get_device_info(uid)
+datasource.disconnect()
+```
+
+### 2. DataSourceManager (`datasource_manager.py`)
+
+Wraps any `DataSource` with a consistent, higher-level API used by tools (TUI, Link, etc.): connection management, a background polling thread, device selection, and a single `snapshot()` call for UI/consumer code.
+
+```python
+from benchlab.core.datasource_manager import DataSourceManager
+
+mgr = DataSourceManager(source_type='fastapi', base_url='http://127.0.0.1:8000')
+mgr.connect()
+mgr.select_device(uid)
+snap = mgr.snapshot()
+# snap: connected, source_type, source_desc, port, uid, device_info,
+#       sensor_data, connection_time, last_error, all_devices, all_telemetry
+```
+
+Also accepts an optional `stats_callback(uid, channel, value)` invoked on every changed numeric telemetry value, typically wired to a `ChannelStats` instance (see below).
+
+### 3. DeviceRegistry (`device_registry.py`)
+
+Thread-safe singleton (`DeviceRegistry.get_instance()`) that is the single source of truth for "which devices exist right now." Exactly one component per process should own registration — e.g. the FastAPI server registers/unregisters devices as its reader threads start and stop. Other tools only observe via `get_devices()`, `get_device(uid)`, `has_device(uid)`, or subscribe to `on_connect(callback)` / `on_disconnect(callback)` events. `update_telemetry(uid)` stamps a device's `last_telemetry` time.
+
+### 4. ProcessManager (`process_manager.py`)
+
+Thread-safe singleton (`ProcessManager.get_instance()`) for starting/stopping infrastructure subprocesses (e.g. a spawned FastAPI server or MQTT publisher process) with health checks:
+
+```python
+pm = ProcessManager.get_instance()
+pm.start_service(
+    name="fastapi",
+    cmd=["python", "-m", "benchlab", "-fastapi"],
+    health_check=lambda: ping_http("http://127.0.0.1:8000/health"),
+    timeout=20,
+)
+pm.stop_service("fastapi")
+pm.shutdown_all()
+```
+
+Redirects each service's stdout/stderr to `logs/svc_<name>_stdout.log` / `_stderr.log`. Stopping tries graceful termination (SIGTERM / `taskkill`) first, then force-kills after a timeout.
+
+### 5. InfrastructureManager (`infrastructure.py`)
+
+Higher-level, non-singleton orchestrator used by the multi-tool launcher path: starts a FastAPI server as a `uvicorn` subprocess (`start_fastapi`) or an MQTT publisher as a background thread (`start_mqtt_publisher`), detecting if a compatible service is already listening on the target port before starting a new one. `start_all(tools)` / `stop_all()` take a list of tool configs and start only what's needed. Usable as a context manager.
+
+### 6. Discovery (`discovery.py`)
+
+`discover_devices()` — the canonical way to enumerate connected BENCHLAB devices over direct serial. Uses `benchlab_pycore.core.get_benchlab_ports()` to find candidate ports, opens each, reads UID/firmware/product ID, and returns `{"uid", "port", "fw", "variant"}` dicts (`variant` is `"ORIGINAL"` or `"BL2"`). Wrapped in the `retry` decorator (3 attempts, exponential backoff).
+
+### 7. Retry (`retry.py`)
+
+`RetryPolicy` (dataclass: `max_retries`, `backoff_factor`, `base_delay`, `allowed_exceptions`) plus a `retry(policy)` decorator that retries a wrapped callable with exponential backoff, logging each attempt. Used throughout `datasource.py` and `discovery.py` for connection attempts.
+
+### 8. Shared serial (`shared_serial.py`)
+
+`open_serial_connection(port)` — the one place that actually calls `serial.Serial(port, 115200, timeout=1)`; returns `None` instead of raising on failure. All direct-serial code paths (`DirectDataSource`, `discovery.py`, `telemetry_api.py`) use this instead of talking to `pyserial` directly, so the "None on failure" contract is consistent everywhere.
+
+Also provides `SharedSerialManager`, a singleton connection pool keyed by port with reference counting (`acquire_connection` / `release_connection`), so multiple in-process consumers can share one open port instead of each opening their own handle. `SharedConnection` is the context-manager wrapper returned by `acquire_connection`.
+
+### 9. Statistics (`statistics.py`)
+
+`ChannelStats` — thread-safe per-device, per-channel running min/max/average tracker (`update`, `get`, `get_all`, `reset`, `get_devices`, `get_channels`, `has_data`). `StatsFormatter` provides display helpers (`format_stat_string`, `format_compact_range`). `create_stats_callback(stats)` builds a `(uid, channel, value) -> None` callback suitable for `DataSourceManager(stats_callback=...)`.
+
+### 10. Config models (`config.py`)
+
+Pydantic models validating each DataSource's constructor kwargs: `SerialConfig`, `FastAPIConfig` (normalizes `base_url` to include a scheme and strips trailing slash), `MQTTConfig`, `NamedPipeConfig`, `ServiceHttpConfig`.
+
+## Package exports (`benchlab/core/__init__.py`)
+
+```python
+from benchlab.core import (
+    DataSource, DirectDataSource, FastAPIDataSource, MQTTDataSource, create_datasource,
+    DataSourceManager,
+    ChannelStats, StatsFormatter, create_stats_callback,
+    DeviceRegistry, DeviceInfo,
+    ProcessManager, ManagedProcess,
+    BENCHLAB_ORIGINAL_PRODUCT_ID, BENCHLAB_BL2_PRODUCT_ID,
+)
+```
+
+`NamedPipeDataSource` and `ServiceHttpDataSource` live in `datasource.py` but aren't re-exported from `__init__.py`; import them directly from `benchlab.core.datasource` if needed. `BENCHLAB_ORIGINAL_PRODUCT_ID` / `BENCHLAB_BL2_PRODUCT_ID` are re-exported from `benchlab_pycore` (with a fallback to hardcoded `0x10`/`0x11` if pycore isn't installed) so tools can detect device variant without importing pycore directly.
+
+## How tools use this
+
+- **`benchlab/main.py`** resolves `--source` into environment variables via `_setup_source_from_args()` and calls `check_and_setup_source()` (in `benchlab/sources.py`) to start/verify the chosen source before launching a tool.
+- **`benchlab/restapi/telemetry_api.py`** is a *producer*: it owns the serial port directly, registers devices in `DeviceRegistry`, and serves `DirectDataSource`-equivalent data to `FastAPIDataSource` clients.
+- **`benchlab/mqtt/mqtt_publisher.py`** is also a producer: reads sensors directly and publishes to an MQTT broker for `MQTTDataSource` clients.
+- **`benchlab/link/link_main.py`** is a consumer: uses `DataSourceManager` against any local source (direct/fastapi/mqtt) and republishes telemetry to a remote/cloud MQTT broker.
+- **`benchlab/tui/`**, **VU dials**, **WigiDash**, **HWiNFO export**, **CSV logger** are consumers via `DataSourceManager` or `create_datasource` directly.
+- The **config tool** (`benchlab/config/`) does not use the DataSource abstraction — it has its own direct/named-pipe client layer (`config_client.py`) for read/write configuration operations, since DataSource is read-only telemetry.
+
+## Data Source Comparison
+
+| Source | Use case | Pros | Cons |
+|---|---|---|---|
+| `direct` | Single tool, lowest latency | No overhead, no extra process | Exclusive port access, only one tool |
+| `fastapi` / `fastapi_custom` | Multiple tools, remote access | HTTP-based, firewall-friendly, multi-client | Small latency overhead, requires a running server |
+| `mqtt` / `mqtt_custom` | Distributed/IoT integration | Pub/sub, works with existing MQTT infra | Requires a broker, more moving parts |
+| `named_pipe` | Windows, alongside the C# BENCHLAB service | Multiple tools, no direct serial management | Windows only, requires the service + pywin32 |
+| `service_http` | Windows, alongside the C# BENCHLAB service | HTTP-based, multi-client | Windows-oriented, requires the service running |
+
+## See Also
+
+- [BENCHLAB PyTools Documentation](../../README.md) - Main PyTools documentation
+- [FastAPI Telemetry Server README](../restapi/readme.md)
+- [MQTT Publisher README](../mqtt/README.md)
+- [Config Tool README](../config/README.md)
+- [Link README](../link/README.md)

benchlab/core/__init__.py

@@ -0,0 +1,78 @@
+"""
+BenchLab Core - Infrastructure layer
+
+Provides:
+- DataSource abstraction for telemetry consumption (direct / FastAPI / MQTT)
+- DataSourceManager for unified datasource management with statistics
+- DeviceRegistry singleton for device lifecycle tracking
+- ProcessManager singleton for infrastructure service management
+- ChannelStats for thread-safe telemetry statistics tracking
+- InfrastructureManager for higher-level orchestration
+
+PyCore v0.3.0 Multi-Variant Support:
+- ORIGINAL (0x10): 11 power sensors, 4 temperature sensors
+- BL2 / BENCHLAB 2 (0x11): 23 power sensors, 8 temperature sensors
+"""
+
+import logging
+
+from benchlab.core.datasource import (
+    DataSource,
+    DirectDataSource,
+    FastAPIDataSource,
+    MQTTDataSource,
+    create_datasource,
+)
+from benchlab.core.datasource_manager import DataSourceManager
+from benchlab.core.device_registry import DeviceRegistry, DeviceInfo
+from benchlab.core.process_manager import ProcessManager, ManagedProcess
+from benchlab.core.statistics import (
+    ChannelStats,
+    StatsFormatter,
+    create_stats_callback,
+)
+
+logger = logging.getLogger("benchlab.core")
+
+# PyCore variant constants for tools that need to detect device capabilities
+# Import from pycore to make them easily accessible to tools.
+# PyCore >=0.4.1 renamed BENCHLAB_CFE_PRODUCT_ID to BENCHLAB_BL2_PRODUCT_ID
+# (the "CFE" SKU is now marketed as BENCHLAB 2); fall back to the old name
+# for older pycore installs.
+try:
+    from benchlab_pycore.core import BENCHLAB_ORIGINAL_PRODUCT_ID
+    try:
+        from benchlab_pycore.core import BENCHLAB_BL2_PRODUCT_ID
+    except ImportError:
+        from benchlab_pycore.core import (
+            BENCHLAB_CFE_PRODUCT_ID as BENCHLAB_BL2_PRODUCT_ID)
+except ImportError:
+    logger.warning(
+        "benchlab_pycore not installed; using fallback product ID constants")
+    BENCHLAB_ORIGINAL_PRODUCT_ID = 0x10
+    BENCHLAB_BL2_PRODUCT_ID = 0x11
+
+__version__ = "2.0.0"
+
+__all__ = [
+    # DataSource layer
+    "DataSource",
+    "DirectDataSource",
+    "FastAPIDataSource",
+    "MQTTDataSource",
+    "create_datasource",
+    # Unified datasource management
+    "DataSourceManager",
+    # Statistics tracking
+    "ChannelStats",
+    "StatsFormatter",
+    "create_stats_callback",
+    # Device and process management
+    "DeviceRegistry",
+    "DeviceInfo",
+    "ProcessManager",
+    "ManagedProcess",
+    # PyCore v0.3.0 variant constants
+    "BENCHLAB_ORIGINAL_PRODUCT_ID",
+    "BENCHLAB_BL2_PRODUCT_ID",
+]

benchlab/core/config.py

@@ -0,0 +1,145 @@
+"""Configuration models for Benchlab data sources.
+
+This module defines Pydantic ``BaseModel`` classes that validate the
+configuration parameters required by each concrete ``DataSource``
+implementation.  Using a strict schema helps catch mis-configurations
+early (e.g. missing serial port, invalid MQTT broker address) and makes
+the library easier to use from external tools.
+"""
+
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel, Field, field_validator
+
+
+class SerialConfig(BaseModel):
+    """Configuration for :class:`DirectDataSource`.
+
+    Attributes
+    ----------
+    port: Optional[str]
+        The serial port to connect to. ``None`` triggers auto-detection.
+    poll_interval: float
+        Seconds between successive sensor reads. Must be positive.
+    """
+
+    port: Optional[str] = None
+    poll_interval: float = Field(
+        default=1.0,
+        gt=0,
+        description="Polling interval in seconds")
+
+
+class FastAPIConfig(BaseModel):
+    """Configuration for :class:`FastAPIDataSource`.
+
+    Attributes
+    ----------
+    base_url: str
+        Base URL of the FastAPI server (e.g. ``http://127.0.0.1:8000``).
+    timeout: float
+        HTTP request timeout in seconds. Must be positive.
+    """
+
+    base_url: str = Field(..., description="Base URL of the FastAPI server")
+    timeout: float = Field(
+        default=5.0,
+        gt=0,
+        description="Request timeout in seconds")
+
+    @field_validator("base_url")
+    @classmethod
+    def _validate_base_url(cls, v: str) -> str:
+        """Ensure base_url has a protocol prefix and no trailing slash."""
+        v = v.strip()
+        if not v.startswith(('http://', 'https://')):
+            v = f"http://{v}"
+        return v.rstrip('/')
+
+
+class MQTTConfig(BaseModel):
+    """Configuration for :class:`MQTTDataSource`.
+
+    Attributes
+    ----------
+    broker: str
+        Hostname of the MQTT broker.
+    port: int
+        Network port of the broker (default 1883).
+    topic_prefix: str
+        Prefix used for all Benchlab topics.
+    timeout: float
+        Connection timeout in seconds.
+    """
+
+    broker: str = Field(
+        default="localhost",
+        description="MQTT broker hostname")
+    port: int = Field(default=1883, ge=1, le=65535, description="Broker port")
+    topic_prefix: str = Field(
+        default="benchlab",
+        description="Base topic prefix")
+    timeout: float = Field(
+        default=5.0,
+        gt=0,
+        description="Connection timeout in seconds")
+
+
+class NamedPipeConfig(BaseModel):
+    """Configuration for :class:`NamedPipeDataSource`.
+
+    Windows-only. Connects to the C# BenchLab Windows service via
+    named pipes (BenchlabDiscovery + per-device BenchlabSensorPipe_XX_YYY).
+
+    Attributes
+    ----------
+    timeout: float
+        Seconds to wait for a pipe connection before giving up.
+    poll_interval: float
+        Seconds between successive sensor reads.
+    """
+
+    timeout: float = Field(
+        default=5.0,
+        gt=0,
+        description="Pipe connection timeout in seconds")
+    poll_interval: float = Field(
+        default=1.0,
+        gt=0,
+        description="Polling interval in seconds")
+
+
+class ServiceHttpConfig(BaseModel):
+    """Configuration for :class:`ServiceHttpDataSource`.
+
+    Connects to the C# BenchLab service REST HTTP API.
+    The service is auto-detected at port 8585 by default.
+
+    Attributes
+    ----------
+    base_url: str
+        Base URL of the C# BenchLab service
+        (e.g. ``http://localhost:8585``).
+    timeout: float
+        HTTP request timeout in seconds. Must be positive.
+    poll_interval: float
+        Seconds between successive telemetry polls.
+    """
+
+    base_url: str = Field(
+        default="http://localhost:8585",
+        description="Base URL of the C# BenchLab service HTTP API",
+    )
+    timeout: float = Field(
+        default=5.0,
+        gt=0,
+        description="Request timeout in seconds")
+    poll_interval: float = Field(
+        default=1.0,
+        gt=0,
+        description="Polling interval in seconds")
+
+    @field_validator("base_url")
+    @classmethod
+    def _strip_trailing_slash(cls, v: str) -> str:
+        return v.rstrip('/')