Functions

group group_wcm_functions

  • The WCM library internally creates a thread; the created threads are executed with the “CY_RTOS_PRIORITY_ABOVENORMAL” priority. The definition of the CY_RTOS_PRIORITY_ABOVENORMAL macro is located at “libs/abstraction-rtos/include/COMPONENT_FREERTOS/cyabs_rtos_impl.h”.

  • The WCM APIs are thread-safe.

  • All the WCM APIs except cy_wcm_start_scan are blocking APIs.

  • cy_wcm_start_scan is a non-blocking API; scan results are delivered via cy_wcm_scan_result_callback_t.

  • All application callbacks invoked by the WCM will be running in the context of the WCM; the pointers passed as argument in the callback function will be freed once the function returns.

  • For the APIs that expect cy_wcm_interface_t as an argument, unless a specific interface type has been called out in the description of the API, any valid WCM interface type can be passed as an argument to the API.

Functions

cy_rslt_t cy_wcm_init(cy_wcm_config_t *config)

Initializes the WCM.

This function initializes the WCM resources, WHD, and Wi-Fi transport; turns Wi-Fi on; and starts up the network stack. This function should be called before calling other WCM APIs.

Return

CY_RSLT_SUCCESS if WCM initialization was successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] config: The configuration to be initialized.

cy_rslt_t cy_wcm_deinit(void)

Shuts down the WCM.

This function cleans up all the resources of the WCM and brings down the Wi-Fi driver.

note

This API does not bring down the network stack because the default underlying stack does not have an implementation for deinit. Therefore, the expectation is that cy_wcm_init and this API should be invoked only once.

Return

CY_RSLT_SUCCESS if the Wi-Fi module was successfully turned off; returns WCM-specific error codes otherwise.

cy_rslt_t cy_wcm_start_scan(cy_wcm_scan_result_callback_t scan_callback, void *user_data, cy_wcm_scan_filter_t *scan_filter)

Performs Wi-Fi network scan.

The scan progressively accumulates results over time and may take between 1 and 10 seconds to complete. The results of the scan will be individually provided to the callback function. This API can be invoked while being connected to an AP.

Return

CY_RSLT_SUCCESS if the Wi-Fi network scan was successful; returns WCM-specific error codes otherwise. While a scan is in progress, if the user issues another scan, this API returns “CY_RSLT_WCM_SCAN_IN_PROGRESS”.

Parameters
  • [in] scan_callback: : Callback function which receives the scan results; callback will be executed in the context of the WCM.

  • [in] user_data: : User data to be returned as an argument in the callback function when the callback function is invoked.

  • [in] scan_filter: : Scan filter parameter passed for scanning (optional).

cy_rslt_t cy_wcm_stop_scan(void)

Stops an ongoing Wi-Fi network scan.

Return

CY_RSLT_SUCCESS if the Wi-Fi network scan was successful; returns WCM-specific error codes otherwise.

cy_rslt_t cy_wcm_connect_ap(const cy_wcm_connect_params_t *connect_params, cy_wcm_ip_address_t *ip_addr)

Connects the STA interface to a AP using the Wi-Fi credentials and configuration parameters provided.

On successful connection to the Wi-Fi network, the API returns the IP address.

This API is a blocking call; this function additionally performs the following checks: 1) Checks for and ignores duplicate connect requests to an already connected AP. 2) Checks the current connection state; if already connected, disconnects from the current Wi-Fi network and connects to the new Wi-Fi network.

note

WEP (Wired Equivalent Privacy) security is not supported by this API. WEP based authentication types are considered to be weaker security types, hence this function doesn't connect to AP that is configured with WEP based authentication.

Return

CY_RSLT_SUCCESS if connection is successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] connect_params: : Configuration to join the AP.

  • [out] ip_addr: : Pointer to return the IP address (optional).

cy_rslt_t cy_wcm_disconnect_ap(void)

Disconnects the STA interface from the currently connected AP.

Return

CY_RSLT_SUCCESS if disconnection was successful or if the device is already disconnected; returns WCM-specific error codes otherwise.

cy_rslt_t cy_wcm_get_ip_addr(cy_wcm_interface_t interface_type, cy_wcm_ip_address_t *ip_addr, uint8_t addr_count)

Retrieves the IPv4 address of the given interface.

See cy_wcm_get_ipv6_addr API to get IPv6 addresses.

Return

CY_RSLT_SUCCESS if IP-address get is successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] interface_type: : Type of the WCM interface.

  • [out] ip_addr: : Pointer to an IP address structure (or) an IP address structure array. If the given interface is CY_WCM_INTERFACE_TYPE_STA or CY_WCM_INTERFACE_TYPE_AP upon return, index-0 stores the IPv4 address of the interface. If the given interface type is CY_WCM_INTERFACE_TYPE_AP_STA, index-0 stores the IPv4 address of the STA interface and index-1 stores the IPV4 address of the AP interface.

  • [in] addr_count: : Length of the array passed in ip_addr.

