Introduction

Overview

This chip contains three cores:

• LP: low power processor, KM0, and the firmware of Wi-Fi works on it.

• NP: Network processor, KM4, and the driver of Wi-Fi works on it.

• AP: Application processor, CA32, and the FullMAC works on it. The FullMAC driver is an adaptive driver between cfg80211 in Linux kernel and INIC device in FreeRTOS.

Architecture

The FullMAC is new Wi-Fi driver based on the CFG80211 interface. So it supports wpa_supplicant, hostapd, iwconfig, and so on. The driver sends the command to IPC INIC device on KM4 with IPC message and receives the event from IPC INIC device. Therefore, the FullMAC driver will convert the command and structure from CFG80211 to the IPC INIC commands and data type, and the events from IPC INIC device also are converted the format of CFG80211 and reported to the Linux kernel.

There are two IPC messages in FullMAC driver. One is the API message, and another is the data message. The API message is used to send command or receive event to manage the Wi-Fi. The data message is used to send or receive the data frame of Wi-Fi. So the former is low speed and the latter is high speed.

Configuration

Configuration in Kernel

Run the following command in build directory of project to open the configuration of kernel.

bitbake virtual/kernel -c menuconfig

Enabling Ameba IPC

The Wi-Fi driver in Linux is based on Ameba IPC’s driver, so the IPC’s driver must be enabled for Wi-Fi driver. Of course, this option is enabled if you choose Fullmac for rtl8730e to yes.

Device Drivers  --->
   <*> Drivers for Realtek  --->
      [*]   Ameba IPC

Enabling CFG80211

This configuration is base of Wi-Fi driver based on cfg80211, and they are enabled by default.

[*] Networking support  --->
   -*-   Wireless  --->
      <*>   cfg80211 - wireless configuration API
      [*]     enable powersave by default
      [*]     support CRDA
      [*]     cfg80211 wireless extensions compatibility

Enabling FullMAC Driver

This configuration is used to enable Wi-Fi driver in Linux kernel, and it is enabled by default.

Device Drivers  --->
   <*> Drivers for Realtek  --->
      <*>   CFG80211 WiFi FULLMAC drivers  --->
         <*>   Fullmac for rtl8730e

Function

There are only two ports in Wi-Fi driver, wlan0 and wlan1. The wlan0 must work in station mode only and the wlan1 must work in access point (AP) mode only.

Initialization

The prerequisite that all APIs are valid in Linux, is the initialization of Wi-Fi IOCTL and event.

Initialization of IOCTL

None.

Initialization of Event

None.

Wi-Fi Data Structures

Data Structures	Introduction
<_cus_ie>	The structure is used to set Wi-Fi custom IE list, and type match CUSTOM_IE_TYPE. The IE will be transmitted according to the type.
<rtw_ssid_t>	The structure is used to describe the SSID.
<rtw_mac_t>	The structure is used to describe the unique 6-byte MAC address.
<rtw_network_info_t>	The structure is used to describe the station mode setting about SSID, security type and password, etc., used when connecting to an AP.
<rtw_scan_param_t>	The structure is used to describe the scan parameters used for scan, including SSID, channel, user callback, etc.
<rtw_scan_result_t>	The structure is used to describe the scan result of the AP.
<rtw_wifi_setting_t>	The structure is used to store the Wi-Fi setting gotten from Wi-Fi driver.
<rtw_mac_filter_list_t>	The structure is used to describe the mac filter list.
<rtw_softap_info_t>	The structure is used to describe the setting about SSID, security type, password, and default channel, used to start AP mode
<psk_info>	The structure is used to describe the SSID, passphrase and PSK which are used to get or store PSK info in the driver.
<rtw_sw_statistics_t>	The structure is used to describe the software statistics of Wi-Fi transmit and receive packets
<rtw_phy_statistics_t>	The structure is used to describe the PHY statistic info, which includes RSSI, SNR, false alarm from PHY layer, TRX counts from MAC layer
<raw_data_desc_t>	The structure is used to describe the raw frame to send by the user, including buffer address and length of the raw frame, and initial transmission rate which this frame will use.
<wifi_user_conf>	The structure is used to describe some configuration of Wi-Fi driver which can be controlled by the user.

Wi-Fi APIs

System APIs

API	Introduction
<wifi_on>	Enable Wi-Fi.
<wifi_off>	Disable Wi-Fi.
<wifi_is_running>	Check if the specified WLAN interface is running
<wifi_set_mode>	Used for switching Wi-Fi mode

wifi_on

Enable Wi-Fi: bring the wireless interface Up.

Parameter	Type	Introduction
<mode>	rtw_mode_t	Decide to enable Wi-Fi in which mode. The optional modes are enumerated in rtw_mode_t.

wifi_off

Disable Wi-Fi.

Parameter: None.

wifi_is_running

Check if the specified interface is up.

Parameter	Type	Introduction
<wlan_idx>	Unsigned char	The idx can be set as WLAN0_IDX or WLAN1_IDX. For STA mode, only use WLAN0_IDX. For softAP mode, use WLAN1_IDX. For concurrent mode, use WLAN0_IDX for STA and WLAN1_IDX for AP.

