# USB console and `scanraw` protocol This document is the implementation reference for talking to tinySA firmware. It combines the official USB-interface description with the behavior visible in the upstream C source and in `src/protocol.rs`, `src/transport.rs`, and `src/acquisition.rs`. ## Transport Connecting a powered tinySA by a data-capable USB cable exposes a virtual serial port (USB CDC): commonly `/dev/ttyACM*` on Linux and `COM*` on Windows. Drivers are built into most Linux systems and are normally installed automatically on Windows. The on-device shell is a command stream, not a packet protocol: - commands are ASCII and are normally terminated by carriage return (`\r`); - terminal input is commonly echoed, so a reply can begin with the command; - ordinary output is text; - the ready prompt is `ch>`; - some commands (`capture`, display bulk data, and `scanraw`) place binary data in the same byte stream; - firmware performs limited parameter validation, so a prompt does not prove that the intended operation occurred. The baud selector in tiny-wb controls how the host opens the serial device. USB CDC and the optional internal TTL USART are different transports; `usart_cfg` configures/reports the internal serial interface in firmware. Do not infer the physical USB transfer speed from that value. ## Shell grammar Common scalar syntax is: - frequency: integer/floating value, optionally suffixed `k`, `M`, or `G`; - level: floating-point dB/dBm value; - time: seconds, optionally suffixed `m` (milliseconds) or `u` (microseconds). For software, plain integer Hz is the least ambiguous frequency representation. Commands and availability vary by build; issue `help`, then record `version` and `info` before relying on optional commands. ## Commands relevant to tiny-wb | Command | Meaning and notes | | --- | --- | | `version` | Firmware version/build text. | | `info` | Model/platform information when enabled in the build. | | `help` | Commands compiled into this firmware. Prefer this over a hard-coded global list. | | `mode low input` | Select Basic low input; on Ultra, firmware also accepts `mode input` and has no Basic high path. | | `mode high input` | Select Basic high input. Not an Ultra input mode. | | `pause` / `resume` | Stop/restart normal display sweeping. | | `repeat 1..1000` | Measurements per frequency. More repeats reduce random noise and increase time. | | `zero N` | Set the additive raw-sample encoding offset used by `scanraw`; not an RF zero/calibration operation. | | `sweep start F`, `sweep stop F` | Change display sweep boundaries. `sweep` alone reports settings. | | `scan START STOP [POINTS] [OUTMASK]` | Perform a scan with at most 290 points and optional textual output. Outmask bits are 1 frequencies, 2 measured data, and 4 stored data. | | `scanraw START STOP [POINTS] [OPTIONS]` | Perform an arbitrary-point binary scan. Option bit 0 requests unbuffered writes; bit 1 repeats continuously. | | `rbw auto` or `rbw VALUE` | Set resolution bandwidth in kHz in current firmware syntax. Valid ranges differ by model. | | `attenuate auto` or `attenuate 0..31` | Select automatic/manual front-end attenuation where supported. | | `spur off\|on[\|auto]` | Control spur removal; `auto` is Ultra-specific. | | `lna off\|on` | Ultra optional LNA; reduces overload headroom and disables its step attenuator path. | | `ultra off\|on\|auto\|start\|harm ...` | Ultra-family build only; control extended-frequency behavior. | | `leveloffset`, `vbat`, `threads`, `usart_cfg`, `marker` | Diagnostic/status queries used by tiny-wb; exact output is firmware-dependent. | Avoid sending mutating calibration, output, correction, or configuration-save commands until the model and active port are known. ## `scanraw` request The request is: ```text scanraw START_HZ STOP_HZ POINTS [OPTIONS]\r ``` Constraints visible in upstream firmware: - at least start and stop are required; - start must not exceed stop; - points defaults to the current display sweep-point count; - option values are bit flags: `1` unbuffered, `2` continuous, `3` both; - waterfall is disabled before acquisition in current firmware; - a continuous request must be explicitly aborted and needs a streaming parser. tiny-wb omits OPTIONS, so ordinary acquisition requests one buffered sweep and `--live` repeats that complete request over one configured connection. The firmware buffers in small blocks internally; “buffered” does not mean the entire sweep is delivered in a single USB transfer. Native option-2 continuous framing remains unsupported until explicit abort and resynchronization are verified. ## Binary response framing Ignoring command echo, line endings, and the final prompt, the firmware emits: ```text 0x7b # '{' 0x78 LOW_BYTE HIGH_BYTE # 'x', sample 0, little-endian 0x78 LOW_BYTE HIGH_BYTE # 'x', sample 1 ... 0x7d # '}' ``` Thus the framed body length is `1 + 3 * points + 1` bytes. Each level is a 16-bit raw value. Although the official USB page describes the bytes in one place as “MSB LSB,” the firmware source writes `val & 0xff` first and `val >> 8` second. The repository correctly unpacks the value as little-endian. The `x` byte is a per-record alignment marker, not padding. Basic and Ultra use the same braces, marker, two-byte value and exact body length; there is no model-specific padding in the documented or reviewed `scanraw` format. Their model-specific difference is the numeric level bias described below. Payload bytes are arbitrary. A payload byte can equal `{`, `}`, `x`, `c`, `h`, or `>`. Framing logic must only interpret `{` before the records, `x` at every three-byte record boundary, and `}` after exactly the requested record count (or after an explicitly aborted short frame). Searching binary payload for text tokens is unsafe. ## Level conversion and `zero` The [official USB interface](https://tinysa.org/wiki/pmwiki.php?n=Main.USBInterface) documents these native conversions: ```text Basic dBm = raw_u16 / 32 - 128 Ultra dBm = raw_u16 / 32 - 174 ``` This is a fixed-point value with 1/32 dB numeric steps. The detector itself has coarser effective resolution, so the encoding precision is not the same as measurement accuracy. The reviewed [firmware defaults](https://github.com/Ho-Ro/tinySA/blob/main/main.c#L1099-L1200) set `config.ext_zero_level` to 128 for Basic and 174 for Ultra. The [`scanraw` implementation](https://github.com/Ho-Ro/tinySA/blob/main/sa_cmd.c#L1221-L1267) adds that offset to the measured value, and the [`zero` handler](https://github.com/Ho-Ro/tinySA/blob/main/sa_cmd.c#L602-L609) lets `zero N` replace it. tiny-wb detects the family and selects its native offset automatically, then requires matching `zero` readback before scanning. For Basic this gives: ```text dBm = raw_u16 / 32 - 128 ``` Ultra uses 174. Manual normalization is still available with `scan.auto_zero_offset = false`; readback must agree with `scan.zero_offset`. A mismatch would shift levels by 46 dB between native defaults, so acquisition now rejects missing or mismatched readback. See [support and migration](ultra-support.md). ### Worked record Suppose the three bytes are: ```text 78 00 08 ``` `0x0800` is 2048. With `zero 128`: ```text 2048 / 32 - 128 = -64 dBm ``` ## Frequency assignment The official USB command page specifies the `scanraw` request and record count, but does not define a point-to-frequency formula. The upstream [`cmd_scanraw` implementation](https://github.com/Ho-Ro/tinySA/blob/main/sa_cmd.c#L1221-L1263), reviewed on 2026-10-05, is the byte-level authority used here. Its C expression has three relevant conversions: ```text integer_step_hz = integer_divide(stop_hz - start_hz, points) firmware_step_hz = float32(integer_step_hz) frequency_hz[i] = start_hz + truncate_to_freq_t(firmware_step_hz * float32(i)) for i = 0 .. points - 1 ``` The denominator is `points`, not `points - 1`. Integer division discards any remainder before the assignment to the 32-bit `float`; multiplication can then round at large values before conversion back to `freq_t`. For example, a 0–10 Hz, three-point request measures nominally at 0, 3, and 6 Hz. The requested stop is an upper boundary and the final point is normally roughly one step below it. tiny-wb's `firmware` axis reproduces these conversions, including the single-precision rounding. The default is now `scan.frequency_axis = "firmware"`. The compatibility-only `inclusive` setting retains labels produced by older tiny-wb releases: ```text host_step = (stop - start) / (points - 1) frequency[i] = start + host_step * i ``` `inclusive` labels both requested endpoints and disagrees with the reviewed firmware. The discrepancy grows linearly through a sweep to almost one firmware step at the last point. Existing saved configuration remains compatible because an explicit `inclusive` value is still accepted. Record the connected device's `version` when validating a narrow carrier: the synthetic tests establish source parity, not RF frequency accuracy or behavior of every firmware revision. ## Prompt and synchronization behavior A reliable request/response state machine should: 1. retain a persistent receive buffer across OS reads; 2. write the complete command plus `\r`; 3. parse optional echo and line endings; 4. for text commands, recognize `ch>` even when split across reads and retain any bytes after it; 5. for `scanraw`, find the frame start in shell text, then consume exactly the expected number of aligned records and the closing brace before looking for the prompt; 6. use an overall deadline plus idle deadlines rather than treating one serial timeout as a successfully completed short reply; 7. make cancellation explicit with the firmware's `abort` behavior; 8. return protocol errors that include command, stage, byte counts, and a bounded hex/text diagnostic. Sleeping a fixed duration is not a protocol guarantee. Sweep time changes with span, RBW, repeat, mode, signal-processing options, and firmware. ## Current tiny-wb transaction The current code sends the following logical sequence (frequency placeholders are decimal Hz): ```text version info help leveloffset vbat usart_cfg threads marker repeat REPEAT zero MODEL_OFFSET zero pause mode LOW_OR_HIGH input sweep start START sweep stop STOP sweep scan START STOP 290 101 scanraw START STOP POINTS resume ``` Every item except `scanraw` goes through the text helper and waits for `ch>`. The transport retains unread bytes and recognizes prompts split across serial reads. It consumes the complete length-delimited raw frame before returning to text prompt parsing; arbitrary sample bytes cannot prematurely end the frame. The pure decoder requires the exact record count, alignment and closing brace. After attempting `pause`, acquisition attempts `resume` even if frame decoding or a later command fails. A failed recovery is included with the original error. There is no cancellation protocol or full state restoration, and process exit can prevent recovery. The offset requires readback; other settings are checked for recognizable command errors. Optional diagnostic queries require `help` advertisement. ZS406 Ultra acquisition additionally requires explicit opt-in, an advertised `ultra` command and exact requested `sweep` boundary readback. See [model-specific planning](ultra-support.md). The `scan` outmask value `101` remains outside the documented three-bit mask and its returned data is discarded. The legacy preparation is enabled by default for compatibility, controlled by `scan.legacy_pre_scan`. Establish its hardware purpose before changing the default or copying it into another client. ## Manual diagnostic session Use a serial terminal that can send carriage return, with every RF source disconnected or safely attenuated. A minimally invasive identification session is: ```text version info help sweep vbat ``` Save the exact transcript. Do not test `scanraw` in a terminal that assumes all input is UTF-8; it returns binary and may corrupt the display or its own log. Use a byte-oriented program and a bounded point count instead. ## Compatibility rules for implementers - Identify capabilities; do not infer Ultra merely from a version prefix if `info` gives an explicit model. - Treat the command list as a firmware-build property. - Keep Basic low/high path selection separate from Ultra normal/Ultra/harmonic range selection. - Make raw offset, valid frequency range, RBW limits, and legal mode syntax model capabilities. - Do not use UTF-8 strings for the mixed shell/binary receive buffer. - Never use an unescaped textual prompt as a delimiter inside a binary frame. - Restore or clearly report every instrument setting that the client changes. - Include model, firmware version, configured offset, start/stop, point count, repeat, RBW, attenuation, LNA, and Ultra state in future output metadata. See [Project architecture](architecture.md#extension-points-and-remaining-limits) for remaining implementation limits and [tiny-wb operations](tiny-wb-operations.md) for what users can safely expect today. ## Configuration command rejection `Shell::command_checked` rejects text lines beginning with `error:`, `usage:`, or `unknown command` (case-insensitive). Acquisition uses it for settings and pause/resume; diagnostic queries retain raw replies. This catches known failure forms, not every firmware-specific error or acknowledgement. Binary scan errors still fail framing/timeout checks. Model-aware replies remain roadmap work.