General Description

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

cy_rslt_t	cy_wcm_deinit (void)
	Shuts down the WCM. More...

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 a Wi-Fi network scan. More...

cy_rslt_t	cy_wcm_stop_scan (void)
	Stops an ongoing Wi-Fi network scan. More...

cy_rslt_t	cy_wcm_connect_ap (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. More...

cy_rslt_t	cy_wcm_disconnect_ap (void)
	Disconnects the STA interface from the currently connected AP. More...

cy_rslt_t	cy_wcm_get_ip_addr (cy_wcm_interface_t interface_type, cy_wcm_ip_address_t *ip_addr)
	Retrieves the IPv4 address of the given interface. More...

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)
	Retrieves the IPv6 address of the given interface. More...

cy_rslt_t	cy_wcm_get_gateway_ip_address (cy_wcm_interface_t interface_type, cy_wcm_ip_address_t *gateway_addr)
	Retrieves the gateway IP address of the given interface. More...

cy_rslt_t	cy_wcm_get_ip_netmask (cy_wcm_interface_t interface_type, cy_wcm_ip_address_t *net_mask_addr)
	Retrieves the subnet mask address of the given interface. More...

cy_rslt_t	cy_wcm_get_mac_addr (cy_wcm_interface_t interface_type, cy_wcm_mac_t *mac_addr)
	Retrieves the MAC address of the given interface. More...

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

cy_rslt_t	cy_wcm_wps_generate_pin (char wps_pin_string[CY_WCM_WPS_PIN_LENGTH])
	Generates a random WPS PIN for PIN mode connection. More...

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

cy_rslt_t	cy_wcm_deregister_event_callback (cy_wcm_event_callback_t event_callback)
	De-registers an event callback. More...

uint8_t	cy_wcm_is_connected_to_ap (void)
	Checks if the STA interface is connected to an AP. More...

cy_rslt_t	cy_wcm_get_associated_ap_info (cy_wcm_associated_ap_info_t *ap_info)
	Retrieves the information such as SSID, BSSID, and other details of the AP to which the STA interface is connected. More...

cy_rslt_t	cy_wcm_get_wlan_statistics (cy_wcm_interface_t interface, cy_wcm_wlan_statistics_t *stat)
	Gets the WLAN statistics of the given interface from the time WLAN driver is up and running. More...

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

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

cy_rslt_t	cy_wcm_start_ap (const cy_wcm_ap_config_t *ap_config)
	Starts an infrastructure Wi-Fi network (SoftAP). More...

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

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

cy_rslt_t	cy_wcm_set_ap_ip_setting (cy_wcm_ip_setting_t ap_ip, const char ip_addr, const char netmask, const char gateway_addr, cy_wcm_ip_version_t ver)
	Stores the AP settings provided by the user. More...

cy_rslt_t	cy_wcm_allow_low_power_mode (cy_wcm_powersave_mode_t mode)
	Sets low power mode capability for WLAN CPU. More...

Function Documentation

◆ cy_wcm_init()

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.

This function is supported in multi-core environment and it must be called in secondary core application before invoking any virtual WCM APIs.

Note: The secondary core can invoke this API by passing the config parameter as NULL.

Parameters

[in] config The configuration to be initialized.

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

◆ cy_wcm_deinit()

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.

This function is supported in multi-core environment and can be invoked in the secondary core application which then cleans up all the resources of WCM in secondary core.

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.

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

◆ cy_wcm_start_scan()

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

Parameters

[in]	scan_callback	: Callback function which receives the scan results; callback will be executed in the context of the WCM. Scan results will be individually provided to this callback function. For more details on the scan results, see cy_wcm_scan_result_callback_t.
[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).

Returns: 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".

◆ cy_wcm_stop_scan()

cy_rslt_t cy_wcm_stop_scan ( void )

Stops an ongoing Wi-Fi network scan.

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

◆ cy_wcm_connect_ap()