wifi_set_mode

Parameter	Type	Introduction
<mode>	int	Decide to switch WiFi to which mode, the optional modes are: RTW_MODE_STA RTW_MODE_AP RTW_MODE_STA_AP RTW_MODE_PROMISC

Scan APIs

API	Introduction
<wifi_scan_networks>	Initiate a scan to search for 802.11 networks
<wifi_get_scan_records>	Used to get scan results when RTW_SCAN_REPORT_EACH mode is not configured in scan parameter
<wifi_scan_abort>	Abort ongoing Wi-Fi scan

wifi_scan_networks

Initiate a scan to search for 802.11 networks.

Parameter	Type	Introduction
<scan_param>	rtw_scan_param_t *	Specifies the scan parameters, including scan type, specific SSID, specific channel list, channel scan time, and scan callback. There are two types of scan callback: scan_user_callback scan_report_each_mode_user_callback If registered, scan_user_callback will be executed when the scan is finished and report the total number of scanned APs, and the detailed scanned AP info can be got by calling wifi_get_scan_records. This callback is suitable for a normal asynchronous scan. If registered, scan_report_each_mode_user_callback is used when configuring RTW_SCAN_REPORT_EACH in options of rtw_scan_param, and it will be executed every time a AP is scanned, and the AP info will be directly reported by this callback.
<block>	Unsigned char	Specifies the scan as synchronous or asynchronous. Setting to 1 means synchronous and this API will return until the scan is finished. Setting to 0 means asynchronous and this API will return immediately.

Note

• If this API is called, the scanned APs are stored in Wi-Fi driver dynamic allocated memory, for a synchronous scan or asynchronous scan which does not use RTW_SCAN_REPORT_EACH, these memories will be freed when wifi_get_scan_records() is called.

• When configuring RTW_SCAN_REPORT_EACH, scan_report_each_mode_user_callback() will report NULL to indicate that the scan is done.

• Only one callback function can be chosen to register. Both scan_user_callback() and scan_report_each_mode_user_callback() are not supported to be registered in one scan.

• The scan callback function will be executed in the context of the RTW thread.

• When scanning specific channels, devices with strong signal strength on nearby channels may be detected.

wifi_get_scan_records

Get scan results.

Parameter	Type	Introduction
<AP_num>	unsigned int *	The pointer to the number of scanned AP info which wants to get, and it will be finally set to the number of scanned AP info which can actually get
<scan_buf>	char *	The pointer to the buf where scan result will be stored, the scanned AP info will be stored one by one in form of struct rtw_scan_result_t.

Note

For an asynchronous scan configuring RTW_SCAN_REPORT_EACH, every time an AP is scanned, the AP info will be directly reported through scan_report_each_mode_user_callback() and freed after user callback is executed, thus there is no need to use this function to get the scan result.

wifi_scan_abort

Abort ongoing scan.

Parameter: None.

Note

• This is an asynchronous function and will return immediately. Return value only indicates whether the scan abort command is successfully notified to the driver or not. When the scan is actually aborted, the user callback registered in wifi_scan_networks() will be executed.

• If there is no Wi-Fi scan in progress, this function will just return RTW_SUCCESS and user callback won’t be executed.

Connection APIs

API	Introduction
<wifi_connect>	Join a Wi-Fi network with a specified SSID or BSSID.
<wifi_disconnect>	Disassociates from current Wi-Fi network.
<wifi_is_connected_to_ap>	Check if Wi-Fi has connected to AP before DHCP.
<wifi_get_join_status>	Get latest Wi-Fi join status.
<wifi_get_disconn_reason_code>	Get reason code of latest disassociation or de-authentication.

wifi_connect

Join a Wi-Fi network with a specified SSID or BSSID. Scan for, associate, and authenticate with a Wi-Fi network. On successful return, the system is ready to send data packets.

Parameter	Type	Introduction
<connect_param>	rtw_network_info_t *	Describe the connection setting about SSID or BSSID, security type, password, and scan channel
<block>	unsigned char	Determine the connection is synchronous or asynchronous. Setting to 1 means synchronous connection Setting to 0 means asynchronous connection

Note

• Make sure the Wi-Fi is enabled before invoking this function (wifi_on()).

• The parameter channel and pscan_option in connect_param can be used to perform fast survey on the specified channel during Wi-Fi connection.

• When the channel is set to a specified channel and pscan_option is set to PSCAN_FAST_SURVEY, during Wi-Fi connection, an active scan will be only performed on the specified channel, the active scan will retry at most 8 times with each round interval 25 ms.

• joinstatus_user_callback() in connect_param can be registered to get the real-time join status changes since this callback will be executed every time join status is changed.

wifi_disconnect

Disassociates from current Wi-Fi network.

Parameter: None.

wifi_is_connected_to_ap

Check if Wi-Fi has connected to AP before DHCP.

Parameter: None.

wifi_get_join_status

Get the latest Wi-Fi join status.

