10 KiB
tiny-wb compatibility and operations
This guide describes the application as it exists today. It is intentionally more conservative than “the firmware probably accepts it”: a range is called supported only when tiny-wb selects the right path, decodes it knowingly, and can represent it in the UI.
Compatibility matrix
| Instrument/use | Status | Reason |
|---|---|---|
| tinySA Basic low input, range wholly below 350 MHz | Best-supported path | The client sends mode low input, uses the Basic-oriented range, and normalizes raw samples with zero 128. |
| tinySA Basic high input, range wholly from 350 to 960 MHz | Implemented | The client sends mode high input; the RF path itself is less accurate and more overload-prone than low input. |
| tinySA Basic crossing from 240–<350 MHz into 350–960 MHz | Implemented as high input | The whole scan is forced onto the high path; the low path is not stitched to it. |
| Basic span starting below 240 MHz and ending at/above 350 MHz | Rejected | One physical path cannot cover it under the client's policy. Split it into scans. |
| tinySA Ultra/Ultra+ below 350 MHz | Experimental, not declared supported | mode low input and zero 128 are plausible, but the client neither detects nor tests the model. |
| tinySA Ultra/Ultra+ at or above 350 MHz | Not supported | The client sends Basic-only mode high input; Ultra has no such high input mode. |
| Ultra mode above the normal range | Not supported | UI stops at 960 MHz and never negotiates Ultra state/capabilities. |
| Generator control, live streaming, capture, calibration, firmware update | Out of scope | No corresponding application workflow exists. |
At the exact 350 MHz boundary, the implementation's matching rules matter: low accepts frequencies strictly below 350 MHz, while high accepts 350 MHz through 960 MHz. A scan from 0 to exactly 350 MHz is rejected, but a scan from 240 to 350 MHz is assigned to the high path.
Required equipment
- A genuine, powered tinySA Basic for the currently supported workflow.
- A data-capable USB cable. Charge-only cables do not enumerate a serial port.
- A host with permission to open the USB serial device.
- For conducted RF measurements: known-good 50-ohm coax/adapters, correctly rated fixed attenuation, and a DC block when needed.
- For transmitter work: a suitable dummy load or sampler and power-rated attenuation. Read the safe-operation guide before connecting a source.
Do initial software/serial testing with no external RF source connected. This separates communications failures from unsafe or overloaded RF setups.
Build and launch
Use a current stable Rust toolchain:
cargo build --release
./target/release/tiny-wb
The program does not currently expose meaningful command-line options; it
starts the interactive terminal immediately. Run it from the directory where
you want config.toml, logs, and scan CSV files to appear.
Serial permissions
On Linux, identify the device after plugging it in:
ls -l /dev/ttyACM*
The exact permission mechanism is distribution-specific (often a dialout or
uucp group, or a udev rule). Do not solve it by running the RF application as
root when a scoped device permission is available.
On Windows, use Device Manager to find the COM port. Close serial terminals and other tinySA applications before launching tiny-wb; only one process can normally own the port.
User interface
Connection screen
The application enumerates ports at startup. Selection priority is:
- the port saved in
config.toml, if present; - common candidates (
/dev/ttyACM0,COM3,COM5,/dev/ttyS16); - the first enumerated port.
Baud choices range from 19,200 to 3,000,000; default is 115,200 unless a saved value matches the built-in list.
Scan screen
Fields and bounds are:
| Field | Unit | Default | Step | Bounds |
|---|---|---|---|---|
| Start frequency | MHz | 240 | 10 | 0–960 |
| Stop frequency | MHz | 960 | 10 | 10–960 |
| Points | samples | 10,001 | 100 | 101–1,000,001 |
| Repeat | measurements/point | 1 | 1 | 1–1,000 |
Left/right or h/l changes the selected field. Up/down or k/j changes
the selection/value. Enter advances to the next screen. q or Escape exits.
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 received, not a predictive time estimate.
Progress and result
The scan runs on a worker thread while the UI displays shared progress and the
concatenated version/info response. On success, the final screen plots a
scatter trace. Its Y axis is fixed to −128–0 dBm, so valid results outside that
range are clipped visually even though CSV data may contain them.
Files
config.toml
The current selection is saved before acquisition starts:
port = "/dev/ttyACM0"
baudrate = 115200
start_frequency = 240
stop_frequency = 960
points = 10001
repeat = 1
Frequencies in this file are MHz, unlike protocol frequencies (Hz). The file is overwritten by the next run. A missing or invalid configuration falls back to defaults; validate unexpected values before assuming they were loaded.
CSV
The scanner writes scan_YYYYMMDD HH_MM_SS.csv in the working directory. It
has no header:
240,-92.4375
240.072,-91.96875
Column one is MHz and column two is dBm. The file is created before full frame validation, so an error can leave a partial or empty CSV. Also note the known frequency-label mismatch.
Logs
flexi_logger writes diagnostic logs to a file in the working directory. Logs
can contain instrument version/configuration details and port names. Attach the
relevant bounded excerpt—not an uncontrolled archive—when reporting a bug.
Instrument state changed by a run
tiny-wb changes repeat count, raw zero offset, input mode, display sweep start and stop, and pause/resume state. It also runs an auxiliary textual scan before the raw scan. It does not snapshot and restore previous values. If preserving a carefully tuned front-panel configuration matters, save it as an instrument preset and reload it after tiny-wb exits.
If acquisition fails after pause, error handling does not guarantee a final
resume; the front panel may remain paused. Send resume, use the UI, or
power-cycle/reload a preset after making the RF setup safe.
Troubleshooting
No serial port is listed
- Confirm the device is powered on and the cable supports data.
- Try a direct USB port or known USB 2.0 hub/cable.
- Check OS device enumeration before debugging tiny-wb.
- On Linux, inspect
/dev/ttyACM*and kernel logs; on Windows, Device Manager.
Port cannot be opened
- Close other serial terminals and tinySA software.
- Check the selected COM/TTY name and user permissions.
- Unplug/reconnect if the device was just in DFU mode; DFU and CDC serial are different USB personalities.
“No version found” or a timeout
- Verify the selected port is the tinySA, not another CDC device.
- Wake/power the instrument and close auto-refreshing software.
- Manually send
versionin a serial terminal and confirm ach>prompt. - Record firmware version. The client relies on prompt timing and may fail on a slow command or fragmented prompt even when the instrument is healthy.
Parse beginning/end/alignment error
- Reduce point count and repeat to minimize transfer time.
- Disable any other process reading the port.
- Ensure the firmware implements the documented
scanrawframing. - Preserve a raw byte capture if possible. Do not convert it through UTF-8.
- Be aware that the current reader can mistake binary bytes equal to
ch>for the shell prompt or miss a prompt split between OS reads.
Trace is shifted in frequency
The current host labels points samples over points - 1 intervals, while the
reviewed firmware measures using a span / points step. Verify with a known
carrier, record firmware version, and use the firmware formula when correcting
the exported axis offline.
Levels are wrong by about 46 dB
That is the difference between Ultra's documented default raw offset (174) and
Basic's (128). tiny-wb sends zero 128; a 46 dB shift suggests the firmware
did not accept/apply that command or the reply was not validated. Stop treating
the result as calibrated data and capture version, info, and the zero
command response.
Unexpected harmonics or spurs
Assume overload or an image until disproved. Add attenuation, reduce span, change RBW, use a filter/preselector, and compare paths where possible. Consult the measurement controls.
Reproducible bug report checklist
Include:
- tiny-wb commit hash shown in the title;
- host OS and serial port type;
- exact tinySA model/rear label;
version,info, and relevanthelpoutput;- start/stop, points, repeat, and selected baud;
- RF setup, attenuation, DC block, expected maximum level, RBW, LNA, and Ultra mode state where relevant;
- the smallest CSV/log excerpt that demonstrates the problem;
- whether the front panel was paused and whether
resumerecovered it.
Never include a dangerous live-transmitter reproduction just to demonstrate a software bug; substitute a low-level known source or recorded serial fixture.
Current engineering backlog implied by the documentation
These are documentation-derived gaps, not changes made in this task:
- Parse
version/infointo a model and capability structure. - Add Ultra/Ultra+ ranges and correct mode syntax, or explicitly reject them.
- Replace prompt searches with a persistent mixed text/binary framing state machine.
- Resolve the
scanrawfrequency denominator against real firmware fixtures. - Remove or justify the preliminary
scan ... 290 101request. - Validate exact record count and closing delimiter before accepting/writing a completed CSV.
- Restore changed instrument state on success, cancellation, and error.
- Put model/firmware/settings and column names in output metadata.
- Add protocol tests based on captured Basic and Ultra transcripts.