Application Notes¶
openwifi ships a set of application notes in openwifi/doc/app_notes/: short, task-focused write-ups for specific scenarios and modes. Their material is spread across the thematic wiki pages (Operating Modes, Research Features, sdrctl, and so on), and this page indexes every note in one place.
These notes assume a board that already boots and runs wgd.sh. If you are not there yet, start with Getting Started.
Each entry below expands to a short summary and the note's key figures. Use Read more to jump to the full section on that topic, or Original note to open the app note on GitHub.
Getting on the air: two-SDR links¶
Communication between two SDR boards: AP and client mode
Step-by-step for an access-point + client link between two openwifi boards using the standard, unmodified hostapd and wpa_supplicant. Covers confirming beacon transmission via /proc/interrupts, associating the client, and getting an IP over the link.
Communication between two SDR boards: ad-hoc mode
Bring two boards into the same 802.11 ad-hoc (IBSS) cell with sdr-ad-hoc-up.sh, confirm both nodes converge on the same Cell ID, and ping across. Includes the antenna-isolation and 5 GHz TX-power caveats.
CSI and sensing¶
From CSI (Channel State Information) to CSI (Chip State Information)
Per-packet CSI (timestamp, frequency offset, channel response, and equalizer output) streamed to a PC through the FPGA side channel. Shows the data path, the 64-bit packet format, how to filter captures by MAC address, and the display scripts.
WiFi CSI radar via self CSI capturing
Full-duplex "Wi-Fi radar": with a TX and an RX antenna, the CSI of openwifi's own transmitted signal reflects changes in the environment. Enable reception of the board's own signal (via sdrctl, register xpu 1), inject a stream of packets to sound the channel, and watch the CSI waterfall change as people or objects move.
CSI fuzzer
Inject a controlled artificial channel response at the transmitter so an eavesdropper's CSI-based sensing is corrupted while normal communication continues. Includes commands to sweep and apply fuzzer parameters and to watch the effect via self-monitoring.
IQ capture¶
Capture IQ sample, AGC gain, RSSI with many trigger conditions
Capture raw baseband IQ plus the AD9361 AGC gain/lock status and RSSI, windowed around any of 30+ trigger conditions. Also compares the FPGA's frequency-offset estimate against a Python calculation.
ACK timing verification by IQ capture
Trigger IQ capture on the ACK-send event to directly measure the Rx-ACK-GAP and Tx-ACK-GAP (the gap between the end of reception, or transmission, of a packet and the ACK leaving the board) against the ~16 µs SIFS across MCS and packet lengths.
Capture dual-antenna TX/RX IQ (collision capture and TX IQ)
Capture IQ from a second monitoring antenna coherently alongside the main antenna. Placed near a peer node, the monitoring antenna catches collisions (moments when both link ends transmit at once) via a dedicated collision trigger. The note also includes two quick starts for capturing the board's own TX IQ from inside the FPGA, one fired by a transmit-start trigger and one free-running.
Wi-Fi packet, CSI and IQ self-loopback test
Verify the TX→RX path end-to-end at the packet, CSI, and IQ level, either over the air (antennas close together) or entirely inside the FPGA. The FPGA-internal loopback provides a distortion-free "golden" reference.
Injection and fuzzing¶
802.11 packet injection and fuzzing
Build and use the inject_80211 tool to craft and transmit arbitrary 802.11 frames in monitor mode, control whether the FPGA generates ACKs, and run link-performance sweeps that are analyzed offline with analyze_80211.
owfuzz: a Wi-Fi protocol fuzzing tool (external)
A third-party 802.11 protocol fuzzer built on openwifi, with a published list of discovered vulnerabilities. Hosted outside the openwifi repos.
Standards background¶
IEEE 802.11n (Wi-Fi 4)
Background on the five 802.11n PHY improvements (more subcarriers, a higher FEC code rate (5/6), short guard interval, MIMO, 40 MHz) and frame aggregation, with a throughput derivation, and which parts openwifi implements: 52 subcarriers, 5/6 FEC, short GI, and experimental A-MPDU.
Counters and statistics¶
Access counter/statistics in FPGA
Read FPGA-level event counters directly: the openofdm_rx watchdog counters (abnormal-signal events) and the side-channel PHY RX/TX event counters (preamble detected, TX start/done, good-FCS frames addressed to the board, and more), all via register reads.
Access counter/statistics in driver
Enable, read, filter, and clear driver-level TX/RX statistics exposed through sysfs: per-packet success/fail counts, realtime MCS, AGC gain, per-peer filtering, and PER calculation.
Runtime control and dev workflow¶
Frequent tricks: Gain / Att / Frequency / CCA / LBT / CSMA / CW / Sensitivity
A cookbook of everyday runtime overrides: TX power and attenuation, RX gain, CCA/LBT threshold, NAV/DIFS/EIFS/CW, ACK and retransmission control, antenna selection, frequency restriction and arbitrary tuning, TX rate, and arbitrary IQ transmission.
Driver and FPGA dynamic reloading
Hot-reload the driver and/or FPGA bitstream on a running board with wgd.sh: no reboot, no power cycle, and keep several driver/FPGA variants side by side for quick switching.
FPGA¶
Build FPGA with High-Level Synthesis modules
Build the receiver's channel-estimation (ch_gain_cal) and equalizer (equalizer) stages from C++ via Vitis HLS instead of hand-written Verilog, which can speed up algorithm development. Based on an FCCM 2023 poster.
Remote access¶
Use openwifi on the w-iLab.t testbed remotely (external)
No hardware? The imec w-iLab.t testbed offers remote access to openwifi-ready boards, including JTAG boot instead of SD-card boot. Hosted on the imec documentation site.