Parameter: None.

Note

Wi-Fi join status will be set during Wi-Fi connection and Wi-Fi disconnection.

wifi_get_disconn_reason_code

Present the reason code of the latest disassociation or de-authentication.

Parameter	Type	Introduction
<reason_code>	unsigned short	The pointer of reason code.

Channel APIs

API	Introduction
<wifi_set_channel>	Set the listening channel on STA interface.
<wifi_get_channel>	Get the current channel on STA interface.

wifi_set_channel

Set the listening channel on STA interface.

Parameter	Type	Introduction
<channel>	int	The desired channel.

Note

Do not need to call this function for STA mode Wi-Fi driver, since it will be determined by the channel from the received beacon.

wifi_get_channel

Get the current channel on STA interface.

Parameter	Type	Introduction
<channel>	int *	A pointer to the variable where the channel value will be written.

Power Save API

API	Introduction
<wifi_set_powersave_mode>	Set Wi-Fi power save mode.

wifi_set_powersave_mode

Set Wi-Fi power save mode, including IPS mode and LPS mode.

• IPS is the abbreviation of Inactive Power Save mode. Wi-Fi automatically turns RF off if it is not associated with AP.

• LPS is the abbreviation of Leisure Power Save mode. Wi-Fi automatically turns RF off during the association with AP if traffic is not busy, while it also automatically turns RF on to listen to the beacon of the associated AP.

Parameter	Type	Introduction
<ips_mode>	u8	The desired ips mode, which can be: IPS_MODE_NONE: leave IPS IPS_MODE_NORMAL: enable to enter IPS IPS_MODE_RESUME: resume to the last IPS mode which recorded in Wi-Fi driver
<lps_mode>	u8	The desired LPS mode, which can be: LPS_MODE_NONE: leave LPS LPS_MODE_NORMAL: enable to enter LPS LPS_MODE_RESUME: resume to the last LPS mode which recorded in Wi-Fi driver

AP Mode APIs

API	Introduction
<wifi_start_ap>	Trigger Wi-Fi driver to start an infrastructure Wi-Fi network.
<wifi_get_associated_client_list>	Get the associated clients with SoftAP.
<wifi_del_station>	Delete a STA

wifi_start_ap

Trigger Wi-Fi driver to start an infrastructure Wi-Fi network.

Parameter	Type	Introduction
<softAP_config>	rtw_softap_info_t *	The pointer of a structure that stores the softAP configuration.

Note

• Make sure the Wi-Fi is enabled before invoking this function (wifi_on()).

• If an STA interface is active when this function is called, the softAP will start on the same channel as the STA. It will not use the channel provided.

wifi_get_associated_client_list

Get the associated clients with SoftAP.

Parameter	Type	Introduction
<client_list_buffer>	int *	The location where the client list will be stored.
<buffer_length>	unsigned short	The buffer length.

wifi_del_station

Delete an STA in AP mode.

Parameter	Type	Introduction
<wlan_idx>	unsigned char	The WLAN interface index which AP is working on.
<hwaddr>	unsigned char *	The pointer to the MAC address of the STA.

Raw frame Tx API

API	Introduction
<wifi_send_raw_frame>	Send a raw frame.

wifi_send_raw_frame

Parameter	Type	Introduction
<raw_data_desc>	raw_data_desc_t *	The pointer of a descriptor about the raw frame, including the buffer address where the frame is stored, frame length, the initial Tx rate of this frame (the default initial Tx rate will be 1Mbps).

Custom IE APIs

API	Introduction
<wifi_add_custom_ie>	Setup custom IE list.
<wifi_update_custom_ie>	Update the item in Wi-Fi custom IE list.
<wifi_del_custom_ie>	Delete Wi-Fi custom IE list.

Note

These three APIs are only effective on beacon, probe request, and probe response frames.

wifi_add_custom_ie

Setup custom IE list.

Parameter	Type	Introduction
<cus_ie>	void *	Pointer to Wi-Fi CUSTOM IE list.
<ie_num>	int	The number of Wi-Fi CUSTOM IE list.

Note

This API cannot be executed twice before deleting the previous custom IE list.

wifi_update_custom_ie

Update the item in Wi-Fi custom IE list.

Parameter	Type	Introduction
<cus_ie>	void *	Pointer to Wi-Fi CUSTOM IE list.
<ie_index>	int	The number of Wi-Fi CUSTOM IE list.

wifi_del_custom_ie

Delete Wi-Fi custom IE list.

Parameter: None.

Wi-Fi Setting APIs

