pytesscope 0.2.1__tar.gz

pytesscope-0.2.1/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: pytesscope
+Version: 0.2.1
+Summary: Live pulse viewer and dIdV scope for pytesdaqx
+Author: TESSERACT DAQ developers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pytesdaqx
+Requires-Dist: numpy<2.0,>=1.26
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: qetpy
+Requires-Dist: astropy
+Requires-Dist: PySide6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-qt; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: ni
+Requires-Dist: pytesdaqx[ni]; extra == "ni"
+
+# pytesscope
+
+Live pulse viewer / dIdV scope for [pytesdaqx](../pytesdaqx), migrated and
+refactored from the pulse viewer in `pytesdaq-obsolete`.
+
+## Installation
+
+```bash
+pip install pytesscope
+```
+
+For live acquisition against real NI/PXI hardware, install the `ni` extra
+too:
+
+```bash
+pip install pytesscope[ni]
+```
+
+`nidaqmx` isn't pulled in by a plain install - it's pytesdaqx's own
+optional `ni` extra (plenty of pytesdaqx use, e.g. temperature control or
+signal generators, doesn't touch NI hardware at all), so pytesscope
+doesn't force it on file-replay/`--backend fake` users either. Without it,
+`pytesscope --backend nidaq ...` fails as soon as it tries to actually
+open a device.
+
+## A Qt styling gotcha worth knowing about
+
+A "bare declaration" stylesheet - `widget.setStyleSheet(f"background-color:
+{color};")` with no selector - silently breaks QComboBox popup styling for
+*any* descendant combobox, anywhere in that widget's subtree, even if the
+popup styling itself lives in a completely separate stylesheet (app-level or
+on the combobox directly). Reproduced with a minimal repro outside this
+codebase before fixing it here. Always use `theme.scoped_background(name,
+color)` / `theme.scoped_text_color(name, color)` (with
+`widget.setObjectName(name)` first) instead of a bare declaration - see
+`gui/theme.py` and its usages in `main_window.py`/`display_panel.py`/
+`tools_window.py`/`channel_panel.py` for the pattern.
+
+## Status
+
+Under active development. Current layout:
+
+```
+pytesscope/
+  analysis/       Qt-free analysis pipeline (normalization, PSD, running
+                   average, pileup rejection, dIdV pole fitting)
+
+                   normalize() requires norm_list whenever norm_type != NoNorm
+                   was actually requested; it used to silently skip the
+                   volts-to-amps division when norm_list was missing (e.g. a
+                   failed board/file read) and fall straight through to the
+                   display unit's scale factor - producing a plausible but
+                   wrong number (raw volts read as if it were current,
+                   inflated further by uAmps' 1e6) instead of an error.
+                   Controller.process_frame() catches this (and any other
+                   per-frame analysis error) and reports it via on_status
+                   instead of letting it recur silently on every poll tick.
+
+                   didv_fit()'s data_array_truncated/fit_array add the
+                   trace's baseline back after qetpy's fit (which works on
+                   an AC-only, baseline-subtracted trace internally) -
+                   without this they were zero-centered, which only matched
+                   the *live* running-average trace (never baseline-
+                   subtracted) on the exact frame the fit ran on. Since the
+                   fit overlay is kept and redrawn on later frames too (see
+                   MainWindow._fit_overlay), the overlay would visibly drift
+                   away from the live trace's true DC level afterward.
+
+                   A completed dIdV fit now also pauses the display (like
+                   the old GUI): ControlPanel becomes a 3-state Start/Stop/
+                   Resume button (yellow while paused), the poll timer stops
+                   so the frame holding the fit result stays on screen for
+                   inspection/zooming, and clicking Resume drops the overlay
+                   and continues - without re-arming the data source, since
+                   pausing never told it to stop in the first place.
+  file_board_reader.py  FileBoardReader: BoardReader backed by a recording's
+                   stored per-channel settings (close_loop_norm, preamp_gain,
+                   signal-gen, TES bias) instead of a live board read - the
+                   file-replay equivalent of board_reader.py, wired into
+                   launcher.py's --file path. Without this, Amps/uAmps
+                   selection during file replay had no normalization source
+                   at all (NullBoardReader raised, but normalize()'s old
+                   silent-skip bug masked that as bad numbers rather than a
+                   visible error).
+  acquisition/     Data source adapters over pytesdaqx: LiveSource (NI-DAQ,
+                   via DAQSession/StreamingAcquisitionLoop) and FileSource
+                   (zarr/hdf5 replay, via StreamReader). Both produce a
+                   common Frame (raw ADC codes + calibration coefficients).
+
+                   read_frame() returning None is ambiguous by itself: for
+                   LiveSource it means "nothing new yet, poll again"; for
+                   FileSource it means "recording is over". FileSource
+                   exposes is_exhausted to disambiguate - MainWindow checks
+                   it after every poll and auto-stops with a clear status
+                   message instead of silently going quiet forever (which
+                   read exactly like a freeze). FileSource.start() rewinds
+                   automatically only when already exhausted, so Stop-then-
+                   Start still resumes mid-file rather than always
+                   restarting from the top.
+
+                   Both sources support an optional trace_length_ms knob
+                   (ControlPanel's "Trace Length [ms]" field), but only where
+                   it's physically meaningful: LiveSource.trace_length_supported()
+                   is true only for a continuous-mode measurement, since a
+                   finite/triggered one (dIdV, threshold) has a fixed record
+                   shape - a PXI-locked dIdV trace needs an integer number of
+                   signal-generator periods, which a plain "ms" knob could
+                   violate. FileSource.trace_length_supported() is true only
+                   for a native continuous Zarr stream (raw_shape_model ==
+                   "channel_sample"); HDF5 recordings and finite/trace Zarr
+                   streams have a fixed length baked into the file itself, so
+                   there's nothing to adjust. When supported, FileSource reads
+                   fixed-size partitions via read_partition() instead of
+                   read_next(); LiveSource folds it into adc.read_block_duration
+                   for the next start(). MainWindow re-checks support on every
+                   measurement change and disables the control accordingly.
+  gui/             PySide6 GUI shell: MainWindow composition root plus
+                   ControlPanel (measurement select + start/stop),
+                   ChannelPanel, DisplayPanel (waveform/PSD toggle,
+                   unit/norm controls, matplotlib canvas, dIdV fit overlay),
+                   ToolsPanel (running avg / LP filter / read-from-board /
+                   opens ToolsWindow), and ToolsWindow (dIdV pole-model fit
+                   + pileup-rejection cuts, in a separate top-level window
+                   like the old design). Widgets only emit signals; all
+                   wiring to the Controller lives in MainWindow.
+
+                   ChannelPanel is a vertical list (color swatch + checkbox)
+                   for the first 8 channels, with a "More Channels..."
+                   button opening a scrollable picker dialog for the rest
+                   (channel count isn't hardcoded to 24 - it's however many
+                   channels are passed in). Long names are middle-elided
+                   ("Mv6BandG...insRight", not right-elided, since detector
+                   names often differ only in a suffix) with the full name
+                   in a tooltip; a fixed-cell button grid (the old AI0-AI7
+                   style) doesn't work once names run 20+ characters.
+  controller.py    Qt-free orchestrator wiring a DataSource into the
+                   analysis pipeline. Board reads (normalization, signal
+                   generator, TES bias) go through a BoardReader Protocol,
+                   cached and refreshed only on explicit triggers (channel
+                   change / norm-type change / user action) since they can
+                   be slow.
+  board_reader.py  PytesdaqxBoardReader: concrete BoardReader over
+                   SQUIDService/TESBiasService. Supports "Open Loop" and
+                   "Close Loop" normalization only (OpenLoop PreAmp+FB was
+                   dropped - see module docstring); output_fix_gain/
+                   preamp_fix_gain are assumed 1.0 until pytesdaqx's config
+                   schema grows a place for them (StarCryo SQUID electronics).
+  launcher.py      CLI entry point: `pytesscope --hardware ... --run-setup
+                   ... --acquisition-config ... [--backend nidaq|fake]` for
+                   live acquisition, or `pytesscope --file <acquisition>`
+                   to replay a recorded zarr/hdf5 acquisition. Live vs. file
+                   is chosen once at launch (a CLI arg), not a runtime GUI
+                   toggle - a deliberate simplification now that the
+                   config-driven design resolves channels/measurements from
+                   YAML rather than a device combobox.
+
+                   For live acquisition, also builds a
+                   `pytesdaqx.control.coordinator.ControlCoordinator` (shared
+                   HardwareRegistry with the board reader) and passes it to
+                   `LiveSource`. `LiveSource` sequences a dIdV measurement's
+                   PXI AC drive correctly: arm the AI task first, *then*
+                   start the AO waveform, so the AI's `/ao/StartTrigger`
+                   defines phase zero. `start_measurement_tes_ac` is a no-op
+                   for measurements without a TES-AC waveform block, so this
+                   is always safe to wire up even for background/threshold
+                   runs.
+```
+
+Qt runs headless via `QT_QPA_PLATFORM=offscreen` in tests and in this
+(display-less) dev environment; `pytest-qt`'s `qtbot` fixture drives widget
+interaction in tests without a real display.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Try the GUI shell against the fake backend (no hardware required), using
+pytesdaqx's example configs:
+
+```bash
+QT_QPA_PLATFORM=offscreen pytesscope \
+  --hardware ../pytesdaqx/examples/configuration/basic/hardware_fake.yaml \
+  --run-setup ../pytesdaqx/examples/configuration/basic/run_setup.yaml \
+  --acquisition-config ../pytesdaqx/examples/configuration/basic/acquisition_background.yaml \
+  --backend fake
+```
+
+(Drop `QT_QPA_PLATFORM=offscreen` on a machine with a real display.)
+
+### Real-display runtime gotcha (Linux/conda)
+
+On a conda-managed Linux machine, PySide6's `xcb` platform plugin (needed to
+actually show a window - `offscreen` above doesn't need any of this) can
+fail to start because `libxcb-cursor.so.1` isn't present, and/or because
+Qt's shared libraries in the conda env aren't on the loader's search path.
+If the GUI won't start outside `QT_QPA_PLATFORM=offscreen`, try:
+
+```bash
+conda install -c conda-forge xcb-util-cursor
+export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
+```
+
+(the `export` isn't persistent - add it to the env's activation script, or
+your shell profile, to avoid repeating it every session).

pytesscope-0.2.1/README.md

@@ -0,0 +1,207 @@
+# pytesscope
+
+Live pulse viewer / dIdV scope for [pytesdaqx](../pytesdaqx), migrated and
+refactored from the pulse viewer in `pytesdaq-obsolete`.
+
+## Installation
+
+```bash
+pip install pytesscope
+```
+
+For live acquisition against real NI/PXI hardware, install the `ni` extra
+too:
+
+```bash
+pip install pytesscope[ni]
+```
+
+`nidaqmx` isn't pulled in by a plain install - it's pytesdaqx's own
+optional `ni` extra (plenty of pytesdaqx use, e.g. temperature control or
+signal generators, doesn't touch NI hardware at all), so pytesscope
+doesn't force it on file-replay/`--backend fake` users either. Without it,
+`pytesscope --backend nidaq ...` fails as soon as it tries to actually
+open a device.
+
+## A Qt styling gotcha worth knowing about
+
+A "bare declaration" stylesheet - `widget.setStyleSheet(f"background-color:
+{color};")` with no selector - silently breaks QComboBox popup styling for
+*any* descendant combobox, anywhere in that widget's subtree, even if the
+popup styling itself lives in a completely separate stylesheet (app-level or
+on the combobox directly). Reproduced with a minimal repro outside this
+codebase before fixing it here. Always use `theme.scoped_background(name,
+color)` / `theme.scoped_text_color(name, color)` (with
+`widget.setObjectName(name)` first) instead of a bare declaration - see
+`gui/theme.py` and its usages in `main_window.py`/`display_panel.py`/
+`tools_window.py`/`channel_panel.py` for the pattern.
+
+## Status
+
+Under active development. Current layout:
+
+```
+pytesscope/
+  analysis/       Qt-free analysis pipeline (normalization, PSD, running
+                   average, pileup rejection, dIdV pole fitting)
+
+                   normalize() requires norm_list whenever norm_type != NoNorm
+                   was actually requested; it used to silently skip the
+                   volts-to-amps division when norm_list was missing (e.g. a
+                   failed board/file read) and fall straight through to the
+                   display unit's scale factor - producing a plausible but
+                   wrong number (raw volts read as if it were current,
+                   inflated further by uAmps' 1e6) instead of an error.
+                   Controller.process_frame() catches this (and any other
+                   per-frame analysis error) and reports it via on_status
+                   instead of letting it recur silently on every poll tick.
+
+                   didv_fit()'s data_array_truncated/fit_array add the
+                   trace's baseline back after qetpy's fit (which works on
+                   an AC-only, baseline-subtracted trace internally) -
+                   without this they were zero-centered, which only matched
+                   the *live* running-average trace (never baseline-
+                   subtracted) on the exact frame the fit ran on. Since the
+                   fit overlay is kept and redrawn on later frames too (see
+                   MainWindow._fit_overlay), the overlay would visibly drift
+                   away from the live trace's true DC level afterward.
+
+                   A completed dIdV fit now also pauses the display (like
+                   the old GUI): ControlPanel becomes a 3-state Start/Stop/
+                   Resume button (yellow while paused), the poll timer stops
+                   so the frame holding the fit result stays on screen for
+                   inspection/zooming, and clicking Resume drops the overlay
+                   and continues - without re-arming the data source, since
+                   pausing never told it to stop in the first place.
+  file_board_reader.py  FileBoardReader: BoardReader backed by a recording's
+                   stored per-channel settings (close_loop_norm, preamp_gain,
+                   signal-gen, TES bias) instead of a live board read - the
+                   file-replay equivalent of board_reader.py, wired into
+                   launcher.py's --file path. Without this, Amps/uAmps
+                   selection during file replay had no normalization source
+                   at all (NullBoardReader raised, but normalize()'s old
+                   silent-skip bug masked that as bad numbers rather than a
+                   visible error).
+  acquisition/     Data source adapters over pytesdaqx: LiveSource (NI-DAQ,
+                   via DAQSession/StreamingAcquisitionLoop) and FileSource
+                   (zarr/hdf5 replay, via StreamReader). Both produce a
+                   common Frame (raw ADC codes + calibration coefficients).
+
+                   read_frame() returning None is ambiguous by itself: for
+                   LiveSource it means "nothing new yet, poll again"; for
+                   FileSource it means "recording is over". FileSource
+                   exposes is_exhausted to disambiguate - MainWindow checks
+                   it after every poll and auto-stops with a clear status
+                   message instead of silently going quiet forever (which
+                   read exactly like a freeze). FileSource.start() rewinds
+                   automatically only when already exhausted, so Stop-then-
+                   Start still resumes mid-file rather than always
+                   restarting from the top.
+
+                   Both sources support an optional trace_length_ms knob
+                   (ControlPanel's "Trace Length [ms]" field), but only where
+                   it's physically meaningful: LiveSource.trace_length_supported()
+                   is true only for a continuous-mode measurement, since a
+                   finite/triggered one (dIdV, threshold) has a fixed record
+                   shape - a PXI-locked dIdV trace needs an integer number of
+                   signal-generator periods, which a plain "ms" knob could
+                   violate. FileSource.trace_length_supported() is true only
+                   for a native continuous Zarr stream (raw_shape_model ==
+                   "channel_sample"); HDF5 recordings and finite/trace Zarr
+                   streams have a fixed length baked into the file itself, so
+                   there's nothing to adjust. When supported, FileSource reads
+                   fixed-size partitions via read_partition() instead of
+                   read_next(); LiveSource folds it into adc.read_block_duration
+                   for the next start(). MainWindow re-checks support on every
+                   measurement change and disables the control accordingly.
+  gui/             PySide6 GUI shell: MainWindow composition root plus
+                   ControlPanel (measurement select + start/stop),
+                   ChannelPanel, DisplayPanel (waveform/PSD toggle,
+                   unit/norm controls, matplotlib canvas, dIdV fit overlay),
+                   ToolsPanel (running avg / LP filter / read-from-board /
+                   opens ToolsWindow), and ToolsWindow (dIdV pole-model fit
+                   + pileup-rejection cuts, in a separate top-level window
+                   like the old design). Widgets only emit signals; all
+                   wiring to the Controller lives in MainWindow.
+
+                   ChannelPanel is a vertical list (color swatch + checkbox)
+                   for the first 8 channels, with a "More Channels..."
+                   button opening a scrollable picker dialog for the rest
+                   (channel count isn't hardcoded to 24 - it's however many
+                   channels are passed in). Long names are middle-elided
+                   ("Mv6BandG...insRight", not right-elided, since detector
+                   names often differ only in a suffix) with the full name
+                   in a tooltip; a fixed-cell button grid (the old AI0-AI7
+                   style) doesn't work once names run 20+ characters.
+  controller.py    Qt-free orchestrator wiring a DataSource into the
+                   analysis pipeline. Board reads (normalization, signal
+                   generator, TES bias) go through a BoardReader Protocol,
+                   cached and refreshed only on explicit triggers (channel
+                   change / norm-type change / user action) since they can
+                   be slow.
+  board_reader.py  PytesdaqxBoardReader: concrete BoardReader over
+                   SQUIDService/TESBiasService. Supports "Open Loop" and
+                   "Close Loop" normalization only (OpenLoop PreAmp+FB was
+                   dropped - see module docstring); output_fix_gain/
+                   preamp_fix_gain are assumed 1.0 until pytesdaqx's config
+                   schema grows a place for them (StarCryo SQUID electronics).
+  launcher.py      CLI entry point: `pytesscope --hardware ... --run-setup
+                   ... --acquisition-config ... [--backend nidaq|fake]` for
+                   live acquisition, or `pytesscope --file <acquisition>`
+                   to replay a recorded zarr/hdf5 acquisition. Live vs. file
+                   is chosen once at launch (a CLI arg), not a runtime GUI
+                   toggle - a deliberate simplification now that the
+                   config-driven design resolves channels/measurements from
+                   YAML rather than a device combobox.
+
+                   For live acquisition, also builds a
+                   `pytesdaqx.control.coordinator.ControlCoordinator` (shared
+                   HardwareRegistry with the board reader) and passes it to
+                   `LiveSource`. `LiveSource` sequences a dIdV measurement's
+                   PXI AC drive correctly: arm the AI task first, *then*
+                   start the AO waveform, so the AI's `/ao/StartTrigger`
+                   defines phase zero. `start_measurement_tes_ac` is a no-op
+                   for measurements without a TES-AC waveform block, so this
+                   is always safe to wire up even for background/threshold
+                   runs.
+```
+
+Qt runs headless via `QT_QPA_PLATFORM=offscreen` in tests and in this
+(display-less) dev environment; `pytest-qt`'s `qtbot` fixture drives widget
+interaction in tests without a real display.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Try the GUI shell against the fake backend (no hardware required), using
+pytesdaqx's example configs:
+
+```bash
+QT_QPA_PLATFORM=offscreen pytesscope \
+  --hardware ../pytesdaqx/examples/configuration/basic/hardware_fake.yaml \
+  --run-setup ../pytesdaqx/examples/configuration/basic/run_setup.yaml \
+  --acquisition-config ../pytesdaqx/examples/configuration/basic/acquisition_background.yaml \
+  --backend fake
+```
+
+(Drop `QT_QPA_PLATFORM=offscreen` on a machine with a real display.)
+
+### Real-display runtime gotcha (Linux/conda)
+
+On a conda-managed Linux machine, PySide6's `xcb` platform plugin (needed to
+actually show a window - `offscreen` above doesn't need any of this) can
+fail to start because `libxcb-cursor.so.1` isn't present, and/or because
+Qt's shared libraries in the conda env aren't on the loader's search path.
+If the GUI won't start outside `QT_QPA_PLATFORM=offscreen`, try:
+
+```bash
+conda install -c conda-forge xcb-util-cursor
+export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
+```
+
+(the `export` isn't persistent - add it to the env's activation script, or
+your shell profile, to avoid repeating it every session).

pytesscope-0.2.1/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytesscope"
+version = "0.2.1"
+description = "Live pulse viewer and dIdV scope for pytesdaqx"
+readme = "README.md"
+requires-python = ">=3.11,<3.13"
+authors = [
+  {name = "TESSERACT DAQ developers"}
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "pytesdaqx",
+  "numpy>=1.26,<2.0",
+  "scipy",
+  "matplotlib",
+  "qetpy",
+  "astropy",
+  "PySide6",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pytest-qt",
+  "ruff",
+]
+# nidaqmx isn't a core pytesdaqx dependency - it's pytesdaqx's own optional
+# "ni" extra, since plenty of pytesdaqx use doesn't touch NI hardware at
+# all. pytesscope's live-acquisition path always needs it, though, so
+# expose the same extra here rather than making every install pull in
+# nidaqmx (and require the driver) just to replay a file or use --backend
+# fake.
+ni = [
+  "pytesdaqx[ni]",
+]
+
+[project.scripts]
+pytesscope = "pytesscope.launcher:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pytesscope*"]
+
+[tool.setuptools.package-data]
+pytesscope = ["gui/assets/*.png"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E9", "F", "I"]

pytesscope-0.2.1/pytesscope/__init__.py

@@ -0,0 +1,10 @@
+"""Live pulse viewer and dIdV scope for pytesdaqx."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pytesscope")
+except PackageNotFoundError:  # Source tree imported before installation.
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

pytesscope-0.2.1/pytesscope/acquisition/__init__.py

@@ -0,0 +1,5 @@
+from .base import DataSource, Frame
+from .file_source import FileSource
+from .live_source import LiveSource
+
+__all__ = ["DataSource", "Frame", "FileSource", "LiveSource"]

pytesscope-0.2.1/pytesscope/acquisition/base.py

@@ -0,0 +1,71 @@
+"""Common data-source interface shared by live acquisition and file replay.
+
+Both :class:`~pytesscope.acquisition.live_source.LiveSource` and
+:class:`~pytesscope.acquisition.file_source.FileSource` produce
+:class:`Frame` objects, so the controller and analysis pipeline never need
+to know which one produced a given frame.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+import numpy as np
+
+
+@dataclass
+class Frame:
+    """One event/read-block of raw ADC-code traces, ready for analysis.
+
+    ``data`` is always in raw ADC codes (never pre-calibrated), so
+    :meth:`pytesscope.analysis.pipeline.AnalysisPipeline.process` can
+    treat live and file-replay frames identically via ``calibration_coeffs``.
+    """
+
+    data: np.ndarray  # [nb_channels, nb_samples]
+    detector_channels: list[str]
+    sample_rate_hz: float
+    measurement: str
+    calibration_coeffs: list[list[float] | None] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class DataSource(Protocol):
+    """Common interface for live and file-replay data sources."""
+
+    def start(
+        self,
+        measurement: str,
+        *,
+        overrides: dict[str, Any] | None = None,
+        active_channels: list[str] | None = None,
+    ) -> None:
+        """Begin producing frames for the given measurement.
+
+        ``active_channels``, when given, scopes any step-level hardware
+        control (notably a dIdV measurement's TES AC drive) to just those
+        detector channels rather than every channel configured in
+        run_setup.yaml - e.g. so only the channel(s) selected in the GUI's
+        channel panel actually get their AC waveform turned on. ``None``
+        means "every run channel", matching the underlying pytesdaqx
+        default.
+        """
+        ...
+
+    def read_frame(self, timeout: float | None = 0.0) -> Frame | None:
+        """Return the next available frame.
+
+        ``None`` means "nothing available right now" for a live source
+        (safe to poll again later) or "exhausted" for a file source
+        (nothing more will ever come).
+        """
+        ...
+
+    def stop(self) -> None:
+        """Stop producing frames; safe to call again with :meth:`start`."""
+        ...
+
+    def close(self) -> None:
+        """Release underlying resources; the source cannot be reused after this."""
+        ...