cy_rslt_t cy_wcm_get_ipv6_addr(cy_wcm_interface_t interface_type, cy_wcm_ipv6_type_t ipv6_addr_type, cy_wcm_ip_address_t *ip_addr, uint8_t addr_count)

Retrieves the IPv6 address of the given interface.

Note: Currently this API supports only CY_WCM_IPV6_LINK_LOCAL type.

Return

CY_RSLT_SUCCESS if IPv6 interface is up and IPv6 address is ready; returns WCM-specific error codes otherwise.

Parameters
  • [in] interface_type: : Type of the WCM interface.

  • [in] ipv6_addr_type: : IPv6 address type.

  • [out] ip_addr: : Pointer to an IP address structure (or) an IP address structure array. If the given interface is CY_WCM_INTERFACE_TYPE_STA or CY_WCM_INTERFACE_TYPE_AP upon return, index-0 stores the IPv6 link-local address of the interface. If the given interface type is CY_WCM_INTERFACE_TYPE_AP_STA, index-0 stores the IPv6 link-local address of the STA interface and index-1 stores the IPv6 link-local address of the AP interface.

  • [in] addr_count: : Length of the array passed in ip_addr.

cy_rslt_t cy_wcm_get_gateway_ip_address(cy_wcm_interface_t interface_type, cy_wcm_ip_address_t *gateway_addr, uint8_t addr_count)

Retrieves the gateway IP address of the given interface.

Return

CY_RSLT_SUCCESS if retrieval of the gateway IP address was successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] interface_type: : Type of the WCM interface.

  • [out] gateway_addr: : Pointer to a single structure or an array of structures to be filled with the gateway IP address or addresses. If the given interface is CY_WCM_INTERFACE_TYPE_STA or CY_WCM_INTERFACE_TYPE_AP upon return, index-0 stores the IPv4 gateway address of the interface. If the given interface type is CY_WCM_INTERFACE_TYPE_AP_STA, index-0 stores the IPv4 gateway address of the STA interface and index-1 stores the IPV4 gateway address of the AP interface. In future, IPv6 addresses will be supported.

  • [in] addr_count: : Length of the array passed in gateway_addr.

cy_rslt_t cy_wcm_get_ip_netmask(cy_wcm_interface_t interface_type, cy_wcm_ip_address_t *net_mask_addr, uint8_t addr_count)

Retrieves the subnet mask address of the given interface.

Return

CY_RSLT_SUCCESS if retrieval of the subnet mask address was successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] interface_type: : Type of the WCM interface.

  • [out] net_mask_addr: : Pointer to a single structure or an array of structures to be filled with the subnet mask address or masks. If the given interface is CY_WCM_INTERFACE_TYPE_STA or CY_WCM_INTERFACE_TYPE_AP upon return, index-0 stores the subnet mask address of the interface. If the given interface type is CY_WCM_INTERFACE_TYPE_AP_STA, index-0 stores the subnet mask address of the STA interface and index-1 stores the subnet mask address of the AP interface.

  • [in] addr_count: : Length of the array passed in net_mask_addr.

cy_rslt_t cy_wcm_get_mac_addr(cy_wcm_interface_t interface_type, cy_wcm_mac_t *mac_addr, uint8_t addr_count)

Retrieves the MAC address of the given interface.

Return

CY_RSLT_SUCCESS if the MAC address get is successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] interface_type: : Type of the WCM interface.

  • [out] mac_addr: : Pointer to a MAC address structure (or) a MAC address structure array. If the given interface is CY_WCM_INTERFACE_TYPE_STA or CY_WCM_INTERFACE_TYPE_AP upon return, index-0 stores the MAC address of the interface. If the given interface type is CY_WCM_INTERFACE_TYPE_AP_STA, index-0 stores the MAC address of the STA interface and index-1 stores the MAC address of the AP interface.

  • [in] addr_count: : Length of the array passed in mac_addr.

cy_rslt_t cy_wcm_wps_enrollee(cy_wcm_wps_config_t *config, const cy_wcm_wps_device_detail_t *details, cy_wcm_wps_credential_t *credentials, uint16_t *credential_count)

Negotiates securely with a Wi-Fi Protected Setup (WPS) Registrar (usually an AP) and obtains the Wi-Fi network credentials.

Return

CY_RSLT_SUCCESS if credentials are retrieved successfully; returns WCM-specific error codes otherwise.

Parameters
  • [in] config: : Pointer to the WPS configuration information.

  • [in] details: : Pointer to a structure containing manufacturing details of this device.

  • [out] credentials: : Pointer to an array of credentials structure cy_wcm_wps_credential_t to receive the AP credentials.

  • [inout] credential_count: : Upon invocation, this parameter stores the size of the credentials parameter. Upon return, denotes the actual number of credentials returned.

cy_rslt_t cy_wcm_wps_generate_pin(char wps_pin_string[CY_WCM_WPS_PIN_LENGTH])

Generates random WPS PIN for PIN mode connection.

Return

CY_RSLT_SUCCESS if WPS PIN generated; returns WCM-specific error codes otherwise.

Parameters
  • [out] wps_pin_string: : Pointer to store the WPS PIN as a null-terminated string.

cy_rslt_t cy_wcm_register_event_callback(cy_wcm_event_callback_t event_callback)

Registers an event callback to monitor the connection and IP address change events.

This is an optional registration; use it if the application needs to monitor events across disconnection and reconnection of STA interface and notifies the clients which are connected or disconnected from the SoftAP.

Note: This API is expected to be called typically while being connected to an AP or once the SoftAP is up.

Return

CY_RSLT_SUCCESS if application callback registration was successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] event_callback: : Callback function to be invoked for event notification. The callback will be executed in the context of the WCM.

cy_rslt_t cy_wcm_deregister_event_callback(cy_wcm_event_callback_t event_callback)

De-registers an event callback.

Return

CY_RSLT_SUCCESS if application callback de-registration was successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] event_callback: : Callback function to de-register from getting notifications.

uint8_t cy_wcm_is_connected_to_ap(void)

Checks if the STA interface is connected to an AP.

Return

1 if connected, 0 otherwise.

cy_rslt_t cy_wcm_get_associated_ap_info(cy_wcm_associated_ap_info_t *ap_info)

This function retrieves the information such as SSID, BSSID, and other details of the AP to which the STA interface is connected.

Return

CY_RSLT_SUCCESS if retrieving the information of the associated AP was successful; returns WCM-specific error codes otherwise.

Parameters

cy_rslt_t cy_wcm_get_wlan_statistics(cy_wcm_interface_t interface, cy_wcm_wlan_statistics_t *stat)

This function gets the WLAN statistics of the given interface from the time WLAN driver is up and running.

The application would typically use this API to get information such as “total transmitted packets” and “total received packets”; for more details, see members of cy_wcm_wlan_statistics_t.

Return

CY_RSLT_SUCCESS if retrieval of statistics was successful; returns WCM-specific error codes otherwise.

Parameters

cy_rslt_t cy_wcm_get_gateway_mac_address(cy_wcm_mac_t *mac_addr)

Retrieves the MAC address of the gateway for STA interface.

Uses Address Resolution Protocol (ARP) to retrieve the gateway MAC address.

This function is a blocking call and uses an internal timeout while running ARP.

Return

CY_RSLT_SUCCESS if retrieval of the gateway MAC address was successful; returns WCM-specific error codes otherwise.

Parameters
  • [out] mac_addr: : Pointer to a MAC address structure which is filled with the gateway’s MAC address on successful return.

cy_rslt_t cy_wcm_ping(cy_wcm_interface_t interface, cy_wcm_ip_address_t *ip_addr, uint32_t timeout_ms, uint32_t *elapsed_ms)

Sends a ping request to the given IP address.

This function is a blocking call; it returns after the specified timeout.

Return

CY_RSLT_SUCCESS if pinging to the IP address was successful; returns WCM-specific error codes otherwise.

Parameters
  • [in] interface: : Type of the WCM interface.

  • [in] ip_addr: : Pointer to the destination IP address structure to which the ping request will be sent.

  • [in] timeout_ms: : Ping request timeout in milliseconds.

  • [out] elapsed_ms: : Pointer to store the round-trip time (in milliseconds), i.e., the time taken to receive the ping response from the destination.

cy_rslt_t cy_wcm_start_ap(const cy_wcm_ap_config_t *ap_config)

Start an infrastructure Wi-Fi network (SoftAP).

This API is a blocking call; this function adds the Information Element to the SoftAP and starts an internal DHCP server.

Return

CY_RSLT_SUCCESS if SoftAp is started ; returns WCM-specific error codes otherwise.

Parameters
  • [in] ap_config: : Configuration parameters for the SoftAP.

cy_rslt_t cy_wcm_stop_ap(void)

Stops the infrastructure Wi-Fi network (SoftAP), removes the Information Element and stops the internal DHCP server.

Return

CY_RSLT_SUCCESS if connection is successful; returns WCM-specific error codes otherwise.

cy_rslt_t cy_wcm_get_associated_client_list(cy_wcm_mac_t *sta_list, uint8_t num_clients)

Gets the MAC address of the clients associated with the SoftAP.

note

Maximum number of supported client list varies for different Wi-Fi chips.

Return

CY_RSLT_SUCCESS If getting the client list is successful; returns WCM-specific error codes otherwise.

Parameters
  • [out] sta_list: : Pointer to MAC address (or) array of MAC addresses.

  • [in] num_clients: : Length of the array passed in sta_list.