API	Introduction
<wifi_get_mac_address>	Retrieve the current Media Access Control (MAC) address (or Ethernet hardware address) of the 802.11 devices.
<wifi_get_setting>	Get current Wi-Fi settings from the driver.
<wifi_set_network_mode>	Set the network mode according to the data rate it supported.
<wifi_set_mfp_support>	Set Management Frame Protection Support Capability.
<wifi_set_group_id>	Set group ID of finite cyclic group for SAE transactions.
<wifi_set_pmk_cache_enable>	Enable or disable PMK cache.
<wifi_psk_info_set>	Set PSK-related info to the driver, including SSID, passphrase, PSK.
<wifi_psk_info_get>	Get PSK-related info from the driver, including SSID, passphrase, PSK.
<wifi_get_ccmp_key>	Get encryption CCMP key used by Wi-Fi (STA mode only).
<wifi_get_sw_statistic>	Get the Tx and Rx statistic information which is counted by software.
<wifi_fetch_phy_statistic>	Fetch statistic info about Wi-Fi, including RSSI, SNR, TRX counting from the MAC layer.
<wifi_set_indicate_mgnt>	Configure mode of HW indicating packets (management and data frames) and SW reporting packets to wifi_indication().
<wifi_get_antenna_info>	Get antenna information.
<wifi_get_auto_chl>	Get an auto channel using NMH algorithm.
<wifi_get_band_type>	Get band type.
<wifi_get_tsf_low>	Get Wi-Fi TSF value from Wi-Fi register.

wifi_get_mac_address

Retrieve the current Media Access Control (MAC) address (or Ethernet hardware address) of the 802.11 devices.

Parameter	Type	Introduction
<mac>	char *	Point to the result of the MAC address that will be got.

wifi_get_setting

Get current Wi-Fi settings from the driver.

Parameter	Type	Introduction
<wlan_idx>	unsigned char	The WLAN interface name: WLAN0_IDX WLAN1_IDX
<pSetting>	rtw_wifi_setting_t *	Points to the rtw_wifi_setting_t structure to store the Wi-Fi setting gotten from driver.

wifi_set_network_mode

Set the network mode according to the data rate it supported. The driver works in BGN mode in default after driver initialization. This function is used to change wireless network mode for station mode before connecting to AP.

Parameter	Type	Introduction
<mode>	rtw_network_mode_t	Network mode to set: RTW_NETWORK_B RTW_NETWORK_BG RTW_NETWORK_BGN

wifi_set_mfp_support

Set Management Frame Protection Support.

Parameter	Type	Introduction
<value>	unsigned char	The value could be: NO_MGMT_FRAME_PROTECTION: not support MGMT_FRAME_PROTECTION_OPTIONAL: capable MGMT_FRAME_PROTECTION_REQUIRED: required

wifi_get_group_id

Set group ID of finite cyclic group for SAE transactions.

Parameter	Type	Introduction
<value>	unsigned char	Specify the group ID of finite cyclic group for SAE transactions.

wifi_set_pmk_cache_enable

Enable or disable PMK cache.

Parameter	Type	Introduction
<value>	unsigned char	1: enable 0: disable

wifi_psk_info_set

Set PSK (pre-shared key) related information to the driver, including SSID, passphrase, PSK.

Normally used for fast connection to restore the PSK information to the driver after connecting to AP successfully, for shrinking PSK calculation time when the chip is power on again and wants to connect to the same AP.

Parameter	Type	Introduction
<psk_data>	struct psk_info *	The pointer to the structure that will restore PSK-related info.

wifi_psk_info_get

Get PSK-related information from the driver, including SSID, passphrase, PSK.

Normally used for fast connection to get PSK information from the driver and then store this information to Flash.

Parameter	Type	Introduction
<psk_data>	struct psk_info *	The pointer to the structure that will restore PSK-related info.

wifi_get_ccmp_key

Get encryption CCMP key used by Wi-Fi (STA mode only).

Parameter	Type	Introduction
<uncst_key>	unsigned char *	The location where the CCMP TK (temporary key) will be stored.
<group_key>	unsigned char *	The location where the CCMP GTK (group key) will be stored.

wifi_get_sw_statistic

Show the Tx and Rx statistic information which is counted by software (Wi-Fi driver, not PHY layer)

Parameter	Type	Introduction
<idx>	unsigned char	Specify the WLAN interface index from which WLAN interface the statistic info will be got
<sw_statistics>	rtw_sw_statistics_t *	The pointer to the structure where store the software statistic

wifi_fetch_phy_statistic

Fetch statistic info from WLAN interface 0, including RSSI, SNR, TRX counting from the MAC layer.

Parameter	Type	Introduction
<phy_statistic>	rtw_phy_statistics_t *	The pointer to the structure that stores the PHY statistic

wifi_set_indicate_mgnt

Configure mode of HW indicating packets (management and data frames) and SW reporting packets to wifi_indication().

Parameter	Type	Introduction
<enable>	int	Value of enable could be: WIFI_INDICATE_DISABLE: disable mode (default), HW only indicates BSSID-matched packets and SW doesn’t report. WIFI_INDICATE_NORMAL: HW only indicates BSSID-matched packets and SW reports. WIFI_INDICATE_WILD: HW indicates all packets and SW reports.

wifi_get_antenna_info

Get antenna information.

Parameter	Type	Introduction
<antenna>	unsigned char *	Points to store the antenna value gotten from the driver. 0: main 1: aux

wifi_get_auto_chl

Get an auto channel by NMH algorithm, the selected channel is in the return value.

