docs: plan complete Basic and Ultra feature coverage
This commit is contained in:
parent
b0be23639f
commit
6893bf890a
|
|
@ -16,6 +16,10 @@ before connecting an Ultra or Ultra+.
|
|||
|
||||
## Documentation
|
||||
|
||||
- [Feature completion roadmap](docs/roadmap.md) — prioritized Basic/Ultra tasks and acceptance criteria
|
||||
- [Library integration](docs/library.md) — core-only builds and optional adapters
|
||||
- [Mock device](docs/mock-device.md) — portable TCP server and deterministic testing
|
||||
|
||||
- [Documentation index](docs/README.md) — where to start and source policy
|
||||
- [Configuration](docs/configuration.md) — defaults, partial overrides, units, validation, and saved selections
|
||||
- [Release guide](docs/releases.md) — wrapper, target/artifact policy, token handling, and publication readiness
|
||||
|
|
|
|||
|
|
@ -50,3 +50,7 @@ grows into many chapters, the files are already organized so that a future
|
|||
- [Agent/contributor guidance](../AGENTS.md): code structure, comments, documentation and atomic commits.
|
||||
|
||||
- [Releases](releases.md): release wrapper, prerequisites, collision checks and publication policy.
|
||||
|
||||
- [Feature roadmap](roadmap.md): model-aware Basic/Ultra completion tasks.
|
||||
- [Library integration](library.md): feature selection and public interfaces.
|
||||
- [Mock device](mock-device.md): in-memory and TCP simulation.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,174 @@
|
|||
# tinySA feature completion roadmap
|
||||
|
||||
This is the task list for reaching documented feature coverage on tinySA Basic
|
||||
and tinySA Ultra. It is a plan, not a claim that either model is fully supported.
|
||||
Reviewed 2026-10-04 against the official console/menu documentation and firmware
|
||||
sources linked below. No physical instrument was available for this change.
|
||||
|
||||
“Complete” means every feature of an explicitly supported hardware/firmware
|
||||
combination has either a tested library API and user interface or a documented
|
||||
remote-control limitation. A feature present on the touchscreen is not necessarily
|
||||
available over USB. Ultra+, hardware revisions and firmware build options must
|
||||
be distinct capability profiles, not inferred from the name “Ultra”.
|
||||
|
||||
## Foundations delivered
|
||||
|
||||
- [x] F01: Build a Rust library without terminal/native serial dependencies;
|
||||
retain optional serial and existing default application builds.
|
||||
- [x] F02: Share `Read + Write` framing across native serial, TCP and in-memory
|
||||
adapters; keep acquisition and export independent of UI/filesystem ownership.
|
||||
- [x] F03: Add bounded, stateful mock Basic/Ultra profiles, deterministic raw
|
||||
samples, one-shot faults and a runnable TCP server example.
|
||||
- [x] F04: Exercise production Basic acquisition over fragmented mock I/O and
|
||||
real loopback TCP, including malformed responses and resume attempts.
|
||||
|
||||
These foundations do not complete Ultra acquisition or firmware emulation.
|
||||
See [library integration](library.md) and [mock scope](mock-device.md).
|
||||
|
||||
## Priority 0 — trustworthy model-aware acquisition
|
||||
|
||||
- [ ] P01 **Inventory and capability negotiation** (depends F01–F04). Capture
|
||||
`version`, `info`, `help` and matching firmware commit/build options for Basic
|
||||
and each supported Ultra revision. Create a versioned command/capability
|
||||
manifest, including argument forms, units, readback and unsupported features.
|
||||
Unknown firmware must expose uncertainty and permit explicit profile selection.
|
||||
Acceptance: recorded fixtures cover both families and unknown variants; no
|
||||
model selection based only on a shared substring or successful prompt.
|
||||
- [ ] P02 **Separate model rules from raw framing** (P01). Replace Basic-only
|
||||
range/input validation with per-model input paths, ranges, zero offsets,
|
||||
sweep/point limits and frequency-axis semantics. Add Ultra acquisition without
|
||||
sending Basic `mode high input`. Acceptance: boundary tests for each declared
|
||||
profile, hardware scans below/above 960 MHz where supported, and independently
|
||||
verified frequency/dBm values. Do not use the mock's synthetic ceiling as evidence.
|
||||
- [ ] P03 **Robust command sessions** (P01). Typed commands/replies, explicit
|
||||
rejection handling, bounded binary capture readers, deadlines, cancellation,
|
||||
reconnect and resynchronization; preserve context and partial results policy.
|
||||
Acceptance: echoed/un-echoed and fragmented real transcripts, timeout/EOF at
|
||||
each phase, stale prompts, rejected commands, and no silent partial success.
|
||||
- [ ] P04 **State ownership and recovery** (P02–P03). Query and restore supported
|
||||
settings, model pause/resume and generator state explicitly, define exclusive
|
||||
session ownership. Acceptance: failure/cancellation tests for every mutation
|
||||
plus hardware readback; report when full restoration is unavailable.
|
||||
|
||||
## Priority 1 — spectrum analyzer controls and data
|
||||
|
||||
Each item depends on P01–P04. Implement library API first, then mock behavior,
|
||||
CLI/TUI access, documentation and hardware acceptance fixtures in the same task.
|
||||
|
||||
- [ ] A01 **Frequency and sweeps:** start/stop, center/span, CW/zero span, point
|
||||
count, sweep time, continuous/single acquisition, repeat, frequency tables,
|
||||
external frequency reference/offset, wideband and multiband where exposed.
|
||||
Acceptance: requested versus actual frequencies and sweep completion verified.
|
||||
- [ ] A02 **RF input chain:** per-model paths, attenuation/auto attenuation,
|
||||
LNA and other gain/AGC controls, Ultra/auto/harmonic mode, IF choices and
|
||||
overload state where queryable. Acceptance: legal combinations enforced by
|
||||
profile and actual device readback; explain expected RF measurement limitations.
|
||||
- [ ] A03 **Bandwidth and processing:** RBW/automatic RBW, VBW where available,
|
||||
averaging, min/max hold, subtraction/reference traces, spur suppression,
|
||||
detector/calculation modes and reset behavior. Acceptance: trace provenance
|
||||
includes processing settings and corresponding firmware behavior is verified.
|
||||
- [ ] A04 **Amplitude and units:** reference level, scale, displayed units,
|
||||
external gain/loss, level correction tables and offsets. Acceptance: documented
|
||||
conversion semantics and tests prevent double application of corrections.
|
||||
- [ ] A05 **Trace acquisition/export:** ASCII scans, raw scans, trace/data and
|
||||
frequencies queries, multiple/stored traces, streaming/repeated scans and
|
||||
timestamped metadata. Acceptance: bounded memory/backpressure, aligned axes,
|
||||
round-trip datasets and explicit firmware/model/settings metadata.
|
||||
- [ ] A06 **Markers and measurements:** enable/select/move, peak search/tracking,
|
||||
delta/reference markers and firmware-supported measurement readouts.
|
||||
Acceptance: typed units and host-computed versus firmware-computed provenance;
|
||||
values checked against the device display or matching trace.
|
||||
- [ ] A07 **Triggers:** supported sources, level, polarity, position and
|
||||
single-shot/auto modes. Acceptance: trigger waiting can be cancelled and is
|
||||
distinguished from transport failure, with captured hardware trigger cases.
|
||||
|
||||
## Priority 2 — generator and complete instrument workflows
|
||||
|
||||
- [ ] G01 **RF generator** (P01–P04): supported output paths, CW/swept frequency,
|
||||
level/attenuation, output enable, level sweep and available modulation modes
|
||||
(AM/FM/narrow FM and other per-build modes). Acceptance: explicit output state,
|
||||
validated limits, predictable stop/disconnect handling and external measurement
|
||||
of supported settings. Never enable RF output as a probing side effect.
|
||||
- [ ] D01 **Display/remote panel** (P03, A05): screenshot/capture decoding,
|
||||
display refresh, touch injection, remote navigation and color/trace settings
|
||||
where exposed. Acceptance: exact dimensions/pixel encoding per profile,
|
||||
truncated-image tests and documented controls unavailable through the console.
|
||||
- [ ] D02 **Presets and storage** (P04): load/save/recall instrument presets,
|
||||
host profiles, saved traces/screenshots and SD features where remotely exposed.
|
||||
Acceptance: distinguish volatile state, instrument persistence and host files;
|
||||
prevent accidental overwrite and support versioned configuration migration.
|
||||
- [ ] D03 **Calibration and self-test** (P01–P04): calibration output, self-test,
|
||||
calibration/correction readback and firmware-supported calibration workflows.
|
||||
Acceptance: guided prerequisites, explicit persistent changes, captured results
|
||||
and hardware verification; simulator results always identified as synthetic.
|
||||
- [ ] D04 **Device management** (P03): battery, device identity, firmware/build,
|
||||
time/RTC, console/USART settings, reset and firmware-update/bootloader workflow
|
||||
if a documented safe interface exists. Acceptance: reconnect behavior tested;
|
||||
unsupported remote update is clearly documented rather than guessed.
|
||||
|
||||
## Priority 3 — access, integrations and qualification
|
||||
|
||||
- [ ] I01 **Headless command interface** (P02, A01–A07): scriptable discovery,
|
||||
inspect/configure/acquire/export commands, stable machine-readable errors and
|
||||
structured output. Acceptance: noninteractive workflows require no terminal,
|
||||
exit codes are tested, and long operations support cancellation.
|
||||
- [ ] I02 **Capability-driven UI** (A01–D04 incrementally): model/firmware banner,
|
||||
units and supported control visibility, streaming plot, markers, generator and
|
||||
saved workflows. Acceptance: every implemented remotely accessible feature
|
||||
has a discoverable entry point; unavailable controls explain the reason.
|
||||
- [ ] I03 **Library API lifecycle** (P02–P04): stable typed device/session facade,
|
||||
builder/configuration versioning, integration examples and a release policy.
|
||||
Decide on asynchronous adapters or foreign-language bindings only with actual
|
||||
integration requirements. Acceptance: downstream example crates compile on
|
||||
the MSRV and API compatibility is assessed before releases.
|
||||
- [ ] Q01 **Expanded mock contracts** (each feature): add tested behavior only
|
||||
for newly implemented commands, transcript replay, delayed/stalled responses,
|
||||
noise fixtures and injected failures at transaction boundaries. Acceptance:
|
||||
shared contract tests exercise adapters and real recorded replies; unsupported
|
||||
commands continue to fail explicitly. Simulation does not certify RF accuracy.
|
||||
- [ ] Q02 **Hardware and platform matrix** (all supported features): Basic and
|
||||
declared Ultra revisions/firmware, Linux/macOS/Windows serial operation,
|
||||
disconnects, permissions and extended acquisition. Acceptance: reproducible
|
||||
test reports with firmware identifiers and reference measurements, separate
|
||||
from mock coverage; Jenkins and packaged releases exercised on their hosts.
|
||||
- [ ] Q03 **Completion audit** (all above): reconcile the capability manifest
|
||||
with the official console list and menu tree. For every entry record API,
|
||||
interface, tests, hardware evidence or precise remote-interface limitation.
|
||||
Acceptance: no unclassified feature or unsupported broad “all tinySA” claim.
|
||||
|
||||
## Coverage audit map
|
||||
|
||||
Use this map when splitting tasks into issues. Command names are discovery
|
||||
candidates, not a universal command contract; firmware conditionals matter.
|
||||
|
||||
| Feature family | Console/menu evidence to inventory | Tasks |
|
||||
| --- | --- | --- |
|
||||
| Identity and build | `version`, `info`, `help`, `deviceid` | P01, D04 |
|
||||
| Frequency/time | `freq`, `sweep`, `sweeptime`, `actual_freq`, `frequencies`, menu multiband | A01 |
|
||||
| Input and gain | `mode`, `attenuate`, `agc`, `lna`, `lna2`, `ultra`, `if`, `if1` | A02 |
|
||||
| Filtering/calculation | `rbw`, `calc`, `spur`, menu VBW | A03 |
|
||||
| Level/units/corrections | `level`, `leveloffset`, `ext_gain`, `correction`, `zero`, display units | A04 |
|
||||
| Data/traces | `scan`, `scanraw`, `data`, `trace`, `repeat`, `pause`, `resume` | A05 |
|
||||
| Markers/triggers | `marker`, `trigger`, measurement menus | A06, A07 |
|
||||
| Generator | output `mode`, `output`, `level`, `levelchange`, `modulation` | G01 |
|
||||
| Display/touch | `capture`, `refresh`, `color`, `touch`, `touchcal`, `touchtest` | D01, D03 |
|
||||
| Presets/files | `save`, `recall`, `load`, `saveconfig`, SD/menu storage | D02 |
|
||||
| Calibration/service | `caloutput`, `selftest`, `test`, `dac`, `sweep_voltage`, `clearconfig` | D03 |
|
||||
| Device lifecycle | `vbat`, `time`, `usart`, `reset`, `release`, build/debug diagnostics | D04 |
|
||||
|
||||
Front-panel-only features may require upstream firmware work. Record that as a
|
||||
separate dependency after checking the matching source; touch emulation alone
|
||||
is not a reliable typed API for every menu feature.
|
||||
|
||||
## Primary references
|
||||
|
||||
- [Official USB interface and commands](https://tinysa.org/wiki/pmwiki.php?n=Main.USBInterface).
|
||||
- [Ultra console transcript](https://tinysa.org/wiki/pmwiki.php?n=TinySA4.ConsoleCommands): historical snapshot, not a current universal schema.
|
||||
- [Ultra menu tree](https://tinysa.org/wiki/pmwiki.php?n=TinySA4.MenuTree): includes functions that may lack console access.
|
||||
- [Basic specifications](https://tinysa.org/wiki/pmwiki.php?n=Main.Specification),
|
||||
[Ultra specifications](https://tinysa.org/wiki/pmwiki.php?n=TinySA4.Specification),
|
||||
[Ultra hardware comparison](https://tinysa.org/wiki/pmwiki.php?n=TinySA4.Comparison).
|
||||
- [Upstream firmware](https://github.com/erikkaashoek/tinySA), especially
|
||||
[command handlers](https://github.com/erikkaashoek/tinySA/blob/main/sa_cmd.c)
|
||||
and [command registration](https://github.com/erikkaashoek/tinySA/blob/main/main.c).
|
||||
These links move; P01 must pin a commit matching each captured device firmware.
|
||||
Loading…
Reference in New Issue