The Paradigm Shift: NetworkManager vs. wpa_supplicant

If you have searched for tutorials on how to connect a Raspberry Pi to WiFi, you have likely encountered outdated advice. For years, the standard method involved editing the /etc/wpa_supplicant/wpa_supplicant.conf file and relying on dhcpcd for IP assignment. However, with the release of Raspberry Pi OS Bookworm (and continuing into 2026), the Raspberry Pi Foundation fundamentally changed the networking stack.

Modern Raspberry Pi OS distributions now use NetworkManager as the default network configuration tool. The legacy wpa_supplicant method will fail on a fully updated Pi 4, Pi 5, or Pi Zero 2 W running Bookworm. Understanding this shift is critical for anyone setting up headless Home Assistant nodes, IoT sensors, or media centers. In this comprehensive setup guide, we will cover the modern nmcli approach, headless pre-configuration, and legacy fallbacks, alongside crucial IoT stability tweaks.

Method 1: Headless Pre-Configuration via Raspberry Pi Imager

The most reliable way to connect a Raspberry Pi to WiFi—especially for headless setups where you do not have a monitor or keyboard attached—is to inject the WiFi credentials before you even flash the SD card. The official Raspberry Pi Imager features a hidden OS Customization menu that handles this perfectly.

  1. Open Raspberry Pi Imager and select your target hardware (e.g., Raspberry Pi 5) and OS (Raspberry Pi OS Lite 64-bit).
  2. Press Ctrl+Shift+X (or click the gear icon) to open the OS Customization menu.
  3. Check the box for Configure Wireless LAN.
  4. Enter your exact SSID and Password. Pay strict attention to case sensitivity.
  5. Select your Wireless LAN Country. This is not just a formality; the 5GHz spectrum is heavily regulated, and omitting the country code will force the Pi to disable 5GHz WiFi entirely to comply with international RF laws.
  6. Enable SSH (using password or key-based authentication) under the Services tab.

When the Pi boots for the first time, NetworkManager will automatically read these injected credentials and establish a connection within seconds.

Method 2: Command Line Setup Using nmcli (Modern OS)

If your Pi is already running Raspberry Pi OS Bookworm or newer, and you are connected via a temporary Ethernet cable or a serial console, you will use nmcli (NetworkManager Command Line Interface) to configure WiFi. This is the modern, robust standard for Linux networking.

Scanning for Available Networks

First, ensure your wireless interface (usually wlan0) is active and scan for local networks:

nmcli device wifi rescan
nmcli device wifi list

This will output a table of available SSIDs, their signal strength (bars), channels, and security protocols (WPA2/WPA3).

Connecting to the Network

To connect to a standard WPA2/WPA3 network, use the following syntax:

sudo nmcli device wifi connect "Your_SSID_Name" password "Your_Secure_Password"

If you are connecting to a hidden network, you must append the hidden yes flag:

sudo nmcli device wifi connect "Hidden_SSID" password "Password" hidden yes

Essential nmcli WiFi Commands

Action nmcli Command
Show active connections nmcli connection show --active
Delete a saved WiFi profile sudo nmcli connection delete "SSID_Name"
Disconnect from WiFi nmcli device disconnect wlan0
Re-enable WiFi radio nmcli radio wifi on
View saved WiFi passwords sudo nmcli connection show "SSID_Name" | grep psk

Method 3: The raspi-config Interactive Menu

For users who prefer a terminal-based GUI over raw commands, the native configuration tool still interfaces correctly with NetworkManager on modern OS builds.

  1. Launch the tool by typing sudo raspi-config in the terminal.
  2. Navigate to System Options > Wireless LAN.
  3. Enter your SSID and passphrase when prompted.

Under the hood, raspi-config generates the appropriate NetworkManager profiles, making this a safe and user-friendly bridge between legacy habits and modern architecture.

Method 4: Legacy wpa_supplicant (Bullseye & Older)

