Wi-Fi Fundamentals

Feedback
Feedback

If you are having issues with the exercises, please create a ticket on DevZone: devzone.nordicsemi.com
Click or drag files to this area to upload. You can upload up to 2 files.
Register

Network Management API

v3.0.0

The Network Management API is used to send network requests or receive notifications on network events. at any level in the IP stack. The API allows applications, as well as network layer code itself, to call defined network routines at any level in the IP stack, or receive notifications on relevant network events. Defined procedure handlers are registered by using a NET_MGMT_REGISTER_REQUEST_HANDLER macro, and procedure requests are done through a single net_mgmt() API that invokes the registered handler for the corresponding request.

Enabling the API

To enable the Network Management API in your application, we can enable the following Kconfigs

CONFIG_NET_MGMT=y
CONFIG_NET_MGMT_EVENT=y
CONFIG_NET_MGMT_EVENT_INFO=y
Kconfig

In addition, you need to include the header file for the API

#include <zephyr/net/net_mgmt.h>
C

Wi-Fi management API

The Wi-Fi management API is used to manage Wi-Fi networks and is implemented in the wifi_mgmt module as part of the network L2 stack (zephyr/subsys/net/l2).

It contains the Wi-Fi relevant procedure requests for the Network Management API, such as NET_REQUEST_WIFI_CONNECT to connect to Wi-Fi and NET_REQUEST_WIFI_CONNECT_STORED to connect to Wi-Fi using stored credentials. Invoking this request will automatically configure connection parameters from stored credentials on the device.

It is automatically included when enabling Wi-Fi (specifically the Wi-Fi supplicant CONFIG_WIFI_NM_WPA_SUPPLICANT selects CONFIG_NET_L2_WIFI_MGMT), so we only have to include the header file for the API

#include <zephyr/net/wifi_mgmt.h>
C

Connection Manager

In this course, we will be using the Connection Manager, a feature of nRF Connect SDK, to listen to the network interface and IP events to verify whether the network interface is ready. The Connection Manager allows applications to control the connectivity without consideration for the underlying network technologies, making it easy to switch between for example Wi-Fi and cellular connectivity.

The Kconfig CONFIG_NET_CONNECTION_MANAGER will add and start the connection manager in the application, and will raise the L4 events “connected” and “disconnected”.

CONFIG_NET_CONNECTION_MANAGER=y
Kconfig

Then we must tell the Connection Manager which L2 connectivity we are using by enabling CONFIG_L2_WIFI_CONNECTIVITY.

CONFIG_L2_WIFI_CONNECTIVITY=y
Kconfig

This will automatically select the following Kconfigs

To ensure there’s sufficient stack space for the Connection Manager monitor thread to handle the new events, we must increase the stack size, by setting the following Kconfig.

CONFIG_NET_CONNECTION_MANAGER_MONITOR_STACK_SIZE=5200
Kconfig

Enabling Wi-Fi

To enable Wi-Fi support for the nRF70 Series devices, we must first enable it in Sysbuild.

Recall

Recall from the nRF Connect SDK Fundamentals course that Sysbuild (System build) is a higher-level build system that can combine multiple other build systems, and is used to configure, build and flash multiple images as part of a single project.

This is done with SB_CONFIG_WIFI_NRF=y by adding the following line to the sysbuild.conf file.

SB_CONFIG_WIFI_NRF70=y
Kconfig

Now that we’ve enabled Wi-Fi in our application at the Sysbuild level, we also want to configure the Wi-Fi stack at the application level, through the prj.conf file.

This is done by enabling the following Kconfigs

CONFIG_WIFI=y
CONFIG_WIFI_NM_WPA_SUPPLICANT=y
Kconfig
  • CONFIG_WIFI: Enables the general Wi-Fi drivers in the application
  • CONFIG_WIFI_NM_WPA_SUPPLICANT: Enables WPA (Wi-Fi Protected Access) supplicant as the network management backend for WIFI_NM. The WPA supplicant is primarily responsible for implementing the authentication phase of WPA, as well as network scanning, key exchange and roaming support.

Configuring the Wi-Fi stack

To optimize the performance and memory usage of the Wi-Fi stack, there are many configuration options to tweak.

The Wi-Fi driver has dedicated heaps for both the control plane and data plane operations. The heap sizes can be configured usingCONFIG_NRF_WIFI_CTRL_HEAP_SIZE (default value 20000) and CONFIG_NRF_WIFI_DATA_HEAP_SIZE (default value 130000).

Note

