WIFI & Bluetooth

Luckfox Lyra Zero W is equipped with the AIC8800DC module, which supports the Wi-Fi AX protocol (Wi-Fi 6), 2.4GHz Wi-Fi, and Bluetooth 5.2/BLE. By default, the development board uses an external antenna. To switch to the onboard chip antenna, simply pull up GPIO pin 55. The steps are as follows:

echo 55 > /sys/class/gpio/export
cd /sys/class/gpio/gpio55
echo out > direction
echo 1 > value

1. Wi-Fi Testing

In wireless communication, Wi-Fi devices typically operate in two basic modes: AP (Access Point) mode and STA (Station) mode. In AP mode, the device acts as a wireless hotspot that other devices can connect to—similar to a home Wi-Fi router. In STA mode, the device connects to an existing wireless network as a Wi-Fi client, just like a phone or laptop connects to Wi-Fi.

1.1 Wi-Fi Connection (STA Mode)

Connect to Wi-Fi using the wifi-connect script:
```
wifi-connect.sh Luckfox-2.4G luckfox12345
```
- Luckfox-2.4G：Name of the Wi-Fi network
- luckfox12345：Wi-Fi password
- Replace the SSID and password with your actual Wi-Fi credentials. No other changes are needed.
Obtain an IP address via DHCP:
```
udhcpc -i wlan0
```

Note: These settings will be lost after reboot. To persist the configuration, you’ll need to write a startup script (for onboard antenna).

#!/bin/sh

WIFI_SSID="Luckfox-2.4G"
WIFI_PASSWD="luckfox12345"
GPIO_NUM=55
GPIO_PATH="/sys/class/gpio/gpio${GPIO_NUM}"

echo_log() {
   echo "[wifi-autostart] $1"
}

wait_for_interface() {
   for i in $(seq 1 5); do
      if ip link show wlan0 > /dev/null 2>&1; then
            return 0
      fi
      echo_log "Waiting for wlan0... ($i)"
      sleep 2
   done
   return 1
}

case "$1" in
   start)
      echo_log "Exporting and setting GPIO${GPIO_NUM}..."
      [ ! -d "$GPIO_PATH" ] && echo "$GPIO_NUM" > /sys/class/gpio/export
      echo out > "${GPIO_PATH}/direction"
      echo 1 > "${GPIO_PATH}/value"

      echo_log "Checking wlan0 interface..."
      if ! wait_for_interface; then
            echo_log "wlan0 not found after retries, aborting."
            exit 1
      fi

      echo_log "Connecting to WiFi: $WIFI_SSID"
      if [ -x /usr/bin/wifi-connect.sh ]; then
            /usr/bin/wifi-connect.sh "$WIFI_SSID" "$WIFI_PASSWD"
      else
            echo_log "wifi-connect.sh not found or not executable"
      fi

      echo_log "Requesting IP via udhcpc..."
      udhcpc -i wlan0

      echo_log "WiFi setup done."
      ;;
   stop)
      echo_log "Stop command received. No action defined."
      ;;
   *)
      echo "Usage: $0 {start|stop}"
      exit 1
      ;;
esac

According to the above configuration method, the settings will be lost after reboot. Therefore, you need to create a startup script to reapply them (for external antenna use).

nano /etc/init.d/S99wlan0

#!/bin/sh

case $1 in
        start)
        sleep 5
        wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf
        udhcpc -i wlan0
                ;;
        stop)
                ;;
        *)
                exit 1
                ;;
esac

chmod +x  /etc/init.d/S99wlan0
reboot

1.2 AP Mode

This section uses hostapd and dnsmasq to configure the wlan0 interface as a WPA2-PSK Wi-Fi hotspot. After configuration, a phone or computer can connect to the development board and access it over the local network.

note

This section creates a local Wi-Fi network only. Internet sharing through the development board is not configured.

1.2.1 Configuration Overview

The following example uses these settings:

Parameter	Value	Description
Wireless interface	`wlan0`	Wi-Fi interface used to create the hotspot
SSID	`Luckfox_AP_2`	Hotspot name displayed on phones and computers
Wi-Fi password	`luckfox88`	WPA2 pre-shared key; must contain 8 to 63 characters
AP address	`10.201.126.1/24`	Development board address on the AP network
DHCP address pool	`10.201.126.50` to `10.201.126.150`	IPv4 addresses assigned to clients

Replace the example SSID and password as needed. Use a stronger password for normal use.

1.2.2 Check the Required Components

Log in to the development board as root, then verify that the wireless interface, hostapd, and dnsmasq are available:

ip link show wlan0
command -v hostapd
command -v dnsmasq

Continue after all three commands return the expected interface or command path.

1.2.3 Configure hostapd

Back up the original configuration file:

cp -p /etc/hostapd.conf /etc/hostapd.conf.bak

