Two Wi-Fi cards on the sb4 RF matrix, joined by a cable and a programmable attenuator. One sends tagged frames at several rates; every radio of the other captures them. Stepping the attenuator shows whether the receiver's reported signal follows the real change, and how weak each rate can get before frames stop arriving. Stepping the requested transmit power shows whether the sender does what it is told.
sb4, image baseline.ndz, node1-5 (AR928X, ath9k) sending to node1-6 (AR928X ath9k and Intel 6250 iwlwifi both listening): all three modes (ansible, manual, Jupyter) with a passing parity run. Evidence: evidence/wifi-calibrate-sb4-20261108/ in cosmos-orchestration.Every Wi-Fi card reports a signal strength for each frame it receives (radiotap antenna signal, dBm) and accepts a transmit power (iw ... set txpower, dBm). Both look like measurements. The receiver's number is the card's own estimate, derived from its gain settings; the transmitter's is a request that the driver may round, cap or ignore. Most Wi-Fi experiments quote them as if they were instrument readings.
On sb4 the Wi-Fi cards are not in the air at all: each is cabled to an RF matrix whose ports are joined pairwise through attenuators (0–63 dB in 1 dB steps, read back after every change). That is the one place on COSMOS where the path between two cards changes by a known amount. The tutorial uses wifi-inject to send and wifi-sniff to capture, and one library to plan the points, drive the matrix and build the result contract. Which matrix port carries which node's card is read from the matrix service's own switch labels, and the matrix is put back as found at the end of every run.
| Difficulty | Intermediate |
| Time | ~7 minutes per run (31 points), plus imaging |
| Sandbox | sb4 (the RF matrix). Anywhere else cosmos-tutorial check wifi-calibrate says NOT RUNNABLE: the matrix service refuses every other console |
| Image | baseline.ndz |
| Transmits? | Yes, but only into the matrix: sb4's Wi-Fi cards have no antennas in the air |
| Modes | manual, Ansible, Jupyter |
sb4 (Getting started) and SSH to its console (SSH).baseline.ndz and powered on (OMF commands): omf load -t node1-5,node1-6 -i baseline.ndz -r 0, then omf tell on -t node1-5,node1-6.| Domains | sb4 |
| Nodes | 2, named in OMF_NODES |
| On the console | python3, ansible-playbook, ssh, tar, curl |
cosmos-tutorial check wifi-calibrate verifies, on each node:
Not in the package - you provide:
export OMF_NODES=<node>,<node>
cosmos-tutorial check wifi-calibrate
cosmos-tutorial run wifi-calibrate # ansible
cosmos-tutorial run wifi-calibrate --mode manual # manual
cosmos-tutorial jupyter wifi-calibrate # jupyter
cosmos-tutorial run wifi-calibrate --mode parity # parity
cosmos-tutorial run wifi-calibrate --mode teardown # teardown
The first node of OMF_NODES sends, the second listens. Any two of node1-3 to node1-6 work; node1-1 and node1-2 are cabled too but did not check in after imaging on 2026-11-06 and 2026-11-08, and node1-7/1-8 carry no Wi-Fi card.
Change any of these with cosmos-tutorial run wifi-calibrate --params my.yml. An unknown key or a wrong type is refused. cosmos-tutorial params wifi-calibrate prints the file.
| Key | Default | Meaning |
|---|---|---|
cal_send_radio |
ath9k |
Which radio sends: an index, phy or driver. |
cal_listen_radios |
all |
Which of the receiver's radios listen: indexes, phys or drivers, or [all] (every radio wifi-sniff lists). |
cal_channel |
1 |
The channel the two cards meet on. |
cal_rates |
1, 6, 54 |
Legacy rates sent at every point, Mb/s: one stream each. |
cal_mcs |
0, 7 |
HT MCS indexes sent at every point (a legacy radio refuses these). |
cal_count |
150 |
Frames per stream per point. |
cal_interval_ms |
3 |
Gap between frames, ms. |
cal_size |
200 |
Bytes per frame. |
cal_listen_s |
9 |
Each capture, seconds: must outlast the injection (streams x count x interval, plus setup). |
cal_regdomain |
US |
|
cal_atten_db |
17 items | Sweep 1: the matrix attenuator between the two cards' ports, dB (0-63). |
cal_atten_sweep_power_dbm |
20 |
The transmit power held during sweep 1, dBm; null = whatever the driver uses. |
cal_power_dbm |
14 items | Sweep 2: the requested transmit power, dBm. |
cal_power_sweep_atten_db |
0 |
The attenuation held during sweep 2, dB. |
cal_take_switches |
True |
A switch in front of each matrix port picks what is cabled to it (Wi-Fi card or SDR). true: a switch set to the SDR is moved to Wi-Fi for the run and put back afterwards. |
Each point of a sweep is the same five steps, in every mode:
wifi-sniff, one monitor interface per radio).wifi-inject): 150 frames each at 1, 6 and 54 Mb/s and HT MCS 0 and 7, every frame tagged with the run, the stream and a sequence number, so the capture counts exactly which frames arrived and at what signal.Sweep 1 steps the attenuator (0 to 33 dB) at 20 dBm; sweep 2 steps the requested power (0 to 25 dBm) at 0 dB.
Setting the power is less simple than it looks. mac80211 refuses a per-interface power on a monitor interface (Operation not supported), so wifi-inject --txpower sets it on the whole radio (iw phy <phy> set txpower fixed <mBm>). On ath9k the new power then reached the air only at the radio's next retune: in the first test every burst went out at the previous request, which looked like a card ignoring half its settings. wifi-inject now moves the radio off its channel and back after setting the power, and reports both the request and what the kernel says it uses.
The fits. For each listening radio and stream, the contract fits a straight line to reported signal against attenuation over the points where at least 90 % of the frames arrived, leaving out the points within 6 dB of the weakest signal received: near the floor only frames that happened to arrive strong are counted, so the median reads high (with those points the 1 Mb/s slope came out −0.78; without them −1.0). For the power sweep it finds where the received signal stops rising, and lists what the kernel still reported above that.
From the 2026-11-08 runs (node1-5 ath9k sending, node1-6 listening on both cards; attenuation sweep at 20 dBm):
| Receiving card | Stream | Slope (dB/dB) | Received down to | at matrix attenuation |
|---|---|---|---|---|
AR928X (ath9k) |
1 Mb/s | −1.0 | −91 dBm | 24 dB |
AR928X (ath9k) |
6 Mb/s | −1.1 | −87 dBm | 14 dB |
AR928X (ath9k) |
54 Mb/s | (one point) | −75 dBm | 0 dB |
Intel 6250 (iwlwifi) |
1 Mb/s | −1.0 | −88 dBm | 18 dB |
Intel 6250 (iwlwifi) |
6 Mb/s | −1.0 | −87 dBm | 12 dB |
Measured by hand the same morning, every pair of node1-3 to node1-6 both ways at 0 dB: A→B and B→A differed by up to 7 dB, although the path is the same cable both ways. The differences add up around every loop to within 1 dB, which is what one offset per card (its transmit strength minus its receive sensitivity) predicts: on that day node1-6 sent about 6 dB stronger than it heard, relative to node1-4 and node1-5.
What is not calibrated. The matrix setting is not the path loss: with 20 dBm requested and 0 dB set, the receiver reports about −70 dBm, i.e. some 90 dB through a few metres of coax, splitters and combiners plus each card's own error. Only differences between points, receivers and powers are calibrated.
Change (--params my.yml) |
Question |
|---|---|
cal_listen_radios: [iwlwifi], cal_atten_db: [10, 11, 12, 13, 14, 15, 16, 17, 18] |
Where exactly does the Intel card stop hearing 6 Mb/s? |
cal_size: 1500 |
How much more signal do long frames need? |
cal_channel: 36 |
Is the 5 GHz path through the matrix the same? |
cal_power_dbm: [10, 10, 10, 10, 10] |
How repeatable is one power setting? |
Swap the two nodes in OMF_NODES |
Is the link symmetric? Which card is the louder sender? |
The run passes when every point's attenuator read back as asked, the sender handed its frames to the kernel at every point, every listening radio produced a capture at every point, and at least one radio received the first stream at three or more attenuations (something to fit). The contract (contract.json in the run directory) holds every curve, so a passing run can still show a card that misbehaves: that is the measurement.
The run stops itself: wifi-inject and wifi-sniff run in the foreground and remove their monitor interfaces, and the matrix is put back as found on every exit path. After an interrupted run, remove a leftover interface with the teardown:
export OMF_NODES=node1-5,node1-6
cosmos-tutorial run wifi-calibrate --mode teardown
| Symptom | Cause and fix |
|---|---|
no matrix switch is labelled as the Wi-Fi of node1-N |
The switch in front of that port is set to the SDR. Keep cal_take_switches: true (the run moves it and puts it back), or pick another node. |
| A received signal that stays at the same value whatever the power | The power is past the card's maximum (see above), or the driver applies it late: check txpower.reported_dbm in points/<i>/inject.json against the received signal. |
| Every point delivers nothing | The attenuator never opened (check points/<i>/matrix.json), or the nodes are not on the matrix (node1-7/1-8 have no Wi-Fi card). |
| A node stops answering SSH during a run with the Intel card sending | Seen once on 2026-11-08 (node1-4, Intel 6250 injecting while its power was stepped): the node answered ping but not SSH. Power-cycle it with omf tell reset; the default sender is the Atheros card. |
iw transmit power: https://wireless.docs.kernel.org/en/latest/en/users/documentation/iw.htmlPackage cosmos-experiments-wifi-monitor 0.1.0-3 - 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/wifi-calibrate/; the programs in its node/ subdirectory are copied to the nodes by every run, so the node image does not need to carry them. To change anything, cosmos-tutorial copy wifi-calibrate puts an editable copy in the current directory, and cosmos-tutorial run wifi-calibrate then runs that copy instead of the installed one (cosmos-tutorial which wifi-calibrate shows which will run). Repository (GitLab account needed, not needed to run or change it): packages/cosmos-experiments-wifi-monitor/usr/share/cosmos-experiments/wifi-calibrate.