Raspberry Pi as Access Point: Bookworm NetworkManager Setup & Debugging

If you are trying to configure a raspberry pi as access point using tutorials written before late 2023, you are going to hit a wall. The shift to Raspberry Pi OS "Bookworm" completely replaced the legacy dhcpcd and wpa_supplicant stack with NetworkManager. Attempting to force the old hostapd and dnsmasq manual configurations on a modern Pi 5 or Pi 4 will result in service conflicts, dropped packets, and boot loops.

The direct answer for a stable, modern Pi AP is to use nmcli (NetworkManager Command Line Interface) to create a shared Wi-Fi connection. This natively handles the DHCP server, NAT routing, and WPA2/WPA3 security without requiring third-party daemon management. This guide targets the Raspberry Pi 5 (8GB) and Raspberry Pi 4 Model B running Raspberry Pi OS Bookworm (64-bit).

Hardware & RF Interface Specifications

Before writing configuration scripts, you must verify your hardware's RF capabilities and power delivery. The Wi-Fi chip on the Pi 5 is a significant upgrade over the Pi 4, but it is also more susceptible to voltage brownouts if the power supply is undersized. Below is the data-dense specification matrix for current board variants.

GPIO Pin Mapping for AP Hardware Control

While the internal Wi-Fi antenna does not use GPIO pins, a robust embedded access point deployed in the field needs hardware-level status indication and a physical reset mechanism to clear NetworkManager state without SSH access. Wire these components to the 40-pin header:

Step-by-Step NetworkManager AP Configuration

Forget editing /etc/hostapd/hostapd.conf. We will use nmcli to spin up a shared connection. This method automatically configures dnsmasq under the hood to hand out IP addresses to connected clients.

Below is the complete, compilable bash script to configure the AP, including interface validation and error handling. Save this as setup_ap.sh, make it executable (chmod +x setup_ap.sh), and run it with sudo.

#!/bin/bash
# Raspberry Pi Access Point Setup via NetworkManager (Bookworm)
# Target: Raspberry Pi 5 / Pi 4 (wlan0)
set -euo pipefail

IFACE="wlan0"
SSID="FluxNet_5G"
PASSWORD="SuperSecret123!"
IP_ADDR="192.168.50.1/24"
CON_NAME="Pi_AP_Shared"

# 1. Verify NetworkManager is active
if ! systemctl is-active --quiet NetworkManager; then
    echo "[ERROR] NetworkManager is not running. This script requires Pi OS Bookworm."
    exit 1
fi

# 2. Verify wlan0 exists and is not hard-blocked
if ! ip link show "$IFACE" > /dev/null 2>&1; then
    echo "[ERROR] Interface $IFACE not found. Check hardware connections."
    exit 1
fi

if rfkill list wifi | grep -q "Soft blocked: yes"; then
    echo "[WARN] Wi-Fi is soft blocked. Unblocking..."
    rfkill unblock wifi
fi

# 3. Remove existing AP connection if it exists to prevent duplicates
nmcli connection delete "$CON_NAME" > /dev/null 2>&1 || true

# 4. Create the Shared Wi-Fi Access Point
echo "[INFO] Creating Access Point '$SSID' on $IFACE..."
nmcli connection add type wifi ifname "$IFACE" con-name "$CON_NAME" \
    autoconnect yes ssid "$SSID" mode ap \
    ipv4.method shared ipv4.addresses "$IP_ADDR" \
    wifi-sec.key-mgmt wpa-psk wifi-sec.psk "$PASSWORD" \
    802-11-wireless.band a 802-11-wireless.channel 36

# 5. Bring up the connection
nmcli connection up "$CON_NAME"

echo "[SUCCESS] Access Point is live. Connect clients to $SSID."
echo "[INFO] Gateway IP: 192.168.50.1"

# 6. Trigger GPIO 18 Status LED (Requires WiringPi or gpioset)
if command -v gpioset > /dev/null; then
    gpioset -m time -s 1 18=1 2>/dev/null || echo "[WARN] Could not set GPIO 18 high."
fi

What this script does:
The ipv4.method shared flag is the magic parameter. It tells NetworkManager to assign the specified static IP to wlan0, start a localized DHCP server for that subnet, and configure iptables to masquerade (NAT) traffic out to the Pi's primary internet connection (usually eth0). The 802-11-wireless.band a forces the 5GHz band, avoiding the noisy 2.4GHz spectrum.

