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 |
---|---|---|---|---|
PCA20053 |
|
|
||
PCA10143 |
|
|||
PCA10143 |
|
|||
PCA10095 |
|
|
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.
Overview
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 |
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 to20000
.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:
Open a new terminal in the test PC.
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
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: