How to Build a Raspberry Pi Wi-Fi AP Using NetworkManager

If you are trying to set up a raspberry pi wifi ap on modern Raspberry Pi OS (Bookworm or newer), forget the outdated tutorials that tell you to manually edit hostapd.conf and dnsmasq.conf. The Raspberry Pi Foundation has fully transitioned to NetworkManager as the default networking stack. Trying to force legacy dhcpcd and hostapd services to run in parallel with NetworkManager is the number one cause of boot-looping and interface conflicts in 2026.

The direct answer: You can provision a fully routed, NAT-enabled Wi-Fi Access Point using exactly four nmcli commands. NetworkManager's shared IPv4 method automatically handles the DHCP server and IP masquerading, eliminating the need for manual iptables rules in most standard setups. This guide targets the Raspberry Pi 5 (8GB) running Raspberry Pi OS Bookworm (64-bit), but the exact same nmcli syntax applies to the Pi 4 Model B and Zero 2 W.

Hardware Requirements & Power Budget for AP Mode

Running a Wi-Fi radio in Access Point (AP) mode requires significantly more transmit power than operating in client (station) mode. The Pi must constantly beacon and handle multiple client associations, which causes current spikes that will brown out a marginal power supply, silently resetting the Wi-Fi chip.

Parts List

• Board: Raspberry Pi 5 (8GB RAM) or Raspberry Pi 4 Model B (4GB+)
• Power Supply: Official Raspberry Pi 27W USB-C PD Power Supply (for Pi 5) or 15W USB-C (for Pi 4)
• Storage: 32GB+ NVMe SSD via PCIe HAT (recommended for logging) or SanDisk Extreme A2 microSD
• Uplink: Cat6 Ethernet patch cable to your main router/switch
• Status LED: Standard 5mm LED with a 220Ω current-limiting resistor

Wi-Fi Chipset & Power Specifications

Note: The "Max AP Clients" is a practical thermal and RAM limit for stable IoT traffic, not a hard firmware limit. For high-density client loads, use a dedicated Ubiquiti or TP-Link Omada AP and let the Pi handle routing/captive portals.

Pin Mapping: Hardware Status & Watchdog

When deploying a Pi as a headless network appliance, you need physical feedback and a way to recover from kernel panics without pulling the plug (which corrupts the filesystem). We map a status LED to indicate AP broadcast state, and a physical button to trigger a clean reboot via the GPIO.

Step-by-Step: Provisioning the AP via nmcli

The following bash script configures the wlan0 interface as an Access Point, sets WPA2/WPA3 security, and enables IPv4 sharing (which automatically spins up a DHCP server and NAT routing for connected clients). Save this as setup_ap.sh.

#!/bin/bash
# Raspberry Pi Wi-Fi AP Setup via NetworkManager
# Targets: Raspberry Pi OS Bookworm (64-bit)
set -euo pipefail

AP_NAME="FluxNet-AP"
AP_PASS="super_secret_password_123"
IFACE="wlan0"

echo "[1/5] Verifying NetworkManager is active..."
if ! systemctl is-active --quiet NetworkManager; then
    echo "ERROR: NetworkManager is not running. Enable it via 'sudo systemctl enable --now NetworkManager'"
    exit 1
fi

echo "[2/5] Unblocking RF kill switches..."
sudo rfkill unblock wifi

echo "[3/5] Deleting existing AP connection if it exists..."
sudo nmcli connection delete "$AP_NAME" 2>/dev/null || true

echo "[4/5] Creating Wi-Fi AP connection..."
sudo nmcli connection add type wifi ifname "$IFACE" con-name "$AP_NAME" autoconnect yes ssid "$AP_NAME"

# Modify connection: set AP mode, 2.4GHz band (bg), shared IPv4 (DHCP+NAT), and WPA security
sudo nmcli connection modify "$AP_NAME" \
    802-11-wireless.mode ap \
    802-11-wireless.band bg \
    ipv4.method shared \
    ipv4.addresses 192.168.4.1/24 \
    wifi-sec.key-mgmt wpa-psk \
    wifi-sec.psk "$AP_PASS"

echo "[5/5] Activating connection..."
if sudo nmcli connection up "$AP_NAME"; then
    echo "SUCCESS: $AP_NAME is now broadcasting on $IFACE."
    # Turn on Status LED (GPIO 17)
    echo 17 | sudo tee /sys/class/gpio/export 2>/dev/null || true
    echo out | sudo tee /sys/class/gpio/gpio17/direction >/dev/null
    echo 1 | sudo tee /sys/class/gpio/gpio17/value >/dev/null
else
    echo "ERROR: Failed to bring up $AP_NAME. Check 'journalctl -u NetworkManager' for details."
    exit 1
fi

Debugging: Exact Errors and Ranked Causes

When a raspberry pi wifi ap fails to start, the terminal output can be cryptic. Before tearing down your config, check these first three things:

1. Is the interface blocked? Run rfkill list. If wlan0 shows "Soft blocked: yes", run sudo rfkill unblock wifi.
2. Is NetworkManager managing the device? Run nmcli device status. If wlan0 says unmanaged, another service (like legacy dhcpcd or wpa_supplicant) is holding it. Disable them via sudo systemctl disable dhcpcd wpa_supplicant.
3. Are you browning out? Run dmesg | grep -i voltage. If you see "Under-voltage detected", your power supply is failing under the AP transmit load.

Error: "The device's driver does not support AP mode"

Exact String: Error: Connection activation failed: (53) The device's driver does not support AP mode.

Ranked Causes:

1. USB Dongle Firmware Missing: You are using a USB Wi-Fi adapter (like the RTL8812AU) that requires out-of-tree drivers. The kernel loaded the station-mode driver, but the AP-mode firmware blob is missing. Fix: Install the specific dkms driver for your chipset.
2. 5GHz DFS Restrictions: You forced 802-11-wireless.band a (5GHz) without configuring the correct regulatory domain. The kernel blocks AP mode on DFS channels until a radar check completes. Fix: Switch to band bg (2.4GHz) or set wifi-sec.pmf and country code explicitly.

Error: "Connection is not available on the device"

Exact String: Error: Connection 'FluxNet-AP' is not available on the device wlan0 at this time.

Ranked Causes:

1. Interface Name Mismatch: On some USB setups, the interface isn't wlan0; it might be wlx00c0ca812345. Fix: Run iw dev to find the exact interface name and update the script's IFACE variable.
2. NetworkManager State File Corruption: NM's internal state machine is stuck. Fix: Run sudo rm /var/lib/NetworkManager/NetworkManager.state && sudo systemctl restart NetworkManager.

Extending or Simplifying the Build

Simplifying: Standalone Offline AP

If you are building an offline IoT sensor hub (e.g., a local MQTT broker for ESP32 nodes) and do not need internet routing, change the IPv4 method from shared to manual. This prevents NetworkManager from trying to configure NAT and firewall rules, reducing boot time and CPU overhead.

sudo nmcli connection modify "FluxNet-AP" ipv4.method manual ipv4.addresses 10.10.0.1/24

Extending: Adding a Captive Portal

To turn this AP into a guest network with a captive portal (like a hotel Wi-Fi), you will need to bypass NetworkManager's built-in DHCP and use dnsmasq to handle DNS hijacking. Set ipv4.method manual in NM, install dnsmasq and nginx, and configure dnsmasq to resolve all DNS queries to the Pi's local IP address. For production captive portals in 2026, look into openNDS, which integrates cleanly with modern Linux firewall stacks.

For deeper reading on Raspberry Pi networking transitions, refer to the official Raspberry Pi OS configuration documentation and the NetworkManager nmcli reference manual.