If you are maintaining an older fleet of devices running Raspberry Pi OS Bullseye or Buster, or using a highly customized minimal image that lacks NetworkManager, you must use the legacy wpa_supplicant method. According to the Raspberry Pi NetworkManager Documentation, this method is deprecated on Bookworm but remains relevant for legacy maintenance.

Generate a secure, hashed passphrase block using:

wpa_passphrase "Your_SSID" "Your_Password"

Copy the resulting output and paste it into /etc/wpa_supplicant/wpa_supplicant.conf. You must also ensure the country code is set at the top of the file (e.g., country=US) to unlock the correct RF channels.

Critical Troubleshooting & IoT Stability Tweaks

Connecting to WiFi is only half the battle. For DIY smart home hubs, Home Assistant servers, and remote environmental sensors, WiFi stability is paramount. The Raspberry Pi's default WiFi configuration prioritizes battery/power saving over latency and persistent connections, which can cause nodes to drop off the network randomly.

Disabling WiFi Power Save Mode

By default, the Pi's WiFi chip enters a low-power sleep state during idle periods. This causes ping spikes, dropped SSH sessions, and missed MQTT payloads. To disable power management via NetworkManager, identify your connection name and modify the profile:

# Find your connection name
nmcli connection show

# Disable power save (2 = disable, 1 = enable)
sudo nmcli connection modify "Your_SSID_Name" 802-11-wireless.powersave 2
sudo nmcli connection up "Your_SSID_Name"

This single tweak is the most effective way to stabilize a Pi-based Home Assistant node connected over WiFi.

Regulatory Domain and 5GHz Blockages

If your Pi refuses to connect to a 5GHz network, or the network does not appear in your scan results, the regulatory domain is likely unset or incorrect. The NetworkManager project enforces strict compliance with local RF laws. You can manually verify and force the regulatory domain using the iw tool:

sudo iw reg set US
iw reg get

Replace US with your actual ISO 3166-1 alpha-2 country code. Reboot the Pi to allow the WiFi firmware to reload the correct channel tables.

Assigning a Static IP via nmcli

DHCP leases can expire or change, breaking port forwarding and local DNS records. Assign a static IP directly within the NetworkManager profile:

sudo nmcli connection modify "Your_SSID_Name" ipv4.addresses 192.168.1.50/24
sudo nmcli connection modify "Your_SSID_Name" ipv4.gateway 192.168.1.1
sudo nmcli connection modify "Your_SSID_Name" ipv4.dns "1.1.1.1,8.8.8.8"
sudo nmcli connection modify "Your_SSID_Name" ipv4.method manual
sudo nmcli connection up "Your_SSID_Name"

Hardware-Specific WiFi Limitations

When designing your IoT topology, you must account for the physical hardware limitations of the specific Single Board Computer (SBC) you are deploying:

  • Raspberry Pi 4B & Pi 5: Feature dual-band 802.11ac (WiFi 5) chips. They support both 2.4GHz and 5GHz, as well as WPA3-SAE security protocols on modern OS builds. Excellent for high-bandwidth tasks like streaming IP cameras.
  • Raspberry Pi Zero 2 W: Features a single-band 802.11n chip. It is strictly limited to 2.4GHz networks. Attempting to force a connection to a 5GHz SSID will result in silent failures. Furthermore, the Pi Zero 2 W relies on the PCB trace antenna; placing it inside a metal enclosure will completely destroy the signal.
  • Compute Module 4 (CM4): Requires an external M.2 or U.FL antenna. If you forget to attach the physical antenna pigtail to the CM4 IO board, the Pi will see the WiFi interface, but signal strength will read near -90dBm, resulting in an unusable connection.

Verifying Signal Strength and Link Quality

Once connected, verify the physical layer health of your connection. Do not rely solely on the presence of an IP address. Use the following command to poll the active WiFi interface for real-time signal data:

iwconfig wlan0 | grep -i signal

A healthy IoT node should maintain a signal level better than -65 dBm. If your readings hover around -75 dBm or lower, you will experience intermittent packet loss, and you should consider deploying a USB WiFi adapter with a high-gain external antenna or relocating the Pi closer to your access point.