nRF70 series Linux SPI reference driver

Linux driver for the nRF70 series Wi-Fi SoC family from Nordic Semiconductor. The driver is based on the nRF Connect SDK and is compatible with the Linux SPI framework.

This driver is a reference implementation and is not intended for production use. It is provided as-is and is not supported by Nordic Semiconductor ASA. It can be used in any Linux environment to evaluate the nRF70 series Wi-Fi SoC family.

Supported hardware

The driver supports the following nRF70 series Wi-Fi SoCs:

• nRF7002
• nRF7001

Supported features

The driver supports the following features:

• Wi-Fi STA mode
• Wi-Fi 6 (802.11ax) 1x1 operation
• Dual-band (2.4 GHz and 5 GHz) operation (Depending on the nRF70 series Wi-Fi SoC variant)
• WPA2-PSK security
• WPA3-SAE security

Getting started

The driver can be used with any Linux based products, but it is tested on a Raspberry Pi4B running the Ubuntu 22.04 LTS operating system. Support for other Linux distributions is not part of the scope of this project.

Prerequisites

Hardware

The following hardware is required to run the driver:

• Raspberry Pi4B
• nRF7002 or nRF7001 Evaluation Kit (without Host MCU)
• An Interposer board to connect the nRF70 series Wi-Fi SoC to the Raspberry Pi4B header Note: The Interposer board is not included in the nRF7002 or nRF7001 Evaluation Kit and must be purchased separately.
• A microSD card (at least 32GB) with Ubuntu 22.04 LTS installed

Software

The following software is required to run the driver:

• Ubuntu 22.04.03 LTS (64-bit) comes with 5.15.0-1037-raspi Linux kernel

Install dependencies

The following dependencies are required to build the driver, install them using apt:

• west
• device-tree-compiler
• build-essential
• wpa_supplicant
  • Make sure that the wpa_supplicant version is 2.10 or newer
• wpa_passphrase
• iw

Build and run the driver

Build the driver

1. Clone the repository using west:

   west init -m [email protected]:NordicPlayground/nrf70-linux-driver.git --mr main

2. Update west projects

   west update

3. Build the driver

   make clean all

Driver feature configuration

nRF70 driver has feature flags to enable/disable certain features. These flags can be controlled via the command line arguments to the make command. The following flags are available:

Flag	Description	Default
MODE	Supported modes are STA only	STA
LOW_POWER	Enable low power mode	0

Examples

1. Build the driver in STA mode with low power enabled

   make clean all MODE=STA LOW_POWER=1

Ensure that the nrf_wifi_fmac_sta.ko and dts/nrf70_rpi_interposer.dtbo files are generated.

Run the driver

1. Load the DTS overlay

   a. Permanent loading: Configure the Raspberry Pi4B to load the DTS overlay at boot time (Recommended for production)

   sudo cp dts/nrf70_rpi_interposer.dtbo /boot/firmware/overlays/
   # Update config.txt
   sudo vim /boot/firmware/config.txt
   # Add below line at the end of the file
   dtoverlay=nrf70_rpi_interposer
   sudo reboot

   b. Runtime loading: Load the DTS overlay at runtime (Helpful for development)

   sudo dtoverlay dts/nrf70_rpi_interposer.dtbo

   Note 1: Using this procedure, the DTS overlay must be loaded every time the Raspberry Pi4B is rebooted.

   Note 2: Using this procedure, in the dmesg ignore the warnings OF: overlay: WARNING: memory leak will occur if overlay removed, property: ******, these are expected as we are dynamically loading the DTS.

2. Load the driver

   sudo insmod nrf_wifi_fmac_sta.ko

   Note 1: Using this procedure, the driver must be loaded every time the Raspberry Pi4B is rebooted.

   Note 2: Using this procedure, in the dmesg ignore the warnings nrf_wifi_fmac_sta: loading out-of-tree module taints kernel, these are expected as we are loading a out-of-tree module.

3. Verify that the driver is loaded

   lsmod | grep nrf_wifi_fmac_sta

4. Verify network interfaces

   ip link show

   The driver should create a new network interface called nrf_wifi.

5. Verify Wi-Fi interface using iw

   iw dev nrf_wifi info

6. Check the kernel log for driver output

   dmesg

Connect to a Wi-Fi network

1. Prepare a WPA supplicant configuration file

   wpa_passphrase <SSID> <PASSWORD> > wpa_supplicant.conf

2. Connect to the Wi-Fi network

   sudo wpa_supplicant -i nrf_wifi -c wpa_supplicant.conf -B

3. Verify that the Wi-Fi interface is connected

   iw dev nrf_wifi link

4. Run a DHCP client to get an IP address

   sudo dhclient nrf_wifi

5. Verify that the Wi-Fi interface has an IP address

   ip addr show nrf_wifi

6. Verify that the Wi-Fi interface has internet access

   ping -I nrf_wifi google.com

Disconnect from a Wi-Fi network

1. Kill the WPA supplicant

   sudo killall wpa_supplicant

2. Verify that the Wi-Fi interface is disconnected

   iw dev nrf_wifi link

Remove the driver

1. Remove the driver

   sudo rmmod nrf_wifi_fmac_sta

Debugging

Run the WPA supplicant in debug mode

1. Stop the WPA supplicant

   sudo killall wpa_supplicant

2. Run the WPA supplicant in debug mode

   sudo wpa_supplicant -i nrf_wifi -c wpa_supplicant.conf -dd -f /tmp/wpa_supplicant.log

3. Share the /tmp/wpa_supplicant.log file along with configuration file wpa_supplicant.conf for debugging purposes.

Collect dmesg

1. Collect the kernel log

   dmesg > dmesg.log

2. Collect the kernel log from all previous boots to give a complete picture of the system

   cat /var/log/kern.log* > kern.log

Collect Sniffer logs

The procedure to collect sniffer logs is outside the scope of this document as it depends heavily on the environment and the sniffer used.

Known issues

1. Target Wake Time (TWT) feature is not supported yet.

2. Maximum UDP/TCP throughputs achieved presently are in the range of 2 - 3 Mbps.

3. Intermittent issues when running UDP/TCP throughputs:

   • Firmware lockup (on the nRF70 series device)
   • Linux kernel crash

4. Sometimes below warning is observed in the dmesg

   • NOHZ tick-stop error: Non-RCU local softirq work is pending, handler #08!!!

5. Sometimes during boot couple of commands timeout and below warning is observed in the dmesg, once the driver is fully initialized the commands work as expected, so, these warnings can be ignored.

   • Timed out waiting for response from RPU (Get Channel)
   • Timed out waiting for response from RPU (Set TX power)