open-sdr/openwifi: an SDR WiFi baseband design for Zynq and AD9361 boards

The problem openwifi solves: WiFi you can instrument down to the waveform

A commercial WiFi chipset gives you a network interface and nothing else. You cannot read the equalizer output, you cannot move the SIFS timing, and you cannot inject a malformed 802.11 frame from the PHY. openwifi exists for the cases where those things are the point: research on channel state information, radar sensing that shares the same radio, protocol fuzzing, and teaching how CSMA/CA actually behaves on air.

The project describes itself as a "Linux mac80211 compatible full-stack IEEE802.11/Wi-Fi design based on SDR". The split matters. This repository contains the Linux driver and the software. The FPGA design lives in a separate repository, openwifi-hw, and prebuilt images live in openwifi-hw-img. The audience is therefore narrow: people who own a Zynq board with an AD9361 front end, or one of the integrated boards listed in the README, and who are comfortable with an SD card, a serial console and an FPGA bitstream. Everyone else is better served by a normal radio.

Where the MAC and PHY actually run

The unusual part of the architecture is the division of labour. The low MAC, meaning DCF and CSMA/CA, runs in FPGA logic rather than in the Linux kernel. The README states that 10us SIFS is achieved this way. Above that, the design presents itself to Linux as an ordinary mac80211 device, so the driver in driver/ plugs into the standard wireless stack and modes such as Station, AP, Ad-hoc and Monitor come from mac80211 rather than from a bespoke networking layer.

The PHY supports 802.11a/g/n with 20MHz bandwidth, over a stated 70MHz to 6GHz frequency range. The README notes that bandwidth and frequency are easy to change, with 2MHz named for 802.11ah in sub-GHz bands and 10MHz for 802.11p in the 5.9GHz range. 802.11ax is not in this repository; the README points to openwifi.tech for it.

Two features explain why researchers pick this over a software PHY. The first is CSI: channel state information, frequency offset and equalizer output are pushed to the computer. The second is IQ capture, with real-time AGC and RSSI, in a single-antenna and a dual-antenna variant. Both are documented as application notes rather than as library calls, which tells you the intended workflow is measurement, not integration into a product.

Installing openwifi from the prebuilt SD image

The fastest path in the README is the prebuilt image, not a source build. You download the image, unzip it, and burn it to an SD card of at least 16GB. After burning, the card should show two partitions, BOOT and rootfs. The README names the 1.5.0 image file directly, so the version you get is tied to that release.

xz -d openwifi-1.5.0-shahecheng.img.xz

Write the resulting .img to the card with whatever flashing tool you normally use. Put the card in the board, boot it, and log in over the serial console or the network. The README then separates the remaining operations into their own short sections: Basic operations, Update FPGA, Update Driver, Update sdrctl and Update Misc Helpers. That structure is a hint about how the system is maintained in practice. The FPGA image, the kernel driver and the user-space control tool are updated independently, so a mismatch between them is a real failure mode rather than a theoretical one.

For OpenWRT there is a separate quick start under doc/img_build_instruction/openwrt/README.md, which covers bringing up an openwifi AP from a prebuilt OpenWRT image. If you would rather build the Linux image yourself, the repository also documents a from-scratch build and small Buildroot SD images under doc/img_build_instruction/buildroot/README.md. Expect the from-scratch route to involve the adi-linux and adi-linux-64 trees that sit at the top level of the repository.

Board support and the Vivado licence trap

The supported-platform table is the first thing to read, because it decides both your budget and your toolchain. Some entries are marked as needing a Vivado licence: zc706_fmcs2, adrv9361z7035 and zcu102_fmcs2. Others are explicitly marked as not needing one, including zed_fmcs2, adrv9364z7020, zc702_fmcs2, antsdr, e310v2, antsdr_e200 and sdrpi. The distinction is not cosmetic. If you pick a board from the first group, you are adding a proprietary FPGA toolchain licence to the cost of a board and an RF front end.

The list also mixes vendor boards with community hardware. neptunesdr and LibreSDR are described as low cost Zynq 7020 plus AD9361 boards and marked unofficial, with LibreSDR pointing at a separate repository maintained by a third party. The antsdr, e310v2, antsdr_e200 and sdrpi entries come from MicroPhase and HexSDR. Treat unofficial ports as a different support level: the openwifi README lists them, but the design files and any board-specific fixes are not necessarily maintained at the same cadence as the vendor boards.

If your board is not in the table, there is a porting guide, and the README explains that board_name identifies the FPGA design under openwifi-hw/boards/ and the FPGA image under openwifi-hw-img/boards. Porting is therefore a naming convention plus real FPGA work, not a configuration flag.

