Send a signal from one software-defined radio and watch its spectrum on another, using the example programs that ship with UHD. First a built-in sine wave, then your own IQ samples from a file, converted from a MATLAB .mat file (or written from Python) with cosmos-iq-convert.
Every COSMOS SDR image carries UHD, the driver for Ettus/NI USRP radios, and with it a set of small example programs. Three of them are all you need to make two radios talk:
| Program | What it does |
|---|---|
tx_waveforms |
transmits a built-in waveform (sine, square, ramp, constant) |
tx_samples_from_file |
transmits IQ samples read from a file, optionally on a loop |
rx_ascii_art_dft |
shows a live spectrum in the terminal |
rx_samples_to_file |
records IQ samples to a file, so you can analyse them afterwards |
cosmos-iq-convert (on the console) |
turns a MATLAB .mat (or .npy, CSV) waveform into the file tx_samples_from_file plays |
This page uses the sb5 sandbox: two USRP B210 radios joined by a coaxial cable through a fixed 60 dB attenuator. Nothing is radiated, nobody else's signal gets in, and the link is the same every time you use it.
tx_waveforms and find it on a live spectrum.tx_samples_from_file, and predict what its spectrum should look like before you transmit it..mat) into the file the radio plays with cosmos-iq-convert, at a safe amplitude and the right rate.| Difficulty | Beginner |
|---|---|
| Time | 45 minutes, plus about 15 minutes of imaging |
| Sandbox | sb5 (2 × B210, coax through a fixed 60 dB attenuator) |
| Image | baseline-sdr.ndz (Ubuntu 24.04, UHD 4.9) |
| Transmits over the air? | No: the radios are cabled |
| Last verified | 2026-11-11 on sb5, every command and number on this page (evidence evidence/uhd-basics-sb5-20261111 in cosmos-orchestration). The PATH behaviour was re-checked the same day on the rebaked baseline-sdr.ndz (same UHD 4.9.0); the radio measurements are from the image before it. |
omf basics: load an image, power nodes on (OMF commands).| Resource | Nodes | Notes |
|---|---|---|
| sb5 | node1-1 (transmitter), node1-2 (receiver) |
one USRP B210 on USB on each |
baseline-sdr.ndz |
both | UHD 4.9.0; the example programs are in /usr/lib/uhd/examples/, on the PATH of a login shell |
node1-1 ── USB ── B210 TX/RX ──coax── [ 60 dB attenuator ] ──coax── RX2 B210 ── USB ── node1-2
(transmitter) (receiver)
Log in to the console:
ssh YOUR_USERNAME@console.sb5.cosmos-lab.org
Load the SDR image on both nodes. -r 0 expands the root partition to the whole disk. omf load leaves the nodes off, so turn them on afterwards:
omf load -t node1-1,node1-2 -i baseline-sdr.ndz -r 0 -o 2400 -b 600
omf tell on -t node1-1,node1-2
Wait for 2 nodes successfully imaged. A minute or two after omf tell on, both nodes answer ssh root@node1-1.
Check that each node sees its radio:
ssh root@node1-1 uhd_find_devices
[INFO] [UHD] linux; GNU C++ version 13.2.0; Boost_108300; UHD_4.9.0.0+ds1-1~noble2
--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
serial: 30D3F15
name: MyB210
product: B210
type: b200
Open two terminals on the console: one logged in to node1-1 (transmitter), one to node1-2 (receiver):
ssh root@node1-1 # in the second terminal: ssh root@node1-2
The image puts the examples on the PATH of a login shell like this one (/etc/profile.d/uhd-examples.sh). A one-off ssh root@node1-1 <command> is not a login shell, so there use the full path /usr/lib/uhd/examples/<program>, as Part 3 does.
On the receiver (node1-2), start the live spectrum, centred on 2 GHz, 1 MHz wide:
rx_ascii_art_dft --args type=b200 --freq 2e9 --rate 1e6 --gain 50 --ref-lvl -30 --dyn-rng 70 --frame-rate 5
On the transmitter (node1-1), send a sine 100 kHz above the carrier:
tx_waveforms --args type=b200 --freq 2e9 --rate 1e6 --gain 85 --ampl 0.3 --wave-type SINE --wave-freq 100e3
Actual TX Freq: 2000.000000 MHz...
Checking TX: LO: locked ...
Press Ctrl + C to stop streaming...
A spike appears 100 kHz right of centre. Try --wave-type SQUARE: a square wave is a sum of odd harmonics, so lines appear at 100, 300 and 500 kHz. Then try --wave-freq -100e3: in complex (I/Q) baseband, negative frequencies are real, and the line moves left of centre. Stop each program with Ctrl-C.
What we measured (tx gain 85, rx gain 50, 1 s recorded with rx_samples_to_file):
| Where | Level relative to the tone | What it is |
|---|---|---|
| +100 kHz | 0 dB | the sine (it arrives at 99.7 kHz: the two radios' clocks differ by about 0.15 ppm) |
| 0 Hz | −28 dB | DC offset and LO leakage, in both radios |
| −100 kHz | −53 dB | the I/Q image: a small gain/phase mismatch between the I and Q paths mirrors every signal |
| +200 kHz | −42 dB | second harmonic |
| noise floor | −67 dB |
The difference between tx gain 75 and 85 was 9.3 dB at the receiver: close to the 10 dB asked, so at these settings the transmitter is still linear.
tx_samples_from_file readsA raw file with no header: I₀ Q₀ I₁ Q₁ I₂ Q₂ …, little-endian.
--type float, each value is a 32-bit float with full scale ±1.0 (an fc32 file).--type short, it is a 16-bit integer with full scale ±32767 (sc16).Nothing in the file says the sample rate. You give it with --rate, and it must be the rate the waveform was made for.
Waveforms are usually designed somewhere else, most often in MATLAB, so the first step is turning that design into this format.
Every console has cosmos-iq-convert and a sample MATLAB file to try it on: staircase.mat. It holds five tones at 1 MS/s, each 6 dB below the last, with one slot left empty. On the console:
cp /usr/share/cosmos-experiments/_shared/samples/staircase.mat .
cosmos-iq-convert staircase.mat -o staircase.fc32
{"file": "staircase.fc32", "format": "fc32", "uhd_type": "float", "rate": 1000000.0, "source": "staircase.mat", "scale": 0.28, "input": {"samples": 10000, "peak": 2.5, "rms": 1.487406, "papr_db": 4.51}, "output": {"samples": 10000, "peak": 0.7, "rms": 0.416474, "papr_db": 4.51}}
The output says what the converter did and why:
.mat holds a complex vector iq and a scalar fs. The converter took the only complex vector as the waveform and fs as the rate. With several candidates it stops and asks for --var NAME.staircase.fc32.json beside the output. That is where --rate comes from, because the .fc32 cannot carry it.Copy the result to the transmitter:
scp staircase.fc32 root@node1-1:
The staircase is built to be read off a spectrum:
--repeat loops without a jump. A jump at the loop point would smear every tone.With Python instead of MATLAB, numpy writes the same file directly. On the node:
python3 - <<'PYEOF'
import numpy as np
t = np.arange(10000) / 1e6 # 10 ms at 1 MS/s
x = sum(10 ** (db / 20) * np.exp(2j * np.pi * f * t)
for f, db in [(-300e3, 0), (-200e3, -6), (-100e3, -12), (100e3, -18), (200e3, -24)])
(x * 0.7 / abs(x).max()).astype(np.complex64).tofile("staircase.fc32")
PYEOF
On the transmitter, play the file on a loop, at the rate the converter reported:
tx_samples_from_file --args type=b200 --file staircase.fc32 --type float --rate 1e6 --freq 2e9 --gain 85 --repeat
The staircase appears on the receiver's rx_ascii_art_dft. To measure it instead of eyeballing it, record a second of samples on the receiver while the transmitter runs:
rx_samples_to_file --args type=b200 --freq 2e9 --rate 1e6 --gain 50 --type float --nsamps 1000000 --file rx.fc32
rx.fc32 is in the same format the transmitter read, so you can open it in MATLAB (fread(fid, [2 Inf], 'float32')) or numpy. On the console (scp root@node1-2:rx.fc32 . first):
python3 - <<'PYEOF'
import numpy as np
x = np.fromfile("rx.fc32", np.complex64)[200000:] # skip the first 0.2 s (the radio settling)
n = 8192; w = np.hanning(n)
P = np.mean([abs(np.fft.fft(x[i:i + n] * w)) ** 2 for i in range(0, x.size - n, n)], axis=0)
f = np.fft.fftfreq(n, 1e-6); D = 10 * np.log10(P / P.max())
for k in (-300e3, -200e3, -100e3, 100e3, 200e3, 300e3):
print("%+5.0f kHz %6.1f dB" % (k / 1e3, D[abs(f - k) < 3e3].max()))
PYEOF

What we measured:
| Tone | In the file | Received (fc32) | Received (sc16, --type short) |
|---|---|---|---|
| −300 kHz | 0 dB | 0 dB (reference) | 0 dB (reference) |
| −200 kHz | −6 dB | −4.9 dB | −5.5 dB |
| −100 kHz | −12 dB | −10.3 dB | −11.6 dB |
| +100 kHz | −18 dB | −16.8 dB | −17.0 dB |
| +200 kHz | −24 dB | −23.8 dB | −23.2 dB |
| +300 kHz (empty) | none | −54 dB | −54 dB |
.mat converted with --format sc16 and played with --type short. It arrived at the same power (RMS 0.0237 against 0.0238), so both formats are scaled alike.Transmit with --rate 500e3 and leave the receiver at 1 MS/s. Every tone lands at half its frequency (measured: −150, −100, −50, +50, +100 kHz; bottom panel of the figure). The file has no way to tell the radio its rate, which is why cosmos-iq-convert writes it into the .json beside the file.
Save the complex waveform and its sample rate from MATLAB, then convert it on the console:
% x: your complex waveform (a vector), fs: the sample rate it was designed at
save('waveform.mat', 'x', 'fs'); % any version, v7.3 included
cosmos-iq-convert waveform.mat -o waveform.fc32
scp waveform.fc32 root@node1-1:
ssh root@node1-1 /usr/lib/uhd/examples/tx_samples_from_file --args type=b200 --file waveform.fc32 --type float --rate <fs> --freq 2e9 --gain 85 --repeat
| Option | When |
|---|---|
--var NAME |
the .mat holds more than one complex array |
--rate R |
the .mat has no fs / Fs / samp_rate / sample_rate |
--peak 0.5 |
a high-PAPR waveform (OFDM, noise bursts) needs more headroom than 0.7 |
--format sc16 |
write 16-bit integers for --type short (half the file size) |
--no-scale |
your values are already scaled (refused if any would clip) |
It also reads:
.npy files;writematrix text, one 1+2i value per line.A real N × 2 or 2 × N array is taken as I and Q.
Or write the file directly from MATLAB, scaled and interleaved:
x = x / max(abs(x)) * 0.7; % peak 0.7 of full scale
v = [real(x(:)).'; imag(x(:)).']; % 2 x N: column-major order gives I1 Q1 I2 Q2 ...
fid = fopen('waveform.fc32', 'w', 'ieee-le');
fwrite(fid, v(:), 'float32');
fclose(fid);
Neither MATLAB snippet was run in MATLAB for this page. The converter was tested on MATLAB v5 and v7.3 (HDF5) files written the way MATLAB writes them; the fwrite layout is the one the numpy generator above produces.
Parts 1-3 are packaged as the uhd-basics tutorial, installed on every console. One command runs both
steps on the two nodes:
cosmos-iq-convert and played with tx_samples_from_file.It records each with rx_samples_to_file and checks the result against the transmitted signal's own
spectrum. It runs the same UHD command lines as above, printed as it goes. The same run is available
three ways: this command (Ansible), --mode manual (the shell script a person would type) and a Jupyter
notebook that takes the signal apart stage by stage (cosmos-tutorial jupyter uhd-basics).
To play your own waveform, list the parameters with cosmos-tutorial params uhd-basics. Then put
uhd_waveform: /path/to/waveform.mat in a file my.yml and add --params my.yml to the run command.
| Domains | sb5, grid |
| Nodes | 2, in this order: tx, rx, named in OMF_NODES |
| On the console | python3, ansible-playbook, ssh, scp, cosmos-iq-convert |
cosmos-tutorial check uhd-basics verifies, on each node:
Change any of these with cosmos-tutorial run uhd-basics --params my.yml. An unknown key or a wrong type is refused. cosmos-tutorial params uhd-basics prints the file.
| Key | Default | Meaning |
|---|---|---|
uhd_freq |
2000000000.0 |
Carrier and sample rate. |
uhd_rate |
1000000.0 |
|
uhd_tx_gain |
85 |
Gains. |
uhd_rx_gain |
50 |
|
uhd_tone_type |
SINE |
Step 1: a built-in waveform from tx_waveforms. |
uhd_tone_freq |
100000.0 |
offset from the carrier, Hz (negative is allowed) |
uhd_tone_ampl |
0.3 |
fraction of full scale |
uhd_waveform |
sample:staircase |
Step 2: your own samples from a file, played with tx_samples_from_file. "sample:staircase" is the shipped MATLAB file (five tones, 0 to -24 dB in 6 dB steps, +300 kHz left empty), converted with cosmos-iq-convert like any .mat of yours. |
uhd_waveform_var |
`` | the .mat variable, when it holds more than one complex array |
uhd_waveform_peak |
0.7 |
fraction of full scale the converter scales to |
uhd_settle_s |
12 |
Recording and analysis. |
uhd_skip_s |
0.2 |
dropped from the start of each recording (receiver settling) |
uhd_capture_s |
1.0 |
analysed per step |
uhd_tone_floor_db |
-40 |
a spectral line in the FILE counts as a tone above this (dB from its peak) |
uhd_min_snr_db |
30 |
every tone must stand this far above the received noise floor |
uhd_level_tol_db |
3 |
and keep its level, relative to the strongest tone, within this |
export OMF_NODES=<tx>,<rx>
cosmos-tutorial check uhd-basics
cosmos-tutorial run uhd-basics # ansible
cosmos-tutorial run uhd-basics --mode manual # manual
cosmos-tutorial jupyter uhd-basics # jupyter
cosmos-tutorial run uhd-basics --mode parity # parity
cosmos-tutorial run uhd-basics --mode teardown # teardown
What a run reports (sb5, 2026-11-12, ansible mode):
All three modes were run on the same two nodes and agreed within 0.6 dB (evidence
evidence/uhd-basics-parity-sb5-20261112 in cosmos-orchestration).
Package cosmos-experiments-uhd-basics 0.1.0-5 - on every console it is released to (cosmos-tutorial list shows the installed version). The code is installed on the console in /usr/share/cosmos-experiments/uhd-basics/; the nodes load baseline-sdr.ndz. To change anything, cosmos-tutorial copy uhd-basics puts an editable copy in the current directory, and cosmos-tutorial run uhd-basics then runs that copy instead of the installed one (cosmos-tutorial which uhd-basics shows which will run). Repository (GitLab account needed, not needed to run or change it): packages/cosmos-experiments-uhd-basics/usr/share/cosmos-experiments/uhd-basics.
--rate R tells the radio how fast to feed those numbers to its DAC. Change R and you rescale every frequency in the file, as Part 2 showed.--freq (2 GHz here). Your 0 Hz becomes 2.000 GHz, and −300 kHz becomes 1.9997 GHz.--rate.rx_ascii_art_dft live, or numpy afterwards) turns the received samples back into frequencies. What it shows is your signal plus what the radios add: DC/LO leakage at 0 Hz, the I/Q image mirrored around 0 Hz, a slope across the band, and the noise floor.Stop every transmitter and receiver with Ctrl-C. Nothing else needs undoing: the next user's image load wipes the nodes.
| Symptom | Cause | Fix |
|---|---|---|
tx_waveforms: command not found |
a one-off ssh node <command> (not a login shell), or a node loaded before 2026-11-11 |
use the full path /usr/lib/uhd/examples/tx_waveforms, or bash -lc '<command>' |
uhd_find_devices finds nothing |
the node is still booting, or it carries an image without UHD | wait a minute; cat /.omf-image-name should say baseline-sdr.ndz |
Device busy, or a second program cannot open the radio |
another UHD program still holds the B210 | stop it with Ctrl-C; pgrep -a tx_ / pgrep -a rx_ |
| Lines at the wrong place | --rate differs from the rate the file was made for |
use the rate the waveform was designed at |
Extra lines and shoulders that grow faster than the signal when you raise --gain |
the transmitter is compressing | lower --gain, or scale the file to a smaller peak |
U characters printed by the transmitter (underflow) |
the host could not feed samples fast enough | lower --rate; close other programs on the node |
--help on any of them lists every option.Author: COSMOS team · Last verified: 2026-11-11 on sb5 (B210 pair, baseline-sdr.ndz, UHD 4.9.0) · Tags: getting-started, sdr, uhd, b210, iq