docs: streamline project readme

This commit is contained in:
Dandaedre 2026-10-05 10:04:24 +02:00
parent 7558a24374
commit 1bc67400f6
4 changed files with 74 additions and 134 deletions

185
README.md
View File

@ -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).

View File

@ -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.

View File

@ -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.

View File

@ -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