Parameter	Type	Introduction
<wlan_idx>	unsigned char	The WLAN interface index, could be: WLAN0_IDX WLAN1_IDX
<channel_set>	unsigned char *	The pointer to the channel set which auto channel will be selected from.
<channel_num>	unsigned char	The number of channels in channel set

wifi_get_band_type

Get Wi-Fi band type, the value of band_type will be stored in the return value, and it can be:

• WL_BAND_2_4G: only 2.4G supported

• WL_BAND_5G: only 5G supported

• WL_BAND_2_4G_5G_BOTH: both 2.4G and 5G supported

Parameter: None.

wifi_get_tsf_low

Get TSF value from Wi-Fi register.

Parameter	Type	Introduction
<port>	u32	Specify the Wi-Fi port which could be 0 or 1. For STA mode and SoftAP mode, use port 0. For concurrent mode, STA uses port 0 and AP uses port 1.

Wi-Fi Indication APIs

API	Introduction
<init_event_callback_list>	Initialize the event callback list.
<wifi_reg_event_handler>	Register the event listener.
<wifi_unreg_event_handler>	Un-register the event listener.

init_event_callback_list

Initialize the event callback list.

Parameter: None.

Note

Make sure this function has been invoked before using the event handler-related mechanism.

wifi_reg_event_handler

Register the event listener.

Parameter	Type	Introduction
<event_cmds>	unsigned int	The event command number indicated.
<handler_func>	rtw_event_handler_t	The callback function that will receive and process the event.
<handler_user_data>	void *	User-specific data that will be passed directly to the callback function.

Note

Setting the same even_cmds with empty handler_func will unregister the event_cmds.

wifi_unreg_event_handler

Un-register the event listener.

Parameter	Type	Introduction
<event_cmds>	unsigned int	The event command number indicated.
<handler_func>	rtw_event_handler_t	The callback function that will receive and process the event.

Promisc APIs

API	Introduction
<wifi_enter_promisc_mode>	Set Wi-Fi to promiscuous mode.
<wifi_set_promisc>	Enable or disable promiscuous callback.
<wifi_init_packet_filter>	Initialize packet filer in promiscuous mode.
<wifi_add_packet_filter>	Add packet filter in promiscuous mode.
<wifi_enable_packet_filter>	Enable filtering packets in promiscuous mode according to the configured.
<wifi_remove_packet_filter>	Remove specified packet filter in promiscuous mode.
<wifi_disable_packet_filter>	Disable filtering packets in promiscuous mode according to the configured.

wifi_enter_promisc_mode

Set Wi-Fi to promiscuous mode.

If Wi-Fi is originally in concurrent mode or SoftAP mode, a mode switch will be performed; if Wi-Fi is originally in STA mode and already connected to AP, the connection to AP will disconnect.

Parameter: None.

wifi_set_promisc

Enable promiscuous callback and enable the Wi-Fi driver to receive packets in promisc mode.

Normally usage: use wifi_enter_promisc_mode() to make sure Wi-Fi in correct mode, and use wifi_set_promisc() to enable promisc receiving and promisc callback.

Parameter	Type	Introduction
<enabled>	rtw_rcr_level_t	The value of enabled could be: RTW_PROMISC_DISABLE = 0, disable the promisc receiving RTW_PROMISC_ENABLE = 1, fetch all ethernet packets RTW_PROMISC_ENABLE_1 = 2, fetch only B/M packets RTW_PROMISC_ENABLE_2 = 3, fetch all 802.11 packets RTW_PROMISC_ENABLE_3 = 4, fetch only B/M 802.11 packets
<callback>	void(*callback)(unsigned char *,unsigned int, void *)	The callback function that will receive and process the network data. The input parameter is unsigned char *buf, unsigned int buf_len, void *userdata. Buf: points to the frame bul_len: the length of the frame userdata: points to the frame info which is in the format of structure ieee80211_frame_info.
<len_used>	unsigned char	If len_used is set to 1, encryption type can be got from userdata in callback. Also, beacon and probersp will be collected in Wi-Fi driver, and encryption type of the BSSID will be recorded, so that when report frame uses the callback, the parameter userdata of callback can carry this encryption info to the user. The encryption type carried in userdata could be: RTW_ENCRYPTION_UNKNOWN = 0 RTW_ENCRYPTION_OPEN = 1 RTW_ENCRYPTION_WEP40 = 2 RTW_ENCRYPTION_WPA_TKIP = 3 RTW_ENCRYPTION_WPA_AES = 4 RTW_ENCRYPTION_WPA2_TKIP = 5 RTW_ENCRYPTION_WPA2_AES = 6 RTW_ENCRYPTION_WPA2_MIXED = 7 RTW_ENCRYPTION_WEP104 = 9 RTW_ENCRYPTION_UNDEF = 0Xff

wifi_init_packet_filter

Initialize packet filer in promiscuous mode.

Parameter: None.

wifi_add_packet_filter

Add a packet filer to the list in promiscuous mode.

