This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

WiFi

WiFi Programming Model

The WiFi program can be seen as a black box that cannot perceive upper layer code such as TCP/IP protocol stack, application tasks, event tasks, etc. Usually, application tasks (code) are responsible for calling WiFi program APIs to initialize WiFi. WiFi triggers WPA callbacks, and WPA triggers WiFi events. Then the WiFi program receives and processes WPA data, and the application will receive a response afterwards.

WiFi Connection Configuration

The WiFi connection configuration mainly consists of the following parts:

WiFi tx buf number

This is the number of transmission buffers in the WiFi MAC layer, mainly used to store data that has not yet been sent by the MAC Users can modify it according to their actual needs.

WiFi rx buf number

This is the number of receiving buffers in the WiFi MAC layer, mainly used to store data received by the MAC layer that has not yet been sent to the application layer. Users can modify it according to their actual needs.

WiFi Initialization

Before using WiFi, it is necessary to perform initialization by calling the wm_wifi_init() function.

WiFi Scanning Mode

Only the station or station/AP coexistence mode supports the wm_wifi_scan_start() API.

Scan Type

Pattern	Description
Active scanning	Scan by sending a probe request. This mode is the default scanning mode.
Passive scanning	Do not send probe requests. Jump to a specific channel and wait for the beacon. The application can enable passive scanning through the `wm_wifi_scan_config_t` field in `wm_wifi_scan_type_t`.
Full channel scanning	When the `channel` in `wm_wifi_scan_config_t` is 0, the current mode is full channel scanning.
Specific channel scanning	When the `channel` in `wm_wifi_scan_config_t` field is 1-14, the current mode is fast scan.

Scan configuration

The scan type and other scan properties are configured through the function wm_wifi_scan_start() The table below provides a detailed description of the field information for the function wm_wifi_scan_config_t .

Field	Description
ssid	If the value of this field is not NULL, only APs with the same SSID value can be scanned.
bssid	If the value of this field is not NULL, only APs with the same BSSID value can be scanned.
channel	If the value of this field is 0, a full channel scan will be performed; On the contrary, scanning will be conducted for specific channels.
show_hidden	If the field value is 0, this scan will ignore APs with hidden SSIDs; On the contrary, these APs will also be considered as normal APs during scanning.
scan_type	If the value of this field is `WM_WIFI_SCAN_TYPE_ACTIVE` ; The field value is `WM_WIFI_SCAN_TYPE_PASSIVE` which will be considered as passive scanning.
scan_time	This field is used to control the scanning time for each channel. During passive scanning, the scan_time.assive field is responsible for specifying the scanning time for each channel. When actively scanning, the scanning time for each channel is shown in the following list. Among them, min represents scan_time-active_min, and max represents scan_time-active_max. min=0, max=0：The scanning time for each channel is 120 ms. min>0, max=0：The scanning time for each channel is 120 ms. min=0, max>0：The scanning time for each channel is max ms. min>0, max>0：The minimum scanning time for each channel is min ms. If no AP is found during this period, it will jump to the next channel. If an AP is found during this period, the scanning time for that channel is max ms. If you want to improve Wi Fi scanning performance, you can modify the above two parameters.
home_chan_dwell_time	The time spent scanning between consecutive channels in the home channel

Event processing stage after scanning completion

When all channel scans are completed, it will generate WM_EVENT_WIFI_SCAN_DONE envent.

The event callback function of the application informs that the application task has received the WIFI_EVENT_SCAN_DONE event. Calling the function wm_wifi_scan_get_ap_num() to obtain the number of APs found in this scan. Then, allocate enough transaction slots and call the function wm_wifi_scan_get_ap_records() to obtain AP records. Please note that after the scan is completed, please call the function wm_wifi_scan_get_ap_records() as soon as possible to retrieve AP records. The records will be retained for a period of time before being automatically released, and can be retrieved repeatedly before that.

WiFi STA mode

STA connection configuration

Call the wm_wifi_set_config() function to configure STA. The STA mode can be configured with the following contents:

Field	Description
ssid	SSID of the target AP field.
password	The password for the target AP.
scan_method	Perform all channel scans or quick scans.
bssid_set	Whether to set the MAC address of the target AP. Generally speaking, the bssid_det of station_comfig needs to be set to 0, only when the MAC address of the AP is set to 1.
bssid	The MAC address of the target AP.
channel	The channel of the target AP. Set to 1~13, start scanning from the specified channel, and then connect to the AP. If the channel of the AP is unknown, set it to 0.
listen_interval	Set the listening interval for receiving beacons when VNet WIFI_S_SMAXVNet, in units of AP beacon interval. If set to 0, the default is 10.
sort_method	Sort the connected APs in the list by RSSI or secure mode.
threshold	When setting sort_method, only APs with authentication modes that are more secure than the selected authentication mode and have signals stronger than the minimum RSSI will be used.
pmf_cfg	Configure a protection management framework. It will be released in the RSN feature of RSN IE.

Usually, configuration is required before establishing a WiFi connection. But if you have already saved the configuration in ref: NVS <nvs> or want to save it, you don’t need to configure it on the next connection, which is also possible.

STA Connection

Call the wm_wifi_connect() function to connect to an AP. If the connection is successful, the WM_EVENT_WIFI_STA_CONNECTED event will be returned, and then the event task will start the DHCP client service, ultimately triggering the DHCP program. If the connection fails for reasons such as incorrect password, channel error, or AP not found, the WM_EVENT_WIFI_STA_DISCONNECTED event will be returned along with the corresponding failure reason.

STA Obtaining IP

Once the DHCP client initialization is complete, WiFi will enter the IP acquisition stage. If WiFi successfully receives an IP address from the DHCP server, the WM_EVENT_WIFI_STA_GOT_IP or WM_EVENT_WIFI_STA_GOT_IP6 event will be triggered, indicating a successful connection to the AP.

STA Disconnection

You can actively disconnect the WiFi by calling the wm_wifi_disconnect() function. WiFi can also disconnect for reasons such as AP power failure or weak RSSI, which will generate a WM_EVENT_WIFI_STA_DISCONNECTED event.

WiFi SoftAP Mode

SoftAP Configuration

Call the wm_wifi_set_config() function to configure WiFi. The AP mode configuration options are as follows:

Field	Description
ssid	The SSID of the SoftAP. If ssid_len` is 0, it must be a null-terminated string. Otherwise, the length is set according to ssid_len.
password	The password for the SoftAP.
ssid_len	Optional SSID field length.
channel	The channel for the SoftAP.
authmode	The authentication mode for the SoftAP.
ssid_hidden	Whether to broadcast the SSID. Default is 0, broadcast SSID.
max_connection	Maximum number of STA connections allowed. Default is 4, maximum is 8.
beacon_interval	Beacon interval, should be a multiple of 100. Unit: TU (time unit, 1 TU = 1024 us). Range: 100 ~ 60000. Default value: 100.
pairwise_cipher	Pairwise cipher for the SoftAP, from which the group cipher will be derived.

Configuration is typically done before creating the SoftAP. However, if the configuration has already been saved in ref : NVS <nvs>, or you want to save the configuration so that it doesn’t need to be set again on the next connection, this is also possible.

SoftAP Start

Call the wm_wifi_ap_start() function to start the SoftAP. If the SoftAP starts successfully, the WM_EVENT_WIFI_AP_START event will be returned. If it fails to start for reasons such as configuration errors or hardware damage, the WM_EVENT_WIFI_AP_STOP event will be returned along with the corresponding failure reason.

SoftAP Connection

Once a STA connects to the SoftAP, the WM_EVENT_WIFI_AP_STACONNECTED event will be returned, and after successfully assigning an IP to the STA, the WM_EVENT_WIFI_AP_STAIPASSIGNED event will be triggered. If the STA disconnects for any reason, the WM_EVENT_WIFI_AP_STADISCONNECTED event will be returned.

SoftAP Stop

You can actively stop the SoftAP by calling the wm_wifi_ap_stop() function. If the SoftAP is stopped due to abnormal conditions such as power failure or restart, the WM_EVENT_WIFI_AP_STOP event will be triggered.

WiFi Event Description

The following are events in WiFi:

Event	Description
WM_EVENT_WIFI_SCAN_DONE	WiFi has completed scanning for APs.
WM_EVENT_WIFI_STA_CONNECTED	WiFi has completed scanning for APs.
WM_EVENT_WIFI_STA_DISCONNECTED	STA has disconnected from an AP.
WM_EVENT_WIFI_STA_BSS_RSSI_LOW	STA’s signal strength to the AP is too low.
WM_EVENT_WIFI_STA_BEACON_TIMEOUT	STA timed out while receiving the AP’s beacon frame.
WM_EVENT_WIFI_AP_START	SoftAP has started.
WM_EVENT_WIFI_AP_STOP	SoftAP has stopped.
WM_EVENT_WIFI_AP_STACONNECTED	APSTA mode has successfully started.
WM_EVENT_WIFI_AP_STADISCONNECTED	APSTA mode has successfully stopped.
WM_EVENT_WIFI_STA_GOT_IP	STA has obtained an IPv4 IP from the AP.
WM_EVENT_WIFI_STA_GOT_IP6	STA has obtained an IPv6 IP from the AP.
WM_EVENT_WIFI_STA_LOST_IP	STA has lost the IPv4 IP from the AP.
WM_EVENT_WIFI_STA_LOST_IP6	STA has lost the IPv6 IP from the AP.
WM_EVENT_WIFI_AP_STAIPASSIGNED	SoftAP has assigned an IP to a connected STA.
WM_EVENT_WIFI_ONESHOT_SCAN_DONE	OneShot mode scan completed.
WM_EVENT_WIFI_ONESHOT_FOUND_CHANNEL	OneShot mode found the channel.
WM_EVENT_WIFI_ONESHOT_GOT_SSID_PSWD	OneShot mode obtained the SSID and password.
WM_EVENT_WIFI_ONESHOT_GOT_CUSTOM_DATA	OneShot mode obtained custom data.
WM_EVENT_WIFI_ONESHOT_SEND_REPLY_DONE	OneShot mode sent ACK completed.

WiFi Error Codes

WiFi APSTA Mode

Other operations are the same as for STA and SoftAP modes and will not be further explained here.

WiFi Sniffer Mode

WiFi Sniffer mode can be enabled by wm_wifi_set_promiscuous() .

The received frame consists of frame information and frame data. The frame information includes the following:

Field	Description
rssi	RSSI of the packet. Unit: dBm.
rate	PHY rate encoding of the packet
sig_mode	0 for non-HT (11bg) packets; 1 for HT (11n) packets.
mcs	Modulation and Coding Scheme.
cwb	Channel bandwidth of the packet.
smoothing	———-。
not_sounding	———-。
aggregation	0 for MPDU packets; 1 for AMPDU packets.。
stbc	0 for non-STBC packets; 1 for STBC packets.
fec_coding	Indicates whether the packet is LDPC-encoded in 11n.
sgi	Short Guard Interval.
noise_floor	Background noise level of the RF module. Unit: 0.25 dBm.
ampdu_cnt	Number of aggregated frames.
channel	Primary channel on which the packet was received.
secondary_channel	Secondary channel on which the packet was received.
rx_state	Status of the packet.
timestamp	Timestamp.
sig_len	Length of the packet excluding FCS.

WiFi OneShot

OneShot is a proprietary one-click network configuration feature from Winner Micro, also supporting WeChat AIRKISS one-click configuration. Due to compatibility issues with various phones and APs and the uncertain nature of wireless environments, WiFi one-click configuration cannot guarantee a 100% success rate. Therefore, it is currently recommended to use the BLE + SoftAP method for configuration.

OneShot currently supports both Android and iOS clients. The download link for the APP will be provided later.