cy_rslt_t cy_wcm_connect_ap	(	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 a successful connection to the Wi-Fi network, the API returns the IP address. If the user does not know the security type of the AP then, connect_param.ap_credentials.security must be set to CY_WCM_SECURITY_UNKNOWN so that the library will internally find the security type before connecting to AP.

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. 3) If the user does not know the security type of the AP, the library internally finds the security type.

Parameters

[in]	connect_params	: Configuration to join the AP.
[out]	ip_addr	: Pointer to return the IP address (optional).

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

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

◆ cy_wcm_disconnect_ap()

cy_rslt_t cy_wcm_disconnect_ap ( void )

Disconnects the STA interface from the currently connected AP.

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

◆ cy_wcm_get_ip_addr()

cy_rslt_t cy_wcm_get_ip_addr	(	cy_wcm_interface_t	interface_type,
		cy_wcm_ip_address_t *	ip_addr
	)

Retrieves the IPv4 address of the given interface.

See cy_wcm_get_ipv6_addr API to get IPv6 addresses.

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. ip_addr should have enough valid memory to hold two IP address structures.

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

◆ cy_wcm_get_ipv6_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
	)

Retrieves the IPv6 address of the given interface.

Note: Currently, this API supports only CY_WCM_IPV6_LINK_LOCAL type.

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. ip_addr should have enough valid memory to hold two IP address structures.

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

◆ cy_wcm_get_gateway_ip_address()

cy_rslt_t cy_wcm_get_gateway_ip_address	(	cy_wcm_interface_t	interface_type,
		cy_wcm_ip_address_t *	gateway_addr
	)

Retrieves the gateway IP address of the given interface.

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. gateway_addr should have enough valid memory to hold two IP address structures. In future, IPv6 addresses will be supported.

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

◆ cy_wcm_get_ip_netmask()

cy_rslt_t cy_wcm_get_ip_netmask	(	cy_wcm_interface_t	interface_type,
		cy_wcm_ip_address_t *	net_mask_addr
	)

Retrieves the subnet mask address of the given interface.

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. net_mask_addr should have enough valid memory to hold two IP address structures.

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

◆ cy_wcm_get_mac_addr()

cy_rslt_t cy_wcm_get_mac_addr	(	cy_wcm_interface_t	interface_type,
		cy_wcm_mac_t *	mac_addr
	)

Retrieves the MAC address of the given interface.

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. mac_addr should have enough valid memory to hold two MAC address structures.

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

◆ cy_wcm_wps_enrollee()

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.

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.
[in,out]	credential_count	: Upon invocation, this parameter stores the size of the credentials parameter. Upon return, denotes the actual number of credentials returned.

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

◆ cy_wcm_wps_generate_pin()

cy_rslt_t cy_wcm_wps_generate_pin ( char wps_pin_string[CY_WCM_WPS_PIN_LENGTH] )

Generates a random WPS PIN for PIN mode connection.

Parameters

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

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

◆ cy_wcm_register_event_callback()

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 the STA interface and notifies the clients which are connected or disconnected from the SoftAP.

This API is supported in multi-core environment and can be invoked as a virtual API from the secondary core application.

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

Parameters

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

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

◆ cy_wcm_deregister_event_callback()

cy_rslt_t cy_wcm_deregister_event_callback ( cy_wcm_event_callback_t event_callback )

De-registers an event callback.

This API is supported in multi-core environment and can be invoked as a virtual API from the secondary core application.

Parameters

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

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

◆ cy_wcm_is_connected_to_ap()

uint8_t cy_wcm_is_connected_to_ap ( void )

Checks if the STA interface is connected to an AP.

This API is supported in multi-core environment and can be invoked as a virtual API from the secondary core application.

Returns: 1 if connected, 0 otherwise.

◆ cy_wcm_get_associated_ap_info()

cy_rslt_t cy_wcm_get_associated_ap_info ( cy_wcm_associated_ap_info_t * ap_info )

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

Parameters

[out] ap_info : Pointer to store the information of the associated AP cy_wcm_associated_ap_info_t.

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

◆ cy_wcm_get_wlan_statistics()

cy_rslt_t cy_wcm_get_wlan_statistics	(	cy_wcm_interface_t	interface,
		cy_wcm_wlan_statistics_t *	stat
	)

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.

