benchlab-pytools 3.0.0__py3-none-any.whl

benchlab/core/statistics.py

@@ -0,0 +1,224 @@
+"""
+Statistics Module for TUI and other tools
+
+Provides thread-safe channel statistics tracking with min/max/average
+calculations that can be used by any tool consuming telemetry data.
+"""
+
+import threading
+from collections import defaultdict
+from typing import Dict, Optional, Tuple
+
+
+def _make_stat() -> Dict[str, float]:
+    """Create a new statistics dictionary."""
+    return {'min': float('inf'), 'max': float('-inf'), 'sum': 0.0, 'count': 0}
+
+
+class ChannelStats:
+    """Thread-safe per-device, per-channel running statistics.
+
+    Tracks minimum, maximum, and average values for numeric telemetry channels
+    across multiple devices. Can be used by TUI, dashboard, or any other tool
+    that needs statistical analysis of telemetry data.
+    """
+
+    def __init__(self):
+        """Initialize statistics tracker."""
+        self._lock = threading.Lock()
+        # device -> channel -> stat dict
+        self._data: Dict[str, Dict[str, Dict[str, float]]
+                         ] = defaultdict(lambda: defaultdict(_make_stat))
+
+    def update(self, device: str, channel: str, value: float) -> None:
+        """Update statistics for a device channel.
+
+        Args:
+            device: Device identifier (UID or port)
+            channel: Channel name (e.g., 'SYS_Power', 'Chip_Temp')
+            value: Numeric value to add to statistics
+        """
+        if value is None or not isinstance(value, (int, float)):
+            return
+
+        with self._lock:
+            s = self._data[device][channel]
+            if value < s['min']:
+                s['min'] = value
+            if value > s['max']:
+                s['max'] = value
+            s['sum'] += value
+            s['count'] += 1
+
+    def get(self,
+            device: str,
+            channel: str) -> Tuple[Optional[float],
+                                   Optional[float],
+                                   Optional[float]]:
+        """Get statistics for a device channel.
+
+        Args:
+            device: Device identifier
+            channel: Channel name
+
+        Returns:
+            Tuple of (min, max, avg) or (None, None, None) if no data
+        """
+        with self._lock:
+            s = self._data[device][channel]
+            if s['count'] == 0:
+                return None, None, None
+            return s['min'], s['max'], s['sum'] / s['count']
+
+    def get_all(self,
+                device: str) -> Dict[str,
+                                     Tuple[Optional[float],
+                                           Optional[float],
+                                           Optional[float]]]:
+        """Get statistics for all channels of a device.
+
+        Args:
+            device: Device identifier
+
+        Returns:
+            Dictionary mapping channel names to (min, max, avg) tuples
+        """
+        with self._lock:
+            result = {}
+            for channel in self._data[device]:
+                s = self._data[device][channel]
+                if s['count'] == 0:
+                    result[channel] = (None, None, None)
+                else:
+                    result[channel] = (
+                        s['min'], s['max'], s['sum'] / s['count'])
+            return result
+
+    def reset(self, device: Optional[str] = None) -> None:
+        """Reset statistics for a device or all devices.
+
+        Args:
+            device: Device identifier to reset, or None to reset all devices
+        """
+        with self._lock:
+            if device is None:
+                # Reset all devices
+                self._data.clear()
+            else:
+                # Reset specific device
+                if device in self._data:
+                    self._data[device].clear()
+
+    def get_devices(self) -> list[str]:
+        """Get list of all devices with statistics.
+
+        Returns:
+            List of device identifiers with recorded statistics
+        """
+        with self._lock:
+            return list(self._data.keys())
+
+    def get_channels(self, device: str) -> list[str]:
+        """Get list of all channels for a device.
+
+        Args:
+            device: Device identifier
+
+        Returns:
+            List of channel names with recorded statistics for the device
+        """
+        with self._lock:
+            if device in self._data:
+                return list(self._data[device].keys())
+            return []
+
+    def has_data(self, device: str, channel: Optional[str] = None) -> bool:
+        """Check if statistics data exists.
+
+        Args:
+            device: Device identifier
+            channel: Optional channel name to check specifically
+
+        Returns:
+            True if statistics data exists
+        """
+        with self._lock:
+            if device not in self._data:
+                return False
+            if channel is None:
+                return bool(self._data[device])
+            return (channel in self._data[device]
+                    and self._data[device][channel]['count'] > 0)
+
+
+class StatsFormatter:
+    """Helper class for formatting statistics for display."""
+
+    @staticmethod
+    def format_stat_string(min_val: Optional[float], max_val: Optional[float],
+                           avg_val: Optional[float], decimals: int = 1,
+                           unit: str = "", width: int = 10) -> str:
+        """Format statistics as a display string.
+
+        Args:
+            min_val: Minimum value
+            max_val: Maximum value
+            avg_val: Average value
+            decimals: Number of decimal places
+            unit: Unit string (e.g., 'W', '°C', 'V')
+            width: Fixed width for each stat column
+
+        Returns:
+            Formatted string like "↓10.2W  ↑15.8W  ~13.1W"
+        """
+        if min_val is None or max_val is None or avg_val is None:
+            return ""
+
+        lo = f"↓{min_val:.{decimals}f}{unit}"
+        hi = f"↑{max_val:.{decimals}f}{unit}"
+        av = f"~{avg_val:.{decimals}f}{unit}"
+
+        return f"  {lo:<{width}} {hi:<{width}} {av:<{width}}"
+
+    @staticmethod
+    def format_compact_range(
+            min_val: Optional[float],
+            max_val: Optional[float],
+            avg_val: Optional[float],
+            decimals: int = 1,
+            unit: str = "") -> str:
+        """Format statistics as a compact range string.
+
+        Args:
+            min_val: Minimum value
+            max_val: Maximum value
+            avg_val: Average value
+            decimals: Number of decimal places
+            unit: Unit string
+
+        Returns:
+            Formatted string like "10.2-15.8 ~13.1W"
+        """
+        if min_val is None or max_val is None or avg_val is None:
+            return ""
+
+        return f"{
+            min_val:.{decimals}f}-{
+            max_val:.{decimals}f} ~{
+            avg_val:.{decimals}f}{unit}"
+
+
+# Convenience function for creating a stats callback
+def create_stats_callback(stats: ChannelStats):
+    """Create a callback function for DataSourceManager.
+
+    Args:
+        stats: ChannelStats instance to update
+
+    Returns:
+        Callback function that can be passed to DataSourceManager
+    """
+    def callback(device_uid: str, channel: str, value: float):
+        stats.update(device_uid, channel, value)
+
+    return callback