In previous versions, the nRF70 driver heap was part of the system shared heap CONFG_HEAP_MEM_POOL_SIZE. However, it is now recommended to disable CONFIG_HEAP_MEM_POOL_IGNORE_MIN and let the system calculate the minimum heap size for the application. Now, any subsequent RAM overflow issues need to be solved by fine-tuning CONFIG_NRF_WIFI_CTRL_HEAP_SIZE and CONFIG_NRF_WIFI_DATA_HEAP_SIZE.

We won’t go into all of them, but there are specifically two parameters in the nRF Wi-Fi driver that we will adjust.

CONFIG_NRF70_RX_NUM_BUFS [1 – unlimited*] specifies the number of RX buffers that can be used by the nRF Wi-Fi driver. The number of buffers must be enough to keep up with the RX traffic, otherwise packets might be dropped. We will set this to 16, which can handle moderate traffic without excessive memory usage. Reducing this will impact the memory of the application.

CONFIG_NRF70_MAX_TX_AGGREGATION [1 – unlimited*] specifies the maximum number of frames that can be coalesced into a single Wi-Fi frame. More frames imply more coalescing opportunities but can add latency to the TX path as we wait for more frames to arrive. We will set this to 4 which provides moderature frame aggregation without excessive latency. Reducing this will impact the memory of the application and tune the performance.

*based on available memory in the nRF70 Series device

CONFIG_NRF70_RX_NUM_BUFS=16
CONFIG_NRF70_MAX_TX_AGGREGATION=4
Kconfig

Wi-Fi stack configuration and performance provides a full list of the configuration options and description.

Configure the Wi-Fi parameters

When connecting to Wi-Fi, the parameters are passed in the structure struct wifi_connect_req_params. Below we see some of the relevant members of this structure

  • SSID – SSID of your Wi-Fi network
  • PSK – PSK, typically a passphrase or password
  • SAE password (sae_password) – SAE password, if using WPA3
  • Band (band) – Wi-Fi band you want to connect to
  • Channel (channel) – Wi-Fi channel to use
  • Security – The security type to use (NONE, PSK, PSK_SHA256, SAW, WAPI, EAP, WEP, WPA_SPK)
  • MFP – Management frame protection options
  • Timeout – Connection timeout in seconds

Here is an example of populating the Wi-Fi parameters

static struct wifi_connect_req_params cnx_params= {
    .ssid = CONFIG_SSID;
    .ssid_length = strlen(cnx_params->ssid);
    .psk = CONFIG_PASSWORD;
    .psk_length = strlen(cnx_params->psk);
    .channel = WIFI_CHANNEL_ANY;
    .security = WIFI_SECURITY_TYPE_PSK;
    .mfp = WIFI_MFP_OPTIONAL;
    .timeout = SYS_FOREVER_MS;
}
C

Request the Wi-Fi connection

All network management requests are called using net_mgmt(), which has the following signature

  • mgmt_request: a bitmask to indicate which stack layer is targeted, if a net_if object is implied and the specific management procedure being requested
  • iface: network interface being used, use the helper function net_if_get_first_wifi() (gets the first Wi-Fi network interface) or net_if_get_default() (gets the default network interface).
  • data: the Wi-Fi configuration parameters, stored in struct wifi_connect_req_params
  • len: the length of data, i.e sizeof(struct wifi_connect_req_params)

To request the Wi-Fi connection, we will invoke the procedure request with NET_REQUEST_WIFI_CONNECT from the Wi-Fi management API, as shown below

struct net_if *iface = net_if_get_first_wifi();
int err = net_mgmt(NET_REQUEST_WIFI_CONNECT, iface, &cnx_params, sizeof(struct wifi_connect_req_params));
if (err) {
	LOG_ERR("Connecting to Wi-Fi failed, err: %d", err);
	return ENOEXEC;
}
C

Listen to network events

After we have requested a Wi-Fi connection, we want to register a callback function to listen to network events so the application is notified when the Wi-Fi connection has been established.

The callback handler function net_mgmt_event_handler_t must have the following signature

The Wi-Fi-related network events are defined in the Wi-Fi Management API, such as NET_EVENT_WIFI_CONNECT_RESULT and NET_EVENT_WIFI_DISCONNECT_RESULT.

However, we will instead be using the events defined in the Network Management API: NET_EVENT_L4_CONNECTED and NET_EVENT_L4_DISCONNECTED.

It is important to note that the NET_EVENT_L4_CONNECTED event is only triggered once your device has received an IP address, so CONFIG_DHCPV4 must be enabled in the application.

