benchlab-pytools 3.0.0__py3-none-any.whl

benchlab/wigidash/wigidash_usb.py

@@ -0,0 +1,247 @@
+# wigidash_usb.py
+
+import glob
+import os
+import re
+import sys
+import usb.core
+import usb.util
+
+from benchlab.wigidash.benchlab_utils import get_logger
+
+is_linux = sys.platform.startswith("linux")
+is_windows = sys.platform.startswith("win")
+
+logger = get_logger("WigidashUsb")
+
+_usb_backend = None
+if is_windows:
+    try:
+        import libusb_package
+        _usb_backend = libusb_package.get_libusb1_backend()
+        logger.debug("Using bundled libusb-package backend for pyusb")
+    except Exception as e:
+        # Fall back to pyusb's normal backend discovery (e.g. a system-wide
+        # libusb-1.0.dll on PATH) if libusb-package isn't installed/usable.
+        logger.debug(
+            "libusb-package backend unavailable, falling back to "
+            f"default discovery: {e}")
+
+_PERMISSION_ERROR_SIGNALS = (
+    "access denied",
+    "insufficient permissions",
+    "errno 13",
+    "operation not permitted",
+    "permission denied",
+)
+
+_UDEV_RULES_DIRS = (
+    "/etc/udev/rules.d",
+    "/usr/lib/udev/rules.d",
+    "/lib/udev/rules.d")
+
+
+def _udev_rule_hint(vendor_id, product_id):
+    """Return the udev rule text + setup steps for granting non-root
+    USB access."""
+    return (
+        f'Create /etc/udev/rules.d/99-wigidash.rules with:\n'
+        f'  SUBSYSTEM=="usb", ATTR{{idVendor}}=="{vendor_id:04x}", '
+        f'ATTR{{idProduct}}=="{product_id:04x}", TAG+="uaccess"\n'
+        "Then run: sudo udevadm control --reload-rules "
+        "&& sudo udevadm trigger"
+    )
+
+
+def _udev_rule_exists(vendor_id, product_id, rules_dirs=_UDEV_RULES_DIRS):
+    """Best-effort scan of udev rule files for one referencing this VID:PID."""
+    vid_hex = f"{vendor_id:04x}"
+    pid_hex = f"{product_id:04x}"
+    pattern = re.compile(
+        rf'idVendor.{{0,5}}{vid_hex}.{{0,80}}idProduct.{{0,5}}{pid_hex}'
+        rf'|idProduct.{{0,5}}{pid_hex}.{{0,80}}idVendor.{{0,5}}{vid_hex}',
+        re.IGNORECASE,
+    )
+    for rules_dir in rules_dirs:
+        for path in glob.glob(os.path.join(rules_dir, "*.rules")):
+            try:
+                with open(path, "r", errors="ignore") as f:
+                    if pattern.search(f.read()):
+                        return True
+            except OSError:
+                continue
+    return False
+
+
+def check_linux_usb_permissions(vendor_id=0x28DA, product_id=0xEF01):
+    """
+    Best-effort check that the current user can access the WigiDash USB
+    device without root (via an existing udev rule, or an already-accessible
+    device node). Linux-only diagnostic — never a hard gate.
+
+    Returns (True, None) if access looks fine or the check is inconclusive,
+    (False, <actionable message>) if it looks like it will fail.
+    """
+    if not is_linux:
+        return True, None
+
+    if os.geteuid() == 0:
+        return True, None
+
+    if _udev_rule_exists(vendor_id, product_id):
+        return True, None
+
+    # No matching rule found — see if a device node is nonetheless already
+    # accessible (e.g. user is in the right group via some other mechanism).
+    try:
+        found = usb.core.find(
+            idVendor=vendor_id,
+            idProduct=product_id,
+            find_all=True)
+        for dev in found:
+            bus, addr = getattr(
+                dev, "bus", None), getattr(
+                dev, "address", None)
+            if bus is None or addr is None:
+                continue
+            node = f"/dev/bus/usb/{bus:03d}/{addr:03d}"
+            if os.path.exists(node) and os.access(node, os.R_OK | os.W_OK):
+                return True, None
+    except Exception:
+        pass  # inconclusive — fall through to the actionable warning
+
+    return False, (
+        "No udev rule found granting non-root access to the WigiDash "
+        f"(VID:0x{vendor_id:04X}, PID:0x{product_id:04X}). "
+        + _udev_rule_hint(vendor_id, product_id)
+    )
+
+
+def _is_permission_error(exc) -> bool:
+    msg = str(exc).lower()
+    return any(signal in msg for signal in _PERMISSION_ERROR_SIGNALS)
+
+
+def scan_wigidash(vendor_id=0x28DA, product_id=0xEF01):
+    """
+    Scan for all connected Wigidash USB devices.
+    Returns a list of USBDevice instances (already connected).
+    """
+    if is_linux:
+        ok, hint = check_linux_usb_permissions(vendor_id, product_id)
+        if not ok:
+            logger.warning(f"WigiDash USB access may be misconfigured: {hint}")
+
+    devices = []
+    find_kwargs = {
+        "idVendor": vendor_id,
+        "idProduct": product_id,
+        "find_all": True}
+    if _usb_backend is not None:
+        find_kwargs["backend"] = _usb_backend
+    found = usb.core.find(**find_kwargs)
+    for dev in found:
+        try:
+            dev.set_configuration()
+            serial = usb.util.get_string(dev, dev.iSerialNumber)
+            usb_dev = USBDevice(vendor_id, product_id, serial=serial)
+            usb_dev.dev = dev
+            logger.info(
+                f"Wigidash device found and configured: VID:0x{
+                    vendor_id:04X}, PID:0x{
+                    product_id:04X}, Serial: {serial}")
+            devices.append(usb_dev)
+        except usb.core.USBError as e:
+            if is_linux and _is_permission_error(e):
+                logger.warning(
+                    f"Failed to configure device {dev}: {e}. "
+                    f"{_udev_rule_hint(vendor_id, product_id)}"
+                )
+            else:
+                logger.warning(f"Failed to configure device {dev}: {e}")
+    return devices
+
+
+class USBDevice:
+    def __init__(self, vendor_id, product_id, serial=None, dev_obj=None):
+        self.vendor_id = vendor_id
+        self.product_id = product_id
+        self.serial = serial
+        self.dev = dev_obj
+
+    def connect(self):
+        if self.dev is None:
+            raise RuntimeError("USB device object not attached!")
+        try:
+            self.dev.set_configuration()
+            logger.info(
+                f"USB device configured successfully, serial: {
+                    self.serial}")
+        except usb.core.USBError as e:
+            if is_linux and _is_permission_error(e):
+                logger.warning(
+                    f"USB set_configuration failed (ignored): {e}. "
+                    f"{_udev_rule_hint(self.vendor_id, self.product_id)}"
+                )
+            else:
+                logger.warning(f"USB set_configuration failed (ignored): {e}")
+
+    def disconnect(self):
+        """Cleanup USB resources"""
+        if self.dev:
+            usb.util.dispose_resources(self.dev)
+            logger.info("USB device resources disposed")
+            self.dev = None
+
+    def ctrl_transfer_in(
+            self,
+            cmd,
+            wValue=0,
+            wIndex=0,
+            length=0,
+            timeout=2000):
+        """Perform IN control transfer"""
+        try:
+            data = self.dev.ctrl_transfer(
+                0x80 | 0x21, cmd, wValue, wIndex, length, timeout=timeout)
+            logger.debug(
+                f"IN transfer cmd=0x{
+                    cmd:02X}, length={length} → {data}")
+            return data
+        except usb.core.USBError as e:
+            logger.error(f"IN transfer failed: {e}")
+            raise RuntimeError(f"IN transfer failed: {e}")
+
+    def ctrl_transfer_out(
+            self,
+            cmd,
+            wValue=0,
+            wIndex=0,
+            data=None,
+            timeout=2000):
+        """Perform OUT control transfer"""
+        try:
+            self.dev.ctrl_transfer(
+                0x00 | 0x21,
+                cmd,
+                wValue,
+                wIndex,
+                data,
+                timeout=timeout)
+            logger.debug(f"OUT transfer cmd=0x{cmd:02X}, data={data}")
+        except usb.core.USBError as e:
+            logger.error(f"OUT transfer failed: {e}")
+            raise RuntimeError(f"OUT transfer failed: {e}")
+
+    def bulk_write(self, endpoint, data, timeout=2000):
+        """Write data via bulk transfer"""
+        try:
+            written = self.dev.write(endpoint, data, timeout=timeout)
+            logger.debug(
+                f"Bulk write to ep=0x{
+                    endpoint:02X}, len={
+                    len(data)} bytes")
+            return written
+        except usb.core.USBError as e:
+            logger.error(f"Bulk write failed: {e}")
+            raise RuntimeError(f"Bulk write failed: {e}")

