tiny-wb/docs/architecture.md

10 KiB

Project architecture

tiny-wb has a reusable acquisition library and a thin terminal application. The core accepts typed values and I/O interfaces; it does not depend on UI widgets, port discovery, worker threads, or the application's working directory.

Source map

File Responsibility
src/lib.rs Public core module boundary.
src/config.rs Typed settings, recursive partial overrides, legacy-key compatibility and validation.
config/default.toml Authoritative embedded defaults, with units and comments.
src/storage.rs Same-directory atomic replacement for saved configuration.
src/protocol.rs Structural scan validation, wire invariants and pure raw-frame decoding.
src/device.rs Family identification, model-specific ranges, input paths and native offsets.
src/transport.rs Buffered Read + Write shell I/O, complete command writes, text prompts and length-delimited raw frames.
src/connection.rs Runtime serial/TCP adapter; native serial is optional.
src/mock/ Opt-in bounded device simulation and stream server.
examples/mock-tinysa-server.rs Portable TCP listener for the mock, outside release binaries.
src/acquisition.rs Command ordering, progress events, frame decoding and resume attempts.
src/export.rs CSV parsing/serialization over I/O traits and collision-safe file export.
src/live.rs Bounded rolling average, hold and decay calculations over explicit sweeps.
src/main.rs Select single/live/direct-view mode, load configuration, start diagnostics, enumerate ports when needed and manage terminal lifetime.
src/error.rs Application/UI boundary errors with original context.
src/scan.rs Open the configured connection, reopen once after empty/unknown identity, adapt core events to shared progress, and export successful acquisitions.
src/ui/mod.rs Screen transitions, keyboard handling, worker startup and progress reconciliation.
src/ui/state.rs UI state, configured port/baud choices and bounded numeric input.
src/ui/view.rs Ratatui rendering and selection styling.
build.rs Embed Git revision and compile the Windows icon resource.
Jenkinsfile Required quality gates, coverage, badge cleanup/archival/publication and diagnostic smoke execution.

Data flow

embedded defaults + runtime overrides -> validated Config
                                            |
                             startup / terminal controller
                                            |
                       ScanRequest (Hz) + selected Config
                                            |
                                      connection worker
                                            |
                          Shell<Connection> -> acquisition
                                            |
                                decode_frame -> Vec<Sample>
                                            |
                           CSV export + completed UI snapshot

ScanRequest carries Hz, sample count and repeat count. Sample carries MHz and dBm. Units are converted at the UI/core boundary, not inside widgets or file naming. The selected zero offset is both sent to the instrument and used by the decoder. Frequency labeling is an explicit policy; the default mirrors the reviewed firmware's integer/single-precision scanraw calculation, while legacy endpoint-inclusive labels remain available for compatibility. Protocol constants record the native raw-level biases (Basic 128, Ultra 174). device.rs detects the family and validates its acquisition plan. Both the application and validator select the native bias automatically and confirm the readback. See support scope.

The core reports ScanEvent values. ScanState adapts them to one Arc<Mutex<Progress>>; completion publishes samples, filename, status and 100% progress together only after export succeeds. The UI transfers the completed sample vector once, rather than cloning it every frame. Error reporting uses the original error's message instead of a second exhaustive mapping.

UI state machine

SelectingConnection -> SelectingScan -> Scanning -> Complete -> exit
                           ^             |   |
                           +---- n -------+   +-- r --> Scanning
          |                  |             |
          +------------------+-------------+-> Error -> exit
CSV file -------------------------------------> Complete -> exit
--live: SelectingConnection -> SelectingScan -> Live --stop+save--> exit

The constructor takes configuration and enumerated ports as values, without reading files. Selection is clamped before rendering, including empty lists. Before a scan starts, the controller validates the complete selected settings and request, atomically saves settings, then starts a worker. The controller reconciles worker status before drawing; rendering does not consume samples. The complete screen owns one named plot with an independent frequency viewport. An acquired result can repeat its retained request/settings or return to the prefilled scan editor; a standalone CSV remains view-only. Zooming and panning mutate only that viewport, not sample data. This plot boundary can grow into a tabbed collection without coupling CSV parsing or acquisition to Ratatui.

Live mode uses repeated complete snapshots over one configured connection. The worker publishes only decoded sweeps into a bounded TraceBuffer; rendering copies at most once per completed sweep. Stop and save requests cross the shared state boundary, while device I/O and CSV creation remain in the worker. Native continuous scanraw is intentionally deferred because it needs verified abort syntax and stream resynchronization.

The terminal guard restores terminal modes on ordinary returns and unwinding. Configuration and direct-view CSV errors occur before logger initialization; logging and enumeration errors occur before terminal takeover. Process termination or release-mode panic abort cannot be recovered by a guard.

Acquisition and protocol boundary

  1. Validate structural request and sample/repeat limits before using a port.
  2. Synchronize with stale input, allowing an idle timeout only during this step.
  3. Query version/info, validate the detected model's range, check help, and run advertised diagnostics.
  4. Set repeat and the selected raw zero offset, then verify its readback.
  5. Attempt pause, select input mode, and configure the display sweep.
  6. Optionally retain the historical scan START STOP 290 101 preparation.
  7. Request scanraw, consume exactly the expected framed record count, then consume the trailing shell prompt.
  8. Decode/validate all records and attempt resume on success or failure after pause was attempted. Preserve both failures if resume also fails.
  9. Export validated samples and mark the application scan complete.

The transport uses a persistent buffered stream. Prompt matching spans serial reads; bytes beyond a prompt remain available. Binary records are read by length, so sample bytes equal to braces or text characters are not delimiters. EOF, disconnect, oversized text and missing prompts are errors rather than successful partial reads. Writers use write_all, and protocol sequencing does not require unsafe.

See USB protocol for firmware evidence and the unresolved frequency-label compatibility decision. Device facts are not inferred from our synthetic test transcripts.

Configuration and persistence

The six legacy selection keys remain top-level. Additional sections cover serial timing/choices, scan policy, event timing, chart bounds, output and logging. Partial files merge with embedded defaults; unknown or invalid values fail explicitly. Saving selection values retains all recognized sections.

CSV formatting is independent of file creation. The worker does not create a CSV until a complete frame has been validated and acquisition has returned success. Filenames contain microseconds plus a collision counter; exclusive creation avoids overwriting earlier scans. Failed writes remove incomplete files when the filesystem permits it. A file may be visible while being written; the returned path/completed status is the success indicator.

See configuration for settings, paths and exact behavior.

Extension points and remaining limits

  • Add model/capability recognition ahead of request planning. The current Basic mode rules must not be stretched to imply Ultra support.
  • Add new output formats beside write_csv, consuming Sample values rather than parsing the wire format again.
  • Inject transcript streams into Shell and writers into export tests. Keep UI tests on Ratatui's in-memory backend. See testing.
  • Settings change policy and timing; wire delimiters, fixed-point scaling and command grammar remain protocol invariants.
  • Known error/usage replies reject configuration commands, but responses are not a complete typed acknowledgement protocol. An echo-only identity can appear nonempty; prompt arrival alone is not proof of acceptance.
  • Serial timeouts are per-read idle timeouts, not a whole-transaction deadline. Cancellation/abort and complete device-state restoration remain future work. Quitting during a scan can terminate the worker before its resume attempt.
  • Synthetic tests do not establish the connected firmware's frequency stepping, raw-offset acceptance, or need for the legacy preliminary scan. Defaults retain previous behavior until hardware evidence supports changing it.

Dependency policy

The core uses standard-library byte decoding instead of packed_struct, and buffered framing instead of a separate direct memchr dependency. Transitive memchr use elsewhere in the graph is unrelated. Serde/TOML handle settings; serialport, Ratatui, chrono, log/flexi_logger, color-eyre and thiserror retain their device, presentation, timestamp and error-reporting roles.

Library consumers can omit terminal and serial dependencies; see feature selection. The mock uses the same shell/acquisition code over memory or TCP.