Compare commits

..

7 Commits
0.1.4 ... main

Author SHA1 Message Date
Dandaedre a20abc677b ci: update coverage tooling for modern Cargo
Rust CI tiny-wb passed CI.
Gitea/tiny-wb/pipeline/head This commit looks good Details
2026-11-21 14:38:53 +01:00
Dandaedre 5ff3f7673f test: cover scan workers and recalibrate coverage floor
Rust CI tiny-wb failed CI.
Gitea/tiny-wb/pipeline/head There was a failure building this commit Details
2026-11-21 13:39:50 +01:00
Dandaedre bc552348d6 fix: replace chrono and update rustix for RustSec
Rust CI tiny-wb failed CI.
Gitea/tiny-wb/pipeline/head There was a failure building this commit Details
2026-11-20 18:22:58 +01:00
Dandaedre 82a495092d docs: add project icon and disclose LLM-assisted development
Rust CI tiny-wb failed CI.
Gitea/tiny-wb/pipeline/head There was a failure building this commit Details
2026-11-20 16:47:47 +01:00
Dandaedre 891b300f86 fix: reconnect once after unusable instrument identification
Rust CI tiny-wb passed CI.
Gitea/tiny-wb/pipeline/head This commit looks good Details
2026-10-20 16:48:10 +02:00
Dandaedre be8f9e1ebf chore: prepare 0.1.5 desktop release
Rust CI tiny-wb passed CI.
Gitea/tiny-wb/pipeline/head This commit looks good Details
2026-10-20 16:39:55 +02:00
Dandaedre 075d0461d7 docs: guide new users through a first scan with screenshots
Rust CI tiny-wb passed CI.
Gitea/tiny-wb/pipeline/head This commit looks good Details
2026-10-20 16:38:08 +02:00
20 changed files with 685 additions and 288 deletions

196
Cargo.lock generated
View File