What openwifi will not do for you

The performance figures in the README are the clearest limitation. With aggregation on, the best case is 40 to 50Mbps TCP and 50Mbps UDP. That is far below what a cheap consumer AP delivers, and it is a consequence of doing the baseband in fabric on a small Zynq part with a single 20MHz channel. If your goal is throughput, this is the wrong tool and no amount of tuning will change the architecture.

Sensitivity is quoted as MCS0 at -92dBm and MCS7 at -73dBm with EVM of -38dB, measured on FMCOMMS2 at 2.4GHz over cable and over the air. Those are respectable numbers for the hardware class, but they are single-band measurements in a specific setup, and the README does not present a sweep across the 70MHz to 6GHz range. Do not assume the same sensitivity everywhere the radio can tune.

The README also carries a warning in bold: it is your responsibility to follow local spectrum regulation, or to use a cable, to avoid interference. That is not boilerplate. A board that can transmit at 70MHz and at 6GHz will happily transmit where it should not, and the project gives you the knobs (CCA threshold, receiver sensitivity, RTS/CTS duration, SIFS, DIFS, slot time, contention window) without a regulatory layer on top.

Finally, the 802.11ax feature set is not here. The README directs you to openwifi.tech for it, alongside a subscription offering. So the open repository is 802.11a/g/n plus the measurement and injection features, and the newer standard sits behind a commercial arrangement.

openwifi compared with srsRAN and with a plain SDR stack

The natural alternative for someone who wants a software-defined radio PHY is not another WiFi project but a software-defined PHY such as srsRAN, where the signal processing runs on the host CPU in C++ and the radio is a peripheral. The difference in approach is where the real-time constraint is met. srsRAN relies on CPU headroom and careful scheduling to hit its deadlines. openwifi moves the low MAC and PHY into FPGA fabric so that timing such as the 10us SIFS is a hardware property rather than a scheduling hope. That is why openwifi can claim a DCF implementation that behaves like a real 802.11 MAC, and why it is bound to specific Zynq plus AD9361 boards. You trade portability for determinism.

The other comparison the search data invites is openwifi against OpenWRT, and it is a category error worth clearing up. OpenWRT is a Linux distribution for routers. openwifi is a baseband and MAC design with a driver. They meet only in the OpenWRT quick start, where openwifi runs as an AP on top of an OpenWRT image. Choosing OpenWRT does not give you an SDR WiFi PHY; choosing openwifi does not give you a router firmware ecosystem. If you already have an OpenWRT device and want an access point, you need nothing from this repository.

A third option is a plain SDR toolkit with no 802.11 stack at all. You would write the framing, the contention logic and the timing yourself. openwifi's value is that all of that already exists and is compatible with mac80211, so tools like iperf and standard wireless utilities work against it.

Maintenance, versions and the AGPL-3.0 question

The last push to the default branch was on 2026-09-21, two days before this article, so the repository is being worked on. That is a statement about the repository, not a promise about any particular board or application note. The release history is uneven: v1.5.0 arrived on 2025-08-06, v1.4.0 on 2023-01-28 and v1.3.1 on 2022-05-16. There was roughly a two and a half year gap between v1.4.0 and v1.5.0. If your plan depends on tagged releases rather than on the master branch, budget for that cadence, and note that the prebuilt image named in the README is the 1.5.0 one.

Upgrade cost is spread across three artefacts. The README treats Update FPGA, Update Driver and Update sdrctl as separate procedures. A driver update without a matching FPGA image, or the reverse, is the kind of mismatch that produces confusing behaviour, and the repository keeps a known-issue file at doc/known_issue/notter.md for exactly this class of problem. Read it before you debug anything yourself.

The licensing is compound and worth stating plainly. The project's own code is AGPL-3.0, with a dual-licence arrangement: the README says to contact openwifi.tech for a non-open-source and advanced-feature licence. The README also warns that the project uses third-party modules and that it is the user's duty to check and follow those licences, pointing to Analog Devices' HDL licence as an example of compound conditions. If you intend to ship a product, the AGPL-3.0 terms and the third-party licences are the first thing to take to someone qualified to read them, not the last.

Editorial conclusion

Adopt openwifi if you already own a supported board, need to see or change WiFi at the MAC and PHY level, or want CSI and IQ samples in a controlled setup. Do not adopt it if you want a production access point, if 40 to 50 Mbps TCP is not enough, or if you cannot accept AGPL-3.0 on the software and a Vivado licence on some boards. Before buying hardware, check the board table, confirm whether your board needs a Vivado licence, and read doc/known_issue/notter.md.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. open-sdr/openwifi on GitHub
4. README
5. Releases