Wi-Fi: Thread coexistence

The Thread coexistence sample demonstrates coexistence between Wi-Fi® and OpenThread device radios in 2.4 GHz frequency.

Requirements 

The sample supports the following development kit:

Hardware platforms	PCA	Board name	Board target	Shields
Thingy:53	PCA20053	thingy53	`thingy53/nrf5340/cpuapp`	`nrf7002eb_coex` `nrf7002eb`
nRF7002 DK (emulating nRF7001)	PCA10143	nrf7002dk	`nrf7002dk/nrf5340/cpuapp/nrf7001`
nRF7002 DK	PCA10143	nrf7002dk	`nrf7002dk/nrf5340/cpuapp`
nRF5340 DK	PCA10095	nrf5340dk	`nrf5340dk/nrf5340/cpuapp`	`nrf7002ek` `nrf7002ek_nrf7001`

Running test cases for this sample requires additional software, such as the Wi-Fi iPerf application. Use iPerf version 2.0.5. For more details, see Network Traffic Generator.

The sample demonstrates how the coexistence mechanism is implemented, and how it can be enabled and disabled between Wi-Fi and Thread radios in the 2.4 GHz band. This is done by using the throughput of the Wi-Fi client and the Thread client, as well as the throughput of the Wi-Fi client and the Thread server.

Test setup 

The following figure shows a reference test setup.

The reference test setup shows the connections between the following devices:

Device Under Test (DUT) (nRF7002 DK on which the coexistence sample runs)
Wi-Fi peer device (access point with test PC that runs iPerf)
Thread peer device (nRF7002 DK on which Thread-only throughput runs)

The following table provides more details on the sample or application that runs on DUT and peer devices:

Device

Application

Details

nRF7002 DK (DUT)

Thread coexistence sample

The sample runs Wi-Fi throughput only, Thread throughput only, or a combination of both based on configuration selections in the prj.conf.

Test PC

iPerf application

Wi-Fi iPerf UDP server is run on the test PC, and this acts as a peer device to the Wi-Fi UDP client.

nRF7002 DK (peer)

Thread only throughput using Thread coexistence sample

Case 1: Thread-only UDP throughput is run in server mode on the peer nRF7002 DK device if Thread role on DUT is a client.

Case 2: Thread-only UDP throughput is run in client mode on the peer nRF7002 DK device if Thread role on DUT is a server.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

Configuration options 

The following sample-specific Kconfig options are used in this sample (located in samples/wifi/thread_coex/Kconfig):

CONFIG_NET_CONFIG_PEER_IPV4_ADDR

(string) Peer IPv4 address

None

CONFIG_NET_CONFIG_PEER_IPV4_PORT

(int) Peer IPv4 port

None

CONFIG_WIFI_THREAD_STACK_SIZE

(int) Wi-Fi thread stack size

None

CONFIG_WIFI_THREAD_PRIORITY

(int) Wi-Fi thread priority

None

CONFIG_WIFI_ZPERF_SERVER

(bool) Zperf role: server or client

None

CONFIG_WIFI_ZPERF_PROT_UDP

(bool) UDP or TCP

None

CONFIG_WIFI_ZPERF_PKT_SIZE

(int) packet size

None

CONFIG_WIFI_ZPERF_RATE

(int) rate in kbps

None

CONFIG_OT_CHANNEL

(int) Thread device operating channel

None

CONFIG_OT_PAN_ID

(int) Thread device PAN ID

None

CONFIG_OT_ROLE_CLIENT

(bool) Thread device role

None

CONFIG_OT_PACKET_SIZE

(int) Thread device packet size

None

CONFIG_OT_RATE_BPS

(int) Thread device rate in bits per seconds

None

CONFIG_NET_CONFIG_THREAD_PORT

(int) Port for Thread zperf

None

CONFIG_OT_ZPERF_PROT_UDP

(bool) UDP or TCP

None

CONFIG_TEST_TYPE_WLAN_ONLY

(bool) WLAN only

Enable WLAN only

CONFIG_TEST_TYPE_OT_ONLY

(bool) Thread only

Enable Thread only

CONFIG_TEST_TYPE_WLAN_OT

(bool) WLAN and Thread

Enable WLAN and Thread

CONFIG_TEST_TYPE_WLAN

(bool) WLAN

Enable WLAN

CONFIG_TEST_TYPE_OT

(bool) Thread

Enable Thread

CONFIG_COEX_TEST_DURATION

(int) test duration in milliseconds

None

CONFIG_COEX_SEP_ANTENNAS

(bool) No support for shared antenna in Thread and WLAN. Set it to yes

None

CONFIG_SR_PROTOCOL_BLE

(bool) Indicates if the SR protocol is Bluetooth LE or not

None

Additional configuration 

To enable different test modes, set up the following configuration parameters in the prj.conf file:

Test modes: Use the following Kconfig options to select the required test case:
- CONFIG_TEST_TYPE_WLAN_ONLY for Wi-Fi-only test.
- CONFIG_TEST_TYPE_OT_ONLY for Thread-only test.
- CONFIG_TEST_TYPE_WLAN_OT for concurrent Wi-Fi and Thread test.
Test duration: Use the CONFIG_COEX_TEST_DURATION Kconfig option to set the duration of the Wi-Fi-only test or Thread-only test or both. The units are in milliseconds. For example, to set the test for 20 seconds, set this value to 20000.
Wi-Fi connection: Configure the following Wi-Fi credentials in the prj.conf: appropriately as per the credentials of the access point used for this testing:

Wi-Fi static credential options

If you want to configure the credentials statically, set the CONFIG_WIFI_CREDENTIALS_STATIC Kconfig option to y.

Important

Do not use static credentials in production environments.

Other options for statically configuring your Wi-Fi credentials:

CONFIG_WIFI_CREDENTIALS_STATIC - This option enables static Wi-Fi configuration.
CONFIG_WIFI_CREDENTIALS_STATIC_SSID - Wi-Fi SSID.
CONFIG_WIFI_CREDENTIALS_STATIC_PASSWORD - Wi-Fi password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_OPEN - Wi-Fi network uses no password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK - Wi-Fi network uses a password and PSK security (default).
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK_SHA256 - Wi-Fi network uses a password and PSK-256 security.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_SAE - Wi-Fi network uses a password and SAE security.

Note

You can also use menuconfig to configure Wi-Fi credentials.

See Interactive Kconfig interfaces in the Zephyr documentation for instructions on how to run menuconfig.

Wi-Fi throughput test: Set the CONFIG_NET_CONFIG_PEER_IPV4_ADDR Kconfig option appropriately as per the Wi-Fi interface IP address of the test PC on which iPerf is run.

Building and running 

This sample can be found under samples/wifi/thread_coex in the nRF Connect SDK folder structure.

When built as firmware image for a board target with the */ns variant, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

You can build the coexistence sample for the following configurations:

Wi-Fi throughput only
Thread throughput only
Concurrent Wi-Fi and Thread throughput (with coexistence enabled and disabled modes)

To build for the nRF7002 DK, use the nrf7002dk/nrf5340/cpuapp board target. The following are examples of the CLI commands:

Build with coexistence disabled:

west build -p -b nrf7002dk/nrf5340/cpuapp -- -DCONFIG_MPSL_CX=n -Dipc_radio_CONFIG_MPSL_CX=n

Use this command for Wi-Fi throughput only, Thread throughput only, or concurrent Wi-Fi and Thread throughput with coexistence disabled tests.

Build with coexistence enabled:

west build -p -b nrf7002dk/nrf5340/cpuapp -- -DCONFIG_MPSL_CX=y -Dipc_radio_CONFIG_MPSL_CX=y

Use this command for concurrent Wi-Fi and Thread throughput with coexistence enabled test.

Change the board target as given below for the nRF7001 DK, nRF7002 EK, and nRF7001 EK.

Board target for nRF7001 DK:
```
nrf7002dk/nrf5340/cpuapp/nrf7001
```
Board target for nRF7002 EK and nRF7001 EK:
```
nrf5340dk/nrf5340/cpuapp
```

Add the following SHIELD options for the nRF7002 EK and nRF7001 EK.

For nRF7002 EK:
```
-DSHIELD=nrf7002ek
```
For nRF7001 EK:
```
-DSHIELD=nrf7002ek_nrf7001
```
Overlay files
- Use the overlay-wifi-udp-client-thread-udp-client.conf file to build for both Wi-Fi and Thread in client roles.
- Use the overlay-wifi-udp-client-thread-udp-server.conf file to build for Wi-Fi in the client role and Thread in the server role.

The generated HEX file to be used is thread_coex/build/merged.hex.

Testing 

