tiny-wb/README.md

90 lines
3.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# tiny-wb
![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 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.
## Support status
- 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.
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.
## Requirements
- 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
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
From the repository root:
```console
cargo run --release
```
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).
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.
## Configuration and documentation
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.
- [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 core protocol, transport, acquisition, and CSV code can be tested without
a terminal or physical instrument:
```console
cargo fmt --all -- --check
cargo test --locked --all-targets --all-features
cargo clippy --locked --all-targets --all-features -- -D warnings
```
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
tiny-wb is available under the [MIT License](LICENSE).