WHD Wi-Fi Utility API

group wifiutilities

Allows WHD to perform utility operations.

Functions

uint32_t whd_wifi_set_channel(whd_interface_t ifp, uint32_t channel)

Set the current channel on the WLAN radio.

note

On most WLAN devices this will set the channel for both AP AND STA (since there is only one radio - it cannot be on two channels simulaneously)

Return

WHD_SUCCESS if the channel was successfully set Error code if the channel was not successfully set

Parameters
  • ifp: Pointer to handle instance of whd interface

  • channel: The desired channel

uint32_t whd_wifi_get_channel(whd_interface_t ifp, uint32_t *channel)

Get the current channel on the WLAN radio.

note

On most WLAN devices this will get the channel for both AP AND STA (since there is only one radio - it cannot be on two channels simulaneously)

Return

WHD_SUCCESS if the channel was successfully retrieved Error code if the channel was not successfully retrieved

Parameters
  • ifp: Pointer to handle instance of whd interface

  • channel: Pointer to receive the current channel

uint32_t whd_wifi_set_passphrase(whd_interface_t ifp, const uint8_t *security_key, uint8_t key_length)

Set the passphrase.

Return

WHD_SUCCESS when the key is set Error code if an error occurred

Parameters
  • ifp: Pointer to handle instance of whd interface

  • security_key: The security key (passphrase) which is to be set

  • key_length: length of the key

uint32_t whd_wifi_sae_password(whd_interface_t ifp, const uint8_t *security_key, uint8_t key_length)

Set the SAE password.

Return

WHD_SUCCESS when the key is set Error code if an error occurred

Parameters
  • ifp: Pointer to handle instance of whd interface

  • security_key: The security key (password) which is to be set

  • key_length: length of the key

uint32_t whd_wifi_enable_sup_set_passphrase(whd_interface_t ifp, const uint8_t *security_key_psk, uint8_t psk_length, whd_security_t auth_type)

Enable WHD internal supplicant and set WPA2 passphrase in case of WPA3/WPA2 transition mode.

Return

WHD_SUCCESS when the supplicant variable and wpa2 passphrase is set Error code if an error occurred

Parameters
  • ifp: Pointer to handle instance of whd interface

  • security_key_psk: The security key (passphrase) which is to be set

  • psk_length: length of the key

  • auth_type: Authentication type: WHD_SECURITY_WPA3_WPA2_PSK

uint32_t whd_wifi_enable_supplicant(whd_interface_t ifp, whd_security_t auth_type)

Enable WHD internal supplicant.

Return

WHD_SUCCESS when the supplicant variable is set Error code if an error occurred

Parameters
  • ifp: Pointer to handle instance of whd interface

  • auth_type: Authentication type

uint32_t whd_wifi_get_rssi(whd_interface_t ifp, int32_t *rssi)

Retrieve the latest RSSI value.

Return

WHD_SUCCESS if the RSSI was successfully retrieved Error code if the RSSI was not retrieved

Parameters
  • ifp: Pointer to handle instance of whd interface

  • rssi: The location where the RSSI value will be stored

uint32_t whd_wifi_get_ap_client_rssi(whd_interface_t ifp, int32_t *rssi, const whd_mac_t *client_mac)

Retrieve the associated STA’s RSSI value.

Return

WHD_SUCCESS : if the RSSI was successfully retrieved Error code : if the RSSI was not retrieved

Parameters
  • ifp: : Pointer to handle instance of whd interface

  • rssi: : The location where the RSSI value will be stored

  • client_mac: : Pointer to associated client’s MAC address

uint32_t whd_wifi_get_mac_address(whd_interface_t ifp, whd_mac_t *mac)

Retrieves the current Media Access Control (MAC) address (or Ethernet hardware address) of the 802.11 device.

Return

WHD_SUCCESS or Error code

Parameters
  • ifp: Pointer to handle instance of whd interface

  • mac: Pointer to a variable that the current MAC address will be written to

uint32_t whd_wifi_get_bssid(whd_interface_t ifp, whd_mac_t *bssid)

Get the BSSID of the interface.

Return

WHD_SUCCESS or Error code

Parameters
  • ifp: Pointer to the whd_interface_t

  • bssid: Returns the BSSID address (mac address) if associated

uint32_t whd_wifi_register_multicast_address(whd_interface_t ifp, const whd_mac_t *mac)

Registers interest in a multicast address.

Once a multicast address has been registered, all packets detected on the medium destined for that address are forwarded to the host. Otherwise they are ignored.

Return

WHD_SUCCESS if the address was registered successfully Error code if the address was not registered

