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

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

@@ -4,6 +4,23 @@ 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.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: benchlab-pytools
-Version: 3.3.1
+Version: 3.4.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

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

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

{benchlab_pytools-3.3.1 → benchlab_pytools-3.4.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.4.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.4.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.4.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.4.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.4.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,18 @@ class Layout:
         'STATS': 52,            # Statistics column
     }
 
+    # Faults tab column positions — two-column grid (17 rows each) so all
+    # 34 Fault enum members 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.4.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,53 @@ 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) == []
+    assert _decode_faults(0) == []
+    assert _decode_faults(1 << 9) == ["OCP_CPU1"]
+    decoded = _decode_faults((1 << 0) | (1 << 33))
+    assert set(decoded) == {"OTP_TCHIP", "CURRENT_IMBALANCE_HPWR2"}
+
+
 def test_help_modal_renders_without_stomping_main_refresh():
     """Regression test: help modal must be composited, not overwritten
     every tick.

{benchlab_pytools-3.3.1 → benchlab_pytools-3.4.0}/benchlab/tui/tui_core.py

@@ -13,10 +13,22 @@ from typing import Dict, Any, List, Optional
 
 from .config import Config
 from benchlab.core.statistics import ChannelStats, StatsFormatter
+from benchlab_pycore.core import Fault
 
 logger = logging.getLogger("benchlab.tui.tui_core")
 
 
+def _decode_faults(bitmask: Optional[float]) -> List[str]:
+    """Decode a FaultStatus/FaultLog bitmask into a list of Fault names.
+
+    Returns an empty list for None/0/falsy bitmasks (no faults set).
+    """
+    if not bitmask:
+        return []
+    bitmask = int(bitmask)
+    return [f.name for f in Fault if bitmask & (1 << f.value)]
+
+
 class TUICore:
     """
     Core TUI class handling rendering, navigation, and user input.
@@ -290,6 +302,8 @@ class TUICore:
                 self._render_temperature_tab(snapshot, stats)
             elif self.current_tab == 7:
                 self._render_fans_tab(snapshot, stats, height, width)
+            elif self.current_tab == 8:
+                self._render_faults_tab(snapshot)
         except curses.error:
             pass
 
@@ -603,9 +617,27 @@ class TUICore:
             self.stdscr.addstr(13, 4, f"{'Device UID':<22} {uid or 'N/A'}")
             self.stdscr.addstr(14, 4, f"{'Firmware Version':<22} {fw_str}")
 
-            self._draw_section(16, 2, "TUI")
+            # Quick-glance active-fault warning (BL2 fw05+ only; nothing is
+            # drawn for ORIGINAL devices or pre-fw05 BL2, where FaultStatus
+            # is simply absent from sensor_data). Full per-fault detail,
+            # including latched history, lives on the Faults tab.
+            sd = snapshot.get('sensor_data') or {}
+            if variant == 'BL2' and sd.get('FaultStatus') is not None:
+                active_faults = _decode_faults(sd.get('FaultStatus'))
+                if active_faults:
+                    names = ", ".join(active_faults)
+                    msg = f"Active Faults: {names}"
+                    width = self.stdscr.getmaxyx()[1]
+                    if len(msg) > width - 5:
+                        msg = (f"{len(active_faults)} active "
+                               f"fault(s) — see Faults tab")
+                    self.stdscr.addstr(
+                        16, 4, msg,
+                        curses.color_pair(Config.COLOR_PAIRS['error']))
+
+            self._draw_section(18, 2, "TUI")
             self.stdscr.addstr(
-                17, 4, f"{'Refresh Interval':<22} {refresh_interval} s")
+                19, 4, f"{'Refresh Interval':<22} {refresh_interval} s")
 
         except curses.error:
             pass
@@ -1216,6 +1248,83 @@ class TUICore:
             except curses.error:
                 pass
 
+    def _render_faults_tab(self, snapshot: Dict[str, Any]):
+        """Render Faults tab — all 34 BL2 Fault enum members, live/latched."""
+        self._draw_section(4, 2, "Fault Monitoring (BL2)")
+
+        if not snapshot.get('connected'):
+            self._draw_disconnected("Fault")
+            return
+
+        sd = snapshot.get('sensor_data') or {}
+        device_info = snapshot.get('device_info') or {}
+        product_id = device_info.get('ProductId')
+        variant = device_info.get('variant')
+        if variant is None:
+            variant = 'BL2' if product_id == 0x11 else 'ORIGINAL'
+
+        if variant != 'BL2' or sd.get('FaultStatus') is None:
+            try:
+                self.stdscr.addstr(
+                    6, 4,
+                    "Fault data unavailable for this device "
+                    "(BL2 firmware 05+ required).",
+                    curses.color_pair(Config.COLOR_PAIRS['default']))
+            except curses.error:
+                pass
+            return
+
+        fault_status = int(sd.get('FaultStatus') or 0)
+        fault_log = int(sd.get('FaultLog') or 0)
+        cols = Config.Layout.FAULT_COLS
+        rows_per_col = Config.Layout.FAULT_ROWS_PER_COL
+
+        try:
+            hdr = f"{'Fault':<22} {'Active':<8} {'Logged':<8}"
+            self.stdscr.addstr(
+                5, cols['NAME'], hdr,
+                curses.A_UNDERLINE | curses.color_pair(
+                    Config.COLOR_PAIRS['default']))
+            self.stdscr.addstr(
+                5, cols['NAME2'], hdr,
+                curses.A_UNDERLINE | curses.color_pair(
+                    Config.COLOR_PAIRS['default']))
+        except curses.error:
+            pass
+
+        faults = list(Fault)
+        for i, fault in enumerate(faults):
+            col_idx = i // rows_per_col
+            row = 6 + (i % rows_per_col)
+            name_col = cols['NAME'] if col_idx == 0 else cols['NAME2']
+            active_col = cols['ACTIVE'] if col_idx == 0 else cols['ACTIVE2']
+            logged_col = cols['LOGGED'] if col_idx == 0 else cols['LOGGED2']
+
+            is_active = bool(fault_status & (1 << fault.value))
+            is_logged = bool(fault_log & (1 << fault.value))
+
+            active_str = "ACTIVE" if is_active else "OK"
+            active_color = (
+                Config.COLOR_PAIRS['error'] if is_active
+                else Config.COLOR_PAIRS['ok'])
+            logged_str = "YES" if is_logged else "-"
+            logged_color = (
+                Config.COLOR_PAIRS['caution'] if is_logged
+                else Config.COLOR_PAIRS['default'])
+
+            try:
+                self.stdscr.addstr(
+                    row, name_col, f"{fault.name:<22}",
+                    curses.color_pair(Config.COLOR_PAIRS['default']))
+                self.stdscr.addstr(
+                    row, active_col, f"{active_str:<8}",
+                    curses.color_pair(active_color))
+                self.stdscr.addstr(
+                    row, logged_col, f"{logged_str:<8}",
+                    curses.color_pair(logged_color))
+            except curses.error:
+                pass
+
     # ═══════════════════════════════════════════════════════════════════════════════
     #  Helper Methods
     # ═══════════════════════════════════════════════════════════════════════════════