The latest development version of this page may be more current than this released 0.4.3 version.

Net manager

Introduction

Net manager provides users with a unified network management API. By shielding the differences in the underlying protocol stack, it encapsulates complex WiFi, network protocol stack, and other component interfaces; providing a simple and fast way to connect and configure the network.

Function List

Quick Network

Quick Start softAP

General Network Management

Function Overview

Quick Network Connection: Provides a simple way to connect to WiFi. Users only need to provide SSID and Password. Net Manager handles WiFi and network protocol stack initialization, WiFi connection, DHCP request, and reconnection. Users only need to wait for the device to obtain an IP address before starting network data transmission.

Quick softAP: Provides a quick start softAP feature. Users only need to specify SSID and Password to quickly start softAP and DHCP server functionalities.

General Network Management: Provides basic network configuration and query functions for IP address, MAC address, DHCP server, DHCP, DNS, and other network features.

Framework Model

Net manager mainly provides two parts of functionality:

Encapsulates WiFi and network protocol stack capabilities, providing simple and convenient interfaces, allowing users to quickly connect to the network and start network data transmission.

Encapsulates unified network management interfaces, allowing users to query and configure basic network settings without concerning themselves with the network protocol stack.

Recommendation: Net manager comprehensively encapsulates WiFi and network protocol stack functionalities. If users only need simple WiFi connection features, it is recommended to use Net Manager for network configuration. For full WiFi capabilities, it is recommended to disable Net Manager and use the relevant APIs provided by WM_WiFi to implement connection features. If users only need simple WiFi connection features, it is recommended to use Net Manager for network configuration.
For full WiFi capabilities, it is recommended to disable Net Manager and use the relevant APIs provided by WM_WiFi to implement connection features.

Net manager Configuration

WiFi Station Configuration

Configuration Item	Description
COMPONENT_NM_WIFI_STA_ENABLED	Net Manager WiFi station feature enable switch. After enabling, users can call the `wm_nm_start_wifi_station` function to quickly connect to the network.
COMPONENT_NM_WIFI_STA_ENABLED	Net manager WiFi station auto-reconnect feature. After enabling, Net Manager will handle WiFi reconnection.
NM_STA_RECONNECT_INTERVAL	WiFi station reconnection interval, default is 1000 milliseconds.

WiFi SoftAP Configuration

Configuration Item	Description
COMPONENT_NM_WIFI_SOFTAP_ENABLED	Net manager WiFi softAP enable switch. After enabling, users can call the `wm_nm_start_wifi_softap` function to quickly start the softAP feature.
NM_WIFI_SOFTAP_CHANNEL	Net Manager softAP channel selection, default is “auto”. If both softAP and station modes are started simultaneously, it is recommended to configure auto. Otherwise, if the softAP and station channels are not consistent, some functions may fail.
NM_WIFI_SOFTAP_MAX_STA_CONN	Specifies the maximum number of connections supported by softAP. By default, it supports up to 8 station connections.

DHCP Server Configuration

Configuration Item	Description
NM_DHCPS_IP	DHCP server IP address.
NM_DHCPS_NETMASK	DHCP server IP address mask.
NM_DHCPS_GATEWAY	DHCP server gateway address.
NM_DHCPS_START_IP	Start IP address assigned by DHCP server, needs to be in the same subnet as NM_DHCPS_IP.
NM_DHCPS_LEASE_TIME	IP lease time assigned by DHCP server, in seconds.

Main Features

Quick Network Connection

WiFi station State Machine

When users call wm_nm_start_wifi_station , Net Manager will start the WiFi connection and network protocol stack initialization, and request an IP address from the router.

After calling wm_nm_start_wifi_station , you can synchronously wait for the IP address allocation flag in the program. Once the device obtains the IP address, users can start network data transmission. Example:

wm_nm_wifi_station_cfg_t cfg = { "ssid", "password" };
wm_nm_start_wifi_station(&cfg);
while (wm_nm_get_wifi_station_state() != WM_NM_WIFI_STA_GOT_IP) {
    vTaskDelay(10);;
}
wm_log_info("wifi station start success, network is ready!");

Additionally, users need to pay attention to the WM_NM_EV event WM_NM_WIFI_STA_LOST_IP. If a WiFi disconnection or other network anomalies occur during communication, Net Manager will push the WM_NM_WIFI_STA_LOST_IP event. Users need to wait for the network to reconnect before resuming data transmission.

/** WM_NM_EV event response function */
static void wm_nm_event_handle(wm_event_group_t group, int event, void *data, void *priv)
{
    switch (event) {
        case WM_NM_WIFI_STA_GOT_IP:
        {
            wm_log_info("net manager got IP");
            break;
        }
        case WM_NM_WIFI_STA_LOST_IP:
        {
            wm_log_error("net manager lost IP, waiting for WiFi reconnection");
            break;
        }
        default:
            break;
    }
}

/** Register WM_NM_EV event response function */
wm_event_add_callback(WM_NM_EV, WM_EVENT_ANY_TYPE, wm_nm_event_handle, NULL);

If users need to disconnect the WiFi connection, they can call wm_nm_stop_wifi_station to disconnect and release resources.

wm_nm_stop_wifi_station();

Quick Start softAP

When users need to enable softAP, they can call wm_nm_start_wifi_softap, which will automatically initialize WiFi and the network protocol stack, and start the DHCP server. After calling wm_nm_start_wifi_softap , you can synchronously wait for the WM_NM_WIFI_AP_READY flag.