Define the callback function

Define the callback function net_mgmt_event_handler()

static void net_mgmt_event_handler(struct net_mgmt_event_callback *cb,
			  uint32_t mgmt_event, struct net_if *iface)
{
	if ((mgmt_event & EVENT_MASK) != mgmt_event) {
		return;
	}
	if (mgmt_event == NET_EVENT_L4_CONNECTED) {
		LOG_INF("Network connected");
		k_sem_give(&run_app);
		return;
	}
	if (mgmt_event == NET_EVENT_L4_DISCONNECTED) {
		if (connected == false) {
			LOG_INF("Waiting for network to be connected");
		} else {
			LOG_INF("Network disconnected");
			connected = false;
		}
		k_sem_reset(&run_app);
		return;
	}
}
C

Initialize and add the callback structure

First, define the Network Management event callback structure, struct net_mgmt_event_callback.

static struct net_mgmt_event_callback mgmt_cb;
C

To initialize the callback structure, we will use the helper function net_mgmt_init_event_callback() which has the following signature

Then, we need to add the callback structure using net_mgmt_add_event_callback() which has the following signature

net_mgmt_init_event_callback(&mgmt_cb, net_mgmt_event_handler, EVENT_MASK);
net_mgmt_add_event_callback(&mgmt_cb);
C

More on this

The Wi-Fi credentials library provides means to load and store Wi-Fi network credentials in the device. We will take a closer look at how to do this in the next topic, Wi-Fi Provisioning and in Exercise 2 of this lesson.

v2.9.0 – v2.8.0

The Network Management API is used to send network requests or receive notifications on network events. at any level in the IP stack. The API allows applications, as well as network layer code itself, to call defined network routines at any level in the IP stack, or receive notifications on relevant network events. Defined procedure handlers are registered by using a NET_MGMT_REGISTER_REQUEST_HANDLER macro, and procedure requests are done through a single net_mgmt() API that invokes the registered handler for the corresponding request.

Enabling the API

To enable the Network Management API in your application, we can enable the following Kconfigs

CONFIG_NET_MGMT=y
CONFIG_NET_MGMT_EVENT=y
CONFIG_NET_MGMT_EVENT_INFO=y
Kconfig

In addition, you need to include the header file for the API

#include <zephyr/net/net_mgmt.h>
C

Wi-Fi management API

The Wi-Fi management API is used to manage Wi-Fi networks and is implemented in the wifi_mgmt module as part of the network L2 stack (zephyr/subsys/net/l2).

It contains the Wi-Fi relevant procedure requests for the Network Management API, such as NET_REQUEST_WIFI_CONNECT to connect to Wi-FI.

It is automatically included when enabling Wi-Fi (specifically the Wi-Fi supplicant CONFIG_WIFI_NM_WPA_SUPPLICANT selects CONFIG_NET_L2_WIFI_MGMT), so we only have to include the header file for the API

#include <zephyr/net/wifi_mgmt.h>
C

Connection Manager

In this course, we will be using the Connection Manager, a feature of nRF Connect SDK, to listen to the network interface and IP events to verify whether the network interface is ready. The Connection Manager allows applications to control the connectivity without consideration for the underlying network technologies, making it easy to switch between for example Wi-Fi and cellular connectivity.

The Kconfig CONFIG_NET_CONNECTION_MANAGER will add and start the connection manager in the application, and will raise the L4 events “connected” and “disconnected”.

CONFIG_NET_CONNECTION_MANAGER=y
Kconfig

Then we must tell the Connection Manager which L2 connectivity we are using by enabling CONFIG_L2_WIFI_CONNECTIVITY.

CONFIG_L2_WIFI_CONNECTIVITY=y
Kconfig

This will automatically select the following Kconfigs

To ensure there’s sufficient stack space for the Connection Manager monitor thread to handle the new events, we must increase the stack size, by setting the following Kconfig.

CONFIG_NET_CONNECTION_MANAGER_MONITOR_STACK_SIZE=5200
Kconfig

Enabling Wi-Fi

To enable Wi-Fi support for the nRF70 Series devices, we must first enable it in Sysbuild.

Recall

Recall from the nRF Connect SDK Fundamentals course that Sysbuild (System build) is a higher-level build system that can combine multiple other build systems, and is used to configure, build and flash multiple images as part of a single project.

This is done with SB_CONFIG_WIFI_NRF=y by adding the following line to the sysbuild.conf file.

SB_CONFIG_WIFI_NRF70=y
Kconfig

