benchlab-pytools 3.0.4__tar.gz → 3.2.0__tar.gz

{benchlab_pytools-3.0.4 → benchlab_pytools-3.2.0}/CHANGELOG.md

@@ -4,6 +4,63 @@ 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.2.0] - 2026-09-29
+
+### Added
+- `GET /events` WebSocket on the FastAPI server (`benchlab.restapi.telemetry_api`):
+  a multiplexed event stream matching the frame envelope of the C# BenchLab
+  service's `/events` (`hello`/`telemetry`/`device` frames), so
+  `ServiceWsDataSource` (`--source service_ws`) can point at either server.
+  `telemetry.v` keeps pytools' own TUI-style sensor-key names (e.g.
+  `EPS1_Power`) rather than the C# service's `ShortName` convention (e.g.
+  `EPS1_P`) -- there's no pycore equivalent of `ShortName` to translate
+  into, and `ServiceWsDataSource`'s key mapping already passes unrecognised
+  keys through unchanged, so no client-side changes are needed. The
+  existing per-device `/device/{uid}/stream` WebSocket is unchanged.
+- `ConfigClient.factory_cal_unlock()` (`direct` and `named_pipe` sources):
+  temporarily lifts write-protection on BL2's factory calibration slot
+  (BL2 firmware 7+ only). Disruptive -- a successful call resets the
+  device immediately; reconnect before issuing further commands.
+
+### Changed
+- Bumped the `benchlab-pycore` floor to `>=0.8.0` (from `>=0.6.0`).
+  0.8.0 fixes `write_calibration()`'s wire format on BL1 firmware 6+ /
+  BL2 firmware 7+, where `WRITE_CALIBRATION` changed from an
+  offset-addressed partial write to a whole-struct replace; sending the
+  old format there silently corrupts calibration data.
+  `DirectConfigClient.write_calibration()` was already firmware-agnostic
+  (it doesn't pass `fw_version`, so pycore auto-probes it), so no code
+  change was needed here beyond the floor bump. Companion release:
+  BENCHLAB_Service v2.6.0, which adds the same `FACTORY_CAL_UNLOCK`
+  command plus BL1/BL2 firmware compatibility and a stuck-disconnect
+  reconnect fix.
+
+### Fixed
+- TUI: a disconnected remote data source (`fastapi_custom`, `mqtt_custom`,
+  `named_pipe`, `service_http`, `service_ws`, etc.) fell back to scanning
+  local serial ports for the Fleet view, which could probe ports already
+  owned by another collector and show unrelated local devices instead of
+  an empty fleet. (#74)
+- TUI: the terminal-too-small warning was drawn but never flushed to the
+  screen before `render()` returned, leaving the terminal blank instead
+  of showing the warning. (#75)
+- Packaging: `benchlab-pytools[tui]` was missing `pydantic` and `requests`,
+  both required to initialize an HTTP-backed TUI (`fastapi`/`service_http`
+  sources); a clean `[tui]`-only install crashed with `ModuleNotFoundError`
+  unless the server/all extras happened to already pull them in. (#76)
+
+## [3.1.0] - 2026-09-08
+
+### Added
+- `service_ws` data source: consumes the BENCHLAB service `/events`
+  WebSocket event stream (added in the C# service's PR #76). Telemetry is
+  pushed at the service's own poll cadence rather than polled, and device
+  connect/disconnect is reflected without a manual rescan. Output is
+  normalized to the same shape as `service_http`. New CLI flags
+  `--service-ws-url` (default `ws://localhost:8585/events`) and
+  `--service-token`; new optional-dependency group
+  `benchlab-pytools[service_ws]` (`websockets`).
+
 ## [3.0.4] - 2026-08-18
 
 ### Fixed
@@ -100,8 +157,10 @@ Snapshot of the codebase at the point packaging work began. Interactive
 menu (prompt_toolkit-based), TUI, CSV logger, FastAPI server, graph, HWiNFO
 export, MQTT publisher, VU dials, WigiDash, and config import/export tools,
 sharing a common data-source layer (direct serial, FastAPI, MQTT, named
-pipe, service HTTP).
+pipe, service HTTP, service WebSocket).
 
+[3.2.0]: https://github.com/BenchLab-io/benchlab-pytools/compare/v3.1.0...v3.2.0
+[3.1.0]: https://github.com/BenchLab-io/benchlab-pytools/compare/v3.0.4...v3.1.0
 [3.0.4]: https://github.com/BenchLab-io/benchlab-pytools/compare/v3.0.3...v3.0.4
 [3.0.3]: https://github.com/BenchLab-io/benchlab-pytools/compare/v3.0.2...v3.0.3
 [3.0.2]: https://github.com/BenchLab-io/benchlab-pytools/compare/v3.0.1...v3.0.2

{benchlab_pytools-3.0.4 → benchlab_pytools-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: benchlab-pytools
-Version: 3.0.4
+Version: 3.2.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,15 +22,15 @@ 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: benchlab-pycore>=0.8.0
 Requires-Dist: packaging<26.0,>=23.0
-Requires-Dist: python-dotenv<2.0,>=1.0.0
+Requires-Dist: python-dotenv<2.0,>=1.2.2
 Requires-Dist: pywin32>=306; platform_system == 'Windows'
 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: benchlab-pycore>=0.8.0; 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'
@@ -43,16 +43,18 @@ 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: python-dotenv==1.2.2; 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: requests>=2.33.1; extra == 'all'
 Requires-Dist: ruamel-yaml; extra == 'all'
 Requires-Dist: tornado; extra == 'all'
 Requires-Dist: uvicorn[standard]==0.24.0; extra == 'all'
+Requires-Dist: websockets<16.0,>=13.0; extra == 'all'
 Provides-Extra: csv-log
-Requires-Dist: benchlab-pycore>=0.5.1; extra == 'csv-log'
+Requires-Dist: benchlab-pycore>=0.8.0; extra == 'csv-log'
 Requires-Dist: pyserial>=3.5; extra == 'csv-log'
 Provides-Extra: graph
 Requires-Dist: dearpygui>=2.1.1; extra == 'graph'
@@ -67,10 +69,14 @@ 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: python-dotenv==1.2.2; extra == 'restapi'
 Requires-Dist: uvicorn[standard]==0.24.0; extra == 'restapi'
+Provides-Extra: service-ws
+Requires-Dist: websockets<16.0,>=13.0; extra == 'service-ws'
 Provides-Extra: tui
+Requires-Dist: pydantic>=2.0.0; extra == 'tui'
 Requires-Dist: pyserial>=3.5; extra == 'tui'
+Requires-Dist: requests>=2.33.1; extra == 'tui'
 Provides-Extra: vu
 Requires-Dist: blessed>=1.20.0; extra == 'vu'
 Requires-Dist: numpy; extra == 'vu'
@@ -186,17 +192,29 @@ Most tools accept `--source` to choose where telemetry comes from:
 | `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`) |
+| `service_http` | BENCHLAB service HTTP API (polling) — requires `--service-url` (default `http://localhost:8585`) |
+| `service_ws` | BENCHLAB service WebSocket event stream (`/events`, push) — requires `--service-ws-url` (default `ws://localhost:8585/events`); needs the `service_ws` extra |
+
+`service_ws` consumes the same BENCHLAB service as `service_http` but over its
+`/events` WebSocket: telemetry is pushed at the service's own cadence instead of
+polled, and device connect/disconnect is reflected without a manual rescan.
+Install its dependency with `pip install "benchlab-pytools[service_ws]"`.
+The pytools FastAPI server (`fastapi`/`fastapi_custom`) also exposes an
+`/events` endpoint with the same frame envelope, so `--source service_ws
+--service-ws-url ws://<fastapi-host>:<port>/events` works against it too —
+see `benchlab/restapi/readme.md`.
 
 Common connection flags:
 
 ```
---source SOURCE          direct | fastapi | fastapi_custom | mqtt | mqtt_custom | named_pipe | service_http
+--source SOURCE          direct | fastapi | fastapi_custom | mqtt | mqtt_custom | named_pipe | service_http | service_ws
 --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)
+--service-url URL          BENCHLAB service HTTP API URL (default: http://localhost:8585)
+--service-ws-url URL       BENCHLAB service WebSocket event stream URL (default: ws://localhost:8585/events)
+--service-token TOKEN      X-Benchlab-Token for the BENCHLAB service (only if token auth is enabled)
 -i, --interval SECONDS     Refresh interval (default: 1.0)
 ```
 

{benchlab_pytools-3.0.4 → benchlab_pytools-3.2.0}/README.md

@@ -95,17 +95,29 @@ Most tools accept `--source` to choose where telemetry comes from:
 | `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`) |
+| `service_http` | BENCHLAB service HTTP API (polling) — requires `--service-url` (default `http://localhost:8585`) |
+| `service_ws` | BENCHLAB service WebSocket event stream (`/events`, push) — requires `--service-ws-url` (default `ws://localhost:8585/events`); needs the `service_ws` extra |
+
+`service_ws` consumes the same BENCHLAB service as `service_http` but over its
+`/events` WebSocket: telemetry is pushed at the service's own cadence instead of
+polled, and device connect/disconnect is reflected without a manual rescan.
+Install its dependency with `pip install "benchlab-pytools[service_ws]"`.
+The pytools FastAPI server (`fastapi`/`fastapi_custom`) also exposes an
+`/events` endpoint with the same frame envelope, so `--source service_ws
+--service-ws-url ws://<fastapi-host>:<port>/events` works against it too —
+see `benchlab/restapi/readme.md`.
 
 Common connection flags:
 
 ```
---source SOURCE          direct | fastapi | fastapi_custom | mqtt | mqtt_custom | named_pipe | service_http
+--source SOURCE          direct | fastapi | fastapi_custom | mqtt | mqtt_custom | named_pipe | service_http | service_ws
 --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)
+--service-url URL          BENCHLAB service HTTP API URL (default: http://localhost:8585)
+--service-ws-url URL       BENCHLAB service WebSocket event stream URL (default: ws://localhost:8585/events)
+--service-token TOKEN      X-Benchlab-Token for the BENCHLAB service (only if token auth is enabled)
 -i, --interval SECONDS     Refresh interval (default: 1.0)
 ```
 

{benchlab_pytools-3.0.4 → benchlab_pytools-3.2.0}/benchlab/__init__.py

@@ -2,4 +2,4 @@
 BENCHLAB Telemetry Package
 """
 
-__version__ = "3.0.4"
+__version__ = "3.2.0"

{benchlab_pytools-3.0.4 → benchlab_pytools-3.2.0}/benchlab/config/README.md

@@ -315,6 +315,21 @@ manager.export_config('COM4', 'output.json')
 manager.import_config('input.json', dry_run=False)
 ```
 
+For lower-level access (used internally by `ConfigManager`), `create_config_client()`
+returns a `ConfigClient` with `read_calibration()`/`write_calibration()`,
+`save_config()`/`load_config()`/`reset_config()`, and (BL2 firmware 7+ only)
+`factory_cal_unlock()`, which temporarily lifts write-protection on the factory
+calibration slot. There is no CLI/JSON-config surface for `factory_cal_unlock()` —
+it's a niche factory-calibration tool, not a user-facing config option, and a
+successful call resets the device immediately:
+
+```python
+from benchlab.config.config_client import create_config_client
+
+client = create_config_client('direct', 'COM4')
+client.factory_cal_unlock()  # BL2 fw7+ only; device resets on success
+```
+
 ## See Also
 
 - [BENCHLAB PyTools Documentation](../../README.md) - Main PyTools documentation

{benchlab_pytools-3.0.4 → benchlab_pytools-3.2.0}/benchlab/config/config_client.py

@@ -149,6 +149,17 @@ class ConfigClient(ABC):
         """Reset configuration to factory defaults."""
         pass
 
+    @abstractmethod
+    def factory_cal_unlock(self) -> bool:
+        """Temporarily lift write-protection on BL2's factory calibration
+        slot (BL2 fw07+ only; rejected on ORIGINAL or older BL2 firmware).
+
+        Disruptive: a successful call resets the device immediately -- the
+        connection drops and must be reestablished before sending further
+        commands.
+        """
+        pass
+
     @abstractmethod
     def close(self):
         """Close connection and cleanup resources."""
@@ -414,20 +425,53 @@ class DirectConfigClient(ConfigClient):
             calibration=cal,
             product_id=self.product_id)
 
+    # CONFIG_ACTION_* codes for UART_CMD_ACTION (opcode 2), the command
+    # firmware actually implements. pycore's old save_config/load_config/
+    # reset_config sent UART_CMD_NVM_CONFIG (opcode 17) and friends -- opcodes
+    # no released or in-development firmware handles -- and were removed in
+    # pycore 0.6.0. See benchlab-pycore issue #11.
+    _CONFIG_ACTION_SAVE = 0
+    _CONFIG_ACTION_LOAD = 1
+    _CONFIG_ACTION_RESET = 2
+
     def save_config(self) -> bool:
         """Save configuration to device flash."""
-        from benchlab_pycore.core.config_io import save_config
-        return save_config(self.ser)
+        from benchlab_pycore.core import send_action
+        return send_action(self.ser, action=self._CONFIG_ACTION_SAVE)
 
     def load_config(self) -> bool:
         """Load configuration from device flash."""
-        from benchlab_pycore.core.config_io import load_config
-        return load_config(self.ser)
+        from benchlab_pycore.core import send_action
+        return send_action(self.ser, action=self._CONFIG_ACTION_LOAD)
 
     def reset_config(self) -> bool:
         """Reset configuration to factory defaults."""
-        from benchlab_pycore.core.config_io import reset_config
-        return reset_config(self.ser)
+        from benchlab_pycore.core import send_action
+        return send_action(self.ser, action=self._CONFIG_ACTION_RESET)
+
+    def factory_cal_unlock(self) -> bool:
+        """Temporarily lift write-protection on BL2's factory calibration
+        slot. BL2 fw07+ only -- rejected on ORIGINAL or older BL2 firmware.
+
+        Disruptive: a successful call resets the device immediately -- the
+        USB CDC port drops and re-enumerates, so callers must reconnect
+        before sending any further command.
+        """
+        from benchlab_pycore.core import (
+            factory_cal_unlock, BENCHLAB_BL2_PRODUCT_ID)
+
+        # pycore's factory_cal_unlock() only reports whether the passphrase
+        # bytes were written to the serial port, not whether the firmware
+        # accepted them -- ORIGINAL and older BL2 firmware silently ignore
+        # the unknown opcode with no ACK either way. Gate on product_id
+        # ourselves so callers get an honest False instead of a misleading
+        # True on hardware where the unlock can never actually take effect.
+        if self.product_id != BENCHLAB_BL2_PRODUCT_ID:
+            logger.warning(
+                "factory_cal_unlock: not a BL2 device, refusing to send "
+                "(unknown opcode on ORIGINAL firmware)")
+            return False
+        return factory_cal_unlock(self.ser)
 
     def close(self):
         """Close serial connection."""
@@ -602,6 +646,17 @@ class NamedPipeConfigClient(ConfigClient):
         result = self._send_command("ResetConfig")
         return result and result.get('success', False)
 
+    def factory_cal_unlock(self) -> bool:
+        """Temporarily lift write-protection on BL2's factory calibration
+        slot. BL2 fw07+ only -- rejected on ORIGINAL or older BL2 firmware.
+
+        Disruptive: a successful call resets the device immediately -- the
+        pipe and COM port disconnect, so callers must reconnect before
+        sending any further command.
+        """
+        result = self._send_command("SendFactoryCalUnlock", payload="benchlab")
+        return result and result.get('success', False)
+
     def close(self):
         """Close pipe connection."""
         self._close_pipe()

benchlab_pytools-3.2.0/benchlab/config/test_config_client.py

@@ -0,0 +1,252 @@
+"""Non-hardware regression tests for benchlab.config.config_client.
+
+Covers the BL2 vs Original calibration struct selection bug fixed in the
+config bug sweep (issue #32): write_calibration used to always reconstruct
+a plain CalibrationStruct (Original, 4 temp sensors) regardless of the
+connected device's actual product_id, even though benchlab-pycore has a
+distinct CalibrationStructBL2 (8 temp sensors) for BL2 devices and
+read_calibration already selected the right one. Uses the real
+benchlab-pycore struct types (a hard dependency of this module) but no
+real serial device -- write_calibration is invoked directly on an instance
+built without going through __init__'s serial connection.
+"""
+
+from benchlab.config.config_client import DirectConfigClient
+from benchlab_pycore.core import (
+    CalibrationStruct, CalibrationStructBL2,
+    BENCHLAB_BL2_PRODUCT_ID, BENCHLAB_ORIGINAL_PRODUCT_ID,
+)
+import pytest
+
+pytest.importorskip("benchlab_pycore")
+
+
+def _make_client(product_id):
+    """Construct a DirectConfigClient without running __init__ (which opens
+    a real serial connection) -- just set the attributes write_calibration
+    actually needs."""
+    client = DirectConfigClient.__new__(DirectConfigClient)
+    client.product_id = product_id
+    client.ser = None
+    return client
+
+
+def test_write_calibration_selects_bl2_struct_for_bl2_device(monkeypatch):
+    """Regression test: BL2-shaped calibration data (8 temp sensors) used
+    to be forced into the Original 4-sensor struct, raising IndexError."""
+    client = _make_client(BENCHLAB_BL2_PRODUCT_ID)
+
+    captured = {}
+
+    def fake_write_calibration(ser, calibration, product_id=None):
+        captured["struct_type"] = type(calibration)
+        return True
+    monkeypatch.setattr(
+        "benchlab_pycore.core.write_calibration",
+        fake_write_calibration)
+
+    cal_dict = {
+        "Crc": 0,
+        # BL2 has 8 sensors
+        "Ts": [{"Offset": i, "GainOffset": 0} for i in range(8)],
+    }
+
+    result = client.write_calibration(cal_dict)
+
+    assert result is True
+    assert captured["struct_type"] is CalibrationStructBL2
+
+
+def test_write_calibration_selects_original_struct_for_original_device(
+        monkeypatch):
+    client = _make_client(BENCHLAB_ORIGINAL_PRODUCT_ID)
+
+    captured = {}
+
+    def fake_write_calibration(ser, calibration, product_id=None):
+        captured["struct_type"] = type(calibration)
+        return True
+    monkeypatch.setattr(
+        "benchlab_pycore.core.write_calibration",
+        fake_write_calibration)
+
+    cal_dict = {
+        "Crc": 0,
+        # Original has 4 sensors
+        "Ts": [{"Offset": i, "GainOffset": 0} for i in range(4)],
+    }
+
+    result = client.write_calibration(cal_dict)
+
+    assert result is True
+    assert captured["struct_type"] is CalibrationStruct
+
+
+def test_write_calibration_bl2_data_no_longer_raises_indexerror():
+    """Directly reproduces the original bug scenario: reconstructing
+    8-sensor calibration data now succeeds when the client knows it's
+    talking to a BL2 device, instead of raising IndexError against the
+    4-sensor Original struct."""
+    client = _make_client(BENCHLAB_BL2_PRODUCT_ID)
+
+    cal_dict = {
+        "Crc": 0,
+        "Ts": [{"Offset": i, "GainOffset": 0} for i in range(8)],
+    }
+
+    # _dict_to_struct is the piece that previously raised IndexError when
+    # forced into the wrong (4-sensor) struct type; call it directly with
+    # the now-correct struct type to confirm reconstruction succeeds.
+    struct_type = (
+        CalibrationStructBL2
+        if client.product_id == BENCHLAB_BL2_PRODUCT_ID
+        else CalibrationStruct
+    )
+    result = client._dict_to_struct(cal_dict, struct_type)
+
+    assert len(result.Ts) == 8
+
+
+# ---------------------------------------------------------------------------
+# save_config / load_config / reset_config -- issue #68
+#
+# benchlab-pycore 0.6.0 removed config_io.save_config/load_config/reset_config
+# (they sent UART_CMD_NVM_CONFIG and friends, opcodes no released or
+# in-development firmware implements -- see benchlab-pycore#11). These three
+# methods now route through send_action(), which mirrors UART_CMD_ACTION
+# (opcode 2), the command firmware actually implements for save/load/reset.
+# ---------------------------------------------------------------------------
+
+def test_save_config_sends_the_save_action(monkeypatch):
+    client = _make_client(BENCHLAB_ORIGINAL_PRODUCT_ID)
+    captured = {}
+
+    def fake_send_action(ser, action):
+        captured["action"] = action
+        return True
+    monkeypatch.setattr("benchlab_pycore.core.send_action", fake_send_action)
+
+    assert client.save_config() is True
+    assert captured["action"] == 0  # CONFIG_ACTION_SAVE
+
+
+def test_load_config_sends_the_load_action(monkeypatch):
+    client = _make_client(BENCHLAB_ORIGINAL_PRODUCT_ID)
+    captured = {}
+
+    def fake_send_action(ser, action):
+        captured["action"] = action
+        return True
+    monkeypatch.setattr("benchlab_pycore.core.send_action", fake_send_action)
+
+    assert client.load_config() is True
+    assert captured["action"] == 1  # CONFIG_ACTION_LOAD
+
+
+def test_reset_config_sends_the_reset_action(monkeypatch):
+    client = _make_client(BENCHLAB_ORIGINAL_PRODUCT_ID)
+    captured = {}
+
+    def fake_send_action(ser, action):
+        captured["action"] = action
+        return True
+    monkeypatch.setattr("benchlab_pycore.core.send_action", fake_send_action)
+
+    assert client.reset_config() is True
+    assert captured["action"] == 2  # CONFIG_ACTION_RESET
+
+
+def test_save_config_propagates_a_failed_send(monkeypatch):
+    """send_action returning False (e.g. another action already pending on
+    the device) must surface as a failed save, not be swallowed."""
+    client = _make_client(BENCHLAB_ORIGINAL_PRODUCT_ID)
+    monkeypatch.setattr(
+        "benchlab_pycore.core.send_action", lambda ser, action: False)
+
+    assert client.save_config() is False
+
+
+# ---------------------------------------------------------------------------
+# factory_cal_unlock -- benchlab-pycore 0.8.0 / BENCHLAB_Service 2.6.0
+#
+# New BL2 fw07+ only command that temporarily lifts write-protection on the
+# factory calibration slot. Disruptive (resets the device on success), but
+# from this client's perspective it's a thin pass-through: DirectConfigClient
+# calls pycore's factory_cal_unlock(ser); NamedPipeConfigClient sends the
+# SendFactoryCalUnlock pipe command with the fixed passphrase payload.
+# ---------------------------------------------------------------------------
+
+def test_direct_factory_cal_unlock_calls_pycore(monkeypatch):
+    client = _make_client(BENCHLAB_BL2_PRODUCT_ID)
+    captured = {}
+
+    def fake_factory_cal_unlock(ser):
+        captured["called"] = True
+        return True
+    monkeypatch.setattr(
+        "benchlab_pycore.core.factory_cal_unlock", fake_factory_cal_unlock)
+
+    assert client.factory_cal_unlock() is True
+    assert captured["called"] is True
+
+
+def test_direct_factory_cal_unlock_refuses_non_bl2_device(monkeypatch):
+    """pycore's factory_cal_unlock() only reports whether bytes were
+    written, not whether the firmware accepted them -- confirmed against
+    real BL1 hardware, which returns True even though the opcode is
+    unknown on ORIGINAL firmware and nothing happens. Gate on product_id
+    ourselves so callers get an honest False."""
+    client = _make_client(BENCHLAB_ORIGINAL_PRODUCT_ID)
+    captured = {}
+
+    def fake_factory_cal_unlock(ser):
+        captured["called"] = True
+        return True
+    monkeypatch.setattr(
+        "benchlab_pycore.core.factory_cal_unlock", fake_factory_cal_unlock)
+
+    assert client.factory_cal_unlock() is False
+    assert "called" not in captured
+
+
+def test_direct_factory_cal_unlock_propagates_a_failed_call(monkeypatch):
+    client = _make_client(BENCHLAB_BL2_PRODUCT_ID)
+    monkeypatch.setattr(
+        "benchlab_pycore.core.factory_cal_unlock", lambda ser: False)
+
+    assert client.factory_cal_unlock() is False
+
+
+def test_named_pipe_factory_cal_unlock_sends_command_and_passphrase(
+        monkeypatch):
+    from benchlab.config.config_client import NamedPipeConfigClient
+
+    client = NamedPipeConfigClient.__new__(NamedPipeConfigClient)
+    client.pipe_name = "BenchlabSensorPipe_11_TEST"
+    client.handle = None
+
+    captured = {}
+
+    def fake_send_command(command, payload=None):
+        captured["command"] = command
+        captured["payload"] = payload
+        return {"success": True}
+    monkeypatch.setattr(client, "_send_command", fake_send_command)
+
+    assert client.factory_cal_unlock() is True
+    assert captured["command"] == "SendFactoryCalUnlock"
+    assert captured["payload"] == "benchlab"
+
+
+def test_named_pipe_factory_cal_unlock_propagates_a_failed_call(monkeypatch):
+    from benchlab.config.config_client import NamedPipeConfigClient
+
+    client = NamedPipeConfigClient.__new__(NamedPipeConfigClient)
+    client.pipe_name = "BenchlabSensorPipe_11_TEST"
+    client.handle = None
+
+    monkeypatch.setattr(
+        client, "_send_command",
+        lambda command, payload=None: {"success": False})
+
+    assert client.factory_cal_unlock() is False

{benchlab_pytools-3.0.4 → benchlab_pytools-3.2.0}/benchlab/core/README.md

@@ -27,8 +27,9 @@ A **DataSource abstraction layer** (`datasource.py`) with multiple implementatio
 | `MQTTDataSource` | `mqtt` / `mqtt_custom` | Subscribes to `<topic_prefix>/+/telemetry` and `<topic_prefix>/+/info` on an MQTT broker via `paho-mqtt`. Resolves `MQTT_PROTOCOL` (v3.1 / v3.1.1 / v5) via the module-level `resolve_mqtt_protocol()` helper. |
 | `NamedPipeDataSource` | `named_pipe` | Windows-only. Talks to the C# BENCHLAB Windows service over named pipes (`BenchlabDiscovery` for device listing, per-device `BenchlabSensorPipe_XX_YYY` pipes for telemetry). Normalizes the C# service's `ShortName`-keyed sensor payloads into the same flat key names Python tools expect, via the module-level `_normalise_cs_telemetry()` helper. |
 | `ServiceHttpDataSource` | `service_http` | REST client for the C# BENCHLAB service's HTTP API (default `http://localhost:8585`). Thin client only — does not start/manage the service. Same telemetry normalization as `NamedPipeDataSource`. |
+| `ServiceWsDataSource` | `service_ws` | Client for the C# BENCHLAB service's `/events` WebSocket stream (default `ws://localhost:8585/events`). Runs an asyncio event loop on a background daemon thread; consumes pushed `hello` / `telemetry` / `device` frames (no poll loop). Same telemetry normalization as `ServiceHttpDataSource` (shared `CS_SHORT_NAME_MAP` / `_normalise_cs_v()`). Requires the `websockets` package (`benchlab-pytools[service_ws]`). The pytools FastAPI server (`benchlab.restapi.telemetry_api`) exposes the same `/events` frame envelope, so this class also works unmodified against it — its `telemetry.v` keys are unmapped by `_normalise_cs_v()` since they're already in the target key convention, not the C# `ShortName` one. |
 
-Each implementation validates its constructor kwargs through a Pydantic model in `config.py` (`SerialConfig`, `FastAPIConfig`, `MQTTConfig`, `NamedPipeConfig`, `ServiceHttpConfig`).
+Each implementation validates its constructor kwargs through a Pydantic model in `config.py` (`SerialConfig`, `FastAPIConfig`, `MQTTConfig`, `NamedPipeConfig`, `ServiceHttpConfig`, `ServiceWsConfig`).
 
 The `create_datasource(source_type, **kwargs)` factory function builds the right class:
 
@@ -109,7 +110,7 @@ Also provides `SharedSerialManager`, a singleton connection pool keyed by port w
 
 ### 10. Config models (`config.py`)
 
-Pydantic models validating each DataSource's constructor kwargs: `SerialConfig`, `FastAPIConfig` (normalizes `base_url` to include a scheme and strips trailing slash), `MQTTConfig`, `NamedPipeConfig`, `ServiceHttpConfig`.
+Pydantic models validating each DataSource's constructor kwargs: `SerialConfig`, `FastAPIConfig` (normalizes `base_url` to include a scheme and strips trailing slash), `MQTTConfig`, `NamedPipeConfig`, `ServiceHttpConfig`, `ServiceWsConfig` (normalizes `url` to a `ws://`/`wss://` scheme ending in `/events`).
 
 ## Package exports (`benchlab/core/__init__.py`)
 
@@ -124,7 +125,7 @@ from benchlab.core import (
 )
 ```
 
-`NamedPipeDataSource` and `ServiceHttpDataSource` live in `datasource.py` but aren't re-exported from `__init__.py`; import them directly from `benchlab.core.datasource` if needed. `BENCHLAB_ORIGINAL_PRODUCT_ID` / `BENCHLAB_BL2_PRODUCT_ID` are re-exported from `benchlab_pycore` (with a fallback to hardcoded `0x10`/`0x11` if pycore isn't installed) so tools can detect device variant without importing pycore directly.
+`NamedPipeDataSource`, `ServiceHttpDataSource`, and `ServiceWsDataSource` live in `datasource.py` but aren't re-exported from `__init__.py`; import them directly from `benchlab.core.datasource` if needed. `BENCHLAB_ORIGINAL_PRODUCT_ID` / `BENCHLAB_BL2_PRODUCT_ID` are re-exported from `benchlab_pycore` (with a fallback to hardcoded `0x10`/`0x11` if pycore isn't installed) so tools can detect device variant without importing pycore directly.
 
 ## How tools use this
 
@@ -144,6 +145,7 @@ from benchlab.core import (
 | `mqtt` / `mqtt_custom` | Distributed/IoT integration | Pub/sub, works with existing MQTT infra | Requires a broker, more moving parts |
 | `named_pipe` | Windows, alongside the C# BENCHLAB service | Multiple tools, no direct serial management | Windows only, requires the service + pywin32 |
 | `service_http` | Windows, alongside the C# BENCHLAB service | HTTP-based, multi-client | Windows-oriented, requires the service running |
+| `service_ws` | Alongside the C# BENCHLAB service, low-latency updates | Push-based (no poll loop), device connect/disconnect events, multi-client | Requires the service running + `websockets` |
 
 ## See Also