Parameters
  • ifp: Pointer to handle instance of whd interface

  • mac: Ethernet MAC address

uint32_t whd_wifi_unregister_multicast_address(whd_interface_t ifp, const whd_mac_t *mac)

Unregisters interest in a multicast address.

Once a multicast address has been unregistered, all packets detected on the medium destined for that address are ignored.

Return

WHD_SUCCESS if the address was unregistered successfully Error code if the address was not unregistered

Parameters
  • ifp: Pointer to handle instance of whd interface

  • mac: Ethernet MAC address

uint32_t whd_wifi_set_listen_interval(whd_interface_t ifp, uint8_t listen_interval, whd_listen_interval_time_unit_t time_unit)

Sets the 802.11 powersave listen interval for a Wi-Fi client, and communicates the listen interval to the Access Point.

The listen interval will be set to (listen_interval x time_unit) seconds.

The default value for the listen interval is 0. With the default value of 0 set, the Wi-Fi device wakes to listen for AP beacons every DTIM period.

If the DTIM listen interval is non-zero, the DTIM listen interval will over ride the beacon listen interval value.

Return

WHD_SUCCESS If the listen interval was successfully set. Error code If the listen interval was not successfully set.

Parameters
  • ifp: Pointer to handle instance of whd interface

  • listen_interval: The desired beacon listen interval

  • time_unit: The listen interval time unit; options are beacon period or DTIM period.

uint32_t whd_wifi_get_listen_interval(whd_interface_t ifp, whd_listen_interval_t *li)

Gets the current value of all beacon listen interval variables.

Return

WHD_SUCCESS If all listen interval values are read successfully Error code If at least one of the listen interval values are NOT read successfully

Parameters
  • ifp: Pointer to handle instance of whd interface

  • li: Powersave listen interval values

    • listen_interval_beacon : The current value of the listen interval set as a multiple of the beacon period

    • listen_interval_dtim : The current value of the listen interval set as a multiple of the DTIM period

    • listen_interval_assoc : The current value of the listen interval sent to access points in an association request frame

uint32_t whd_wifi_is_ready_to_transceive(whd_interface_t ifp)

Determines if a particular interface is ready to transceive ethernet packets.

Return

WHD_SUCCESS if the interface is ready to transceive ethernet packets WHD_NOTFOUND no AP with a matching SSID was found WHD_NOT_AUTHENTICATED Matching AP was found but it won’t let you authenticate. This can occur if this device is in the block list on the AP. WHD_NOT_KEYED Device has authenticated and associated but has not completed the key exchange. This can occur if the passphrase is incorrect. Error code if the interface is not ready to transceive ethernet packets

Parameters
  • ifp: Pointer to handle instance of whd interface

uint32_t whd_wifi_get_acparams(whd_interface_t ifp, whd_edcf_ac_param_t *acp)

Retrieve the latest STA EDCF AC parameters.

Retrieve the latest Station (STA) interface EDCF (Enhanced Distributed Coordination Function) Access Category parameters

Return

WHD_SUCCESS if the AC Parameters were successfully retrieved Error code if the AC Parameters were not retrieved

Parameters
  • ifp: Pointer to handle instance of whd interface

  • acp: The location where the array of AC parameters will be stored

uint32_t whd_wifi_manage_custom_ie(whd_interface_t ifp, whd_custom_ie_action_t action, const uint8_t *oui, uint8_t subtype, const void *data, uint16_t length, uint16_t which_packets)

Manage the addition and removal of custom IEs.

Return

WHD_SUCCESS if the custom IE action was successful Error code if the custom IE action failed

Parameters
  • ifp: Pointer to handle instance of whd interface

  • action: the action to take (add or remove IE)

  • oui: the oui of the custom IE

  • subtype: the IE sub-type

  • data: a pointer to the buffer that hold the custom IE

  • length: the length of the buffer pointed to by ‘data’

  • which_packets: A mask to indicate in which all packets this IE should be included. See whd_ie_packet_flag_t.

uint32_t whd_wifi_send_action_frame(whd_interface_t ifp, whd_af_params_t *af_params)

Send a pre-prepared action frame.

Return

WHD_SUCCESS or Error code

Parameters
  • ifp: Pointer to handle instance of whd interface

  • af_params: A pointer to a pre-prepared action frame structure

uint32_t whd_wifi_set_coex_config(whd_interface_t ifp, whd_coex_config_t *coex_config)

Set coex configuration.

Return

WHD_SUCCESS or Error code