@ -32,15 +32,6 @@ version = "0.2.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
[[package]]
name = "android_system_properties"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
dependencies = [
"libc",
]
[[package]]
name = "anyhow"
version = "1.0.104"
@ -155,16 +146,6 @@ dependencies = [
"rustversion",
]
[[package]]
name = "cc"
version = "1.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f74872d07caf508b30a21f6836e7d7016a2eaf7d9ff4f48deaa58cd8a0407630"
dependencies = [
"find-msvc-tools",
"shlex",
]
[[package]]
name = "cfg-if"
version = "1.0.5"
@ -177,19 +158,6 @@ version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
[[package]]
name = "chrono"
version = "0.4.45"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
dependencies = [
"iana-time-zone",
"js-sys",
"num-traits",
"wasm-bindgen",
"windows-link",
]
[[package]]
name = "color-eyre"
version = "0.6.5"
@ -468,12 +436,6 @@ dependencies = [
"winapi",
]
[[package]]
name = "find-msvc-tools"
version = "0.1.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
[[package]]
name = "finl_unicode"
version = "1.5.0"
@ -488,11 +450,11 @@ checksum = "0ce7134b9999ecaf8bcd65542e436736ef32ddca1b3e06094cb6ec5755203b80"
[[package]]
name = "flexi_logger"
version = "0.29.8"
version = "0.32.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "88a5a6882b2e137c4f2664562995865084eb5a00611fba30c582ef10354c4ad8"
checksum = "5e87b74024da93123949cca26cb6e366744234fdd4d7914eb3dfeab0baa82d51"
dependencies = [
"chrono",
"jiff",
"log",
"nu-ansi-term",
"regex",
@ -608,30 +570,6 @@ version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
[[package]]
name = "iana-time-zone"
version = "0.1.65"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
dependencies = [
"android_system_properties",
"core-foundation-sys",
"iana-time-zone-haiku",
"js-sys",
"log",
"wasm-bindgen",
"windows-core",
]
[[package]]
name = "iana-time-zone-haiku"
version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
dependencies = [
"cc",
]
[[package]]
name = "ident_case"
version = "1.0.1"
@ -701,6 +639,58 @@ version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "jiff"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed5d126d72eb017f10b302e73bdeca446bea405ee449af4d9e7866d6b082d83e"
dependencies = [
"jiff-core",
"jiff-static",
"jiff-tzdb-platform",
"log",
"portable-atomic",
"portable-atomic-util",
"serde_core",
"windows-link",
]
[[package]]
name = "jiff-core"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6b46a105a9874634dd96231021526bf24ca04955a5998c59a9c7666e634b7b8"
dependencies = [
"log",
]
[[package]]
name = "jiff-static"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c0127e9bde3c6130d6169e7d8d68676e4be69c4bf7573c308b6f960a5089c428"
dependencies = [
"jiff-core",
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "jiff-tzdb"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "12e71a1b68a875a44a33bb7a1dd84392cb77145a3367a552a3cfe6a4f5cf3afc"
[[package]]
name = "jiff-tzdb-platform"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc65b284afcfa8f6cf189c7274c805505314a7ab975c60e1f548bff56525420e"
dependencies = [
"jiff-tzdb",
]
[[package]]
name = "js-sys"
version = "0.3.106"
@ -1167,6 +1157,15 @@ version = "1.15.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
[[package]]
name = "portable-atomic-util"
version = "0.2.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715"
dependencies = [
"portable-atomic",
]
[[package]]
name = "powerfmt"
version = "0.2.0"
@ -1374,9 +1373,9 @@ dependencies = [
[[package]]
name = "rustix"
version = "1.1.5"
version = "1.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "891efababe418670775f199f0d233d84843c227a0949a883ce15b37c78d6629d"
checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa"
dependencies = [
"bitflags 2.13.2",
"errno",
@ -1487,12 +1486,6 @@ dependencies = [
"lazy_static",
]
[[package]]
name = "shlex"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
[[package]]
name = "signal-hook"
version = "0.3.18"
@ -1756,11 +1749,11 @@ checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
[[package]]
name = "tiny-wb"
version = "0.1.4"
version = "0.1.5"
dependencies = [
"chrono",
"color-eyre",
"flexi_logger",
"jiff",
"log",
"ratatui",
"serde",
@ -2121,65 +2114,12 @@ version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
[[package]]
name = "windows-core"
version = "0.62.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
dependencies = [
"windows-implement",
"windows-interface",
"windows-link",
"windows-result",
"windows-strings",
]
[[package]]
name = "windows-implement"
version = "0.60.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "windows-interface"
version = "0.59.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "windows-link"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-result"
version = "0.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
dependencies = [
"windows-link",
]
[[package]]
name = "windows-strings"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
dependencies = [
"windows-link",
]
[[package]]
name = "windows-sys"
version = "0.52.0"

View File

@ -1,8 +1,8 @@
[package]
name = "tiny-wb"
version = "0.1.4"
version = "0.1.5"
edition = "2021"
rust-version = "1.88.0"
rust-version = "1.91.0"
license = "MIT"
repository = "https://proxy.dandaedre.com/gitea/idle-org/tiny-wb"
@ -49,9 +49,9 @@ path = "tests/mock_device.rs"
required-features = ["mock"]
[dependencies]
chrono = "0.4.38"
color-eyre = { version = "0.6.3", optional = true }
flexi_logger = { version = "0.29.0", optional = true }
flexi_logger = { version = "0.32.0", optional = true }
jiff = "1.0.1"
log = "0.4.22"
ratatui = { version = "=0.30.2", optional = true }
serde = { version = "1.0.210", features = ["derive"] }

4
Jenkinsfile vendored
View File

@ -16,12 +16,12 @@ pipeline {
RUST_BACKTRACE = '1'
// LTS-like compatibility floor verified by the dedicated MSRV stage.
MSRV = '1.88.0'
MSRV = '1.91.0'
// Supply-chain tools are pinned for reproducible policy behavior.
CARGO_AUDIT_VERSION = '0.22.2'
CARGO_DENY_VERSION = '0.20.2'
CARGO_LLVM_COV_VERSION = '0.6.16'
CARGO_LLVM_COV_VERSION = '0.9.1'
BADGE_ROOT = '/mnt/assets/coverage'
BADGE_OWNER = 'idle-org'
BADGE_PROJECT = 'tiny-wb'

186
README.md
View File

@ -1,121 +1,125 @@
# tiny-wb
<p align="center">
<img src="docs/images/project-icon.png" width="96" height="96" alt="tiny-wb icon">
</p>
<h1 align="center">tiny-wb</h1>
![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.
Scan a frequency range with your **tinySA**, see the spectrum in your terminal,
and save the measurements as CSV. Start with one scan; no configuration-file
editing is needed.
## Support status
## Open source and development
- tinySA Basic low and high inputs are supported through 960 MHz, subject to
the instrument's path limits.
- tinySA Ultra-family detection and acquisition are implemented for the shared
0.1–800 MHz normal range. A detected Ultra+ ZS406 additionally supports its
0.1–900 MHz normal range and explicit opt-in Ultra mode through 5.4 GHz.
- ZS407 extended mode and harmonic-mode reception remain unsupported. Hardware
validation proves communications and framing, not RF frequency/level accuracy.
tiny-wb is open-source software under the [MIT license](LICENSE). Its
development includes LLM-generated or LLM-assisted work, with human review.
It is used in professional settings; supported workflows and current
limitations are documented in this repository.
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.
## Get running
## Requirements
You need a powered tinySA Basic, Ultra or supported Ultra+, a **data-capable USB
cable**, and access to its serial port. Close other software using the tinySA.
For a first communications check, leave external RF sources disconnected.
Before connecting a signal, read the [safe-operation guide](docs/tinysa-field-guide.md#safe-operation-read-before-connecting-a-signal).
- Rust 1.88.0 or newer
- For acquisition, a powered tinySA Basic, Ultra, or Ultra+ and a data-capable
USB cable
- For acquisition, 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:
To build from source, install Rust **1.91 or newer**, then run:
```console
cargo run --release
git clone https://proxy.dandaedre.com/gitea/idle-org/tiny-wb.git
cd tiny-wb
cargo run --locked --release
```
For Apple Silicon and Intel macOS binaries built from Linux, use the
[release workflow](docs/releases.md): `./release.sh --compile-only` packages
both macOS architectures alongside Linux and Windows. See
[macOS requirements and validation](docs/macos.md).
Already have the checkout? Run just the last command from its root. On Linux,
building also requires the libudev development package and `pkg-config`; this
checkout's linker configuration uses `lld`.
Use `cargo run --release -- --live` to confirm the usual connection and scan
settings, then display repeated complete sweeps until stopped. Number keys select
average/hold/decay traces, `s` saves the visible buffer, and `q`, Escape, or
Enter stops, resumes the instrument, saves once more, and exits.
## Your first scan
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).
1. **Connect by USB and choose the port.** On the connection screen, select your
tinySA's port with the arrow keys. Linux commonly uses `/dev/ttyACM0`; Windows
uses a COM port. On macOS, select the enumerated USB serial device. Leave the
baud rate at **115200** for the first attempt and press **Enter**.
2. **Choose a small range.** Try **Start 280**, **Stop 320** (MHz), **Points 1001**,
and **Repeat 1**. This range uses the Basic's low input and is also within the
supported Ultra normal range. For a connected RF signal, use the appropriate
instrument input and safe signal level.
3. **Enter the values.** **Left/Right** selects a field. Type digits for a
frequency or point count, then press **Enter** to apply that value. Use
**Up/Down** to adjust a value, including Repeat. Once all fields are set,
press **Enter** again to start the scan.
4. **Read the plot.** Wait for the scan to finish. Frequency runs left to right
in **MHz**; level is in **dBm**. A higher point means a stronger signal.
The app automatically saves a `scan_*.csv` in your current directory.
Use Left/Right or `h`/`l` to select a field, Up/Down or `k`/`j` to change it,
or type digits to edit a selected start/stop frequency in MHz or the point count.
Enter applies a typed value (press it again to advance), Backspace removes a
digit, and Escape cancels an active edit. Otherwise Enter advances and `q` or
Escape quits.
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.
![Scan setup with Start 280 MHz, Stop 320 MHz, 1001 points and Repeat 1](docs/images/scan-settings.png)
Open an existing tiny-wb CSV directly in the interactive renderer without
enumerating or connecting to a device:
*Scan settings in the real application. Screenshots use the mock device; no
physical instrument or RF source is needed to reproduce this demonstration.*
![Completed simulated scan with a peak near 300 MHz and the visible-peak readout enabled](docs/images/scan-result.png)
*Example result from simulated data, with **m** pressed to show the peak.
Your real trace will depend on the signals and measurement setup.*
## Explore and save
| Key on the result screen | Action |
| --- | --- |
| `m` | Show or hide the strongest visible sample's frequency and level |
| `+` / `-` | Zoom in / out |
| Left / Right | Pan across the frequency range |
| `0` | Return to the full range |
| `r` | Repeat the same scan and save a new CSV |
| `n` | Edit the settings for a new scan |
| `q` | Quit |
CSV columns are **frequency in MHz, level in dBm**; by default there is no
header. Each successful scan gets a new filename. To reopen a saved scan
without connecting a device, replace `scan.csv` with your file:
```console
cargo run --release -- --view scan.csv
# The shorter `cargo run --release -- scan.csv` is equivalent.
cargo run --locked --release -- --view scan.csv
```
On a plot, use `+`/`=` and `-` to zoom, Left/Right or `h`/`l` to pan, and
`0` or Home to restore the full frequency range. These controls also work during
live capture. Press `m` to toggle a box showing the strongest visible sample's
level and frequency. Plot bindings are configurable
under `[ui.bindings]`. After an acquired scan, `r` immediately repeats the same
scan and `n` returns to the prefilled scan-parameter editor.
Want repeated sweeps? Start with `cargo run --locked --release -- --live`, then
choose the connection and range as above. In live mode, **s** saves the visible
trace and **q** stops after the current sweep and saves it. See
[live controls](docs/tiny-wb-operations.md#live-display) for averaging and hold modes.
## Configuration and documentation
## If something does not work
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.
- **No port, or access denied?** Check the USB cable, close other serial software,
and follow the [serial-permission guide](docs/tiny-wb-operations.md#serial-permissions).
- **Timeout or no instrument detected?** Check the selected port and power, then
consult [troubleshooting](docs/tiny-wb-operations.md#troubleshooting).
- **No tinySA yet?** Follow the [mock-device walkthrough](docs/mock-device.md)
to try the same screens and CSV workflow with simulated data.
- [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)
Settings are saved automatically in `config.toml`. See the
[configuration guide](docs/configuration.md) for output directories, keyboard
bindings and the `TINY_WB_CONFIG` override.
## Development
## Supported instruments and more
The core protocol, transport, acquisition, and CSV code can be tested without
a terminal or physical instrument:
Basic low/high acquisition is supported through 960 MHz, subject to input-path
limits. Ultra-family normal-mode support covers 0.1–800 MHz; detected Ultra+
ZS406 devices also support 0.1–900 MHz and opt-in Ultra mode through 5.4 GHz.
ZS407 extended mode and harmonic reception are not supported. Check the
[compatibility matrix](docs/tiny-wb-operations.md#compatibility-matrix) and
[Ultra support scope](docs/ultra-support.md) before choosing a wider range.
Hardware communications checks do not establish RF accuracy.
```console
cargo fmt --all -- --check
cargo test --locked --all-targets --all-features
cargo clippy --locked --all-targets --all-features -- -D warnings
```
- [Operations and detailed controls](docs/tiny-wb-operations.md)
- [Linux, Windows and macOS release builds](docs/releases.md)
- [Reusable Rust library](docs/library.md)
- [Development and verification](docs/security-and-ci.md#local-verification)
- [Documentation index](docs/README.md) · [Contributor instructions](AGENTS.md)
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.
Report bugs in the [issue tracker](https://proxy.dandaedre.com/gitea/idle-org/tiny-wb/issues)
with the [reproduction details](docs/tiny-wb-operations.md#reproducible-bug-report-checklist).
## 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).
Licensed under the [MIT License](LICENSE).

View File

@ -23,7 +23,7 @@ widgets, port discovery, worker threads, or the application's working directory.
| `src/live.rs` | Bounded rolling average, hold and decay calculations over explicit sweeps. |
| `src/main.rs` | Select single/live/direct-view mode, load configuration, start diagnostics, enumerate ports when needed and manage terminal lifetime. |
| `src/error.rs` | Application/UI boundary errors with original context. |
| `src/scan.rs` | Open the configured connection, adapt core events to shared progress, and export successful acquisitions. |
| `src/scan.rs` | Open the configured connection, reopen once after empty/unknown identity, adapt core events to shared progress, and export successful acquisitions. |
| `src/ui/mod.rs` | Screen transitions, keyboard handling, worker startup and progress reconciliation. |
| `src/ui/state.rs` | UI state, configured port/baud choices and bounded numeric input. |
| `src/ui/view.rs` | Ratatui rendering and selection styling. |
@ -167,7 +167,7 @@ See [configuration](configuration.md) for settings, paths and exact behavior.
The core uses standard-library byte decoding instead of `packed_struct`, and
buffered framing instead of a separate direct `memchr` dependency. Transitive
`memchr` use elsewhere in the graph is unrelated. Serde/TOML handle settings;
serialport, Ratatui, chrono, log/flexi_logger, color-eyre and thiserror retain
serialport, Ratatui, jiff, log/flexi_logger, color-eyre and thiserror retain
their device, presentation, timestamp and error-reporting roles.
Library consumers can omit terminal and serial dependencies; see [feature selection](library.md).

20
docs/images/README.md Normal file
View File

@ -0,0 +1,20 @@
# README screenshots
`scan-settings.png` and `scan-result.png` show the real tiny-wb terminal UI,
captured on 2026-10-20 from a Linux release binary. Input comes from the
[Basic mock device](../mock-device.md), not a physical instrument. The screenshot
binary identifies itself as `0.1.4-8ed07cb`; later release/documentation changes
did not change this UI.
To reproduce the screens, follow the mock-device walkthrough using a temporary
copy of the client settings. Set start to 280 MHz, stop to 320 MHz, points to
1001 and repeat to 1. Capture the scan-settings screen after confirming the
connection; start the scan and press `m` on the completed plot to show its peak.
The mock's peak is near 300 MHz. The displayed CSV filename varies with time.
These PNGs were rendered from the application's captured pseudo-terminal output
using pyte 0.8.2 and Pillow 13.0.0, with DejaVu Sans Mono and a dark terminal
palette. The setup screen is 132 columns by 13 rows; the result is 132 by 26.
Colors were enabled (`NO_COLOR` unset). No UI labels or trace values were drawn
by hand. The mock run completed acquisition and exported one CSV in a temporary
directory. Screenshot tooling is not an application or build dependency.

View File

@ -0,0 +1,5 @@
# Project icon provenance
`project-icon.png` is the existing tiny-wb repository avatar, retrieved from the
maintainer's Gitea repository on 2026-11-20 and reused unchanged for the project
README and Idle organisation profile. No new logo or license is introduced.

Binary file not shown.

After

Width:  |  Height:  |  Size: 180 KiB

BIN
docs/images/scan-result.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB

View File

@ -1,7 +1,7 @@
# Rust library integration
The package builds both `tiny_wb` (Rust library) and `tiny-wb` (terminal app).
Rust 1.88 or newer is required. To integrate a checkout without terminal, serial,
Rust 1.91 or newer is required. To integrate a checkout without terminal, serial,
libudev or Windows resource dependencies:
```toml

View File

@ -0,0 +1,35 @@
# tiny-wb 0.1.5
This release adds Apple Silicon and Intel macOS downloads alongside Linux and
Windows. The README now walks new users through a first scan, with screenshots
of the real application using clearly labelled simulated data.
## Downloads
Choose the archive for your computer, extract it, and run `tiny-wb` (or
`tiny-wb.exe` on Windows) from a terminal:
| Platform | Target |
| --- | --- |
| Linux x86-64 (glibc, system libudev required) | `x86_64-unknown-linux-gnu` |
| Windows x86-64 | `x86_64-pc-windows-gnu` |
| macOS Apple Silicon | `aarch64-apple-darwin` |
| macOS Intel | `x86_64-apple-darwin` |
Each target has a `.tgz` archive and a standalone executable. `SHA256SUMS`
covers all eight payload files.
macOS requires version 13.0 or newer. These are separate, unsigned and
unnotarized command-line executables, not universal binaries or `.app` bundles.
The release pipeline checks Mach-O architecture, deployment minimum, system
library paths, archive layout and checksums. Native macOS execution and USB
hardware behavior remain unverified by this Linux release workflow.
## Release workflow
All four targets now use `release.sh` and `rust_realease`. Apple builds use the
pinned cargo-zigbuild image; Linux and Windows use Cross. The obsolete standalone
macOS build script and its tests have been removed.
See the [README](https://proxy.dandaedre.com/gitea/idle-org/tiny-wb/src/tag/0.1.5/README.md)
for setup, your first scan, result controls and CSV export.

View File

@ -7,7 +7,7 @@ runs `cargo-audit` plus `cargo-deny`. No other hardening tools are in scope.
## Rust compatibility floor
The declared and CI-tested minimum supported Rust version (MSRV) is
**Rust 1.88.0**. This is an LTS-like project policy rather than an upstream Rust
**Rust 1.91.0**. This is an LTS-like project policy rather than an upstream Rust
LTS designation: Rust itself does not publish LTS toolchains.
The application code and the former Ratatui 0.28 dependency could be made to
@ -15,14 +15,23 @@ compile with older compilers, but that graph contained the unmaintained `paste`
crate and `lru` releases covered by RustSec soundness advisories. Ratatui 0.30.0
still locked an affected optional `lru` and a vulnerable `time`. Ratatui 0.30.2
is the first tested upstream line that clears those findings, and it declares
Rust 1.88.0. The project therefore treats 1.88.0 as the lowest supported clean
graph rather than adding advisory exceptions or local dependency patches.
Rust 1.88.0. That established the previous compatibility floor.
`Cargo.toml` declares `rust-version = "1.88.0"`. CI installs that exact
On 2026-11-20, [RUSTSEC-2026-0543](https://rustsec.org/advisories/RUSTSEC-2026-0543)
required removing chrono (all versions are unmaintained). CSV export and the
hardware-validation example now use jiff, preserving local-time filenames and
six fractional digits. flexi_logger 0.32 removes its transitive chrono dependency
and requires Rust 1.91.0, which is the new build and CI floor. Existing logging
settings remain compatible; source builders must upgrade their Rust toolchain.
The locked rustix is also updated to at least 1.1.6 for
[RUSTSEC-2026-0486](https://rustsec.org/advisories/RUSTSEC-2026-0486).
Neither advisory is ignored.
`Cargo.toml` declares `rust-version = "1.91.0"`. CI installs that exact
toolchain and runs:
```console
cargo +1.88.0 check --locked --all-targets --all-features
cargo +1.91.0 check --locked --all-targets --all-features
```
The normal CI jobs use current stable Rust, while the MSRV job prevents source
@ -118,7 +127,7 @@ Run from the repository root, in this order:
cargo audit --deny warnings
cargo deny check
cargo fmt --all -- --check
cargo +1.88.0 check --locked --all-targets --all-features
cargo +1.91.0 check --locked --all-targets --all-features
cargo check --locked --all-targets --all-features
cargo test --locked --all-targets --all-features
cargo test --locked --no-default-features --lib
@ -153,12 +162,12 @@ Repository identity and `main` were verified against the origin remote, its
HEAD, and Gitea repository metadata. The version comes from `Cargo.toml` via
`cargo metadata --no-deps --locked --format-version 1`, never a Jenkins constant.
Coverage uses pinned `cargo-llvm-cov` 0.6.16 and Rust's `llvm-tools-preview`
Coverage uses pinned `cargo-llvm-cov` 0.9.1 and Rust's `llvm-tools-preview`
component. The worker also needs `jq`. Install the prerequisites and run:
```console
rustup component add llvm-tools-preview
cargo install --locked --version 0.6.16 cargo-llvm-cov
cargo install --locked --version 0.9.1 cargo-llvm-cov
mkdir -p coverage
cargo coverage
```
@ -170,12 +179,17 @@ cargo llvm-cov --locked --all-targets --all-features --ignore-filename-regex /re
```
The enforced line-coverage floor is **85%**, measured across the library and
application without excluding production sources. Local measurement on 2026-10-04 was **1,852 of 2,038 lines (90.87%)**.
application without excluding production sources. Local measurement on 2026-11-21
with the pinned tool was **3,731 of 4,078 lines (91.49%)** after adding loopback
worker tests for complete single-scan export and live capture, deferred save,
and graceful shutdown.
The suite includes library, application, mock/loopback integration and startup
tests, plus separately run Rustdoc examples. Tests
cover configuration, protocol, transport, acquisition, export, UI, startup and
mock device behavior. The floor leaves some headroom for
platform differences; it is not evidence of device/firmware correctness.
mock device behavior. The floor leaves headroom for platform differences; it is
not evidence of device/firmware correctness. Version 0.9.1 excludes in-source
test bodies from the report while retaining every production module, so adding
tests does not increase the acceptance denominator.
`scripts/collect-coverage.sh` runs that command, validates the overall line
percentage from temporary `coverage/summary.json`, renders the coverage badge,
@ -184,7 +198,7 @@ build's test and coverage markers only after unit/integration tests, Rustdoc tes
The release smoke test remains a nonfatal diagnostic.
The collector removes any stale summary before running Cargo and displays only
`Final line coverage: 90.87%` on success. Compiler and test output is saved to
`Final line coverage: 91.49%` on success. Compiler and test output is saved to
ignored `coverage/coverage.log` in the workspace; failures print a short error
pointing to that log and preserve Cargo's exit status. Missing or invalid
summaries fail explicitly. No per-file coverage listing is printed, and failed
@ -197,14 +211,24 @@ Dependency sources under `/root/.cargo/registry/src/` escaped the pinned tool's
default Cargo-home-based filter. The log does not establish why that default
filter missed these paths. The alias explicitly filters
`/registry/src/` paths so dependency caches are excluded regardless of their
home directory. All tiny-wb production sources and the **85%** floor remain
unchanged. This corrects report scope, not test coverage. The subsequent supplied
home directory. At that time, all tiny-wb production sources and the **85%** floor
remained unchanged. This corrected report scope, not test coverage. The subsequent supplied
FreeBSD Jenkins build #7 confirmed `Final line coverage: 90.87%` and passed the
coverage stage. That build then stopped at Clippy's `chunks_exact_to_as_chunks`
lint; the decoder now iterates fixed-size records with `as_chunks::<3>()`,
compatible with the declared Rust 1.88 MSRV. Its exact frame-length validation
compatible with the then-declared Rust 1.88 MSRV. Its exact frame-length validation
still rejects incomplete records before iteration.
FreeBSD Jenkins build #29 used Rust 1.100/LLVM 23 but downgraded the worker's
0.9.1 installation to the obsolete 0.6.16 pin. Although every test passed, that
tool reported 29.01%. The retained log does not include per-file totals, so it
cannot establish the exact files added to the report. Upstream
[0.9.0](https://github.com/taiki-e/cargo-llvm-cov/releases/tag/v0.9.0) fixed
build-script files appearing under Cargo's newer build-directory layout, and
the same CI environment and flags were reproduced locally with 0.9.1 at 91.49%.
This is a tooling correction, not an exclusion of production code or a
reduction of the coverage floor.
At checkout, CI recreates ignored `coverage/` to remove stale workspace state.
In `post { cleanup { ... } }`, it uses only current-build markers to choose test
status and retain measured coverage, falling back to `failing` and neutral `-%`

View File

@ -16,6 +16,7 @@ cargo test --locked --doc
| Protocol | Basic mode boundaries, point/repeat validation, truncated/extra records, alignment, closing brace, binary delimiter bytes, little-endian levels, Basic/Ultra raw offsets, both frequency-axis conventions, and firmware integer/single-precision frequency rounding. |
| Transport | One-byte/fragmented reads, multiple responses in one read, retained bytes after prompts, partial writes, invalid command lines, EOF, timeout, response size limits and raw-body framing. |
| Acquisition | Exact command ordering, one retry after an unusable identity reply, repeated complete live snapshots, optional legacy pre-scan, progress completion, successful decoding, resume after malformed frames, and preservation of acquisition plus recovery errors. |
| Connection worker | Healthy single/live scans open once; empty/unknown identity closes the first port and drops buffered bytes before reopening; fresh-session acquisition succeeds; repeated identity failure stops after one reconnect; conflicting identities, transport/configuration/frame errors and open failures are not replayed. |
| Live processing | Four/sixteen-sweep rolling windows, bounded history, min/max hold, one-dB decay, incompatible axes, non-finite input and mode-key mapping. |
| UI/startup | `--live` parsing, missing/stale ports, numeric overflow and clamping, typed frequency/point commit/cancel/bounds, configured baud rates, completed/live sample-resolution zoom, adaptive axis precision, pan/reset and clamping, viewport-aware peak selection and overlay, new-scan navigation, view-only CSV behavior, direct CSV startup failures, one-time result transfer, every screen on small/headless terminals, and invalid config before terminal startup. |
| Export | Header/units, header and headerless parsing, malformed/unordered input, deterministic CSV values, propagated write failures and collision-safe output files. |

View File

@ -124,9 +124,25 @@ the editor, Enter advances to the next screen and `q` or Escape exits.
Instrument identification sends the read-only `version` and `info` queries. If
the first complete pair is empty or cannot identify a supported family, tiny-wb
repeats that pair once before reporting the identification error. Transport
timeouts and incomplete prompts are not replayed on a potentially unsynchronized
stream.
repeats that pair once on the same connection. If both exchanges are empty or
unrecognized, the terminal application's single-scan and live workers close the
connection, discard their buffered replies, reopen once, and repeat identification
automatically. The UI briefly reports `Reconnecting after failed identification`.
A successful retry proceeds with the original settings; a second failed connection
reports its error. This recovery occurs before scan settings are changed or CSV
output is created.
Conflicting model identities, connection-opening failures, transport timeouts,
incomplete prompts, and failures during configuration/acquisition do not trigger
a reconnect. This avoids replaying a scan after a possible device mutation.
Library callers of `acquire`/`acquire_live` retain ownership of their connection
and only get the existing same-connection identity retry.
The reconnect addresses a user-reported Linux first-open failure where a manual
retry works. Stale serial input is a possible cause, not a verified diagnosis;
there is no new operating-system buffer purge or firmware-specific workaround.
Regression transcripts cover this recovery, but the intermittent first-open
hardware failure has not been reproduced locally.
Large point and repeat values can produce extremely long scans. Total time also
depends on RBW and instrument mode; the progress bar is based mainly on bytes
@ -257,6 +273,13 @@ power-cycle/reload a preset after making the RF setup safe.
- Unplug/reconnect if the device was just in DFU mode; DFU and CDC serial are
different USB personalities.
### Unsupported device identity on first connection
The application automatically reopens once after repeated empty or unknown
identity replies; see [identification recovery](#scan-screen). If it still
fails, confirm the port and instrument model. Do not assume that every unknown
device is a tinySA. Include the final error and firmware details in a bug report.
### “No version found” or a timeout
- Verify the selected port is the tinySA, not another CDC device.

View File

@ -226,7 +226,7 @@ fn run() -> Result<(), Box<dyn Error>> {
let session = arguments.output.join(format!(
"{}-{}",
arguments.model.name().to_ascii_lowercase(),
chrono::Local::now().format("%Y%m%d-%H%M%S-%6f")
jiff::ZonedDateTime::now().strftime("%Y%m%d-%H%M%S-%6f")
));
fs::create_dir_all(&session)?;

View File

@ -9,7 +9,7 @@ trap 'exit 1' HUP INT TERM
rm -f "$summary"
coverage_status=0
cargo coverage >"$log" 2>&1 || coverage_status=$?
# cargo-llvm-cov 0.6.16 can fail the floor silently after writing its report.
# Preserve the explicit status check even when Cargo writes a valid report.
# Print the measurement before cleanup, but never mask a failed Cargo run.
if [ ! -s "$summary" ]; then
echo "ERROR: cargo coverage produced no summary (exit $coverage_status); see coverage/coverage.log." >&2

View File

@ -172,7 +172,7 @@ exit "$FAKE_COVERAGE_STATUS"
''')
cargo.chmod(0o755)
os.environ['PATH'] = str(tools) + ':' + old_path
for percentage, status in ((90.87, 0), (85, 0), (84.99, 1), (90.87, 7)):
for percentage, status in ((91.49, 0), (85, 0), (84.99, 1), (91.49, 7)):
os.environ['FAKE_COVERAGE_REPORT'] = json.dumps({'data': [{
'totals': {'lines': {'percent': percentage}},
'files': [{'filename': 'src/example.rs', 'summary': {
@ -233,6 +233,7 @@ readme = (REPO/'README.md').read_text()
for name in ('version', 'test', 'coverage'):
assert readme.count(f'https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/{name}.svg') == 1
pipeline = (REPO/'Jenkinsfile').read_text()
assert "CARGO_LLVM_COV_VERSION = '0.9.1'" in pipeline
assert "artifacts: 'coverage/version.svg,coverage/test.svg,coverage/coverage.svg'" in pipeline
assert 'fingerprint: true, allowEmptyArchive: false' in pipeline
print('Badge rendering, XML, validation, coverage diagnostics, publication, README and archive checks passed.')

View File

@ -1,7 +1,7 @@
//! CSV serialization and collision-safe file creation, separate from decoding.
use crate::{config::OutputConfig, protocol::Sample};
use chrono::Local;
use jiff::ZonedDateTime;
use std::{
fs::{self, OpenOptions},
io::{self, BufRead, BufWriter, Write},
@ -108,7 +108,7 @@ pub fn write_csv(
/// Readers may see the in-progress file, so only the returned path means complete.
pub fn save_csv(samples: &[Sample], settings: &OutputConfig) -> io::Result<PathBuf> {
fs::create_dir_all(&settings.directory)?;
let stamp = Local::now().format("%Y%m%d %H_%M_%S_%6f").to_string();
let stamp = filename_stamp(&ZonedDateTime::now());
for suffix in 0..100 {
let path = settings
.directory
@ -135,10 +135,33 @@ pub fn save_csv(samples: &[Sample], settings: &OutputConfig) -> io::Result<PathB
))
}
/// Preserve the local calendar fields and six fractional digits in export names.
fn filename_stamp(now: &ZonedDateTime) -> String {
now.strftime("%Y%m%d %H_%M_%S_%6f").to_string()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn filename_timestamp_preserves_local_time_and_microseconds() {
for (input, expected) in [
(
"2024-02-29T23:59:58.123456789+05:30[+05:30]",
"20240229 23_59_58_123456",
),
(
"2026-01-01T00:00:00.000001-04:00[-04:00]",
"20260101 00_00_00_000001",
),
("2026-01-01T00:00:00Z[UTC]", "20260101 00_00_00_000000"),
] {
let now: ZonedDateTime = input.parse().unwrap();
assert_eq!(filename_stamp(&now), expected);
}
}
#[test]
fn csv_has_explicit_units_only_when_requested() {
let samples = [Sample {

View File

@ -1,17 +1,20 @@
//! Serial worker adapter and shared progress state for the terminal application.
//!
//! The worker opens the device and exports completed samples. Protocol parsing
//! The worker opens the device, retries an unusable identity on one fresh
//! connection, and exports completed samples. Protocol parsing
//! and orchestration stay in the library; no core type knows about UI widgets.
use crate::error::{AppError, UiError};
use std::{
io::{Read, Write},
path::PathBuf,
sync::{Arc, Mutex, MutexGuard},
};
use tiny_wb::{
acquisition::{acquire, acquire_live, ScanEvent},
acquisition::{acquire, acquire_live, AcquisitionError, ScanEvent},
config::Config,
connection::open_connection,
connection::{open_connection, ConnectionError},
device::DeviceError,
export::save_csv,
live::{TraceBuffer, TraceMode},
protocol::Sample,
@ -348,7 +351,36 @@ impl LiveState {
}
}
/// Open one port, acquire through the reusable core, then export valid samples.
/// Reopen once when complete identity replies remain empty or unrecognized.
///
/// Dropping the entire shell before opening again releases the port and its
/// buffered replies. These errors occur before any acquisition settings change;
/// transport errors and failures after configuration must never replay a scan.
fn with_identity_reconnect<T: Read + Write, R>(
max_response_bytes: usize,
mut open: impl FnMut() -> Result<T, ConnectionError>,
mut operation: impl FnMut(&mut Shell<T>) -> Result<R, AcquisitionError>,
mut on_retry: impl FnMut(),
) -> Result<R, AppError> {
let first = {
let mut shell = Shell::new(open()?, max_response_bytes);
operation(&mut shell)
};
match first {
Err(
error @ (AcquisitionError::MissingIdentity
| AcquisitionError::Device(DeviceError::Unknown)),
) => {
log::warn!("instrument identification failed; reopening connection once: {error}");
on_retry();
let mut shell = Shell::new(open()?, max_response_bytes);
Ok(operation(&mut shell)?)
}
result => Ok(result?),
}
}
/// Acquire with one identity-only reconnect, then export valid samples.
pub(crate) fn run_scan(
state: ScanState,
request: ScanRequest,
@ -359,14 +391,19 @@ pub(crate) fn run_scan(
request
.validate()
.map_err(tiny_wb::acquisition::AcquisitionError::from)?;
let port = open_connection(&config)?;
let mut shell = Shell::new(port, config.serial.max_response_bytes);
let samples = acquire(
&mut shell,
&request,
&config.scan,
&config.serial,
|event| state.report(event),
let samples = with_identity_reconnect(
config.serial.max_response_bytes,
|| open_connection(&config),
|shell| {
acquire(shell, &request, &config.scan, &config.serial, |event| {
state.report(event)
})
},
|| {
state.report(ScanEvent::Message(
"Reconnecting after failed identification",
))
},
)?;
state.report(ScanEvent::Message("Writing CSV"));
let filename = save_csv(&samples, &config.output)?;
@ -393,33 +430,40 @@ pub(crate) fn run_live(
request
.validate()
.map_err(tiny_wb::acquisition::AcquisitionError::from)?;
let port = open_connection(&config)?;
let mut shell = Shell::new(port, config.serial.max_response_bytes);
let callback_state = state.clone();
let output = config.output.clone();
acquire_live(
&mut shell,
&request,
&config.scan,
&config.serial,
|| state.should_stop(),
move |samples| {
if let Err(error) = callback_state.publish(samples) {
callback_state.fail(error);
callback_state.request_stop();
return;
}
if let Some(samples) = callback_state.take_save_request() {
match save_csv(&samples, &output) {
Ok(path) => callback_state.saved(&path),
Err(error) => {
callback_state.fail(error);
callback_state.request_stop();
with_identity_reconnect(
config.serial.max_response_bytes,
|| open_connection(&config),
|shell| {
acquire_live(
shell,
&request,
&config.scan,
&config.serial,
|| state.should_stop(),
|samples| {
if let Err(error) = state.publish(samples) {
state.fail(error);
state.request_stop();
return;
}
}
}
if let Some(samples) = state.take_save_request() {
match save_csv(&samples, &config.output) {
Ok(path) => state.saved(&path),
Err(error) => {
state.fail(error);
state.request_stop();
}
}
}
},
|event| state.report(event),
)
},
|| {
state.report(ScanEvent::Message(
"Reconnecting after failed identification",
))
},
|event| state.report(event),
)?;
if let Some(error) = state.error() {
return Err(AppError::Live(error));
@ -436,6 +480,200 @@ pub(crate) fn run_live(
mod tests {
use super::*;
use std::{
cell::{Cell, RefCell},
io::{self, Cursor},
net::TcpListener,
rc::Rc,
thread,
time::{Duration, Instant},
};
use tiny_wb::{
config::Backend,
mock::{serve_connection, MockConfig},
};
struct IdentitySession {
input: Cursor<Vec<u8>>,
commands: Rc<RefCell<Vec<u8>>>,
closed: Rc<Cell<bool>>,
}
impl Read for IdentitySession {
fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
self.input.read(buffer)
}
}
impl Write for IdentitySession {
fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
self.commands.borrow_mut().extend_from_slice(bytes);
Ok(bytes.len())
}
fn flush(&mut self) -> io::Result<()> {
Ok(())
}
}
impl Drop for IdentitySession {
fn drop(&mut self) {
self.closed.set(true);
}
}
#[test]
fn single_and_live_scans_reconnect_only_after_unusable_identity() {
for live in [false, true] {
// None also checks that a healthy first connection is never replayed.
for failed_reply in [None, Some(""), Some("stale startup text")] {
let config = Config::from_toml(
"[scan]\nlegacy_pre_scan=false\n[serial]\ncommand_delay_ms=0\nsettle_delay_ms=0",
).unwrap();
let request = ScanRequest {
start_hz: 280_000_000,
stop_hz: 320_000_000,
points: 2,
repeat: 1,
};
let closed = Rc::new(Cell::new(true));
let commands = [
Rc::new(RefCell::new(Vec::new())),
Rc::new(RefCell::new(Vec::new())),
];
let mut opened = 0;
let mut retries = 0;
let mut open = || {
assert!(
closed.replace(false),
"old port must close before reopening"
);
let input = if let Some(reply) = failed_reply.filter(|_| opened == 0) {
// Extra bytes are prefetched into the first shell's buffer.
// They must not leak into the fresh identity exchange.
format!("ch>{reply}ch>{reply}ch>{reply}ch>{reply}ch>leftover stale bytes")
.into_bytes()
} else {
b"ch>tinySA_v1.4-test\r\nch>tinySA\r\nch>repeat zero pause mode sweep scanraw resume\r\nch>ch>ch>128dBm\r\nch>ch>ch>ch>ch>ch>{x\0\x08x\0\x10}ch>ch>".to_vec()
};
let session = IdentitySession {
input: Cursor::new(input),
commands: commands[opened].clone(),
closed: closed.clone(),
};
opened += 1;
Ok(session)
};
let sweeps = Cell::new(0);
let result = with_identity_reconnect(
1024,
&mut open,
|shell| {
if live {
acquire_live(
shell,
&request,
&config.scan,
&config.serial,
|| sweeps.get() == 1,
|samples| {
assert_eq!(samples.len(), 2);
sweeps.set(sweeps.get() + 1);
},
|_| {},
)
.map(|_| ())
} else {
acquire(shell, &request, &config.scan, &config.serial, |_| {})
.map(|samples| assert_eq!(samples.len(), 2))
}
},
|| retries += 1,
);
assert!(result.is_ok(), "{result:?}");
assert_eq!(opened, 1 + usize::from(failed_reply.is_some()));
assert_eq!(retries, usize::from(failed_reply.is_some()));
assert!(closed.get());
if failed_reply.is_some() {
assert_eq!(&*commands[0].borrow(), b"version\rinfo\rversion\rinfo\r");
}
let successful = String::from_utf8(commands[opened - 1].borrow().clone()).unwrap();
assert_eq!(successful.matches("scanraw ").count(), 1);
assert!(successful.ends_with("resume\r"));
}
}
}
#[test]
fn reconnect_is_bounded_and_other_acquisition_errors_are_not_retried() {
for (error, expected_opens) in [
(AcquisitionError::MissingIdentity, 2),
(AcquisitionError::Device(DeviceError::Unknown), 2),
(AcquisitionError::Device(DeviceError::Conflicting), 1),
(
AcquisitionError::Device(DeviceError::ConflictingRevision),
1,
),
(
AcquisitionError::Transport(io::Error::from(io::ErrorKind::TimedOut).into()),
1,
),
(AcquisitionError::MissingZeroReadback { requested: 128 }, 1),
(
AcquisitionError::Protocol(tiny_wb::protocol::ProtocolError::MissingEnd),
1,
),
] {
let mut opened = 0;
let mut error = Some(error);
let result = with_identity_reconnect(
256,
|| {
opened += 1;
Ok(Cursor::new(Vec::<u8>::new()))
},
|_| {
Err::<(), _>(
error
.take()
.unwrap_or(AcquisitionError::Device(DeviceError::Unknown)),
)
},
|| {},
);
assert!(matches!(result, Err(AppError::Acquisition(_))));
assert_eq!(opened, expected_opens);
}
}
#[test]
fn connection_open_errors_are_propagated_without_another_attempt() {
for fail_on in [1, 2] {
let mut opened = 0;
let mut operations = 0;
let result = with_identity_reconnect(
256,
|| {
opened += 1;
if opened == fail_on {
Err(ConnectionError::Tcp(io::ErrorKind::PermissionDenied.into()))
} else {
Ok(Cursor::new(Vec::<u8>::new()))
}
},
|_| {
operations += 1;
Err::<(), _>(AcquisitionError::MissingIdentity)
},
|| {},
);
assert!(matches!(result, Err(AppError::Connection(_))));
assert_eq!(opened, fail_on);
assert_eq!(operations, fail_on - 1);
}
}
#[test]
fn shared_progress_and_errors_are_visible_across_clones() {
let state = ScanState::default();
@ -504,4 +742,87 @@ mod tests {
state.request_stop();
assert!(state.should_stop());
}
fn mock_tcp_config(output_name: &str) -> (Config, thread::JoinHandle<()>) {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let mut config = Config::default();
config.connection.backend = Backend::Tcp;
config.connection.tcp_address = listener.local_addr().unwrap().to_string();
config.serial.command_delay_ms = 0;
config.serial.settle_delay_ms = 0;
config.serial.scan_delay_ms = 0;
config.scan.legacy_pre_scan = false;
config.output.directory =
std::env::temp_dir().join(format!("tiny-wb-{output_name}-{}", std::process::id()));
let server = thread::spawn(move || {
let (socket, _) = listener.accept().unwrap();
socket
.set_read_timeout(Some(Duration::from_secs(5)))
.unwrap();
socket
.set_write_timeout(Some(Duration::from_secs(5)))
.unwrap();
serve_connection(socket, MockConfig::default()).unwrap();
});
(config, server)
}
fn mock_request() -> ScanRequest {
ScanRequest {
start_hz: 240_000_000,
stop_hz: 360_000_000,
points: 4,
repeat: 1,
}
}
#[test]
fn scan_worker_acquires_exports_and_publishes_completion() {
let (config, server) = mock_tcp_config("scan-worker");
let output = config.output.directory.clone();
let state = ScanState::default();
run_scan(state.clone(), mock_request(), config).unwrap();
assert_eq!(state.status(), ScanStatus::Complete);
assert_eq!(state.progress(), 100);
assert_eq!(state.take_samples().unwrap().len(), 4);
assert!(state.message().starts_with("Saved "));
server.join().unwrap();
std::fs::remove_dir_all(output).unwrap();
}
#[test]
fn live_worker_honors_deferred_save_and_graceful_stop() {
let (config, server) = mock_tcp_config("live-worker");
let output = config.output.directory.clone();
let state = LiveState::default();
state.begin();
state.report(ScanEvent::InstrumentInfo("mock identity".into()));
assert_eq!(state.info(), "mock identity");
state.request_save();
let controller = state.clone();
let stop = thread::spawn(move || {
let deadline = Instant::now() + Duration::from_secs(5);
while controller.snapshot_after(0).is_none() {
assert!(
Instant::now() < deadline,
"live worker produced no snapshot"
);
thread::yield_now();
}
controller.request_stop();
});
run_live(state.clone(), mock_request(), config).unwrap();
stop.join().unwrap();
server.join().unwrap();
assert_eq!(state.status(), ScanStatus::Complete);
assert!(state.error().is_none());
assert!(state.message().contains("stopped live capture"));
assert!(std::fs::read_dir(&output).unwrap().count() >= 2);
std::fs::remove_dir_all(output).unwrap();
}
}