Parameter	Type	Introduction
<filter_id>	unsigned char	Filter ID to recognize the filter
<patt>	rtw_packet_filter_pattern_t *	Point to the filter pattern
<rule>	rtw_packet_filter_rule_t	The value could be: RTW_POSITIVE_MATCHING = 0: accept the frame if matching with this pattern, otherwise discard the frame RTW_NEGATIVE_MATCHING = 1: discard the frame if matching with this pattern, otherwise accept the frame

Note

This is software filter in promisc mode.

wifi_remove_packet_filter

Remove the specified packet filer from the list in promiscuous mode.

Parameter	Type	Introduction
<filter_id>	unsigned char	The filter ID of the specified packet filter which will be removed from the filter list.

wifi_enable_packet_filter

Enable the specified packet filter in promiscuous mode.

Parameter	Type	Introduction
<filter_id>	unsigned char	The filter ID of the specified packet filter which will be enabled

wifi_disable_packet_filter

Disable the specified packet filter in promiscuous mode.

Parameter	Type	Introduction
<filter_id>	unsigned char	The filter ID of the specified packet filter which will be disabled

Mac filter APIs

API	Introduction
<wifi_init_mac_filter>	Initialize MAC address filter list.
<wifi_add_mac_filter>	Add MAC address to MAC filter list then this address will be rejected during authentication
<wifi_del_mac_filter>	Remove MAC address from MAC filter list

Note

These APIs should be used only when operating as softAP.

wifi_remove_packet_filter

Initialize MAC address filter list.

Parameter: None.

wifi_add_packet_filter

Add MAC address to MAC filter list then this address will be rejected during authentication

Parameter	Type	Introduction
<hwaddr>	unsigned char *	Point to the MAC address which will be added to the MAC filter list, and this MAC address will be rejected during authentication.

wifi_del_packet_filter

Remove the corresponding MAC address from the MAC filter list

Parameter	Type	Introduction
<hwaddr>	unsigned char *	Point to the MAC address which will be removed from the MAC filter list.

WPS APIs

API	Introduction
<wps_start>	Start WPS enrollee process
<wps_stop>	Stop WPS enrollee process

wps_start

Start WPS enrollee process.

Parameter	Type	Introduction
<wps_config>	u16	WPS configure method: WPS_CONFIG_DISPLAY WPS_CONFIG_KEYPAD WPS_CONFIG_PUSHBUTTON
<pin>	char *	PIN number. Can be set to NULL if using WPS_CONFIG_PUSHBUTTON.
<channel>	u8	Channel. Currently un-used, can be set to 0.
<ssid>	char *	Target network SSID, which can be set to NULL if no target network is specified.

Note

• Before invoking this function, the Wi-Fi should be enabled by calling wifi_on().

• Make sure CONFIG_ENABLE_WPS is enabled in platform_opts.h. After calling wps_start(), the longest time of WPS is 120s. You can call wps_stop() to quit WPS.

wps_stop

Stop WPS enrollee process.

Parameter: None.

Note

Make sure CONFIG_ENABLE_WPS is enabled in platform_opts.h.

STD_WLAN

This is NL80211 version driver and it supports wpa_supplicant and hostapd.

Station Mode

wpa_supplicant

wpa_supplicant is a cross-platform supplicant with support for WPA, WPA2 and WPA3 (IEEE 802.11i). It is the IEEE 802.1X/WPA component that is used in the client stations. It implements key negotiation with a WPA authenticator and it controls the roaming and IEEE 802.11 authentication/association of the wireless driver.

wpa_supplicant.conf

wpa_supplicant is configured using a text file that lists all accepted networks and security policies, including pre-shared keys. See the example configuration file, probably in /etc/wifi, for detailed information about the configuration format and supported fields.

All file paths in this configuration file should use full (absolute, not relative to working directory) path in order to allow working directory to be changed. This can happen if wpa_supplicant is run in the background.

Changes to configuration file can be reloaded be sending SIGHUP signal to wpa_supplicant (killall -HUP wpa_supplicant). Similarly, reloading can be triggered with the wpa_cli reconfigure command.

Configuration file can include one or more network blocks, e.g., one for each used SSID. wpa_supplicant will automatically select the best network based on the order of network blocks in the configuration file, network security level (WPA/WPA2 is preferred), and signal strength.

Below example is two examples for WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work network.

# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
#
# home network; allow all valid ciphers
update_config=1
wowlan_triggers=any

network={
   ssid="home"
   scan_ssid=1
   key_mgmt=WPA-PSK
   psk="very secret passphrase"
}
#
# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
network={
   ssid="work"
   scan_ssid=1
   key_mgmt=WPA-EAP
   pairwise=CCMP TKIP
   group=CCMP TKIP
   eap=TLS
   identity="user@example.com"
   ca_cert="/etc/cert/ca.pem"
   client_cert="/etc/cert/user.pem"
   private_key="/etc/cert/user.prv"
   private_key_passwd="password"
}

If the configuration want to be saved, update_config=1 should be added in the /etc/wifi/wpa_supplicant.conf, or to use command wpa_cli -i wlan0 set update_config 1.

