Skip to content

hostapd and wpa_supplicant

openwifi runs stock hostapd and wpa_supplicant, the same binaries Ubuntu or Debian install for any Wi-Fi card. Nothing in them knows that the radio underneath is an FPGA. That is the point of the design, and it is also the thing that trips people up: when a link fails to come up, it is rarely obvious whether the daemon, the kernel, the driver, or the PHY is at fault.

For the mode-by-mode command sequences, see Operating Modes.

What each daemon does

Both are user-space programs that implement the parts of 802.11 that are too slow, too stateful, or too policy-driven to belong in the kernel. They handle getting a link established. They do not carry your traffic.

hostapd wpa_supplicant
Role The access point The client (station)
Used in AP mode Client mode
Builds The beacon and probe-response contents Scan requests and connection attempts
Runs The authenticator half of the WPA handshake The supplicant half of the WPA handshake
Decides Which SSID, channel, rates, and capabilities to advertise Which network to join, and with which credentials

A daemon is busy for the first second or so of a connection and then goes quiet. If ping is slow or lossy on an associated link, the daemon is almost certainly not the cause. If association never completes, read the daemon's output first.

How they reach openwifi

They do not talk to openwifi, and they cannot. A daemon speaks the generic nl80211 netlink interface to cfg80211, cfg80211 drives mac80211, and mac80211 calls the openwifi driver through the ieee80211_ops callbacks. Only the last step touches openwifi-specific code.

nl80211 setup and teardown only sockets every data frame hostapd · wpa_supplicantassociation, keys, beacon contents your applicationping, iperf, a browser cfg80211 network stack (IP, sockets) mac80211 openwifi driver (sdr.ko)the only openwifi-specific part of this picture FPGA: low MAC and PHY
Two separate paths into mac80211. The daemons (left) use nl80211 and are active only while a link is being set up or torn down. Applications (right) use ordinary sockets, and their traffic reaches the driver without any daemon involvement. Everything above the driver box is generic Linux.

Four consequences follow from this.

You do not need an openwifi build of either daemon. apt-get install hostapd is what the SD image build does, and it is enough. The one exception is the 11b-suppressing wpa_supplicant described below, and that patch is about rate advertisement, not about openwifi.

The daemons cannot see or set openwifi's own settings. TX power, RX gain, CCA threshold, ACK behavior, and the FPGA registers are reached through a completely separate channel, sdrctl, which uses an nl80211 testmode command. See sdrctl and Runtime Control. So a config file never contains an openwifi register setting, and sdrctl never changes an SSID.

hostapd does not transmit beacons. It hands mac80211 the beacon contents, and mac80211 plus the driver put a beacon on the air on a timer. That is why the beacon check in the AP walkthrough watches the TX interrupt count in /proc/interrupts rather than anything hostapd prints.

Encryption runs in software. The driver implements no key-offload callback (there is no set_key in the callback table), so mac80211 does CCMP on the ARM cores. WPA2 works normally, but it costs processor time, so an encrypted link doesn't reach the throughput of an open one. When you are measuring peak throughput, test with security disabled.

The configuration files openwifi ships

These live in the openwifi directory on the board, next to wgd.sh and fosdem.sh. They are ordinary hostapd and wpa_supplicant config files with no openwifi-specific syntax, so any hostapd or wpa_supplicant documentation applies to them directly.

File Used by Purpose
hostapd-openwifi.conf fosdem.sh The demo AP: SSID, channel, band, rates, security
wpa-openwifi.conf wpa_supplicant -c Joining an openwifi AP
wpa-connect.conf wpa_supplicant -c Joining some other network, so edit this one for your home or lab AP

fosdem.sh starts hostapd with hostapd-openwifi.conf and adds a DHCP server and a demo webserver on top. fosdem-11ag.sh is the same thing forced to legacy 802.11a/g. Neither script does anything to hostapd that you could not do by hand.

Check the shipped files on your own board before assuming defaults. They change between releases, and the wiki is not the source of truth for their contents.

When you have to edit them

Most openwifi work never touches these files. These are the cases that do.

Changing channel or band. The demo defaults to channel 36 in 5 GHz. A 2.4 GHz-only client cannot see it. Edit the channel and hw_mode in hostapd-openwifi.conf and re-run fosdem.sh. This is the single most common edit, and it is called out in Getting Started for that reason.

Turning security on or off. Standard hostapd wpa / wpa_passphrase / wpa_key_mgmt settings, matched by psk and key_mgmt on the client side. A minimal WPA2 stanza for hostapd-openwifi.conf:

wpa=2
wpa_passphrase=yourpassphrase
wpa_key_mgmt=WPA-PSK
rsn_pairwise=CCMP

The client-side wpa_supplicant config carries the matching psk and key_mgmt fields. Worth disabling when you are benchmarking, for the software-crypto reason above.

Suppressing 802.11b rates. openwifi is OFDM-only and cannot do the 11b (DSSS) rates that 2.4 GHz devices often fall back to for beacons and management frames. The shipped hostapd-openwifi.conf already handles the AP side with supported_rates and basic_rates. The client side is harder, because an unmodified wpa_supplicant gives you no way to suppress 11b rates in 2.4 GHz, so openwifi ships a patched build. Run this on the client machine:

sudo apt-get install libssl-dev    # Ubuntu 20.04 and later. On 18.04 the package is libssl1.0-dev
cd openwifi/user_space
./build_wpa_supplicant_wo11b.sh

Staying in 5 GHz avoids the whole problem, which is why the demo defaults to a 5 GHz channel. The full explanation is in About 802.11b.

Forcing legacy 802.11a/g. Use fosdem-11ag.sh, or set ieee80211n=0 in the hostapd config yourself. Useful when you are trying to tell an 11n problem apart from an RF problem. The 11n side is covered in Wi-Fi 4 and Wi-Fi 6 Features.

A-MPDU aggregation is not a hostapd setting. It is enabled when the driver loads, with ./wgd.sh 1. See Turning on A-MPDU aggregation.

Run the daemon in the foreground with verbose output. This is the fastest way to find out whether the problem is above or below the daemon:

wpa_supplicant -dd -i sdr0 -c wpa-openwifi.conf     # client
hostapd -dd hostapd-openwifi.conf                    # AP, instead of fosdem.sh

Read the output against these three cases.

  • Nothing appears in a scan. The daemon is fine and the problem is below it. Either the AP is not beaconing, or the receiver is not hearing it. Check the AP's TX interrupt count, then antennas and distance, then receiver sensitivity and gain.
  • Authentication or association is attempted and times out. Frames are going out but nothing usable is coming back. In 2.4 GHz, suspect the 11b problem first. Otherwise treat it as a link-quality problem.
  • Association completes and then the link drops or gives no IP. The daemons did their job. Go to Client and link problems in Troubleshooting, starting with the DHCP server.

If a config file sets ctrl_interface, you can also attach wpa_cli or hostapd_cli to a running daemon to inspect state and issue commands without restarting it. For example, wpa_cli -i sdr0 status prints the association state of a running supplicant.

Two openwifi-specific traps: reloading the driver destroys and recreates sdr0, so any daemon that was running is now attached to nothing and has to be restarted, as noted in the driver iteration loop. And NetworkManager fights wpa_supplicant for control of the interface, which is why the client walkthrough starts with service network-manager stop.

For anything below the daemon, the driver's own logging is on the Troubleshooting page.