Debugging: Exact Errors and the "First Three" Checks

When building embedded networks, things fail. Here is how to debug the specific errors that plague Pi AP setups, starting with the mandatory triage checklist.

The First Three Things to Check When It Fails

1. RFKill State: Run rfkill list. If Wi-Fi is "Hard blocked: yes", your power supply is likely failing to initialize the radio, or you have a physical hardware switch fault (rare on Pi, common on USB dongles).
2. NetworkManager Radio State: Run nmcli radio wifi. If it returns disabled, NetworkManager has soft-turned off the radio. Fix it with nmcli radio wifi on.
3. Power Supply Brownout: Run vcgencmd get_throttled. If you see 0x50005 or similar undervoltage flags, the Pi 5 is starving. The Wi-Fi chip is the first peripheral to drop offline during a brownout. Upgrade to the official 27W PD supply.

Ranked Causes for Exact Error Strings

Error 1: Error: Connection activation failed: (2) Active connection removed before it was initialized.

• Cause A (Most Likely): You specified a 5GHz channel (like 36 or 149) but your regulatory domain (iw reg get) is set to a country that restricts that channel, or the Pi hasn't pulled the correct country code from the EEPROM. Fix: Set the country code via sudo raspi-config (Localization Options > WLAN Country) and reboot.
• Cause B: Another process (like a lingering hostapd service from an old tutorial) is holding the wlan0 interface lock. Fix: sudo systemctl stop hostapd and sudo systemctl disable hostapd.

Error 2: hostapd: wlan0: Could not connect to kernel driver.

• Cause (The Legacy Trap): You are trying to run a manual hostapd config file on Bookworm. NetworkManager owns the wlan0 interface via wpa_supplicant and iwd. hostapd cannot claim the socket. Fix: Abandon the manual hostapd method and use the nmcli script provided above.

Error 3: Warning: password has only 7 characters, minimum 8 required.

• Cause: WPA2-PSK strictly requires a minimum of 8 ASCII characters. Fix: Update the wifi-sec.psk parameter in your nmcli command.

Extending to a Bridge vs. Simplifying the Build

Depending on your deployment environment, you may need to alter the network topology or streamline the manufacturing process for multiple units.

How to Extend: Bridging Ethernet to Wi-Fi

The script above creates a NAT Router (clients are on a separate 192.168.50.x subnet). If you want the Pi to act as a transparent Wireless Bridge (clients get IP addresses from your main home router's DHCP server and appear on the same LAN), you must change the IPv4 method.

Instead of ipv4.method shared, you create a bridge interface:

# Create a bridge
nmcli connection add type bridge con-name br0 ifname br0 ipv4.method auto
# Add ethernet to the bridge
nmcli connection add type bridge-slave con-name br0-eth0 ifname eth0 master br0
# Add Wi-Fi AP to the bridge (Requires specific kernel support, can be flaky on Pi)
nmcli connection add type wifi ifname wlan0 con-name Pi_AP_Bridge mode ap ssid "BridgeNet" wifi-sec.key-mgmt wpa-psk wifi-sec.psk "Password123" master br0

Warning: The Pi's internal Wi-Fi chip does not officially support 4-address (WDS) bridging in all driver revisions. If bridging fails, stick to the NAT "shared" method and add static routes on your main router.

How to Simplify: Headless Fleet Deployment

If you are flashing 20 Pis for a remote sensor network, running the bash script manually on each is inefficient. Simplify the build by leveraging the Raspberry Pi Imager OS Customisation settings (Ctrl+Shift+X). While the Imager cannot natively configure "AP Mode" via the GUI, it can pre-configure your SSH keys, hostname, and connect to a temporary staging Wi-Fi network.

Once the Pi boots and connects to your staging network, use a tool like Ansible or a simple SSH loop to push the setup_ap.sh script and execute it remotely. After execution, the Pi will drop the staging connection and broadcast its own AP network, ready for field deployment.

For deeper reading on the underlying network stack changes, refer to the official Raspberry Pi NetworkManager documentation and the NetworkManager nmcli reference.