244 lines
10 KiB
Markdown
244 lines
10 KiB
Markdown
# 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](tinysa-field-guide.md#safe-operation-read-before-connecting-a-signal)
|
||
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:
|
||
|
||
```console
|
||
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:
|
||
|
||
```console
|
||
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:
|
||
|
||
1. the port saved in `config.toml`, if present;
|
||
2. common candidates (`/dev/ttyACM0`, `COM3`, `COM5`, `/dev/ttyS16`);
|
||
3. 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:
|
||
|
||
```toml
|
||
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:
|
||
|
||
```csv
|
||
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](usb-protocol.md#frequency-assignment).
|
||
|
||
### 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 `version` in a serial terminal and confirm a `ch>` 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 `scanraw` framing.
|
||
- 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](tinysa-field-guide.md#measurement-controls-and-trade-offs).
|
||
|
||
## 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 relevant `help` output;
|
||
- 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 `resume` recovered 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:
|
||
|
||
1. Parse `version`/`info` into a model and capability structure.
|
||
2. Add Ultra/Ultra+ ranges and correct mode syntax, or explicitly reject them.
|
||
3. Replace prompt searches with a persistent mixed text/binary framing state
|
||
machine.
|
||
4. Resolve the `scanraw` frequency denominator against real firmware fixtures.
|
||
5. Remove or justify the preliminary `scan ... 290 101` request.
|
||
6. Validate exact record count and closing delimiter before accepting/writing a
|
||
completed CSV.
|
||
7. Restore changed instrument state on success, cancellation, and error.
|
||
8. Put model/firmware/settings and column names in output metadata.
|
||
9. Add protocol tests based on captured Basic and Ultra transcripts.
|