695 lines
39 KiB
Markdown
695 lines
39 KiB
Markdown
# tinySA Basic and Ultra implementation tasks
|
||
|
||
Planning baseline: repository state after `b4d1462`, reviewed 2026-10-05.
|
||
This file is the detailed implementation backlog. The
|
||
[roadmap](docs/roadmap.md) remains the short feature overview; shared IDs below
|
||
refer to the same work. All unchecked items are proposals, not implemented
|
||
features or certified device support. Stretch goals are unselected until the
|
||
user chooses them.
|
||
|
||
## What complete coverage means
|
||
|
||
Coverage here means instrument features, not Rust line coverage. Qualify each
|
||
exact model, hardware revision, firmware version, and host platform separately.
|
||
Basic and Ultra are the primary targets; Ultra+ and other revisions need
|
||
explicit profiles and evidence rather than inheriting support by name.
|
||
|
||
For every console command and front-panel feature, record one disposition:
|
||
implemented and verified; implemented but awaiting hardware; front-panel-only;
|
||
not present on this model/build; or blocked with a concrete upstream dependency.
|
||
No feature may disappear silently from the inventory. A documented limitation
|
||
completes the audit entry, but does not make that feature remotely implemented.
|
||
Do not advertise full remote coverage while remote-capable entries remain open.
|
||
|
||
Use the existing [source catalogue](docs/sources.md),
|
||
[protocol evidence](docs/usb-protocol.md), and
|
||
[compatibility matrix](docs/tiny-wb-operations.md#compatibility-matrix).
|
||
Their firmware observations are dated; this planning change does not reverify
|
||
upstream firmware. Command names below are investigation candidates until P01
|
||
confirms their syntax and availability on the selected build.
|
||
|
||
## Current baseline
|
||
|
||
| Area | Delivered | Still missing |
|
||
| --- | --- | --- |
|
||
| Library | Terminal-independent config, framing, Basic acquisition, CSV; optional serial/mock features | Model/session API and the remaining device operations |
|
||
| Basic | Low/high selection, one-shot raw sweep, repeat, configurable zero offset, resume attempt | Hardware qualification, processing/input controls, generator and complete workflows |
|
||
| Ultra | Synthetic profile; experimental physical validator at 240–300 MHz | Model detection, normal/extended range planning, Ultra-specific controls and qualification |
|
||
| Transport | Buffered mixed text/binary I/O, complete writes, bounded responses, serial/TCP adapters | Overall deadlines, abort, reconnect, typed replies and full recovery |
|
||
| Interface | One scan per TUI launch, plot and CSV | Headless commands, repeat/live operation, capability-aware controls |
|
||
| Verification | Regression/mock tests, CI gates, guided hardware validator | Captured real-device fixtures, RF reference measurements and platform matrix |
|
||
|
||
- [x] F01–F04: reusable library, injected I/O, bounded mock profiles and loopback tests.
|
||
- [x] H00: initial [hardware checklist](docs/hardware-validation.md),
|
||
[launcher](scripts/test-hardware.sh), and [validator](examples/validate-hardware.rs).
|
||
- [ ] H00 qualification: execute on real Basic and Ultra units and retain evidence.
|
||
Providing the validator has not completed hardware acceptance.
|
||
|
||
## Implementation rules and common completion gate
|
||
|
||
Keep the boundaries in [architecture](docs/architecture.md). Candidate new
|
||
modules such as `device`, `commands`, `session`, and `measurements` below are
|
||
proposed responsibilities, not existing APIs. Introduce them only with the
|
||
first concrete consumer; do not recreate a miscellaneous `structs` module.
|
||
|
||
Every feature slice must include:
|
||
|
||
- [ ] A typed library operation, validation before mutation, and an explicit
|
||
supported-model/firmware capability entry.
|
||
- [ ] Protocol parsing over bytes or `Read`/`Write`, with no hidden port/file
|
||
opening; settings use MHz/dBm/milliseconds, wire frequencies use Hz.
|
||
- [ ] Mock/transcript tests for success, rejection, boundaries, fragmentation,
|
||
timeouts, partial writes, disconnects and recovery where applicable.
|
||
- [ ] CLI/TUI exposure appropriate to the operation, including unsupported-state
|
||
feedback; diagnostics must not turn a rejected command into success.
|
||
- [ ] Configuration compatibility or a tested migration, Rustdoc, user guidance,
|
||
source links and hardware evidence status updated together.
|
||
- [ ] The [required verification commands](docs/security-and-ci.md#local-verification)
|
||
pass; run `cargo coverage` for Rust behavior and security gates for dependency
|
||
changes. Keep production coverage exclusions and the floor policy unchanged.
|
||
|
||
Hardware results must name the device/build, settings, RF setup and references,
|
||
expected result, observed result, tolerances and artifact paths. Mock results
|
||
must remain labeled synthetic. Publish or run shared Jenkins jobs only as a
|
||
separately authorized action.
|
||
|
||
## Delivery order
|
||
|
||
| Milestone | Work | Exit condition |
|
||
| --- | --- | --- |
|
||
| M0: reliable evidence | H01, P01, initial Q01/Q02 | Identity and command fixtures for each target; failed tests retain reports |
|
||
| M1: trustworthy acquisition | P02–P04, C01, initial I01/I02 | Basic and Ultra scans use verified profiles; timeout/cancel/recovery work |
|
||
| M2: analyzer parity | A01–A07, continuing I01/I02/Q01/Q02 | Analyzer controls and traces exposed and qualified per profile |
|
||
| M3: remaining device workflows | G01, D01–D04 | Generator, display, persistence, calibration and management classified/implemented |
|
||
| M4: supported release | I03, Q02, Q03 | Complete feature ledger and tested releases for explicitly supported combinations |
|
||
|
||
Start the small `list`/`inspect` CLI in M0 and extend it feature by feature.
|
||
Do not postpone all interface work until every analyzer control exists.
|
||
Hardware evidence collection can run alongside implementation; it is a gate
|
||
for support claims, not a reason to stop developing transcript tests.
|
||
|
||
## M0 — evidence and device identity
|
||
|
||
### H01 — harden the guided hardware validator
|
||
|
||
Depends on H00; extend incrementally with P01/P03/P04. Start in
|
||
`examples/validate-hardware.rs`, `scripts/test-hardware.sh`, and the checklist.
|
||
|
||
- [ ] Treat stdin EOF as cancellation. Do not interpret a closed input stream
|
||
as confirmation to start a scan.
|
||
- [ ] Retry enumeration for a bounded interval; require explicit selection if
|
||
no newly attached port is found. The current sole-port fallback can select an
|
||
unrelated serial device. Handle multiple devices and permissions explicitly.
|
||
- [ ] Query identity and `help` before any mutating acquisition. Confirm the
|
||
selected model/profile before scanning; current confirmation happens afterward.
|
||
- [ ] Create a unique session directory with exclusive creation and write the
|
||
initial report immediately. Append/checkpoint each stage so early I/O failures
|
||
preserve identity, completed work and the original failure.
|
||
- [ ] Record app revision/version, OS, model label, firmware, raw identity/help,
|
||
test settings including zero offset and frequency-axis policy, and timestamps.
|
||
Preserve bounded raw transcripts separately from sanitized terminal text.
|
||
- [ ] Give separate pass/fail/skipped/unverified results for command acceptance,
|
||
data framing, export, operator identity and front-panel recovery. A no-signal
|
||
scan cannot establish RF amplitude or frequency accuracy or prove zero readback.
|
||
- [ ] Run paired legacy/direct scans with identical settings before attributing
|
||
differences to the preparatory scan. Keep Basic high-path coverage as its own
|
||
case; currently Basic changes path and preparation in the same comparison.
|
||
- [ ] Add portable invocation instructions using `cargo run --example` on
|
||
Windows, an optional prebuilt validator, and concise `--help`/argument errors.
|
||
- [ ] Add optional reference-source and unplug/reconnect stages after P03/P04;
|
||
skip them explicitly when equipment is absent. Prompt once per physical wiring
|
||
change, automate all software checks, and retain a useful final summary.
|
||
|
||
Acceptance: test EOF, ambiguous ports, wrong model, second-scan failure, failed
|
||
report writes and negative operator confirmation without hardware. A real failed
|
||
run must still leave a report; a skipped check must never become a pass.
|
||
|
||
### P01 — inventory, identification and capabilities
|
||
|
||
Depends on F01–F04; H01 supplies evidence. Touch acquisition identification and
|
||
add a concrete `device` module plus versioned fixture metadata.
|
||
|
||
- [ ] Build a ledger per exact device/build: feature, command/arguments, units,
|
||
limits, query/readback form, mutation/persistence effects, source revision,
|
||
test fixture and support status.
|
||
- [ ] Inventory both official menu trees and command registration at the matching
|
||
firmware commit. Resolve the differing upstream repository references in local
|
||
docs against each captured firmware; do not treat a moving branch as evidence.
|
||
- [ ] Parse `version`/`info` after removing only known echo/prompt framing. Reject
|
||
empty and echo-only replies; retain unknown fields verbatim.
|
||
- [ ] Parse command availability from `help`, but distinguish advertised commands
|
||
from verified argument forms and successful readback.
|
||
- [ ] Represent identity confidence and unknown firmware explicitly. Permit a
|
||
recorded profile override without pretending it proves hardware identity.
|
||
- [ ] Gate optional diagnostic queries (`threads`, `usart_cfg`, etc.) on
|
||
availability; an absent debug command must not invalidate a supported scan.
|
||
- [ ] Keep inspection free of calibration, RF-output and persistent-write probes.
|
||
|
||
Acceptance: Basic, Ultra, unknown build, conflicting identity, echo-only and
|
||
missing-optional-command fixtures produce the expected profile or an explicit
|
||
unsupported/uncertain result before settings change.
|
||
|
||
## M1 — reliable Basic and Ultra acquisition
|
||
|
||
### P02 — separate model policy from raw decoding
|
||
|
||
Depends on P01. Main files: `src/protocol.rs`, `src/acquisition.rs`,
|
||
`src/config.rs`, `src/ui/state.rs`, `src/ui/mod.rs` and `src/mock/`.
|
||
|
||
- [ ] Move Basic physical-path/range selection out of generic frame-length and
|
||
sample-decoding rules. Keep delimiters, little-endian representation and raw
|
||
scale in the protocol module.
|
||
- [ ] Introduce a validated acquisition plan containing selected profile/path,
|
||
command sequence, sample count, axis policy and confirmed encoding offset.
|
||
- [ ] Preserve the current Basic overlap/boundary policy unless hardware evidence
|
||
justifies a documented change; test spans below, at and across each boundary.
|
||
- [ ] Add Ultra normal/extended/harmonic mode plans only for evidenced ranges.
|
||
Never send Basic `mode high input` on Ultra. Distinguish hardware revisions,
|
||
unlocked state and firmware limitations; the mock's ceiling is not a spec.
|
||
- [ ] Remove Basic-only UI/config ceilings when a resolved profile supplies the
|
||
range. Split structural config validation from post-identification validation
|
||
so detection can occur before rejecting a legitimate Ultra request.
|
||
- [ ] Verify `zero` acceptance/readback where available, bind the decoder to the
|
||
actual encoding, and expose uncertainty when a setting cannot be confirmed.
|
||
- [ ] Resolve frequency assignment using matching firmware and a reference
|
||
signal; preserve legacy inclusive behavior through an explicit migration.
|
||
- [ ] Qualify removal/replacement of the legacy `scan ... 290 101` preparation;
|
||
explain its undocumented mask and observed effects before changing defaults.
|
||
|
||
Acceptance: Basic path boundaries and Ultra boundaries reject invalid plans
|
||
without writes; valid Ultra plans above 960 MHz work on declared hardware.
|
||
Known-source measurements verify frequency/level conversion, including the
|
||
potential 46 dB offset mismatch. No synthetic result alone closes this task.
|
||
|
||
### P03 — typed replies, deadlines, abort and reconnect
|
||
|
||
Depends on P01; develop alongside P02. Extend `src/transport.rs` and
|
||
`src/connection.rs`; add small command-specific parsers as needed.
|
||
|
||
- [ ] Define typed replies/errors for implemented commands. Handle known firmware
|
||
rejection variants, optional echoes and readback mismatches; a prompt alone is
|
||
not acknowledgement of a setting change.
|
||
- [ ] Track an overall transaction deadline separately from idle read timeout.
|
||
Bound each blocking adapter call by remaining time; checking a clock only
|
||
between indefinitely blocking reads is insufficient.
|
||
- [ ] Add a cancellation token checked at bounded intervals, verified firmware
|
||
abort syntax, and a drain/resynchronization state before another command.
|
||
- [ ] Decode streaming/aborted frames with explicit complete/partial states.
|
||
Never search arbitrary sample bytes for a text prompt.
|
||
- [ ] Include command, stage, expected/received bytes and bounded diagnostics in
|
||
errors. Keep binary captures as bytes; escape terminal-control characters.
|
||
- [ ] Retry only operations known to be safe/idempotent. Reconnect must reidentify
|
||
the unit and reset stale buffers; never replay output/calibration mutations.
|
||
- [ ] Introduce a clock/adapter test seam only where needed to simulate elapsed
|
||
deadlines and blocking behavior deterministically.
|
||
|
||
Acceptance: fragmented prompts, slow trickle, total silence, late replies,
|
||
unplug mid-frame, aborted short frames and reconnect to another device all
|
||
terminate predictably without reporting partial data as a complete acquisition.
|
||
|
||
### P04 — session ownership and state restoration
|
||
|
||
Depends on P02/P03. A concrete session should own connection, identified profile,
|
||
operation state and restorable settings; the UI owns its worker lifetime.
|
||
|
||
- [ ] Snapshot queryable settings before mutation and track only successful
|
||
changes. Record settings whose previous values cannot be queried.
|
||
- [ ] Restore settings in a verified order on success, failure and cancellation;
|
||
preserve the primary failure together with every recovery failure.
|
||
- [ ] Replace detached worker exit with cancel-and-join under a bounded timeout.
|
||
Ensure `q`, Escape and process interrupts do not silently abandon acquisition.
|
||
- [ ] Expose recovery as events/status, not just a `Drop` side effect. Abort-mode
|
||
panics, unplugged devices and power loss cannot guarantee remote restoration.
|
||
- [ ] Prevent simultaneous commands from UI, scanning and diagnostics. Document
|
||
limits of OS port exclusivity rather than assuming universal locking.
|
||
- [ ] Do not automatically re-enable RF output when restoring a preset/session;
|
||
generator recovery needs a separate, explicit state policy in G01.
|
||
|
||
Acceptance: inject failure after each mutation and assert restoration attempts,
|
||
error preservation and worker termination. Verify final device state physically;
|
||
mark unavailable restoration as incomplete, never silently successful.
|
||
|
||
### C01 — typed settings and compatibility migration
|
||
|
||
Depends on P01/P02; accompanies every new control. Extend `src/config.rs`,
|
||
`config/default.toml`, persistence and configuration examples.
|
||
|
||
- [ ] Design explicit profile selection, analyzer settings and operation timeout
|
||
sections; distinguish requested settings from observed device state.
|
||
- [ ] Preserve six legacy selection keys and existing partial overrides, or
|
||
provide a tested migration with backup and actionable errors.
|
||
- [ ] Validate units, finite values, supported enum choices, mode combinations,
|
||
allocation limits and empty collections before commands/output creation.
|
||
- [ ] Keep model/wire invariants in code/profile evidence; changing a config
|
||
number must not authorize an unsupported physical range.
|
||
- [ ] Persist only intended user settings; do not silently save transient
|
||
generator enablement or hardware identity as permanent truth.
|
||
|
||
Acceptance: old configs still load, unknown keys fail, invalid combinations
|
||
cause no mutations, and failed persistence leaves the previous config usable.
|
||
|
||
## M2 — analyzer feature coverage
|
||
|
||
Each A-task depends on P01–P04/C01 and must extend I01/I02/Q01/Q02 in the same
|
||
feature slice. Firmware-only controls are conditional on the capability ledger.
|
||
|
||
### A01 — frequency, sweep and timing controls
|
||
|
||
- [ ] Add start/stop and center/span conversion with checked arithmetic; separate
|
||
frequency sweeps from CW/zero-span time traces so the axis cannot be mislabeled.
|
||
- [ ] Add supported point counts, repeat, sweep time, single/continuous operation
|
||
and actual frequency tables/readback rather than assuming requested settings.
|
||
- [ ] Inventory external reference, frequency offset, wideband/multiband and
|
||
segment behavior; implement supported forms with explicit metadata.
|
||
- [ ] Estimate progress from known phases without presenting byte count as a
|
||
reliable prediction of measurement duration.
|
||
|
||
Acceptance: boundary and overflow tests; compare requested/actual sweep and time
|
||
axis on hardware. Unsupported sweep forms fail before commands are sent.
|
||
|
||
### A02 — input paths, attenuation, gain and Ultra modes
|
||
|
||
- [ ] Model Basic low/high input separately from Ultra normal/extended/harmonic
|
||
modes; surface the physical connector and selected mode to the user.
|
||
- [ ] Add manual/automatic attenuation, available AGC/LNA stages and legal
|
||
combinations using per-profile ranges and mutual-exclusion rules.
|
||
- [ ] Inventory exposed IF and expert controls; retain automatic defaults until
|
||
an explicit user choice and verified syntax justify changing them.
|
||
- [ ] Capture overload/readback indicators where available; distinguish measured
|
||
overload status from a host heuristic.
|
||
|
||
Acceptance: illegal combinations are rejected, transitions/readback match the
|
||
panel, and low-level reference measurements show expected gain changes within
|
||
documented tolerances. Do not use damage-limit signals as test inputs.
|
||
|
||
### A03 — bandwidth, detector and trace processing
|
||
|
||
- [ ] Implement auto/manual RBW and available VBW with explicit unit conversion
|
||
at command boundaries; profile limits may differ.
|
||
- [ ] Add supported averaging, detector/calculation modes, min/max hold,
|
||
reference/subtraction traces and spur controls, including reset semantics.
|
||
- [ ] Record firmware processing separately from host processing. Changing span,
|
||
RBW or mode must invalidate incompatible accumulated/reference traces.
|
||
- [ ] Keep state and bounded trace buffers outside terminal rendering code.
|
||
|
||
Acceptance: deterministic sequences verify averaging/hold/reset; real-device
|
||
fixtures verify command forms, and RF tests record their bandwidth/settings.
|
||
|
||
### A04 — amplitude, display units and correction
|
||
|
||
- [ ] Add supported reference level, scale and display units; keep canonical
|
||
exported levels explicit and do not change values merely to fit a chart.
|
||
- [ ] Separate raw encoding offset, external loss/gain and calibration correction
|
||
in types and metadata; prevent correction from being applied twice.
|
||
- [ ] Define conversions requiring impedance or bandwidth only when that context
|
||
is available. Never label arbitrary dBm conversions as noise density.
|
||
- [ ] Validate correction tables for ordering, units, interpolation and range
|
||
policy; device-persistent calibration writes belong to D03.
|
||
|
||
Acceptance: numeric tests cover zero/negative/non-finite inputs and round trips;
|
||
reference measurements verify exported amplitude and visible correction state.
|
||
|
||
### A05 — trace APIs, streaming and export provenance
|
||
|
||
- [ ] Add typed ASCII scan, binary raw, stored trace and frequency-query decoders
|
||
only for advertised forms. Verify frequency/value lengths and record counts.
|
||
- [ ] Introduce trace metadata: device/build/profile, requested and actual range,
|
||
axis policy, offset, RF path, processing, timestamps and completion status.
|
||
- [ ] Support repeated snapshots before native continuous frames; both need
|
||
bounded queues, cancellation, backpressure and explicit dropped-frame counts.
|
||
- [ ] Preserve current two-column CSV compatibility. Add opt-in metadata sidecars
|
||
or a documented versioned format; keep serialization independent of paths.
|
||
- [ ] Define atomic completion for trace plus metadata and a clearly labeled
|
||
partial-output policy. Disk-full/cancel must not leave a success-looking file.
|
||
|
||
Acceptance: transcript replay, multiple frames per read, truncated streaming
|
||
frames, full queues and disk failures preserve correct ordering and status.
|
||
|
||
### A06 — markers and measurement readouts
|
||
|
||
- [ ] Implement available marker enable/select/move, peak, tracking, reference
|
||
and delta controls with typed frequency/level results.
|
||
- [ ] Inventory model-specific readouts and measurement modes; implement each
|
||
exposed form or record a precise front-panel limitation.
|
||
- [ ] Distinguish firmware readouts from calculations over exported samples;
|
||
include algorithm and resolution when the host computes a result.
|
||
- [ ] Handle flat traces, tied peaks, nonuniform frequency tables and stale traces.
|
||
|
||
Acceptance: known trace fixtures and device-panel comparisons agree within
|
||
specified resolution/tolerance; unsupported readouts are never fabricated.
|
||
|
||
### A07 — trigger workflows
|
||
|
||
- [ ] Inventory trigger sources, level, polarity, position and auto/single modes
|
||
per build; add validated operations and readback where available.
|
||
- [ ] Represent armed, waiting, triggered, complete, cancelled and failed states.
|
||
Trigger waiting must have its own configurable deadline/status.
|
||
- [ ] Combine cancellation with P03 abort/resynchronization and P04 restoration.
|
||
|
||
Acceptance: no-trigger timeout, delayed trigger, cancel while armed and repeated
|
||
arming are covered synthetically and with a controlled hardware stimulus.
|
||
|
||
## M3 — generator and remaining device workflows
|
||
|
||
### G01 — RF generator
|
||
|
||
Depends on P01–P04/C01. Add a dedicated generator state/operation module rather
|
||
than reusing analyzer input-mode booleans.
|
||
|
||
- [ ] Inventory Basic output paths and Ultra output modes, frequency/level
|
||
bounds, step sizes, swept frequency/level and supported modulation variants.
|
||
- [ ] Add configure, explicitly enable, query and disable operations; opening
|
||
a connection, identifying a unit or loading a host profile must not emit RF.
|
||
- [ ] Validate modulation type/depth/rate and sweep parameters per profile before
|
||
switching modes. Record which limits cannot be remotely read back.
|
||
- [ ] Implement orderly shutdown/output-off attempts and report unknown state
|
||
after disconnect; never promise software can turn off an unreachable device.
|
||
- [ ] Extend CLI/TUI with visible output state and a direct stop control.
|
||
|
||
Acceptance: command-order/failure tests plus frequency/level/modulation checks
|
||
using suitable external equipment and a documented terminated/attenuated setup.
|
||
Analyzer-only or no-signal tests cannot qualify this task.
|
||
|
||
### D01 — display capture and remote panel
|
||
|
||
Depends on P01/P03; use A05 metadata conventions.
|
||
|
||
- [ ] Implement profile-specific capture dimensions/pixel format and exact byte
|
||
counts in a pure decoder; test truncated and oversized image responses.
|
||
- [ ] Export screenshots with firmware/settings provenance; keep image encoding
|
||
separate from serial I/O and add a dependency only if justified.
|
||
- [ ] Implement supported refresh, color/display options and touch coordinates
|
||
with bounds checks and known panel dimensions/orientation.
|
||
- [ ] Classify front-panel-only features explicitly. Touch navigation sequences
|
||
are firmware-specific automation, not a replacement for a typed command API.
|
||
|
||
Acceptance: capture fixtures decode correctly; hardware screenshots match the
|
||
panel; malformed captures cannot desynchronize the following command.
|
||
|
||
### D02 — presets, traces and storage
|
||
|
||
Depends on P04/C01/A05.
|
||
|
||
- [ ] Separate host profiles, instrument preset slots and removable storage in
|
||
types and UI. Inventory query/save/recall/delete support per firmware.
|
||
- [ ] Prevent accidental overwrite, path traversal and invalid names; use atomic
|
||
replacement for host files and explicit intent for device persistence.
|
||
- [ ] Read back settings after recall and refresh capabilities/trace provenance
|
||
if a preset changes mode. Recalled output state follows G01 policy.
|
||
- [ ] Implement SD trace/screenshot/file access only when a documented remote
|
||
interface exists; otherwise supply the verified manual transfer procedure.
|
||
|
||
Acceptance: full storage, missing media, interrupted writes, wrong profile and
|
||
recall failures preserve existing data and expose actual resulting state.
|
||
|
||
### D03 — calibration and self-test
|
||
|
||
Depends on P01–P04 and G01 when calibration output is involved.
|
||
|
||
- [ ] Inventory read-only calibration/status queries separately from self-test,
|
||
calibration-output enablement and persistent correction writes.
|
||
- [ ] Provide model-specific wiring/equipment instructions and explicit entry
|
||
into mutating procedures; do not probe service commands automatically.
|
||
- [ ] Capture preconditions, firmware result codes, before/after status and
|
||
operator observations; use staged progress with a defined abort procedure.
|
||
- [ ] Document recovery if interruption can leave calibration incomplete; never
|
||
claim rollback where firmware provides none.
|
||
|
||
Acceptance: parser/state tests plus operator-performed calibration/self-test
|
||
on each supported revision. Skipped equipment or failed firmware results remain
|
||
visible; a mock success never constitutes calibration evidence.
|
||
|
||
### D04 — device information and maintenance
|
||
|
||
Depends on P01/P03/P04.
|
||
|
||
- [ ] Add typed supported battery, device ID, build, clock/RTC and diagnostic
|
||
queries with unknown-field preservation and bounded output.
|
||
- [ ] Distinguish USB CDC settings from internal USART controls; implement only
|
||
verified forms and explain changes that can break the active connection.
|
||
- [ ] Add explicit reset/reconnect lifecycle handling and fresh identification.
|
||
- [ ] Inventory bootloader/update capabilities; where remote updating is not
|
||
supported, provide an exact manual workflow and classify the limitation.
|
||
If implemented, verify target image/device matching and recovery prerequisites.
|
||
|
||
Acceptance: restart, re-enumeration, changed port names and incompatible firmware
|
||
are handled without silently reusing an old profile or repeating mutations.
|
||
|
||
## M4 — interfaces, tests and release qualification
|
||
|
||
### I01 — scriptable command interface
|
||
|
||
Start with P01 inspection; extend alongside each feature family.
|
||
|
||
- [ ] Separate CLI parsing from the small startup entry point; keep ordinary TUI
|
||
startup compatible. Provide real `--help`/`--version` that never initialize a
|
||
terminal, enumerate/open a port or start an RF operation.
|
||
- [ ] Add discover/inspect/acquire first, then typed analyzer, generator, capture
|
||
and preset subcommands as their library APIs arrive.
|
||
- [ ] Define explicit model/port selection, machine-readable output, stable exit
|
||
categories and stdout/stderr separation; noninteractive mode must never prompt.
|
||
- [ ] Return failures for acquisition/export/recovery errors and propagate
|
||
cancellation/interrupt status. Validate config before opening output.
|
||
|
||
Acceptance: subprocess tests cover invalid arguments, no terminal, missing port,
|
||
unknown profile, timeout, cancellation and successful machine-readable output.
|
||
|
||
### I02 — capability-aware terminal UI
|
||
|
||
Depends incrementally on P01/P02 and each exposed feature.
|
||
|
||
- [ ] Display model/build/connection state and derive field limits/choices from
|
||
capabilities. Explain unavailable features rather than offering illegal values.
|
||
- [ ] Add rescan and return-to-settings without restarting, live plots, marker
|
||
controls and appropriate analyzer/generator/preset screens.
|
||
- [ ] Keep worker events/state updates outside rendering; add cancel, recovery,
|
||
trigger-wait and reconnect states without blocking the event loop.
|
||
- [ ] Label MHz/dBm/time axes, selected path, corrections, output state and dropped
|
||
frames. Keep rendering bounded on small terminals and long acquisitions.
|
||
|
||
Acceptance: in-memory rendering/event tests plus keyboard testing on real
|
||
terminals; every implemented end-user feature has a documented access path.
|
||
|
||
### I03 — public library and compatibility policy
|
||
|
||
Depends on stable P02–P04 interfaces, then evolves with feature slices.
|
||
|
||
- [ ] Expose session/profile/trace/error types with Rustdoc for units, invariants,
|
||
side effects, cancellation and restoration guarantees.
|
||
- [ ] Keep native serial and TUI optional; prove core-only downstream builds and
|
||
caller-provided streams remain usable.
|
||
- [ ] Document breaking changes and migration for config, exported metadata and
|
||
library calls. Add small downstream examples for Basic and Ultra inspection
|
||
and acquisition rather than speculative framework abstractions.
|
||
|
||
Acceptance: MSRV and feature matrix pass; examples build independently and public
|
||
APIs do not leak terminal types into device/protocol layers.
|
||
|
||
### Q01 — feature contracts, fixtures and fault coverage
|
||
|
||
Continuous task accompanying each feature.
|
||
|
||
- [ ] Add stateful mock behavior only for implemented commands; unsupported forms
|
||
continue to reject rather than return universal `ok` responses.
|
||
- [ ] Store approved bounded real transcripts with model/build/date/settings,
|
||
source provenance and byte-exact binary fixtures; redact identifying details
|
||
without altering protocol behavior.
|
||
- [ ] Replay identical feature contracts against mocks, captured transcripts and
|
||
explicitly enabled hardware sessions. Label their evidence levels separately.
|
||
- [ ] Add delayed responses, interrupted/partial writes, buffer limits, disconnect
|
||
at each mutation, rejected settings and recovery failures.
|
||
- [ ] Use property/exhaustive boundary tests for pure codecs where valuable;
|
||
never exclude production code to improve the reported coverage percentage.
|
||
|
||
Acceptance: each capability-ledger row links to a relevant test, and simulation
|
||
tests assert semantic outcomes as well as the actual command sequence.
|
||
|
||
### Q02 — hardware, host and distribution matrix
|
||
|
||
Depends on H01 and the feature being qualified.
|
||
|
||
- [ ] Maintain rows for exact Basic/Ultra revision + firmware + host OS + transport
|
||
+ build/artifact version, with pass/fail/skipped/unverified per feature group.
|
||
- [ ] Execute no-signal checks first; add calibrated/reference measurements for
|
||
frequency, amplitude, processing, triggers and generator as equipment permits.
|
||
- [ ] Measure tolerances from the chosen instrument specification and reference
|
||
uncertainty before running tests; do not retrofit thresholds to observed data.
|
||
- [ ] Test permissions, multiple devices, sleep/wake, USB unplug, reconnect and
|
||
extended acquisition memory/runtime behavior on declared platforms.
|
||
- [ ] Verify packaged binaries as well as source builds; reconcile supported
|
||
targets with `rust-release.toml` and [release guidance](docs/releases.md).
|
||
- [ ] Investigate the Jenkinsfile's documented FreeBSD release-startup SIGILL;
|
||
obtain a reproducible trace/build comparison before declaring that runtime
|
||
supported or making its diagnostic smoke stage a required gate.
|
||
- [ ] Keep local verification, physical-device runs, Jenkins execution and
|
||
publication evidence separate. Do not infer runtime support from compilation.
|
||
|
||
Acceptance: every claimed support combination has retained results and no
|
||
unexplained critical failure; unavailable hardware/platforms remain unverified.
|
||
|
||
### Q03 — final feature audit and support declaration
|
||
|
||
Depends on all baseline tasks for the declared profiles.
|
||
|
||
- [ ] Reconcile every P01 command/menu entry with implementation, interface,
|
||
regression tests, hardware evidence and any remote-control limitation.
|
||
- [ ] Resolve unclassified entries and stale compatibility/README claims.
|
||
Maintain separate Basic and Ultra support tables, including firmware ranges.
|
||
- [ ] Record residual limitations with consequences and evidence needed to
|
||
remove them; do not close tasks using vague future-work notes.
|
||
- [ ] Produce a release acceptance record linking artifacts and measurements,
|
||
migration notes and known issues. Publishing is a separate requested action.
|
||
|
||
Acceptance: no open remote-capable feature in the declared completeness scope;
|
||
any front-panel/upstream limitation is explicit in the public support statement.
|
||
|
||
## Optional stretch goals — choose individually
|
||
|
||
These add host-side capabilities beyond device feature parity. None is selected
|
||
or required for M0–M4. Size is relative implementation effort, not a delivery
|
||
estimate: M = a contained feature with several components; L = multiple feature
|
||
slices; XL = an additional subsystem. Pick by ID, for example `S01, S03, S06`.
|
||
|
||
| Pick | ID | Feature | Depends on | Size |
|
||
| --- | --- | --- | --- | --- |
|
||
| [ ] | S01 | Waterfall, history and offline replay | A05, I02 | L |
|
||
| [ ] | S02 | Scheduled unattended measurement sessions | P03/P04, A05, I01 | L |
|
||
| [ ] | S03 | Spectrum masks, alarms and change detection | A04/A05/A06 | M |
|
||
| [ ] | S04 | Occupancy and channel-power analysis | A01/A03/A04/A05 | L |
|
||
| [ ] | S05 | Wide-span segmented survey planner | P02/P04, A01/A02/A05 | L |
|
||
| [ ] | S06 | Measurement comparison and report bundles | A04/A05, D01 | M |
|
||
| [ ] | S07 | Local web dashboard and remote-control service | P04, I01/I03 | XL |
|
||
| [ ] | S08 | Multiple instruments and comparison sessions | P04, A05, I03 | XL |
|
||
| [ ] | S09 | Generator/analyzer characterization recipes | G01, A04/A05, P04 | XL |
|
||
| [ ] | S10 | Python analysis bindings | I03, A05 | L |
|
||
| [ ] | S11 | Guided overload and measurement-quality assistant | A02–A05, Q02 | L |
|
||
| [ ] | S12 | Additional export formats and integrations | A05, I01 | M |
|
||
|
||
### S01 — waterfall, history and offline replay
|
||
|
||
- [ ] Define a versioned recording containing timestamped traces and immutable
|
||
settings snapshots; use a bounded ring buffer and configurable disk retention.
|
||
- [ ] Render waterfall/time-history with pause, zoom and color scale; replay
|
||
recordings through the same view without opening a device.
|
||
- [ ] Test missing frames, changing axes, bounded memory, truncated recordings
|
||
and replay speed. Acceptance: a recorded session reproduces its trace order,
|
||
timing and settings; gaps remain visible rather than interpolated silently.
|
||
|
||
### S02 — scheduled unattended sessions
|
||
|
||
- [ ] Define recipes with profile, span, interval, duration, output retention,
|
||
retry limits and collision policy; use monotonic time for intervals.
|
||
- [ ] Run one owner per connection, checkpoint progress, detect disk exhaustion,
|
||
and recover only safe analyzer operations after reconnect.
|
||
- [ ] Integrate through the headless CLI before adding a scheduler UI. Test clock
|
||
jumps, missed intervals and process restart. Acceptance: bounded, resumable
|
||
sessions report missed measurements and do not reactivate RF output.
|
||
|
||
### S03 — spectrum masks and alerts
|
||
|
||
- [ ] Represent frequency-dependent limits with units, interpolation, hysteresis,
|
||
debounce and an explicit response to missing/out-of-range samples.
|
||
- [ ] Compare compatible traces against masks or saved baselines and retain the
|
||
triggering trace plus settings as evidence.
|
||
- [ ] Start with local events/files; outbound notifications require a selected
|
||
integration. Acceptance: synthetic edge cases verify no alert chatter, while
|
||
dropped/incompatible data creates uncertainty rather than a false pass.
|
||
|
||
### S04 — occupancy and channel-power analysis
|
||
|
||
- [ ] Define channel plans, level thresholds, observation duration and denominators
|
||
that account for scan gaps and unequal dwell time.
|
||
- [ ] Implement linear-power integration only with defensible bandwidth/sample
|
||
assumptions; report RBW, detector and uncertainty with every result.
|
||
- [ ] Test analytic synthetic spectra and controlled signals. Acceptance: label
|
||
sweep-based estimates explicitly; do not claim simultaneous real-time capture,
|
||
demodulation or IQ information that the source trace does not contain.
|
||
|
||
### S05 — segmented surveys
|
||
|
||
- [ ] Plan overlapping segments constrained by model/path/RBW/point limits;
|
||
estimate duration and show any required physical connector change.
|
||
- [ ] Preserve each segment's settings and timing; define overlap/deduplication
|
||
and level-discontinuity handling before constructing a combined trace.
|
||
- [ ] Test cancellation/resume and segment-boundary peaks. Acceptance: no missing
|
||
frequencies or hidden cross-path correction; never assume software can switch
|
||
a Basic cable between physical connectors.
|
||
|
||
### S06 — comparison and reproducible reports
|
||
|
||
- [ ] Compare recordings only after checking axes, RF path, correction and
|
||
bandwidth compatibility; make interpolation explicit and retain originals.
|
||
- [ ] Generate a portable HTML report first: plots, settings, identity, reference
|
||
setup, uncertainty, pass/fail criteria and links to original trace data.
|
||
- [ ] Add deterministic fixtures for differences and missing metadata.
|
||
Acceptance: another user can recompute the comparison from the exported bundle.
|
||
|
||
### S07 — local web dashboard and control service
|
||
|
||
- [ ] Wrap the typed session API with one device owner, bounded requests and
|
||
streamed telemetry; begin bound to localhost with view-only operation.
|
||
- [ ] Add explicit control ownership, authentication for network exposure and
|
||
operation authorization; never expose arbitrary shell/serial command execution.
|
||
- [ ] Provide cancellation and disconnect behavior matching the native client.
|
||
Acceptance: concurrent browsers cannot interleave commands, exhaust queues or
|
||
leave output state misrepresented. Deployment is a separate scope decision.
|
||
|
||
### S08 — multiple instruments
|
||
|
||
- [ ] Maintain independent sessions/capabilities and stable device selection;
|
||
record host/device timestamps and measured scheduling skew.
|
||
- [ ] Coordinate start/stop and comparison while isolating a failed unit; model
|
||
hardware synchronization only where an actual supported interface exists.
|
||
- [ ] Test two mocks with different timing plus paired hardware.
|
||
Acceptance: do not label host-scheduled USB scans phase-coherent or simultaneous.
|
||
|
||
### S09 — characterization recipes
|
||
|
||
- [ ] Define typed generator/analyzer steps, expected wiring, settling, source
|
||
limits and a dry-run plan; require explicit output enablement at execution.
|
||
- [ ] Capture scalar gain/loss versus frequency with fixture/reference corrections
|
||
and preserve raw measurements. Do not label scalar data vector S-parameters.
|
||
- [ ] Add stop/recovery for failure on either instrument and operator checkpoints
|
||
for cabling. Acceptance: reference fixtures reproduce known scalar behavior
|
||
within stated uncertainty; disconnected output state is reported as unknown.
|
||
|
||
### S10 — Python analysis bindings
|
||
|
||
- [ ] Select a concrete use case first; compare invoking the stable CLI with a
|
||
native binding before adding packaging and interpreter dependencies.
|
||
- [ ] Expose profiles, traces, metadata and structured exceptions; document
|
||
ownership/cancellation if direct device access is included.
|
||
- [ ] Test wheels/imports on chosen platforms and version the binding contract.
|
||
Acceptance: notebooks can inspect/replay/analyze traces without hidden device
|
||
access and without requiring terminal dependencies.
|
||
|
||
### S11 — measurement-quality guidance
|
||
|
||
- [ ] Detect suspicious overload/image patterns using documented heuristics and
|
||
explain confidence; never equate a heuristic with calibrated diagnosis.
|
||
- [ ] Offer guided attenuation/span/RBW comparison steps with operator approval
|
||
for physical changes, keeping original measurements and settings.
|
||
- [ ] Validate suggestions against reference setups and known false positives.
|
||
Acceptance: advice is tied to recorded evidence and cannot silently alter
|
||
calibration, RF output or user-selected pass/fail criteria.
|
||
|
||
### S12 — additional exports and integrations
|
||
|
||
- [ ] Choose actual consumers and formats before adding dependencies: versioned
|
||
JSON/JSONL, analysis-tool imports, compressed archives or selected databases.
|
||
- [ ] Serialize the common A05 trace model with units, identity, corrections and
|
||
completion status; stream large datasets and document precision loss.
|
||
- [ ] Add round-trip/schema compatibility tests and interrupted-write recovery.
|
||
Acceptance: data retains provenance across formats; external publication or
|
||
account writes require a separately selected integration and destination.
|
||
|
||
## Suggested first implementation slice
|
||
|
||
Choose H01 + P01 first: identify before mutation, preserve failure reports,
|
||
capture `help`, and create the per-firmware capability ledger. Then implement
|
||
one end-to-end M1 slice: verified Basic/Ultra profile, one-shot acquisition,
|
||
bounded cancellation/recovery, minimal inspect/acquire CLI and its hardware test.
|
||
After that, prioritize analyzer tasks or select stretch goals by ID; selecting a
|
||
stretch goal brings its listed prerequisites into scope but does not select the
|
||
other stretch goals.
|