wm_nm_wifi_softap_cfg_t cfg = { "wm_ssid", "password" };
wm_nm_start_wifi_softap(&cfg);
while (wm_nm_get_wifi_softap_state() != WM_NM_WIFI_AP_READY) {
    vTaskDelay(10);;
}

Similarly, users can listen for the WM_NM_EV event WM_NM_WIFI_AP_ASSIGNED_IP_ID to detect the joining of a station.

/** WM_NM_EV event response function */
static void wm_nm_event_handle(wm_event_group_t group, int event, void *data, void *priv)
{
    static wm_app_msg_t app_msg;
    switch (event) {
        case WM_NM_WIFI_AP_READY:
        {
            wm_log_info("softAP is ready");
            break;
        }
        case WM_NM_WIFI_AP_ASSIGNED_IP_ID:
        {
            wm_log_info("assigned IP to staion");
            break;
        }
        default:
        {
            break;
        }
    }
}

/** Register WM_NM_EV event response function */
wm_event_add_callback(WM_NM_EV, WM_EVENT_ANY_TYPE, wm_nm_event_handle, NULL);

If users need to stop the softAP, they can call wm_nm_stop_wifi_softap to stop the softAP and release resources.

wm_nm_stop_wifi_station();

General Network Management

Finding Net Manager Handles

Net manager provides basic network configuration interfaces. Users can query or set related parameters through the corresponding APIs.

Net Manager API operations depend on wm_nm_netif_t, which can be obtained as follows:

/** Iterate through all netif */
for (wm_nm_netif_t netif = wm_nm_get_netif(); netif != WM_NM_INVALID_NETIF; netif = wm_nm_get_next_netif(netif)) {
}

/** Query WiFi station netif, note that a netif can only be queried after WiFi connection */
wm_nm_netif_t netif = wm_nm_get_netif_by_name(WIFI_STATION_NETIF_NAME);

/** Query WiFi softAP netif, note that a netif can only be queried after softAP startup */
wm_nm_netif_t netif = wm_nm_get_netif_by_name(WIFI_SOFTAP_NETIF_NAME);

Configuring IPv4 Addresses

Set a static IPv4 address for the WiFi station. Note that setting a static IPv4 address will disable DHCP functionality:

wm_netif_ip_info_t ip_info      = { 0 };
ip_info.ip.u_addr.ip4.addr      = inet_addr("192.168.1.10");    /** Set IPv4 address */
ip_info.netmask.u_addr.ip4.addr = inet_addr("255.255.255.0");   /** Set IPv4 network mask */
ip_info.gw.u_addr.ip4.addr      = inet_addr("192.168.1.1");     /** Set IPv4 gateway address */
wm_nm_set_netif_ip_info(wm_nm_get_netif_by_name(WIFI_STATION_NETIF_NAME), &ip_info);

If you need to reopen the DHCP function of WiFi station, you need to clear the static IPv4 address in advance before enabling the DHCP function:

wm_netif_ip_info_t ip_info      = { 0 };
ip_info.ip.u_addr.ip4.addr      = 0;    /** Clear static IPv4 address */
ip_info.netmask.u_addr.ip4.addr = 0;
ip_info.gw.u_addr.ip4.addr      = 0;
wm_nm_set_netif_ip_info(wm_nm_get_netif_by_name(WIFI_STATION_NETIF_NAME), &ip_info);
wm_nm_set_netif_ip_info(wm_nm_get_netif_by_name(WIFI_STATION_NETIF_NAME), &ip_info);
wm_nm_start_netif_dhcpc(wm_nm_get_netif_by_name(WIFI_STATION_NETIF_NAME));

Configuring DHCP Functionality

Net Manager supports users to configure DHCP server related parameters, including server IP address, network mask, gateway IP address, assigned starting IP address, and duration of assigned IP. Note that the server IP address, gateway IP address, and assigned starting IP address need to be on the same subnet:

wm_nm_netif_t netif;
wm_nm_dhcps_option_t dhcps_option = { 0 };

netif = wm_nm_get_netif_by_name(WIFI_SOFTAP_NETIF_NAME); /** Query softAP handle */

dhcps_option.lease_time = 7200;                         /** Write the duration of IP allocation */
dhcps_option.server_ip  = inet_addr("192.168.8.1");     /** Write the server IP address */
dhcps_option.start_ip   = inet_addr("192.168.8.100");   /** Write network mask */
dhcps_option.ip_mask    = inet_addr("255.255.255.0");   /** Write gateway IP address */
dhcps_option.gateway    = inet_addr("192.168.8.1");     /** Write the starting IP address for allocation */
dhcps_option.dns1       = inet_addr("8.8.8.8");         /** Write DNS primary address */
dhcps_option.dns2       = inet_addr("114.114.114.114"); /** Write backup DNS address */

wm_nm_set_netif_dhcps_option(netif, &dhcps_option); /** Set DHCP server parameters */
wm_nm_start_netif_dhcps(netif);                     /** Start DHCP server */

matters needing attention

Warning

It is not recommended to mix Net Manager with WiFi API. If only simple networking is needed, it is recommended to use Net Manager; Otherwise, please close the Net Manager component and directly call the WiFi API and network protocol stack API

应用实例

Please refer to the SDK for basic examples of using net manager for wifi stations: examples/network/net_manager/wifi_station/ 工程

Please refer to the SDK for basic examples of using net manager’s wifi softAP: examples/network/net_manager/wifi_softap/ 工程