127 lines
6.0 KiB
Markdown
127 lines
6.0 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 its detected model/revision policy; the mock's larger synthetic range is not
|
|
a production capability. ZS406 limits are covered by identity-policy transcript
|
|
tests rather than inferred from this generic Ultra mock.
|
|
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).
|