Parameters
  • ifp: Pointer to handle instance of whd interface

  • coex_config: Pointer to the structure whd_coex_config_t

whd_result_t whd_arp_version(whd_interface_t ifp, uint32_t *version)

Get version of Device (WLAN) Firmware.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [out] version: : pointer to store version #

whd_result_t whd_arp_peerage_get(whd_interface_t ifp, uint32_t *seconds)

Get ARP Offload Peer Age from Device (WLAN) Length of time in seconds before aging out an entry in the WLAN processor ARP table.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [out] seconds: : pointer to store value

whd_result_t whd_arp_peerage_set(whd_interface_t ifp, uint32_t seconds)

Set ARP Offload Peer Age in Device (WLAN) Length of time in seconds before aging out an entry in the WLAN processor ARP table.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] seconds: : Seconds to age out IP

whd_result_t whd_arp_arpoe_get(whd_interface_t ifp, uint32_t *agent_enable)

Get ARP Offload Agent Enable from Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [out] agent_enable: : pointer to store value

whd_result_t whd_arp_arpoe_set(whd_interface_t ifp, uint32_t agent_enable)

Set ARP Offload Agent Enable in Device (WLAN) Set Enable/Disable of ARP Offload Agent.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] agent_enable: : Enable=1 / Disable=0

whd_result_t whd_arp_cache_clear(whd_interface_t ifp)

Clear ARP Offload cache in Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

whd_result_t whd_arp_features_get(whd_interface_t ifp, uint32_t *features)

Get ARP Offload Feature Flags from Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [out] features: : ptr to store currently set features - bit flags CY_ARP_OL_AGENT_ENABLE, etc. ARL_OL_AGENT | ARL_OL_SNOOP | ARP_OL_HOST_AUTO_REPLY | ARP_OL_PEER_AUTO_REPLY

whd_result_t whd_arp_features_set(whd_interface_t ifp, uint32_t features)

Set ARP Offload Feature Flags in Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] features: : features to set value (you can OR (‘|’) multiple flags) CY_ARP_OL_AGENT_ENABLE, etc. ARL_OL_AGENT | ARL_OL_SNOOP | ARP_OL_HOST_AUTO_REPLY | ARP_OL_PEER_AUTO_REPLY

whd_result_t whd_arp_features_print(uint32_t features, const char *title)

Print ARP Offload Feature Flags in Human readable form to console.

Return

whd_result_t

Parameters
  • [in] features: : feature flags to set (you can OR ‘|’ multiple flags) CY_ARP_OL_AGENT_ENABLE, etc. ARL_OL_AGENT | ARL_OL_SNOOP | ARP_OL_HOST_AUTO_REPLY | ARP_OL_PEER_AUTO_REPLY

  • [in] title: : Optional: Title for output (NULL == no title)

whd_result_t whd_arp_hostip_list_add(whd_interface_t ifp, uint32_t *host_ipv4_list, uint32_t count)

Add ARP Offload Host IP Identifier(s) to HostIP List to Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] host_ipv4_list: : pointer to host_ip data (IPv4, 1 uint32_t per ip addr)

  • [in] count: : Number of array elements in host_ip

whd_result_t whd_arp_hostip_list_add_string(whd_interface_t ifp, const char *ip_addr)

Add One ARP Offload Host IP Identifier to HostIP List (mbed-style IP string) to Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] ip_addr: : pointer to ip string (as returned from mbedos calls)

whd_result_t whd_arp_hostip_list_clear_id(whd_interface_t ifp, uint32_t ipv4_addr)

Clear One ARP Offload Host IP Identifier from Host IP List in Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] ipv4_addr: : ip addr expressed as a uint32_t

whd_result_t whd_arp_hostip_list_clear_id_string(whd_interface_t ifp, const char *ip_addr)

Clear One ARP Offload Host IP Identifier from Host IP List (mbed-style IP string) in Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] ip_addr: : pointer to ip string (as returned from mbedos calls)

whd_result_t whd_arp_hostip_list_clear(whd_interface_t ifp)

Clear all ARP Offload Host IP Identifier List.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

whd_result_t whd_arp_hostip_list_get(whd_interface_t ifp, uint32_t count, uint32_t *host_ipv4_list, uint32_t *filled)

Get ARP Offload Host IP Identifiers from Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] count: : Number of array elements in host_ip

  • [out] host_ipv4_list: : Pointer to structure array to store host_ip data

  • [out] filled: : Number of array elements filled by this routine

whd_result_t whd_arp_stats_clear(whd_interface_t ifp)

Clear ARP Offload statistics in Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

whd_result_t whd_arp_stats_get(whd_interface_t ifp, whd_arp_stats_t *stats)