After programming the sample to your development kit, complete the following steps to test it:

Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.
Connect to the kit with a terminal emulator (for example, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.
Run the following command to check the available devices:
```
nrfjprog --com
```
This command returned the following output in the setup used to run the coexistence tests.
```
1050779496         /dev/ttyACM0    VCOM0
1050779496         /dev/ttyACM1    VCOM1
1050759502         /dev/ttyACM2    VCOM0
1050759502         /dev/ttyACM3    VCOM1
```
In this example, 1050779496 is the serial number of the first nRF7002 DK and 1050759502 is the serial number of the other one.

While connecting to a particular device, use the /dev/ttyACM corresponding to VCOM1. In the example, use /dev/ttyACM1 to connect to the device with the serial number 1050779496. Similarly, use /dev/ttyACM3 to connect to the device with the serial number 1050759502.

Run the following commands to connect to the desired devices:

minicom -D /dev/ttyACM1 -b 115200
minicom -D /dev/ttyACM3 -b 115200

Programming DKs 

Complete the following steps to program the nRF7002 DK:

Start the toolchain environment in a terminal window.
Navigate to the <ncs code>/nrf/samples/wifi/thread_coex/ folder.

Run the following command:

west flash --dev-id <device-id> --hex-file build/merged.hex

Test procedure 

The following tables provide the procedure to run Wi-Fi only, Bluetooth LE-only, and combined throughput for different Thread roles.

Complete the following steps to run the Wi-Fi client and Thread client:

Test case

Coexistence

Test procedure

Wi-Fi-only throughput

N.A.

Run Wi-Fi iPerf in server mode on the test PC. Build the coexistence sample for Wi-Fi-only throughput in the client role and program the DUT nRF7002 DK.

Thread-only throughput

N.A.

Build the coexistence sample for Thread-only throughput in the server role and program the peer nRF7002 DK. Build the coexistence sample for Thread-only throughput in the client role and program the DUT nRF7002 DK after Run thread application on client is seen on the peer nRF7002 DK’s UART console window.

Wi-Fi and Thread combined throughput

Disabled/ Enabled

Build the coexistence sample for Thread-only throughput in the server role and program the peer nRF7002 DK. Run Wi-Fi iPerf in server mode on the test PC. Build the coexistence sample for concurrent Wi-Fi and Thread throughput with both Wi-Fi and Thread in client roles. Program the sample on the DUT nRF7002 DK after Run thread application on client is seen on the peer nRF7002 DK’s UART console window.

Complete the following steps to run the Wi-Fi client and Thread server:

Test case

Coexistence

Test procedure

Wi-Fi-only throughput

N.A.

Run Wi-Fi iPerf in server mode on the test PC. Build the coexistence sample for Wi-Fi-only throughput in the client role and program the DUT nRF7002 DK.

Thread-only throughput

N.A

Build the coexistence sample for Thread-only throughput in the server role and program the DUT nRF7002 DK. Build the coexistence sample for Thread-only throughput in the client role and program the peer nRF7002 DK after Run thread application on client is seen on the DUT nRF7002 DK’s UART console window.

Wi-Fi and Thread combined throughput

Disabled/ Enabled

Build the coexistence sample for concurrent Wi-Fi and Thread throughput with Wi-Fi in the client role and Thread in the server role, program this on the DUT nRF7002 DK. Run Wi-Fi iPerf in server mode on the test PC. Build the coexistence sample for Thread-only throughput in the client role and program the peer nRF7002 DK after Run thread application on client is seen on the DUT nRF7002 DK’s UART console window.

When the sample is executed, the Wi-Fi UDP throughput operates with the Device Under Test (DUT) in client mode. To run the UDP throughput in server mode on the peer device (test PC), use the following command.

iperf -s -i 1 -u

Observe that the Wi-Fi throughput result appears on the test PC terminal on which iPerf server is run. The Thread throughput result appears on the minicom terminal connected to the nRF7002 DK, on which Thread is run in the client role.

Results 

The following tables summarize the results obtained from coexistence tests conducted in a clean RF environment for different Wi-Fi operating bands, with Wi-Fi and Thread data rates set to 10 Mbps and 65 kbps, respectively. These results are representative and might vary based on the RSSI and the level of external interference.

The Wi-Fi and Thread channels (both in the 2.4 GHz band) are selected to overlap, thereby maximizing interference. Tests are run using separate antenna configurations only, as Thread does not support shared antenna configurations due to being in idle listening mode when not active.

Wi-Fi (802.11n mode) in 2.4 GHz

Wi-Fi in client role (channel 11), Thread in client role (channel 22):

Test case	Wi-Fi UDP TX throughput in Mbps	Thread throughput in kbps
Wi-Fi-only	9.6	N.A.
Thread-only	N.A.	63
Wi-Fi and Thread, coexistence disabled	9.5	14
Wi-Fi and Thread, coexistence enabled	9.3	59

Wi-Fi in client role (channel 11), Thread in server role (channel 22):

Test case	Wi-Fi UDP TX throughput in Mbps	Thread throughput in kbps
Wi-Fi-only	9.6	N.A.
Thread-only	N.A.	63
Wi-Fi and Thread, coexistence disabled	9.4	14
Wi-Fi and Thread, coexistence enabled	8.8	63

Wi-Fi (802.11n mode) in 5 GHz

Wi-Fi in client role (channel 48), Thread in client role (channel 22):

Test case	Wi-Fi UDP TX throughput in Mbps	Thread throughput in kbps
Wi-Fi-only	9.6	N.A.
Thread-only	N.A.	63
Wi-Fi and Thread, coexistence disabled	9.2	63
Wi-Fi and Thread, coexistence enabled	9.1	63

Wi-Fi in client role (channel 48), Thread in server role (channel 22):

Test case	Wi-Fi UDP TX throughput in Mbps	Thread throughput in kbps
Wi-Fi-only	9.6	N.A.
Thread-only	N.A.	63
Wi-Fi and Thread, coexistence disabled	8.6	63
Wi-Fi and Thread, coexistence enabled	8.5	63

The results show that coexistence harmonizes airtime between Wi-Fi and Thread rather than resulting in a higher combined throughput. This is consistent with the design intent.

Dependencies 

This sample uses the following library:

nRF Security