docs: streamline project readme
This commit is contained in:
parent
7558a24374
commit
1bc67400f6
185
README.md
185
README.md
|
|
@ -1,164 +1,89 @@
|
|||
# tiny-wb
|
||||
|
||||

|
||||

|
||||

|
||||

|
||||

|
||||

|
||||
|
||||
`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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue