125 lines
5.9 KiB
Markdown
125 lines
5.9 KiB
Markdown
# Mock tinySA device
|
||
|
||
The optional `mock` feature provides a deterministic in-memory duplex stream
|
||
and a TCP server backed by the same device model. Standard `Read + Write`
|
||
keeps this portable without pseudo-terminal pairs, virtual COM drivers or
|
||
privileged serial setup. TCP is a mock/bridge transport, not a native tinySA
|
||
network feature. Simulated success is not hardware validation.
|
||
|
||
## Run the server and application
|
||
|
||
From the checkout, start the server:
|
||
|
||
```console
|
||
cargo run --locked --no-default-features --features mock --example mock-tinysa-server -- --config config/mock-basic.toml
|
||
```
|
||
|
||
In a second terminal, copy the client template to a writable settings file
|
||
outside the checkout, then point `TINY_WB_CONFIG` at that copy:
|
||
|
||
```sh
|
||
cp config/mock-client.toml /tmp/tiny-wb-mock-client.toml
|
||
TINY_WB_CONFIG=/tmp/tiny-wb-mock-client.toml cargo run --locked --bin tiny-wb
|
||
```
|
||
|
||
On Windows, copy the template to a chosen temporary file and set
|
||
`$env:TINY_WB_CONFIG` in PowerShell before running Cargo. The app saves settings
|
||
to this path; do not use the tracked template as the runtime file. The connection
|
||
screen offers `tcp://127.0.0.1:7355` without enumerating USB devices. Serial port
|
||
and baud selections have no effect on a TCP connection. Successful scans still
|
||
write CSV to the configured export directory.
|
||
|
||
Options: `--bind IP:port` (default `127.0.0.1:7355`), `--config FILE`, `--once`,
|
||
`--help`. Port zero asks the OS for a free port; the actual endpoint is printed.
|
||
Each accepted connection gets fresh state. The example serves one client at a
|
||
time; disconnected/error sessions allow the next client. `--once` exits after
|
||
one session, returning failure for session I/O errors. The library's
|
||
`serve_connection` lets integrations supply their own listener and concurrency.
|
||
Keep this unauthenticated test service on loopback.
|
||
|
||
## In-memory integration
|
||
|
||
Enable `mock` alongside `default-features = false` in the dependency entry:
|
||
|
||
```rust
|
||
use tiny_wb::{mock::{MockConfig, MockStream}, transport::Shell};
|
||
use std::time::Duration;
|
||
let mut device = MockStream::new(MockConfig::default()).unwrap();
|
||
{
|
||
let mut shell = Shell::new(&mut device, 65_536);
|
||
shell.synchronize().unwrap();
|
||
shell.command_checked("pause", Duration::ZERO, Duration::ZERO).unwrap();
|
||
}
|
||
assert!(device.state().paused);
|
||
```
|
||
|
||
`tests/mock_device.rs` runs production acquisition with one-byte reads/writes,
|
||
both echo modes, legacy preparation enabled/disabled, recovery faults, and a
|
||
real loopback TCP connection. Run without terminal or native serial dependencies:
|
||
|
||
```console
|
||
cargo test --locked --no-default-features --features mock --lib --test mock_device
|
||
```
|
||
|
||
## Supported synthetic behavior
|
||
|
||
| Commands | Behavior |
|
||
| --- | --- |
|
||
| `version`, `info`, `help` | Explicitly synthetic identity and implemented subset |
|
||
| `pause`, `resume` | Observable sweep state |
|
||
| `mode low/high input` | Basic input paths; Basic low stop below 350 MHz, high start at least 240 MHz |
|
||
| `mode input`, `mode low input` | Ultra mock input syntax; high mode rejected |
|
||
| `repeat N`, `zero N` | Stored count and fixed-point offset |
|
||
| `sweep start/stop Hz`, `sweep` | Stored bounds and query |
|
||
| `scanraw start stop points` | Bounded deterministic binary spectrum |
|
||
| `scan start stop 290 101` | Current app's compatibility preparation only; no trace data |
|
||
| `leveloffset`, `vbat`, `usart_cfg`, `threads`, `marker` | Fixed diagnostic fixtures, not measurement implementations |
|
||
| `lna on/off`, `ultra on/off` | Ultra-only state toggles with no RF effect |
|
||
|
||
Other commands or invalid arguments return an explicit error. No calibration,
|
||
RF output, display capture, arbitrary firmware behavior or complete console
|
||
emulation is claimed. The Ultra profile exercises automatic detection, native
|
||
offset readback and low-input acquisition. Production Ultra scans are limited
|
||
to 0.1–800 MHz; the mock's larger synthetic range is not a production capability.
|
||
See [support scope](ultra-support.md).
|
||
|
||
Samples use the reviewed firmware's integer-divided, single-precision
|
||
`scanraw` point frequencies, a triangular peak above a configured floor, and
|
||
`round((dBm + zero_offset) * 32)` clamped to `u16`.
|
||
Frames contain `{`, repeated `x` plus little-endian `u16`, then `}` and a prompt.
|
||
Use the firmware frequency-axis setting for matching labels. There is no noise,
|
||
RF physics, timing model or amplitude change from LNA/repeat/Ultra toggles.
|
||
The mock Ultra ceiling is adjustable synthetic policy, not a model specification.
|
||
|
||
## Configuration and failures
|
||
|
||
[Basic](../config/mock-basic.toml) and [Ultra](../config/mock-ultra.toml) profiles
|
||
are partial TOML overrides of `MockConfig::default()`, separate from application
|
||
settings. Unknown keys and invalid bounds fail before accepting a session.
|
||
Public Rustdoc lists every field and unit. `session_timeout_ms` defaults to
|
||
30,000 and bounds server socket reads/writes; client timeouts are independent.
|
||
`read_chunk_bytes` and `write_chunk_bytes` exercise partial I/O. TCP may coalesce
|
||
chunks. Commands, frame allocations, pending responses and command history are
|
||
bounded; integrations must read responses instead of pipelining indefinitely.
|
||
|
||
`fault` is one of `none`, `reject`, `timeout`, `disconnect`, `missing_prompt`,
|
||
`truncated_frame`, `bad_alignment`. It fires once per session on the first
|
||
`fault_command` (default `scanraw`). Frame corruption requires `scanraw`.
|
||
Rejection/timeout/disconnect do not execute the command. Missing prompt and
|
||
frame corruption occur after execution. Timeout drops the response: an empty
|
||
in-memory read immediately returns `TimedOut`; a TCP client waits for its own
|
||
socket deadline. Disconnect yields EOF, then `BrokenPipe` on later writes.
|
||
|
||
Example fault override:
|
||
|
||
```toml
|
||
fault = "truncated_frame"
|
||
fault_command = "scanraw"
|
||
read_chunk_bytes = 1
|
||
write_chunk_bytes = 1
|
||
```
|
||
|
||
Faults verify error handling and resume attempts, not reliable recovery from
|
||
all possible real firmware stream states. Hardware transcripts and per-firmware
|
||
acceptance tests remain [roadmap work](roadmap.md).
|