cicwave 0.7.2__tar.gz → 0.7.4__tar.gz

{cicwave-0.7.2/src/cicwave.egg-info → cicwave-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cicwave
-Version: 0.7.2
+Version: 0.7.4
 Summary: Advanced waveform viewer with PyQtGraph backend
 Author-email: Carsten Wulff <carsten@wulff.no>
 License: MIT
@@ -35,6 +35,8 @@ Provides-Extra: parquet
 Requires-Dist: pyarrow; extra == "parquet"
 Provides-Extra: hdf5
 Requires-Dist: tables; extra == "hdf5"
+Provides-Extra: audio
+Requires-Dist: soundfile; extra == "audio"
 Provides-Extra: mcp
 Requires-Dist: mcp[cli]; extra == "mcp"
 Dynamic: license-file
@@ -80,8 +82,10 @@ repo. As such, you're here.
   - Pickle (`.pkl`) for cached DataFrames
   - VCD digital waveforms 
   - LitePoint `.iqvsa` IQ capture files
+  - SigMF IQ recordings (`.sigmf-meta` + `.sigmf-data`, or `.sigmf` archives)
   - STDF (`.stdf`, `.stdf.gz`) semiconductor ATE test results
   - Raw `uint32` counter captures (`.u32`) with a JSON sidecar
+  - Audio: `.wav` natively; FLAC, Ogg, AIFF, MP3 with `cicwave[audio]`
   - Statistical formats: Stata (`.dta`), SAS (`.sas7bdat`), SPSS (`.sav`)
 - **URL data sources**: load CSV/JSON/Excel/Parquet/... straight from an
   `http(s)://` URL — REST APIs, hosted datasets, anything pandas can read
@@ -100,6 +104,11 @@ repo. As such, you're here.
 - **GPU-accelerated plotting** for smooth interaction with large datasets
 - **MCP server** (`cicwave-mcp`, optional): plot/analyze tools for an
   agent driving tests to call directly — see [docs](https://wulffern.github.io/cicwave/mcp)
+- **Plugins**: private file formats, annotations, analyses and constellation
+  presets from separately installed packages, listed under Help → Plugins —
+  see [docs](https://wulffern.github.io/cicwave/plugins) and the examples:
+  a UART decoder ([`examples/cicwave-uart`](examples/cicwave-uart)) and a
+  Touchstone reader with Smith chart ([`examples/cicwave-smith`](examples/cicwave-smith))
 
 ## Installation
 
@@ -113,6 +122,12 @@ For the MCP server (agent-driven plotting/analysis; requires Python 3.10+):
 pip install "cicwave[mcp]"
 ```
 
+For FLAC, Ogg, AIFF and MP3 audio (WAV works without it):
+
+```bash
+pip install "cicwave[audio]"
+```
+
 For development installation:
 
 ```bash
@@ -198,8 +213,10 @@ through to the ngspice raw reader, so non-standard suffixes (e.g. `.raw0`,
 | Whitespace text | `.dat`, `.spe`, `.cou`, `.chi` | Eldo `.cou`/`.chi`, ngspice `.dat`, generic space/tab columns; `#` comments stripped by default |
 | VCD | `.vcd` | Value Change Dump — digital simulation waveforms |
 | LitePoint IQ | `.iqvsa` | LitePoint IQxstream / IQfact IQ capture data |
+| SigMF | `.sigmf-meta`, `.sigmf-data`, `.sigmf-data.zip`, `.sigmf` | SigMF recordings (open either half of the pair, or a `.sigmf` archive). A zipped dataset (`<name>.sigmf-data.zip`) is read in place without unpacking. `litepoint:scale` converts counts to analyser units; `litepoint:channel_offset_hz` / `litepoint:spectrum_inverted` put a low-IF capture's FFT on the RF axis. Each recording also gets magnitude views: `mag` (\|iq\|) and `power_dBm` (dBm for LitePoint analyser captures, matching their burst annotations), `power_dBFS` (ADC counts with a stated full scale) or `power_dB`. All `core:datatype`s (`cf32_le`, `ci16_le`, `cu8`, `rf64_be`, …), multi-channel and per-capture header bytes. Gives a complex `iq` column plus `I`/`Q`, a `time` axis from `core:sample_rate`, and the FFT is centred on the first capture's `core:frequency` |
 | STDF | `.stdf`, `.stdf.gz` | Semiconductor ATE test results (SEMI E10/V4) — parametric (PTR) results per part/site, gzip auto-detected |
 | Raw counter | `.u32` | Bare little-endian `uint32` counter records with a `.meta.json` sidecar giving the tick length and periods per sample; converted to Hz or ns on load, with the dead time between capture chunks preserved |
+| Audio | `.wav`, `.flac`, `.ogg`, `.opus`, `.aif`/`.aiff`, `.mp3`, … | Audio recordings. `.wav` is read natively (PCM 8/16/24/32-bit, 32/64-bit float, `WAVE_FORMAT_EXTENSIBLE`, RF64); the other formats need `pip install cicwave[audio]` (soundfile/libsndfile). Samples are in full scale (±1) with a `time` axis in seconds, one column per channel: `audio` (mono), `left`/`right` (stereo) or `ch0`, `ch1`, … The sample rate prefills the FFT and analysis dialogs |
 
 ### Tabular text formats
 
@@ -239,6 +256,7 @@ through to the ngspice raw reader, so non-standard suffixes (e.g. `.raw0`,
 ## Environment Variables
 
 - `CICWAVE_X` - Default X-axis column name
+- `CICWAVE_PLUGINS=0` - Start without loading any [plugins](https://wulffern.github.io/cicwave/plugins)
 
 ## GUI Features
 

{cicwave-0.7.2 → cicwave-0.7.4}/README.md

@@ -39,8 +39,10 @@ repo. As such, you're here.
   - Pickle (`.pkl`) for cached DataFrames
   - VCD digital waveforms 
   - LitePoint `.iqvsa` IQ capture files
+  - SigMF IQ recordings (`.sigmf-meta` + `.sigmf-data`, or `.sigmf` archives)
   - STDF (`.stdf`, `.stdf.gz`) semiconductor ATE test results
   - Raw `uint32` counter captures (`.u32`) with a JSON sidecar
+  - Audio: `.wav` natively; FLAC, Ogg, AIFF, MP3 with `cicwave[audio]`
   - Statistical formats: Stata (`.dta`), SAS (`.sas7bdat`), SPSS (`.sav`)
 - **URL data sources**: load CSV/JSON/Excel/Parquet/... straight from an
   `http(s)://` URL — REST APIs, hosted datasets, anything pandas can read
@@ -59,6 +61,11 @@ repo. As such, you're here.
 - **GPU-accelerated plotting** for smooth interaction with large datasets
 - **MCP server** (`cicwave-mcp`, optional): plot/analyze tools for an
   agent driving tests to call directly — see [docs](https://wulffern.github.io/cicwave/mcp)
+- **Plugins**: private file formats, annotations, analyses and constellation
+  presets from separately installed packages, listed under Help → Plugins —
+  see [docs](https://wulffern.github.io/cicwave/plugins) and the examples:
+  a UART decoder ([`examples/cicwave-uart`](examples/cicwave-uart)) and a
+  Touchstone reader with Smith chart ([`examples/cicwave-smith`](examples/cicwave-smith))
 
 ## Installation
 
@@ -72,6 +79,12 @@ For the MCP server (agent-driven plotting/analysis; requires Python 3.10+):
 pip install "cicwave[mcp]"
 ```
 
+For FLAC, Ogg, AIFF and MP3 audio (WAV works without it):
+
+```bash
+pip install "cicwave[audio]"
+```
+
 For development installation:
 
 ```bash
@@ -157,8 +170,10 @@ through to the ngspice raw reader, so non-standard suffixes (e.g. `.raw0`,
 | Whitespace text | `.dat`, `.spe`, `.cou`, `.chi` | Eldo `.cou`/`.chi`, ngspice `.dat`, generic space/tab columns; `#` comments stripped by default |
 | VCD | `.vcd` | Value Change Dump — digital simulation waveforms |
 | LitePoint IQ | `.iqvsa` | LitePoint IQxstream / IQfact IQ capture data |
+| SigMF | `.sigmf-meta`, `.sigmf-data`, `.sigmf-data.zip`, `.sigmf` | SigMF recordings (open either half of the pair, or a `.sigmf` archive). A zipped dataset (`<name>.sigmf-data.zip`) is read in place without unpacking. `litepoint:scale` converts counts to analyser units; `litepoint:channel_offset_hz` / `litepoint:spectrum_inverted` put a low-IF capture's FFT on the RF axis. Each recording also gets magnitude views: `mag` (\|iq\|) and `power_dBm` (dBm for LitePoint analyser captures, matching their burst annotations), `power_dBFS` (ADC counts with a stated full scale) or `power_dB`. All `core:datatype`s (`cf32_le`, `ci16_le`, `cu8`, `rf64_be`, …), multi-channel and per-capture header bytes. Gives a complex `iq` column plus `I`/`Q`, a `time` axis from `core:sample_rate`, and the FFT is centred on the first capture's `core:frequency` |
 | STDF | `.stdf`, `.stdf.gz` | Semiconductor ATE test results (SEMI E10/V4) — parametric (PTR) results per part/site, gzip auto-detected |
 | Raw counter | `.u32` | Bare little-endian `uint32` counter records with a `.meta.json` sidecar giving the tick length and periods per sample; converted to Hz or ns on load, with the dead time between capture chunks preserved |
+| Audio | `.wav`, `.flac`, `.ogg`, `.opus`, `.aif`/`.aiff`, `.mp3`, … | Audio recordings. `.wav` is read natively (PCM 8/16/24/32-bit, 32/64-bit float, `WAVE_FORMAT_EXTENSIBLE`, RF64); the other formats need `pip install cicwave[audio]` (soundfile/libsndfile). Samples are in full scale (±1) with a `time` axis in seconds, one column per channel: `audio` (mono), `left`/`right` (stereo) or `ch0`, `ch1`, … The sample rate prefills the FFT and analysis dialogs |
 
 ### Tabular text formats
 
@@ -198,6 +213,7 @@ through to the ngspice raw reader, so non-standard suffixes (e.g. `.raw0`,
 ## Environment Variables
 
 - `CICWAVE_X` - Default X-axis column name
+- `CICWAVE_PLUGINS=0` - Start without loading any [plugins](https://wulffern.github.io/cicwave/plugins)
 
 ## GUI Features
 

{cicwave-0.7.2 → cicwave-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cicwave"
-version = "0.7.2"
+version = "0.7.4"
 authors = [
   { name="Carsten Wulff", email="carsten@wulff.no" },
 ]
@@ -42,6 +42,7 @@ classifiers = [
 [project.optional-dependencies]
 parquet = ["pyarrow"]     # Parquet file support
 hdf5 = ["tables"]         # HDF5 file support
+audio = ["soundfile"]     # FLAC/Ogg/AIFF/MP3 audio (.wav needs nothing)
 mcp = ["mcp[cli]"]        # MCP server (cicwave-mcp); requires Python >= 3.10
 
 [project.scripts]

{cicwave-0.7.2 → cicwave-0.7.4}/src/cicwave/__init__.py

@@ -11,6 +11,7 @@ Supports multiple file formats:
 - NumPy .npz archives (tabular / bench traces)
 - VCD digital waveforms
 - LitePoint .iqvsa IQ capture files
+- SigMF IQ recordings (.sigmf-meta/.sigmf-data, .sigmf archives)
 
 Features:
 - GPU-accelerated rendering with PyQtGraph
@@ -21,6 +22,10 @@ Features:
 - Engineering unit formatting
 """
 
-__version__ = "1.0.0"
+try:
+    from importlib.metadata import PackageNotFoundError, version as _version
+    __version__ = _version("cicwave")
+except PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0.0.0"
 __author__ = "Carsten Wulff"
 __email__ = "carsten@wulff.no"

{cicwave-0.7.2 → cicwave-0.7.4}/src/cicwave/analysis.py

@@ -29,6 +29,8 @@ __all__ = [
     "linear_fit",
     "LinearFitResult",
     "difference",
+    "constellation",
+    "ConstellationResult",
     "run_analysis_steps",
     "AnalysisRunResult",
 ]
@@ -713,6 +715,85 @@ def difference(
     return a[:n] - b[:n]
 
 
+@dataclass(frozen=True)
+class ConstellationResult:
+    points: np.ndarray        # complex symbol (or sample) decisions
+    samples_per_symbol: float  # 1.0 when no symbol rate was given
+    offset_samples: float
+    freq_offset_hz: float
+    rms: float                # RMS magnitude before normalisation
+
+
+def constellation(
+        iq: np.ndarray,
+        *,
+        fs: Optional[float] = None,
+        symbol_rate: Optional[float] = None,
+        offset: float = 0.0,
+        freq_offset_hz: float = 0.0,
+        phase_deg: float = 0.0,
+        conjugate: bool = False,
+        start_sample: int = 0,
+        normalize: bool = True) -> ConstellationResult:
+    """Pick constellation points out of a complex baseband capture.
+
+    *freq_offset_hz* is the carrier offset to remove: the capture is
+    derotated by ``exp(-j·2π·f·t)`` (needs *fs*), then turned by
+    *phase_deg*; *conjugate* then mirrors Q, undoing a spectrum-inverted
+    receiver. With *symbol_rate* the result holds one point per symbol,
+    taken at sample ``offset + k·fs/symbol_rate`` (rounded, so fractional
+    samples per symbol work); without it every sample from *offset* on is
+    returned, which shows the trajectory. *normalize* scales the points to
+    unit RMS magnitude so constellations from different gains overlay.
+    *start_sample* is where *iq* begins in the whole recording: the
+    derotation runs on the recording's time base, so a phase found for one
+    part of a capture still holds when another part is selected.
+    """
+    z = np.asarray(iq)
+    if not np.iscomplexobj(z):
+        raise ValueError("constellation needs complex IQ samples")
+    z = z.astype(np.complex128)
+    fs = float(fs) if fs else None
+    if freq_offset_hz or symbol_rate:
+        if fs is None or not np.isfinite(fs) or fs <= 0:
+            raise ValueError(
+                "a sample rate is needed for a symbol rate or a "
+                "frequency offset")
+    if freq_offset_hz:
+        t = (np.arange(z.size, dtype=np.float64) + int(start_sample)) / fs
+        z = z * np.exp(-2j * np.pi * float(freq_offset_hz) * t)
+    if phase_deg:
+        z = z * np.exp(-1j * np.deg2rad(float(phase_deg)))
+    if conjugate:
+        z = np.conj(z)
+
+    offset = float(offset or 0.0)
+    if offset < 0:
+        raise ValueError("offset must be >= 0 samples")
+    if symbol_rate:
+        sps = fs / float(symbol_rate)
+        if sps < 1.0:
+            raise ValueError(
+                "symbol rate %.6g Hz is above the sample rate %.6g Hz"
+                % (symbol_rate, fs))
+        count = int(np.floor((z.size - 1 - offset) / sps)) + 1 \
+            if z.size > offset else 0
+        idx = np.rint(offset + np.arange(max(count, 0)) * sps).astype(np.int64)
+        idx = idx[idx < z.size]
+        pts = z[idx]
+    else:
+        sps = 1.0
+        pts = z[int(round(offset)):]
+
+    pts = pts[np.isfinite(pts)]
+    rms_mag = float(np.sqrt(np.mean(np.abs(pts) ** 2))) if pts.size else 0.0
+    if normalize and rms_mag > 0:
+        pts = pts / rms_mag
+    return ConstellationResult(
+        points=pts, samples_per_symbol=float(sps), offset_samples=offset,
+        freq_offset_hz=float(freq_offset_hz or 0.0), rms=rms_mag)
+
+
 @dataclass
 class AnalysisRunResult:
     """Structured + text output from :func:`run_analysis_steps`."""

{cicwave-0.7.2 → cicwave-0.7.4}/src/cicwave/apisource.py

@@ -367,6 +367,12 @@ def _run_request(req, idx, results, fetcher):
     return out
 
 
+_DERIVE_KEYS = {
+    "from", "regex", "group", "kv", "sep", "assign", "split", "index",
+    "type", "scale", "offset",
+}
+
+
 def _derive_extractor(rule, what):
     """Return ``f(text) -> value`` for one derive rule.
 
@@ -375,6 +381,7 @@ def _derive_extractor(rule, what):
     """
     if not isinstance(rule, dict):
         raise ValueError("%s: must be a mapping" % what)
+    _check_keys(rule, _DERIVE_KEYS, what)
 
     if "regex" in rule:
         pattern = re.compile(str(rule["regex"]))
@@ -423,16 +430,18 @@ def _derive_extractor(rule, what):
     raise ValueError("%s: needs one of 'regex', 'kv' or 'split'" % what)
 
 
-def _cast_value(value, dtype, what):
-    if dtype in (None, "str"):
+def _cast_value(value, dtype, what, scale=None, offset=None):
+    if dtype in (None, "str") and scale is None and offset is None:
         return value
-    if dtype not in ("int", "float"):
+    if dtype not in (None, "int", "float", "str"):
         raise ValueError(
             "%s: unknown type '%s' (int, float or str)" % (what, dtype))
     try:
         number = float(value)
     except (TypeError, ValueError):
         return None
+    number = number * float(1 if scale is None else scale)
+    number = number + float(0 if offset is None else offset)
     return int(number) if dtype == "int" else number
 
 
@@ -449,8 +458,13 @@ def _derive_series(df, name, rule):
     out = df[src].astype(str).map(_derive_extractor(rule, what))
 
     dtype = rule.get("type")
-    if dtype in ("int", "float"):
+    scale, offset = rule.get("scale"), rule.get("offset")
+    if dtype in ("int", "float") or scale is not None or offset is not None:
         out = pd.to_numeric(out, errors="coerce")
+        if scale is not None:
+            out = out * float(scale)
+        if offset is not None:
+            out = out + float(offset)
         if dtype == "int":
             out = out.astype("Int64")
     elif dtype not in (None, "str"):
@@ -473,13 +487,14 @@ def _derive_records(rows, derive, what):
             raise ValueError("%s: needs a 'from' field" % rule_what)
         extract = _derive_extractor(rule, rule_what)
         dtype = rule.get("type")
+        scale, offset = rule.get("scale"), rule.get("offset")
         for row in rows:
             if src not in row:
                 raise ValueError(
                     "%s: field '%s' is not in the records (available: %s)" % (
                         rule_what, src, ", ".join(sorted(row)) or "none"))
             value = extract("" if row[src] is None else str(row[src]))
-            row[name] = _cast_value(value, dtype, rule_what)
+            row[name] = _cast_value(value, dtype, rule_what, scale, offset)
     return rows
 
 

{cicwave-0.7.2 → cicwave-0.7.4}/src/cicwave/cli.py

@@ -404,7 +404,8 @@ def main(files, globs, x, sheet, fmt, pivot, pivot_info, session, export,
 
     Supports: .raw, .csv, .tsv, .xlsx, .json, .parquet, .feather, .npz,
     .h5, .pkl, .vcd (digital), .iqvsa (LitePoint), .stdf (ATE),
-    .u32 (raw counter captures), and more.
+    .u32 (raw counter captures), .sigmf-meta/.sigmf (SigMF IQ),
+    .wav/.flac/.ogg/.aiff/.mp3 (audio), and more.
 
     \b
     URL sources:

cicwave-0.7.4/src/cicwave/plugins.py

@@ -0,0 +1,253 @@
+"""Plugin API: extend cicwave from separately installed packages.
+
+cicwave itself stays generic. Anything specific to a private format,
+instrument or protocol lives in its own package, which declares an entry
+point in the ``cicwave.plugins`` group::
+
+    # pyproject.toml of the plugin package
+    [project.entry-points."cicwave.plugins"]
+    myplugin = "myplugin:register"
+
+The entry point names a callable taking this module's :class:`PluginAPI`.
+It is called once, the first time cicwave needs its plugins, and uses the
+API to register:
+
+* **readers** -- ``register_reader(".ext", fn)``; ``fn(path)`` returns a
+  :class:`pandas.DataFrame`. Matched on the longest filename suffix, before
+  the built-in readers, so a plugin can also take over a built-in suffix.
+* **annotators** -- ``register_annotator(fn)``; ``fn(df, path)`` runs after
+  every file is read and may add attributes or annotations to *df* in
+  place (see :func:`annotations`). This is how a plugin labels the parts
+  of a recording (e.g. the sections of each packet) without editing files.
+* **analyses** -- ``register_analysis(label, fn)``; adds *label* to a
+  wave's right-click menu, and ``fn(window, wave)`` runs when chosen.
+* **constellation presets** -- ``register_constellation_preset(name,
+  settings)``; offered in the constellation dialog, filling its fields.
+
+``set_description(text)`` gives the plugin a one-line description for
+Help > Plugins; without it the package's own summary is shown.
+
+A plugin that fails to load or raises is logged and skipped, never taking
+cicwave down with it. ``CICWAVE_PLUGINS=0`` in the environment disables
+plugin discovery altogether (cicwave's own test suite runs that way).
+"""
+
+import logging
+import os
+
+__all__ = [
+    "API_VERSION",
+    "PluginAPI",
+    "load_plugins",
+    "annotations",
+    "find_reader",
+    "run_annotators",
+    "analyses",
+    "constellation_presets",
+    "CONSTELLATION_FIELDS",
+    "plugin_info",
+    "describe_plugins",
+]
+
+#: Bumped when the API changes incompatibly; a plugin can compare it.
+API_VERSION = 1
+
+ENTRY_POINT_GROUP = "cicwave.plugins"
+
+#: Keys a constellation preset may set, mirroring the dialog's fields.
+CONSTELLATION_FIELDS = (
+    "symbol_rate", "offset", "freq_offset", "phase", "window_start",
+    "window_stop", "conjugate", "normalize", "trajectory", "annotation",
+)
+
+_log = logging.getLogger("cicwave.plugins")
+
+_readers = {}
+_annotators = []
+_analyses = []
+_presets = {}
+_info = {}
+_loaded = False
+
+
+class PluginAPI:
+    """What a plugin's ``register`` callable receives."""
+
+    API_VERSION = API_VERSION
+
+    def __init__(self, name):
+        self.name = name
+        self._info = _info.setdefault(name, _new_info(name))
+
+    def set_description(self, text):
+        """One line saying what the plugin is for, shown in Help > Plugins."""
+        self._info["description"] = str(text).strip()
+
+    def register_reader(self, suffix, fn):
+        suffix = suffix.lower()
+        if not suffix.startswith("."):
+            suffix = "." + suffix
+        _readers[suffix] = (fn, self.name)
+        self._info["readers"].append(suffix)
+
+    def register_annotator(self, fn):
+        _annotators.append((fn, self.name))
+        self._info["annotators"].append(getattr(fn, "__name__", repr(fn)))
+
+    def register_analysis(self, label, fn):
+        _analyses.append((label, fn, self.name))
+        self._info["analyses"].append(label)
+
+    def register_constellation_preset(self, name, settings):
+        unknown = set(settings) - set(CONSTELLATION_FIELDS)
+        if unknown:
+            raise ValueError("unknown constellation preset field(s): %s"
+                             % ", ".join(sorted(unknown)))
+        _presets[name] = dict(settings)
+        self._info["presets"].append(name)
+
+
+def _new_info(name):
+    return {"name": name, "description": "", "version": "", "error": None,
+            "readers": [], "annotators": [], "analyses": [], "presets": []}
+
+
+def _dist_metadata(ep):
+    """``(summary, version)`` of the package providing *ep*, if known."""
+    dist = getattr(ep, "dist", None)
+    if dist is None:
+        return "", ""
+    try:
+        return (dist.metadata.get("Summary") or "", dist.version or "")
+    except Exception:  # pragma: no cover - odd metadata
+        return "", ""
+
+
+def load_plugins(entry_points=None):
+    """Discover and register plugins, once. Returns the names loaded.
+
+    *entry_points* is for tests; by default the installed ``cicwave.plugins``
+    entry points are used. Importing :mod:`importlib.metadata` and the
+    plugins is deferred to here so a plain launch pays nothing until a file
+    is read or a menu is built.
+    """
+    global _loaded
+    if _loaded and entry_points is None:
+        return []
+    _loaded = True
+    if entry_points is None:
+        if os.environ.get("CICWAVE_PLUGINS") == "0":
+            return []
+        try:
+            from importlib.metadata import entry_points as _eps
+            entry_points = list(_eps(group=ENTRY_POINT_GROUP))
+        except Exception as e:  # pragma: no cover - broken environment
+            _log.warning("could not list cicwave plugins: %s", e)
+            return []
+    names = []
+    for ep in entry_points:
+        info = _info.setdefault(ep.name, _new_info(ep.name))
+        info["description"], info["version"] = _dist_metadata(ep)
+        try:
+            register = ep.load()
+            register(PluginAPI(ep.name))
+            names.append(ep.name)
+        except Exception as e:
+            info["error"] = str(e) or type(e).__name__
+            _log.warning("cicwave plugin %r failed to load: %s", ep.name, e)
+    return names
+
+
+def plugin_info():
+    """What each discovered plugin is and registered, for display.
+
+    A list of dicts with ``name``, ``description``, ``version``, ``error``
+    (the load failure, or None) and the lists ``readers``, ``annotators``,
+    ``analyses`` and ``presets``.
+    """
+    load_plugins()
+    return [dict(i) for i in _info.values()]
+
+
+def describe_plugins():
+    """Plain-text summary of :func:`plugin_info`, as Help > Plugins shows."""
+    infos = plugin_info()
+    if not infos and os.environ.get("CICWAVE_PLUGINS") == "0":
+        return "Plugin discovery is off (CICWAVE_PLUGINS=0)."
+    if not infos:
+        return ("No plugins installed.\n\nA plugin is a package declaring a "
+                "'%s' entry point." % ENTRY_POINT_GROUP)
+    out = []
+    for i in infos:
+        head = i["name"] + (" " + i["version"] if i["version"] else "")
+        out.append(head)
+        if i["description"]:
+            out.append("  " + i["description"])
+        if i["error"]:
+            out.append("  FAILED TO LOAD: " + i["error"])
+        for key, title in (("readers", "Readers"),
+                           ("annotators", "Annotators"),
+                           ("analyses", "Analyses"),
+                           ("presets", "Constellation presets")):
+            if i[key]:
+                out.append("  %-22s %s" % (title + ":", ", ".join(i[key])))
+        out.append("")
+    return "\n".join(out).rstrip()
+
+
+def find_reader(path):
+    """The plugin reader for *path* (longest matching suffix), or None."""
+    load_plugins()
+    lower = path.lower()
+    best = None
+    for suffix, (fn, _name) in _readers.items():
+        if lower.endswith(suffix) and (best is None or len(suffix) > len(best[0])):
+            best = (suffix, fn)
+    return best[1] if best else None
+
+
+def run_annotators(df, path):
+    """Let every registered annotator add to *df* (in place)."""
+    load_plugins()
+    for fn, name in _annotators:
+        try:
+            fn(df, path)
+        except Exception as e:
+            _log.warning("cicwave plugin %r annotator failed on %s: %s",
+                         name, path, e)
+    return df
+
+
+def annotations(df):
+    """The annotation list of *df*, created empty if missing.
+
+    Annotations follow the SigMF convention -- dicts with
+    ``core:sample_start``, ``core:sample_count`` and ``core:label`` -- and
+    are what the constellation dialog offers as sample ranges. SigMF
+    recordings start with the file's own annotations; an annotator
+    appends to the same list.
+    """
+    return df.attrs.setdefault("cicwave_annotations", [])
+
+
+def analyses():
+    """``[(label, fn)]`` registered for the wave context menu."""
+    load_plugins()
+    return [(label, fn) for label, fn, _name in _analyses]
+
+
+def constellation_presets():
+    """``{name: settings}`` registered for the constellation dialog."""
+    load_plugins()
+    return dict(_presets)
+
+
+def _reset():
+    """Forget every registration (tests only)."""
+    global _loaded
+    _readers.clear()
+    _annotators.clear()
+    _analyses.clear()
+    _presets.clear()
+    _info.clear()
+    _loaded = False