If the enable wowlan function, wowlan_triggers=any should be added in the /etc/wifi/wpa_supplicant.conf, or to use command wpa_cli -i wlan0 set wowlan_triggers any. Otherwise, the supplicant will disconnect from AP when to suspend.

run wpa_supplicant

Below command can run wpa_supplicant on nl80211 interface and wlan0 port. It will use the configuration file /etc/wifi/wpa_supplicant.conf and run in background.

wpa_supplicant -D nl80211 -i wlan0 -c /etc/wifi/wpa_supplicant.conf -B

For more detail, please refer to wpa_supplicant --help or wpa_supplicant wiki.

wpa_cli

wpa_cli is a text-based frontend program for interacting with wpa_supplicant. It is used to query current status, change configuration, trigger events, and request interactive user input.

wpa_cli can show the current authentication status, selected security mode, dot11 and dot1x MIBs, etc. In addition, it can configure some variables like EAPOL state machine parameters and trigger events like reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user interface to request authentication information, like username and password, if these are not included in the configuration. This can be used to implement, e.g., one-time-passwords or generic token card authentication where the authentication is based on a challenge-response that uses an external device for generating the response.

The control interface of wpa_supplicant can be configured to allow non-root user access (ctrl_interface GROUP = parameter in the configuration file). This makes it possible to run wpa_cli with a normal user account.

wpa_cli supports two modes: interactive and command line. Both modes share the same command set and the main difference is in interactive mode providing access to unsolicited messages (event messages, username/password requests).

Interactive mode is started when wpa_cli is executed without including the command as a command line parameter. Commands are then entered on the wpa_cli prompt. In command line mode, the same commands are entered as command line arguments for wpa_cli.

For detail, please refer to wpa_cli.

scan

There is two way to scan based on STA_WLAN.

Scan with iw

Bellow command is uesd to scan on wlan0.

iw wlan0 scan

The following figure shows the result of above command. It prints the detail result of scanned APs.

Scan with wpa_cli

Bellow commands is uesd to scan and get scan result on wlan0.

wpa_cli -i wlan0 scan
wpa_cli -i wlan0 scan_result

The following figure shows the result of above commands. It prints the detail result of scanned APs.

Set ssid and password

Bellow commands is uesd to set SSID and password on wlan0.

wpa_cli -i wlan0
add_network
set_network <network_id> ssid "ssid"
set_network <network_id> psk "password"

If AP is hidden AP, below command is necessary:

set_network <network_id> scan_ssid 1

Or, add scan_ssid=1 in the wpa_supplicant.conf for that hidden AP.

The following figure shows to set the SSID MERCURY_1200_W6 and password 12345678 successfully.

Note

wpa_cli -i wlan0 will enter the console of wpa_cli. All operation is running on wlan0. quit command can quit the console of wpa_cli.

Connect

Bellow commands is used to enable network and select network to connect.

enable_network <network_id>
select_network <network_id>

Note

If a network is stored in wpa_supplicant.conf, the wifi should connect the network automatically after run to wpa_supplicant.

Connect to WEP AP

wpa_supplicant

For WEP, below commands can be used to configure WEP SSID and connect the WEP AP.

# Open WEP key connection (two-message auth; no WPA, no IEEE 802.1X)
set_network id key_mgmt NONE
set_network id wep_key0 "abcde" // ASCII 64bit
set_network id wep_key1 1234567890 // hex 64bit
set_network id wep_key2 "1234567890123" // ASCII 128bit
set_network id wep_tx_keyidx 0 // key id
# Shared WEP key connection (four-message auth; no WPA, no IEEE 802.1X)
set_network id key_mgmt NONE
set_network id wep_key0 "abcde" // ASCII 64bit
set_network id wep_key1 1234567890 // hex 64bit
set_network id wep_key2 "1234567890123" // ASCII 128bit
set_network id wep_tx_keyidx 0 // key id
set_network id auth_alg SHARED

On other side, these commands can be replaced by below configuration in wpa_supplicant.conf.

# Open WEP key connection (two-message auth; no WPA, no IEEE 802.1X)
network={
   ssid="static-wep-test"
   key_mgmt=NONE
   wep_key0="abcde" #ASCII 64bit
   wep_key1=1234567890 # hex 64bit
   wep_key2="1234567890123" #ASCII 128bit
   wep_tx_keyidx=0 #key id
   priority=5
}
# Shared WEP key connection (four-message auth; no WPA, no IEEE 802.1X)
network={
   ssid="static-wep-test"
   key_mgmt=NONE
   wep_key0="abcde" #ASCII 64bit
   wep_key1=1234567890 # hex 64bit
   wep_key2="1234567890123" #ASCII 128bit
   wep_tx_keyidx=0 #key id
   priority=5
   auth_alg=SHARED
}

iwconfig

For WEP, below commands can be used to connect the WEP AP.

iwconfig wlan0 key [id] hex   //hex
iwconfig wlan0 key s:password [id] // ASCII
iwconfig wlan0 key [id] //choose psk id.
iwconfig wlan0 essid "ssid" //set ssid and connect

