Building a Raspberry Pi as a Wireless Access Point: hostapd & dnsmasq Setup

Configuring a Raspberry Pi as a wireless access point requires bridging the Ethernet interface (eth0) to the Wi-Fi interface (wlan0) using hostapd for the access point daemon and dnsmasq for DHCP and DNS forwarding. While modern Raspberry Pi OS versions lean heavily on NetworkManager, building a standalone routed access point with dedicated daemons provides superior control over RF channels, client isolation, and lease management for embedded deployments.

This guide targets the Raspberry Pi 4 Model B (4GB variant). The Pi 4B's Cypress CYW43455 Wi-Fi chip handles concurrent AP and managed modes more reliably than the Pi 3B+, and unlike the Pi 5, it has a vast, validated thermal profile for continuous 24/7 RF transmission without active cooling when paired with a passive aluminum case.

Parts List & Build Specifications

Pin Mapping: Adding an I2C Status Display

Headless access points are frustrating to debug when they drop offline. Instead of SSHing in to check client leases, we wire an SSD1306 I2C OLED to display the active IP and connected client count. This utilizes the Pi's hardware I2C bus.

Step-by-Step: hostapd and dnsmasq Configuration

Ensure you are running Raspberry Pi OS (Legacy/Bullseye) or have explicitly enabled dhcpcd on Bookworm via sudo raspi-config (Advanced Options > Network Config > dhcpcd). NetworkManager's default Wi-Fi handling will conflict with raw hostapd.

1. Install Dependencies:
   sudo apt update && sudo apt install hostapd dnsmasq tcpdump
2. Set a Static IP for wlan0:
   Edit /etc/dhcpcd.conf and append:
   

   interface wlan0
   static ip_address=192.168.4.1/24
   nohook wpa_supplicant

   The nohook directive is critical; it prevents wpa_supplicant from taking control of the interface.
3. Configure dnsmasq (DHCP/DNS):
   Backup the default file and create a new /etc/dnsmasq.conf:
   

   interface=wlan0
   dhcp-range=192.168.4.10,192.168.4.100,255.255.255.0,24h
   dhcp-option=3,192.168.4.1
   dhcp-option=6,192.168.4.1
   server=1.1.1.1

4. Configure hostapd (The AP Daemon):
   Create /etc/hostapd/hostapd.conf:
   

   interface=wlan0
   driver=nl80211
   ssid=FluxNet_Lab
   hw_mode=g
   channel=6
   ieee80211n=1
   wmm_enabled=1
   macaddr_acl=0
   auth_algs=1
   ignore_broadcast_ssid=0
   wpa=2
   wpa_passphrase=BenchTest123!
   wpa_key_mgmt=WPA-PSK
   rsn_pairwise=CCMP
   country_code=US

   Note: hw_mode=g locks the Pi to 2.4GHz. The Pi 4's 5GHz implementation requires DFS channel management which frequently drops clients in embedded environments. Stick to 2.4GHz channel 1, 6, or 11 for stability.
5. Enable IP Forwarding:
   Uncomment net.ipv4.ip_forward=1 in /etc/sysctl.conf. Then add the NAT routing rule:
   sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
   Save the rules with sudo sh -c "iptables-save > /etc/iptables.ipv4.nat" and load them on boot via /etc/rc.local.
6. Unmask and Start Services:
   sudo systemctl unmask hostapd
sudo systemctl enable hostapd dnsmasq
sudo systemctl start hostapd dnsmasq

For deeper protocol tuning, refer to the hostapd official project documentation and the dnsmasq manual.

Python Status Monitor & Error Handling

With the hardware wired and the AP broadcasting, deploy this Python script to read the dnsmasq lease file and render the client count on the I2C OLED. Install the Adafruit Blinka and SSD1306 libraries first: pip3 install adafruit-blinka adafruit-circuitpython-ssd1306.

import time
import board
import busio
import adafruit_ssd1306

# Pin Definitions:
# SDA = Pi Pin 3 (GPIO 2)
# SCL = Pi Pin 5 (GPIO 3)
# Hardware I2C is handled automatically by board.I2C()

LEASE_FILE = '/var/lib/misc/dnsmasq.leases'
I2C_ADDRESS = 0x3C

def get_client_count():
    """Parses the dnsmasq lease file to count active DHCP clients."""
    try:
        with open(LEASE_FILE, 'r') as f:
            # Each active lease is a single line in the file
            return len(f.readlines())
    except FileNotFoundError:
        return 0
    except PermissionError:
        print("Error: Script must be run with sudo to read lease file.")
        return -1

