Application Notes¶
openwifi ships application notes in openwifi/doc/app_notes/: short, task-focused guides for specific scenarios and modes. Their material appears across the thematic wiki pages, including Operating Modes, Research Features, and sdrctl. 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.
Links between two SDR boards¶
Two SDR boards in AP and client mode
Step-by-step for an access point and 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.
Two SDR boards in 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" uses a TX and an RX antenna to capture CSI from the board's own transmitted signal. Enable self-reception with sdrctl register xpu 1, then inject packets to sound the channel. 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, AD9361 AGC gain and lock status, and RSSI around any of 30+ trigger conditions. The note also compares the FPGA's frequency-offset estimate with a Python calculation.
ACK timing verification by IQ capture
Trigger IQ capture on the ACK-send event to measure the Rx-ACK-GAP and Tx-ACK-GAP directly, across MCS and packet lengths. Each gap runs from the end of a received or transmitted packet to the ACK leaving the board, and should be close to the 16 µs SIFS.
Dual-antenna IQ capture (collisions and own 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. The note also shows how to control whether the FPGA generates ACKs, and how to run link-performance sweeps 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 of 5/6, short guard interval, MIMO, 40 MHz) and on frame aggregation, with a throughput derivation. openwifi implements 52 subcarriers, 5/6 FEC, short GI, and experimental A-MPDU.
Counters and statistics¶
Counters and statistics in the FPGA
Read FPGA-level event counters from registers: the openofdm_rx watchdog counters for abnormal signals and the side-channel PHY RX and TX counters. The latter track events such as preamble detection, TX start and completion, and good-FCS frames addressed to the board.
Counters and statistics in the driver
Enable, read, filter, and clear driver-level TX and RX statistics exposed through sysfs. These include per-packet success and failure counts, real-time MCS, AGC gain, per-peer filtering, and PER calculation.
Runtime control and development workflow¶
Frequent runtime controls
A cookbook of runtime overrides for TX power and attenuation, RX gain, the CCA or LBT threshold, and timing controls such as NAV, DIFS, EIFS, and CW. It also covers ACK and retransmission control, antenna selection, frequency locking and arbitrary tuning, TX rate, and arbitrary IQ transmission.
Driver and FPGA dynamic reloading
Hot-reload the driver, the FPGA bitstream, or both on a running board with wgd.sh, without a reboot or power cycle. You can also keep several driver and FPGA variants side by side and switch between them quickly.
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.