Get ARP Offload statistics from Device (WLAN)

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [out] stats: : Ptr to store statistics whd_arp_stats_t

whd_result_t whd_arp_stats_print(whd_arp_stats_t *arp_stats, const char *title)

Print ARP Offload statistics NOTE: call whd_arp_stats_get(), then print them using this function.

Return

whd_result_t

Parameters
  • [in] arp_stats: : Ptr to ARP statistics structure

  • [in] title: : Optional: Title for output (NULL == no title)

whd_result_t whd_pf_add_packet_filter(whd_interface_t ifp, const whd_packet_filter_t *settings)

A filter must be added (e.g.

created) before it can be enabled.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] settings: : Ptr to filter settings whd_packet_filter_t

whd_result_t whd_pf_remove_packet_filter(whd_interface_t ifp, uint8_t filter_id)

Remove a previously added filter.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] filter_id: : filter to remove

whd_result_t whd_pf_enable_packet_filter(whd_interface_t ifp, uint8_t filter_id)

After a filter has been added it can be enabled or disabled as needed.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] filter_id: : filter to enable

whd_result_t whd_pf_disable_packet_filter(whd_interface_t ifp, uint8_t filter_id)

After a filter has been added it can be enabled or disabled as needed.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] filter_id: : filter to disable

whd_result_t whd_wifi_toggle_packet_filter(whd_interface_t ifp, uint8_t filter_id, whd_bool_t enable)

After a filter has been added it can be enabled or disabled as needed.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] filter_id: : filter to disable/enable

  • [in] enable: : Enable/Disable Flag

whd_result_t whd_pf_get_packet_filter_mask_and_pattern(whd_interface_t ifp, uint8_t filter_id, uint32_t max_size, uint8_t *mask, uint8_t *pattern, uint32_t *size_out)

Filters are implemented in WLAN subsystem as a bit pattern and matching bit mask that are applied to incoming packets.

This API retrieves the pattern and mask.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] filter_id: : which filter to retrieve

  • [in] max_size: : size of both mask and pattern buffers

  • [out] mask: : mask for this filter

  • [out] pattern: : pattern for this filter

  • [out] size_out: : length of both mask and pattern

whd_result_t whd_wifi_clear_packet_filter_stats(whd_interface_t ifp, uint32_t filter_id)

Clear the packet filter stats associated with a filter id.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] filter_id: : which filter

whd_result_t whd_pf_get_packet_filter_stats(whd_interface_t ifp, uint8_t filter_id, whd_pkt_filter_stats_t *stats)

Return the stats associated with a filter.

Return

whd_result_t

Parameters
  • [in] ifp: : pointer to handle instance of whd interface

  • [in] filter_id: : which filter

  • [out] stats: : Ptr to store statistics wl_pkt_filter_stats_t

whd_result_t whd_tko_param(whd_interface_t ifp, whd_tko_retry_t *whd_tko_retry, int set)

Set/Get TKO retry & interval parameters.

Return

whd_result_t

Parameters
  • [in] ifp: : Pointer to handle instance of whd interface

  • [in] whd_tko_retry: : whd retry & interval parameters structure

  • [in] set: : Set/Get Flag

whd_result_t whd_tko_get_status(whd_interface_t ifp, whd_tko_status_t *tko_status)

Return the tko status for all indexes.

Return

whd_result_t

Parameters
  • [in] ifp: : Pointer to handle instance of whd interface

  • [out] tko_status: : Ptr to store tko_status

whd_result_t whd_tko_max_assoc(whd_interface_t ifp, uint8_t *max)

Return the stats associated with a filter.

Return

whd_result_t

Parameters
  • [in] ifp: : Pointer to handle instance of whd interface

  • [out] max: : returns Max TCP connections supported by WLAN Firmware

whd_result_t whd_tko_get_FW_connect(whd_interface_t ifp, uint8_t index, whd_tko_connect_t *whd_connect, uint16_t buflen)

Return the stats associated with a filter.

Return

whd_result_t

Parameters
  • [in] ifp: : Pointer to handle instance of whd interface

  • [in] index: : index for TCP offload connection

  • [out] whd_connect: : tko_connect structure buffer from Firmware

  • [in] buflen: : Buffer given for tko_connect

whd_result_t whd_tko_toggle(whd_interface_t ifp, whd_bool_t enable)

Return the stats associated with a filter.

Return

whd_result_t

Parameters
  • [in] ifp: : Pointer to handle instance of whd interface

  • [in] enable: : Enable/Disable TCP Keepalive offload