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)

Parameters
  • ifp – Pointer to handle instance of whd interface

  • channel – The desired channel

Returns

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

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)

Parameters
  • ifp – Pointer to handle instance of whd interface

  • channel – Pointer to receive the current channel

Returns

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

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

Set the passphrase.

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

Returns

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

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

Set the SAE password.

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

Returns

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

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.

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

Returns

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

uint32_t whd_wifi_enable_supplicant(whd_interface_t ifp, whd_security_t auth_type)

Enable WHD internal supplicant.

Parameters
  • ifp – Pointer to handle instance of whd interface

  • auth_type – Authentication type

Returns

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

uint32_t whd_wifi_get_rssi(whd_interface_t ifp, int32_t *rssi)

Retrieve the latest RSSI value.

Parameters
  • ifp – Pointer to handle instance of whd interface

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

Returns

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

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.

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

Returns

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

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.

Parameters
  • ifp – Pointer to handle instance of whd interface

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

Returns

WHD_SUCCESS or Error code

uint32_t whd_wifi_get_bssid(whd_interface_t ifp, whd_mac_t *bssid)

Get the BSSID of the interface.

Parameters
  • ifp – Pointer to the whd_interface_t

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

Returns

WHD_SUCCESS or Error code

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.

Parameters
  • ifp – Pointer to handle instance of whd interface

  • mac – Ethernet MAC address

Returns

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

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.

Parameters
  • ifp – Pointer to handle instance of whd interface

  • mac – Ethernet MAC address

Returns

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

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.

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.

Returns

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

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.

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

Returns

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

uint32_t whd_wifi_is_ready_to_transceive(whd_interface_t ifp)

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

Parameters

ifp – Pointer to handle instance of whd interface

Returns

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

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

Parameters
  • ifp – Pointer to handle instance of whd interface

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

Returns

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

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.

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.

Returns

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

uint32_t whd_wifi_send_action_frame(whd_interface_t ifp, whd_af_params_t *af_params)

Send a pre-prepared action frame.

Parameters
  • ifp – Pointer to handle instance of whd interface

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

Returns

WHD_SUCCESS or Error code

uint32_t whd_wifi_set_coex_config(whd_interface_t ifp, whd_coex_config_t *coex_config)

Set coex configuration.

Parameters
  • ifp – Pointer to handle instance of whd interface

  • coex_config – Pointer to the structure whd_coex_config_t

Returns

WHD_SUCCESS or Error code

whd_result_t whd_arp_version(whd_interface_t ifp, uint32_t *version)

Get version of Device (WLAN) Firmware.

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

  • version[out] : pointer to store version #

Returns

whd_result_t

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.

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

  • seconds[out] : pointer to store value

Returns

whd_result_t

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.

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

  • seconds[in] : Seconds to age out IP

Returns

whd_result_t

whd_result_t whd_arp_arpoe_get(whd_interface_t ifp, uint32_t *agent_enable)

Get ARP Offload Agent Enable from Device (WLAN)

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

  • agent_enable[out] : pointer to store value

Returns

whd_result_t

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.

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

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

Returns

whd_result_t

whd_result_t whd_arp_cache_clear(whd_interface_t ifp)

Clear ARP Offload cache in Device (WLAN)

Parameters

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

Returns

whd_result_t

whd_result_t whd_arp_features_get(whd_interface_t ifp, uint32_t *features)

Get ARP Offload Feature Flags from Device (WLAN)

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

  • features[out] : 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

Returns

whd_result_t

whd_result_t whd_arp_features_set(whd_interface_t ifp, uint32_t features)

Set ARP Offload Feature Flags in Device (WLAN)

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

  • features[in] : 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

Returns

whd_result_t

whd_result_t whd_arp_features_print(uint32_t features, const char *title)

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

Parameters
  • features[in] : 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

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

Returns

whd_result_t

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)

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

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

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

Returns

whd_result_t

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)

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

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

Returns

whd_result_t

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)

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

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

Returns

whd_result_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)

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

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

Returns

whd_result_t

whd_result_t whd_arp_hostip_list_clear(whd_interface_t ifp)

Clear all ARP Offload Host IP Identifier List.

Parameters

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

Returns

whd_result_t

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)

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

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

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

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

Returns

whd_result_t

whd_result_t whd_arp_stats_clear(whd_interface_t ifp)

Clear ARP Offload statistics in Device (WLAN)

Parameters

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

Returns

whd_result_t

whd_result_t whd_arp_stats_get(whd_interface_t ifp, whd_arp_stats_t *stats)

Get ARP Offload statistics from Device (WLAN)

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

  • stats[out] : Ptr to store statistics whd_arp_stats_t

Returns

whd_result_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.

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

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

Returns

whd_result_t

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.

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

  • settings[in] : Ptr to filter settings whd_packet_filter_t

Returns

whd_result_t

whd_result_t whd_pf_remove_packet_filter(whd_interface_t ifp, uint8_t filter_id)

Remove a previously added filter.

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

  • filter_id[in] : filter to remove

Returns

whd_result_t

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.

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

  • filter_id[in] : filter to enable

Returns

whd_result_t

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.

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

  • filter_id[in] : filter to disable

Returns

whd_result_t

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.

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

  • filter_id[in] : filter to disable/enable

  • enable[in] : Enable/Disable Flag

Returns

whd_result_t

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.

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

  • filter_id[in] : which filter to retrieve

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

  • mask[out] : mask for this filter

  • pattern[out] : pattern for this filter

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

Returns

whd_result_t

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.

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

  • filter_id[in] : which filter

Returns

whd_result_t

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.

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

  • filter_id[in] : which filter

  • stats[out] : Ptr to store statistics wl_pkt_filter_stats_t

Returns

whd_result_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.

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

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

  • set[in] : Set/Get Flag

Returns

whd_result_t

whd_result_t whd_tko_get_status(whd_interface_t ifp, whd_tko_status_t *tko_status)

Return the tko status for all indexes.

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

  • tko_status[out] : Ptr to store tko_status

Returns

whd_result_t

whd_result_t whd_tko_max_assoc(whd_interface_t ifp, uint8_t *max)

Return the stats associated with a filter.

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

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

Returns

whd_result_t

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.

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

  • index[in] : index for TCP offload connection

  • whd_connect[out] : tko_connect structure buffer from Firmware

  • buflen[in] : Buffer given for tko_connect

Returns

whd_result_t

whd_result_t whd_tko_toggle(whd_interface_t ifp, whd_bool_t enable)

Return the stats associated with a filter.

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

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

Returns

whd_result_t