To restore the original configuration later, run:

cp -p /etc/hostapd.conf.bak /etc/hostapd.conf

Set the SSID and WPA2-PSK parameters:
```
sed -i \
    -e 's/^ssid=.*/ssid=Luckfox_AP_2/' \
    -e 's/^auth_algs=.*/auth_algs=1/' \
    -e 's/^wpa_passphrase=.*/wpa_passphrase=luckfox88/' \
    -e 's/^wpa_key_mgmt=.*/wpa_key_mgmt=WPA-PSK/' \
    -e '/^rsn_pairwise=/d' \
    -e '/^wpa_key_mgmt=/a rsn_pairwise=CCMP' \
    /etc/hostapd.conf
```
The key parameters are:
- ssid: hotspot name.
- auth_algs=1: Open System authentication; WPA2 authentication is completed during the four-way handshake.
- wpa=2: enables WPA2 and should already be present in the original configuration.
- wpa_passphrase: hotspot password, which must contain 8 to 63 characters.
- wpa_key_mgmt=WPA-PSK: uses pre-shared key authentication.
- rsn_pairwise=CCMP: uses AES-CCMP encryption.

Check the key settings:

grep -nE '^(interface|ssid|hw_mode|channel|auth_algs|wpa|wpa_passphrase|wpa_key_mgmt|rsn_pairwise)=' /etc/hostapd.conf

The output should include:

interface=wlan0
ssid=Luckfox_AP_2
hw_mode=g
channel=1
auth_algs=1
wpa=2
wpa_passphrase=luckfox88
wpa_key_mgmt=WPA-PSK
rsn_pairwise=CCMP

1.2.4 Start the Hotspot

Stop any existing hostapd process, then start it in the background:

killall hostapd 2>/dev/null
hostapd -B /etc/hostapd.conf

The following output indicates that the AP has started:

wlan0: interface state UNINITIALIZED->ENABLED
wlan0: AP-ENABLED

Check its status:

hostapd_cli -i wlan0 status

The output should include:

state=ENABLED
channel=1
ssid[0]=Luckfox_AP_2

1.2.5 Configure the AP Address

Assign the example gateway address to wlan0:

ip addr add 10.201.126.1/24 dev wlan0

Verify the address:

ip -4 addr show dev wlan0

The output should include:

inet 10.201.126.1/24 scope global wlan0

If the ip addr add command reports RTNETLINK answers: File exists, the address is already configured and does not need to be added again.

1.2.6 Configure and Start DHCP

Make sure /etc/dnsmasq.conf contains at least the following settings:

listen-address=10.201.126.1
dhcp-range=10.201.126.50,10.201.126.150

listen-address must match the AP address assigned to wlan0. dnsmasq uses the development board address on this subnet as the default gateway for clients.

Restart dnsmasq:

killall dnsmasq 2>/dev/null
dnsmasq --pid-file=/var/run/dnsmasq.pid

Check the DNS and DHCP listening ports:

ss -lunp

Under normal conditions, dnsmasq listens on UDP port 53 for DNS and UDP port 67 for DHCP.

Use a Custom Subnet

The AP does not have to use 10.201.126.0/24. When changing the subnet, update both the wlan0 address and /etc/dnsmasq.conf. For example, to use 192.168.50.0/24:

ip addr del 10.201.126.1/24 dev wlan0
ip addr add 192.168.50.1/24 dev wlan0

Then update /etc/dnsmasq.conf:

listen-address=192.168.50.1
dhcp-range=192.168.50.50,192.168.50.150,255.255.255.0,12h
dhcp-option=3,192.168.50.1

dhcp-option=3 explicitly defines the client default gateway. It can be omitted when the development board address on this subnet should be used as the gateway. Choose a subnet that does not overlap with eth0, usb0, or the upstream router, then restart dnsmasq.

1.2.7 Connect and Verify

On a phone or computer, search for and connect to the following hotspot:

Wi-Fi name: Luckfox_AP_2
Wi-Fi password: luckfox88

The client should receive an address from 10.201.126.50 to 10.201.126.150. From the client, test connectivity to the development board:

ping 10.201.126.1

To view connected clients on the development board, run:

hostapd_cli -i wlan0 all_sta

1.2.8 Troubleshooting

hostapd reports an invalid password length: wpa_passphrase must contain 8 to 63 characters. Correct the password and restart hostapd.
A phone reports an incorrect password or cannot connect: if the log contains AP-STA-POSSIBLE-PSK-MISMATCH, forget the saved network on the phone and enter the current password again. Changing the SSID also prevents the phone from reusing an outdated Wi-Fi profile.
A client remains at "Obtaining IP address": run ip -4 addr show dev wlan0, ps | grep '[d]nsmasq', and ss -lunp. Confirm that wlan0 has 10.201.126.1/24 and that dnsmasq is listening on UDP port 67.
The hotspot works but has no internet access: this is expected. Internet sharing also requires IPv4 forwarding, firewall forwarding rules, and NAT, which are outside the scope of this section.

