PrecisionFab SA

PrecisionFabSA logo

Radxa Zero Wi-Fi Setup Success — Full Guide (Debian Bullseye KDE B23 Image)

—

by

admin
in , ,

Getting Wi-Fi working reliably on the Radxa Zero 512 MB board can be frustrating, especially when running the official Debian Bullseye KDE B23 image.
This post documents the exact steps, failures, fixes, and working configuration that finally delivered a stable, automatic Wi-Fi connection at boot, confirmed over multiple reboots and SSH sessions.

If you’ve been stuck with a board that boots fine but never connects to Wi-Fi, this is the tested, working reference.

1. The Base Image

After testing several Radxa Zero OS images, including minimal and Ubuntu variants, the only image that consistently booted and initialized the USB multifunction gadget (for serial, Ethernet, and mass storage) was:

radxa-zero-debian-bullseye-kde-b23.img.xz

This image provides a full desktop, stable USB gadget drivers, and working peripherals — but Wi-Fi does not connect by default.

Even though the Broadcom brcmfmac driver and firmware are present, the wireless interface (wlan0) always remains down on boot.

2. The Problem

Symptoms observed on fresh boot:

ip addr show wlan0

Output:

3: wlan0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000

No IP address, no DHCP attempt, and no automatic connection.

Manual attempts like:

sudo ifconfig wlan0 up
sudo wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf
sudo dhclient wlan0

worked temporarily — confirming hardware and firmware were fine — but the connection was lost on reboot.
The goal was to automate Wi-Fi startup on every boot with a static IP to allow SSH access headlessly.

3. The Working Base Script (Host-Side Preparation)

All work was performed on an MX Linux host.
The SD card with the Radxa root filesystem was mounted under /media/mxlinux/rootfs.

A working automation script was built to prepare and configure the image before booting the board:

#!/bin/bash
set -e

ROOTFS="/media/mxlinux/rootfs"
QEMU_BIN="/usr/bin/qemu-aarch64-static"

# Verify mount
if [ ! -d "$ROOTFS/etc" ]; then
  echo "Root filesystem missing."
  exit 1
fi
echo "Rootfs found at $ROOTFS"

# Required tools
sudo apt update -y
sudo apt install -y qemu-user-static binfmt-support

# Copy QEMU for ARM chroot
sudo cp "$QEMU_BIN" "$ROOTFS/usr/bin/"

# Bind system directories
for d in dev dev/pts proc sys run; do
  sudo mount --bind /$d "$ROOTFS/$d"
done

# Configure Wi-Fi inside chroot
sudo chroot "$ROOTFS" /bin/bash <<'CHROOT_CMDS'
set -e
echo "Configuring Wi-Fi..."

systemctl disable iwd.service || true
systemctl stop iwd.service || true
systemctl disable NetworkManager || true
systemctl stop NetworkManager || true

mkdir -p /etc/network/interfaces.d
cat <<'EOF' > /etc/network/interfaces.d/wlan0
auto wlan0
iface wlan0 inet static
    address 192.168.10.210
    netmask 255.255.255.0
    gateway 192.168.10.1
    dns-nameservers 8.8.8.8 1.1.1.1
    wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
EOF

cat <<'EOF' > /etc/wpa_supplicant/wpa_supplicant.conf
country=ZA
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
    ssid="Cudy-DD8C"
    psk="86319959"
    key_mgmt=WPA-PSK
}
EOF

cat <<'EOF' > /usr/local/bin/wifi-restart.sh
#!/bin/bash
sleep 5
echo "[wifi-restart] Bringing wlan0 down and up..."
ifdown wlan0 || true
ifup wlan0
EOF
chmod +x /usr/local/bin/wifi-restart.sh

cat <<'EOF' > /etc/systemd/system/wifi-restart.service
[Unit]
Description=Wi-Fi Auto-Restart Service
After=multi-user.target network.target
Wants=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/wifi-restart.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable wifi-restart.service || true
CHROOT_CMDS

