197 lines
8.5 KiB
Markdown
197 lines
8.5 KiB
Markdown
# 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
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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](usb-protocol.md).
|
||
|
||
## Persistence and outputs
|
||
|
||
`config.toml` is stored in the process working directory and contains:
|
||
|
||
```toml
|
||
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.
|
||
|
||
## Recommended evolution path
|
||
|
||
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.
|