benchlab-pytools 3.3.1__tar.gz → 3.5.0__tar.gz

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to BENCHLAB PyTools are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
 [SemVer](https://semver.org/).
 
+## [3.5.0] - 2026-11-04
+
+### Added
+- BL1 (ORIGINAL, fw07+) fault status is now supported, matching BL2:
+  the TUI is variant-aware and decodes faults with the correct enum
+  for each device instead of always assuming BL2's (which previously
+  meant BL1 faults were silently never shown). (#100)
+- `PatchVersion` is now surfaced end-to-end (TUI Device tab, discovery,
+  FastAPI `/devices`, MQTT publisher), including a fix for a
+  worker-loop bug that dropped it on every periodic device-list
+  refresh. (#100)
+- A startup check now verifies the installed `benchlab-pycore` version
+  and fails with a clear message instead of an `ImportError` traceback
+  when it's missing or too old. (#100)
+
+### Changed
+- Raised the `benchlab-pycore` floor to `>=0.9.1` after finding and
+  reporting a `read_device()` short-read bug in 0.9.0
+  (benchlab-pycore#22), fixed upstream in 0.9.1 (benchlab-pycore#23).
+  (#100)
+
+## [3.4.0] - 2026-10-22
+
+### Added
+- TUI: BENCHLAB2 fault status is now surfaced. The Device tab shows a
+  quick-glance warning when a fault is currently active, and a new Faults
+  tab lists all 34 known BL2 faults with their live (`FaultStatus`) and
+  latched (`FaultLog`) state. Requires BL2 firmware 05+; ORIGINAL devices
+  and earlier BL2 firmware show an explanatory message instead. (#95)
+
+### Fixed
+- `-flash`: confirmed against real hardware that a device doesn't always
+  re-enumerate as CDC on its own after leaving DFU mode, even though the
+  flash and verify already succeeded. The tool now says so plainly instead
+  of a vague "may just be slow re-enumeration" warning, and the
+  interactive flow prompts to replug the USB cable and re-checks the
+  device before exiting instead of leaving the user to guess. (#97)
+
 ## [3.3.1] - 2026-10-17
 
 ### Fixed

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: benchlab-pytools
-Version: 3.3.1
+Version: 3.5.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
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Hardware
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.10
-Requires-Dist: benchlab-pycore>=0.8.0
+Requires-Dist: benchlab-pycore>=0.9.1
 Requires-Dist: packaging<26.0,>=23.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-dotenv<2.0,>=1.2.2

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/__init__.py

@@ -2,4 +2,4 @@
 BENCHLAB Telemetry Package
 """
 
-__version__ = "3.3.1"
+__version__ = "3.5.0"

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/core/datasource.py

@@ -312,6 +312,15 @@ class DirectDataSource(DataSource):
                         ser, product_id=product_id)
                     if sensors:
                         data = self._pycore['translate_sensor_struct'](sensors)
+                        # translate_sensor_struct_bl2() doesn't read these
+                        # off the raw struct (BL2 fw05+ only), so pull them
+                        # directly here.
+                        fault_status = getattr(sensors, 'FaultStatus', None)
+                        fault_log = getattr(sensors, 'FaultLog', None)
+                        if fault_status is not None:
+                            data['FaultStatus'] = fault_status
+                        if fault_log is not None:
+                            data['FaultLog'] = fault_log
                         data['timestamp'] = datetime.now(UTC).isoformat()
                         with self._lock:
                             self._latest_data[uid] = data
@@ -722,6 +731,10 @@ CS_SHORT_NAME_MAP: Dict[str, str] = {
         **{f"FAN{i}_T": f"Fan{i}_RPM" for i in range(1, 10)},
         **{f"FAN{i}_D": f"Fan{i}_Duty" for i in range(1, 10)},
         "FAN_EXT": "FanExtDuty",
+
+        # BL2 fault bitmasks (fw05+ only) — see Fault enum in benchlab_pycore
+        "FAULT_STATUS": "FaultStatus",
+        "FAULT_LOG": "FaultLog",
 }
 
 

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/core/datasource_manager.py

@@ -372,7 +372,11 @@ class DataSourceManager:
                     time.sleep(2.0)
                     continue
 
-                # Update device list periodically
+                # Update device list periodically. list_devices() only
+                # returns a summary shape; merge in get_device_info()'s
+                # fuller dict (as connect() does) so fields it alone
+                # provides -- e.g. PatchVersion -- don't get dropped on
+                # every refresh.
                 try:
                     devices = self._datasource.list_devices()
                     with self._lock:
@@ -380,7 +384,16 @@ class DataSourceManager:
                         for device in devices:
                             uid = device.get('uid')
                             if uid:
-                                self._devices[uid] = device
+                                device_entry = device.copy()
+                                try:
+                                    full_info = (
+                                        self._datasource.get_device_info(
+                                            uid))
+                                    if full_info:
+                                        device_entry.update(full_info)
+                                except Exception:
+                                    pass
+                                self._devices[uid] = device_entry
                 except Exception as e:
                     logger.debug(f"Error updating device list: {e}")
 

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/core/discovery.py

@@ -68,13 +68,15 @@ def discover_devices() -> List[Dict[str, Any]]:
             ser.close()
             if uid:
                 fw = info.get("FwVersion", "?")
+                patch = info.get("PatchVersion", 0xFF)
                 product_id = info.get(
                     "ProductId", BENCHLAB_ORIGINAL_PRODUCT_ID)
                 variant = (
                     "BL2" if product_id == BENCHLAB_BL2_PRODUCT_ID
                     else "ORIGINAL")
-                devices.append({"uid": uid, "port": port,
-                               "fw": fw, "variant": variant})
+                devices.append({
+                    "uid": uid, "port": port, "fw": fw,
+                    "PatchVersion": patch, "variant": variant})
                 logger.info(
                     "Discovered BenchLab device UID=%s on %s "
                     "(FW=%s, Variant=%s)",

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/flash/flash_manager.py

@@ -325,7 +325,9 @@ class FlashManager:
 
         logger.warning(
             "%s did not reappear within %.0fs after leaving DFU mode -- "
-            "this may just be slow re-enumeration, verify manually.",
+            "flash/verify already succeeded, but it didn't re-enumerate "
+            "as CDC on its own. Unplug and replug the USB cable to "
+            "reconnect it.",
             port, timeout)
         return None
 
@@ -353,7 +355,11 @@ class FlashManager:
                 "Flash completed but verification failed")
 
         if port is not None:
-            self.leave_and_reboot(usb_dev, port)
+            reboot_info = self.leave_and_reboot(usb_dev, port)
+            if reboot_info is None and self.source == "direct":
+                message += (
+                    f" -- {port} did not come back on its own; unplug and "
+                    "replug the USB cable to reconnect it")
         else:
             # No CDC port to wait for -- just trigger the DfuSe leave
             # sequence so the device reboots into the newly-flashed app.

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/flash/flash_tool.py

@@ -226,8 +226,9 @@ def cmd_flash(args):
 
     def progress_cb(port, written, total):
         pct = (written / total * 100) if total else 100
+        done = total and written >= total
         print(f"\r  {port}: {written}/{total} bytes ({pct:.0f}%)",
-              end="", flush=True)
+              end="\n" if done else "", flush=True)
 
     results = manager.flash_many(
         [port for port, _ in targets], args.file,
@@ -316,8 +317,9 @@ def cmd_flash_bare_dfu(args):
 
     def progress_cb(written, total):
         pct = (written / total * 100) if total else 100
+        done = total and written >= total
         print(f"\r  {written}/{total} bytes ({pct:.0f}%)",
-              end="", flush=True)
+              end="\n" if done else "", flush=True)
 
     result = manager.flash_bare_dfu(
         product_id, data, verify_only=args.verify_only,
@@ -453,24 +455,45 @@ def interactive_mode(args):
 
     def progress_cb(port, written, total):
         pct = (written / total * 100) if total else 100
+        done = total and written >= total
         print(f"\r  {port}: {written}/{total} bytes ({pct:.0f}%)",
-              end="", flush=True)
+              end="\n" if done else "", flush=True)
 
     print()
     results = manager.flash_many(
         [_device_identifier(args, device) for device in targets],
         file_path, progress_cb=progress_cb,
         on_unsupported_firmware=_make_boot0_fallback_prompt())
-    print()
 
     print()
     print("Results:")
     any_failed = False
+    needs_reconnect_check = []
     for result in results:
         status = "OK" if result.ok else "FAILED"
         if not result.ok:
             any_failed = True
         print(f"  {result.port}  [{status}]  {result.message}")
+        if result.ok and "unplug and replug" in result.message:
+            needs_reconnect_check.append(result.port)
+
+    for port in needs_reconnect_check:
+        print()
+        while True:
+            choice = input(
+                f"Replug {port}'s USB cable, then press Enter to check "
+                "it's back (or type 'skip' to continue without "
+                "checking): ").strip().lower()
+            if choice == "skip":
+                break
+            info = manager.identify_device(port)
+            if info is not None:
+                fw = info.get('FwVersion', 0)
+                print(f"  {port} is back (FW: 0x{fw:02X})")
+                break
+            print(f"  {port} not detected yet -- check the cable and try "
+                  "again.")
+
     print()
     input("Press Enter to exit...")
 

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/flash/test_flash_manager.py

@@ -365,6 +365,33 @@ def test_flash_bare_dfu_flashes_without_cdc_round_trip(
     assert "Flashed and verified successfully" in result.message
 
 
+def test_erase_verify_leave_hints_replug_when_port_does_not_reappear(
+        manager, monkeypatch):
+    """leave_and_reboot() returning None for a 'direct' flash (the CDC
+    port never came back on its own) must not be silently swallowed --
+    append an actionable unplug/replug hint to the result message rather
+    than reporting a bare success. Confirmed against real hardware: the
+    flash+verify succeed but the device needs a manual USB replug to
+    re-enumerate as CDC (see PR discussion)."""
+    fake_usb_dev = MagicMock()
+    monkeypatch.setattr(
+        manager, "verify_image", lambda usb_dev, d, pid: True)
+    monkeypatch.setattr(
+        manager, "erase_and_flash",
+        lambda usb_dev, d, pid, progress_cb=None: None)
+    monkeypatch.setattr(
+        manager, "leave_and_reboot", lambda usb_dev, port: None)
+
+    ok, message = manager._erase_verify_leave(
+        fake_usb_dev, b"\x00" * 16, BENCHLAB_ORIGINAL_PRODUCT_ID,
+        "COM3", verify_only=False)
+
+    assert ok
+    assert "Flashed and verified successfully" in message
+    assert "unplug and replug" in message.lower()
+    assert "COM3" in message
+
+
 def test_flash_bare_dfu_catches_exceptions(manager, monkeypatch):
     monkeypatch.setattr(
         manager, "wait_for_dfu_device",

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/main.py

@@ -17,6 +17,9 @@ import logging
 import os
 import sys
 import traceback
+from importlib.metadata import PackageNotFoundError, version
+
+from packaging.version import Version
 
 from .tools import CONSUMER_TOOLS, LAUNCH_PROFILES  # noqa: F401
 # CONSUMER_TOOLS re-exported for benchlab.main.CONSUMER_TOOLS consumers
@@ -25,6 +28,34 @@ from .launcher import launch_tools_concurrent
 
 logger = logging.getLogger("benchlab.launcher")
 
+# Keep in sync with the "benchlab-pycore>=X.Y.Z" pin in pyproject.toml --
+# this is pytools' own belt-and-suspenders check so a stale pycore install
+# (e.g. an env pip never upgraded) fails with a clear message instead of an
+# ImportError traceback deep in a tool module.
+MIN_PYCORE_VERSION = "0.9.1"
+
+
+def _check_pycore_version() -> None:
+    try:
+        installed = version("benchlab-pycore")
+    except PackageNotFoundError:
+        print(
+            "ERROR: benchlab-pycore is not installed.\n"
+            "Install it with: pip install "
+            f"\"benchlab-pycore>={MIN_PYCORE_VERSION}\"",
+            file=sys.stderr)
+        sys.exit(1)
+
+    if Version(installed) < Version(MIN_PYCORE_VERSION):
+        print(
+            f"ERROR: benchlab-pycore {installed} is installed, but "
+            f"pytools requires >={MIN_PYCORE_VERSION}.\n"
+            "Upgrade it with: pip install "
+            f"\"benchlab-pycore>={MIN_PYCORE_VERSION}\"",
+            file=sys.stderr)
+        sys.exit(1)
+
+
 try:
     from .menu import interactive_loop
 except ImportError as e:
@@ -511,6 +542,8 @@ def launch_mode() -> None:
 
 def main() -> None:
     """Entry point."""
+    if not ({"-h", "--help", "--version"} & set(sys.argv[1:])):
+        _check_pycore_version()
     launch_mode()
 
 

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/mqtt/mqtt_publisher.py

@@ -351,6 +351,7 @@ def device_thread(device, cfg, publish_interval=1):
                 vendor_id = 0
                 product_id = BENCHLAB_ORIGINAL_PRODUCT_ID
                 fw_version = device.get("firmware")
+                patch_version = 0xFF
                 try:
                     dev_info = read_device(ser)
                     if dev_info:
@@ -358,6 +359,7 @@ def device_thread(device, cfg, publish_interval=1):
                         product_id = dev_info.get(
                             'ProductId', BENCHLAB_ORIGINAL_PRODUCT_ID)
                         fw_version = dev_info.get('FwVersion', fw_version)
+                        patch_version = dev_info.get('PatchVersion', 0xFF)
                 except Exception:
                     pass
                 variant = (
@@ -373,6 +375,7 @@ def device_thread(device, cfg, publish_interval=1):
                     "VendorId": vendor_id,
                     "ProductId": product_id,
                     "FwVersion": fw_version,
+                    "PatchVersion": patch_version,
                     "variant": variant,
                 }
                 topic_info = f"{cfg['topic_prefix']}/{uid}/info"

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/restapi/telemetry_api.py

@@ -606,6 +606,7 @@ def list_devices():
             "uid": uid,
             "port": info.get("port", "unknown"),
             "firmware": device_info.get("FwVersion", "?"),
+            "PatchVersion": device_info.get("PatchVersion", 0xFF),
             "variant": device_info.get("variant", "ORIGINAL"),
             "VendorId": device_info.get("VendorId", 0),
             "ProductId": device_info.get("ProductId", 0),

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/tui/README.md

@@ -33,7 +33,7 @@ The BENCHLAB Enhanced TUI provides a modern, feature-rich curses-based interface
 
 ## 📊 Telemetry Tabs
 
-The TUI has 8 tabs: `Fleet`, `Device`, `System`, `Motherboard`, `12VHPWR`, `Voltage`, `Temperature`, `Fans` (in this order; see `Config.TAB_NAMES` in `benchlab/tui/config.py`). Tabs can also be jumped to directly with the number keys `0`-`7`.
+The TUI has 9 tabs: `Fleet`, `Device`, `System`, `Motherboard`, `12VHPWR`, `Voltage`, `Temperature`, `Fans`, `Faults` (in this order; see `Config.TAB_NAMES` in `benchlab/tui/config.py`). Tabs can also be jumped to directly with the number keys `0`-`8`.
 
 ### **Fleet Tab (Tab 0)**
 - Device list with connection status indicators
@@ -46,6 +46,7 @@ The TUI has 8 tabs: `Fleet`, `Device`, `System`, `Motherboard`, `12VHPWR`, `Volt
 - Device identification (Model, Vendor ID, Product ID, UID)
 - Firmware version display
 - TUI refresh interval
+- Quick-glance active-fault warning (BL2 fw05+ only); see the Faults tab for full detail
 
 ### **System / Motherboard / 12VHPWR Tabs (Tabs 2-4)**
 - Real-time power consumption with progress bars
@@ -76,12 +77,16 @@ The TUI has 8 tabs: `Fleet`, `Device`, `System`, `Motherboard`, `12VHPWR`, `Volt
 - External fan duty monitoring
 - Fan statistics (average duty, max RPM, active count)
 
+### **Faults Tab (Tab 8)**
+- Per-fault Active/Logged status for all BENCHLAB 2 fault conditions
+- BL2 firmware 05+ only; shows an unavailable message on ORIGINAL devices or older BL2 firmware
+
 ## 🎮 Keyboard Shortcuts
 
 ### **Navigation**
 - `h`, `←` - Move to previous tab
 - `l`, `→` - Move to next tab
-- `0`-`7` - Jump directly to a tab by index
+- `0`-`8` - Jump directly to a tab by index
 - `q`, `Q` - Quit application
 - `?` - Show/hide help modal
 

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/tui/config.py

@@ -29,7 +29,8 @@ TAB_NAMES = [
     "12VHPWR",
     "Voltage",
     "Temperature",
-    "Fans"]
+    "Fans",
+    "Faults"]
 
 # Statistics display width
 STAT_COLUMN_WIDTH = 10
@@ -323,6 +324,19 @@ class Layout:
         'STATS': 52,            # Statistics column
     }
 
+    # Faults tab column positions — two-column grid (17 rows each) so all
+    # 34 BL2 Fault enum members (or 16 for ORIGINAL fw07+) fit on one
+    # screen under MIN_TERMINAL_ROWS/COLS.
+    FAULT_COLS = {
+        'NAME': 2,              # Fault name column (left grid column)
+        'ACTIVE': 26,           # Active status column (left grid column)
+        'LOGGED': 36,           # Logged status column (left grid column)
+        'NAME2': 48,            # Fault name column (right grid column)
+        'ACTIVE2': 72,          # Active status column (right grid column)
+        'LOGGED2': 82,          # Logged status column (right grid column)
+    }
+    FAULT_ROWS_PER_COL = 17     # Rows per grid column (34 faults / 2)
+
 
 # ═══════════════════════════════════════════════════════════════════════════════
 #  Help Text

{benchlab_pytools-3.3.1 → benchlab_pytools-3.5.0}/benchlab/tui/test_tui_core.py

@@ -106,7 +106,7 @@ def _render_tab(tab_index, snapshot, fleet_devices=None):
 
 
 @pytest.mark.parametrize("tab_index",
-                         range(8),
+                         range(9),
                          ids=["fleet",
                               "device",
                               "system",
@@ -114,7 +114,8 @@ def _render_tab(tab_index, snapshot, fleet_devices=None):
                               "hpwr",
                               "voltage",
                               "temperature",
-                              "fans"],
+                              "fans",
+                              "faults"],
                          )
 def test_render_tab_survives_none_sensor_values(tab_index):
     """Every tab must render without raising when sensor_data values are None.
@@ -148,7 +149,7 @@ def test_fleet_tab_survives_disconnected_and_empty_fleet():
 
 
 @pytest.mark.parametrize("tab_index",
-                         range(8),
+                         range(9),
                          ids=["fleet",
                               "device",
                               "system",
@@ -156,7 +157,8 @@ def test_fleet_tab_survives_disconnected_and_empty_fleet():
                               "hpwr",
                               "voltage",
                               "temperature",
-                              "fans"],
+                              "fans",
+                              "faults"],
                          )
 def test_render_tab_survives_disconnected(tab_index):
     """All tabs must render their disconnected state without raising."""
@@ -195,6 +197,56 @@ def test_fans_tab_survives_many_fans_on_small_terminal():
         pytest.skip("curses screen unavailable in this environment")
 
 
+def test_faults_tab_shows_no_warning_when_no_faults_active():
+    """Device tab draws no fault warning line when FaultStatus is all-clear."""
+    bl2_info = {"VendorId": 0xEE, "ProductId": 0x11, "FwVersion": 0x07,
+                "variant": "BL2"}
+    sensor_data = dict(SENSOR_DATA_ALL_NONE)
+    sensor_data["FaultStatus"] = 0
+    sensor_data["FaultLog"] = 0
+    snapshot = _snapshot(device_info=bl2_info, sensor_data=sensor_data)
+    _render_tab(1, snapshot)  # Device tab
+    _render_tab(8, snapshot)  # Faults tab
+
+
+def test_faults_tab_decodes_active_and_logged_bits():
+    """Faults tab and Device tab warning must render without raising when
+    specific fault bits are set, for a BL2 fw05+ device."""
+    bl2_info = {"VendorId": 0xEE, "ProductId": 0x11, "FwVersion": 0x07,
+                "variant": "BL2"}
+    sensor_data = dict(SENSOR_DATA_ALL_NONE)
+    # Bit 9 = OCP_CPU1 (active), bit 32 = CURRENT_IMBALANCE_HPWR1 (logged only)
+    sensor_data["FaultStatus"] = 1 << 9
+    sensor_data["FaultLog"] = (1 << 9) | (1 << 32)
+    snapshot = _snapshot(device_info=bl2_info, sensor_data=sensor_data)
+    _render_tab(1, snapshot)  # Device tab warning line
+    _render_tab(8, snapshot)  # Faults tab full grid
+
+
+def test_faults_tab_handles_device_without_fault_data():
+    """ORIGINAL devices and pre-fw05 BL2 firmware have no FaultStatus key —
+    the Faults tab must show an explanatory message, not crash."""
+    original_info = {
+        "VendorId": 0x1234, "ProductId": 0x10, "FwVersion": 0x01,
+        "variant": "ORIGINAL"}
+    snapshot = _snapshot(device_info=original_info)  # no FaultStatus key
+    _render_tab(1, snapshot)  # Device tab
+    _render_tab(8, snapshot)  # Faults tab
+
+
+def test_decode_faults_helper():
+    from benchlab.tui.tui_core import _decode_faults
+
+    assert _decode_faults(None, "BL2") == []
+    assert _decode_faults(0, "BL2") == []
+    assert _decode_faults(1 << 9, "BL2") == ["OCP_CPU1"]
+    decoded = _decode_faults((1 << 0) | (1 << 33), "BL2")
+    assert set(decoded) == {"OTP_TCHIP", "CURRENT_IMBALANCE_HPWR2"}
+
+    decoded_original = _decode_faults((1 << 0) | (1 << 10), "ORIGINAL")
+    assert set(decoded_original) == {"OTP_TCHIP", "OCP_ATX12V"}
+
+
 def test_help_modal_renders_without_stomping_main_refresh():
     """Regression test: help modal must be composited, not overwritten
     every tick.