Parameters

[in]	interface	: Type of the WCM interface.
[in]	stat	: Pointer to store the statistics cy_wcm_wlan_statistics_t.

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

◆ cy_wcm_get_gateway_mac_address()

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.

Parameters

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

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

◆ cy_wcm_ping()

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.

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.

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

◆ cy_wcm_start_ap()

cy_rslt_t cy_wcm_start_ap ( const cy_wcm_ap_config_t * ap_config )

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

Parameters

[in] ap_config : Configuration parameters for the SoftAP.

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

◆ cy_wcm_stop_ap()

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.

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

◆ cy_wcm_get_associated_client_list()

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.

Parameters

[out]	sta_list	: Pointer to the MAC address (or) array of MAC addresses. The client's (STA) MAC address is stored on this array before the function returns.
[in]	num_clients	: Length of the array passed in sta_list.

Note: If the number of connected clients is less than the num_clients, then elements of sta_list beyond number of connected clients will be set to zero. The maximum number of supported client list varies for different Wi-Fi chips.

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

◆ cy_wcm_set_ap_ip_setting()

cy_rslt_t cy_wcm_set_ap_ip_setting	(	cy_wcm_ip_setting_t *	ap_ip,
		const char *	ip_addr,
		const char *	netmask,
		const char *	gateway_addr,
		cy_wcm_ip_version_t	ver
	)

Stores the AP settings provided by the user.

NOTE: Dotted-decimal format example: 192.168.0.1

Parameters

[in]	ip_addr	: Pointer to an array containing the IP address of the AP in dotted-decimal format.
[in]	netmask	: Pointer to an array containing the network mask in dotted-decimal format.
[in]	gateway_addr	: Pointer to an array containing the gateway address in dotted-decimal format.
[in]	ver	: IP version. Possible values CY_WCM_IP_VER_V6 or CY_WCM_IP_VER_V4.
[in]	ap_ip	: Pointer to the variable which stores AP settings.

Returns: CY_RSLT_SUCCESS if the AP settings are successfully stored in the user-provided variable; returns WCM-specific error codes otherwise.

◆ cy_wcm_allow_low_power_mode()

cy_rslt_t cy_wcm_allow_low_power_mode ( cy_wcm_powersave_mode_t mode )

Sets low power mode capability for WLAN CPU.

Parameters

[in] mode - can be one of: CY_WCM_NO_POWERSAVE_MODE WLAN CPU will not go into powersave mode CY_WCM_PM1_POWERSAVE_MODE Powersave mode on specified interface without regard for throughput reduction CY_WCM_PM2_POWERSAVE_MODE Powersave mode on specified interface with High throughput

Returns: CY_RSLT_SUCCESS if the Wi-Fi module mode was successfully changed; returns WCM-specific error codes otherwise.

General Description

Functions

Function Documentation

◆ cy_wcm_init()

◆ cy_wcm_deinit()

◆ cy_wcm_start_scan()

◆ cy_wcm_stop_scan()

◆ cy_wcm_connect_ap()

◆ cy_wcm_disconnect_ap()

◆ cy_wcm_get_ip_addr()

◆ cy_wcm_get_ipv6_addr()

◆ cy_wcm_get_gateway_ip_address()

◆ cy_wcm_get_ip_netmask()

◆ cy_wcm_get_mac_addr()

◆ cy_wcm_wps_enrollee()

◆ cy_wcm_wps_generate_pin()

◆ cy_wcm_register_event_callback()

◆ cy_wcm_deregister_event_callback()

◆ cy_wcm_is_connected_to_ap()

◆ cy_wcm_get_associated_ap_info()

◆ cy_wcm_get_wlan_statistics()

◆ cy_wcm_get_gateway_mac_address()

◆ cy_wcm_ping()

◆ cy_wcm_start_ap()

◆ cy_wcm_stop_ap()

◆ cy_wcm_get_associated_client_list()

◆ cy_wcm_set_ap_ip_setting()

◆ cy_wcm_allow_low_power_mode()