def main():
    try:
        i2c = busio.I2C(board.SCL, board.SDA)
        oled = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c, addr=I2C_ADDRESS)
    except (ValueError, RuntimeError) as e:
        print(f"I2C Initialization failed. Check wiring on Pins 3 & 5. Error: {e}")
        exit(1)

    oled.fill(0)
    oled.show()
    oled.text('FluxAP Online', 0, 0, 1)
    oled.text('192.168.4.1', 0, 50, 1)
    oled.show()
    time.sleep(2)

    while True:
        clients = get_client_count()
        oled.fill(0)
        oled.text('FluxAP Online', 0, 0, 1)
        oled.text(f'Clients: {clients}', 0, 20, 1, font_name='font11')
        oled.text('192.168.4.1', 0, 50, 1)
        oled.show()
        time.sleep(5)

if __name__ == '__main__':
    try:
        main()
    except KeyboardInterrupt:
        print("Monitor stopped by user.")

Debugging: "nl80211: Could not configure driver mode"

When running sudo systemctl status hostapd, the most common failure on a Raspberry Pi yields this exact error string in the journal:

nl80211: Could not configure driver mode
wlan0: interface state UNINITIALIZED->DISABLED
hostapd_free_hapd_data: Interface wlan0 wasn't started

This means the kernel's nl80211 subsystem rejected the request to put the Wi-Fi chip into AP mode because another process already holds a lock on the interface.

The First Three Things to Check When It Fails

1. Is wpa_supplicant still running? Even with the nohook directive in dhcpcd.conf, the wpa_supplicant service might be active. Kill it and disable it:
   sudo systemctl stop wpa_supplicant
sudo systemctl disable wpa_supplicant
2. Is the Country Code set correctly? If country_code=US is missing from hostapd.conf, the kernel blocks AP initialization to prevent illegal RF transmission on DFS (Dynamic Frequency Selection) channels. Add the country code and reboot.
3. Is wlan0 assigned an IP before hostapd starts? hostapd will fail to bind if the interface is down. Ensure dhcpcd has assigned 192.168.4.1 by running ip addr show wlan0. If it's missing, restart dhcpcd: sudo systemctl restart dhcpcd.

For broader OS-level networking context, consult the Raspberry Pi Official Configuration Documentation.

Extending or Simplifying the Build

To Simplify: If you don't need granular control over DHCP options or RF parameters, bypass hostapd entirely and use NetworkManager's built-in hotspot feature. You can spin up a basic WPA2 AP in one command:
sudo nmcli con add type wifi ifname wlan0 con-name Hotspot autoconnect yes ssid MySimpleAP
sudo nmcli con modify Hotspot 802-11-wireless.mode ap 802-11-wireless.band bg ipv4.method shared
sudo nmcli con modify Hotspot wifi-sec.key-mgmt wpa-psk wifi-sec.psk "password123"
sudo nmcli con up Hotspot

To Extend: For public-facing deployments (like a guest network or field kiosk), integrate Nodogsplash to create a captive portal. Nodogsplash intercepts HTTP traffic on port 80 and forces clients to click a "Connect" button on a local web page before granting internet access via iptables MAC address whitelisting. Alternatively, add a hardware watchdog via the Pi's built-in BCM2835 watchdog timer to automatically reboot the board if the hostapd process hangs.

Frequently Asked Questions

Can I use a Raspberry Pi as a wireless access point without an Ethernet cable?

Yes, this is known as a "Wi-Fi repeater" or "bridge" mode. However, the Raspberry Pi 4's internal Wi-Fi chip is a single-chain 1x1 MIMO radio. If you use the same wlan0 interface to connect to an upstream router (managed mode) while simultaneously broadcasting an AP (master mode), the chip must time-slice between the two tasks. This halves your throughput and significantly increases latency. For a repeater setup, plug a USB Wi-Fi adapter (like an Alfa AWUS036ACH) into the Pi and use wlan1 for the upstream connection and wlan0 for the AP broadcast.

How many clients can a Raspberry Pi wireless access point handle simultaneously?

The Cypress CYW43455 chip technically supports up to 32 associated MAC addresses in AP mode. In practice, the bottleneck is the CPU's ability to handle NAT routing and the chip's limited RAM for beacon frames. For general web browsing and IoT telemetry, expect stable performance with 10 to 15 active clients. Beyond 15 clients, you will notice severe DHCP lease delays and increased packet loss unless you offload routing to a dedicated edge router and use the Pi strictly as a dumb bridge.

Why is my Raspberry Pi access point dropping 5GHz connections?

The 5GHz band requires DFS (Dynamic Frequency Selection) compliance to avoid interfering with military and weather radar. If your hostapd.conf selects a DFS channel (like 52-64 or 100-144) and the Pi detects radar pulses, it will immediately shut down the AP and jump to a new channel, dropping all clients. To fix this, hardcode a non-DFS channel in your config: use channel=36, 40, 44, or 48, and ensure hw_mode=a is set.