# Cleanup
for d in run sys proc dev/pts dev; do
  sudo umount "$ROOTFS/$d"
done

echo "SD card ready for headless boot."

4. Booting and Testing

After unmounting and booting the SD card in the Radxa Zero, the multifunction USB gadget showed up immediately on the host as usb0.

From the host:

sudo ip link set usb0 up
ping 192.168.7.2
ssh radxa@192.168.7.2

Initially, there was no route — because the board had no Wi-Fi connection yet.

Running the /usr/local/bin/wifi-restart.sh manually inside the Radxa shell connected instantly.

This confirmed that:

  • The config files were correct
  • The firmware and interface worked
  • The issue was purely timing — Wi-Fi was being initialized before the kernel driver finished loading.

5. The Boot Delay Fix

Through multiple timed reboots and ping tests, it was found that the system needed approximately 75 seconds after power-on before wlan0 could be successfully brought up.

A simple delay in the systemd service solved this.

The working /etc/systemd/system/wifi-restart.service is:

[Unit]
Description=Wi-Fi Auto-Restart Service
After=multi-user.target network.target
Wants=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/wifi-restart.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

And the script /usr/local/bin/wifi-restart.sh:

#!/bin/bash
sleep 75
echo "[wifi-restart] Initializing wlan0..."
ifdown wlan0 || true
ifup wlan0

After applying this, Wi-Fi came online automatically at boot every single time.
The static IP 192.168.10.210 became reachable via ping and SSH after ~75 seconds.

6. Router Hostname Issue (Solved)

Even though the board now connected perfectly, it appeared as “Unknown” in the router’s client list.

Investigation showed that /etc/hosts inside the Debian image was completely empty.
Without this file, the system fails to identify its own hostname over the network.

Fix:

sudo hostnamectl set-hostname radxa-zero
sudo nano /etc/hosts

Add:

127.0.0.1    localhost
127.0.1.1    radxa-zero

Save, reboot, and now the router correctly shows the device as radxa-zero.

7. Final System Summary

Image Used: radxa-zero-debian-bullseye-kde-b23
Network Configuration: /etc/network/interfaces.d/wlan0
WPA Config: /etc/wpa_supplicant/wpa_supplicant.conf
Static IP: 192.168.10.210
Service File: /etc/systemd/system/wifi-restart.service
Boot Delay: 75 seconds
Hostname Fix: /etc/hosts populated

After all adjustments, Wi-Fi connects automatically, router displays correct hostname, and SSH is available on every reboot.

8. Lessons Learned

  • Boot timing matters: low-memory Radxa Zero models load the Wi-Fi firmware slowly.
  • NetworkManager and iwd interfere with Debian’s ifupdown — disable them.
  • Static IP is simpler and faster for headless setups than DHCP on slow boots.
  • Router hostname depends on a valid /etc/hosts file.
  • Testing via USB gadget (usb0) provides a safe recovery channel during configuration.

9. Conclusion

The Radxa Zero 512 MB running Debian Bullseye KDE B23 can operate fully headless with reliable Wi-Fi connectivity — but only after careful adjustment of timing and network service priorities.

This guide consolidates all working fixes: chroot configuration, systemd delay, static IP, and hostname correction.
It has been tested through multiple cold boots and remains stable.

With this setup, your Radxa Zero will come online automatically and be ready for SSH management within 75 seconds of power-on.

⚠️ DisclaimerThe information provided in this article is based on personal testing and experience with the Radxa Zero 512 MB running Debian Bullseye KDE (b23) image. While every effort has been made to ensure accuracy, configurations, firmware versions, and hardware variations may produce different results.Use these instructions at your own discretion and always back up your data before making system-level changes. Neither the author nor PrintLabSA is responsible for any damage, data loss, or connectivity issues that may arise from following these steps.For official documentation and updates, please refer to the Radxa Wiki and associated Debian repositories.

💬 WhatsApp Now