benchlab-pytools 3.1.0__tar.gz → 3.2.1__tar.gz

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/CHANGELOG.md

@@ -4,6 +4,65 @@ 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.1] - 2026-10-01
+
+### Fixed
+- Collector recovery after incomplete sensor reads
+  (`benchlab.restapi.telemetry_api.read_device_loop`): incomplete serial
+  responses (`read_sensors()` returning `None`) are now treated as read
+  failures instead of being silently ignored, so the collector reconnects
+  instead of continuing to publish stale telemetry. The read-error
+  backoff counter now survives serial port reopen attempts and resets
+  only after a successfully decoded sample, restoring the intended
+  retry/backoff policy. A device is marked `connected` only once a
+  sample has actually been decoded, and stale telemetry is cleared
+  before the collector waits to retry. (#77)
+
+## [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
@@ -114,6 +173,8 @@ 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, service WebSocket).
 
+[3.2.1]: https://github.com/BenchLab-io/benchlab-pytools/compare/v3.2.0...v3.2.1
+[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

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: benchlab-pytools
-Version: 3.1.0
+Version: 3.2.1
 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.6.0
+Requires-Dist: benchlab-pycore>=0.8.0
 Requires-Dist: packaging<26.0,>=23.0
 Requires-Dist: python-dotenv<2.0,>=1.2.2
 Requires-Dist: pywin32>=306; platform_system == 'Windows'
@@ -30,7 +30,7 @@ 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.6.0; 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'
@@ -48,12 +48,13 @@ 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.6.0; 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'
@@ -73,7 +74,9 @@ 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'
@@ -196,6 +199,10 @@ Most tools accept `--source` to choose where telemetry comes from:
 `/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:
 

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/README.md

@@ -102,6 +102,10 @@ Most tools accept `--source` to choose where telemetry comes from:
 `/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:
 

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/benchlab/__init__.py

@@ -2,4 +2,4 @@
 BENCHLAB Telemetry Package
 """
 
-__version__ = "3.1.0"
+__version__ = "3.2.1"

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/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.1.0 → benchlab_pytools-3.2.1}/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."""
@@ -438,6 +449,30 @@ class DirectConfigClient(ConfigClient):
         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."""
         if self.ser and self.ser.is_open:
@@ -611,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.1.0 → benchlab_pytools-3.2.1}/benchlab/config/test_config_client.py

@@ -164,3 +164,89 @@ def test_save_config_propagates_a_failed_send(monkeypatch):
         "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.1.0 → benchlab_pytools-3.2.1}/benchlab/core/README.md

@@ -27,7 +27,7 @@ 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]`). |
+| `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`, `ServiceWsConfig`).
 

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/benchlab/csv_log/requirements.txt

@@ -1,3 +1,3 @@
 # benchlab/csv_log/requirements.txt
 pyserial>=3.5
-benchlab-pycore>=0.6.0
+benchlab-pycore>=0.8.0

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/benchlab/requirements.txt

@@ -4,7 +4,7 @@ python-dotenv>=1.2.2,<2.0
 textual>=0.60,<9.0
 
 # BENCHLAB Serial Handler
-benchlab-pycore>=0.6.0
+benchlab-pycore>=0.8.0
 
 # FastAPI Data Source
 fastapi==0.111.1

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/benchlab/restapi/readme.md

@@ -61,6 +61,7 @@ The server will start on `http://0.0.0.0:8000` by default (configurable via `API
 
 ### Real-time Streaming
 - `WebSocket /device/{uid}/stream` - Real-time telemetry updates, pushed as each device's reader thread reads new sensor data
+- `WebSocket /events` - Multiplexed event stream for all devices: a `hello` frame on connect (service version, poll interval, device list), then `telemetry` and `device` (connected/disconnected) frames as they occur. Matches the frame envelope of the C# BENCHLAB service's `/events` (see `ServiceWsDataSource`, `--source service_ws`), so the same client works against either server — except `telemetry.v` keeps this server's own long-form sensor-key names (e.g. `EPS1_Power`) rather than the C# service's `ShortName` convention (e.g. `EPS1_P`).
 
 ### Monitoring
 - `GET /health` - Basic health check (status, platform, timestamp, connected_devices, total_clients)
@@ -131,6 +132,16 @@ ws.onmessage = (event) => {
 };
 ```
 
+### Multiplexed Event Stream (WebSocket)
+```javascript
+const ws = new WebSocket('ws://localhost:8000/events');
+ws.onmessage = (event) => {
+    const frame = JSON.parse(event.data);
+    // frame.type is "hello", "telemetry", or "device"
+    console.log(frame);
+};
+```
+
 ## Production Deployment
 
 ### Docker Support

{benchlab_pytools-3.1.0 → benchlab_pytools-3.2.1}/benchlab/restapi/telemetry_api.py

@@ -14,6 +14,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, JSONResponse
 from pathlib import Path
 
+import benchlab
 from benchlab_pycore.core import (
     read_sensors, read_device, translate_sensor_struct)
 from benchlab.core import (
@@ -86,6 +87,7 @@ api_port = Config.API_PORT
 # { uid: { "port": str, "latest": dict, "history": deque, "connected": bool } }
 devices_data = {}
 clients = {}           # { uid: set([WebSocket, ...]) }
+event_clients = set()  # WebSockets subscribed to the /events stream
 main_loop = None       # Will store main asyncio loop
 shutdown_event = threading.Event()  # Graceful shutdown flag
 device_threads = {}    # { uid: threading.Thread } - device reader threads
@@ -142,9 +144,12 @@ def device_scanner_loop():
                         logger.info(
                             "Device %s appears disconnected "
                             "(port %s not found)", uid, port)
+                        was_connected = data.get("connected", False)
                         with data_lock:
                             if uid in devices_data:
                                 devices_data[uid]["connected"] = False
+                        if was_connected:
+                            schedule_device_event(uid, "disconnected")
 
                 logger.debug("Scanner: scan complete")
 
@@ -277,10 +282,77 @@ async def send_updates(uid, data):
                 clients[uid].discard(ws)
 
 
+async def _broadcast_event(frame):
+    """Push a hello/telemetry/device frame to every /events subscriber."""
+    with data_lock:
+        ws_list = list(event_clients)
+    dead_clients = set()
+    for ws in ws_list:
+        try:
+            await ws.send_json(frame)
+        except Exception:
+            dead_clients.add(ws)
+    if dead_clients:
+        with data_lock:
+            event_clients.difference_update(dead_clients)
+
+
+async def send_event_telemetry(uid, data):
+    """Push a /events "telemetry" frame for this UID's latest reading.
+
+    ``v`` keeps pytools' own TUI-style sensor keys (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 ShortName->TUI-key mapping already passes
+    unrecognised keys through unchanged, so this is a no-op there rather
+    than a translation, but no client-side change is required.
+    """
+    await _broadcast_event({
+        "type": "telemetry",
+        "uid": uid,
+        "ts": data.get("timestamp"),
+        "v": {k: v for k, v in data.items() if k != "timestamp"},
+    })
+
+
 def schedule_update(uid, data):
     """Thread-safe schedule to send telemetry to WebSocket clients."""
     if main_loop is not None and not main_loop.is_closed():
         asyncio.run_coroutine_threadsafe(send_updates(uid, data), main_loop)
+        asyncio.run_coroutine_threadsafe(
+            send_event_telemetry(uid, data), main_loop)
+
+
+def _device_to_wire_shape(uid, info=None):
+    """Shape a device's info the way /events' hello/device frames expect
+    (mirrors the C# service's device shape), independent of GET /devices'
+    own response shape."""
+    if info is None:
+        with data_lock:
+            info = devices_data.get(uid, {})
+    device_info = info.get("info", {}) or {}
+    return {
+        "uid": uid,
+        "name": device_info.get("deviceName", ""),
+        "productId": device_info.get("ProductId", 0),
+        "port": info.get("port", "unknown"),
+        "status": "CONNECTED" if info.get("connected", False) else
+                  "DISCONNECTED",
+        "sensorCount": len(info.get("latest", {}) or {}),
+        "firmwareVersion": device_info.get("FwVersion", 0),
+    }
+
+
+def schedule_device_event(uid, event):
+    """Thread-safe schedule to broadcast a /events "device" frame."""
+    if main_loop is not None and not main_loop.is_closed():
+        frame = {
+            "type": "device",
+            "uid": uid,
+            "event": event,
+            "device": _device_to_wire_shape(uid),
+        }
+        asyncio.run_coroutine_threadsafe(_broadcast_event(frame), main_loop)
 
 
 RECONNECT_DELAY = 2.0  # seconds
@@ -369,29 +441,25 @@ def read_device_loop(port, uid):
     reconnection logic."""
     ser = None
     consecutive_errors = 0
-    max_consecutive_errors = 10  # After this many errors, attempt reconnect
+    max_consecutive_errors = 10  # Back off after repeated read failures
     product_id = None  # Will be set once we read device info
-    is_connected = False  # Track connection status
+    is_connected = False  # Only valid telemetry establishes a connection
+    with data_lock:
+        was_connected = devices_data.get(uid, {}).get("connected", False)
+        if uid in devices_data:
+            devices_data[uid]["connected"] = False
+            devices_data[uid]["latest"] = create_empty_telemetry()
+    if was_connected:
+        schedule_device_event(uid, "disconnected")
 
     while not shutdown_event.is_set():
         # --- (Re)connect ---
         if ser is None:
-            # Mark as disconnected
-            if is_connected:
-                is_connected = False
-                with data_lock:
-                    if uid in devices_data:
-                        devices_data[uid]["connected"] = False
-                        devices_data[uid]["latest"] = create_empty_telemetry()
-                logger.info("[%s] Device disconnected", uid)
-
             try:
                 new_ser = open_serial_connection(port)
                 if new_ser is None:
                     raise OSError("open_serial_connection returned None")
                 ser = new_ser
-                # Reset error counter on successful connect
-                consecutive_errors = 0
 
                 # Read device info to get product_id for sensor reading
                 try:
@@ -408,17 +476,12 @@ def read_device_loop(port, uid):
                 except Exception:
                     pass
 
-                is_connected = True
-                with data_lock:
-                    if uid in devices_data:
-                        devices_data[uid]["connected"] = True
-                logger.info("Connected to device %s on %s", uid, port)
             except Exception as exc:
                 ser = None  # Ensure ser is None on error
                 consecutive_errors += 1
                 delay = min(
                     RECONNECT_DELAY * consecutive_errors,
-                    30)  # Exponential backoff, capped
+                    30)  # Linear backoff, capped
                 logger.warning(
                     "[%s] Failed to open serial port %s: %s (retry in %.1fs)",
                     uid,
@@ -435,6 +498,8 @@ def read_device_loop(port, uid):
                 shutdown_event.wait(1)
                 continue
             sensors = read_sensors(ser, product_id=product_id)
+            if sensors is None:
+                raise OSError("No complete sensor response received")
             if sensors:
                 translated = translate_sensor_struct(sensors)
                 translated["timestamp"] = datetime.now().strftime(
@@ -444,12 +509,15 @@ def read_device_loop(port, uid):
 
                 with data_lock:
                     if uid in devices_data:
+                        devices_data[uid]["connected"] = True
                         devices_data[uid]["latest"] = translated
                         devices_data[uid]["history"].append(translated)
 
+                if not is_connected:
+                    is_connected = True
+                    schedule_device_event(uid, "connected")
+                    logger.info("Connected to device %s on %s", uid, port)
                 schedule_update(uid, translated)
-            else:
-                logger.debug("[%s] No sensor data read", uid)
         except Exception as e:
             consecutive_errors += 1
             # Specific debug logging for unsupported commands
@@ -473,8 +541,18 @@ def read_device_loop(port, uid):
             except Exception:
                 pass
             ser = None
+            was_connected = is_connected
+            if is_connected:
+                logger.info("[%s] Device disconnected", uid)
+            is_connected = False
+            with data_lock:
+                if uid in devices_data:
+                    devices_data[uid]["connected"] = False
+                    devices_data[uid]["latest"] = create_empty_telemetry()
+            if was_connected:
+                schedule_device_event(uid, "disconnected")
 
-            # Exponential backoff with cap
+            # Linear backoff with cap
             if consecutive_errors >= max_consecutive_errors:
                 delay = min(RECONNECT_DELAY * consecutive_errors, 30)
                 logger.warning(
@@ -490,6 +568,7 @@ def read_device_loop(port, uid):
             if uid in devices_data:
                 devices_data[uid]["connected"] = False
                 devices_data[uid]["latest"] = create_empty_telemetry()
+        schedule_device_event(uid, "disconnected")
 
     if ser:
         try:
@@ -627,6 +706,50 @@ async def stream_device(uid: str, ws: WebSocket):
         logger.info("[%s] Client disconnected (%d total)", uid, client_count)
 
 
+def build_hello_frame():
+    """Build the /events "hello" frame sent on connect: service version,
+    poll interval, and the current device list, matching the C# service's
+    /events wire shape."""
+    with data_lock:
+        uids = list(devices_data.keys())
+    return {
+        "type": "hello",
+        "serviceVersion": benchlab.__version__,
+        "pollIntervalMs": int(Config.POLL_INTERVAL * 1000),
+        "devices": [_device_to_wire_shape(uid) for uid in uids],
+    }
+
+
+@app.websocket("/events")
+async def events_stream(ws: WebSocket):
+    """Multiplexed event stream: hello on connect, then telemetry/device
+    frames for every device, matching the C# BenchLab service's /events
+    protocol (see ServiceWsDataSource in benchlab.core.datasource, the
+    consumer this endpoint is meant to be compatible with)."""
+    await ws.accept()
+    with data_lock:
+        event_clients.add(ws)
+    await ws.send_json(build_hello_frame())
+    logger.info("[/events] Client connected (%d total)", len(event_clients))
+    try:
+        while True:
+            msg = await ws.receive_json()
+            if isinstance(msg, dict) and msg.get("type") == "ping":
+                await ws.send_json({
+                    "type": "pong",
+                    "ts": datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
+                })
+            # "subscribe" and any other client message: accepted, no-op --
+            # this endpoint always broadcasts every device to every client.
+    except WebSocketDisconnect:
+        pass
+    finally:
+        with data_lock:
+            event_clients.discard(ws)
+        logger.info(
+            "[/events] Client disconnected (%d total)", len(event_clients))
+
+
 @app.get("/favicon.ico")
 def favicon():
     return FileResponse(Path(__file__).parent / "favicon.ico")
@@ -766,9 +889,12 @@ def scan_for_devices():
                 disconnected.append({"uid": uid, "port": port})
                 logger.info(
                     "Device %s appears to be disconnected from %s", uid, port)
+                was_connected = data.get("connected", False)
                 with data_lock:
                     if uid in devices_data:
                         devices_data[uid]["connected"] = False
+                if was_connected:
+                    schedule_device_event(uid, "disconnected")
 
         result = {
             "scan_time": datetime.now().isoformat(),