Skip to content

Check a Synthetic IQ Exercise

This standard-library Python 3.10+ checker is for local synthetic exercises, not live capture, uploading or full SigMF conformance. It checks declarations and file size; it cannot establish where a recording came from or whether samples actually contain the declared encoding.

From a monorepo checkout:

Terminal window
python3 apps/wiki/scripts/check_rf_exercise.py --manifest apps/wiki/scripts/fixtures/rf/good.manifest.json
python3 apps/wiki/scripts/check_rf_exercise.py --manifest apps/wiki/scripts/fixtures/rf/truncated.manifest.json
python3 -m unittest discover -s apps/wiki/scripts/tests -p 'test_rf_exercise.py' -v

The first command returns ok: true, exit 0 and duration_seconds: 0.0001. The truncated fixture returns exit 1 with a data_file: size mismatch error. The tests include contradictory endianness, malformed field types, invalid rates, count mismatches, path/symlink escapes and an audit guard against socket operations, file writes and sample-content reads.

{
"format": "iq-s16le",
"sample_rate_hz": 1000000,
"byte_order": "little",
"sample_count": 100,
"data_file": "good.iq",
"provenance": {"source": "synthetic"}
}
FieldContract
formatExactly iq-s16le: interleaved signed 16-bit I/Q, four bytes per complex sample.
sample_rate_hzA positive finite number of complex samples per second, not a Boolean.
byte_orderExactly little, consistent with the supported format.
sample_countNonnegative integer count of complex samples, not a Boolean.
data_fileNonempty relative path inside the selected exercise directory; symlinks resolving outside it and absolute paths are rejected.
provenance.sourceExactly synthetic: an explicit contributor declaration, not verified provenance.

The exercise directory defaults to the manifest’s parent. Select another with --exercise-dir /path/to/exercise; data paths are relative to that directory. The manifest is the explicitly selected metadata input. No automatic scan occurs.

The file must have exactly sample_count × 4 bytes. Duration is sample_count / sample_rate_hz, rounded to six decimal places, and must be finite. The checker reads the JSON and stats the data file; it never opens IQ sample contents, modifies files, opens sockets or prints sample bytes. Success output includes only the validated fields and the synthetic-source declaration.

Exit 1 returns ok: false and an errors array. Each error identifies a field: format, byte_order, sample_rate_hz, sample_count, data_file, provenance or manifest. Correct the named metadata or regenerate the synthetic data; do not change the count just to hide an unexpectedly truncated recording. Argument usage errors use argparse’s normal exit 2.

Related: Software Defined Radios.

Recent changes

  1. feat(wiki): add read-only RF/SDR exercise sidecar checker Hugo Zarate