Now that we’ve enabled Wi-Fi in our application at the Sysbuild level, we also want to configure the Wi-Fi stack at the application level, through the prj.conf file.

This is done by enabling the following Kconfigs

CONFIG_WIFI=y
CONFIG_WIFI_NM_WPA_SUPPLICANT=y
Kconfig
  • CONFIG_WIFI: Enables the general Wi-Fi drivers in the application
  • CONFIG_WIFI_NM_WPA_SUPPLICANT: Enables WPA (Wi-Fi Protected Access) supplicant as the network management backend for WIFI_NM. The WPA supplicant is primarily responsible for implementing the authentication phase of WPA, as well as network scanning, key exchange and roaming support.

Configuring the Wi-Fi stack

The optimize the performance and memory usage of the Wi-Fi stack, there are many configuration options to tweak.

Wi-Fi stack configuration and performance provides a full list of the configuration options and description

We won’t go into all of them, but there are specifically two parameters in the nRF Wi-Fi driver that we will adjust

CONFIG_NRF70_RX_NUM_BUFS [1 – unlimited*] specifies the number of RX buffers that can be used by the nRF Wi-Fi driver. The number of buffers must be enough to keep up with the RX traffic, otherwise packets might be dropped. We will set this to 16, which can handle moderate traffic without excessive memory usage. Reducing this will impact the memory of the application.

CONFIG_NRF70_MAX_TX_AGGREGATION [1 – unlimited*] specifies the maximum number of frames that can be coalesced into a single Wi-Fi frame. More frames imply more coalescing opportunities but can add latency to the TX path as we wait for more frames to arrive. We will set this to 4 which provides moderature frame aggregation without excessive latency. Reducing this will impact the memory of the application and tune the performance.

*based on available memory in the nRF70 Series device

CONFIG_NRF70_RX_NUM_BUFS=16
CONFIG_NRF70_MAX_TX_AGGREGATION=4
Kconfig

Configure the Wi-Fi parameters

When connecting to Wi-Fi, the parameters are passed in the structure struct wifi_connect_req_params. Below we see some of the relevant members of this structure

  • SSID – SSID of your Wi-Fi network
  • PSK – PSK, typically a passphrase or password
  • SAE password (sae_password) – SAE password, if using WPA3
  • Band (band) – Wi-Fi band you want to connect to
  • Channel (channel) – Wi-Fi channel to use
  • Security – The security type to use (NONE, PSK, PSK_SHA256, SAW, WAPI, EAP, WEP, WPA_SPK)
  • MFP – Management frame protection options
  • Timeout – Connection timeout in seconds

Here is an example of populating the Wi-Fi parameters

static struct wifi_connect_req_params cnx_params= {
    .ssid = CONFIG_SSID;
    .ssid_length = strlen(cnx_params->ssid);
    .psk = CONFIG_PASSWORD;
    .psk_length = strlen(cnx_params->psk);
    .channel = WIFI_CHANNEL_ANY;
    .security = WIFI_SECURITY_TYPE_PSK;
    .mfp = WIFI_MFP_OPTIONAL;
    .timeout = SYS_FOREVER_MS;
}
C

Request the Wi-Fi connection

All network management requests are called using net_mgmt(), which has the following signature

  • mgmt_request: a bitmask to indicate which stack layer is targeted, if a net_if object is implied and the specific management procedure being requested
  • iface: network interface being used, use the helper function net_if_get_first_wifi() (gets the first Wi-Fi network interface) or net_if_get_default() (gets the default network interface).
  • data: the Wi-Fi configuration parameters, stored in struct wifi_connect_req_params
  • len: the length of data, i.e sizeof(struct wifi_connect_req_params)

To request the Wi-Fi connection, we will invoke the procedure request with NET_REQUEST_WIFI_CONNECT from the Wi-Fi management API, as shown below

struct net_if *iface = net_if_get_first_wifi();
int err = net_mgmt(NET_REQUEST_WIFI_CONNECT, iface, &cnx_params, sizeof(struct wifi_connect_req_params));
if (err) {
	LOG_ERR("Connecting to Wi-Fi failed, err: %d", err);
	return ENOEXEC;
}
C

Listen to network events

After we have requested a Wi-Fi connection, we want to register a callback function to listen to network events so the application is notified when the Wi-Fi connection has been established.

The callback handler function net_mgmt_event_handler_t must have the following signature

The Wi-Fi-related network events are defined in the Wi-Fi Management API, such as NET_EVENT_WIFI_CONNECT_RESULT and NET_EVENT_WIFI_DISCONNECT_RESULT.

