tiny-wb/docs/architecture.md

8.5 KiB
Raw Blame History

Project architecture

Purpose and boundary

tiny-wb is a single-process desktop terminal application. Its job is narrow: collect an amplitude-versus-frequency sweep from a tinySA through the USB serial console, persist the sweep as CSV, and show the result in a terminal chart.

It is not currently a general tinySA controller, live spectrum display, firmware updater, calibration utility, or Rust protocol library. It changes a small amount of temporary instrument state during acquisition and restores continuous sweeping with resume; it does not restore every preceding device setting.

Runtime data flow

keyboard
   |
   v
Ratatui event loop (AppInfo)
   |  selected port, baud, MHz range, points, repeat
   v
ConnectionInfo (shared Arc<Mutex<...>> state)
   |
   +---- UI thread: render progress, device info, errors, chart
   |
   `---- scan worker thread
           |
           v
      serialport / USB CDC
           |
           v
        tinySA shell ---- text responses ending in "ch>"
           |
           `------------ scanraw binary frame
                              |
                              v
                    parser -> Vec<(MHz, dBm)>
                              |
                              +-> timestamped CSV
                              `-> final Ratatui chart

The UI remains responsive because scanning runs in a worker thread. Clones of ConnectionInfo share progress, status, returned data, messages, file name, and error state through Arc<Mutex<_>> values. The selected connection and scan parameters themselves are copied into the worker.

Source map

File Responsibility
src/main.rs Start file logging and error reporting, initialize/restore the terminal, enumerate serial ports, and run the application.
src/ui.rs Construct defaults, drive the event/render loop, transition screens, spawn the scan worker, plot results, and map errors to user messages.
src/ui_struct.rs Define UI state, selectable fields, baud-rate and port lists, numeric bounds, colors, and navigation helpers.
src/structs.rs Define configuration persistence, shared connection state, status values, and application/protocol error types.
src/scan.rs Open the serial port, issue shell commands, find prompts, request scanraw, parse binary samples, convert levels, and write CSV.
build.rs Embed the Git short hash and, on Windows, compile the application icon resource.
Jenkinsfile Run formatting, checks, tests, Clippy, release build, and a non-fatal interactive-binary smoke diagnostic.

UI state machine

AppState advances in one direction during a normal run:

InitialConfig -> FinalConfig -> Finished -> EndWindow -> exit
      |               |             |
      `---------------+-------------+-> Error -> exit
  • InitialConfig selects a serial port and baud rate.
  • FinalConfig selects start/stop MHz, sample count, and repeat count.
  • Enter from FinalConfig writes config.toml, fills ConnectionInfo, and spawns the worker.
  • Finished is somewhat counter-intuitively the in-progress screen. It polls shared status while the worker runs.
  • EndWindow plots the collected samples and reports success.
  • Error presents the mapped failure and exits on confirmation.

Defaults are 240–960 MHz, 10,001 points, one measurement per frequency, and 115,200 baud. The UI permits 0–960 MHz in 10 MHz steps, 101–1,000,001 points in 100-point steps, and repeat values from 1–1,000. A valid config.toml overrides the defaults. Frequencies are converted from UI MHz to protocol Hz only when ConnectionInfo is filled.

Acquisition pipeline

scan_with_progress performs these operations:

  1. Validate the requested range and choose Basic low or high input mode.
  2. Open the selected port with a 3 s read timeout.
  3. Drain stale input until the shell prompt is seen or reading times out.
  4. Query version, info, leveloffset, vbat, usart_cfg, and threads.
  5. Send repeat N and zero 128.
  6. Query markers, pause the normal sweep, and set the input mode.
  7. Set sweep start/stop, query the sweep, then run a 290-point textual scan.
  8. Send scanraw START STOP POINTS without immediately consuming a text reply.
  9. Read and parse its binary frame, update progress, and write CSV.
  10. Send resume, set progress to 100%, and expose the samples to the UI.

Step 7's textual scan ... 290 101 does not contribute samples to the final CSV; its response is read and discarded. It therefore needs a documented reason or removal during a future protocol cleanup.

Protocol boundary

Text commands are terminated with carriage return (\r). send_cmd sleeps, then reads until it finds the ASCII prompt ch>, and sleeps again. This is a timing-assisted, prompt-delimited request/response protocol. The application does not currently:

  • parse command echo separately from command output;
  • validate an explicit success status;
  • retain bytes after a prompt found in the middle of a serial read;
  • account for a prompt split across two read buffers;
  • preserve partial results after a read timeout;
  • negotiate capabilities from version, info, or help.

The scanraw body is different: it is a binary {...} frame made of three-byte sample records. See USB console and scanraw protocol.

Persistence and outputs

config.toml is stored in the process working directory and contains:

port = "/dev/ttyACM0"
baudrate = 115200
start_frequency = 240
stop_frequency = 960
points = 10001
repeat = 1

Each acquisition immediately creates a timestamped CSV in the working directory. It has no header. Column one is the application-computed frequency in MHz and column two is level in dBm. Logs are produced by flexi_logger in the working directory with its default file naming policy.

Important invariants and risks

  • A scan needs at least two points because host interpolation divides by points - 1; the UI minimum of 101 enforces this, but the parser itself does not.
  • read_port_with_progress estimates 3 * points + 6 bytes. Progress is only an estimate because command echo and prompt bytes are also present.
  • The parser finds the first {, requires each subsequent full triple to start with x, and stops on a triple whose first byte is }. End-frame validation is currently commented out, so a truncated frame can be accepted.
  • The firmware emits sample bytes little-endian even though one wiki sentence labels them “MSB LSB.” The upstream C implementation and the Rust parser both use low byte followed by high byte.
  • Firmware computes scanraw's step as (stop - start) / points, while the host labels samples using (stop - start) / (points - 1). The final host CSV therefore labels its last point at stop, but current firmware measures its last point one step below stop. This should be resolved in code, ideally by testing against the target firmware version.
  • zero 128 deliberately asks firmware to encode the level around a 128 dB offset and the host subtracts 128. Without that command, the documented default offset is 128 for Basic and 174 for Ultra.
  • Input-mode selection encodes Basic-only assumptions. Ultra has no high input command, and the UI cannot request its ranges above 960 MHz.

Dependency roles

  • ratatui and crossterm (through Ratatui) provide terminal rendering and input.
  • serialport enumerates and opens the device.
  • packed_struct decodes the three-byte sample representation.
  • memchr locates { and the ch> prompt.
  • serde and toml persist settings.
  • chrono names scan files.
  • flexi_logger, log, color-eyre, and thiserror cover diagnostics and error propagation.
  • strum derives iteration/counting for menu enums.

The manifest intentionally contains only dependencies used by the current binary. In particular, the parser uses std::sync::OnceLock; no external once_cell dependency is needed.

The cleanest route to reliable multi-model support is to separate four layers:

  1. a byte-accurate transport that preserves unread bytes and uses deadlines;
  2. a shell codec for echo, response, prompt, and binary frames;
  3. a capability/model layer derived from version/info plus explicit firmware quirks;
  4. the TUI and CSV application built on a reusable acquisition API.

Tests should cover prompt fragmentation, binary frames containing arbitrary byte values, truncation, Basic versus Ultra offsets/modes, frequency labeling, timeouts, and disconnects. Captured serial transcripts make good fixtures and do not require hardware in CI.