From 1bc67400f66782c0ea1f57839fdcfa2a62a901af Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 5 Oct 2026 10:04:24 +0200 Subject: [PATCH] docs: streamline project readme --- README.md | 185 +++++++++++------------------------- docs/README.md | 4 +- docs/hardware-validation.md | 9 ++ docs/security-and-ci.md | 10 +- 4 files changed, 74 insertions(+), 134 deletions(-) diff --git a/README.md b/README.md index b7cf1a0..96d1313 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,89 @@ # tiny-wb -![Version](https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/version.svg) -![Tests](https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/test.svg) -![Coverage](https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/coverage.svg) +![tiny-wb version](https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/version.svg) +![Test status](https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/test.svg) +![Line coverage](https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/coverage.svg) -`tiny-wb` is an interactive terminal application that acquires a frequency -sweep from a tinySA over its USB serial console and exports the result as CSV. -It is written in Rust and uses Ratatui for the interface. +`tiny-wb` is an interactive terminal application for acquiring a frequency +sweep from a tinySA over its USB serial console, plotting the result, and +exporting it as CSV. It is intended for tinySA users who want a repeatable scan +workflow and for Rust applications that need its reusable acquisition library. -The application detects tinySA Basic and Ultra families automatically. Basic -retains its low/high paths through 960 MHz; initial Ultra software support covers -the common 0.1–800 MHz normal range with automatic raw-offset selection and -readback. See [support scope and migration](docs/ultra-support.md) for hardware -qualification status and extended-range limitations. +## Support status -## Documentation +- tinySA Basic low and high inputs are supported through 960 MHz, subject to + the instrument's path limits. +- tinySA Ultra and Ultra+ detection and acquisition are implemented for the + shared 0.1–800 MHz normal range, but still await physical hardware + qualification. -- [Implementation tasks and stretch goals](task.md) — detailed Basic/Ultra backlog and optional features to choose -- [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 +See the [compatibility matrix](docs/tiny-wb-operations.md#compatibility-matrix) +and [Ultra support scope](docs/ultra-support.md) before relying on a particular +model, range, or mode. -- [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 -- [Testing guide](docs/testing.md) — hardware-free regression tests and test boundaries -- [Hardware validation](docs/hardware-validation.md) — guided Basic and Ultra acceptance checks -- [Project architecture](docs/architecture.md) — components, state, data flow, - files, dependencies, and extension points -- [tinySA field guide](docs/tinysa-field-guide.md) — models, RF architecture, - specifications, safe operation, measurement practice, calibration, and - firmware -- [USB console and `scanraw` protocol](docs/usb-protocol.md) — framing, - commands, binary decoding, synchronization, and a worked example -- [tiny-wb compatibility and operations](docs/tiny-wb-operations.md) — current - behavior, setup, controls, files, troubleshooting, and known limitations -- [Security, dependency policy, and MSRV](docs/security-and-ci.md) — Rust 1.88 - compatibility floor, locked builds, RustSec, licenses, and CI gates -- [Upstream source catalogue](docs/sources.md) — authoritative links and what - each source is used for +## Requirements -The documentation was checked against the official tinySA wiki and firmware -source on 2026-10-04. Instrument firmware evolves, so `help`, `version`, and -`info` on the connected unit remain the final authority for its command set. +- Rust 1.88.0 or newer +- A powered tinySA Basic, Ultra, or Ultra+ and a data-capable USB cable +- Permission to open the instrument's serial port -The Basic acquisition path was validated on physical hardware on 2026-10-05 -with firmware `tinySA_v1.4-175-g1419a93`. Both the 240–300 MHz low-input scan -and the 350–400 MHz high-input scan returned 101 valid samples, exercised the -fixed-record binary decoder, produced CSV output, and resumed the live sweep. -This is communications and workflow evidence, not frequency or level-accuracy -calibration; see the [hardware validation checklist](docs/hardware-validation.md) -for the tested scope and remaining limitations. +Do not connect an unknown RF source directly to a tinySA. Use suitable external +attenuation for transmitters and a DC block where a DC component may be present. +Read the [safe-operation guidance](docs/tinysa-field-guide.md#safe-operation-read-before-connecting-a-signal) +before connecting a signal. ## Build and run -Install Rust 1.88.0 or newer, connect and power on the instrument, then run: +From the repository root: ```console cargo run --release ``` -On Linux the USB CDC device is commonly `/dev/ttyACM0`; on Windows it appears -as a COM port. The user running `tiny-wb` must have permission to open it. +On Linux the serial device is commonly `/dev/ttyACM0`; on Windows it appears as +a COM port. If the port cannot be opened, follow the +[serial-permission guidance](docs/tiny-wb-operations.md#serial-permissions). -### Linux serial permissions +Use Left/Right or `h`/`l` to select a field, Up/Down or `k`/`j` to change it, +Enter to advance, and `q` or Escape to quit. A successful scan displays a trace +and writes a collision-safe `scan_*.csv` file in the current directory. CSV +frequencies are in MHz and levels are in dBm. -If `tiny-wb` or `scripts/test-hardware.sh` reports `serial connection: -Permission denied`, inspect the device ownership after connecting the tinySA: +## Configuration and documentation -```console -ls -l /dev/ttyACM* /dev/ttyUSB* 2>/dev/null -``` +The selected settings are saved to `config.toml`, or to the path in +`TINY_WB_CONFIG`. Start with the commented [default configuration](config/default.toml) +and consult the [configuration guide](docs/configuration.md) for validation, +units, output, and logging settings. -Add your user to the group shown for the device. This is usually `dialout` on -Debian, Ubuntu, and Fedora, or `uucp` on Arch Linux. For example: - -```console -sudo usermod -aG dialout "$(id -un)" -``` - -Log out completely and back in for the new group membership to take effect, -then confirm that the port is readable and writable: - -```console -id -nG -test -r /dev/ttyACM0 && test -w /dev/ttyACM0 && echo "serial access OK" -``` - -Close serial terminals and other tinySA software before retrying. Run the -application or hardware validator as your normal user, not with `sudo`; avoid -making the device world-writable with `chmod 666`, because that permission is -overly broad and is normally lost when the device reconnects. See the -[operations guide](docs/tiny-wb-operations.md#serial-permissions) for more -platform setup information. - -The interface uses arrow keys or Vim-style `h`, `j`, `k`, `l`. Left/right -selects a field, up/down changes its value, Enter advances, and `q` or Escape -quits. Scan frequencies shown in the UI are MHz. The selected settings are -stored in `config.toml` (or `TINY_WB_CONFIG`); scan results default to the current -directory with collision-safe timestamped names. Timing, scan defaults, chart -bounds, CSV output, and logging are configurable. See the commented -[defaults](config/default.toml) and [configuration guide](docs/configuration.md). - -## Current scan flow - -At a high level, `tiny-wb`: - -1. opens the selected serial port; -2. identifies the instrument with `version` and `info`; -3. configures repeat count, raw-value zero offset, input mode, and sweep; -4. requests a binary `scanraw` acquisition; -5. decodes each level sample into dBm and writes `frequency_MHz,level_dBm`; -6. resumes the instrument sweep and plots the acquired points. - -By default, point frequencies reproduce the reviewed firmware's `scanraw` -integer/single-precision calculation. The requested stop frequency is an upper -boundary and is normally not sampled. Existing configurations that explicitly -select `scan.frequency_axis = "inclusive"` retain the older endpoint-inclusive -labels; see [frequency assignment](docs/usb-protocol.md#frequency-assignment). - -Raw `scanraw` levels also have a model-specific encoding bias: 128 dB for -tinySA Basic and 174 dB for tinySA Ultra. This is not record padding; both use -the same `x` plus little-endian `u16` record. Automatic detection selects and -confirms the native offset before acquisition. See -[level conversion and `zero`](docs/usb-protocol.md#level-conversion-and-zero). - -For the exact command sequence and compatibility implications, read -[USB console and `scanraw` protocol](docs/usb-protocol.md) and -[tiny-wb compatibility and operations](docs/tiny-wb-operations.md). - -## Safety - -Do not connect an unknown RF source directly to a tinySA. Use external -attenuation for transmitters and a DC block where a DC component may be -present. The Ultra family has an absolute RF input limit of +6 dBm at 0 dB -internal attenuation; the Basic limit is +10 dBm. These are damage limits, -not recommended measurement levels. See the [safe-operation section](docs/tinysa-field-guide.md#safe-operation-read-before-connecting-a-signal). +- [Compatibility, operation, and troubleshooting](docs/tiny-wb-operations.md) +- [Hardware validation checklist](docs/hardware-validation.md) +- [USB console and `scanraw` protocol](docs/usb-protocol.md) +- [Documentation index](docs/README.md) ## Development -The Jenkins pipeline checks formatting, compilation, tests, documentation, -coverage, Clippy, and a release build. Run the equivalent local checks with: +The core protocol, transport, acquisition, and CSV code can be tested without +a terminal or physical instrument: ```console cargo fmt --all -- --check -cargo audit --deny warnings -cargo deny check -cargo +1.88.0 check --locked --all-targets --all-features -cargo check --locked --all-targets --all-features cargo test --locked --all-targets --all-features -cargo test --locked --doc --all-features -RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps --all-features cargo clippy --locked --all-targets --all-features -- -D warnings ``` -The binary builds on a reusable library for configuration, protocol decoding, -transport, acquisition, and CSV export. UI control flow, state, and rendering -live in `src/ui/`. See [architecture](docs/architecture.md) for the source map -and [AGENTS.md](AGENTS.md) for code, documentation, and commit conventions. +Run the complete local CI sequence in +[Security, dependency policy, and MSRV](docs/security-and-ci.md#local-verification). +See the [architecture guide](docs/architecture.md), +[testing guide](docs/testing.md), and [contributor instructions](AGENTS.md) +before changing behavior. + +## Support + +Report bugs in the [project issue tracker](https://proxy.dandaedre.com/gitea/idle-org/tiny-wb/issues). +Include the details from the +[reproducible bug-report checklist](docs/tiny-wb-operations.md#reproducible-bug-report-checklist). ## License -See [LICENSE](LICENSE). +tiny-wb is available under the [MIT License](LICENSE). diff --git a/docs/README.md b/docs/README.md index 0d67139..c3dc2ee 100644 --- a/docs/README.md +++ b/docs/README.md @@ -50,9 +50,9 @@ grows into many chapters, the files are already organized so that a future - [Configuration](configuration.md): embedded defaults, partial overrides and persistence. - [Testing](testing.md): regression seams and hardware verification boundaries. - [Agent/contributor guidance](../AGENTS.md): code structure, comments, documentation and atomic commits. - - [Releases](releases.md): release wrapper, prerequisites, collision checks and publication policy. - +- [Basic and Ultra support](ultra-support.md): implemented range, model detection and qualification status. - [Feature roadmap](roadmap.md): model-aware Basic/Ultra completion tasks. +- [Implementation task backlog](../task.md): detailed milestones and optional stretch goals. - [Library integration](library.md): feature selection and public interfaces. - [Mock device](mock-device.md): in-memory and TCP simulation. diff --git a/docs/hardware-validation.md b/docs/hardware-validation.md index 75e3dd1..a1a2ea2 100644 --- a/docs/hardware-validation.md +++ b/docs/hardware-validation.md @@ -46,6 +46,15 @@ front-panel sweep resumed. `operator_confirmed=y` (or `yes`). - [ ] Each report entry records `raw_level_offset_db=128`. +### Recorded Basic evidence + +The Basic acquisition path was validated on physical hardware on 2026-10-05 +with firmware `tinySA_v1.4-175-g1419a93`. Both the 240–300 MHz low-input scan +and the 350–400 MHz high-input scan returned 101 valid samples, exercised the +fixed-record binary decoder, produced CSV output, and resumed the live sweep. +This is communications and workflow evidence, not frequency or level-accuracy +calibration. + ## Ultra acceptance and limit - [ ] The automatically selected port belongs to the Ultra. diff --git a/docs/security-and-ci.md b/docs/security-and-ci.md index 16174fe..41d2701 100644 --- a/docs/security-and-ci.md +++ b/docs/security-and-ci.md @@ -225,8 +225,14 @@ and excludes change requests and tags. The actual job configuration is not in this repository and remains unverified. When `BRANCH_NAME` is absent, publication is skipped with a diagnostic; generation and archival still run. Verify the job type and its branch variable before deployment. Real Jenkins -execution, access to the asset mount, and public URL retrieval are separate -unverified deployment checkpoints; README links alone do not make badges live. +execution and access to the asset mount remain external deployment checkpoints. + +The three public URLs were retrieved on 2026-10-05. Each returned HTTP 200 with +`image/svg+xml` content and parsed as XML. Their accessible labels reported +version 0.1.1, tests passing, and 90% coverage; the version matches +`Cargo.toml`. This confirms that the publication endpoint is live, but does not +independently verify the external Jenkins job configuration or the freshness of +its most recent build. Server configuration is external: mount public assets read-only, disable directory listing, serve SVG with a restrictive Content-Security-Policy, and