However, we will instead be using the events defined in the Network Management API: NET_EVENT_L4_CONNECTED and NET_EVENT_L4_DISCONNECTED.

It is important to note that the NET_EVENT_L4_CONNECTED event is only triggered once your device has received an IP address, so CONFIG_DHCPV4 must be enabled in the application.

Define the callback function

Define the callback function net_mgmt_event_handler()

static void net_mgmt_event_handler(struct net_mgmt_event_callback *cb,
			  uint32_t mgmt_event, struct net_if *iface)
{
	if ((mgmt_event & EVENT_MASK) != mgmt_event) {
		return;
	}
	if (mgmt_event == NET_EVENT_L4_CONNECTED) {
		LOG_INF("Network connected");
		k_sem_give(&run_app);
		return;
	}
	if (mgmt_event == NET_EVENT_L4_DISCONNECTED) {
		if (connected == false) {
			LOG_INF("Waiting for network to be connected");
		} else {
			LOG_INF("Network disconnected");
			connected = false;
		}
		k_sem_reset(&run_app);
		return;
	}
}
C

Initialize and add the callback structure

First, define the Network Management event callback structure, struct net_mgmt_event_callback.

static struct net_mgmt_event_callback mgmt_cb;
C

To initialize the callback structure, we will use the helper function net_mgmt_init_event_callback() which has the following signature

Then, we need to add the callback structure using net_mgmt_add_event_callback() which has the following signature

net_mgmt_init_event_callback(&mgmt_cb, net_mgmt_event_handler, EVENT_MASK);
net_mgmt_add_event_callback(&mgmt_cb);
C

Automatic connection feature

The Wi-Fi management extension library adds a procedure request for an automatic connection feature with NET_REQUEST_WIFI_CONNECT_STORED. Invoking this request will automatically configure connection parameters from stored credentials on the device.

Add the library to your application through the following Kconfig

CONFIG_WIFI_MGMT_EXT=y
Kconfig

Include the header file for the library in the main.c file of your application

#include <net/wifi_mgmt_ext.h>
C

The following code snippet is an example of how to invoke this procedure request with net_mgmt().

struct net_if *iface = net_if_get_first_wifi();
int err = net_mgmt(NET_REQUEST_WIFI_CONNECT_STORED, iface, NULL, 0);
if (err) {
	LOG_ERR("Auto-connecting to Wi-Fi failed, err: %d", err);
	return ENOEXEC;
}
C

Notice that we are passing NULL to the data parameter, as opposed to when invoking NET_REQUEST_WIFI_CONNECT. This is because the Wi-Fi management extension library creates the connection parameters from credentials stored on the device.

More on this

The Wi-Fi credentials library provides means to load and store Wi-Fi network credentials in the device. We will take a closer look at how to do this in the next topic, Wi-Fi Provisioning and in Exercise 2 of this lesson.

v2.7.0 – v2.6.1

The Network Management API is used to send network requests or receive notifications on network events. The API allows applications, as well as network layer code itself, to call defined network routines at any level in the IP stack, or receive notifications on relevant network events. Procedure requests are done through a single net_mgmt() API that invokes the registered handler for the corresponding request.

Enabling the API

To enable the Network Management API in your application, we can enable the following Kconfigs

CONFIG_NET_MGMT=y
CONFIG_NET_MGMT_EVENT=y
CONFIG_NET_MGMT_EVENT_INFO=y
CONFIG_NET_MGMT_EVENT_STACK_SIZE=4096
Kconfig

In addition, you need to include the following header files

#include <zephyr/net/wifi.h>
#include <zephyr/net/wifi_mgmt.h>
#include <zephyr/net/net_mgmt.h>
C
  • wifi.h: Header file for Wi-Fi Management API
  • wifi_mgmt.h: Header file for Wi-Fi specific Network Management API’s
  • net_mgmt.h: Header file for the Network Management API

In this course, we will be using the network connection manager, an experimental feature of nRF Connect SDK, to listen to the network interface and IP events to verify whether an interface is connected or not.

The Kconfig CONFIG_NET_CONNECTION_MANAGER will add and start the connection manager in the application, and will raise L4 events “connected” and “disconnected”,

CONFIG_NET_CONNECTION_MANAGER=y
Kconfig

Enabling Wi-Fi

To be able to use the Network Management API to connect to Wi-Fi, we also need to enable Wi-Fi in the application.

This is done by enabling the following Kconfigs