benchlab/wigidash/wigidash_widget.py

@@ -0,0 +1,88 @@
+# wigidash_widget.py
+
+from ctypes import Structure, c_int16, c_uint16, c_uint8, c_uint32
+
+from benchlab.wigidash.benchlab_utils import get_logger
+
+logger = get_logger("WigidashWidget")
+
+
+class WidgetConfig(Structure):
+    _pack_ = 4
+    _fields_ = [
+        ('X', c_int16),
+        ('Y', c_int16),
+        ('Width', c_int16),
+        ('Height', c_int16),
+        ('BaseClr', c_uint16),
+        ('DrawAddr', c_uint32),
+        ('DrawLock', c_uint8),
+        ('InvalidateFlag', c_uint8),
+        ('UpdateFromCache', c_uint8)
+    ]
+
+    def __str__(self):
+        return (
+            f'X: {self.X}, Y: {self.Y}, Width: {self.Width}, '
+            f'Height: {self.Height}, '
+            f'BaseClr: {self.BaseClr}, DrawAddr: {self.DrawAddr}, '
+            f'DrawLock: {self.DrawLock}, '
+            f'InvalidateFlag: {self.InvalidateFlag}, '
+            f'UpdateFromCache: {self.UpdateFromCache}')
+
+    # --- Properties with logging ---
+    @property
+    def DrawLock(self):
+        return self._DrawLock
+
+    @DrawLock.setter
+    def DrawLock(self, value):
+        logger.debug(f"DrawLock changed: {self._DrawLock} → {value}")
+        self._DrawLock = value
+
+    @property
+    def InvalidateFlag(self):
+        return self._InvalidateFlag
+
+    @InvalidateFlag.setter
+    def InvalidateFlag(self, value):
+        logger.debug(
+            f"InvalidateFlag changed: {
+                self._InvalidateFlag} → {value}")
+        self._InvalidateFlag = value
+
+    @property
+    def UpdateFromCache(self):
+        return self._UpdateFromCache
+
+    @UpdateFromCache.setter
+    def UpdateFromCache(self, value):
+        logger.debug(
+            f"UpdateFromCache changed: {
+                self._UpdateFromCache} → {value}")
+        self._UpdateFromCache = value
+
+    @classmethod
+    def create_fullscreen(cls, width=1016, height=592):
+        """Create a fullscreen widget configuration"""
+        widget = cls()
+        widget.X = 0
+        widget.Y = 0
+        widget.Width = width
+        widget.Height = height
+        widget.DrawAddr = 0
+        logger.info(f"Created fullscreen widget: {widget}")
+        return widget
+
+    @classmethod
+    def create_custom(cls, x=0, y=0, width=100, height=100, base_color=0):
+        """Create a custom positioned widget"""
+        widget = cls()
+        widget.X = x
+        widget.Y = y
+        widget.Width = width
+        widget.Height = height
+        widget.BaseClr = base_color
+        widget.DrawAddr = 0
+        logger.info(f"Created custom widget: {widget}")
+        return widget

