EDF Wi-Fi Setup

Introduction

This page is a step-by-step guide for bringing up a USB Wi-Fi adapter under EDF by using iwd/iwctl and systemd-networkd networking stack. It covers tested hardware, driver verification, Wi-Fi connection setup, DHCP configuration on wlan0, basic connectivity checks, and troubleshooting.

Networking Stack

In EDF, the base networking stack uses iwd (iNet wireless daemon) and its command-line front-end iwctl, combined with systemd-networkd for IP configuration and link management. iwd handles Wi-Fi device control, scanning, authentication, and association, while iwctl provides the user interface to create and manage Wi-Fi profiles. After iwd establishes a wireless link, systemd-networkd handles DHCP/static addressing, routing, and DNS settings for the corresponding network interfaces.

In the EDF images, iwd/iwctl and systemd-networkd are already enabled, and a variety of popular USB Wi-Fi drivers and Linux firmware blobs are preinstalled, including support for chipsets from Mediatek, Atheros, Realtek, Ralink, and Broadcom.

Tested Devices

The following Wi-Fi USB dongles have been explicitly tested with EDF and confirmed to work with the default iwd/systemd-networkd networking stack.

Panda Wireless PAU0A Dual Band Wi-Fi USB Adapter – Amazon
TP-Link TL-WN725N N150 Nano USB Wi-Fi Adapter – Amazon
TP-Link Archer T3U AC1300 Dual Band USB Wi-Fi Adapter – Amazon
EDUP AX3000 USB 3.0 Wi-Fi 6E Tri-Band Adapter (MT7921AU) – Amazon
LOTEKOO 300Mbps USB Wi-Fi Adapter (RTL8192EU) – Amazon
TP-Link Archer TX10UB Nano AX900 Wi-Fi 6 USB Adapter (RTL8851BU, requires usb-modeswitch) – Amazon

Wi-Fi Setup (Step-by-Step)

The following steps walk through setting up a Wi-Fi connection on a running EDF Linux system by using iwctl (iwd) and systemd-networkd. The commands and output examples assume you are using a supported USB Wi-Fi dongle such as the Panda Wireless PAU0A listed previously.

Verify Services, Driver, and Identify the Wi-Fi Interface

Make sure iwd is running:
```
$ systemctl status iwd
```
Make sure systemd-networkd is running:
```
$ systemctl status systemd-networkd
```
Check the kernel log to confirm that the Wi-Fi driver for the USB dongle loaded correctly. For example, with the Panda Wireless adapter, lines similar to the following appear:
```
$ dmesg | grep -i mt76
```
Example output:
```
[ 22.437350] mt76x0u 1-1:1.0: ASIC revision: 76100002 MAC revision: 76502000
[ 23.520020] mt76x0u 1-1:1.0: EEPROM ver:02 fae:04
[ 23.541335] usbcore: registered new interface driver mt76x0u
```
Seeing messages such as this indicates that the kernel driver for the USB Wi-Fi adapter has initialized successfully.
List Wi-Fi devices known to iwd:
```
$ sudo iwctl device list
```
Note the Wi-Fi device name (for example, wlan0).

Scan for Available Networks

Start the iwctl interactive shell:
```
$ sudo iwctl
```
Inside iwctl, scan for networks on your Wi-Fi device (replace wlan0 with your device name if different):
```
[iwd]# station wlan0 scan
```
Show the scan results:
```
[iwd]# station wlan0 get-networks
```
Identify the SSID (Service Set Identifier) of the network you want to join.

Connect to a Wi-Fi Network

Still inside iwctl, connect to the required SSID (replace MySSID with your network name):
```
[iwd]# station wlan0 connect MySSID
```
If the network is protected, iwctl prompts for the Wi-Fi passphrase.
After connecting, you can confirm the link state:
```
[iwd]# station wlan0 show
```
Exit iwctl:
```
[iwd]# exit
```

You can also observe kernel log messages indicating authentication and association of wlan0 with the access point by checking dmesg:

$ dmesg | grep wlan0

Example output:

[ 484.633139] wlan0: authenticate with ba:5e:71:25:72:5f (local address=9c:ef:d5:f9:54:22)
[ 484.633154] wlan0: send auth to ba:5e:71:25:72:5f (try 1/3)
[ 484.637809] wlan0: authenticated
[ 484.639194] wlan0: associate with ba:5e:71:25:72:5f (try 1/3)
[ 484.642385] wlan0: RX AssocResp from ba:5e:71:25:72:5f (capab=0x1011 status=0 aid=22)
[ 484.645618] wlan0: associated
[ 484.723244] wlan0: Limiting TX power to 30 (30 - 0) dBm as advertised by ba:5e:71:25:72:5f

Obtain an IP Address Through systemd-networkd

By default, systemd-networkd in EDF is not configured to use DHCP on the Wi-Fi interface (for example, wlan0). You must first create a network configuration file for wlan0, then restart systemd-networkd so it can request an IP address from your DHCP server.

Create a network configuration file for wlan0:

