quelware-tools 0.1.0__py3-none-any.whl

quelware_tools/cli/echo_test.py

@@ -0,0 +1,222 @@
+"""quel-echo-test: emit a pulse on a TRX port and capture the echoed response."""
+
+import asyncio
+import logging
+from typing import Annotated
+
+import matplotlib.pyplot as plt
+import numpy as np
+import typer
+from quelware_client.client import create_quelware_client
+from quelware_client.client.helpers.sequencer import Sequencer
+from quelware_client.core import QuelwareClient
+from quelware_client.core.instrument_driver import (
+    create_instrument_driver_fixed_timeline,
+)
+from quelware_core.entities import directives
+from quelware_core.entities.directives import CaptureMode
+from quelware_core.entities.instrument import (
+    FixedTimelineProfile,
+    InstrumentDefinition,
+    InstrumentInfo,
+    InstrumentMode,
+    InstrumentRole,
+)
+from quelware_core.entities.port import PortRole
+from quelware_core.entities.resource import ResourceCategory, ResourceId
+
+logger = logging.getLogger(__name__)
+
+_ALIAS = "echo_test"
+_HALF_BW_HZ = 2.5e6
+
+
+async def _resolve_port(qc: QuelwareClient, port_id: str | None) -> ResourceId:
+    if port_id is not None:
+        return ResourceId(port_id)
+    for info in await qc.list_resource_infos():
+        if info.category is not ResourceCategory.PORT:
+            continue
+        port_info = await qc.get_port_info(info.id)
+        if port_info.role is PortRole.TRANSCEIVER:
+            return info.id
+    raise RuntimeError("no TRX port found on any reachable unit")
+
+
+async def _deploy(
+    qc: QuelwareClient,
+    port_id: ResourceId,
+    frequency_hz: float,
+    loopback: bool,
+) -> tuple[ResourceId, InstrumentInfo]:
+    role = (
+        InstrumentRole.TRANSCEIVER_LOOPBACK if loopback else InstrumentRole.TRANSCEIVER
+    )
+    async with qc.create_session([port_id]) as session:
+        definition = InstrumentDefinition(
+            alias=_ALIAS,
+            mode=InstrumentMode.FIXED_TIMELINE,
+            role=role,
+            profile=FixedTimelineProfile(
+                frequency_range_min=frequency_hz - _HALF_BW_HZ,
+                frequency_range_max=frequency_hz + _HALF_BW_HZ,
+            ),
+        )
+        inst_infos = await session.deploy_instruments(port_id, definitions=[definition])
+    inst_info = inst_infos[0]
+    logger.info("Deployed instrument: %s", inst_info.id)
+    return inst_info.id, inst_info
+
+
+async def _run(
+    qc: QuelwareClient,
+    inst_id: ResourceId,
+    inst_info: InstrumentInfo,
+    frequency_hz: float,
+    pulse_len_samples: int,
+    capture_start_offset_samples: int,
+    capture_len_samples: int,
+    shot_gap_ns: float,
+    iterations: int,
+) -> np.ndarray:
+    sampling_period_ns = inst_info.config.sampling_period_fs * 1e-6
+    pulse_len_ns = pulse_len_samples * sampling_period_ns
+    capture_delay_ns = capture_start_offset_samples * sampling_period_ns
+    capture_len_ns = capture_len_samples * sampling_period_ns
+    timeline_len_ns = max(pulse_len_ns, capture_delay_ns + capture_len_ns) + shot_gap_ns
+
+    async with qc.create_session([inst_id], ttl_ms=10000) as session:
+        driver = create_instrument_driver_fixed_timeline(session, inst_info)
+        seq = Sequencer(
+            default_sampling_period_ns=sampling_period_ns,
+            enforce_sample_grid=True,
+        )
+        seq.bind(
+            alias=_ALIAS,
+            sampling_period_fs=inst_info.config.sampling_period_fs,
+            step_samples=inst_info.config.timeline_step_samples,
+        )
+        seq.register_waveform("rect_pulse", np.ones(pulse_len_samples, dtype=complex))
+        seq.add_event(_ALIAS, "rect_pulse", start_offset_ns=0.0)
+        seq.add_capture_window(
+            _ALIAS,
+            "capture",
+            start_offset_ns=capture_delay_ns,
+            length_ns=capture_len_ns,
+        )
+        seq.extend_length_ns(timeline_len_ns)
+        seq.set_iterations(iterations)
+
+        await driver.initialize()
+        await driver.apply(
+            [
+                directives.SetFrequency(hz=frequency_hz),
+                directives.SetCaptureMode(mode=CaptureMode.AVERAGED_WAVEFORM),
+                seq.export_set_fixed_timeline_directive(_ALIAS),
+            ]
+        )
+        await session.trigger([inst_id])
+        result = await driver.fetch_result()
+
+    return result.iq_waveform_result["capture"][0].iq_array
+
+
+def _plot(iq: np.ndarray, save_path: str | None) -> None:
+    fig, ax = plt.subplots()
+    ax.plot(iq.real, label="I")
+    ax.plot(iq.imag, label="Q")
+    ax.set_xlabel("sample")
+    ax.set_ylabel("amplitude")
+    ax.legend()
+    ax.set_title("echo test capture (averaged waveform)")
+    if save_path is None:
+        plt.show()
+    else:
+        fig.savefig(save_path)
+        logger.info("saved plot to %s", save_path)
+        plt.close(fig)
+
+
+def _entry(
+    host: Annotated[str, typer.Argument(help="server host")],
+    port_id: Annotated[
+        str | None,
+        typer.Option(
+            help="port resource id (e.g. quel3-01-a28:trx_p00p01); "
+            "pick first reachable TRX port if omitted"
+        ),
+    ] = None,
+    port: Annotated[int, typer.Option(help="server port")] = 50051,
+    iterations: Annotated[
+        int, typer.Option("--iter", help="number of pulses to average")
+    ] = 1000,
+    pulse_len_samples: Annotated[
+        int, typer.Option(help="pulse length in samples")
+    ] = 400,
+    capture_start_offset: Annotated[
+        int, typer.Option(help="capture window offset from pulse start, in samples")
+    ] = 500,
+    capture_len_samples: Annotated[
+        int, typer.Option(help="capture window length in samples")
+    ] = 1000,
+    freq_hz: Annotated[float, typer.Option(help="carrier frequency in Hz")] = 6.0e9,
+    shot_gap_ns: Annotated[
+        float, typer.Option(help="gap between successive pulses, in ns")
+    ] = 100_000.0,
+    loopback: Annotated[bool, typer.Option(help="route TX into RX internally")] = False,
+    iq_plot: Annotated[bool, typer.Option(help="show I/Q time-series plot")] = False,
+    iq_plot_png: Annotated[
+        str | None,
+        typer.Option(
+            metavar="PATH",
+            help="save I/Q plot as PNG to PATH instead of displaying",
+        ),
+    ] = None,
+    log_level: Annotated[str, typer.Option(help="DEBUG|INFO|WARNING|ERROR")] = "INFO",
+) -> None:
+    """Emit a pulse on a TRX port and capture the echoed averaged response."""
+    logging.basicConfig(
+        level=getattr(logging, log_level),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    async def _main() -> None:
+        qc = create_quelware_client(host, port)
+        async with qc:
+            resolved_port_id = await _resolve_port(qc, port_id)
+            logger.info("using TRX port: %s", resolved_port_id)
+            inst_id, inst_info = await _deploy(
+                qc, resolved_port_id, frequency_hz=freq_hz, loopback=loopback
+            )
+            iq = await _run(
+                qc,
+                inst_id,
+                inst_info,
+                frequency_hz=freq_hz,
+                pulse_len_samples=pulse_len_samples,
+                capture_start_offset_samples=capture_start_offset,
+                capture_len_samples=capture_len_samples,
+                shot_gap_ns=shot_gap_ns,
+                iterations=iterations,
+            )
+        print(f"captured {len(iq)} samples (mean |iq| = {np.abs(iq).mean():.6f})")
+        if iq_plot_png is not None:
+            _plot(iq, iq_plot_png)
+        elif iq_plot:
+            _plot(iq, None)
+
+    try:
+        asyncio.run(_main())
+    except Exception as exc:
+        # gRPC errors carry a human message; fall back to the repr otherwise
+        message = getattr(exc, "message", None) or str(exc)
+        typer.echo(f"error: {message}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+def cli() -> None:
+    typer.run(_entry)
+
+
+if __name__ == "__main__":
+    cli()

quelware_tools/cli/tone_test.py

@@ -0,0 +1,88 @@
+"""quel-tone-test: per-port tone test for a QuEL-3 unit.
+
+Puts the unit's monitor into loopback and, for every tx/trx port, emits a tone
+and checks it appears in the monitor capture. Intended as a post-update health
+check against a running system. Requires an admin PAT and an idle unit; the
+monitor is restored to ``open`` on the way out. Exits non-zero if any port fails.
+"""
+
+import asyncio
+import logging
+from typing import Annotated
+
+import typer
+from quelware_client.client import create_quelware_client
+from quelware_core.entities.unit import UnitLabel
+
+from quelware_tools.diagnostics import run_tone_test
+
+logger = logging.getLogger(__name__)
+
+
+def _entry(
+    host: Annotated[str, typer.Argument(help="manager host")],
+    unit: Annotated[str, typer.Option(help="unit label to check")],
+    port: Annotated[int, typer.Option(help="manager port")] = 50051,
+    pat: Annotated[
+        str | None,
+        typer.Option(help="admin PAT; defaults to the configured PAT"),
+    ] = None,
+    target_port: Annotated[
+        str | None,
+        typer.Option(help="restrict to one port id (default: all tx/trx ports)"),
+    ] = None,
+    tx_hz: Annotated[float, typer.Option(help="transmit frequency in Hz")] = 5.1e9,
+    mon_hz: Annotated[float, typer.Option(help="monitor frequency in Hz")] = 5.0e9,
+    threshold_db: Annotated[
+        float, typer.Option(help="minimum tone peak-to-median in dB to pass")
+    ] = 20.0,
+    cw_length_ns: Annotated[
+        float, typer.Option(help="length of the emitted CW in ns")
+    ] = 4000.0,
+    capture_start_ns: Annotated[
+        float, typer.Option(help="capture window start offset in ns")
+    ] = 1000.0,
+    capture_length_ns: Annotated[
+        float, typer.Option(help="capture window length in ns")
+    ] = 800.0,
+    iterations: Annotated[int, typer.Option(help="capture averaging iterations")] = 1,
+    log_level: Annotated[str, typer.Option(help="DEBUG|INFO|WARNING|ERROR")] = "INFO",
+) -> None:
+    """Run the per-port tone test on one QuEL-3 unit."""
+    logging.basicConfig(
+        level=getattr(logging, log_level, logging.INFO),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    async def _main() -> None:
+        qc = create_quelware_client(host, port, pat=pat)
+        async with qc:
+            report = await run_tone_test(
+                qc,
+                UnitLabel(unit),
+                port=target_port,
+                tx_hz=tx_hz,
+                mon_hz=mon_hz,
+                min_peak_to_median_db=threshold_db,
+                cw_length_ns=cw_length_ns,
+                capture_start_ns=capture_start_ns,
+                capture_length_ns=capture_length_ns,
+                iterations=iterations,
+            )
+        for r in report.results:
+            print(f"[{'PASS' if r.passed else 'FAIL'}] {r.port_id}: {r.detail}")
+        passed_n = sum(r.passed for r in report.results)
+        status = "PASS" if report.passed else "FAIL"
+        print(f"[{status}] {report.unit_label}: {passed_n}/{len(report.results)} ports")
+        if not report.passed:
+            raise typer.Exit(code=1)
+
+    asyncio.run(_main())
+
+
+def cli() -> None:
+    typer.run(_entry)
+
+
+if __name__ == "__main__":
+    cli()

quelware_tools/cli/unit_config.py

@@ -0,0 +1,130 @@
+"""quel-unit-config: inspect or change QuEL-3 unit configuration controls.
+
+``show`` prints each control's current and allowed values; ``set`` applies one
+or more ``KEY=VALUE`` controls. Setting needs an admin PAT, an idle unit (no
+deployed instruments), and locks on every port of the unit, so it is a
+maintenance-window operation. Keys are opaque -- discover them with ``show``.
+"""
+
+import asyncio
+import json
+from collections.abc import Coroutine
+from typing import Annotated, Any
+
+import typer
+from quelware_client.client import create_quelware_client
+from quelware_client.core import QuelwareClient
+from quelware_core.entities.resource import ResourceCategory, ResourceId
+from quelware_core.entities.unit import UnitLabel
+
+app = typer.Typer(add_completion=False, help="Show or set QuEL-3 unit configuration.")
+
+
+@app.command()
+def show(
+    host: Annotated[str, typer.Argument(help="manager host")],
+    unit: Annotated[str, typer.Option(help="unit label")],
+    port: Annotated[int, typer.Option(help="manager port")] = 50051,
+    pat: Annotated[
+        str | None, typer.Option(help="PAT; defaults to the configured PAT")
+    ] = None,
+    as_json: Annotated[bool, typer.Option("--json", help="emit JSON")] = False,
+) -> None:
+    """Show a unit's configuration controls."""
+
+    async def _main() -> None:
+        qc = create_quelware_client(host, port, pat=pat)
+        async with qc:
+            cfg = await qc.get_unit_configuration(UnitLabel(unit))
+        if as_json:
+            doc = {
+                s.key: {"current": s.current_value, "allowed": list(s.allowed_values)}
+                for s in cfg.supported
+            }
+            print(json.dumps(doc, indent=2))
+        else:
+            for s in cfg.supported:
+                allowed = ", ".join(s.allowed_values)
+                print(f"{s.key}: {s.current_value}  (allowed: {allowed})")
+
+    _run(_main())
+
+
+@app.command("set")
+def set_(
+    host: Annotated[str, typer.Argument(help="manager host")],
+    controls: Annotated[
+        list[str], typer.Argument(help="controls to apply as KEY=VALUE")
+    ],
+    unit: Annotated[str, typer.Option(help="unit label")],
+    port: Annotated[int, typer.Option(help="manager port")] = 50051,
+    pat: Annotated[
+        str | None, typer.Option(help="admin PAT; defaults to the configured PAT")
+    ] = None,
+    discard_instruments: Annotated[
+        bool,
+        typer.Option(
+            "--discard-instruments",
+            help="discard all instruments on the unit before configuring",
+        ),
+    ] = False,
+) -> None:
+    """Set KEY=VALUE controls on a unit (admin PAT, idle unit)."""
+    parsed = _parse_controls(controls)
+
+    async def _main() -> None:
+        qc = create_quelware_client(host, port, pat=pat)
+        async with qc:
+            port_ids = await _unit_port_ids(qc, UnitLabel(unit))
+            if not port_ids:
+                raise RuntimeError(f"no ports found for unit '{unit}'")
+            async with qc.create_session(port_ids) as session:
+                if discard_instruments:
+                    for port_id in port_ids:
+                        await session.discard_instruments(port_id)
+                result = await session.configure_unit(UnitLabel(unit), parsed)
+        for key, value in result.items():
+            print(f"{key}: {value}")
+
+    _run(_main())
+
+
+def _parse_controls(pairs: list[str]) -> dict[str, str]:
+    controls: dict[str, str] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            raise typer.BadParameter(f"expected KEY=VALUE, got {pair!r}")
+        controls[key] = value
+    return controls
+
+
+async def _unit_port_ids(
+    client: QuelwareClient, unit_label: UnitLabel
+) -> list[ResourceId]:
+    prefix = f"{unit_label}:"
+    return [
+        r.id
+        for r in await client.list_resource_infos()
+        if r.category == ResourceCategory.PORT and str(r.id).startswith(prefix)
+    ]
+
+
+def _run(coro: Coroutine[Any, Any, None]) -> None:
+    try:
+        asyncio.run(coro)
+    except typer.Exit:
+        raise
+    except Exception as exc:
+        # gRPC errors carry a human message; fall back to the repr otherwise
+        message = getattr(exc, "message", None) or str(exc)
+        typer.echo(f"error: {message}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+def cli() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    cli()

quelware_tools/diagnostics/__init__.py

@@ -0,0 +1,15 @@
+from ._tone import ToneResult, detect_tone, top_peaks
+from .tone_test import (
+    PortToneResult,
+    ToneTestReport,
+    run_tone_test,
+)
+
+__all__ = [
+    "PortToneResult",
+    "ToneResult",
+    "ToneTestReport",
+    "detect_tone",
+    "run_tone_test",
+    "top_peaks",
+]

quelware_tools/diagnostics/_tone.py

@@ -0,0 +1,93 @@
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class ToneResult:
+    """Outcome of looking for a single expected tone in a captured IQ trace."""
+
+    expected_hz: float
+    measured_hz: float
+    peak_to_median_db: float
+    within_tolerance: bool
+    above_threshold: bool
+
+    @property
+    def ok(self) -> bool:
+        return self.within_tolerance and self.above_threshold
+
+
+def detect_tone(
+    iq: np.ndarray,
+    sample_rate_hz: float,
+    expected_hz: float,
+    *,
+    freq_tol_hz: float,
+    min_peak_to_median_db: float,
+) -> ToneResult:
+    """Locate the dominant tone in a complex IQ trace and grade it.
+
+    The trace is expected to contain a single tone (the transmitted signal seen
+    through the internal loopback). The dominant FFT bin gives the measured
+    frequency; the peak's height over the spectrum's median gives a crude SNR.
+    The tone passes when it sits within ``freq_tol_hz`` of ``expected_hz`` and
+    rises at least ``min_peak_to_median_db`` above the noise floor.
+
+    Args:
+        iq: Captured complex samples.
+        sample_rate_hz: Sample rate of ``iq``.
+        expected_hz: Baseband frequency the tone should appear at (the transmit
+            frequency down-converted by the capturing mixer).
+        freq_tol_hz: Allowed deviation of the measured tone from ``expected_hz``.
+        min_peak_to_median_db: Minimum peak-to-median magnitude, in dB.
+    """
+    samples = np.asarray(iq)
+    if samples.ndim != 1 or samples.size == 0:
+        raise ValueError("iq must be a non-empty 1-D array")
+
+    spectrum = np.abs(np.fft.fftshift(np.fft.fft(samples)))
+    freqs = np.fft.fftshift(np.fft.fftfreq(samples.size, d=1.0 / sample_rate_hz))
+
+    peak_idx = int(np.argmax(spectrum))
+    measured_hz = float(freqs[peak_idx])
+    peak = float(spectrum[peak_idx])
+    median = float(np.median(spectrum))
+    peak_to_median_db = (
+        20.0 * float(np.log10(peak / median)) if median > 0.0 else float("inf")
+    )
+
+    return ToneResult(
+        expected_hz=expected_hz,
+        measured_hz=measured_hz,
+        peak_to_median_db=peak_to_median_db,
+        within_tolerance=abs(measured_hz - expected_hz) <= freq_tol_hz,
+        above_threshold=peak_to_median_db >= min_peak_to_median_db,
+    )
+
+
+def top_peaks(
+    iq: np.ndarray, sample_rate_hz: float, count: int = 5
+) -> list[tuple[float, float]]:
+    """Return ``(frequency_hz, db_over_median)`` for the strongest spectral bins.
+
+    Diagnostic aid: shows where the captured energy actually sits, independent
+    of any expected frequency. Adjacent bins of one tone may appear together.
+    """
+    samples = np.asarray(iq)
+    spectrum = np.abs(np.fft.fftshift(np.fft.fft(samples)))
+    freqs = np.fft.fftshift(np.fft.fftfreq(samples.size, d=1.0 / sample_rate_hz))
+    median = float(np.median(spectrum))
+    order = np.argsort(spectrum)[::-1][:count]
+    return [
+        (
+            float(freqs[i]),
+            20.0 * float(np.log10(spectrum[i] / median))
+            if median > 0.0
+            else float("inf"),
+        )
+        for i in order
+    ]
+
+
+__all__ = ["ToneResult", "detect_tone", "top_peaks"]

quelware_tools/diagnostics/tone_test.py

@@ -0,0 +1,350 @@
+"""Per-port tone test for a live QuEL-3 system.
+
+Drives the public client SDK against an already-running manager + edge server
+(reachable via ``client``, using an admin PAT) to confirm the internal signal
+path is healthy: it puts the unit's monitor into loopback and, for every
+tx/trx port, emits a long CW tone and checks that the tone appears in a monitor
+capture taken from inside the CW. Capturing well inside a long emission makes
+the check robust to the (unknown) loopback + digital-pipeline delay. The
+monitor is always restored to ``open`` before returning, even on failure.
+
+This targets a real (or fidelity-simulating) backend; the model-agnostic fake
+worker returns no signal, so a passing fidelity result only means something
+against real hardware or the device mock. It requires an idle unit (no deployed
+instruments) and admin privileges, so it is a maintenance-window operation --
+e.g. a health check after an on-site software update.
+"""
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+from quelware_client.client.helpers.sequencer import Sequencer
+from quelware_client.core import QuelwareClient
+from quelware_client.core.instrument_driver import (
+    create_instrument_driver_fixed_timeline,
+)
+from quelware_core.entities.directives import (
+    CaptureMode,
+    SetCaptureMode,
+    SetFrequency,
+)
+from quelware_core.entities.instrument import (
+    FixedTimelineProfile,
+    InstrumentDefinition,
+    InstrumentInfo,
+    InstrumentMode,
+    InstrumentRole,
+)
+from quelware_core.entities.resource import ResourceCategory, ResourceId
+from quelware_core.entities.unit import UnitLabel
+
+from ._tone import ToneResult, detect_tone, top_peaks
+
+logger = logging.getLogger(__name__)
+
+# QuEL-3-specific: the monitor is a unit control keyed "quel3.monitor.mode"; the
+# emitting ports are named trx*/tx*, and the monitor capture port ends ":mon".
+_MONITOR_MODE_KEY = "quel3.monitor.mode"
+_MON_PORT_SUFFIX = ":mon"
+_EMIT_PORT_PREFIXES = ("trx", "tx")
+
+_FS_PER_SEC = 10**15
+_PROFILE_HALF_HZ = 200e6
+
+
+@dataclass(frozen=True)
+class PortToneResult:
+    port_id: str
+    passed: bool
+    detail: str
+    tone: ToneResult | None = None
+
+
+@dataclass(frozen=True)
+class ToneTestReport:
+    unit_label: str
+    passed: bool
+    results: tuple[PortToneResult, ...]
+
+
+async def run_tone_test(
+    client: QuelwareClient,
+    unit_label: UnitLabel,
+    *,
+    port: str | None = None,
+    tx_hz: float = 5.1e9,
+    mon_hz: float = 5.0e9,
+    min_peak_to_median_db: float = 20.0,
+    cw_length_ns: float = 4000.0,
+    capture_start_ns: float = 1000.0,
+    capture_length_ns: float = 800.0,
+    iterations: int = 1,
+) -> ToneTestReport:
+    """Run the per-port tone test on one unit.
+
+    Tests every tx/trx port by default, or just ``port`` when given. For each,
+    emits a ``cw_length_ns`` CW and captures ``capture_length_ns`` starting at
+    ``capture_start_ns`` (a margin past the path delay) from inside that CW.
+
+    Preconditions: the unit is idle (no instruments) and ``client`` was built
+    with an admin PAT (configuring the monitor needs the CONFIGURE_UNIT
+    capability). The monitor is restored to ``open`` before returning, even on
+    failure.
+    """
+    cleanup_ports: list[ResourceId] = []
+    try:
+        logger.info("setting monitor to loopback on %s", unit_label)
+        async with client.create_session(await _port_ids(client)) as session:
+            await session.configure_unit(unit_label, {_MONITOR_MODE_KEY: "loopback"})
+
+        mon_port = await _monitor_port(client)
+        emit_ports = [ResourceId(port)] if port else await _emit_ports(client)
+        emit_ports.sort(key=str)
+        cleanup_ports = [*emit_ports, mon_port]
+        logger.info(
+            "monitor loopback enabled; mon=%s, testing %d emit port(s)",
+            mon_port,
+            len(emit_ports),
+        )
+
+        expected_hz = tx_hz - mon_hz
+        freq_tol_hz = 1e9 / capture_length_ns  # one FFT bin (1 / capture length)
+
+        results: list[PortToneResult] = []
+        for emit_port in emit_ports:
+            try:
+                results.append(
+                    await _check_port(
+                        client,
+                        emit_port,
+                        mon_port,
+                        tx_freq_hz=tx_hz,
+                        mon_freq_hz=mon_hz,
+                        expected_hz=expected_hz,
+                        freq_tol_hz=freq_tol_hz,
+                        min_peak_to_median_db=min_peak_to_median_db,
+                        cw_length_ns=cw_length_ns,
+                        capture_start_ns=capture_start_ns,
+                        capture_length_ns=capture_length_ns,
+                        iterations=iterations,
+                    )
+                )
+            except Exception as exc:
+                logger.exception("error testing %s", emit_port)
+                results.append(PortToneResult(str(emit_port), False, f"error: {exc}"))
+        passed = bool(results) and all(r.passed for r in results)
+        return ToneTestReport(str(unit_label), passed, tuple(results))
+    finally:
+        await _restore_monitor_open(client, unit_label, cleanup_ports)
+
+
+async def _check_port(
+    client: QuelwareClient,
+    emit_port: ResourceId,
+    mon_port: ResourceId,
+    *,
+    tx_freq_hz: float,
+    mon_freq_hz: float,
+    expected_hz: float,
+    freq_tol_hz: float,
+    min_peak_to_median_db: float,
+    cw_length_ns: float,
+    capture_start_ns: float,
+    capture_length_ns: float,
+    iterations: int,
+) -> PortToneResult:
+    logger.info(
+        "testing %s -> monitor (tx=%.6g Hz, expected baseband=%.6g Hz)",
+        emit_port,
+        tx_freq_hz,
+        expected_hz,
+    )
+    captured, sample_rate_hz = await _emit_and_capture(
+        client,
+        emit_port,
+        mon_port,
+        tx_freq_hz=tx_freq_hz,
+        mon_freq_hz=mon_freq_hz,
+        cw_length_ns=cw_length_ns,
+        capture_start_ns=capture_start_ns,
+        capture_length_ns=capture_length_ns,
+        iterations=iterations,
+    )
+    if abs(expected_hz) > sample_rate_hz / 2:
+        logger.warning(
+            "  %s baseband %.4g Hz beyond Nyquist %.4g Hz (Fs=%.4g); tx/mon too far",
+            emit_port,
+            expected_hz,
+            sample_rate_hz / 2,
+            sample_rate_hz,
+        )
+    logger.info(
+        "  %s capture: Fs=%.4g Hz, N=%d, top peaks=%s",
+        emit_port,
+        sample_rate_hz,
+        captured.size,
+        [
+            (f"{f / 1e6:.1f} MHz", f"{db:.1f} dB")
+            for f, db in top_peaks(captured, sample_rate_hz)
+        ],
+    )
+    tone = detect_tone(
+        captured,
+        sample_rate_hz,
+        expected_hz=expected_hz,
+        freq_tol_hz=freq_tol_hz,
+        min_peak_to_median_db=min_peak_to_median_db,
+    )
+    detail = (
+        f"tone at {tone.measured_hz:.3e} Hz (expected {tone.expected_hz:.3e}); "
+        f"{tone.peak_to_median_db:.1f} dB over noise"
+    )
+    logger.info("  %s: %s (%s)", emit_port, "PASS" if tone.ok else "FAIL", detail)
+    return PortToneResult(str(emit_port), tone.ok, detail, tone)
+
+
+async def _port_ids(client: QuelwareClient) -> list[ResourceId]:
+    rinfos = await client.list_resource_infos()
+    return [r.id for r in rinfos if r.category == ResourceCategory.PORT]
+
+
+def _port_name(port_id: ResourceId) -> str:
+    return str(port_id).rsplit(":", 1)[-1]
+
+
+async def _emit_ports(client: QuelwareClient) -> list[ResourceId]:
+    ports = [
+        p
+        for p in await _port_ids(client)
+        if _port_name(p).startswith(_EMIT_PORT_PREFIXES)
+    ]
+    if not ports:
+        raise RuntimeError("no tx/trx ports found on the unit")
+    return ports
+
+
+async def _monitor_port(client: QuelwareClient) -> ResourceId:
+    mon = next(
+        (p for p in await _port_ids(client) if str(p).endswith(_MON_PORT_SUFFIX)), None
+    )
+    if mon is None:
+        raise RuntimeError("monitor port not found after enabling loopback")
+    return mon
+
+
+async def _emit_and_capture(
+    client: QuelwareClient,
+    emit_port: ResourceId,
+    mon_port: ResourceId,
+    *,
+    tx_freq_hz: float,
+    mon_freq_hz: float,
+    cw_length_ns: float,
+    capture_start_ns: float,
+    capture_length_ns: float,
+    iterations: int,
+) -> tuple[np.ndarray, float]:
+    tx_def = InstrumentDefinition(
+        alias="tone_test_tx",
+        mode=InstrumentMode.FIXED_TIMELINE,
+        role=InstrumentRole.TRANSMITTER,
+        profile=FixedTimelineProfile(
+            tx_freq_hz - _PROFILE_HALF_HZ, tx_freq_hz + _PROFILE_HALF_HZ
+        ),
+    )
+    mon_def = InstrumentDefinition(
+        alias="tone_test_mon",
+        mode=InstrumentMode.FIXED_TIMELINE,
+        role=InstrumentRole.RECEIVER,
+        profile=FixedTimelineProfile(
+            mon_freq_hz - _PROFILE_HALF_HZ, mon_freq_hz + _PROFILE_HALF_HZ
+        ),
+    )
+
+    async with client.create_session([emit_port, mon_port]) as deploy_session:
+        (tx_info,) = await deploy_session.deploy_instruments(emit_port, [tx_def])
+        (mon_info,) = await deploy_session.deploy_instruments(mon_port, [mon_def])
+
+    async with client.create_session([tx_info.id, mon_info.id]) as drive_session:
+        tx_driver = create_instrument_driver_fixed_timeline(drive_session, tx_info)
+        mon_driver = create_instrument_driver_fixed_timeline(drive_session, mon_info)
+
+        tx_directive, mon_directive = _build_directives(
+            tx_info,
+            mon_info,
+            cw_length_ns=cw_length_ns,
+            capture_start_ns=capture_start_ns,
+            capture_length_ns=capture_length_ns,
+            iterations=iterations,
+        )
+        await tx_driver.apply(SetFrequency(hz=tx_freq_hz))
+        await tx_driver.apply(tx_directive)
+
+        await mon_driver.apply(
+            [
+                SetFrequency(hz=mon_freq_hz),
+                SetCaptureMode(mode=CaptureMode.AVERAGED_WAVEFORM),
+            ]
+        )
+        await mon_driver.apply(mon_directive)
+
+        await drive_session.trigger([tx_info.id, mon_info.id])
+        result = await mon_driver.fetch_result()
+
+    captured = np.asarray(result.iq_waveform_result["cap"][0].iq_array)
+    return captured, _FS_PER_SEC / mon_info.config.sampling_period_fs
+
+
+def _build_directives(
+    tx_info: InstrumentInfo,
+    mon_info: InstrumentInfo,
+    *,
+    cw_length_ns: float,
+    capture_start_ns: float,
+    capture_length_ns: float,
+    iterations: int,
+):
+    """Emit and capture share one timeline, so bind both to a single sequencer.
+
+    The tx CW sets the shared length; the mon capture window lands inside it.
+    """
+    tx_period_ns = tx_info.config.sampling_period_fs / 1_000_000
+    seq = Sequencer(default_sampling_period_ns=tx_period_ns, enforce_sample_grid=False)
+    for inst in (tx_info, mon_info):
+        seq.bind(
+            inst.definition.alias,
+            inst.config.sampling_period_fs,
+            inst.config.timeline_step_samples,
+        )
+    samples = max(1, round(cw_length_ns / tx_period_ns))
+    seq.register_waveform("cw", np.full(samples, 0.5 + 0.0j, dtype=complex))
+    seq.add_event(tx_info.definition.alias, "cw", 0.0)
+    seq.add_capture_window(
+        mon_info.definition.alias, "cap", capture_start_ns, capture_length_ns
+    )
+    seq.set_iterations(iterations)
+    return (
+        seq.export_set_fixed_timeline_directive(tx_info.definition.alias),
+        seq.export_set_fixed_timeline_directive(mon_info.definition.alias),
+    )
+
+
+async def _restore_monitor_open(
+    client: QuelwareClient,
+    unit_label: UnitLabel,
+    deployed_ports: list[ResourceId],
+) -> None:
+    async with client.create_session(await _port_ids(client)) as session:
+        for port_id in deployed_ports:
+            logger.info("discarding instruments on %s", port_id)
+            await session.discard_instruments(port_id)
+        logger.info("restoring monitor to open on %s", unit_label)
+        await session.configure_unit(unit_label, {_MONITOR_MODE_KEY: "open"})
+
+
+__all__ = [
+    "PortToneResult",
+    "ToneTestReport",
+    "run_tone_test",
+]

quelware_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: quelware-tools
+Version: 0.1.0
+Summary: Command-line tools and diagnostics for QuEL systems.
+Project-URL: Repository, https://github.com/quel-inc/quelware-client
+Project-URL: Documentation, https://quel-inc.github.io/quelware-client/
+Project-URL: Changelog, https://github.com/quel-inc/quelware-client/blob/main/quelware-tools/CHANGELOG.md
+Author-email: quelware Authors <opensource@quel-inc.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: quelware-client>=0.5.0
+Requires-Dist: quelware-core>=0.5.0
+Requires-Dist: typer>=0.21.1
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# quelware-tools
+
+Command-line tools and diagnostics for QuEL systems, built on `quelware-client`.
+
+They run against an already-running manager + edge server (endpoint + PAT); they
+start nothing themselves.
+
+## Commands
+
+- `quel-tone-test` — per-port tone test: put the unit's monitor into loopback,
+  emit a tone on every tx/trx port, and check it appears in the monitor capture.
+  A post-update health check. Exits non-zero if any port fails.
+- `quel-unit-config` — `show` / `set` a unit's configuration controls.
+  `set` needs an admin PAT and an idle unit.
+- `quel-echo-test` — emit a pulse on a TRX port and capture the echoed response
+  (optionally plotting the I/Q trace; install with the `plot` extra).
+
+## Install
+
+```
+pip install quelware-tools          # tools only
+pip install "quelware-tools[plot]"  # + matplotlib for quel-echo-test plots
+```

quelware_tools-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+quelware_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quelware_tools/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quelware_tools/cli/echo_test.py,sha256=S_mRedMALbQ12ANUOHSVBuJRDhG5t0NavDdYnkj8Hb0,7760
+quelware_tools/cli/tone_test.py,sha256=qhJHDN0q8R5fHd-oFIUlAbTZUkRyYpAK-JRE0iH1MiM,3208
+quelware_tools/cli/unit_config.py,sha256=A0d9BUhxeMnVWP3jPk7apuzDbRpnG8hgI6dNvR0S4-c,4393
+quelware_tools/diagnostics/__init__.py,sha256=MtCJYdJuXtBTtI3T7LisfutabvUY1NOauHeEvwsj6as,274
+quelware_tools/diagnostics/_tone.py,sha256=a5dgVJ6oNFFmxYy104J1oQxWFDq9paWlyfeoUSaHmf0,3140
+quelware_tools/diagnostics/tone_test.py,sha256=FnDpxIHRseT96EmpvhlE-6TYgS03F43sg8ggrjmVdfw,11951
+quelware_tools-0.1.0.dist-info/METADATA,sha256=VtwHKiaFiz5o9t8BlLtl0avxcz7yXeKpSP_tFliG8JQ,1593
+quelware_tools-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+quelware_tools-0.1.0.dist-info/entry_points.txt,sha256=1zZuwrJ04FRaD_aW_-a1YrsBgHMktHQI1vVj39-xekw,172
+quelware_tools-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+quelware_tools-0.1.0.dist-info/RECORD,,

quelware_tools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

quelware_tools-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+quel-echo-test = quelware_tools.cli.echo_test:cli
+quel-tone-test = quelware_tools.cli.tone_test:cli
+quel-unit-config = quelware_tools.cli.unit_config:cli

quelware_tools-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.