benchlab_pytools-3.0.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: benchlab-pytools
+Version: 3.0.0
+Summary: Python control suite for BENCHLAB telemetry devices
+Project-URL: Homepage, https://benchlab.io/
+Project-URL: Repository, https://github.com/BenchLab-io/benchlab-pytools
+Project-URL: Issues, https://github.com/BenchLab-io/benchlab-pytools/issues
+Author: BENCHLAB.io
+License-Expression: MIT
+License-File: LICENSE
+Keywords: benchlab,hardware-monitoring,telemetry
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: benchlab-pycore>=0.5.1
+Requires-Dist: packaging<26.0,>=23.0
+Requires-Dist: python-dotenv<2.0,>=1.0.0
+Requires-Dist: textual<9.0,>=0.60
+Requires-Dist: windows-curses>=2.4.1; platform_system == 'Windows'
+Provides-Extra: all
+Requires-Dist: amqtt<0.13.0,>=0.12.0; extra == 'all'
+Requires-Dist: benchlab-pycore>=0.5.1; extra == 'all'
+Requires-Dist: blessed>=1.20.0; extra == 'all'
+Requires-Dist: dearpygui>=2.1.1; extra == 'all'
+Requires-Dist: fastapi==0.111.1; extra == 'all'
+Requires-Dist: libusb-package>=1.0.26.1; (sys_platform == 'win32') and extra == 'all'
+Requires-Dist: matplotlib>=3.10.7; extra == 'all'
+Requires-Dist: numpy; extra == 'all'
+Requires-Dist: numpy>=2.2.0; extra == 'all'
+Requires-Dist: paho-mqtt<3.0,>=2.0; extra == 'all'
+Requires-Dist: pillow>=10.0.0; extra == 'all'
+Requires-Dist: pillow>=11.3.0; extra == 'all'
+Requires-Dist: pydantic>=2.0.0; extra == 'all'
+Requires-Dist: pyserial>=3.5; extra == 'all'
+Requires-Dist: python-dotenv==1.1.1; extra == 'all'
+Requires-Dist: pyusb>=1.3.1; extra == 'all'
+Requires-Dist: pyyaml<7.0,>=6.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: requests>=2.31.0; extra == 'all'
+Requires-Dist: ruamel-yaml; extra == 'all'
+Requires-Dist: tornado; extra == 'all'
+Requires-Dist: uvicorn[standard]==0.24.0; extra == 'all'
+Provides-Extra: csv-log
+Requires-Dist: benchlab-pycore>=0.5.1; extra == 'csv-log'
+Requires-Dist: pyserial>=3.5; extra == 'csv-log'
+Provides-Extra: graph
+Requires-Dist: dearpygui>=2.1.1; extra == 'graph'
+Requires-Dist: pyserial>=3.5; extra == 'graph'
+Provides-Extra: hwinfo
+Requires-Dist: pyserial>=3.5; extra == 'hwinfo'
+Provides-Extra: mqtt
+Requires-Dist: amqtt<0.13.0,>=0.12.0; extra == 'mqtt'
+Requires-Dist: paho-mqtt<3.0,>=2.0; extra == 'mqtt'
+Requires-Dist: pyyaml<7.0,>=6.0; extra == 'mqtt'
+Provides-Extra: restapi
+Requires-Dist: fastapi==0.111.1; extra == 'restapi'
+Requires-Dist: pydantic>=2.0.0; extra == 'restapi'
+Requires-Dist: pyserial>=3.5; extra == 'restapi'
+Requires-Dist: python-dotenv==1.1.1; extra == 'restapi'
+Requires-Dist: uvicorn[standard]==0.24.0; extra == 'restapi'
+Provides-Extra: tui
+Requires-Dist: pyserial>=3.5; extra == 'tui'
+Provides-Extra: vu
+Requires-Dist: blessed>=1.20.0; extra == 'vu'
+Requires-Dist: numpy; extra == 'vu'
+Requires-Dist: pillow>=10.0.0; extra == 'vu'
+Requires-Dist: pyserial>=3.5; extra == 'vu'
+Requires-Dist: pyyaml>=6.0; extra == 'vu'
+Requires-Dist: requests>=2.31.0; extra == 'vu'
+Requires-Dist: ruamel-yaml; extra == 'vu'
+Requires-Dist: tornado; extra == 'vu'
+Provides-Extra: wigidash
+Requires-Dist: libusb-package>=1.0.26.1; (sys_platform == 'win32') and extra == 'wigidash'
+Requires-Dist: matplotlib>=3.10.7; extra == 'wigidash'
+Requires-Dist: numpy>=2.2.0; extra == 'wigidash'
+Requires-Dist: pillow>=11.3.0; extra == 'wigidash'
+Requires-Dist: pyserial>=3.5; extra == 'wigidash'
+Requires-Dist: pyusb>=1.3.1; extra == 'wigidash'
+Description-Content-Type: text/markdown
+
+# BENCHLAB PyTools
+
+BENCHLAB PyTools is the Python-based control suite for BENCHLAB telemetry devices. It provides a shared telemetry pipeline — device discovery, data sourcing, and process management — plus a set of consumer tools built on top of it:
+
+- **TUI** — interactive terminal dashboard for live monitoring
+- **CSV Logger** — fleet-wide telemetry logging for offline analysis
+- **FastAPI Server** — REST API for telemetry, exposed for other tools/integrations
+- **Graph** — DearPyGui-based real-time sensor graphing
+- **HWiNFO Export** — exposes sensors as HWiNFO64 custom sensors
+- **MQTT Publisher** — publishes telemetry to a local or remote MQTT broker
+- **Link** — publishes telemetry to the BENCHLAB cloud (SaaS) MQTT broker
+- **VU Dials** — analog-style VU meter dial display and configuration
+- **WigiDash** — telemetry/graph display on a G.SKILL WigiDash panel
+- **Config Tool** — import/export device configuration (fan curves, RGB, etc.) via JSON
+
+All tools share a common data-source layer, so the same telemetry can be read directly from a device, through a FastAPI server, over MQTT, or via the Windows BENCHLAB service — locally or remotely — without changing the consumer tool.
+
+---
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install -r requirements.txt
+```
+
+Each tool has its own `requirements.txt` (e.g. `benchlab/graph/requirements.txt`, `benchlab/vu/requirements.txt`). The launcher installs a tool's requirements automatically the first time it's run — you generally don't need to install them by hand.
+
+---
+
+## Usage
+
+### Interactive Menu
+
+Run with no arguments to enter the interactive launcher:
+
+```bash
+python benchlab.py
+```
+
+or equivalently:
+
+```bash
+python -m benchlab
+```
+
+The interactive menu (prompt_toolkit-based, with a plain-input fallback if `prompt_toolkit` isn't installed) lets you pick a data source and one or more tools, then launches them — installing any missing per-tool dependencies along the way.
+
+### Command-Line Flags
+
+Each tool can also be launched directly with a flag:
+
+```bash
+python -m benchlab -tui         # Interactive terminal dashboard
+python -m benchlab -logfleet    # CSV logger (no TUI)
+python -m benchlab -fastapi     # FastAPI telemetry server
+python -m benchlab -graph       # DearPyGui graph
+python -m benchlab -hwinfo      # HWiNFO custom sensor export
+python -m benchlab -mqtt [broker]  # MQTT publisher (default broker: localhost)
+python -m benchlab -link        # Publish telemetry to BENCHLAB cloud (Link)
+python -m benchlab -vu          # VU analog dials
+python -m benchlab -vuconfig    # VU dial configuration UI
+python -m benchlab -wigidash    # WigiDash display
+python -m benchlab -config ...  # Device configuration import/export
+```
+
+Running with no flags is equivalent to launching the interactive menu.
+
+### Data Sources
+
+Most tools accept `--source` to choose where telemetry comes from:
+
+| Source | Description |
+|---|---|
+| `direct` (default) | Direct USB-serial connection via `benchlab-pycore` |
+| `fastapi` | Local FastAPI server, started automatically if not already running |
+| `fastapi_custom` | Remote FastAPI server — requires `--api-url` |
+| `mqtt` | Local MQTT broker + publisher, started automatically if needed |
+| `mqtt_custom` | Remote/existing MQTT broker — requires `--mqtt-broker`/`--mqtt-port` |
+| `named_pipe` | Windows BENCHLAB service (`BL_Service`) via named pipes — Windows only |
+| `service_http` | Windows BENCHLAB service HTTP API — requires `--service-url` (default `http://localhost:8585`) |
+
+Common connection flags:
+
+```
+--source SOURCE          direct | fastapi | fastapi_custom | mqtt | mqtt_custom | named_pipe | service_http
+--api-url URL             FastAPI base URL (default: http://127.0.0.1:8000)
+--api-port PORT           FastAPI port (default: 8000)
+--mqtt-broker HOST         MQTT broker host (default: localhost)
+--mqtt-port PORT           MQTT broker port (default: 1883)
+--service-url URL          BENCHLAB Windows service HTTP API URL (default: http://localhost:8585)
+-i, --interval SECONDS     Refresh interval (default: 1.0)
+```
+
+When a source needs a background service (`fastapi`, `mqtt`), the launcher starts and health-checks it automatically, and tears it down on exit. Not every tool supports every source — the config tool, for example, only supports `direct` and `named_pipe`. See each tool's README for specifics.
+
+### Launch Profiles
+
+A named profile can bundle a data source and a set of tools to start together:
+
+```bash
+python -m benchlab --profile gskill_ctex26
+```
+
+Profiles are defined in `benchlab/tools.py` (`LAUNCH_PROFILES`). Each spawns its tools in separate terminal windows and manages them as a group.
+
+---
+
+## Architecture
+
+- `benchlab/main.py` — CLI argument parsing and mode dispatch (`launch_mode()`)
+- `benchlab/launcher.py` — in-process and multi-terminal tool launching, process lifecycle
+- `benchlab/sources.py` — data-source detection, startup, and teardown for all supported sources
+- `benchlab/tools.py` — the `CONSUMER_TOOLS` registry (tool metadata, module/function to invoke, dependencies) and `LAUNCH_PROFILES`
+- `benchlab/menu.py` / `benchlab/menu_classic.py` — interactive terminal menu (prompt_toolkit, with a plain-input fallback)
+- `benchlab/core/` — shared internals used by every tool: device discovery, the data-source abstraction, process management, retry logic. See [benchlab/core/README.md](benchlab/core/README.md).
+
+Each consumer tool lives in its own subpackage under `benchlab/` with its own README, and (where needed) its own `requirements.txt`.
+
+### Adding a New Tool
+
+1. Add an entry to `CONSUMER_TOOLS` in `benchlab/tools.py` with `name`, `flag`, `module`, `function`, and `requirements`.
+2. Implement the tool's entry function in its module, accepting an `args` namespace (see `benchlab/launcher.py::_build_args_namespace`).
+3. Add a CLI flag for it in `benchlab/main.py::get_parser()` and dispatch it in `launch_mode()`.
+4. Add a `requirements.txt` in the tool's directory if it has extra dependencies.
+5. Write a `README.md` in the tool's directory following the style of the existing ones.
+
+---
+
+## Tool Documentation
+
+- [Config Tool](benchlab/config/README.md) — device configuration import/export
+- [Core](benchlab/core/README.md) — shared internals (data sources, process management, discovery)
+- [CSV Logger](benchlab/csv_log/README.md)
+- [FastAPI Server](benchlab/restapi/readme.md)
+- [Graph](benchlab/graph/README.md)
+- [HWiNFO Export](benchlab/hwinfo/README.md)
+- [Link](benchlab/link/README.md) — publish telemetry to BENCHLAB cloud
+- [MQTT Publisher](benchlab/mqtt/README.md)
+- [TUI](benchlab/tui/README.md)
+- [VU Dials](benchlab/vu/README.md)
+- [WigiDash](benchlab/wigidash/README.md)
+
+---
+
+## License
+
+Part of BENCHLAB PyTools. See main project license for details.