benchlab/csv_log/README.md

@@ -0,0 +1,206 @@
+# Enhanced BENCHLAB CSV Fleet Logger
+
+## Overview
+
+The Enhanced CSV Fleet Logger provides robust, lightweight telemetry logging for BENCHLAB devices with improved error handling, performance optimization, and cross-platform compatibility.
+
+### Key Improvements
+
+- **Configuration-driven**: Support for config files and environment variables
+- **Enhanced error handling**: Exponential backoff retry logic and auto-reconnection
+- **Performance optimized**: Buffered writes and async file I/O
+- **Cross-platform**: Optimized for both Windows and Linux environments
+- **Multiple formats**: Support for CSV and JSON output formats
+- **Silent operation**: Headless mode for automated deployments
+- **Connection monitoring**: Automatic reconnection for dropped devices
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Configurable operation** | File-based and environment variable configuration |
+| **Smart device discovery** | Enhanced error handling during device detection |
+| **Buffered writes** | Configurable buffer size for optimal disk I/O |
+| **Auto-reconnection** | Automatic reconnection for dropped serial connections |
+| **Multiple output formats** | CSV and JSON format support |
+| **Silent mode** | Headless operation for automated scripts |
+| **Cross-platform** | Optimized for Windows, Linux, and embedded systems |
+| **Memory efficient** | Circular buffers and automatic cleanup |
+| **Detailed logging** | Configurable log levels and structured output |
+
+---
+
+## Installation
+
+Install the tool's dependencies (from `benchlab/csv_log/requirements.txt`):
+
+```bash
+pip install -r benchlab/csv_log/requirements.txt
+```
+
+Key dependencies: `pyserial`, `benchlab-pycore`.
+
+---
+
+## Configuration
+
+### Configuration File
+
+Create a `csv_logger.config` file in your working directory. Only the settings below are actually read by `LoggerConfig`/`load_config()`; other keys are ignored:
+
+```ini
+[logger]
+interval = 1.0                    # Logging interval in seconds
+output_dir = logs                 # Output directory
+buffer_size = 100                 # Rows buffered before a batched write
+format = csv                      # Output format: csv or json (currently informational; batcher writes CSV)
+silent_mode = false                # Silent operation (also auto-selects devices)
+auto_select = false                # Auto-select all discovered devices, skip the prompt
+```
+
+### Environment Variables
+
+Override select settings with environment variables (read in `load_config()`):
+
+```bash
+export CSV_LOG_INTERVAL=0.5
+export CSV_LOG_OUTPUT_DIR=/var/log/benchlab
+export CSV_LOG_BUFFER_SIZE=200
+export CSV_LOG_SILENT=true
+export CSV_LOG_AUTO_SELECT=true
+```
+
+`BENCHLAB_AUTO_SELECT=true` is also honored by `run_enhanced_csv_logger()` (used when launched via `python -m benchlab -logfleet`) to force auto-selection.
+
+---
+
+## Usage
+
+### Command Line Interface
+
+Via the main BENCHLAB launcher (recommended):
+
+```bash
+# Basic usage with default settings (direct/serial source, 1s interval)
+python -m benchlab -logfleet
+
+# Custom interval
+python -m benchlab -logfleet -i 0.5
+
+# Choose a data source (direct | fastapi | fastapi_custom | mqtt | mqtt_custom | named_pipe | service_http)
+python -m benchlab -logfleet --source fastapi --api-url http://127.0.0.1:8000
+python -m benchlab -logfleet --source mqtt --mqtt-broker localhost --mqtt-port 1883
+```
+
+`-i`/`--interval`, `--source`, `--api-url`, `--api-port`, `--mqtt-broker`, and `--mqtt-port` are the standard `benchlab/main.py` CLI flags; the tool itself has no `-logfleet`-specific flags beyond what `main.py` exposes.
+
+Running the module standalone (bypasses the main launcher, uses its own small argparse CLI limited to `direct`/`fastapi`/`mqtt` sources):
+
+```bash
+python -m benchlab.csv_log.csv_logger_enhanced -i 0.5 -c my_config.config
+python -m benchlab.csv_log.csv_logger_enhanced --silent --auto-select
+```
+
+### Programmatic Usage
+
+```python
+from benchlab.csv_log.csv_logger_enhanced import EnhancedCSVLogger, LoggerConfig
+import types
+
+# Create configuration
+config = LoggerConfig(
+    interval=0.5,
+    output_dir="custom_logs",
+    buffer_size=50,
+    silent_mode=True,
+    auto_select=True,
+)
+
+# args mirrors the standard benchlab CLI namespace (source/api_url/mqtt_broker/mqtt_port)
+args = types.SimpleNamespace(source="direct", interval=0.5, api_url="http://127.0.0.1:8000",
+                              mqtt_broker="localhost", mqtt_port=1883)
+
+# Create and run logger (use as a context manager so stop_logging() always runs)
+with EnhancedCSVLogger(config, args=args) as logger:
+    logger.start_logging()
+```
+
+---
+
+## Output Format
+
+Rows are written as CSV via the batching logger (`benchlab/csv_log/message_batcher.py`):
+
+```
+Timestamp,uid,SYS_Power,CPU_Power,GPU_Power,Temp1,Temp2,...
+2025-10-06T10:15:01.123456,BL-1234,120,50,30,65,70,...
+2025-10-06T10:15:02.123456,BL-1234,118,49,31,65,71,...
+```
+
+The `format` config key is accepted by `LoggerConfig` but the batcher currently always writes CSV; JSON output is not implemented.
+
+---
+
+## Behavior Notes
+
+- **Buffered writes**: rows are batched (default `buffer_size = 100`) and flushed via `BatchingLogger`, with a background flush every 5 seconds and an explicit flush each polling cycle.
+- **Retry on connect**: initial connection to the data source uses `SmartRetryManager` (3 attempts, exponential backoff) — see `benchlab/csv_log/smart_retry.py`.
+- **Silent/auto-select**: `silent_mode` or `auto_select` (or `BENCHLAB_AUTO_SELECT=true`) skip the interactive device-selection prompt and log at `WARNING` level instead of `INFO`.
+- **Graceful shutdown**: Ctrl+C stops the polling loop, flushes the batcher, and disconnects the data source (`EnhancedCSVLogger.stop_logging()`).
+
+---
+
+## Troubleshooting
+
+### Device Not Detected
+```bash
+python -c "from benchlab_pycore.core import get_benchlab_ports; print(get_benchlab_ports())"
+```
+
+### Permission Errors (Linux)
+```bash
+# Add user to dialout group for serial access
+sudo usermod -a -G dialout $USER
+# Log out and back in, or restart
+```
+
+### No devices selected / logging exits immediately
+Ensure the configured `--source` (direct/fastapi/mqtt/etc.) is actually running and reachable — the logger connects via `DataSourceManager`, and a failed connection or empty device discovery causes it to log an error and stop.
+
+---
+
+## API Reference
+
+### EnhancedCSVLogger Class
+
+```python
+class EnhancedCSVLogger:
+    def __init__(self, config: LoggerConfig, args=None)
+    def start_logging(self)
+    def stop_logging(self)
+    def discover_devices(self) -> List[DeviceConfig]
+    def select_devices(self, devices: List[DeviceConfig]) -> List[DeviceConfig]
+    def create_batcher(self)
+    def log_device_data(self, uid: str) -> bool
+```
+
+### LoggerConfig Dataclass
+
+```python
+@dataclass
+class LoggerConfig:
+    interval: float = 1.0
+    output_dir: str = "logs"
+    buffer_size: int = 100
+    format: str = "csv"          # accepted, but only CSV output is implemented
+    silent_mode: bool = False
+    auto_select: bool = False
+```
+
+---
+
+## Support
+
+For issues, check the Troubleshooting section above or report bugs via GitHub issues.

benchlab/csv_log/__init__.py

@@ -0,0 +1,5 @@
+"""
+BENCHLAB Telemetry Package
+"""
+
+__version__ = "0.9.0"