For more detail, please refer to iwconfig_8.

Connect with WPS

For WPS, below commands can be used when ap support and enable related capabilities.

Note

WPS doesn’t support WPA3 Wi-Fi security according to the specification.

WPS PBC

Excute below command and press the Push-Button in the router in 2 min, then network configuration can be received from the ap and stored in wpa_supplicant.conf.

wpa_cli -i wlan0 wps_pbc [BSSID]

Note

It may fail when there is more than 1 client or ap in PBC state.

WPS PIN - Client pin

Excute below command, you will get a pin number or used specified pin value in this command. Input the pin number in the router and then network configuration can be received from the ap and stored in wpa_supplicant.conf.

wpa_cli -i wlan0 wps_pin <BSSID | any> [pin_number]

Note

The specified pin number used in the commands must be processed by an UI to remove non-digit characters and potentially, to verify the checksum digit. Below commands can be used to do such processing.

wpa_cli wps_check_pin <PIN>

WPS PIN - Router pin

Enable router pin capability and get the bssid or the router pin value from the web_interface or the label in the router, use below command to connect ap.

wpa_cli -i wlan0 wps_reg <BSSID > <AP PIN>

For more detail, please refer to WPS.

Disconnect and Reconnect

Bellow commands is used to disconnect network.

disconnect

Bellow commands is used to reconnect network.

reconnect

The following figure shows to disconnect network 1 then reconnect it is successfully.

DHCP

dhcpcd wlan0 is used to get IP address from the AP’s DHCP server. The following figure shows the sample to run DHCP client and get the IP 192.168.1.101.

SoftAP mode

hostapd

hostapd (host access point daemon) is a user space daemon software enabling a network interface card to act as an access point and authentication server.

hostapd.conf

The hostapd.conf is the configuration file of hostapd and stored in /etc normally. It includes the parameters of SoftAP.

driver=nl80211
logger_syslog=-1
logger_syslog_level=2
logger_stdout=-1
logger_stdout_level=2
ctrl_interface=/var/run/hostapd
hw_mode=g
channel=1
ssid=sqb_test
beacon_int=100
dtim_period=1
max_num_sta=20
rts_threshold=2347
fragm_threshold=2346
ieee80211n=1
erp_send_reauth_start=1
wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=CCMP
wpa_passphrase=12345678

Above file is an example for hostapd.conf, and it sets the SSID sqb_test and password 12345678. For more detail, please refer to hostapd wiki.

Run hostapd

Below command can run hostapd in background and start softap on wlan1.

hostapd /etc/hostapd.conf -B -i wlan1

The following figure shows to start softap successuffly.

Note

Whether wlan0 nor wlan1 can be running as softap. If one port works as softap and other works as station, the wifi is working in concurrent mode.

DHCP server

This flow is as below.

ifconfig wlan1 192.168.43.1
udhcpd -S /etc/udhcpd.conf

Test

Environment

Station Test Environment

Note

• AP: a router with WiFi AP to support 11 a/b/g/n.

• PC: a personal computer to connect to AP’s LAN port with Ethernet cable.

• DUT: The device to test, it should be ameba smart board. It will connect to AP with wireless and connect to PC with serial port cable.

The PC can control the DUT with console of serial port cable.

Softap Test Environment

Note

• PC: a personal computer with WiFi card to support 11 a/b/g/n.

• DUT: The device to test, it should be ameba smart board. It will connect to PC with wireless and serial port cable.

• The PC can control the DUT with console of serial port cable

Ping Test

ping in system is classic ping tool in Linux, and ping -h can get the help information. The following figure shows to ping the 192.168.39.2 and no packet loss.

Throughput Test

This system support iperf3 to test the throughput of Wi-Fi, and iperf3 is classic in Linux. iperf3 -h can get the help information.

# To run as a server, UPD or TCP:
iperf3 -s -i 1
# To run as a client of TCP:
iperf3 -c ip_of_server -i 1 -t count
# To run as a client of UDP:
iperf3 -c ip_of_server -i 1 -t count -u -b bandwidth

Note

• ip_of_server is the IP address of server.

• The unit of count is second.

• Bandwidth’s unit should be K, M or G. There are some errors in official windows iperf3 bin, so bandwidth should be set to the limit of real bandwidth of WiFi.

TP for TCP TX

TP for TCP RX

TP for UDP TX

TP for UDP RX

DNS Test

Below command can add the AP_IP as the DNS server for Linux.

echo "nameserver AP_IP" >> /etc/resolv.conf

The following figure shows the result to ping www.baidu.com.

IP Forward

Below command can set the forward. The DUT connected softap can ping the AP connected by wlan0.

echo 1 > /proc/sys/net/ipv4/ip_forward
iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE

Adb shell

If the adb function want to be used, the usb.sh adb should be executed on the board to initialize the USB adb function. Then to enter adb shell on the PC to connect to board. The following figure shows to enter adb shell connecting board seccussfully.

Debug

Refer to the section of Trace Tool.