CONFIG_WIFI=y
CONFIG_WIFI_NRF700X=y
CONFIG_WPA_SUPP=y
Kconfig
  • CONFIG_WIFI: Enables the general Wi-Fi drivers
  • CONFIG_WIFI_NRF700X: Enables the Nordic Wi-Fi Driver
  • CONFIG_WPA_SUPP: Enables WPA (Wi-Fi Protected Access) supplicant support, primarily responsible for implementing the authentication phase of WPA, as well as network scanning, key exchange and roaming support.

Configure the Wi-Fi parameters

When connecting to Wi-Fi, the parameters are passed in the structure struct wifi_connect_req_params, which has the following signature

  • SSID – SSID of your Wi-Fi network
  • PSK – PSK, typically a passphrase or password
  • SAE password (sae_password) – SAE password, if using WPA3
  • Band (band) – Wi-Fi band you want to connect to
  • Channel (channel) – Wi-Fi channel to use
  • Security – The security type to use (NONE, PSK, PSK_SHA256, SAW, WAPI, EAP, WEP, WPA_SPK)
  • MFP – Management frame protection options
  • Timeout – Connection timeout in seconds

Here is an example of populating the Wi-Fi parameters

static struct wifi_connect_req_params params = {
    .ssid = CONFIG_SSID;
    .ssid_length = strlen(params->ssid);
    .psk = CONFIG_PASSWORD;
    .psk_length = strlen(params->psk);
    .channel = WIFI_CHANNEL_ANY;
    .security = WIFI_SECURITY_TYPE_PSK;
    .mfp = WIFI_MFP_OPTIONAL;
    .timeout = SYS_FOREVER_MS;
}
C

Request the Wi-Fi connection

All network management requests are called using net_mgmt(), which has the following signature

  • mgmt_request: a bitmask to indicate which stack layer is targeted, if a net_if object is implied and the specific management procedure being requested
  • iface: network interface being used, use the helper function net_if_get_first_wifi() (gets the first Wi-Fi network interface) or net_if_get_default() (gets the default network interface).
  • data: the Wi-Fi configuration parameters, stored in struct wifi_connect_req_params
  • len: the length of data, i.e sizeof(struct wifi_connect_req_params)

To request the Wi-Fi connection, we will use the command NET_REQUEST_WIFI_CONNECT, as shown below

struct net_if *iface = net_if_get_first_wifi();
int err = net_mgmt(NET_REQUEST_WIFI_CONNECT, iface, &params, sizeof(struct wifi_connect_req_params));
if (err) {
	LOG_ERR("Connecting to Wi-Fi failed, err: %d", err);
	return ENOEXEC;
}
C

Listen to network events

After we have requested a Wi-Fi connection, we want to register a callback function to listen to network events so the application is notified when the Wi-Fi connection has been established.

The callback handler function net_mgmt_event_handler_t must have the following signature

The Wi-Fi-related network events are defined in the Wi-Fi Management API, such as NET_EVENT_WIFI_CONNECT_RESULT and NET_EVENT_WIFI_DISCONNECT_RESULT.

However, we will instead be using the events defined in the network connection manager: NET_EVENT_L4_CONNECTED and NET_EVENT_L4_DISCONNECTED. The network connection manager adds a layer of abstraction to your application to easily be able to port an application between different connection protocols, for example, Wi-Fi and cellular.

It is important to note that the NET_EVENT_L4_CONNECTED event is only triggered once your device has received an IP address, so CONFIG_DHCPV4 must be enabled in the application.

Define the callback function

Define the callback function net_mgmt_event_handler()

static void net_mgmt_event_handler(struct net_mgmt_event_callback *cb,
			  uint32_t mgmt_event, struct net_if *iface)
{
	if ((mgmt_event & EVENT_MASK) != mgmt_event) {
		return;
	}
	if (mgmt_event == NET_EVENT_L4_CONNECTED) {
		LOG_INF("Network connected");
		k_sem_give(&run_app);
		return;
	}
	if (mgmt_event == NET_EVENT_L4_DISCONNECTED) {
		if (connected == false) {
			LOG_INF("Waiting for network to be connected");
		} else {
			LOG_INF("Network disconnected");
			connected = false;
		}
		k_sem_reset(&run_app);
		return;
	}
}
C

Initialize and add the callback structure

First, define the Network Management event callback structure, struct net_mgmt_event_callback.

static struct net_mgmt_event_callback mgmt_cb;
C

To initialize the callback structure, we will use the helper function net_mgmt_init_event_callback() which has the following signature

