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_nrf7001_coex` `nrf7002ek_nrf7001` `nrf7002ek` `nrf7002ek_coex`

Running coexistence sample test cases require 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` file.
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 an application 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_TEST_TYPE_WLAN_ONLY: This option enables the Wi-Fi test type.

CONFIG_TEST_TYPE_OT_ONLY: This option enables the Thread test type.

CONFIG_TEST_TYPE_WLAN_OT: This option enables concurrent Wi-Fi and Thread tests.

CONFIG_COEX_TEST_DURATION: This option sets the Wi-Fi, Thread, or both test duration in milliseconds.

WIFI_CREDENTIALS_STATIC_SSID: This option specifies the SSID of the Wi-Fi access point to connect.

WIFI_CREDENTIALS_STATIC_PASSWORD: This option specifies the Wi-Fi passphrase (WPA2™) or password (WPA3™) to connect.

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

menuconfig can also be used to configure Wi-Fi credentials

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.

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

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 Configuring and 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 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 -Dipc_radio_SHIELD=nrf7002ek_coex

For nRF7001 EK:

-DSHIELD=nrf7002ek_nrf7001 -Dipc_radio_SHIELD=nrf7002ek_nrf7001_coex

Overlay files
- Use the overlay-ot.conf overlay-wifi-udp-client-thread-udp-client.conf file to build for both Wi-Fi and Thread in client roles.
- Use the overlay-ot.conf 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.

Use the following commands to check the available devices:

$ nrfjprog --com
1050779496         /dev/ttyACM0    VCOM0
1050779496         /dev/ttyACM1    VCOM1
1050759502         /dev/ttyACM2    VCOM0
1050759502         /dev/ttyACM3    VCOM1
$

  In this example, ``1050779496`` is the device ID of the first nRF7002 DK and ``1050759502`` is the device ID of the second nRF7002 DK.

  While connecting to a particular board, use the ttyACMx corresponding to VCOM1.
  In the example, use ttyACM1 to connect to the board with device ID ``1050779496``.
  Similarly, use ttyACM3 to connect to the board with device ID ``1050759502``.

Use the following commands to connect to the desired devices:

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

Program the nRF7002 DK by completing the following steps:
1. Open a new terminal in the test PC.
2. Navigate to the <ncs code>/nrf/samples/wifi/thread_coex/ folder.
3. Run the following command:
  $ west flash --dev-id <device-id> --hex-file build/merged.hex
When the sample runs Wi-Fi UDP throughput in client mode, a peer device (test PC) runs UDP throughput in server mode using the following command:
$ iperf -s -i 1 -u

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

Test case

Coexistence

Test procedure

Wi-Fi-only throughput

NA

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

NA

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

NA

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

NA

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.

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