1.2.9 Configuration After Reboot

Changes to /etc/hostapd.conf and /etc/dnsmasq.conf are retained, but the following runtime operations must be repeated after a reboot:

hostapd -B /etc/hostapd.conf
ip addr add 10.201.126.1/24 dev wlan0
dnsmasq --pid-file=/var/run/dnsmasq.pid

To enable AP mode automatically at startup, add the interface address and the hostapd and dnsmasq startup commands to a system startup script.

1.2.10 Command Summary

Run the following commands during initial configuration:

cp -p /etc/hostapd.conf /etc/hostapd.conf.bak

sed -i \
    -e 's/^ssid=.*/ssid=Luckfox_AP_2/' \
    -e 's/^auth_algs=.*/auth_algs=1/' \
    -e 's/^wpa_passphrase=.*/wpa_passphrase=luckfox88/' \
    -e 's/^wpa_key_mgmt=.*/wpa_key_mgmt=WPA-PSK/' \
    -e '/^rsn_pairwise=/d' \
    -e '/^wpa_key_mgmt=/a rsn_pairwise=CCMP' \
    /etc/hostapd.conf

killall hostapd 2>/dev/null
hostapd -B /etc/hostapd.conf

ip addr add 10.201.126.1/24 dev wlan0

killall dnsmasq 2>/dev/null
dnsmasq --pid-file=/var/run/dnsmasq.pid

To start AP mode again later, run:

killall hostapd 2>/dev/null
hostapd -B /etc/hostapd.conf

ip addr add 10.201.126.1/24 dev wlan0

killall dnsmasq 2>/dev/null
dnsmasq --pid-file=/var/run/dnsmasq.pid

1.3 Wi-Fi Speed Test

On your PC or virtual machine:
```
iperf3 -s -i 10 -p 5001
```
- -s: Start in server mode
- -i: Report interval set to 10 seconds
- -p: Use port 5001
On the development board:
```
iperf3 -c 192.168.10.176 -p 5001 -f m -i 2 -t 24
```
- -c: Client mode, connecting to server IP 192.168.10.176
- -p: Use port 5001
- -f: Report format, m = Mbps
- -i: Report interval = 2 seconds
- -t: Duration = 24 seconds

2. Bluetooth Test

By default, the Wi-Fi and Bluetooth modules work cooperatively in BLE (Low Energy) mode. If you need to connect traditional Bluetooth devices (like speakers), you must manually switch the Bluetooth mode.

In the file /usr/bin/wifibt-util.sh, comment out the following line:
```
# Aicsemi AIC8800DC       a69c:88dc       aic8800_fdrv.ko
```
Reboot the development board:
```
reboot
```

Start Bluetooth:

root@luckfox:~# bluetoothctl
hci0 new_settings: powered bondable ssp br/edr le secure-conn
Agent registered
[CHG] Controller 38:54:39:03:10:70 Powered: yes
[CHG] Controller 38:54:39:03:10:70 Pairable: yes
[bluetooth]# power on                   # Power on Bluetooth
[bluetooth]# scan on                    # Scan for Bluetooth devices
[bluetooth]# trust 12:11:32:DE:A3:03    # Trust device
[bluetooth]# pair 12:11:32:DE:A3:03     # Pair device
[bluetooth]# connect 12:11:32:DE:A3:03  # Connect device
[M1]# exit

1. Wi-Fi Testing​

1.1 Wi-Fi Connection (STA Mode)​

1.2 AP Mode​

1.2.1 Configuration Overview​

1.2.2 Check the Required Components​

1.2.3 Configure hostapd​

1.2.4 Start the Hotspot​

1.2.5 Configure the AP Address​

1.2.6 Configure and Start DHCP​

Use a Custom Subnet​

1.2.7 Connect and Verify​

1.2.8 Troubleshooting​

1.2.9 Configuration After Reboot​

1.2.10 Command Summary​

1.3 Wi-Fi Speed Test​

2. Bluetooth Test​

1. Wi-Fi Testing

1.1 Wi-Fi Connection (STA Mode)

1.2 AP Mode

1.2.1 Configuration Overview

1.2.2 Check the Required Components

1.2.3 Configure hostapd

1.2.4 Start the Hotspot

1.2.5 Configure the AP Address

1.2.6 Configure and Start DHCP

Use a Custom Subnet

1.2.7 Connect and Verify

1.2.8 Troubleshooting

1.2.9 Configuration After Reboot

1.2.10 Command Summary

1.3 Wi-Fi Speed Test

2. Bluetooth Test