Then, we need to add the callback structure using net_mgmt_add_event_callback() which has the following signature

net_mgmt_init_event_callback(&mgmt_cb, net_mgmt_event_handler, EVENT_MASK);
net_mgmt_add_event_callback(&mgmt_cb);
C

Automatic connection feature

The Wi-Fi management extension library adds an automatic connect feature to the Wi-Fi stack, by using the NET_REQUEST_WIFI_CONNECT_STORED command in net_mgmt().

Add the library to your application through the following Kconfig

CONFIG_WIFI_MGMT_EXT=y
Kconfig

Include the header file for the library in the main.c file of your application

#include <net/wifi_mgmt_ext.h>
C
struct net_if *iface = net_if_get_first_wifi();
int err = net_mgmt(NET_REQUEST_WIFI_CONNECT_STORED, iface, NULL, 0);
if (err) {
	LOG_ERR("Auto-connecting to Wi-Fi failed, err: %d", err);
	return ENOEXEC;
}
C

Important

Please note that although this is the most configurable way to request a Wi-Fi connection, since you can configure struct wifi_connect_req_params, it requires inputting Wi-Fi credentials into the application firmware and is therefore not secure and not recommended in production, but rather for development purposes. We will take a look at a more secure way to provision the network credentials in Exercise 2 of this lesson.

v2.6.0 – v2.5.0

The Network Management API is used to send network requests or receive notifications on network events. The API allows applications, as well as network layer code itself, to call defined network routines at any level in the IP stack, or receive notifications on relevant network events. Procedure requests are done through a single net_mgmt() API that invokes the registered handler for the corresponding request.

Enabling the API

To enable the Network Management API in your application, we can enable the following Kconfigs

CONFIG_NET_MGMT=y
CONFIG_NET_MGMT_EVENT=y
CONFIG_NET_MGMT_EVENT_INFO=y
CONFIG_NET_MGMT_EVENT_STACK_SIZE=4096
Kconfig

In addition, you need to include the following header files

#include <zephyr/net/wifi.h>
#include <zephyr/net/wifi_mgmt.h>
#include <zephyr/net/net_mgmt.h>
C
  • wifi.h: Header file for Wi-Fi Management API
  • wifi_mgmt.h: Header file for Wi-Fi specific Network Management API’s
  • net_mgmt.h: Header file for the Network Management API

In this course, we will be using the network connection manager, an experimental feature of nRF Connect SDK, to listen to the network interface and IP events to verify whether an interface is connected or not.

The Kconfig CONFIG_NET_CONNECTION_MANAGER will add and start the connection manager in the application, and will raise L4 events “connected” and “disconnected”,

CONFIG_NET_CONNECTION_MANAGER=y
Kconfig

Enabling Wi-Fi

To be able to use the Network Management API to connect to Wi-Fi, we also need to enable Wi-Fi in the application.

This is done by enabling the following Kconfigs

CONFIG_WIFI=y
CONFIG_WIFI_NRF700X=y
CONFIG_WPA_SUPP=y
Kconfig
  • CONFIG_WIFI: Enables the general Wi-Fi drivers
  • CONFIG_WIFI_NRF700X: Enables the Nordic Wi-Fi Driver
  • CONFIG_WPA_SUPP: Enables WPA (Wi-Fi Protected Access) supplicant support, primarily responsible for implementing the authentication phase of WPA, as well as network scanning, key exchange and roaming support.

Configure the Wi-Fi parameters

When connecting to Wi-Fi, the parameters are passed in the structure struct wifi_connect_req_params, which has the following signature

  • SSID – SSID of your Wi-Fi network
  • PSK – PSK, typically a passphrase or password
  • SAE password (sae_password) – SAE password, if using WPA3
  • Band (band) – Wi-Fi band you want to connect to
  • Channel (channel) – Wi-Fi channel to use
  • Security – The security type to use (NONE, PSK, PSK_SHA256, SAW, WAPI, EAP, WEP, WPA_SPK)
  • MFP – Management frame protection options
  • Timeout – Connection timeout in seconds

Here is an example of populating the Wi-Fi parameters

static struct wifi_connect_req_params params = {
    .ssid = CONFIG_SSID;
    .ssid_length = strlen(params->ssid);
    .psk = CONFIG_PASSWORD;
    .psk_length = strlen(params->psk);
    .channel = WIFI_CHANNEL_ANY;
    .security = WIFI_SECURITY_TYPE_PSK;
    .mfp = WIFI_MFP_OPTIONAL;
    .timeout = SYS_FOREVER_MS;
}
C