$ sudo tee /etc/systemd/network/25-wireless.network >/dev/null << 'EOF'
[Match]
Name=wlan0
[Network]
DHCP=yes
EOF

Reload and restart systemd-networkd so the new configuration takes effect:

$ sudo systemctl daemon-reload
$ sudo systemctl restart systemd-networkd

Verify that wlan0 has obtained an IP address:

$ networkctl status wlan0
$ ip addr show wlan0

Verify Connectivity

Use basic tools to confirm external connectivity:

$ ping -c 3 8.8.8.8         # Test raw IP connectivity
$ ping -c 3 www.google.com  # Test DNS resolution and connectivity

If both commands succeed, your Wi-Fi connection is working correctly under EDF with iwd/iwctl and systemd-networkd.

Conclusion

This tutorial showed how to set up a USB Wi-Fi adapter under EDF by using iwd/iwctl and systemd-networkd: verifying services and driver load, scanning for available networks, connecting to an access point, enabling DHCP on wlan0, and validating connectivity.

Wi-Fi network settings and the passphrase you configure by using iwctl persist on disk in iwd network profiles. Your EDF system remembers the configured Wi-Fi network across reboots and automatically reconnects to the same SSID when the access point is available and the USB Wi-Fi adapter is present.

Troubleshooting

Wi-Fi Adapter Shows up as a USB Storage Device

Some USB Wi-Fi adapters (such as those based on Realtek RTL8851BU) enumerate as a mass storage device on plug-in. Check dmesg for lines such as:

[ 214.438016] usb 1-1: Product: DISK
[ 214.442223] usb-storage 1-1:1.0: USB Mass Storage device detected

EDF includes usb-modeswitch which automatically switches these adapters to Wi-Fi mode through udev rules. If the automatic switch does not occur, trigger it manually:

$ sudo usb_modeswitch -KW -v 0bda -p 1a2b

Replace the vendor (-v) and product (-p) IDs with the values from lsusb. After a successful switch, the adapter re-enumerates and the Wi-Fi driver loads normally.

No Wi-Fi Interface Is Displayed in `iwctl device list`

Confirm the USB dongle is firmly connected and recognized by the kernel:
```
$ lsusb
$ dmesg | tail -n 50
```
Check for driver load messages (for the Panda adapter, look for mt76x0u):
```
$ dmesg | grep -i mt76
```
If no driver-related messages appear, try a different USB port or hub.

Driver Loads, but `iwctl` Still Shows No Devices

Verify that iwd is active and not failing:
```
$ systemctl status iwd
```

Restart iwd and recheck:

$ sudo systemctl restart iwd
$ iwctl device list

`station wlan0 scan` or `get-networks` shows no SSIDs

Make sure your access point is powered on and within range.
Check regulatory domain settings (if applicable) and antenna placement.
Inspect the kernel log for rfkill or power issues:
```
$ dmesg | grep -i wlan0
```

Connection Fails or Supplicant Keeps Prompting for Passphrase

Double-check the SSID and passphrase (case-sensitive).
Examine kernel log messages for authentication/association failures:
```
$ dmesg | grep wlan0
```

If you changed the passphrase on the AP, delete the old network profile and reconnect:

$ iwctl station wlan0 list-known-networks
$ iwctl station wlan0 forget <SSID>
$ iwctl station wlan0 connect <SSID>

Connected in `iwctl`, but No IP Address

Confirm the wlan0 network file exists and DHCP is enabled:
```
$ cat /etc/systemd/network/25-wireless.network
```

Verify systemd-networkd is running and managing wlan0:

$ systemctl status systemd-networkd
$ networkctl status wlan0

Restart systemd-networkd and recheck:

$ sudo systemctl restart systemd-networkd
$ ip addr show wlan0

IP Address Assigned, but No External Connectivity

Test connectivity to the default gateway:
```
$ ip route
$ ping -c 3 <gateway_ip>
```

If gateway pings succeed but DNS fails, check /etc/resolv.conf:

$ cat /etc/resolv.conf
$ ping -c 3 8.8.8.8
$ ping -c 3 www.google.com

Wi-Fi Works Initially but Does Not Reconnect After Reboot

Confirm that iwd has stored the Wi-Fi network profile:
```
$ ls /var/lib/iwd
```

Make sure both iwd and systemd-networkd are enabled at boot:

$ systemctl is-enabled iwd
$ systemctl is-enabled systemd-networkd

If necessary, enable them:

$ sudo systemctl enable iwd
$ sudo systemctl enable systemd-networkd

Next Steps

The steps in this document focus on bringing up Wi-Fi at runtime on an EDF Linux system by using a prebuilt image. In many deployments, you might also want Wi-Fi support enabled and pre-configured directly in your Yocto Project build so that the required packages, services, and configuration files are part of the generated EDF image. Detailed Yocto Project build instructions for enabling and configuring Wi-Fi-related components (such as iwd, iwctl, systemd-networkd configuration, and firmware/driver packages) as part of your EDF build are available in EDF Wi-Fi Yocto integration.