benchlab-pytools 3.0.0__py3-none-any.whl

benchlab/tui/tui_main.py

@@ -0,0 +1,418 @@
+"""
+Refactored TUI Main Entry Point
+Clean main entry point using the refactored architecture with separated
+concerns:
+- DataSourceManager handles all data source operations
+- ChannelStats manages statistics
+- TUICore handles all UI rendering
+- Config centralizes configuration
+This replaces the original monolithic tui_main.py with a much cleaner
+implementation.
+"""
+import curses
+import logging
+import sys
+import time
+from typing import List, Dict, Any
+
+from benchlab.tui.__init__ import __version__
+from benchlab.core.datasource_manager import DataSourceManager
+from benchlab.core.statistics import ChannelStats, create_stats_callback
+from .tui_core import TUICore
+
+logger = logging.getLogger("benchlab.tui.main")
+
+
+class _DevNullWriter:
+    """A file-like object that discards all output."""
+
+    def write(self, s):
+        pass
+
+    def flush(self):
+        pass
+
+    def isatty(self):
+        return False
+
+
+class _TUIStdoutRedirect:
+    """Redirect stdout/stderr to prevent interference with curses display.
+
+    The pycore library writes INFO messages directly to stdout which messes
+    up the curses layout. This class redirects stdout/stderr to a file or
+    /dev/null
+    during TUI operation.
+    """
+
+    def __init__(self, log_file: str = None):
+        self.log_file = log_file
+        self._original_stdout = None
+        self._original_stderr = None
+        self._file_handle = None
+
+    def __enter__(self):
+        self._original_stdout = sys.stdout
+        self._original_stderr = sys.stderr
+
+        if self.log_file:
+            self._file_handle = open(self.log_file, 'a')
+            sys.stdout = self._file_handle
+            sys.stderr = self._file_handle
+        else:
+            # Discard all output
+            sys.stdout = _DevNullWriter()
+            sys.stderr = _DevNullWriter()
+
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._file_handle:
+            self._file_handle.flush()
+            self._file_handle.close()
+
+        sys.stdout = self._original_stdout
+        sys.stderr = self._original_stderr
+        return False
+
+
+def get_default_datasource(args) -> str:
+    """Get default data source based on command-line arguments."""
+    if hasattr(args, 'source') and args.source:
+        return args.source
+    return 'direct'
+
+
+def convert_fleet_format(
+        devices_dict: Dict[str, Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Convert DataSourceManager device dict to fleet list format."""
+    fleet = []
+    for uid, device_info in devices_dict.items():
+        fleet.append({
+            'uid': uid,
+            'port': device_info.get('port', 'unknown'),
+            'firmware': device_info.get(
+                'firmware', device_info.get('FwVersion', 0)),
+            'variant': device_info.get('variant'),
+            'ProductId': device_info.get('ProductId'),
+        })
+    return sorted(fleet, key=lambda d: d["port"])
+
+
+class TUIApplication:
+    """
+    Main TUI application class that coordinates between DataSourceManager,
+    statistics tracking, and UI rendering.
+    """
+
+    def __init__(self, args):
+        self.args = args
+        self.source_type = get_default_datasource(args)
+
+        self.stats = ChannelStats()
+        stats_callback = create_stats_callback(self.stats)
+
+        datasource_kwargs = {
+            'poll_interval': getattr(args, 'interval', 1.0),
+        }
+
+        if self.source_type == 'fastapi':
+            if hasattr(args, 'api_port'):
+                datasource_kwargs['base_url'] = f"http://127.0.0.1:{
+                    args.api_port}"
+            else:
+                datasource_kwargs['base_url'] = "http://127.0.0.1:8000"
+            datasource_kwargs['timeout'] = 5.0
+
+        elif self.source_type == 'fastapi_custom':
+            # Use the custom URL from args.api_url (set from BENCHLAB_API_URL
+            # env var)
+            datasource_kwargs['base_url'] = getattr(
+                args, 'api_url', 'http://127.0.0.1:8000')
+            datasource_kwargs['timeout'] = 5.0
+
+        elif self.source_type == 'mqtt':
+            datasource_kwargs['broker'] = getattr(
+                args, 'mqtt_broker', 'localhost')
+            datasource_kwargs['port'] = getattr(args, 'mqtt_port', 1883)
+            datasource_kwargs['timeout'] = 5.0
+
+        elif self.source_type == 'named_pipe':
+            datasource_kwargs['timeout'] = 5.0
+
+        elif self.source_type == 'service_http':
+            service_url = getattr(
+                args, 'service_url', None) or 'http://localhost:8585'
+            datasource_kwargs['base_url'] = service_url
+            datasource_kwargs['timeout'] = 5.0
+
+        self.datasource_manager = DataSourceManager(
+            source_type=self.source_type,
+            stats_callback=stats_callback,
+            **datasource_kwargs
+        )
+
+        self.tui_core = None
+        self.fleet_cache = []
+        self.last_fleet_refresh = 0.0
+
+    def run(self, stdscr):
+        self.tui_core = TUICore(stdscr, __version__)
+
+        # Force full screen redraw to overwrite any stray console output
+        stdscr.clearok(True)
+
+        # Auto-connect for all non-direct sources
+        if self.source_type != 'direct':
+            self._connect_datasource()
+
+        self._refresh_fleet_cache()
+
+        while True:
+            snapshot = self.datasource_manager.snapshot()
+
+            rendered = self.tui_core.render(
+                snapshot=snapshot,
+                stats=self.stats,
+                fleet_devices=self.fleet_cache,
+                refresh_interval=getattr(self.args, 'interval', 1.0)
+            )
+
+            if not rendered:
+                time.sleep(0.2)
+                continue
+
+            try:
+                key = stdscr.getkey()
+                action = self.tui_core.handle_key(key)
+
+                if not self._handle_action(action):
+                    break
+
+            except curses.error:
+                pass
+
+    def _handle_action(self, action: Dict[str, Any]) -> bool:
+        action_type = action.get('type', 'none')
+
+        if action_type == 'quit':
+            return False
+
+        elif action_type == 'reset_stats':
+            uid = self.datasource_manager.get_selected_uid()
+            if uid:
+                self.stats.reset(uid)
+                self.tui_core.set_status("Stats reset.")
+            else:
+                self.tui_core.set_status("No device selected.")
+
+        elif action_type == 'rescan_fleet':
+            self._refresh_fleet_cache()
+            count = len(self.fleet_cache)
+            source_label = (
+                self.source_type.upper()
+                if self.source_type != 'direct' else 'serial')
+            self.tui_core.set_status(
+                f"Fleet rescanned ({source_label}) — {count} device(s) found.")
+
+        elif action_type == 'fleet_nav':
+            direction = action.get('direction')
+            self.tui_core.update_fleet_index(len(self.fleet_cache), direction)
+
+        elif action_type == 'fleet_select':
+            index = action.get('index', 0)
+            if 0 <= index < len(self.fleet_cache):
+                selected_device = self.fleet_cache[index]
+                self._connect_to_device(selected_device)
+
+        return True
+
+    def _connect_datasource(self):
+        """Connect via non-direct datasource
+        (FastAPI/MQTT/named_pipe/service_http)."""
+        try:
+            if self.datasource_manager.connect():
+                uid = self.datasource_manager.get_selected_uid()
+                self.tui_core.set_status(
+                    f"Connected via {
+                        self.source_type.upper()}")
+                logger.info(
+                    f"Connected to {
+                        self.source_type} datasource, selected: {uid}")
+            else:
+                snapshot = self.datasource_manager.snapshot()
+                error_msg = snapshot.get(
+                    'last_error', f"Failed to connect to {
+                        self.source_type}")
+                self.tui_core.set_status(
+                    f"Connection failed: {error_msg}", 5.0)
+                logger.error(
+                    f"Failed to connect to {
+                        self.source_type}: {error_msg}")
+        except Exception as e:
+            self.tui_core.set_status(f"Connection error: {str(e)}", 5.0)
+            logger.error(
+                f"Exception during {
+                    self.source_type} connection: {e}")
+
+    def _connect_to_device(self, device: Dict[str, Any]):
+        port = device.get('port')
+        uid = device.get('uid')
+
+        if uid == "BUSY":
+            self.tui_core.set_status(
+                "Device is busy (already connected elsewhere)", 3.0)
+            return
+
+        try:
+            if self.source_type == 'direct':
+                if self.datasource_manager.connect(port=port):
+                    self.tui_core.set_status(f"Connected to {port}")
+                    logger.info(f"Connected to device on {port}")
+                else:
+                    snapshot = self.datasource_manager.snapshot()
+                    error_msg = snapshot.get('last_error', 'Connection failed')
+                    self.tui_core.set_status(
+                        f"Connection failed: {error_msg}", 4.0)
+                    logger.error(f"Failed to connect to {port}: {error_msg}")
+            else:
+                # Network/pipe datasource — select different device
+                if self.datasource_manager.select_device(uid):
+                    self.tui_core.set_status(f"Selected device {uid}")
+                    logger.info(
+                        f"Selected device {uid} via {
+                            self.source_type}")
+                else:
+                    self.tui_core.set_status("Failed to select device", 3.0)
+                    logger.warning(f"Failed to select device {uid}")
+
+        except Exception as e:
+            self.tui_core.set_status(f"Connection error: {str(e)}", 4.0)
+            logger.error(f"Exception during device connection: {e}")
+
+    def _refresh_fleet_cache(self):
+        try:
+            current_time = time.time()
+            if current_time - self.last_fleet_refresh < 1.0:
+                return
+            self.last_fleet_refresh = current_time
+
+            if (self.source_type != 'direct'
+                    and self.datasource_manager.is_connected()):
+                devices_dict = self.datasource_manager.list_devices()
+                self.fleet_cache = convert_fleet_format(devices_dict)
+            else:
+                self.fleet_cache = self._scan_local_fleet()
+
+            if self.tui_core and self.tui_core.fleet_index >= len(
+                    self.fleet_cache):
+                self.tui_core.fleet_index = 0
+
+            logger.debug(
+                f"Fleet cache refreshed: {len(self.fleet_cache)} devices")
+
+        except Exception as e:
+            logger.warning(f"Error refreshing fleet cache: {e}")
+            self.fleet_cache = []
+
+    def _scan_local_fleet(self) -> List[Dict[str, Any]]:
+        fleet = []
+        try:
+            devices = self.datasource_manager.discover_devices()
+            for device in devices:
+                fleet.append({
+                    "port": device.get("port", "Unknown"),
+                    "firmware": device.get("fw", "?"),
+                    "uid": device.get("uid", "Unknown"),
+                    "variant": device.get("variant", "ORIGINAL"),
+                })
+        except Exception as e:
+            logger.error(f"Error during local fleet scan: {e}")
+
+        # discover_devices() probes each port with a fresh serial connection,
+        # which fails (and is silently dropped) for the port our own active
+        # connection already holds exclusively. Fall back to the connected
+        # device's own info so it doesn't vanish from the fleet list while
+        # we're connected to it.
+        if self.datasource_manager.is_connected():
+            uid = self.datasource_manager.get_selected_uid()
+            if uid and not any(d["uid"] == uid for d in fleet):
+                snapshot = self.datasource_manager.snapshot()
+                device_info = snapshot.get('device_info') or {}
+                fleet.append({
+                    "port": snapshot.get("port") or "Unknown",
+                    "firmware": device_info.get("FwVersion", "?"),
+                    "uid": uid,
+                    "variant": device_info.get("variant", "ORIGINAL"),
+                })
+
+        return sorted(fleet, key=lambda d: d["port"])
+
+    def cleanup(self):
+        if self.datasource_manager:
+            self.datasource_manager.disconnect()
+
+
+def tui_main(stdscr, _unused, args):
+    """Main TUI entry point."""
+    # Redirect stdout/stderr to prevent pycore INFO messages from messing up
+    # curses layout
+    with _TUIStdoutRedirect():
+        app = TUIApplication(args)
+
+        try:
+            app.run(stdscr)
+        except Exception as e:
+            logger.error(f"TUI application error: {e}")
+            raise
+        finally:
+            app.cleanup()
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="BenchLab TUI")
+    parser.add_argument(
+        '--interval',
+        type=float,
+        default=1.0,
+        help='Telemetry refresh interval')
+    parser.add_argument(
+        '--source',
+        choices=[
+            'direct',
+            'fastapi',
+            'fastapi_custom',
+            'mqtt',
+            'named_pipe',
+            'service_http'],
+        default='direct',
+        help='Data source type')
+    parser.add_argument('--api-port', type=int, default=8000, dest='api_port',
+                        help='FastAPI server port')
+    parser.add_argument(
+        '--mqtt-broker',
+        default='localhost',
+        dest='mqtt_broker',
+        help='MQTT broker hostname')
+    parser.add_argument(
+        '--mqtt-port',
+        type=int,
+        default=1883,
+        dest='mqtt_port',
+        help='MQTT broker port')
+    parser.add_argument(
+        '--service-url',
+        default='http://localhost:8585',
+        dest='service_url',
+        help='C# BenchLab service HTTP API URL')
+    args = parser.parse_args()
+
+    try:
+        curses.wrapper(tui_main, None, args)
+    except KeyboardInterrupt:
+        print("\nTUI interrupted by user")
+    except Exception as e:
+        print(f"TUI error: {e}")
+        sys.exit(1)

benchlab/vu/README.md

@@ -0,0 +1,64 @@
+# BENCHLAB VU Dials
+
+Drives physical analog-style USB "VU dial" gauges (via the bundled [VU-Server](VU-Server/)) using live BENCHLAB telemetry, and provides a terminal UI for mapping dials to sensors.
+
+## Overview
+
+This tool has two pieces:
+
+- **VU Updater** (`-vu`) — polls BENCHLAB telemetry via the shared data-source layer, resolves each configured dial's mapped sensor value, and pushes it to the VU-Server API so the physical dial needle moves. Also renders and uploads a sensor logo image to each dial's screen.
+- **VU Config** (`-vuconfig`) — a curses TUI (`vu_tui.py`) for discovering connected VU dials and BENCHLAB devices, and mapping each dial to a specific device + sensor.
+
+Both talk to a local **VU-Server** process (bundled in [`VU-Server/`](VU-Server/), a fork of [ThePi910FC's VU1 server](VU-Server/README.md)), which the tool starts and manages automatically if it isn't already running.
+
+## Installation
+
+```bash
+pip install -r benchlab/vu/requirements.txt
+```
+
+Key dependencies: `requests`, `PyYAML`, `Pillow` (logo rendering), `pyserial`, `tornado` (VU-Server), plus `blessed` for the legacy curses-adjacent terminal helpers.
+
+## Usage
+
+### Configure dial-to-sensor mappings
+
+```bash
+python -m benchlab -vuconfig
+```
+
+Lists detected VU dials and BENCHLAB devices/sensors, and lets you assign a sensor to each dial. Mappings are written to `benchlab/vu/vu_dial.config`.
+
+### Run the updater
+
+```bash
+python -m benchlab -vu
+```
+
+Starts (or connects to) VU-Server, then continuously polls telemetry and updates each mapped dial. Supports the standard data-source flags (`--source`, `--api-url`, `--mqtt-broker`, etc. — see the [top-level README](../../README.md#data-sources)) and `-i/--interval` for poll frequency.
+
+The updater watches `vu_dial.config` for changes and hot-reloads mappings without restarting.
+
+## Configuration
+
+- **`vu_server.config`** — VU-Server connection settings:
+  ```json
+  {
+    "vu_server_url": "http://localhost:5340",
+    "api_key": "...",
+    "logo_file": "assets/bl_logo_144x200.png"
+  }
+  ```
+- **`vu_dial.config`** — list of dial-to-sensor mappings (`dial_uid`, `dial_name`, `benchlab_uid`, `benchlab_port`, `sensor`), managed by `-vuconfig` or by editing directly.
+- **`VU-Server/config.yaml`** — the underlying VU-Server's own device/serial configuration.
+
+## Troubleshooting
+
+- **VU-Server won't start** — check `vu_updater.log` in this directory; the updater forwards VU-Server's stdout/stderr there.
+- **No dials detected** — VU dials enumerate as USB serial devices; verify they're connected and recognized by the OS before running `-vuconfig`.
+- **Dial not updating** — confirm the mapped sensor name still exists in the current telemetry snapshot (sensor keys can change if a device's config changes).
+
+## See Also
+
+- [BENCHLAB PyTools Documentation](../../README.md)
+- [VU-Server README](VU-Server/README.md) — the bundled dial server itself

benchlab/vu/VU-Server/NOTICE.md

@@ -0,0 +1,13 @@
+# Notice
+
+This directory vendors code and assets from the VU Server project by Sasa
+Karanovic: https://github.com/SasaKaranovic/VU-Server
+
+The upstream repository does not publish a `LICENSE` file. BENCHLAB.io has
+obtained permission directly from the author to include and redistribute
+this code as part of BENCHLAB PyTools, including in the packaged PyPI
+distribution (`benchlab-pytools[vu]`).
+
+This notice documents that redistribution grant. It does not itself
+constitute a license; questions about terms for other uses should be
+directed to the upstream author.

benchlab/vu/VU-Server/README.md

@@ -0,0 +1,80 @@
+# VU Dials - VU Server
+
+
+![VU1 Dial](assets/vu1_hello_world.png?raw=true "VU1 Dial")
+
+This is the official VU dials repository for the VU Server application and it's source code.
+
+You can learn more about VU dials at [VUDials.com](https://vudials.com)
+
+The VU Server is a key component of the VU dials.
+
+It provides a Web API that can be interfaced by any third party application/script/service, allowing it to easily interact with and control the VU dials.
+
+For example, in order to update a dial, any application can make a simple [API request](https://docs.vudials.com/api/dial_UID_set/) to the VU server and that's it.
+
+
+# Demo application
+
+Right now, we have a very simple [VU1 demo application](https://github.com/SasaKaranovic/VU-Demo-App) that runs on Windows and demonstrates how dials can be used for resource usage monitoring.
+
+You can download it from [VUDials Download page](https://vudials.com/download/demo_app) (or look at the [source code](https://github.com/SasaKaranovic/VU-Demo-App)).
+
+Demo application uses VU Server API to demonstrate how a third party application can interact with VU dials.
+
+
+# Why not build apps for VU dials?
+
+You might ask why build an API server? Why not just build more stand-alone applications for VU dials? It's not that simple, but we believe that we have a good reason for this decision...
+
+VU dials can display virtually any information, and we all have our favourite/preferred applications for temperature monitoring, CPU/GPU/MEM load monitoring, weather app, stock monitoring, and the list can go on for days.
+
+If we started building new applications specifically for VU dials, we would be forcing our users to choose between their existing favourite application and the new one that works with VU dials.
+
+In the long run, this would result in "splitting the community" or forcing users to choose between abandoning perfectly fine software packages or abandoning the option to show some information on the VU dials.
+
+Instead, our approach is that we have completely opened the VU dials to the community and any third-party application/script/service running on your PC (or even network).
+
+Any application can make a straightforward API request to the VU server and say, "Hey, update dial X to show the value of Y", and that's it.
+
+Making a web API request is a very simple thing to do in almost any software package.
+
+So how does this benefit the community?
+
+This approach should allow existing applications to integrate/support VU dials natively or through extensions/addons/plugins. This means you still get to use your favourite application, but as a bonus, it now works seamlessly with VU dials.
+
+We are aware of the big caveat, which is that VU dial adoption won't happen over night and that it will require a lot of love and support from the community and developers.
+
+But we strongly believe that in the long run this is a much better approach than creating another closed-source, black-box product that forces you to use prescribed app store if you want to use the product.
+
+
+
+# How to run/install VU Server
+
+For Windows we have an installer that can be download from [https://vudials.com/download/server](https://vudials.com/download/server)
+
+For Linux and Mac users, we don't have the installer (yet), but you can run the VU Server from the source code.
+
+We have a simple example that describes how to run VU Server from source code on a Linux machine.
+
+
+[Jump to Linux Running From Source Code read me](Running_from_source_on_linux.md)
+
+
+# Want to contribute?
+
+As mentioned, right now, VU Dials adoption is the main hurdle for everyone enjoying VU dials in combination with their favourite game/applications/service.
+
+For developers interested in supporting VU dials natively or through extension/addon/plugin, please take a look at [VU Dials API](https://docs.vudials.com/api_messaging/) documentation to learn how you can communicate with the dials through VU server.
+
+For non-developers interested in supporting VU dials; you can reach out to your favorite developers and let them know that you would appreciate if they could integrate VU dials in their software.
+
+We could use any and all the love that the community has to offer. :)
+
+
+---
+
+[VU Dials Home page](https://vudials.com)
+
+
+

benchlab/vu/VU-Server/Running_from_source_on_linux.md

@@ -0,0 +1,97 @@
+# Running VU Server from source code on Linux
+
+You can run VU Server from source code.
+
+In order to do this you will need to install Python (programming language used by VU Server) and optionally Git.
+
+To do this you can run the following command
+
+```bash
+sudo apt install git python3 python3-pip
+```
+
+Then you can clone the VU Server repository and install project dependencies
+
+```bash
+git clone https://github.com/SasaKaranovic/VU-Server.git
+cd VU-Server
+pip3 install -r requirements.txt
+```
+
+
+You will need to run the above steps only once.
+
+After that you can start VU server by running `python3 server.py`
+
+Now you can access VU server web GUI by navigating to http://localhost:5340 in your browser.
+
+
+## How to fix "OSError: [Errno 13] Permission denied: '/dev/ttyUSBx'" error
+
+On some distributions you will need to explicitly allow access to `/dev/ttyUSBx` where `x` is usually a number (ie `/dev/ttyUSB0`).
+
+There are multiple ways to do this.
+
+You can temporarily grant access by running `sudo chmod 666 /dev/ttyUSB0`.
+
+But you will have to run this command every time you re-plug in the hub, which is not very practical.
+
+More permanent solution involves creating a udev rule
+
+```bash
+# navigate to rules.d directory
+cd /etc/udev/rules.d
+#create a new rule file
+sudo touch vu-rule.rules
+# open the file
+sudo nano vu-rule.rules
+# add the following
+KERNEL=="ttyUSB0", MODE="0666"
+```
+
+Please note that you will have to reboot your machine in order for new udev rules to take effect.
+
+
+# Example command line usage
+
+Ideally you would have an application/service/script that updates VU dials for you.
+
+But in some instances you might want to update the VU dials from the command line.
+
+This example shows how to do this.
+
+Requirements
+
+- You have to have VU server running.
+- From the VU Server GUI; Get the UID of the dial you want to update.
+- From the VU Server GUI; Get the API key you want to use for this purpose (create a new one or use existing one).
+
+
+In order to update the dial, we need to make a [HTTP request](https://docs.vudials.com/api/dial_UID_set/) to the VU server.
+
+Let's say we want to set the dial with the UID `3E0075000650564139323920` to `50%` using API key `cTpAWYuRpA2zx75Yh961Cg`
+
+We can make a simple GET request using `wget` (or `curl` if you prefer):
+
+```bash
+wget -O- -q "http://localhost:5340/api/v0/dial/3E0075000650564139323920/set?value=50&key=cTpAWYuRpA2zx75Yh961C" ; echo
+```
+
+You can use pipe redirects in your terminal to redirect output of applications to VU dials.
+
+Let's say we use following command to retrieve CPU usage on our Ubuntu machine
+
+```bash
+echo $[100-$(vmstat 1 2|tail -1|awk '{print $15}')]
+```
+
+This command will output an integer that represents CPU usage in percentage. We can then forward this information to VU server using pipe redirects
+
+```bash
+echo $[100-$(vmstat 1 2|tail -1|awk '{print $15}')] | xargs -I{} wget -O- -q "http://localhost:5340/api/v0/dial/3E0075000650564139323920/set?value={}&key=cTpAWYuRpA2zx75Yh961C"; echo
+```
+
+Please keep in mind that this is a very "simple" example (and yet looks somewhat complicated), but the main idea is that you can easily redirect output of any application on your system and send it to VU Server to have it displayed on your VU1 dials.
+
+Ideally you would not run these commands manually but instead have a script/service/cron that updates your dials periodically.
+