/*
* FreeRTOS WiFi V2.0.0
* Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
* http://aws.amazon.com/freertos
* http://www.FreeRTOS.org
*/
/**
* @file iot_wifi.h
* @brief Wi-Fi Interface.
*/
#ifndef _AWS_WIFI_H_
#define _AWS_WIFI_H_
#include <stdint.h>
/* FreeRTOS include for BaseType_t. */
#include "portmacro.h"
/* Wi-Fi configuration includes. */
#include "aws_wifi_config.h"
/**
* @brief IPV6 length in 32-bit words
*
* @note This is the constant for IPV6 length in 32-bit words
*/
#define IPV6_LENGTH 4
/**
* @brief Wi-Fi lower level supported feature mask.
*
* @see WIFICapabilityInfo_t.
*/
#define WIFI_WPS_SUPPORTED 0x0001
#define WIFI_ENTERPRISE_SUPPORTED 0x0002
#define WIFI_P2P_SUPPORTED 0x0004
#define WIFI_TDLS_SUPPORTED 0x0008
/**
* @brief Return code denoting API status.
*
* @note Codes other than eWiFiSuccess are failure codes.
* @ingroup WiFi_datatypes_enums
*/
typedef enum
{
eWiFiSuccess = 0, /**< Success. */
eWiFiFailure = 1, /**< Failure. */
eWiFiTimeout = 2, /**< Timeout. */
eWiFiNotSupported = 3, /**< Not supported. */
} WIFIReturnCode_t;
/**
* @brief Wi-Fi Security types.
*
* @ingroup WiFi_datatypes_enums
*/
typedef enum
{
eWiFiSecurityOpen = 0, /**< Open - No Security. */
eWiFiSecurityWEP, /**< WEP Security. */
eWiFiSecurityWPA, /**< WPA Security. */
eWiFiSecurityWPA2, /**< WPA2 Security. */
eWiFiSecurityWPA2_ent, /**< WPA2 Enterprise Security. */
eWiFiSecurityWPA3, /**< WPA3 Security. */
eWiFiSecurityNotSupported /**< Unknown Security. */
} WIFISecurity_t;
/**
* @brief Wi-Fi device modes.
*
* Device roles/modes supported.
* @ingroup WiFi_datatypes_enums
*/
typedef enum
{
eWiFiModeStation = 0, /**< Station mode. */
eWiFiModeAP, /**< Access point mode. */
eWiFiModeP2P, /**< P2P mode. */
eWiFiModeAPStation, /**< AP+Station (repeater) mode. */
eWiFiModeNotSupported /**< Unsupported mode. */
} WIFIDeviceMode_t;
/**
* @brief Wi-Fi device power management modes.
*
* Device power management modes supported.
* @ingroup WiFi_datatypes_enums
*/
typedef enum
{
eWiFiPMNormal = 0, /**< Normal mode. */
eWiFiPMLowPower, /**< Low Power mode. */
eWiFiPMAlwaysOn, /**< Always On mode. */
eWiFiPMNotSupported /**< Unsupported PM mode. */
} WIFIPMMode_t;
/**
* @brief Wi-Fi WEP keys (64- and 128-bit keys only)
*/
typedef struct
{
char cKey[ wificonfigMAX_WEPKEY_LEN ]; /**< WEP key (binary array, not C-string). */
uint8_t ucLength; /**< Key length. */
} WIFIWEPKey_t;
/**
* @brief Wi-Fi WPA/WPA2 passphrase
*/
typedef struct
{
char cPassphrase[ wificonfigMAX_PASSPHRASE_LEN ]; /**< WPA passphrase (binary array, not C-string). */
uint8_t ucLength; /**< Passphrase length (must be between 8 and 64 inclusive). */
} WIFIWPAPassphrase_t;
/**
* @brief Parameters passed to the WIFI_ConnectAP API for connection.
*
* @see WIFI_ConnectAP
*
* @ingroup WiFi_datatypes_paramstructs
*/
typedef struct
{
uint8_t ucSSID[ wificonfigMAX_SSID_LEN ]; /**< SSID of the Wi-Fi network (binary array, not C-string). */
uint8_t ucSSIDLength; /**< SSID length. */
WIFISecurity_t xSecurity; /**< Wi-Fi Security. */
union
{
WIFIWEPKey_t xWEP[ wificonfigMAX_WEPKEYS ]; /**< WEP keys. */
WIFIWPAPassphrase_t xWPA; /**< WPA/WPA2 passphrase. */
} xPassword;
uint8_t ucDefaultWEPKeyIndex; /**< Default WEP key index. */
uint8_t ucChannel; /**< Channel number. */
} WIFINetworkParams_t;
/**
* @brief Wi-Fi scan configuration.
*/
typedef struct
{
uint8_t ucSSID[ wificonfigMAX_SSID_LEN ]; /**< SSID for targeted scan (binary array, not C-string). */
uint8_t ucSSIDLength; /**< SSID length, 0 if broadcast scan. */
uint8_t ucChannel; /**< Channel to scan (0 means all channels). */
} WIFIScanConfig_t;
/**
* @brief Wi-Fi scan results.
*
* Structure to store the Wi-Fi scan results.
*
* @note The size of char arrays are the MAX lengths + 1 to
* account for possible null terminating at the end of the
* strings.
*
* @see WIFI_Scan
*
* @ingroup WiFi_datatypes_returnstructs
*/
typedef struct
{
uint8_t ucSSID[ wificonfigMAX_SSID_LEN ]; /**< SSID of the Wi-Fi network (binary array, not C-string). */
uint8_t ucSSIDLength; /**< SSID length. */
uint8_t ucBSSID[ wificonfigMAX_BSSID_LEN ]; /**< BSSID of the Wi-Fi network (binary array, not C-string). */
WIFISecurity_t xSecurity; /**< Security type of the Wi-Fi network. */
int8_t cRSSI; /**< Signal strength of the Wi-Fi network. */
uint8_t ucChannel; /**< Channel of the Wi-Fi network. */
} WIFIScanResult_t;
/**
* @brief Wi-Fi SoftAP connected station info.
*/
typedef struct
{
uint8_t ucMAC[ wificonfigMAX_BSSID_LEN ]; /**< MAC address of Wi-Fi station */
} WIFIStationInfo_t;
/**
* @brief Wi-Fi network parameters passed to the WIFI_NetworkAdd API.
*
* @note The size of char arrays are the MAX lengths + 1 to
* account for possible null terminating at the end of the
* strings.
*
* @ingroup WiFi_datatypes_paramstructs
*/
typedef struct
{
uint8_t ucSSID[ wificonfigMAX_SSID_LEN ]; /**< SSID of the Wi-Fi network to join with a NULL termination. */
uint8_t ucSSIDLength; /**< SSID length not including NULL termination. */
uint8_t ucBSSID[ wificonfigMAX_BSSID_LEN ]; /**< BSSID of the Wi-Fi network. */
char cPassword[ wificonfigMAX_PASSPHRASE_LEN ]; /**< Password needed to join the AP. */
uint8_t ucPasswordLength; /**< Password length not including null termination. */
WIFISecurity_t xSecurity; /**< Wi-Fi Security. @see WIFISecurity_t. */
} WIFINetworkProfile_t;
/**
* @brief Wi-Fi station IP address type.
*/
typedef enum
{
eWiFiIPAddressTypeV4,
eWiFiIPAddressTypeV6,
eWiFiIPAddressTypeNotSupported,
} WIFIIPAddressType_t;
/**
* @brief Wi-Fi station IP address format.
*/
typedef struct
{
WIFIIPAddressType_t xType; /**< IP address type (only eWiFiIPAddressTypeV4 is currently supported). */
uint32_t ulAddress[ IPV6_LENGTH ]; /**< IP address in binary form, use inet_ntop/inet_pton for conversion. */
} WIFIIPAddress_t;
/**
* @brief IP address configuration.
*/
typedef struct
{
WIFIIPAddress_t xIPAddress; /**< IP address */
WIFIIPAddress_t xNetMask; /**< Network mask */
WIFIIPAddress_t xGateway; /**< Gateway IP address */
WIFIIPAddress_t xDns1; /**< First DNS server IP address */
WIFIIPAddress_t xDns2; /**< Second DNS server IP address */
} WIFIIPConfiguration_t;
/**
* @brief Wi-Fi info of the connected AP.
*
* Structure to store info of the connected AP.
*/
typedef struct
{
uint8_t ucSSID[ wificonfigMAX_SSID_LEN ]; /**< SSID of the Wi-Fi network (binary array, not C-string). */
uint8_t ucSSIDLength; /**< SSID length. */
uint8_t ucBSSID[ wificonfigMAX_BSSID_LEN ]; /**< BSSID of the Wi-Fi network (binary array, not C-string). */
WIFISecurity_t xSecurity; /**< Wi-Fi Security. */
uint8_t ucChannel; /**< Channel info. */
} WIFIConnectionInfo_t;
/**
* @brief Wi-Fi protocol reason codes.
*/
typedef enum
{
eWiFiReasonUnspecified, /**< Unspecified error */
eWiFiReasonAPNotFound, /**< Cannot find the target AP. */
eWiFiReasonAuthExpired, /**< Previous auth invalid. */
eWiFiReasonAuthLeaveBSS, /**< Deauth leaving BSS. */
eWiFiReasonAuthFailed, /**< All other AUTH errors. */
eWiFiReasonAssocExpired, /**< Disassoc due to inactivity. */
eWiFiReasonAssocTooMany, /**< AP is overloaded. */
eWiFiReasonAssocPowerCapBad, /**< Power capability unacceptable. */
eWiFiReasonAssocSupChanBad, /**< Supported channel unacceptable. */
eWiFiReasonAssocFailed, /**< All other ASSOC errors. */
eWiFiReasonIEInvalid, /**< Management frame IE invalid. */
eWiFiReasonMICFailure, /**< MIC failure detected. */
eWiFiReason4WayTimeout, /**< 4WAY handshake timeout. */
eWiFiReason4WayIEDiffer, /**< 4WAY handshake IE error. */
eWiFiReason4WayFailed, /**< All other 4WAY errors. */
eWiFiReasonAKMPInvalid, /**< AKMP invalid. */
eWiFiReasonPairwiseCipherInvalid, /**< Pairwise cipher invalid. */
eWiFiReasonGroupCipherInvalid, /**< Group cipher invalid. */
eWiFiReasonRSNVersionInvalid, /**< RSN version invalid. */
eWiFiReasonRSNCapInvalid, /**< RSN capability invalid. */
eWiFiReasonGroupKeyUpdateTimeout, /**< Group key update timeout. */
eWiFiReasonCipherSuiteRejected, /**< Cipher violates security policy. */
eWiFiReason8021XAuthFailed, /**< 802.1X auth errors. */
eWiFiReasonBeaconTimeout, /**< Beacon timeout. */
eWiFiReasonLinkFailed, /**< All other link errors. */
eWiFiReasonDHCPExpired, /**< DHCP license expired. */
eWiFiReasonDHCPFailed, /**< All other DHCP errors. */
eWiFiReasonMax
} WIFIReason_t;
/**
* @brief Wi-Fi event types.
*/
typedef enum
{
eWiFiEventReady, /**< Wi-Fi is initialized or was reset in the lower layer. */
eWiFiEventScanDone, /**< Scan is finished. */
eWiFiEventConnected, /**< Station is connected to the AP. */
eWiFiEventDisconnected, /**< Station is disconnected from the AP. */
eWiFiEventConnectionFailed, /**< Station connection has failed. */
eWiFiEventIPReady, /**< DHCP is successful. */
eWiFiEventAPStateChanged, /**< SoftAP state changed. */
eWiFiEventAPStationConnected, /**< SoftAP got a new station. */
eWiFiEventAPStationDisconnected, /**< SoftAP lost a new station. */
eWiFiEventWPSSuccess, /**< WPS is completed successfully. */
eWiFiEventWPSFailed, /**< WPS has failed. */
eWiFiEventWPSTimeout, /**< WPS has timeout. */
eWiFiEventMax
} WIFIEventType_t;
/**
* @brief Wi-Fi event info for WI-FI ready.
*/
typedef struct
{
uint8_t dummy;
} WiFiEventInfoReady_t;
/**
* @brief Wi-Fi event info for scan done.
*/
typedef struct
{
WIFIScanResult_t * pxScanResults;
uint16_t usNumScanResults;
} WiFiEventInfoScanDone_t;
/**
* @brief Wi-Fi event info for station connected to AP.
*/
typedef struct
{
WIFIConnectionInfo_t xConnectionInfo;
} WiFiEventInfoConnected_t;
/**
* @brief Wi-Fi event info for station disconnected from AP.
*/
typedef struct
{
WIFIReason_t xReason; /**< Reason code for station disconnection. */
} WiFiEventInfoDisconnected_t;
/**
* @brief Wi-Fi event info for station connection failure.
*/
typedef struct
{
WIFIReason_t xReason; /**< Reason code for connection failure. */
} WiFiEventInfoConnectionFailed_t;
/**
* @brief Wi-Fi event info for IP ready.
*/
typedef struct
{
WIFIIPAddress_t xIPAddress; /**< Station IP address from DHCP. */
} WiFiEventInfoIPReady_t;
/**
* @brief Wi-Fi event info for AP state change.
*/
typedef struct
{
uint8_t ucState; /**< AP state: 0 = DOWN, 1 = UP. */
} WiFiEventInfoAPStateChanged_t;
/**
* @brief Wi-Fi event info for AP got a connected station.
*/
typedef struct
{
uint8_t ucMac[ wificonfigMAX_BSSID_LEN ]; /**< MAC address of connected station. */
} WiFiEventInfoAPStationConnected_t;
/**
* @brief Wi-Fi event info for AP got a disconnected station.
*/
typedef struct
{
uint8_t ucMac[ wificonfigMAX_BSSID_LEN ]; /**< MAC address of disconnected station. */
WIFIReason_t xReason; /**< Reason code for the disconnection. */
} WiFiEventInfoAPStationDisconnected_t;
/**
* @brief Wi-Fi event info for receiving a frame in monitor mode (or normal mode
* with RX filter).
*/
typedef struct
{
uint8_t * pucData; /**< Data buffer of received raw frame. */
uint32_t ulLength; /**< Length of the raw frame. */
} WiFiEventInfoRxDone_t;
/**
* @brief Wi-Fi event info for finishing transmitting an injection frame.
*/
typedef struct
{
uint8_t dummy;
} WiFiEventInfoTxDone_t;
/**
* @brief Wi-Fi combined event data structure.
*/
typedef struct
{
WIFIEventType_t xEventType;
union
{
WiFiEventInfoReady_t xReady;
WiFiEventInfoScanDone_t xScanDone;
WiFiEventInfoConnected_t xConnected;
WiFiEventInfoIPReady_t xIPReady;
WiFiEventInfoDisconnected_t xDisconnected;
WiFiEventInfoConnectionFailed_t xConnectionFailed;
WiFiEventInfoAPStateChanged_t xAPStateChanged;
WiFiEventInfoAPStationConnected_t xAPStationConnected;
WiFiEventInfoAPStationDisconnected_t xAPStationDisconnected;
WiFiEventInfoRxDone_t xRxDone;
WiFiEventInfoTxDone_t xTxDone;
} xInfo;
} WIFIEvent_t;
/**
* @brief Wi-Fi Statistic info.
*/
typedef struct
{
uint32_t ulTxSuccessCount; /**< Number of TX successes, 0 if unavailable */
uint32_t ulTxRetryCount; /**< Number of TX retries, 0 if unavailable */
uint32_t ulTxFailCount; /**< Number of TX failures, 0 if unavailable */
uint32_t ulRxSuccessCount; /**< Number of RX successes, 0 if unavailable */
uint32_t ulRxCRCErrorCount; /**< Number of RX FCS errors, 0 if unavailable */
uint32_t ulMICErrorCount; /**< Number of MIC errors, 0 if unavailable */
int8_t cNoise; /**< Average noise level in dBm, -128 if unavailable */
uint16_t usPhyRate; /**< Maximum used PHY rate, 0 if unavailable */
uint16_t usTxRate; /**< Average used TX rate, 0 if unavailable */
uint16_t usRxRate; /**< Average used RX rate, 0 if unavailable */
int8_t cRssi; /**< Average beacon RSSI in dBm, -128 if unavailable */
uint8_t ucBandwidth; /**< Average used bandwidth, 0 if unavailable */
uint8_t ucIdleTimePer; /**< Percent of idle time, 0 if unavailable */
} WIFIStatisticInfo_t;
/**
* @brief Wi-Fi band.
*/
typedef enum
{
eWiFiBand2G = 0, /**< 2.4G band */
eWiFiBand5G, /**< 5G band */
eWiFiBandDual, /**< Dual band */
eWiFiBandMax /**< Unsupported */
} WIFIBand_t;
/**
* @brief Wi-Fi PHY mode.
*/
typedef enum
{
eWiFiPhy11b = 0, /**< 11B */
eWiFiPhy11g, /**< 11G */
eWiFiPhy11n, /**< 11N */
eWiFiPhy11ac, /**< 11AC */
eWiFiPhy11ax, /**< 11AX */
eWiFiPhyMax, /**< Unsupported */
} WIFIPhyMode_t;
/**
* @brief Wi-Fi bandwidth.
*/
typedef enum
{
eWiFiBW20 = 0, /**< 20MHz only */
eWiFiBW40, /**< Max 40MHz */
eWiFiBW80, /**< Max 80MHz */
eWiFiBW160, /**< Max 80+80 or 160MHz */
eWiFiBWMax /**< Unsupported */
} WIFIBandwidth_t;
/**
* @brief Wi-Fi capabilities.
*
* @note Applications can use it to check whether the Wi-Fi interface can meet their
* requirements (features like P2P, or performance as shown by xPhyMode and xBandwidth).
*/
typedef struct
{
WIFIBand_t xBand; /**< Supported band */
WIFIPhyMode_t xPhyMode; /**< Supported PHY mode */
WIFIBandwidth_t xBandwidth; /**< Supported bandwidth */
uint32_t ulMaxAggr; /**< Max aggregation length, 0 if no aggregation support */
uint16_t usSupportedFeatures; /**< Supported features bitmap, e.g., WIFI_WPS_SUPPORTED */
} WIFICapabilityInfo_t;
/**
* @brief Wi-Fi event handler definition.
*
* @param[in] xEvent - Wi-Fi event data structure.
*
* @return None.
*/
typedef void (* WIFIEventHandler_t)( WIFIEvent_t * xEvent );
/**
* @brief Turns on Wi-Fi.
*
* This function turns on Wi-Fi module,initializes the drivers and must be called
* before calling any other Wi-Fi API
*
* @return @ref eWiFiSuccess if Wi-Fi module was successfully turned on, failure code otherwise.
*/
/* @[declare_wifi_wifi_on] */
WIFIReturnCode_t WIFI_On( void );
/* @[declare_wifi_wifi_on] */
/**
* @brief Turns off Wi-Fi.
*
* This function turns off the Wi-Fi module. The Wi-Fi peripheral should be put in a
* low power or off state in this routine.
*
* @return @ref eWiFiSuccess if Wi-Fi module was successfully turned off, failure code otherwise.
*/
/* @[declare_wifi_wifi_off] */
WIFIReturnCode_t WIFI_Off( void );
/* @[declare_wifi_wifi_off] */
/**
* @brief Connects to the Wi-Fi Access Point (AP) specified in the input.
*
* The Wi-Fi should stay connected when the same Access Point it is currently connected to
* is specified. Otherwise, the Wi-Fi should disconnect and connect to the new Access Point
* specified. If the new Access Point specifed has invalid parameters, then the Wi-Fi should be
* disconnected.
*
* @param[in] pxNetworkParams Configuration to join AP.
*
* @return @ref eWiFiSuccess if connection is successful, failure code otherwise.
*
* **Example**
* @code
* WIFINetworkParams_t xNetworkParams;
* WIFIReturnCode_t xWifiStatus;
* xNetworkParams.pcSSID = "SSID String";
* xNetworkParams.ucSSIDLength = SSIDLen;
* xNetworkParams.pcPassword = "Password String";
* xNetworkParams.ucPasswordLength = PassLength;
* xNetworkParams.xSecurity = eWiFiSecurityWPA2;
* xWifiStatus = WIFI_ConnectAP( &( xNetworkParams ) );
* if(xWifiStatus == eWiFiSuccess)
* {
* //Connected to AP.
* }
* @endcode
*
* @see WIFINetworkParams_t
*/
/* @[declare_wifi_wifi_connectap] */
WIFIReturnCode_t WIFI_ConnectAP( const WIFINetworkParams_t * const pxNetworkParams );
/* @[declare_wifi_wifi_connectap] */
/**
* @brief Disconnects from the currently connected Access Point.
*
* @return @ref eWiFiSuccess if disconnection was successful or if the device is already
* disconnected, failure code otherwise.
*/
/* @[declare_wifi_wifi_disconnect] */
WIFIReturnCode_t WIFI_Disconnect( void );
/* @[declare_wifi_wifi_disconnect] */
/**
* @brief Resets the Wi-Fi Module.
*
* @return @ref eWiFiSuccess if Wi-Fi module was successfully reset, failure code otherwise.
*/
/* @[declare_wifi_wifi_reset] */
WIFIReturnCode_t WIFI_Reset( void );
/* @[declare_wifi_wifi_reset] */
/**
* @brief Sets the Wi-Fi mode.
*
* @param[in] xDeviceMode - Mode of the device Station / Access Point /P2P.
*
* **Example**
* @code
* WIFIReturnCode_t xWifiStatus;
* xWifiStatus = WIFI_SetMode(eWiFiModeStation);
* if(xWifiStatus == eWiFiSuccess)
* {
* //device Set to station mode
* }
* @endcode
*
* @return @ref eWiFiSuccess if Wi-Fi mode was set successfully, failure code otherwise.
*/
/* @[declare_wifi_wifi_setmode] */
WIFIReturnCode_t WIFI_SetMode( WIFIDeviceMode_t xDeviceMode );
/* @[declare_wifi_wifi_setmode] */
/**
* @brief Gets the Wi-Fi mode.
*
* @param[out] pxDeviceMode - return mode Station / Access Point /P2P
*
* **Example**
* @code
* WIFIReturnCode_t xWifiStatus;
* WIFIDeviceMode_t xDeviceMode;
* xWifiStatus = WIFI_GetMode(&xDeviceMode);
* if(xWifiStatus == eWiFiSuccess)
* {
* //device mode is xDeviceMode
* }
* @endcode
*
* @return @ref eWiFiSuccess if Wi-Fi mode was successfully retrieved, failure code otherwise.
*/
/* @[declare_wifi_wifi_getmode] */
WIFIReturnCode_t WIFI_GetMode( WIFIDeviceMode_t * pxDeviceMode );
/* @[declare_wifi_wifi_getmode] */
/**
* @brief Add a Wi-Fi Network profile.
*
* Adds a Wi-fi network to the network list in Non Volatile memory.
*
* @param[in] pxNetworkProfile - Network profile parameters
* @param[out] pusIndex - Network profile index in storage
*
* @return Index of the profile storage on success, or failure return code on failure.
*
* **Example**
* @code
* WIFINetworkProfile_t xNetworkProfile = {0};
* WIFIReturnCode_t xWiFiStatus;
* uint16_t usIndex;
* strncpy( xNetworkProfile.cSSID, "SSID_Name", SSIDLen));
* xNetworkProfile.ucSSIDLength = SSIDLen;
* strncpy( xNetworkProfile.cPassword, "PASSWORD",PASSLen );
* xNetworkProfile.ucPasswordLength = PASSLen;
* xNetworkProfile.xSecurity = eWiFiSecurityWPA2;
* WIFI_NetworkAdd( &xNetworkProfile, &usIndex );
* @endcode
*/
/* @[declare_wifi_wifi_networkadd] */
WIFIReturnCode_t WIFI_NetworkAdd( const WIFINetworkProfile_t * const pxNetworkProfile,
uint16_t * pusIndex );
/* @[declare_wifi_wifi_networkadd] */
/**
* @brief Get a Wi-Fi network profile.
*
* Gets the Wi-Fi network parameters at the given index from network list in non-volatile
* memory.
*
* @note The WIFINetworkProfile_t data returned must have the the SSID and Password lengths
* specified as the length without a null terminator.
*
* @param[out] pxNetworkProfile - pointer to return network profile parameters
* @param[in] usIndex - Index of the network profile,
* must be between 0 to wificonfigMAX_NETWORK_PROFILES
*
* @return @ref eWiFiSuccess if the network profile was successfully retrieved, failure code
* otherwise.
*
* @see WIFINetworkProfile_t
*
* **Example**
* @code
* WIFINetworkProfile_t xNetworkProfile = {0};
* uint16_t usIndex = 3; //Get profile stored at index 3.
* WIFI_NetworkGet( &xNetworkProfile, usIndex );
* @endcode
*/
/* @[declare_wifi_wifi_networkget] */
WIFIReturnCode_t WIFI_NetworkGet( WIFINetworkProfile_t * pxNetworkProfile,
uint16_t usIndex );
/* @[declare_wifi_wifi_networkget] */
/**
* @brief Delete a Wi-Fi Network profile.
*
* Deletes the Wi-Fi network profile from the network profile list at given index in
* non-volatile memory
*
* @param[in] usIndex - Index of the network profile, must be between 0 to
* wificonfigMAX_NETWORK_PROFILES.
*
* If wificonfigMAX_NETWORK_PROFILES is the index, then all
* network profiles will be deleted.
*
* @return @ref eWiFiSuccess if successful, failure code otherwise. If successful, the
* interface IP address is copied into the IP address buffer.
*
* **Example**
* @code
* uint16_t usIndex = 2; //Delete profile at index 2
* WIFI_NetworkDelete( usIndex );
* @endcode
*
*/
/* @[declare_wifi_wifi_networkdelete] */
WIFIReturnCode_t WIFI_NetworkDelete( uint16_t usIndex );
/* @[declare_wifi_wifi_networkdelete] */
/**
* @brief Ping an IP address in the network.
*
* @param[in] pucIPAddr IP Address array to ping.
* @param[in] usCount Number of times to ping
* @param[in] ulIntervalMS Interval in mili-seconds for ping operation
*
* @return @ref eWiFiSuccess if ping was successful, other failure code otherwise.
*/
/* @[declare_wifi_wifi_ping] */
WIFIReturnCode_t WIFI_Ping( uint8_t * pucIPAddr,
uint16_t usCount,
uint32_t ulIntervalMS );
/* @[declare_wifi_wifi_ping] */
/**
* @brief Retrieves the Wi-Fi interface's MAC address.
*
* @param[out] pucMac MAC Address buffer sized 6 bytes.
*
* **Example**
* @code
* uint8_t ucMacAddressVal[ wificonfigMAX_BSSID_LEN ];
* WIFI_GetMAC( &ucMacAddressVal[0] );
* @endcode
*
* @return @ref eWiFiSuccess if the MAC address was successfully retrieved, failure code
* otherwise. The returned MAC address must be 6 consecutive bytes with no delimitters.
*/
/* @[declare_wifi_wifi_getmac] */
WIFIReturnCode_t WIFI_GetMAC( uint8_t * pucMac );
/* @[declare_wifi_wifi_getmac] */
/**
* @brief Retrieves the host IP address from a host name using DNS.
*
* @param[in] pcHost - Host (node) name.
* @param[in] pucIPAddr - IP Address buffer.
*
* @return @ref eWiFiSuccess if the host IP address was successfully retrieved, failure code
* otherwise.
*
* **Example**
* @code
* uint8_t ucIPAddr[ 4 ];
* WIFI_GetHostIP( "amazon.com", &ucIPAddr[0] );
* @endcode
*/
/* @[declare_wifi_wifi_gethostip] */
WIFIReturnCode_t WIFI_GetHostIP( char * pcHost,
uint8_t * pucIPAddr );
/* @[declare_wifi_wifi_gethostip] */
/**
* @brief Perform a Wi-Fi network Scan.
*
* @param[in] pxBuffer - Buffer for scan results.
* @param[in] ucNumNetworks - Number of networks to retrieve in scan result.
*
* @return @ref eWiFiSuccess if the Wi-Fi network scan was successful, failure code otherwise.
*
* @note The input buffer will have the results of the scan.
*
* **Example**
* @code
* const uint8_t ucNumNetworks = 10; //Get 10 scan results
* WIFIScanResult_t xScanResults[ ucNumNetworks ];
* WIFI_Scan( xScanResults, ucNumNetworks );
* @endcode
*/
/* @[declare_wifi_wifi_scan] */
WIFIReturnCode_t WIFI_Scan( WIFIScanResult_t * pxBuffer,
uint8_t ucNumNetworks );
/* @[declare_wifi_wifi_scan] */
/**
* @brief Start SoftAP mode.
*
* @return @ref eWiFiSuccess if SoftAP was successfully started, failure code otherwise.
*/
/* @[declare_wifi_wifi_startap] */
WIFIReturnCode_t WIFI_StartAP( void );
/* @[declare_wifi_wifi_startap] */
/**
* @brief Stop SoftAP mode.
*
* @return @ref eWiFiSuccess if the SoftAP was successfully stopped, failure code otherwise.
*/
/* @[declare_wifi_wifi_stopap] */
WIFIReturnCode_t WIFI_StopAP( void );
/* @[declare_wifi_wifi_stopap] */
/**
* @brief Configure SoftAP.
*
* @param[in] pxNetworkParams - Network parameters to configure AP.
*
* @return @ref eWiFiSuccess if SoftAP was successfully configured, failure code otherwise.
*
* **Example**
* @code
* WIFINetworkParams_t xNetworkParams;
* xNetworkParams.pcSSID = "SSID_Name";
* xNetworkParams.pcPassword = "PASSWORD";
* xNetworkParams.xSecurity = eWiFiSecurityWPA2;
* xNetworkParams.cChannel = ChannelNum;
* WIFI_ConfigureAP( &xNetworkParams );
* @endcode
*/
/* @[declare_wifi_wifi_configureap] */
WIFIReturnCode_t WIFI_ConfigureAP( const WIFINetworkParams_t * const pxNetworkParams );
/* @[declare_wifi_wifi_configureap] */
/**
* @brief Set the Wi-Fi power management mode.
*
* @param[in] xPMModeType - Power mode type.
*
* @param[in] pvOptionValue - A buffer containing the value of the option to set
* depends on the mode type
* example - beacon interval in sec
*
* @return @ref eWiFiSuccess if the power mode was successfully configured, failure code otherwise.
*/
/* @[declare_wifi_wifi_setpmmode] */
WIFIReturnCode_t WIFI_SetPMMode( WIFIPMMode_t xPMModeType,
const void * pvOptionValue );
/* @[declare_wifi_wifi_setpmmode] */
/**
* @brief Get the Wi-Fi power management mode
*
* @param[out] pxPMModeType - pointer to get current power mode set.
*
* @param[out] pvOptionValue - optional value
*
* @return @ref eWiFiSuccess if the power mode was successfully retrieved, failure code otherwise.
*/
/* @[declare_wifi_wifi_getpmmode] */
WIFIReturnCode_t WIFI_GetPMMode( WIFIPMMode_t * pxPMModeType,
void * pvOptionValue );
/* @[declare_wifi_wifi_getpmmode] */
/**
* @brief Register a Wi-Fi event Handler.
*
* @param[in] xEventType - Wi-Fi event type.
* @param[in] xHandler - Wi-Fi event handler.
*
* @return eWiFiSuccess if registration is successful, failure code otherwise.
*/
/* @[declare_wifi_registerevent] */
WIFIReturnCode_t WIFI_RegisterEvent( WIFIEventType_t xEventType,
WIFIEventHandler_t xHandler );
/* @[declare_wifi_registerevent] */
/**
*
* @brief Check if the Wi-Fi is connected and the AP configuration matches the query.
*
* param[in] pxNetworkParams - Network parameters to query, if NULL then just check the
* Wi-Fi link status.
*/
/* @[declare_wifi_wifi_isconnected] */
BaseType_t WIFI_IsConnected( const WIFINetworkParams_t * pxNetworkParams );
/* @[declare_wifi_wifi_isconnected] */
/**
* @brief Start a Wi-Fi scan.
*
* This is an asynchronous call, the result will be notified by an event.
* @see WiFiEventInfoScanDone_t.
*
* @param[in] pxScanConfig - Parameters for scan, NULL if default scan
* (i.e. broadcast scan on all channels).
*
* @return eWiFiSuccess if scan was started successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_StartScan( WIFIScanConfig_t * pxScanConfig );
/**
* @brief Get Wi-Fi scan results. It should be called only after scan is completed. Scan results are sorted in decreasing rssi order.
*
* @param[out] pxBuffer - Handle to the READ ONLY scan results buffer.
* @param[out] ucNumNetworks - Actual number of networks in the scan results.
*
* @return eWiFiSuccess if the scan results were got successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetScanResults( const WIFIScanResult_t ** pxBuffer,
uint16_t * ucNumNetworks );
/**
* @brief Connect to the Wi-Fi Access Point (AP) specified in the input.
*
* This is an asynchronous call, the result will be notified by an event.
* @see WiFiEventInfoConnected_t.
*
* The Wi-Fi should stay connected when the specified AP is the same as the
* currently connected AP. Otherwise, the Wi-Fi should disconnect and connect
* to the specified AP. If the specified AP has invalid parameters, the Wi-Fi
* should be disconnected.
*
* @param[in] pxNetworkParams - Configuration of the targeted AP.
*
* @return eWiFiSuccess if connection was started successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_StartConnectAP( const WIFINetworkParams_t * pxNetworkParams );
/**
* @brief Wi-Fi station disconnects from AP.
*
* This is an asynchronous call. The result will be notified by an event.
* @see WiFiEventInfoDisconnected_t.
*
* @return eWiFiSuccess if disconnection was started successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_StartDisconnect( void );
/**
* @brief Get Wi-Fi info of the connected AP.
*
* This is a synchronous call.
*
* @param[out] pxConnectionInfo - Wi-Fi info of the connected AP.
*
* @return eWiFiSuccess if connection info was got successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetConnectionInfo( WIFIConnectionInfo_t * pxConnectionInfo );
/**
* @brief Get IP configuration (IP address, NetworkMask, Gateway and
* DNS server addresses).
*
* This is a synchronous call.
*
* @param[out] pxIPInfo - Current IP configuration.
*
* @return eWiFiSuccess if connection info was got successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetIPInfo( WIFIIPConfiguration_t * pxIPInfo );
/**
* @brief Get the RSSI of the connected AP.
*
* This only works when the station is connected.
*
* @param[out] pcRSSI - RSSI of the connected AP.
*
* @return eWiFiSuccess if RSSI was got successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetRSSI( int8_t * pcRSSI );
/**
* @brief SoftAP mode get connected station list.
*
* @param[out] pxStationList - Buffer for station list, supplied by the caller.
* @param[in, out] pcStationListSize - Input size of the list, output number of connected stations.
*
* @return eWiFiSuccess if stations were got successfully (manybe none),
* failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetStationList( WIFIStationInfo_t * pxStationList,
uint8_t * pcStationListSize );
/**
* @brief AP mode disconnecting a station.
*
* This is an asynchronous call, the result will be notified by an event.
* @see WiFiEventInfoAPStationDisconnected_t.
*
* @param[in] pucMac - MAC Address of the station to be disconnected.
*
* @return eWiFiSuccess if disconnection was started successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_StartDisconnectStation( uint8_t * pucMac );
/**
* @brief Set Wi-Fi MAC addresses.
*
* The given MAC address will become the station MAC address. The AP MAC address
* (i.e. BSSID) will be the same MAC address but with the local bit set.
*
* @param[in] pucMac - Station MAC address.
*
* @return eWiFiSuccess if MAC address was set successfully, failure code otherwise.
*
* @note On some platforms the change of MAC address can only take effect after reboot.
*/
WIFIReturnCode_t WIFI_SetMAC( uint8_t * pucMac );
/**
* @brief Set country based configuration (including channel list, power table)
*
* @param[in] pcCountryCode - Country code (null-terminated string, e.g. "US", "CN". See ISO-3166).
*
* @return eWiFiSuccess if Country Code is set successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_SetCountryCode( const char * pcCountryCode );
/**
* @brief Get the currently configured country code.
*
* @param[out] pcCountryCode - Null-terminated string to hold the country code (see ISO-3166).
* Must be at least 4 bytes.
*
* @return eWiFiSuccess if Country Code is retrieved successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetCountryCode( char * pcCountryCode );
/**
* @brief Get the Wi-Fi statistics.
*
* @param[out] pxStats - Structure to hold the WiFi statistics.
*
* @return eWiFiSuccess if statistics are retrieved successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetStatistic( WIFIStatisticInfo_t * pxStats );
/**
* @brief Get the Wi-Fi capability.
*
* @param[out] pxCaps - Structure to hold the Wi-Fi capabilities.
*
* @return eWiFiSuccess if capabilities are retrieved successfully, failure code otherwise.
*/
WIFIReturnCode_t WIFI_GetCapability( WIFICapabilityInfo_t * pxCaps );
#endif /* _AWS_WIFI_H_ */