Request the Wi-Fi connection

All network management requests are called using net_mgmt(), which has the following signature

  • mgmt_request: a bitmask to indicate which stack layer is targeted, if a net_if object is implied and the specific management procedure being requested
  • iface: network interface being used, use the helper function net_if_get_first_wifi() (gets the first Wi-Fi network interface) or net_if_get_default() (gets the default network interface).
  • data: the Wi-Fi configuration parameters, stored in struct wifi_connect_req_params
  • len: the length of data, i.e sizeof(struct wifi_connect_req_params)

To request the Wi-Fi connection, we will use the command NET_REQUEST_WIFI_CONNECT, as shown below

struct net_if *iface = net_if_get_first_wifi();
int err = net_mgmt(NET_REQUEST_WIFI_CONNECT, iface, &params, sizeof(struct wifi_connect_req_params));
if (err) {
	LOG_ERR("Connecting to Wi-Fi failed, err: %d", err);
	return ENOEXEC;
}
C

Listen to network events

After we have requested a Wi-Fi connection, we want to register a callback function to listen to network events so the application is notified when the Wi-Fi connection has been established.

The callback handler function net_mgmt_event_handler_t must have the following signature

The Wi-Fi-related network events are defined in the Wi-Fi Management API, such as NET_EVENT_WIFI_CONNECT_RESULT and NET_EVENT_WIFI_DISCONNECT_RESULT.

However, we will instead be using the events defined in the network connection manager: NET_EVENT_L4_CONNECTED and NET_EVENT_L4_DISCONNECTED. The network connection manager adds a layer of abstraction to your application to easily be able to port an application between different connection protocols, for example, Wi-Fi and cellular.

It is important to note that the NET_EVENT_L4_CONNECTED event is only triggered once your device has received an IP address, so CONFIG_DHCPV4 must be enabled in the application.

Define the callback function

Define the callback function net_mgmt_event_handler()

static void net_mgmt_event_handler(struct net_mgmt_event_callback *cb,
			  uint32_t mgmt_event, struct net_if *iface)
{
	if ((mgmt_event & EVENT_MASK) != mgmt_event) {
		return;
	}
	if (mgmt_event == NET_EVENT_L4_CONNECTED) {
		LOG_INF("Network connected");
		k_sem_give(&run_app);
		return;
	}
	if (mgmt_event == NET_EVENT_L4_DISCONNECTED) {
		if (connected == false) {
			LOG_INF("Waiting for network to be connected");
		} else {
			LOG_INF("Network disconnected");
			connected = false;
		}
		k_sem_reset(&run_app);
		return;
	}
}
C

Initialize and add the callback structure

First, define the Network Management event callback structure, struct net_mgmt_event_callback.

static struct net_mgmt_event_callback mgmt_cb;
C

To initialize the callback structure, we will use the helper function net_mgmt_init_event_callback() which has the following signature

Then, we need to add the callback structure using net_mgmt_add_event_callback() which has the following signature

net_mgmt_init_event_callback(&mgmt_cb, net_mgmt_event_handler, EVENT_MASK);
net_mgmt_add_event_callback(&mgmt_cb);
C

Automatic connection feature

The Wi-Fi management extension library adds an automatic connect feature to the Wi-Fi stack, by using the NET_REQUEST_WIFI_CONNECT_STORED command in net_mgmt().

Add the library to your application through the following Kconfig

CONFIG_WIFI_MGMT_EXT=y
Kconfig

Include the header file for the library in the main.c file of your application

#include <net/wifi_mgmt_ext.h>
C
struct net_if *iface = net_if_get_first_wifi();
int err = net_mgmt(NET_REQUEST_WIFI_CONNECT_STORED, iface, NULL, 0);
if (err) {
	LOG_ERR("Auto-connecting to Wi-Fi failed, err: %d", err);
	return ENOEXEC;
}
C

Important

Please note that although this is the most configurable way to request a Wi-Fi connection, since you can configure struct wifi_connect_req_params, it requires inputting Wi-Fi credentials into the application firmware and is therefore not secure and not recommended in production, but rather for development purposes. We will take a look at a more secure way to provision the network credentials in Exercise 2 of this lesson.

Make sure to Log in or Register to save your progress

Back
Next
Register an account
Already have an account? Log in
(All fields are required unless specified optional)

  • 8 or more characters
  • Upper and lower case letters
  • At least one number or special character

Forgot your password?
Enter the email associated with your account, and we will send you a link to reset your password.