/** * * \file * * \brief WINC WLAN Application Interface. * * Copyright (c) 2016-2021 Microchip Technology Inc. and its subsidiaries. * * \asf_license_start * * \page License * * Subject to your compliance with these terms, you may use Microchip * software and any derivatives exclusively with Microchip products. * It is your responsibility to comply with third party license terms applicable * to your use of third party software (including open source software) that * may accompany Microchip software. * * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. * * \asf_license_stop * */ /**@defgroup m2m_wifi WLAN @{ @defgroup WLANCallbacks Callbacks @brief Provides detail on the available callbacks for the Wlan APIs. @defgroup WlanDefines Defines @brief Specifies the macros and defines used by the Wlan APIs. @defgroup WlanEnums Enumerations and Typedefs @brief Specifies the enums and Data Structures used by the Wlan APIs. @defgroup WLANAPI Functions @brief Here are listed all the functions that implement the Wlan APIs. @{ @defgroup WLANINIT Initialization @brief Here are listed all the functions that implement the Wlan Initialization APIs. @defgroup WLANEVTS Wlan Events @brief Here are listed all the functions that implement the Wlan Events APIs. @defgroup WLANCONNECT Connection @brief Here are listed all the functions that implement the Wifi Connection APIs. @defgroup WLANSCAN Scanning @brief Here are listed all the functions that implement the Wifi Scanning APIs. @defgroup WLANAP Hot-Spot (Access-Point) @brief Here are listed all the functions that implement the Wifi Hot-Spot (Access-Point) APIs. @defgroup WLANAP Hot-Spot (Access-Point) @brief Here are listed all the functions that implement the Wifi Hot-Spot (Access-Point) APIs. @defgroup WLANETH Bypass Mode @brief Here are listed all the functions that implement the Bypass Mode APIs. @defgroup WLANROAMING Roaming @brief Here are listed all the functions that implement the Wifi Roaming APIs. @defgroup WLANPS Power Save @brief Here are listed all the functions that implement the Power-Save APIs. @defgroup WLANCONF Configuration @brief Here are listed all the functions that implement the Wlan Configuration APIs. @defgroup WLANTIME System Time @brief Here are listed all the functions that implement the System Time APIs. @defgroup WLANPROVISION Provisioning @brief Here are listed all the functions that implement the Wifi Provisioning APIs. @defgroup WLANCRYPTO Crypto @brief Here are listed all the functions that implement the Wifi Crypto APIs. @cond P2P_DOC @defgroup WLANP2P P2P @brief Here are listed all the functions that implement the Wifi P2P APIs. @endcond @cond MON_DOC @defgroup WLANMON Monitoring Mode @brief Here are listed all the functions that implement the Wifi Monitoring Mode APIs. @endcond @} @} */ #ifndef __M2M_WIFI_H__ #define __M2M_WIFI_H__ /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* INCLUDES *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ #include #include "common/include/nm_common.h" #include "driver/include/m2m_types.h" #include "driver/source/nmdrv.h" /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* MACROS *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ /**@addtogroup WLANCallbacks * @{ */ /*! @typedef void (*tpfAppWifiCb)(uint8 u8MsgType, void* pvMsg); @brief Wi-Fi's main callback function handler, for handling the M2M_WIFI events received on the Wi-Fi interface. Such notifications are received in response to Wi-Fi operations such as @ref m2m_wifi_request_scan, @ref m2m_wifi_connect_open, @ref m2m_wifi_connect_wep, @ref m2m_wifi_connect_psk, @ref m2m_wifi_connect_1x_mschap2, @ref m2m_wifi_connect_1x_tls. Wi-Fi operations are implemented in an asynchronous mode, and all incoming information/status are to be handled through this callback function when the corresponding notification is received. Applications are expected to assign this wi-fi callback function by calling @ref m2m_wifi_init. @param [in] u8MsgType Type of notification. Possible types are: - @ref M2M_WIFI_RESP_CON_STATE_CHANGED - @ref M2M_WIFI_RESP_CONN_INFO - @ref M2M_WIFI_REQ_DHCP_CONF - @ref M2M_WIFI_REQ_WPS - @ref M2M_WIFI_RESP_IP_CONFLICT - @ref M2M_WIFI_RESP_SCAN_DONE - @ref M2M_WIFI_RESP_SCAN_RESULT - @ref M2M_WIFI_RESP_CURRENT_RSSI - @ref M2M_WIFI_RESP_CLIENT_INFO - @ref M2M_WIFI_RESP_PROVISION_INFO - @ref M2M_WIFI_RESP_DEFAULT_CONNECT - @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET (In case Ethernet/Bypass mode is defined) - @ref M2M_WIFI_RESP_WIFI_RX_PACKET (In case monitoring mode is used) @param [in] pvMsg A pointer to a buffer containing the notification parameters (if any). It should be cast to the correct data type corresponding to the notification type. @see tstrM2mWifiStateChanged tstrM2MWPSInfo tstrM2mScanDone tstrM2mWifiscanResult m2m_wifi_init */ typedef void (*tpfAppWifiCb) (uint8 u8MsgType, void * pvMsg); /*! @typedef void (*tpfAppEthCb)(uint8 u8MsgType, void* pvMsg, void* pvCtrlBuf); @brief Ethernet (Bypass mode) notification callback function receiving Bypass mode events as defined in the Wi-Fi responses enumeration @ref tenuM2mStaCmd. If bypass mode is enabled, applications must ensure this callback function is registered with the Wi-Fi driver by calling @ref m2m_wifi_init. @param [in] u8MsgType Type of notification. Possible types are: - @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET @param [in] pvMsg A pointer to a buffer containing the notification parameters (if any). It should be cast to the correct data type corresponding to the notification type. For example, it could be a pointer to the buffer holding the received frame in case of @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET event. @param [in] pvControlBuf A pointer to control buffer describing the accompanied message. To be cast to @ref tstrM2mIpCtrlBuf in case of @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET event. @warning Make sure that the application defines ETH_MODE. @see m2m_wifi_init */ typedef void (*tpfAppEthCb) (uint8 u8MsgType, void * pvMsg,void * pvCtrlBuf); /**@cond MON_DOC */ /*! @typedef void (*tpfAppMonCb)(tstrM2MWifiRxPacketInfo* pstrWifiRxPacket, uint8* pu8Payload, uint16 u16PayloadSize); @brief Wi-Fi monitoring mode callback function. This function delivers all received wi-Fi packets through the Wi-Fi interface. Applications requiring to operate in the monitoring should call the asynchronous function m2m_wifi_enable_monitoring_mode and expect to receive the Wi-Fi packets through this callback function, when the event is received. To disable the monitoring mode a call to @ref m2m_wifi_disable_monitoring_mode should be made. @param [in] pstrWifiRxPacket Pointer to a structure holding the Wi-Fi packet header parameters. @param [in] pu8Payload Pointer to the buffer holding the Wi-Fi packet payload information required by the application starting from the defined OFFSET by the application (when calling m2m_wifi_enable_monitoring_mode). Could hold a value of NULL, if the application does not need any data from the payload. @param [in] u16PayloadSize The size of the payload in bytes. @see m2m_wifi_enable_monitoring_mode, m2m_wifi_init @warning u16PayloadSize should not exceed the buffer size given through m2m_wifi_enable_monitoring_mode. */ typedef void (*tpfAppMonCb)(tstrM2MWifiRxPacketInfo *pstrWifiRxPacket, uint8 *pu8Payload, uint16 u16PayloadSize); /**@endcond*/ //MON_DOC /**@}*/ //WLANCallbacks /**@addtogroup WlanEnums * @{ */ /*! @enum \ tenuWifiState @brief Enumeration for Wi-Fi state The following is used to track the state of the wifi (not initialized, initialized or started) @remarks This is useful when putting the WINC in "download mode" to access the flash via SPI. By using @ref m2m_wifi_get_state and checking against the desired state, it is possible to validate if the Application should proceed with the SPI Flash access or not. */ typedef enum { WIFI_STATE_DEINIT, /*!< Wifi is not initialized */ WIFI_STATE_INIT, /*!< Wifi has been initialized */ WIFI_STATE_START, /*!< Wifi has started */ } tenuWifiState; typedef enum { WIFI_CRED_DONTSAVE, /*!< Credentials will not be stored in WINC flash. */ WIFI_CRED_SAVE_UNENCRYPTED, /*!< Credentials will be stored unencrypted in WINC flash. */ WIFI_CRED_SAVE_ENCRYPTED /*!< Credentials will be stored encrypted in WINC flash. The encryption is not secure; it is merely intended to prevent sensitive information being leaked by an opportunistic read of WINC flash contents. The encryption keys involve WINC efuse contents, so WINC efuses should not be written while this option is in use. */ } tenuCredStoreOption; /*! @enum \ tenu1xOption @brief @remarks */ typedef enum { WIFI_1X_BYPASS_SERVER_AUTH, /*!< Server authentication for 802.1x connections. Values are of type @ref int.\n 0: Authenticate server; Default, Recommended.\n 1: Bypass server authentication.\n */ WIFI_1X_SESSION_CACHING, /*!< TLS session caching on/off for 802.1x connections. Values are of type @ref int.\n 0: Session caching off.\n 1: Session caching on; Default.\n Note that the WINC implementation of PEAPv0 does not support session caching; this setting is ignored for PEAPv0 methods. */ WIFI_1X_SPECIFIC_ROOTCERT, /*!< SHA1 digest of subject name of the root certificate to be used during server authentication. Values are:\n 20-byte arrays: authentication is limited to this particular root certificate; Recommended\n 0-byte array: authentication can succeed with any certificate in the WINC root certificate store; Default.\n */ WIFI_1X_TIME_VERIF_MODE, /*!< Mode for checking expiry of server certificate chain. Values are of type @ref tenuSslCertExpSettings. Default is @ref SSL_CERT_EXP_CHECK_EN_IF_SYS_TIME. */ } tenu1xOption; /*! @struct \ tstrEthInitParam @brief Structure to hold Ethernet interface parameters. Structure is to be defined and have its attributes set, based on the application's functionality before a call is made to initialize the wi-fi operations by calling the @ref m2m_wifi_init function. Part of the wi-fi configuration structure @ref tstrWifiInitParam. Applications shouldn't need to define this structure, if the bypass mode is not defined. @see tpfAppEthCb tpfAppWifiCb m2m_wifi_init @warning Make sure that application defines ETH_MODE before using @ref tstrEthInitParam. */ typedef struct { tpfAppWifiCb pfAppWifiCb; /*!< Callback for wifi notifications. */ tpfAppEthCb pfAppEthCb; /*!< Callback for Ethernet interface. */ uint8 * au8ethRcvBuf; /*!< Pointer to Receive Buffer of Ethernet Packet */ uint16 u16ethRcvBufSize; /*!< Size of Receive Buffer for Ethernet Packet */ uint8 u8EthernetEnable; /*!< Enable Ethernet mode flag */ uint8 __PAD8__; /*!< Padding */ } tstrEthInitParam; /*! @struct \ tstrM2mIpCtrlBuf @brief Structure holding the incoming buffer's data size information, indicating the data size of the buffer and the remaining buffer's data size. The data of the buffer which holds the packet sent to the host when in the bypass mode, is placed in the @ref tstrEthInitParam::au8ethRcvBuf attribute. This following information is retrieved in the host when an event @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET is received in the Wi-Fi callback function @ref tpfAppWifiCb. The application is expected to use this structure's information to determine if there is still incoming data to be received from the firmware. @see tpfAppWifiCb tpfAppEthCb tstrEthInitParam @warning Make sure that ETHERNET/bypass mode is defined before using @ref tstrM2mIpCtrlBuf */ typedef struct{ uint16 u16DataSize; /*!< Size of the received data in bytes. */ uint16 u16RemainingDataSize; /*!< Size of the remaining data bytes to be delivered to host. */ } tstrM2mIpCtrlBuf; /** @struct \ tstrWifiInitParam @brief Structure, holding the Wi-fi configuration attributes such as the wi-fi callback , monitoring mode callback and Ethernet parameter initialization structure. Such configuration parameters are required to be set before calling the wi-fi initialization function @ref m2m_wifi_init. @ref pfAppWifiCb attribute must be set to handle the wi-fi callback operations. @ref pfAppMonCb attribute, is optional based on whether the application requires the monitoring mode configuration, and can there not be set before the initialization. @ref strEthInitParam structure, is another optional configuration based on whether the bypass mode is set. @see tpfAppEthCb tpfAppMonCb tstrEthInitParam */ typedef struct { tpfAppWifiCb pfAppWifiCb; /*!< Callback for Wi-Fi notifications. */ tpfAppMonCb pfAppMonCb; /*!< Callback for monitoring interface. */ tstrEthInitParam strEthInitParam ; /*!< Structure to hold Ethernet interface parameters. */ } tstrWifiInitParam; typedef struct { uint8 *pu8Bssid; /*!< Pointer to BSSID (6 bytes). Optional (may be NULL). If present, this restricts the connection attempt to APs that have a matching BSSID. */ uint8 *pu8Ssid; /*!< Pointer to SSID. Required. */ uint8 u8SsidLen; /*!< Length of SSID in bytes. Permitted values are between 0 and 32. */ tenuM2mScanCh enuChannel; /*!< Wi-Fi channel to connect on. If an appropriate AP cannot be found on this channel then connection fails. @ref M2M_WIFI_CH_ALL may be used to allow scanning of all channels. */ }tstrNetworkId; /* Legacy Wep param structure. */ typedef struct { uint8 u8KeyIndx; uint8 u8KeySz; uint8 au8WepKey[WEP_104_KEY_STRING_SIZE + 1]; // NULL terminated uint8 __PAD24__[3]; }tstrM2mWifiWepParams; /* Legacy 802.1x MsChapv2 param structure. */ typedef struct{ uint8 au8UserName[21]; // NULL terminated uint8 au8Passwd[41]; // NULL terminated }tstr1xAuthCredentials; typedef struct { uint8 *pu8Psk; /*!< Pointer to PSK, represented as an ASCII string (64 characters, representing 32 bytes). Must be NULL if Passphrase is provided instead. */ uint8 *pu8Passphrase; /*!< Pointer to Passphrase (Printable ASCII). Must be NULL if PSK is provided instead. */ uint8 u8PassphraseLen; /*!< Length of Passphrase. Permitted values are between 8 and 63. This field is ignored if pu8Passphrase == NULL. */ }tstrAuthPsk; typedef struct { uint8 *pu8WepKey; /*!< Pointer to WEP Key, represented as an ASCII string. (10 or 26 characters, representing 5 or 13 bytes.) */ uint8 u8KeySz; /*!< Size of WEP Key string. Permitted values are @ref WEP_40_KEY_STRING_SIZE or @ref WEP_104_KEY_STRING_SIZE. */ uint8 u8KeyIndx; /*!< WEP Key Index in the range 1 to 4. */ }tstrAuthWep; typedef struct { uint8 *pu8Domain; /*!< Pointer to Domain of authentication server (printable ASCII), including '@' or '\' separator character as appropriate. Use NULL if there is no domain information. The Domain will be either prepended or appended to the UserName, depending on the setting of field bPrependDomain. \n Example 1: if [Domain]is "@my_domain" and bPrependDomain is false, then the EAP identity response is "[UserName]@my_domain". \n Example 2: if [Domain]is "my_domain\" and bPrependDomain is true, then the EAP identity response is "my_domain\[UserName]". */ uint8 *pu8UserName; /*!< Pointer to UserName (ASCII). This will be sent (encrypted) in the tunneled EAP identity response (if applicable) and used during MSCHAPv2 authentication. If bUnencryptedUserName is true then it will also be sent (unencrypted) in the initial EAP identity response. */ uint8 *pu8Password; /*!< Pointer to MSCHAPv2 Password (ASCII). This will be used during MSCHAPv2 authentication. */ uint16 u16DomainLen; /*!< Length of Domain (in ASCII characters), including '@' or '\' separator character as appropriate. Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and @ref M2M_AUTH_1X_USER_LEN_MAX. */ uint16 u16UserNameLen; /*!< Length of UserName (in ASCII characters). Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and @ref M2M_AUTH_1X_USER_LEN_MAX. */ uint16 u16PasswordLen; /*!< Length of Password (in ASCII characters). Permitted values are between 0 and @ref M2M_AUTH_1X_PASSWORD_LEN_MAX. */ bool bUnencryptedUserName; /*!< Determines whether UserName or "anonymous" is sent (unencrypted) in the initial EAP identity response. Domain is sent in both cases. \n true: UserName is sent in the initial EAP identity response (not recommended). false: "anonymous" is sent in the initial EAP identity response. This setting is recommended for tunneled methods. MSCHAPv2 is always a tunneled method. */ bool bPrependDomain; /*!< Determines whether Domain is prepended or appended to UserName in EAP identity responses. true: Domain is prepended to UserName - [Domain][UserName]. false: Domain is appended to UserName - [UserName][Domain]. */ }tstrAuth1xMschap2; typedef struct { uint8 *pu8Domain; /*!< Pointer to Domain of authentication server (printable ASCII), including '@' or '\' separator character as appropriate. Use NULL if there is no domain information. The Domain will be either prepended or appended to the UserName, depending on the setting of field bPrependDomain. \n Example 1: if [Domain]is "@my_domain" and bPrependDomain is false, then the EAP identity response is "[UserName]@my_domain". \n Example 2: if [Domain]is "my_domain\" and bPrependDomain is true, then the EAP identity response is "my_domain\[UserName]". */ uint8 *pu8UserName; /*!< Pointer to UserName (ASCII). This will be sent (encrypted) in the tunneled EAP identity response. If bUnencryptedUserName is true then it will also be sent (unencrypted) in the initial EAP identity response. */ uint8 *pu8PrivateKey_Mod; /*!< Pointer to PrivateKey modulus (raw data). This will be used during TLS client authentication. */ uint8 *pu8PrivateKey_Exp; /*!< Pointer to PrivateKey exponent (raw data). This will be used during TLS client authentication. */ uint8 *pu8Certificate; /*!< Pointer to TLS client certificate corresponding to PrivateKey. This will be used during TLS client authentication. */ uint16 u16DomainLen; /*!< Length of Domain (in ASCII characters), including '@' or '\' separator character as appropriate. Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and @ref M2M_AUTH_1X_USER_LEN_MAX. */ uint16 u16UserNameLen; /*!< Length of UserName (in ASCII characters). Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and @ref M2M_AUTH_1X_USER_LEN_MAX. */ uint16 u16PrivateKeyLen; /*!< Length of PrivateKey_Mod (in bytes). Permitted values are between 0 and @ref M2M_AUTH_1X_PRIVATEKEY_LEN_MAX, typically 128 or 256. PrivateKey_Exp must be the same length as modulus, pre-padded with 0s if necessary. */ uint16 u16CertificateLen; /*!< Length of Certificate (in bytes). Permitted values are between 0 and @ref M2M_AUTH_1X_CERT_LEN_MAX. */ bool bUnencryptedUserName; /*!< Determines whether UserName or "anonymous" is sent (unencrypted) in the initial EAP identity response. Domain is sent in both cases. \n true: UserName is sent in the initial EAP identity response (required for EAP-TLS). false: "anonymous" is sent in the initial EAP identity response. This setting is recommended for tunneled methods such as EAP-PEAP/TLS. */ bool bPrependDomain; /*!< Determines whether Domain is prepended or appended to UserName in EAP identity responses. true: Domain is prepended to UserName - [Domain][UserName]. false: Domain is appended to UserName - [UserName][Domain]. */ }tstrAuth1xTls; /**@}*/ //WlanEnums /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* FUNCTION PROTOTYPES *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ #ifdef __cplusplus extern "C" { #endif /*! @ingroup WLANINIT @fn \ NMI_API void m2m_wifi_download_mode(void); @brief Prepares the WINC board before downloading any data (Firmware, Certificates, etc). @details This function should be called before attempting to download any data to the WINC board. Performs the appropriate WINC driver initialization, this includes bus initialization, interrupt enabling and it halts the chip to allow for the firmware downloads. Firmware can be downloaded through a number of interfaces, UART, I2C and SPI. @pre Prior to call m2m_wifi_download_mode, the Application should ensure that the wifi is not initialized. This can be done by calling @ref m2m_wifi_get_state and in case the wifi state differs from @ref WIFI_STATE_DEINIT, a @ref m2m_wifi_deinit needs to be issued. @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. */ NMI_API sint8 m2m_wifi_download_mode(void); /*! @ingroup WLANINIT @fn \ NMI_API sint8 m2m_wifi_init(tstrWifiInitParam * pWifiInitParam); @brief Synchronous API to initialize the WINC driver. @details This function initializes the WINC driver by registering the callback function for the M2M_WIFI layer (also the callback function for bypass mode/monitoring mode if defined), initializing the host interface layer and the bus interfaces. Wi-Fi callback registering is essential to allow the handling of the events received, in response to the asynchronous Wi-Fi operations. The possible Wi-Fi events that are expected to be received through the callback function (provided by the application) to the M2M_WIFI layer are listed below: - @ref M2M_WIFI_RESP_CON_STATE_CHANGED - @ref M2M_WIFI_RESP_CONN_INFO - @ref M2M_WIFI_REQ_DHCP_CONF - @ref M2M_WIFI_REQ_WPS - @ref M2M_WIFI_RESP_IP_CONFLICT - @ref M2M_WIFI_RESP_SCAN_DONE - @ref M2M_WIFI_RESP_SCAN_RESULT - @ref M2M_WIFI_RESP_CURRENT_RSSI - @ref M2M_WIFI_RESP_CLIENT_INFO - @ref M2M_WIFI_RESP_PROVISION_INFO - @ref M2M_WIFI_RESP_DEFAULT_CONNECT - @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET (if bypass mode is enabled) - @ref M2M_WIFI_RESP_WIFI_RX_PACKET (if monitoring mode is enabled) Any application using the WINC driver must call this function at the start of its main function. @param [in] pWifiInitParam This is a pointer to a structure of type @ref tstrWifiInitParam which contains pointers to the application WIFI layer callback function, monitoring mode callback and @ref tstrEthInitParam structure (which contains initialization settings for bypass mode). @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. @pre Prior to this function call, The application should initialize the BSP using @ref nm_bsp_init. Also, application users must provide a call back function responsible for receiving all the wi-fi events that are received on the M2M_WIFI layer. @warning Failure to successfully complete indicates that the driver could not be initialized and a fatal error will prevent the application from proceeding, proper error handling should be implemented by the application. @see m2m_wifi_deinit m2m_wifi_init_hold m2m_wifi_init_start tstrWifiInitParam tenuM2mStaCmd tenuM2mStaCmd */ NMI_API sint8 m2m_wifi_init(tstrWifiInitParam * pWifiInitParam); /*! @ingroup WLANINIT @fn \ NMI_API sint8 m2m_wifi_deinit(void * arg); @brief De-initialize the WINC driver and host interface. @details Synchronous de-initialization function for the WINC driver. De-initializes the host interface and frees any resources used by the M2M_WIFI layer. This function must be called in the application closing phase to ensure that all resources have been correctly released. No arguments are expected to be passed in. @param [in] arg Opaque argument, not used in current implementation. Application should use null. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC, and a negative value otherwise. @note This function must be called at the de-initialization stage of the application. Generally this function should be the last function before switching off the chip and it should be followed only by @ref nm_bsp_deinit function call. Every function call of @ref m2m_wifi_init should be matched with a call to m2m_wifi_deinit. @see nm_bsp_deinit m2m_wifi_init m2m_wifi_init_hold m2m_wifi_download_mode */ NMI_API sint8 m2m_wifi_deinit(void * arg); /*! @ingroup WLANINIT @fn \ NMI_API sint8 m2m_wifi_init_hold(void); @brief First part of @ref m2m_wifi_init, up to the point of initializing SPI for flash access. @see m2m_wifi_init m2m_wifi_init_start */ NMI_API sint8 m2m_wifi_init_hold(void); /*! @ingroup WLANINIT @fn \ NMI_API sint8 m2m_wifi_init_start(tstrWifiInitParam * pWifiInitParam); @brief Second part of @ref m2m_wifi_init, continuing from where @ref m2m_wifi_init_hold left off. @param [in] pWifiInitParam This is a pointer to a variable of type @ref tstrWifiInitParam which contains pointers to the application WIFI layer callback function (see @ref tpfAppWifiCb), monitoring mode callback (see @ref tpfAppEthCb) and @ref tstrEthInitParam structure (which contains initialization settings for bypass mode). @see m2m_wifi_init tstrWifiInitParam */ NMI_API sint8 m2m_wifi_init_start(tstrWifiInitParam * pWifiInitParam); /*! @ingroup WLANINIT @fn \ NMI_API sint8 m2m_wifi_reinit(tstrWifiInitParam * pWifiInitParam); @brief De-initialize and then initialize wifi. Resets the WINC. @param [in] pWifiInitParam This is a pointer to a variable of type @ref tstrWifiInitParam which contains pointers to the application WIFI layer callback function (see @ref tpfAppWifiCb), monitoring mode callback (see @ref tpfAppEthCb) and @ref tstrEthInitParam structure (which contains initialization settings for bypass mode). @note m2m_wifi_reinit wraps a call to @ref m2m_wifi_deinit and to @ref m2m_wifi_init. @see m2m_wifi_deinit m2m_wifi_init tstrWifiInitParam */ NMI_API sint8 m2m_wifi_reinit(tstrWifiInitParam * pWifiInitParam); /*! @ingroup WLANINIT @fn \ NMI_API sint8 m2m_wifi_reinit_hold(void); @brief First part of @ref m2m_wifi_reinit, up to the point of initializing SPI for flash access. @note m2m_wifi_reinit_hold wraps a call to @ref m2m_wifi_deinit and to @ref m2m_wifi_init_hold. @see m2m_wifi_deinit m2m_wifi_reinit m2m_wifi_init_hold */ NMI_API sint8 m2m_wifi_reinit_hold(void); /*! @ingroup WLANINIT @fn \ NMI_API sint8 m2m_wifi_reinit_start(tstrWifiInitParam * pWifiInitParam); @brief Second part of @ref m2m_wifi_reinit, continuing from where m2m_wifi_reinit_hold left off. @param [in] pWifiInitParam This is a pointer to the @ref tstrWifiInitParam structure which contains pointers to the application WIFI layer callback function (see @ref tpfAppWifiCb), monitoring mode callback (see @ref tpfAppEthCb) and @ref tstrEthInitParam structure (which contains initialization settings for bypass mode). @see m2m_wifi_reinit m2m_wifi_init_start tstrWifiInitParam */ NMI_API sint8 m2m_wifi_reinit_start(tstrWifiInitParam * pWifiInitParam); /*! @ingroup WLANEVTS @fn \ NMI_API void m2m_wifi_yield(void); @brief Yield from processing more synchronous M2M events. @details This function causes the synchronous M2M event handler function to yield from processing further events and return control to the caller. @pre Prior to receiving Wi-Fi interrupts, the WINC driver should have been successfully initialized by calling the @ref m2m_wifi_init function. @warning Failure to successfully complete this function indicates bus errors and hence a fatal error that will prevent the application from proceeding. */ NMI_API void m2m_wifi_yield(void); /*! @ingroup WLANEVTS @fn \ NMI_API sint8 m2m_wifi_handle_events(void * arg); @brief Synchronous M2M event handler function. @details This function is responsible for handling interrupts received from the WINC firmware. Applications should call this function periodically in-order to receive the events that are to be handled by the callback functions implemented by the application. Handle the various events received from the WINC board. Whenever an event happens in the WINC board (e.g. Connection, Disconnection, DHCP, etc), the WINC will interrupt the host to let it know that a new event has occurred. The host driver will attempt to handle these events whenever the application decides to do so by calling the m2m_wifi_handle_events function. It is mandatory to call this function periodically and independently of any other condition. It is ideal to include this function in the main and the most frequent loop of the host application. @pre Prior to receiving events, the WINC driver should have been successfully initialized by calling the @ref m2m_wifi_init function. @warning Failure to successfully complete this function indicates bus errors and hence a fatal error that will prevent the application from proceeding. @return The function returns @ref M2M_SUCCESS for successful interrupt handling and a negative value otherwise. */ NMI_API sint8 m2m_wifi_handle_events(void * arg); /*! @fn \ sint8 m2m_wifi_send_crl(tstrTlsCrlInfo* pCRL); @brief Asynchronous API that notifies the WINC with the Certificate Revocation List. @param [in] pCRL Pointer to the structure containing certificate revocation list details. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. */ sint8 m2m_wifi_send_crl(tstrTlsCrlInfo* pCRL); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_delete_sc(char *pcSsid, uint8 u8SsidLen); @brief Asynchronous API that deletes connection credentials (PSK, WEP key, 802.1X password) from WINC flash. Either deletes all credentials, or for a specific SSID. @details Causes WINC to delete connection credentials. If the parameter is NULL, then WINC will delete all credentials from flash. Otherwise WINC will only delete credentials for matching SSID. Callback will report the status of the operation (success or not). @param [in] pcSsid SSID to match on when deleting credentials. SSID must not contain '\0'. NULL is a valid argument here, in which case all credentials are deleted. @param [in] u8SsidLen Length of SSID provided in pcSsid. Must be less than @ref M2M_MAX_SSID_LEN. This parameter is ignored if pcSsid is NULL. @pre Prior to deleting credentials, the WINC driver should have been successfully initialized by calling the @ref m2m_wifi_init function. @warning The option to delete for a specific SSID is currently not supported; all credentials are deleted regardless of the input parameters. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. */ sint8 m2m_wifi_delete_sc(char *pcSsid, uint8 u8SsidLen); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_default_connect(void); @brief Asynchronous API that attempts to reconnect to the last-associated access point. @details Asynchronous Wi-Fi connection function. An application calling this function will cause the firmware to correspondingly connect to the last successfully connected AP from the cached connections.\n A failure to connect will result in a response of @ref M2M_WIFI_RESP_DEFAULT_CONNECT indicating the connection error as defined in the structure @ref tstrM2MDefaultConnResp. Possible errors are: The connection list is empty @ref M2M_DEFAULT_CONN_EMPTY_LIST or a mismatch for the saved AP name @ref M2M_DEFAULT_CONN_SCAN_MISMATCH. @pre Prior to connecting, the WINC driver should have been successfully initialized by calling the @ref m2m_wifi_init function. @warning This function must be called in station mode only. It is important to note that successful completion of a call to m2m_wifi_default_connect() does not guarantee success of the WIFI connection; a negative return value indicates only locally-detected errors. @see m2m_wifi_connect @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. */ NMI_API sint8 m2m_wifi_default_connect(void); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_connect_open(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId); @brief Asynchronous API to connect to an access point using open authentication. @details Asynchronous Wi-Fi connection function. An application calling this function will cause the firmware to attempt to connect to an access point matching the details in pstrNetworkId, with open authentication. On successful connection, the connection details may be saved in WINC's flash, according to the option selected in enuCredStoreOption. Once connection has been attempted (whether successful or otherwise), a response event @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb provided during initialization @ref m2m_wifi_init. Possible results indicated by the response event are: - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed. - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded. @pre Prior to attempting connection, the WINC driver must have been initialized by calling the @ref m2m_wifi_init function. @warning This function is handled in station mode only. @param[in] enuCredStoreOption Option to specify whether connection details (i.e. the contents of pstrNetworkId) are stored in WINC's flash and, if so, whether they are encrypted before storing. @param[in] pstrNetworkId Structure specifying SSID/BSSID and Wi-Fi channel. @return The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise. */ sint8 m2m_wifi_connect_open(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_connect_wep(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthWep *pstrAuthWep); @brief Asynchronous API to connect to an access point using WEP authentication. @details Asynchronous Wi-Fi connection function. An application calling this function will cause the firmware to attempt to connect to an access point matching the details in pstrNetworkId, with the WEP key provided in pstrAuthWep. On successful connection, the connection details may be saved in WINC's flash, according to the option selected in enuCredStoreOption. Once connection has been attempted (whether successful or otherwise), a response event @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb provided during initialization @ref m2m_wifi_init. Possible results indicated by the response event are: - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed. - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded. @pre Prior to attempting connection, the WINC driver must have been initialized by calling the @ref m2m_wifi_init function. @warning This function is handled in station mode only. @param[in] enuCredStoreOption Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuthWep) are stored in WINC's flash and, if so, whether they are encrypted before storing. @param[in] pstrNetworkId Structure specifying SSID/BSSID and Wi-Fi channel. @param[in] pstrAuthWep Structure specifying the WEP key. @return The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise. */ sint8 m2m_wifi_connect_wep(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthWep *pstrAuthWep); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_connect_psk(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthPsk *pstrAuthPsk); @brief Asynchronous API to connect to an access point using WPA(2) PSK authentication. @details Asynchronous Wi-Fi connection function. An application calling this function will cause the firmware to attempt to connect to an access point matching the details in pstrNetworkId, with the PSK passphrase provided in pstrAuthPsk. On successful connection, the connection details may be saved in WINC's flash, according to the option selected in enuCredStoreOption. Once connection has been attempted (whether successful or otherwise), a response event @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb provided during initialization @ref m2m_wifi_init. Possible results indicated by the response event are: - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed. - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded. @pre Prior to attempting connection, the WINC driver must have been initialized by calling the @ref m2m_wifi_init function. @warning This function is handled in station mode only. @param[in] enuCredStoreOption Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuthPsk) are stored in WINC's flash and, if so, whether they are encrypted before storing. @param[in] pstrNetworkId Structure specifying SSID/BSSID and Wi-Fi channel. @param[in] pstrAuthPsk Structure specifying the Passphrase/PSK. @return The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise. */ sint8 m2m_wifi_connect_psk(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthPsk *pstrAuthPsk); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_1x_set_option(tenu1xOption enuOptionName, const void *pOptionValue, size_t OptionLen); @brief API to set (write) options relating to Wi-Fi connection using WPA(2) Enterprise authentication. @details The following options can be set:\n @ref WIFI_1X_BYPASS_SERVER_AUTH\n @ref WIFI_1X_SESSION_CACHING\n @ref WIFI_1X_SPECIFIC_ROOTCERT\n @ref WIFI_1X_TIME_VERIF_MODE\n The setting applies to all subsequent connection attempts via @ref m2m_wifi_connect_1x_mschap2 or @ref m2m_wifi_connect_1x_tls.\n Connection attempts via @ref m2m_wifi_default_connect use the settings which were in place at the time of the original connection. @param[in] enuOptionName The option to set. @param[in] pOptionValue Pointer to a buffer containing the value to set. The buffer must be at least as long as OptionLen. If OptionLen is 0, then pOptionValue may be NULL. @param[in] OptionLen The length of the option value being set. @return The function returns @ref M2M_SUCCESS if the parameters are valid and @ref M2M_ERR_INVALID_ARG otherwise. */ sint8 m2m_wifi_1x_set_option(tenu1xOption enuOptionName, const void *pOptionValue, size_t OptionLen); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_1x_get_option(tenu1xOption enuOptionName, void *pOptionValue, size_t *pOptionLen); @brief API to get (read) options relating to Wi-Fi connection using WPA(2) Enterprise authentication. @details The following options can be read:\n @ref WIFI_1X_BYPASS_SERVER_AUTH\n @ref WIFI_1X_SESSION_CACHING\n @ref WIFI_1X_SPECIFIC_ROOTCERT\n @ref WIFI_1X_TIME_VERIF_MODE\n @param[in] enuOptionName The option to get. @param[out] pOptionValue Pointer to a buffer containing the value to set. The buffer must be at least as long as OptionLen. If OptionLen is 0, then pOptionValue may be NULL. @param[inout] pOptionLen Pointer to a length. When calling the function, this length must be the length of the buffer available for reading the option value. When the function returns, this length is the length of the data that has been populated by the function. @return The function returns @ref M2M_SUCCESS if the parameters are valid and @ref M2M_ERR_INVALID_ARG otherwise. */ sint8 m2m_wifi_1x_get_option(tenu1xOption enuOptionName, void *pOptionValue, size_t *pOptionLen); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_connect_1x_mschap2(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xMschap2 *pstrAuth1xMschap2); @brief Asynchronous API to connect to an access point using WPA(2) Enterprise authentication with MS-CHAP-V2 credentials. @details Asynchronous Wi-Fi connection function. An application calling this function will cause the firmware to attempt to connect to an access point matching the details in pstrNetworkId, with the Enterprise MS-CHAP-V2 credentials provided in pstrAuth1xMschap2. On successful connection, the connection details may be saved in WINC's flash, according to the option selected in enuCredStoreOption. Once connection has been attempted (whether successful or otherwise), a response event @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function tpfAppWifiCb provided during initialization @ref m2m_wifi_init. Possible results indicated by the response event are: - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed. - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded. @pre Prior to attempting connection, the WINC driver must have been initialized by calling the @ref m2m_wifi_init function. @warning This function is handled in station mode only. @param[in] enuCredStoreOption Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuth1xMschap2) are stored in WINC's flash and, if so, whether they are encrypted before storing. @param[in] pstrNetworkId Structure specifying SSID/BSSID and Wi-Fi channel. @param[in] pstrAuth1xMschap2 Structure specifying the MS-CHAP-V2 credentials. @return The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise. */ sint8 m2m_wifi_connect_1x_mschap2(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xMschap2 *pstrAuth1xMschap2); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_connect_1x_tls(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xTls *pstrAuth1xTls); @brief Asynchronous API to connect to an access point using WPA(2) Enterprise authentication with MS-CHAP-V2 credentials. @details Asynchronous Wi-Fi connection function. An application calling this function will cause the firmware to attempt to connect to an access point matching the details in pstrNetworkId, with the Enterprise TLS credentials provided in pstrAuth1xTls. On successful connection, the connection details may be saved in WINC's flash, according to the option selected in enuCredStoreOption. Once connection has been attempted (whether successful or otherwise), a response event @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb provided during initialization @ref m2m_wifi_init. Possible results indicated by the response event are: - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed. - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded. @pre Prior to attempting connection, the WINC driver must have been initialized by calling the @ref m2m_wifi_init function. @warning This function is handled in station mode only. @param[in] enuCredStoreOption Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuth1xTls) are stored in WINC's flash and, if so, whether they are encrypted before storing. @param[in] pstrNetworkId Structure specifying SSID/BSSID and Wi-Fi channel. @param[in] pstrAuth1xTls Structure specifying the EAP-TLS credentials. @return The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise. */ sint8 m2m_wifi_connect_1x_tls(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xTls *pstrAuth1xTls); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_connect(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch); @brief DEPRECATED in v19.6.1 - Kept only for legacy purposes.\n Legacy asynchronous API to request connection to a specified access point. @details Prior to a successful connection, the application must define the SSID of the AP, the security type, the authentication information parameters and the channel number to which the connection will be established. The connection status is known when a response of @ref M2M_WIFI_RESP_CON_STATE_CHANGED is received based on the states defined in @ref tenuM2mConnState, successful connection is defined by @ref M2M_WIFI_CONNECTED The only difference between this function and @ref m2m_wifi_default_connect, is the set of connection parameters. Connection using this function is expected to be made to a specific AP and to a specified channel. @param[in] pcSsid A buffer holding the SSID corresponding to the requested AP. SSID must not contain '\0'. @param[in] u8SsidLen Length of the given SSID (not including the NULL termination). A length greater than the maximum defined SSID @ref M2M_MAX_SSID_LEN will result in a negative error @ref M2M_ERR_FAIL. @param[in] u8SecType Wi-Fi security type security for the network. It can be one of the following types: -@ref M2M_WIFI_SEC_OPEN -@ref M2M_WIFI_SEC_WEP -@ref M2M_WIFI_SEC_WPA_PSK -@ref M2M_WIFI_SEC_802_1X A value outside these possible values will result in a negative return error @ref M2M_ERR_FAIL. @param [in] pvAuthInfo Authentication parameters required for completing the connection. Its type is based on the security type. If the authentication parameters are NULL or are greater than the maximum length of the authentication parameters length as defined by @ref M2M_MAX_PSK_LEN a negative error will return @ref M2M_ERR_FAIL(-12) indicating connection failure. @param [in] u16Ch Wi-Fi channel number as defined in @ref tenuM2mScanCh enumeration. Specifying a channel number greater than @ref M2M_WIFI_CH_14 returns a negative error @ref M2M_ERR_FAIL(-12), unless the value is @ref M2M_WIFI_CH_ALL, since this indicates that the firmware should scan all channels to find the SSID specified in parameter pcSsid. Failure to find the connection match will return a negative error @ref M2M_DEFAULT_CONN_SCAN_MISMATCH. @pre Prior to a successful connection request, the wi-fi driver must have been successfully initialized through the call of the @ref m2m_wifi_init function @warning If there is a '\0' character within the first u8SsidLen characters, then this function will assume that the input u8SsidLen was incorrect, set length to strlen(pcSsid) and continue.\n This function has been deprecated since v19.6.1 and will no longer be supported afterwards. The following should be used instead: @ref m2m_wifi_connect_open @ref m2m_wifi_connect_wep @ref m2m_wifi_connect_psk @ref m2m_wifi_connect_1x_mschap2 @ref m2m_wifi_connect_1x_tls Additionally: - This function must be called in station mode only. - Successful completion of this function does not guarantee success of the WIFI connection, and a negative return value indicates only locally-detected errors. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tstr1xAuthCredentials tstrM2mWifiWepParams */ NMI_API sint8 m2m_wifi_connect(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_connect_sc(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch, uint8 u8NoSaveCred); @brief DEPRECATED in v19.6.1 - Kept only for legacy purposes.\n Legacy asynchronous API to request connection to a specific AP with the option to save credentials in Flash. @details Prior to a successful connection, the application developers must know the SSID of the AP, the security type, the authentication information parameters and the channel number to which the connection will be established. The connection status is known when a response of @ref M2M_WIFI_RESP_CON_STATE_CHANGED is received based on the states defined in @ref tenuM2mConnState, successful connection is defined by @ref M2M_WIFI_CONNECTED The only difference between this function and @ref m2m_wifi_connect, is the option to save the access point info (SSID, password...etc) or not. Connection using this function is expected to be made to a specific AP and to a specified channel. @param [in] pcSsid A buffer holding the SSID corresponding to the requested AP. SSID must not contain '\0'. @param [in] u8SsidLen Length of the given SSID (not including the NULL termination). A length greater than the maximum defined SSID @ref M2M_MAX_SSID_LEN will result in a negative error @ref M2M_ERR_FAIL. @param [in] u8SecType Wi-Fi security type security for the network see @ref tenuM2mSecType. It can be one of the following types: -@ref M2M_WIFI_SEC_OPEN -@ref M2M_WIFI_SEC_WEP -@ref M2M_WIFI_SEC_WPA_PSK -@ref M2M_WIFI_SEC_802_1X A value outside these possible values will result in a negative return error @ref M2M_ERR_FAIL. @param [in] pvAuthInfo Authentication parameters required for completing the connection. Its type is based on the security type. If the authentication parameters are NULL or are greater than the maximum length of the authentication parameters length as defined by @ref M2M_MAX_PSK_LEN a negative error will return @ref M2M_ERR_FAIL(-12) indicating connection failure. @param [in] u16Ch Wi-Fi channel number as defined in @ref tenuM2mScanCh enumeration. Specification of a channel number greater than @ref M2M_WIFI_CH_14 returns a negative error @ref M2M_ERR_FAIL(-12) unless the value is @ref M2M_WIFI_CH_ALL. A channel number of @ref M2M_WIFI_CH_ALL indicates that the firmware should scan all channels to find the SSID specified in parameter pcSsid. Failure to find the connection match will return a negative error @ref M2M_DEFAULT_CONN_SCAN_MISMATCH. @param [in] u8NoSaveCred Option to store the access point SSID and password into the WINC flash memory or not. @pre Prior to a successful connection request, the wi-fi driver must have been successfully initialized through the call of the @ref m2m_wifi_init function. @warning If there is a '\0' character within the first u8SsidLen characters, then this function will assume that the input u8SsidLen was incorrect, set length to strlen(pcSsid) and continue.\n This function has been deprecated since v19.6.1 and will no longer be supported afterwards. The following should be used instead: @ref m2m_wifi_connect_open @ref m2m_wifi_connect_wep @ref m2m_wifi_connect_psk @ref m2m_wifi_connect_1x_mschap2 @ref m2m_wifi_connect_1x_tls Additionally: - This function must be called in station mode only. - Successful completion of this function does not guarantee success of the WIFI connection, and a negative return value indicates only locally-detected errors. @see tenuM2mSecType tstr1xAuthCredentials tstrM2mWifiWepParams @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. */ NMI_API sint8 m2m_wifi_connect_sc(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch, uint8 u8NoSaveCred); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_disconnect(void); @brief Synchronous API to request disconnection from a network. @details Request a Wi-Fi disconnect from the currently connected AP. After the disconnect is complete the driver should receive a response of @ref M2M_WIFI_RESP_CON_STATE_CHANGED based on the states defined in @ref tenuM2mConnState, successful disconnection is defined by @ref M2M_WIFI_DISCONNECTED . @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @pre Disconnection request must be made to a successfully connected AP. If the WINC is not in the connected state, a call to this function will hold insignificant. @warning This function must be called in station mode only. @see m2m_wifi_connect_open m2m_wifi_connect_wep m2m_wifi_connect_psk m2m_wifi_connect_1x_mschap2 m2m_wifi_connect_1x_tls m2m_wifi_default_connect */ NMI_API sint8 m2m_wifi_disconnect(void); /*! @ingroup WLANPROVISION @fn \ NMI_API sint8 m2m_wifi_start_provision_mode(tstrM2MAPConfig *pstrAPConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect); @brief Asynchronous API for control of Wi-Fi provisioning functionality. @details Asynchronous Wi-Fi provisioning function, which starts the WINC HTTP PROVISIONING mode. The function triggers the WINC to activate the Wi-Fi AP (HOTSPOT) mode with the passed configuration parameters and then starts the HTTP Provision WEB Server. Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO. @param[in] pstrAPConfig AP configuration parameters as defined in @ref tstrM2MAPConfig configuration structure. If a NULL value is passed in, the call will result in a negative error @ref M2M_ERR_FAIL. @param[in] pcHttpServerDomainName Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page. The domain name can have one of the following 3 forms: - 1. "wincprov.com" - 2. "http://wincprov.com" - 3. "https://wincprov.com" Forms 1 and 2 are equivalent, they will both start a plain http server, while form 3 will start a secure HTTP provisioning Session (HTTP over SSL connection). @param [in] bEnableHttpRedirect A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS). Possible values are: - ZERO value, which means DO NOT use HTTP Redirect. In this case, the associated device could open the provisioning page ONLY when the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser. - Non-Zero value, means use HTTP Redirect. In this case, all http traffic (http://URL) from the associated device (Phone, PC, etc) will be redirected to the WINC HTTP Provisioning Home page. @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the initialization @ref m2m_wifi_init function. - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info. @warning DO NOT use ".local" in the pcHttpServerDomainName. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tpfAppWifiCb m2m_wifi_init M2M_WIFI_RESP_PROVISION_INFO m2m_wifi_stop_provision_mode tstrM2MAPConfig \section WIFIExample1 Example The example demonstrates a code snippet for how provisioning is triggered and the response event received accordingly. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_RESP_PROVISION_INFO: { tstrM2MProvisionInfo *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg; if(pstrProvInfo->u8Status == M2M_SUCCESS) { tstrNetworkId strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL}; tstrAuthPsk strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8)strlen((char*)(pstrProvInfo->au8Password))}; m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk); printf("PROV SSID : %s\n",pstrProvInfo->au8SSID); printf("PROV PSK : %s\n",pstrProvInfo->au8Password); } else { printf("(ERR) Provisioning Failed\n"); } } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { tstrM2MAPConfig apConfig; uint8 bEnableRedirect = 1; strcpy(apConfig.au8SSID, "WINC_SSID"); apConfig.u8ListenChannel = 1; apConfig.u8SecType = M2M_WIFI_SEC_OPEN; apConfig.u8SsidHide = 0; // IP Address apConfig.au8DHCPServerIP[0] = 192; apConfig.au8DHCPServerIP[1] = 168; apConfig.au8DHCPServerIP[2] = 1; apConfig.au8DHCPServerIP[3] = 1; m2m_wifi_start_provision_mode(&apConfig, "atmelwincconf.com", bEnableRedirect); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_start_provision_mode(tstrM2MAPConfig *pstrAPConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect); /*! @ingroup WLANPROVISION @fn \ NMI_API sint8 m2m_wifi_start_provision_mode_ext(tstrM2MAPModeConfig *pstrAPModeConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect); @brief Asynchronous API for control of Wi-Fi provisioning functionality with extended options. @details Asynchronous Wi-Fi provisioning function, which starts the WINC HTTP PROVISIONING mode. The function triggers the WINC to activate the Wi-Fi AP (HOTSPOT) mode with the passed configuration parameters and then starts the HTTP Provision WEB Server. Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO. @param[in] pstrAPModeConfig AP configuration parameters as defined in @ref tstrM2MAPModeConfig configuration structure. A NULL value passed in, will result in a negative error @ref M2M_ERR_FAIL. @param[in] pcHttpServerDomainName Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page. The domain name can have one of the following 3 forms: - 1. "wincprov.com" - 2. "http://wincprov.com" - 3. "https://wincprov.com" The forms 1 and 2 are equivalent, they both will start a plain http server, while form 3 will start a secure HTTP provisioning Session (HTTP over SSL connection). @param[in] bEnableHttpRedirect A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS). Possible values are: - ZERO value, which means DO NOT use HTTP Redirect. In this case, the associated device could open the provisioning page ONLY when the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser. - Non-Zero value, means use HTTP Redirect. In this case, all http traffic (http://URL) from the associated device (Phone, PC, etc) will be redirected to the WINC HTTP Provisioning Home page. @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the initialization @ref m2m_wifi_init function. - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info. @warning DO Not use ".local" in the pcHttpServerDomainName. @see tpfAppWifiCb m2m_wifi_init M2M_WIFI_RESP_PROVISION_INFO m2m_wifi_stop_provision_mode tstrM2MAPModeConfig @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. \section WIFIExample1b Example The example demonstrates a code snippet for how provisioning is triggered and the response event received accordingly. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_RESP_PROVISION_INFO: { tstrM2MProvisionInfo *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg; if(pstrProvInfo->u8Status == M2M_SUCCESS) { tstrNetworkId strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL}; tstrAuthPsk strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8)strlen((char*)(pstrProvInfo->au8Password))}; m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk); printf("PROV SSID : %s\n",pstrProvInfo->au8SSID); printf("PROV PSK : %s\n",pstrProvInfo->au8Password); } else { printf("(ERR) Provisioning Failed\n"); } } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { tstrM2MAPModeConfig apModeConfig; uint8 bEnableRedirect = 1; strcpy(apModeConfig.strApConfig.au8SSID, "WINC_SSID"); apModeConfig.strApConfig.u8ListenChannel = 1; apModeConfig.strApConfig.u8SecType = M2M_WIFI_SEC_OPEN; apModeConfig.strApConfig.u8SsidHide = 0; // IP Address apModeConfig.strApConfig.au8DHCPServerIP[0] = 192; apModeConfig.strApConfig.au8DHCPServerIP[1] = 168; apModeConfig.strApConfig.au8DHCPServerIP[2] = 1; apModeConfig.strApConfig.au8DHCPServerIP[3] = 1; // Default router IP m2m_memcpy(apModeConfig.strApConfigExt.au8DefRouterIP, apModeConfig.strApConfig.au8DHCPServerIP, 4); // DNS Server IP m2m_memcpy(apModeConfig.strApConfigExt.au8DNSServerIP, apModeConfig.strApConfig.au8DHCPServerIP, 4); // Subnet mask apModeConfig.strApConfigExt.au8SubnetMask[0] = 255; apModeConfig.strApConfigExt.au8SubnetMask[1] = 255; apModeConfig.strApConfigExt.au8SubnetMask[2] = 255; apModeConfig.strApConfigExt.au8SubnetMask[3] = 0; m2m_wifi_start_provision_mode_ext(&apModeConfig, "atmelwincconf.com", bEnableRedirect); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_start_provision_mode_ext(tstrM2MAPModeConfig *pstrAPModeConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect); /*! @ingroup WLANPROVISION @fn \ sint8 m2m_wifi_stop_provision_mode(void); @brief Synchronous API for terminating provisioning mode on the WINC IC. @details This function will terminate any currently active provisioning mode on the WINC IC, returning the IC to idle. @pre An active provisioning session must be active before it is terminated through this function. @return The function returns @ref M2M_SUCCESS for success and a negative value otherwise. @see m2m_wifi_start_provision_mode */ NMI_API sint8 m2m_wifi_stop_provision_mode(void); /*! @ingroup WLANCONNECT @fn \ sint8 m2m_wifi_get_connection_info(void); @brief Asynchronous API for retrieving the WINC IC's connection status. @details Asynchronous connection status retrieval function, retrieves the status information of the currently connected AP. The result is passed to the Wi-Fi notification callback through the event @ref M2M_WIFI_RESP_CONN_INFO. Connection information is retrieved from the structure @ref tstrM2MConnInfo. Connection Information retrieved: -Connection Security -Connection RSSI -Remote MAC address -Remote IP address In case the WINC is operating in station mode, the SSID of the AP is also retrieved. @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the initialization @ref m2m_wifi_init function. - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info. @warning - In case the WINC is operating in AP mode, the SSID field will be returned as a NULL string. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see M2M_WIFI_RESP_CONN_INFO, tstrM2MConnInfo \section WIFIExample2 Example The code snippet shows an example of how wi-fi connection information is retrieved . @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_RESP_CONN_INFO: { tstrM2MConnInfo *pstrConnInfo = (tstrM2MConnInfo*)pvMsg; printf("CONNECTED AP INFO\n"); printf("SSID : %s\n",pstrConnInfo->acSSID); printf("SEC TYPE : %d\n",pstrConnInfo->u8SecType); printf("Signal Strength : %d\n", pstrConnInfo->s8RSSI); printf("Local IP Address : %d.%d.%d.%d\n", pstrConnInfo->au8IPAddr[0] , pstrConnInfo->au8IPAddr[1], pstrConnInfo->au8IPAddr[2], pstrConnInfo->au8IPAddr[3]); } break; case M2M_WIFI_REQ_DHCP_CONF: { // Get the current AP information. m2m_wifi_get_connection_info(); } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // connect to the default AP m2m_wifi_default_connect(); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_get_connection_info(void); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_set_mac_address(uint8 au8MacAddress[6]); @brief Synchronous API for assigning a MAC address to the WINC IC. @details This function override the already assigned MAC address of the WINC board with a user provided one. This is for experimental use only and should never be used in the production SW. @param [in] au8MacAddress MAC Address to be provisioned to the WINC. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. */ NMI_API sint8 m2m_wifi_set_mac_address(uint8 au8MacAddress[6]); /*! @ingroup WLANWPS @fn \ NMI_API sint8 m2m_wifi_wps(uint8 u8TriggerType,const char * pcPinNumber); @brief Asynchronous API to engage the WINC IC's Wi-Fi Protected Setup (enrollee) function. @details This function is called for the WINC to enter the WPS (Wi-Fi Protected Setup) mode. The result is passed to the Wi-Fi notification callback with the event @ref M2M_WIFI_REQ_WPS. @param [in] u8TriggerType WPS Trigger method. This may be: - @ref WPS_PIN_TRIGGER Push button method - @ref WPS_PBC_TRIGGER Pin method @param[in] pcPinNumber PIN number for WPS PIN method. It is not used if the trigger type is WPS_PBC_TRIGGER. It must follow the rules stated by the WPS standard. @pre - A Wi-Fi notification callback of type (@ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to @ref m2m_wifi_init. - The event @ref M2M_WIFI_REQ_WPS must be handled in the callback to receive the WPS status. - The WINC device MUST be in IDLE or STA mode. If AP mode is active, the WPS will not be performed. - The @ref m2m_wifi_handle_events MUST be called periodically to receive the responses in the callback. @warning This function is not allowed in AP mode. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tpfAppWifiCb m2m_wifi_init M2M_WIFI_REQ_WPS tenuWPSTrigger tstrM2MWPSInfo \section WIFIExample3 Example The code snippet shows an example of how wi-fi WPS is triggered . @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_REQ_WPS: { tstrM2MWPSInfo *pstrWPS = (tstrM2MWPSInfo*)pvMsg; if(pstrWPS->u8AuthType != 0) { // establish Wi-Fi connection tstrNetworkId strNetworkId = {NULL, pstrWPS->au8SSID, (uint8)strlen((char*)(pstrWPS->au8SSID)), pstrWPS->u8Ch}; if(pstrWPS->u8AuthType == M2M_WIFI_SEC_OPEN) { m2m_wifi_connect_open(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId); } else { tstrAuthPsk strAuthPsk = {NULL, pstrWPS->au8PSK, (uint8)strlen((char*)(pstrWPS->au8PSK))}; m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk); } printf("WPS SSID : %s\n",pstrWPS->au8SSID); printf("WPS PSK : %s\n",pstrWPS->au8PSK); printf("WPS SSID Auth Type : %s\n",pstrWPS->u8AuthType == M2M_WIFI_SEC_OPEN ? "OPEN" : "WPA/WPA2"); printf("WPS Channel : %d\n",pstrWPS->u8Ch); } else { printf("(ERR) WPS Is not enabled OR Timed out\n"); } } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // Trigger WPS in Push button mode. m2m_wifi_wps(WPS_PBC_TRIGGER, NULL); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_wps(uint8 u8TriggerType,const char *pcPinNumber); /*! @ingroup WLANWPS @fn \ NMI_API sint8 m2m_wifi_wps_disable(void); @brief Stops the ongoing WPS session. @pre WINC should be already in WPS mode using @ref m2m_wifi_wps. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_wps */ NMI_API sint8 m2m_wifi_wps_disable(void); /**@cond P2P_DOC */ /*! @ingroup WLANP2P @fn \ NMI_API sint8 m2m_wifi_p2p(uint8 u8Channel); @warning P2P has been deprecated from version 19.5.3! */ NMI_API sint8 m2m_wifi_p2p(uint8 u8Channel); /*! @ingroup WLANP2P @fn \ NMI_API sint8 m2m_wifi_p2p_disconnect(void); @warning P2P has been deprecated from version 19.5.3! */ NMI_API sint8 m2m_wifi_p2p_disconnect(void); /**@endcond*/ //P2P_DOC /*! @ingroup WLANAP @fn \ NMI_API sint8 m2m_wifi_enable_ap(CONST tstrM2MAPConfig* pstrM2MAPConfig); @brief Asynchronous API to enable access point (AKA "hot-spot") mode on the WINC IC. @details The WINC IC supports the ability to operate as an access point with the following limitations: - Only 1 station may be associated at any given time. - Open system and WEP are the only security suites supported. @param[in] pstrM2MAPConfig A structure holding the AP configurations. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback is done through passing it to the @ref m2m_wifi_init. - The event @ref M2M_WIFI_REQ_DHCP_CONF must be handled in the callback. - The @ref m2m_wifi_handle_events MUST be called to receive the responses in the callback. @warning This function is not allowed in STA mode. @see tpfAppWifiCb tenuM2mSecType m2m_wifi_init M2M_WIFI_REQ_DHCP_CONF tstrM2mWifiStateChanged tstrM2MAPConfig \section WIFIExample5 Example The code snippet demonstrates how the AP mode is enabled after the driver is initialized in the application's main function and the handling of the event @ref M2M_WIFI_REQ_DHCP_CONF, to indicate successful connection. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_REQ_DHCP_CONF: { uint8 *pu8IPAddress = (uint8*)pvMsg; printf("Associated STA has IP Address \"%u.%u.%u.%u\"\n",pu8IPAddress[0],pu8IPAddress[1],pu8IPAddress[2],pu8IPAddress[3]); } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { tstrM2MAPConfig apConfig; strcpy(apConfig.au8SSID, "WINC_SSID"); apConfig.u8ListenChannel = 1; apConfig.u8SecType = M2M_WIFI_SEC_OPEN; apConfig.u8SsidHide = 0; // IP Address apConfig.au8DHCPServerIP[0] = 192; apConfig.au8DHCPServerIP[1] = 168; apConfig.au8DHCPServerIP[2] = 1; apConfig.au8DHCPServerIP[3] = 1; // Trigger AP m2m_wifi_enable_ap(&apConfig); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_enable_ap(CONST tstrM2MAPConfig* pstrM2MAPConfig); /*! @ingroup WLANAP @fn \ NMI_API sint8 m2m_wifi_enable_ap_ext(CONST tstrM2MAPModeConfig* pstrM2MAPModeConfig); @brief Asynchronous API to enable access point (AKA "hot-spot") mode on the WINC IC with extended options. @details The WINC IC supports the ability to operate as an access point with the following limitations: - Only 1 station may be associated at any given time. - Open system and WEP are the only security suites supported. @param [in] pstrM2MAPModeConfig A structure holding the AP configurations. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback is done through passing it to the @ref m2m_wifi_init. - The event @ref M2M_WIFI_REQ_DHCP_CONF must be handled in the callback. - The @ref m2m_wifi_handle_events MUST be called to receive the responses in the callback. @warning This function is not allowed in STA mode. @see tpfAppWifiCb tenuM2mSecType m2m_wifi_init M2M_WIFI_REQ_DHCP_CONF tstrM2mWifiStateChanged tstrM2MAPModeConfig tstrM2MAPConfigExt \section WIFIExample5b Example The code snippet demonstrates how the AP mode is enabled after the driver is initialized in the application's main function and the handling of the event @ref M2M_WIFI_REQ_DHCP_CONF, to indicate successful connection. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_REQ_DHCP_CONF: { uint8 *pu8IPAddress = (uint8*)pvMsg; printf("Associated STA has IP Address \"%u.%u.%u.%u\"\n",pu8IPAddress[0],pu8IPAddress[1],pu8IPAddress[2],pu8IPAddress[3]); } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { tstrM2MAPModeConfig apModeConfig; strcpy(apConfig.strApConfig.au8SSID, "WINC_SSID"); apModeConfig.strApConfig.u8ListenChannel = 1; apModeConfig.strApConfig.u8SecType = M2M_WIFI_SEC_OPEN; apModeConfig.strApConfig.u8SsidHide = 0; // IP Address apModeConfig.strApConfig.au8DHCPServerIP[0] = 192; apModeConfig.strApConfig.au8DHCPServerIP[1] = 168; apModeConfig.strApConfig.au8DHCPServerIP[2] = 1; apModeConfig.strApConfig.au8DHCPServerIP[3] = 1; // Default router IP m2m_memcpy(apModeConfig.strApConfigExt.au8DefRouterIP, apModeConfig.strApConfig.au8DHCPServerIP, 4); // DNS Server IP m2m_memcpy(apModeConfig.strApConfigExt.au8DNSServerIP, apModeConfig.strApConfig.au8DHCPServerIP, 4); // Subnet mask apModeConfig.strApConfigExt.au8SubnetMask[0] = 255; apModeConfig.strApConfigExt.au8SubnetMask[1] = 255; apModeConfig.strApConfigExt.au8SubnetMask[2] = 255; apModeConfig.strApConfigExt.au8SubnetMask[3] = 0; // Trigger AP m2m_wifi_enable_ap_ext(&apModeConfig); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_enable_ap_ext(CONST tstrM2MAPModeConfig* pstrM2MAPModeConfig); /*! @ingroup WLANAP @fn \ NMI_API sint8 m2m_wifi_disable_ap(void); @brief Synchronous API to disable access point mode on the WINC IC. @details Must be called only when the AP is enabled through the @ref m2m_wifi_enable_ap function. Otherwise the call to this function will not be useful. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_ap */ NMI_API sint8 m2m_wifi_disable_ap(void); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_set_static_ip(tstrM2MIPConfig * pstrStaticIPConf); @brief Synchronous API to manually assign a (static) IP address to the WINC IC. @details Assign a static IP address to the WINC board. This function assigns a static IP address in case the AP doesn't have a DHCP server or in case the application wants to assign a predefined known IP address. The user must keep in mind that assigning a static IP address might result in an IP address conflict. In case of an IP address conflict observed by the WINC board the user will get a response of @ref M2M_WIFI_RESP_IP_CONFLICT in the wifi callback. The application is then responsible to either solve the conflict or assign another IP address. @pre The application must disable auto DHCP using @ref m2m_wifi_enable_dhcp before assigning a static IP address. @warning Normally this function should not be used. DHCP configuration is requested automatically after successful Wi-Fi connection is established. @param [in] pstrStaticIPConf Pointer to a structure holding the static IP configuration (IP, Gateway, subnet mask and DNS address). @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tstrM2MIPConfig */ NMI_API sint8 m2m_wifi_set_static_ip(tstrM2MIPConfig * pstrStaticIPConf); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_request_dhcp_client(void); @brief Legacy (deprecated) Asynchronous API for starting a DHCP client on the WINC IC. @details This is a legacy API and is no longer supported. Calls to this API will not result in any changes being made to the state of the WINC IC. @warning This function has been deprecated. DHCP is used automatically when the WINC IC connects. @return This function always returns @ref M2M_SUCCESS. */ NMI_API sint8 m2m_wifi_request_dhcp_client(void); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_request_dhcp_server(uint8* addr); @brief Dhcp requested by the firmware automatically in STA/AP mode). @warning This function is legacy and exists only for compatibility with older applications. DHCP server is started automatically when enabling the AP mode. @return This function always returns @ref M2M_SUCCESS. */ NMI_API sint8 m2m_wifi_request_dhcp_server(uint8* addr); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_enable_dhcp(uint8 u8DhcpEn); @brief Enable/Disable the DHCP client after connection. @details Synchronous Wi-Fi DHCP enable function. This function will Enable/Disable the DHCP protocol. @param [in] u8DhcpEn The state of the DHCP client feature after successful association with an access point: - 1: Enables DHCP client after connection. - 0: Disables DHCP client after connection. @return The function SHALL return @ref M2M_SUCCESS for successful operation and a negative value otherwise. @warning DHCP client is enabled by default. This Function should be called before using @ref m2m_wifi_set_static_ip @see m2m_wifi_set_static_ip */ NMI_API sint8 m2m_wifi_enable_dhcp(uint8 u8DhcpEn ); /*! @ingroup WLANSCAN @fn \ sint8 m2m_wifi_set_scan_options(tstrM2MScanOption* ptstrM2MScanOption); @brief Synchronous API for configuring the behaviour of the WINC IC's network scanning functions. @details This function sets the configuration parameters for the scan operation. @param [in] ptstrM2MScanOption; Pointer to the structure holding the Scan Parameters. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tenuM2mScanCh m2m_wifi_request_scan tstrM2MScanOption */ NMI_API sint8 m2m_wifi_set_scan_options(tstrM2MScanOption* ptstrM2MScanOption); /*! @ingroup WLANSCAN @fn \ sint8 m2m_wifi_set_stop_scan_on_first(uint8 u8StopScanOption); @brief Synchronous API for enabling/disabling the stop scan on first result of the WINC IC's network scanning functions. @details Allows for enabling/disabling of stop scan on first result. When enabled, the WINC will stop the scan as soon as it detects a network and return the results to the host. Setting is persistent and will need to be explicitly reverted back by the application if it no longer wishes for it to be enabled. @param[in] u8StopScanOption; Setting for enabling or disabling Stopping Scan on first result. 1 = Enabled, 0 = Disabled (Default) @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tenuM2mScanCh tstrM2MScanOption tstrM2MStopScanOption m2m_wifi_request_scan m2m_wifi_set_scan_options */ NMI_API sint8 m2m_wifi_set_stop_scan_on_first(uint8 u8StopScanOption); /*! @ingroup WLANSCAN @fn \ sint8 m2m_wifi_set_scan_region(uint16 ScanRegion); @brief Synchronous API for configuring the regulatory restrictions that may affect the WINC ICs scanning behaviour. @details This function sets a property called the scan region, a parameter that affects the range of channels that the WINC IC may legally scan given a geographic region. For 2.4GHz, supported in the current release, the requested scan region can't exceed the maximum number of channels (14). @param [in] ScanRegion ASIA NORTH_AMERICA @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tenuM2mScanCh m2m_wifi_request_scan */ NMI_API sint8 m2m_wifi_set_scan_region(uint16 ScanRegion); /*! @ingroup WLANSCAN @fn \ NMI_API sint8 m2m_wifi_request_scan(uint8 ch); @brief Asynchronous API to request the WINC IC to scan for networks. @details Scan statuses are delivered to the application via the Wi-Fi event callback (@ref tpfAppWifiCb) in three stages. The first step involves the event @ref M2M_WIFI_RESP_SCAN_DONE which, if successful, provides the number of detected networks (access points). The application must then read the list of access points via multiple calls to the asynchronous @ref m2m_wifi_req_scan_result API. For each call to this function, the application will receive (step three) the event @ref M2M_WIFI_RESP_SCAN_RESULT. @param [in] ch RF Channel ID for SCAN operation. It should be set according to @ref tenuM2mScanCh, with a value of @ref M2M_WIFI_CH_ALL to scan all channels. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registration of the callback is done via @ref m2m_wifi_init. - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT must be handled in the (tpfAppWifiCb) callback. - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback. @warning This API is valid only for STA mode, it may be called regardless of connection state (connected or disconnected states). @see M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT tpfAppWifiCb tstrM2mWifiscanResult tenuM2mScanCh m2m_wifi_init m2m_wifi_handle_events m2m_wifi_req_scan_result \section WIFIExample6 Example The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { static uint8 u8ScanResultIdx = 0; switch(u8WiFiEvent) { case M2M_WIFI_RESP_SCAN_DONE: { tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg; printf("Num of AP found %d\n",pstrInfo->u8NumofCh); if(pstrInfo->s8ScanState == M2M_SUCCESS) { u8ScanResultIdx = 0; if(pstrInfo->u8NumofCh >= 1) { m2m_wifi_req_scan_result(u8ScanResultIdx); u8ScanResultIdx ++; } else { printf("No AP Found Rescan\n"); m2m_wifi_request_scan(M2M_WIFI_CH_ALL); } } else { printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState); } } break; case M2M_WIFI_RESP_SCAN_RESULT: { tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg; uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found(); printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n", pstrScanResult->u8index,pstrScanResult->s8rssi, pstrScanResult->u8AuthType, pstrScanResult->u8ch, pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2], pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5], pstrScanResult->au8SSID); if(u8ScanResultIdx < u8NumFoundAPs) { // Read the next scan result m2m_wifi_req_scan_result(index); u8ScanResultIdx ++; } } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // Scan all channels m2m_wifi_request_scan(M2M_WIFI_CH_ALL); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_request_scan(uint8 ch); /*! @ingroup WLANSCAN @fn \ NMI_API sint8 m2m_wifi_request_scan_passive(uint8 ch, uint16 scan_time); @brief Similar to @ref m2m_wifi_request_scan but performs passive scanning instead of active scanning. @param [in] ch RF Channel ID for SCAN operation. It should be set according to @ref tenuM2mScanCh. With a value of @ref M2M_WIFI_CH_ALL, means to scan all channels. @param [in] scan_time The time in ms that passive scan is listening for beacons on each channel per one slot, enter 0 for default setting. @warning This function is not allowed in AP mode. It works only for STA mode (both connected or disconnected states). @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback is done through passing it to the @ref m2m_wifi_init. - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT. must be handled in the callback. - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback. @see M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT tpfAppWifiCb tstrM2mWifiscanResult tenuM2mScanCh m2m_wifi_init m2m_wifi_request_scan m2m_wifi_handle_events m2m_wifi_req_scan_result @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. */ NMI_API sint8 m2m_wifi_request_scan_passive(uint8 ch, uint16 scan_time); /*! @ingroup WLANSCAN @fn \ NMI_API sint8 m2m_wifi_request_scan_ssid_list(uint8 ch,uint8 * u8SsidList); @brief Asynchronous wi-fi scan request on the given channel and the hidden scan list. @details The scan status is delivered in the wi-fi event callback and then the application is to read the scan results sequentially. The number of APs found (N) is returned in event @ref M2M_WIFI_RESP_SCAN_DONE with the number of found APs. The application could read the list of APs by calling the function @ref m2m_wifi_req_scan_result N times. @param [in] ch RF Channel ID for SCAN operation. It should be set according to @ref tenuM2mScanCh. With a value of @ref M2M_WIFI_CH_ALL, means to scan all channels. @param [in] u8SsidList u8SsidList is a buffer containing a list of hidden SSIDs to include during the scan. The first byte in the buffer, u8SsidList[0], is the number of SSIDs encoded in the string. The number of hidden SSIDs cannot exceed @ref MAX_HIDDEN_SITES. All SSIDs are concatenated in the following bytes and each SSID is prefixed with a one-byte header containing its length. The total number of bytes in u8SsidList buffer, including length byte, cannot exceed 133 bytes (MAX_HIDDEN_SITES SSIDs x 32 bytes each, which is max SSID length). For instance, encoding the two hidden SSIDs "DEMO_AP" and "TEST" results in the following buffer content: @code uint8 u8SsidList[14]; u8SsidList[0] = 2; // Number of SSIDs is 2 u8SsidList[1] = 7; // Length of the string "DEMO_AP" without NULL termination memcpy(&u8SsidList[2], "DEMO_AP", 7); // Bytes index 2-9 containing the string DEMO_AP u8SsidList[9] = 4; // Length of the string "TEST" without NULL termination memcpy(&u8SsidList[10], "TEST", 4); // Bytes index 10-13 containing the string TEST @endcode @note It works with STA/AP mode (connected or disconnected). @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback is done through passing it to the @ref m2m_wifi_init. - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT. must be handled in the callback. - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback. @see M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT tpfAppWifiCb tstrM2mWifiscanResult tenuM2mScanCh m2m_wifi_init m2m_wifi_handle_events m2m_wifi_req_scan_result @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. \section WIFIExample6b Example The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response. @code #include "m2m_wifi.h" #include "m2m_types.h" static void request_scan_hidden_demo_ap(void); void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { static uint8 u8ScanResultIdx = 0; switch(u8WiFiEvent) { case M2M_WIFI_RESP_SCAN_DONE: { tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg; printf("Num of AP found %d\n",pstrInfo->u8NumofCh); if(pstrInfo->s8ScanState == M2M_SUCCESS) { u8ScanResultIdx = 0; if(pstrInfo->u8NumofCh >= 1) { m2m_wifi_req_scan_result(u8ScanResultIdx); u8ScanResultIdx ++; } else { printf("No AP Found Rescan\n"); request_scan_hidden_demo_ap(); } } else { printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState); } } break; case M2M_WIFI_RESP_SCAN_RESULT: { tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg; uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found(); printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n", pstrScanResult->u8index,pstrScanResult->s8rssi, pstrScanResult->u8AuthType, pstrScanResult->u8ch, pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2], pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5], pstrScanResult->au8SSID); if(u8ScanResultIdx < u8NumFoundAPs) { // Read the next scan result m2m_wifi_req_scan_result(index); u8ScanResultIdx ++; } } break; default: break; } } static void request_scan_hidden_demo_ap(void) { uint8 list[9]; char ssid[] = "DEMO_AP"; uint8 len = (uint8)(sizeof(ssid)-1); list[0] = 1; list[1] = len; memcpy(&list[2], ssid, len); // copy 7 bytes // Scan all channels m2m_wifi_request_scan_ssid_list(M2M_WIFI_CH_ALL, list); } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { request_scan_hidden_demo_ap(); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_request_scan_ssid_list(uint8 ch,uint8 * u8Ssidlist); /*! @ingroup WLANSCAN @fn \ NMI_API uint8 m2m_wifi_get_num_ap_found(void); @brief Synchronous function to retrieve the number of AP's found during the last scan operation. @details The function reads the number of APs from global variable which was updated in the Wi-Fi callback function through the @ref M2M_WIFI_RESP_SCAN_DONE event. Function used only in STA mode only. @see m2m_wifi_request_scan M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT @pre m2m_wifi_request_scan must be called first to ensure up to date results are available. - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback is done through passing it to the @ref m2m_wifi_init. - The event @ref M2M_WIFI_RESP_SCAN_DONE must be handled in the callback to receive the requested scan information. @warning This function must be called only in the wi-fi callback function when the events @ref M2M_WIFI_RESP_SCAN_DONE or @ref M2M_WIFI_RESP_SCAN_RESULT are received. Calling this function in any other place will result in undefined/outdated numbers. @return Return the number of AP's found in the last Scan Request. \section WIFIExample7 Example The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { static uint8 u8ScanResultIdx = 0; switch(u8WiFiEvent) { case M2M_WIFI_RESP_SCAN_DONE: { tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg; printf("Num of AP found %d\n",pstrInfo->u8NumofCh); if(pstrInfo->s8ScanState == M2M_SUCCESS) { u8ScanResultIdx = 0; if(pstrInfo->u8NumofCh >= 1) { m2m_wifi_req_scan_result(u8ScanResultIdx); u8ScanResultIdx ++; } else { printf("No AP Found Rescan\n"); m2m_wifi_request_scan(M2M_WIFI_CH_ALL); } } else { printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState); } } break; case M2M_WIFI_RESP_SCAN_RESULT: { tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg; uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found(); printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n", pstrScanResult->u8index,pstrScanResult->s8rssi, pstrScanResult->u8AuthType, pstrScanResult->u8ch, pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2], pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5], pstrScanResult->au8SSID); if(u8ScanResultIdx < u8NumFoundAPs) { // Read the next scan result m2m_wifi_req_scan_result(index); u8ScanResultIdx ++; } } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // Scan all channels m2m_wifi_request_scan(M2M_WIFI_CH_ALL); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API uint8 m2m_wifi_get_num_ap_found(void); /*! @ingroup WLANSCAN @fn \ NMI_API sint8 m2m_wifi_req_scan_result(uint8 index); @brief Synchronous call to read the AP information from the SCAN Result list. @details Synchronous call to read the AP information from the SCAN Result list with the given index. This function is expected to be called when the response events @ref M2M_WIFI_RESP_SCAN_RESULT or @ref M2M_WIFI_RESP_SCAN_DONE are received in the wi-fi callback function. The response information received can be obtained through the casting to the @ref tstrM2mWifiscanResult structure. @param [in] index Index for the requested result, the index range start from 0 till number of AP's found. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tstrM2mWifiscanResult m2m_wifi_get_num_ap_found m2m_wifi_request_scan @pre - @ref m2m_wifi_request_scan needs to be called first, then m2m_wifi_get_num_ap_found to get the number of AP's found. - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the @ref m2m_wifi_init function. - The event @ref M2M_WIFI_RESP_SCAN_RESULT must be handled in the callback to receive the requested scan information. @warning - Function used in STA mode only. the scan results are updated only if the scan request is called. - Calling this function only without a scan request will lead to firmware errors. - Application code should refrain from introducing a large delay between the scan request and the scan result request, to prevent errors occurring. \section WIFIExample8 Example The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { static uint8 u8ScanResultIdx = 0; switch(u8WiFiEvent) { case M2M_WIFI_RESP_SCAN_DONE: { tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg; printf("Num of AP found %d\n",pstrInfo->u8NumofCh); if(pstrInfo->s8ScanState == M2M_SUCCESS) { u8ScanResultIdx = 0; if(pstrInfo->u8NumofCh >= 1) { m2m_wifi_req_scan_result(u8ScanResultIdx); u8ScanResultIdx ++; } else { printf("No AP Found Rescan\n"); m2m_wifi_request_scan(M2M_WIFI_CH_ALL); } } else { printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState); } } break; case M2M_WIFI_RESP_SCAN_RESULT: { tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg; uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found(); printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n", pstrScanResult->u8index,pstrScanResult->s8rssi, pstrScanResult->u8AuthType, pstrScanResult->u8ch, pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2], pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5], pstrScanResult->au8SSID); if(u8ScanResultIdx < u8NumFoundAPs) { // Read the next scan result m2m_wifi_req_scan_result(index); u8ScanResultIdx ++; } } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // Scan all channels m2m_wifi_request_scan(M2M_WIFI_CH_ALL); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_req_scan_result(uint8 index); /*! @ingroup WLANCONNECT @fn \ NMI_API sint8 m2m_wifi_req_curr_rssi(void); @brief Asynchronous API to request the current Receive Signal Strength (RSSI) of the current connection. @details This function will result in the application receiving the RSSI via a @ref M2M_WIFI_RESP_CURRENT_RSSI event. @pre - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered during initialization. Registration of the callback is done through passing it to @ref m2m_wifi_init via the @ref tstrWifiInitParam initialization structure. - The event @ref M2M_WIFI_RESP_CURRENT_RSSI must be handled in the callback to receive the requested Rssi information. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. \section WIFIExample9 Example The code snippet demonstrates how the RSSI request is called in the application's main function and the handling of the event received in the callback. @code #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { static uint8 u8ScanResultIdx = 0; switch(u8WiFiEvent) { case M2M_WIFI_RESP_CURRENT_RSSI: { sint8 *rssi = (sint8*)pvMsg; M2M_INFO("ch rssi %d\n",*rssi); } break; default: break; } } int main() { tstrWifiInitParam param; param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // Scan all channels m2m_wifi_req_curr_rssi(); while(1) { m2m_wifi_handle_events(NULL); } } } @endcode */ NMI_API sint8 m2m_wifi_req_curr_rssi(void); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_get_otp_mac_address(uint8 *pu8MacAddr, uint8 * pu8IsValid); @brief Synchronous API to query the MAC address programmed into the WINC ICs OTP memory. @details This function attempts to read the device's MAC address from the One Time Programmable (OTP) memory on the IC. The presence (yes or no) of a MAC address in the OTP memory and, in the case of it being present, its value is returned via RAM pointed to by the input arguments. Request the MAC address stored on the One Time Programmable(OTP) memory of the device. The function is blocking until the response is received. @pre Prior call to @ref m2m_wifi_init is required before any WIFI/socket function. @param [out] pu8MacAddr Output MAC address buffer 6 bytes in size. Valid only if *pu8Valid=1. @param [out] pu8IsValid A boolean value set by the callee to indicate the validity of pu8MacAddr in OTP. If no MAC has been programmed in the OTP the value of this parameter will be zero; otherwise it will be non-zero. @return The function returns @ref M2M_SUCCESS for success and a negative value otherwise. @see m2m_wifi_get_mac_address */ NMI_API sint8 m2m_wifi_get_otp_mac_address(uint8 *pu8MacAddr, uint8 * pu8IsValid); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_get_mac_address(uint8 *pu8MacAddr) @brief Synchronous API to retrieve the MAC address currently in use by the device. @details Function to retrieve the current MAC address. The function is blocking until the response is received. @pre Prior call to @ref m2m_wifi_init is required before any WIFI/socket function. @param [out] pu8MacAddr Pointer to a buffer in memory containing a 6-byte MAC address (provided function returns @ref M2M_SUCCESS). @return The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise. @see m2m_wifi_get_otp_mac_address */ NMI_API sint8 m2m_wifi_get_mac_address(uint8 *pu8MacAddr); /*! @ingroup WLANPS @fn \ NMI_API sint8 m2m_wifi_set_sleep_mode(uint8 PsTyp, uint8 BcastEn); @brief Synchronous API to set the power-save mode of the WINC IC. @details This is one of the two synchronous power-save setting functions that allow the host MCU application to tweak the system power consumption. Such tweaking can be done through one of two ways: - 1) Changing the power save mode, to one of the allowed power save modes (see @ref tenuPowerSaveModes). This is done by setting the first parameter. - 2) Configuring DTIM monitoring: Configuring beacon monitoring parameters by enabling or disabling the reception of broadcast/multicast data. This is done by setting the second parameter. @param [in] PsTyp Desired power saving mode. Supported types are enumerated in @ref tenuPowerSaveModes. @param [in] BcastEn Broadcast reception enable flag. If it is 1, the WINC will be awake for each DTIM beacon in order to check for and receive broadcast traffic. If it is 0, the WINC will ignore broadcast traffic. Through this flag the WINC will not wakeup at the DTIM beacon, but instead it will wakeup only based on the configured Listen Interval. @warning The function called once after initialization. @return The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise. @see tenuPowerSaveModes m2m_wifi_get_sleep_mode m2m_wifi_set_lsn_int */ NMI_API sint8 m2m_wifi_set_sleep_mode(uint8 PsTyp, uint8 BcastEn); /*! @ingroup WLANPS @fn \ NMI_API sint8 m2m_wifi_request_sleep(uint32 u32SlpReqTime); @brief API to place the WINC IC into sleep mode for a specified period of time. @details Synchronous power-save sleep request function, which requests the WINC device to sleep in the currently configured power save mode, as set using @ref m2m_wifi_set_sleep_mode, for a specific time as defined by the passed in parameter. This function should be used in the @ref M2M_PS_MANUAL power save mode only. A wake up request is automatically performed by the WINC device when any host driver API function, e.g. Wi-Fi or socket operation is called. @param [in] u32SlpReqTime Request sleep time in ms.\n The best recommended sleep duration is left to be determined by the application. Taking into account that if the application sends notifications very rarely, sleeping for a long time can be a power-efficient decision. In contrast, applications that are sensitive for long periods of absence can experience performance degradation in the connection if long sleeping times are used. @return The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise. @warning The function should be called in @ref M2M_PS_MANUAL power save mode only. As enumerated in @ref tenuPowerSaveModes. It's also important to note that during the sleeping time while in the M2M_PS_MANUAL mode, AP beacon monitoring is bypassed and the wifi-connection may drop if the sleep period is elongated. @see tenuPowerSaveModes m2m_wifi_set_sleep_mode */ NMI_API sint8 m2m_wifi_request_sleep(uint32 u32SlpReqTime); /*! @ingroup WLANPS @fn \ NMI_API uint8 m2m_wifi_get_sleep_mode(void); @brief Synchronous power save mode retrieval function. @return The current operating power saving mode based on the enumerated sleep modes @ref tenuPowerSaveModes. @see tenuPowerSaveModes m2m_wifi_set_sleep_mode */ NMI_API uint8 m2m_wifi_get_sleep_mode(void); /*! @fn \ NMI_API sint8 m2m_wifi_req_client_ctrl(uint8 cmd); @brief Asynchronous command sending function to the PS Client. @details Asynchronous command sending function to the PS Client (a WINC board running the ps_firmware) if the PS client sends any command, it will be received through the @ref M2M_WIFI_RESP_CLIENT_INFO event. @param [in] cmd Control command sent from PS Server to PS Client (command values defined by the application) @pre @ref m2m_wifi_req_server_init should be called first. @warning This mode is not supported in the current release. @see m2m_wifi_req_server_init M2M_WIFI_RESP_CLIENT_INFO @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. */ NMI_API sint8 m2m_wifi_req_client_ctrl(uint8 cmd); /*! @fn \ NMI_API sint8 m2m_wifi_req_server_init(uint8 ch); @brief Synchronous function to initialize the PS Server. @details The WINC supports non secure communication with another WINC, (SERVER/CLIENT) through one byte command (probe request and probe response) without any connection setup. The server mode can't be used with any other modes (STA/AP) @param [in] ch Server listening channel @see m2m_wifi_req_client_ctrl @warning This mode is not supported in the current release. @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. */ NMI_API sint8 m2m_wifi_req_server_init(uint8 ch); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_set_device_name(uint8 *pu8DeviceName, uint8 u8DeviceNameLength); @brief Asynchronous API to set the "Device Name" of the WINC IC. @details Sets the WINC device name. The name string is used as a device name in DHCP hostname (option 12). If a device is not set through this function a default name is assigned. The default name is WINC-XX-YY, where XX and YY are the last 2 octets of the OTP MAC address. If OTP (eFuse) is programmed, then the default name is WINC-00-00. @warning The function called once after initialization.\n Used for DHCP client hostname option (12).\n Device name shall contain only characters allowed in valid internet host name as defined in RFC 952 and 1123. @param [in] pu8DeviceName Buffer holding the device name. Device name is a null terminated C string. @param [in] u8DeviceNameLength Length of the device name. Should not exceed the maximum device name's length @ref M2M_DEVICE_NAME_MAX (including null character). @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. */ NMI_API sint8 m2m_wifi_set_device_name(uint8 *pu8DeviceName, uint8 u8DeviceNameLength); /*! @ingroup WLANTIME @fn \ NMI_API sint8 m2m_wifi_configure_sntp(uint8 *pu8NTPServerName, uint8 u8NTPServerNameLength, tenuSNTPUseDHCP useDHCP); @brief Configures what NTP server the SNTP client should use. @details Configures what NTP server the SNTP client should use. Only 1 server name can be provided, if the configured server name begins with an asterisk then it will be treated as a server pool. The SNTP client can also use the NTP server provided by the DHCP server through option 42. By default the NTP server provided by DHCP will be tried first, then the built-in default NTP server (time.nist.gov) will be used. @param [in] pu8NTPServerName Buffer holding the NTP server name. If the first character is an asterisk (*) then it will be treated as a server pool, where the asterisk will be replaced with an incrementing value from 0 to 3 each time a server fails (example: *.pool.ntp.org). @param [in] u8NTPServerNameLength Length of the NTP server name. Should not exceed the maximum NTP server name length of @ref M2M_NTP_MAX_SERVER_NAME_LENGTH. @param[in] useDHCP Explicity tell the WINC if it should use the NTP server provided by the DHCP server or not. @warning SNTP should be configured before the connection takes place. If SNTP is configured after the device connects to a network, the new configuration can take a minimum of 24h to be applied. However, it can take even longer since it is triggered by DHCP renewal. Currently there is also a known issue in which if the WINC obtains the NTP server from DHCP and then connects to a different network, it will still use the NTP from the previous network. Configuring a server name will overwrite the built-in default server until next reboot. @return The function returns @ref M2M_SUCCESS for success and a negative value otherwise. */ NMI_API sint8 m2m_wifi_configure_sntp(uint8 *pu8NTPServerName, uint8 u8NTPServerNameLength, tenuSNTPUseDHCP useDHCP); /*! @ingroup WLANPS @fn \ NMI_API sint8 m2m_wifi_set_lsn_int(tstrM2mLsnInt * pstrM2mLsnInt); @brief API to set Wi-Fi listen interval for power save operation. @details This is one of the two synchronous power-save setting functions that allow the host MCU application to tweak the system power consumption. Such tweaking can be done by modifying the Wi-Fi listen interval. The listen interval is how many beacon periods the station can sleep before it wakes up to receive data buffered in the AP. It is represented in units of AP beacon periods(100ms). @warning The function should be called once after initialization. @param [in] pstrM2mLsnInt Structure holding the listen interval configuration. @pre The function @ref m2m_wifi_set_sleep_mode shall be called first, to set the power saving mode required. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tstrM2mLsnInt m2m_wifi_set_sleep_mode */ NMI_API sint8 m2m_wifi_set_lsn_int(tstrM2mLsnInt *pstrM2mLsnInt); /**@cond MON_DOC */ /*! @ingroup WLANMON @fn \ NMI_API sint8 m2m_wifi_enable_monitoring_mode(tstrM2MWifiMonitorModeCtrl *, uint8 *, uint16 , uint16); @brief Asynchronous call to enable Wi-Fi monitoring (promiscuous receive) mode. @details Asynchronous Wi-Fi monitoring mode (Promiscuous mode) enabling function. This function enables the monitoring mode, thus allowing two operations to be performed: 1) Transmission of manually configured frames, through using the @ref m2m_wifi_send_wlan_pkt function. 2) Reception of frames based on a defined filtering criteria. When the monitoring mode is enabled, reception of all frames that satisfy the filter criteria passed in as a parameter is allowed, on the current wireless channel. All packets that meet the filtering criteria are passed to the application layer, to be handled by the assigned monitoring callback function. The monitoring callback function must be implemented before starting the monitoring mode, in-order to handle the packets received. Registering of the implemented callback function is through the callback pointer @ref tpfAppMonCb in the @ref tstrWifiInitParam structure passed to @ref m2m_wifi_init function at initialization. @param [in] pstrMtrCtrl Pointer to @ref tstrM2MWifiMonitorModeCtrl structure holding the filtering parameters. @param [in] pu8PayloadBuffer Pointer to a Buffer allocated by the application. The buffer SHALL hold the Data field of the WIFI RX Packet (Or a part from it). If it is set to NULL, the WIFI data payload will be discarded by the monitoring driver. @param [in] u16BufferSize The total size of the pu8PayloadBuffer in bytes. @param [in] u16DataOffset Starting offset in the DATA FIELD of the received WIFI packet. The application may be interested in reading specific information from the received packet. It must assign the offset to the starting position of it relative to the DATA payload start.\n \e Example, \e if \e the \e SSID \e is \e needed \e to \e be \e read \e from \e a \e PROBE \e REQ \e packet, \e the \e u16Offset \e MUST \e be \e set \e to \e 0. @warning When this mode is enabled, you cannot be connected in any mode (Station or Access Point). @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see tstrM2MWifiMonitorModeCtrl tstrM2MWifiRxPacketInfo tstrWifiInitParam tenuM2mScanCh m2m_wifi_disable_monitoring_mode m2m_wifi_send_wlan_pkt m2m_wifi_send_ethernet_pkt \section WIFIExample10 Example The example demonstrates the main function where-by the monitoring enable function is called after the initialization of the driver and the packets are handled in the callback function. @code #include "m2m_wifi.h" #include "m2m_types.h" //Declare receive buffer uint8 gmgmt[1600]; //Callback functions void wifi_cb(uint8 u8WiFiEvent, void * pvMsg) { ; } void wifi_monitoring_cb(tstrM2MWifiRxPacketInfo *pstrWifiRxPacket, uint8 *pu8Payload, uint16 u16PayloadSize) { if((NULL != pstrWifiRxPacket) && (0 != u16PayloadSize)) { if(MANAGEMENT == pstrWifiRxPacket->u8FrameType) { M2M_INFO("***# MGMT PACKET #***\n"); } else if(DATA_BASICTYPE == pstrWifiRxPacket->u8FrameType) { M2M_INFO("***# DATA PACKET #***\n"); } else if(CONTROL == pstrWifiRxPacket->u8FrameType) { M2M_INFO("***# CONTROL PACKET #***\n"); } } } int main() { //Register wifi_monitoring_cb tstrWifiInitParam param; param.pfAppWifiCb = wifi_cb; param.pfAppMonCb = wifi_monitoring_cb; nm_bsp_init(); if(!m2m_wifi_init(¶m)) { //Enable Monitor Mode with filter to receive all data frames on channel 1 tstrM2MWifiMonitorModeCtrl strMonitorCtrl = {0}; strMonitorCtrl.u8ChannelID = M2M_WIFI_CH_1; strMonitorCtrl.u8FrameType = DATA_BASICTYPE; strMonitorCtrl.u8FrameSubtype = M2M_WIFI_FRAME_SUB_TYPE_ANY; //Receive any subtype of data frame m2m_wifi_enable_monitoring_mode(&strMonitorCtrl, gmgmt, sizeof(gmgmt), 0); while(1) { m2m_wifi_handle_events(NULL); } } return 0; } @endcode */ NMI_API sint8 m2m_wifi_enable_monitoring_mode(tstrM2MWifiMonitorModeCtrl *pstrMtrCtrl, uint8 *pu8PayloadBuffer, uint16 u16BufferSize, uint16 u16DataOffset); /*! @ingroup WLANMON @fn \ NMI_API sint8 m2m_wifi_disable_monitoring_mode(void); @brief API to disable Wi-Fi monitoring (promiscuous receive) mode. @details Synchronous function to disable Wi-Fi monitoring mode (Promiscuous mode). Expected to be called, if the enable monitoring mode is set, but if it was called without enabling no negative impact will reside. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_monitoring_mode */ NMI_API sint8 m2m_wifi_disable_monitoring_mode(void); /*! @ingroup WLANMON @fn \ NMI_API sint8 m2m_wifi_send_wlan_pkt(uint8 *, uint16, uint16); @brief Synchronous function to transmit a WIFI RAW packet while the implementation of this packet is left to the application developer. @pre Enable Monitoring mode first using @ref m2m_wifi_enable_monitoring_mode @note Packets are user's responsibility. @warning This function available in monitoring mode ONLY. @param [in] pu8WlanPacket Pointer to a buffer holding the whole WIFI frame. @param [in] u16WlanHeaderLength The size of the WIFI packet header ONLY. @param [in] u16WlanPktSize The size of the whole packet in bytes. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_monitoring_mode m2m_wifi_disable_monitoring_mode */ NMI_API sint8 m2m_wifi_send_wlan_pkt(uint8 *pu8WlanPacket, uint16 u16WlanHeaderLength, uint16 u16WlanPktSize); /**@endcond*/ //MON_DOC /*! @ingroup WLANETH @fn \ NMI_API sint8 m2m_wifi_send_ethernet_pkt(uint8* pu8Packet,uint16 u16PacketSize); @brief Synchronous function to transmit an Ethernet packet. @details Transmit a packet directly in ETHERNET/bypass mode where the TCP/IP stack is disabled and the implementation of this packet is left to the application developer. The Ethernet packet composition is left to the application developer. @note Packets are the user's responsibility. @warning This function available in ETHERNET/Bypass mode ONLY. Make sure that application defines ETH_MODE. @param [in] pu8Packet Pointer to a buffer holding the whole Ethernet frame. @param [in] u16PacketSize The size of the whole packet in bytes. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_mac_mcast m2m_wifi_set_receive_buffer */ NMI_API sint8 m2m_wifi_send_ethernet_pkt(uint8* pu8Packet,uint16 u16PacketSize); /*! @ingroup WLANTIME @fn \ NMI_API sint8 m2m_wifi_enable_sntp(uint8); @brief Synchronous function to enable/disable the native Simple Network Time Protocol(SNTP) client in the WINC15x0 firmware. @details The SNTP is enabled by default at start-up.The SNTP client at firmware is used to synchronize the system clock to the UTC time from the well known time servers (e.g. "time-c.nist.gov"). The SNTP client uses a default update cycle of 1 day. The UTC is important for checking the expiration date of X509 certificates used while establishing TLS (Transport Layer Security) connections. It is highly recommended to use it if there is no other means to get the UTC time. If there is a RTC on the host MCU, the SNTP could be disabled and the host should set the system time to the firmware using the @ref m2m_wifi_set_system_time function. @param [in] bEnable Enables or disables the SNTP service '0' :disable SNTP '1' :enable SNTP @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_set_system_time */ NMI_API sint8 m2m_wifi_enable_sntp(uint8 bEnable); /*! @ingroup WLANTIME @fn \ NMI_API sint8 m2m_wifi_set_system_time(uint32); @brief Function for setting the system time within the WINC IC. @details Synchronous function for setting the system time in time/date format (@ref uint32). The @ref tstrSystemTime structure can be used as a reference to the time values that should be set and pass its value as @ref uint32. @param [in] u32UTCSeconds Seconds elapsed since January 1, 1900 (NTP Timestamp). @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_sntp tstrSystemTime @note If there is an RTC on the host MCU, the SNTP may be disabled and the host may set the system time within the firmware using the API @ref m2m_wifi_set_system_time. */ NMI_API sint8 m2m_wifi_set_system_time(uint32 u32UTCSeconds); /*! @ingroup WLANTIME @fn \ NMI_API sint8 m2m_wifi_get_system_time(void); @brief Asynchronous API to obtain the system time in use by the WINC IC. @details Asynchronous function used to retrieve the system time through the use of the response @ref M2M_WIFI_RESP_GET_SYS_TIME. Response time retrieved is parsed into the members defined in the structure @ref tstrSystemTime. @note Get the system time from the SNTP client using the API @ref m2m_wifi_get_system_time. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_sntp tstrSystemTime */ NMI_API sint8 m2m_wifi_get_system_time(void); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_set_cust_InfoElement(uint8*); @brief API to add or remove a user-defined Information Element @details Synchronous function to Add/Remove user-defined Information Element to the WIFIBeacon and Probe Response frames while chip mode is Access Point Mode.\n According to the information element layout shown bellow, if it is required to set new data for the information elements, pass in the buffer with the information according to the sizes and ordering defined bellow. However, if it's required to delete these IEs, fill the buffer with zeros. @param [in] pau8M2mCustInfoElement Pointer to Buffer containing the IE to be sent. It is the application developer's responsibility to ensure on the correctness of the information element's ordering passed in. @warning Size of All elements combined must not exceed 255 byte. Used in Access Point Mode. @note IEs Format will be follow the following layout: @verbatim --------------- ---------- ---------- ------------------- -------- -------- ----------- ----------------------- | Byte[0] | Byte[1] | Byte[2] | Byte[3:length1+2] | ..... | Byte[n] | Byte[n+1] | Byte[n+2:lengthx+2] | |---------------|----------|----------|-------------------|-------- --------|-----------|---------------------| | #of all Bytes | IE1 ID | Length1 | Data1(Hex Coded) | ..... | IEx ID | Lengthx | Datax(Hex Coded) | --------------- ---------- ---------- ------------------- -------- -------- ----------- ----------------------- @endverbatim @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_sntp \section WIFIExample11 Example The example demonstrates how the information elements are set using this function. @code char elementData[21]; static char state = 0; // To Add, Append, and Delete if(0 == state) { //Add 3 IEs state = 1; //Total Number of Bytes elementData[0]=12; //First IE elementData[1]=200; elementData[2]=1; elementData[3]='A'; //Second IE elementData[4]=201; elementData[5]=2; elementData[6]='B'; elementData[7]='C'; //Third IE elementData[8]=202; elementData[9]=3; elementData[10]='D'; elementData[11]=0; elementData[12]='F'; } else if(1 == state) { //Append 2 IEs to others, Notice that we keep old data in array starting with\n //element 13 and total number of bytes increased to 20 state = 2; //Total Number of Bytes elementData[0]=20; //Fourth IE elementData[13]=203; elementData[14]=1; elementData[15]='G'; //Fifth IE elementData[16]=204; elementData[17]=3; elementData[18]='X'; elementData[19]=5; elementData[20]='Z'; } else if(2 == state) { //Delete All IEs state = 0; //Total Number of Bytes elementData[0]=0; } m2m_wifi_set_cust_InfoElement(elementData); @endcode */ NMI_API sint8 m2m_wifi_set_cust_InfoElement(uint8* pau8M2mCustInfoElement); /*! @ingroup WLANPS @fn \ NMI_API sint8 m2m_wifi_set_power_profile(uint8 u8PwrMode); @brief Change the power profile mode @param [in] u8PwrMode Change the WINC power profile to different mode based on the enumeration @ref tenuM2mPwrMode. @warning May only be called after initialization, before any connection request, and may not be used to change the power mode thereafter. @return The function SHALL return @ref M2M_SUCCESS for success and a negative value otherwise. @see tenuM2mPwrMode m2m_wifi_init */ sint8 m2m_wifi_set_power_profile(uint8 u8PwrMode); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_set_tx_power(uint8 u8TxPwrLevel); @brief Set the TX power tenuM2mTxPwrLevel. @param [in] u8TxPwrLevel Change the TX power based on the enumeration \ref tenuM2mTxPwrLevel. @pre Must be called after the initialization and before any connection request and can't be changed in runtime. @return The function SHALL return @ref M2M_SUCCESS for success and a negative value otherwise. @see tenuM2mTxPwrLevel m2m_wifi_init */ sint8 m2m_wifi_set_tx_power(uint8 u8TxPwrLevel); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_set_gain_table_idx(uint8 u8GainTableIdx); @brief Set the Gain table index corresponding to specific WiFi region. @param [in] u8GainTableIdx change the gain table index based on the WiFi region it is suppose to be used. @pre Must be called after the initialization and before any connection request. The corresponding gain tables must be present in the flash. @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. @see m2m_wifi_init */ sint8 m2m_wifi_set_gain_table_idx(uint8 u8GainTableIdx); /*! @ingroup WLANLOG @fn \ NMI_API sint8 m2m_wifi_enable_firmware_logs(uint8 u8Enable); @brief Enable or Disable logs in run time. @details Enable or Disable logs in run time (Disable Firmware logs will enhance the firmware start-up time and performance). @param [in] u8Enable Set 1 to enable the logs, 0 for disable. @pre Must be called after initialization through the following function @ref m2m_wifi_init(). @return The function SHALL return @ref M2M_SUCCESS for success and a negative value otherwise. @see __DISABLE_FIRMWARE_LOGS__ (build option to disable logs from initializations) m2m_wifi_init */ sint8 m2m_wifi_enable_firmware_logs(uint8 u8Enable); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_set_battery_voltage(uint8 u8BattVolt); @brief Set the battery voltage to update the firmware calculations. @pre Must be called after initialization through the following function @ref m2m_wifi_init(). @param [in] dbBattVolt Battery Voltage as double. @return The function SHALL return @ref M2M_SUCCESS for success and a negative value otherwise. @see m2m_wifi_init */ sint8 m2m_wifi_set_battery_voltage(uint16 u16BattVoltx100); /*! @ingroup WLANCONF @fn \ sint8 m2m_wifi_set_gains(tstrM2mWifiGainsParams* pstrM2mGain); @brief Set the chip PPA gain for 11b/11gn. @param [in] pstrM2mGain @ref tstrM2mWifiGainsParams contain gain parameters as implemented in rf document. @pre Must be called after initialization through the following function @ref m2m_wifi_init. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_init */ sint8 m2m_wifi_set_gains(tstrM2mWifiGainsParams* pstrM2mGain); #ifdef ETH_MODE /*! @ingroup WLANETH @fn \ NMI_API sint8 m2m_wifi_enable_mac_mcast(uint8 *, uint8); @brief Synchronous function for filtering received MAC addresses @details Synchronous function for filtering received MAC addresses from certain MAC address groups. This function allows the addition/removal of certain MAC addresses, used in the multicast filter. @param [in] pu8MulticastMacAddress Pointer to MAC address @param [in] u8AddRemove A flag to add or remove the MAC ADDRESS, based on the following values: - 0 : remove MAC address - 1 : add MAC address @note Maximum number of MAC addresses that could be added is 8. @warning This function is available in ETHERNET/bypass mode ONLY. Make sure that the application defines ETH_MODE. @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_set_receive_buffer m2m_wifi_send_ethernet_pkt */ NMI_API sint8 m2m_wifi_enable_mac_mcast(uint8* pu8MulticastMacAddress, uint8 u8AddRemove); /*! @ingroup WLANETH @fn \ NMI_API sint8 m2m_wifi_set_receive_buffer(void *, uint16); @brief Synchronous function for setting or modifying the receiver buffer's length. @details Synchronous function for setting or modifying the receiver buffer's length. In the ETHERNET/bypass mode the application should define a callback of type @ref tpfAppEthCb, through which the application handles the received ethernet frames. It is through this callback function that the user can dynamically modify the length of the currently used receiver buffer. @param [in] pvBuffer Pointer to Buffer to receive data. NULL pointer causes a negative error @ref M2M_ERR_FAIL. @param [in] u16BufferLen Length of data to be received. Maximum length of data should not exceed the size defined by TCP/IP defined as @ref SOCKET_BUFFER_MAX_LENGTH @warning This function is available in the Ethernet/bypass mode ONLY. Make sure that the application defines ETH_MODE.\n @return The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise. @see m2m_wifi_enable_mac_mcast m2m_wifi_send_ethernet_pkt */ NMI_API sint8 m2m_wifi_set_receive_buffer(void* pvBuffer,uint16 u16BufferLen); #endif /* ETH_MODE */ /*! @ingroup WLANCRYPTO @fn \ sint8 m2m_wifi_prng_get_random_bytes(uint8* pu8PrngBuff,uint16 u16PrngSize); @brief Asynchronous function for retrieving from the firmware a pseudo-random set of bytes. @details Asynchronous function for retrieving from the firmware a pseudo-random set of bytes as specified in the size passed in as a parameter. The registered wifi-cb function retrieves the random bytes through the response @ref M2M_WIFI_RESP_GET_PRNG @param [in] pu8PrngBuff Pointer to a buffer to receive data. @param [in] u16PrngSize Requested size in bytes. Maximum 1580. @warning Size greater than the maximum specified (1580) causes a negative error @ref M2M_ERR_FAIL. @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. */ sint8 m2m_wifi_prng_get_random_bytes(uint8 * pu8PrngBuff,uint16 u16PrngSize); /*! @ingroup WLANCONF @fn \ NMI_API sint8 m2m_wifi_conf_auto_rate(tstrConfAutoRate * pstrConfAutoRate); @brief Configures WLAN automatic TX rate adaptation algorithm. @details Allow the host MCU app to configure auto TX rate selection algorithm. The application can use this API to tweak the algorithm performance. Moreover, it allows the application to force a specific WLAN PHY rate for transmitted data packets to favor range vs. throughput needs. @param [in] pstrConfAutoRate The Auto rate configuration parameters as listed in tstrConfAutoRate. @return The function SHALL return @ref M2M_SUCCESS for success and a negative value otherwise. @see tstrConfAutoRate */ NMI_API sint8 m2m_wifi_conf_auto_rate(tstrConfAutoRate * pstrConfAutoRate); /*! @ingroup WLANROAMING @fn \ sint8 m2m_wifi_enable_roaming(uint8 bEnableDhcp); @brief Enable WiFi STA roaming. @details m2m_wifi_enable_roaming enables the firmware to trigger the roaming algorithm/steps on link loss with the current AP. If roaming is successful, the @ref M2M_WIFI_RESP_CON_STATE_CHANGED message with state as @ref M2M_WIFI_ROAMED is sent to host. Additionally a @ref M2M_WIFI_REQ_DHCP_CONF message with new DHCP lease details is sent to host (only if bEnableDhcp=1). If roaming is unsuccessful, @ref M2M_WIFI_RESP_CON_STATE_CHANGED message with state as @ref M2M_WIFI_DISCONNECTED is sent to host. @param [in] bEnableDhcp 0 : Disables DHCP client execution after roaming to new AP 1 : Enables DHCP client execution after roaming to new AP @pre Must be called after the initialization. The roaming algorithm/procedure is internal to the firmware. @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. @see m2m_wifi_init */ sint8 m2m_wifi_enable_roaming(uint8 bEnableDhcp); /*! @ingroup WLANROAMING @fn \ sint8 m2m_wifi_disable_roaming(void); @brief Disable WiFi STA roaming. @pre Must be called after the initialization. @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. @see m2m_wifi_init */ sint8 m2m_wifi_disable_roaming(void); /*! @ingroup WLANINIT @fn \ NMI_API uint8 m2m_wifi_get_state(void); @brief Get the wifi state. @return The function returns the current wifi state (see @ref tenuWifiState for the possible states). @note Check the WINC state. See @ref tenuWifiState for possible states.\n @ref WIFI_STATE_INIT state represents WINC initialized but not started, this is a suitable state for safe flash access. @sa m2m_wifi_init m2m_wifi_download_mode */ NMI_API uint8 m2m_wifi_get_state(void); /** @defgroup VERSION Version @brief Describes the APIs for reading the version information of the WINC firmware. @{ @defgroup VERSIONDEF Defines @brief Specifies the macros and defines used by the version APIs. @defgroup VERSIONAPI Functions @brief Lists the APIs for reading the version information of the WINC firmware. @} */ /*! @ingroup VERSIONAPI @fn NMI_API m2m_wifi_get_firmware_version(tstrM2mRev* pstrRev); @brief Get Firmware version info. @details Get the Firmware version info from the active partition, as defined in the structure tstrM2mRev. @param [out] pstrRev Pointer to the structure tstrM2mRev that contains the firmware version parameters. @pre Must be called after initialization through the following function @ref m2m_wifi_init. @sa m2m_wifi_init @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. */ NMI_API sint8 m2m_wifi_get_firmware_version(tstrM2mRev* pstrRev); /*! @ingroup WLANPS @fn \ sint8 m2m_wifi_enable_XO_during_sleep(uint8 bXOSleepEnable); @brief Specifies whether the crystal oscillator is left on or off during deep sleep (defaults to off). @details m2m_wifi_enable_XO_during_sleep controls the state of the crystal oscillator during deep sleep. @param[in] bXOSleepEnable 0 : The XO will be switched off during deep sleep 1 : The XO will be kept on during deep sleep @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. */ sint8 m2m_wifi_enable_XO_during_sleep(uint8 bXOSleepEnable); #ifdef __cplusplus } #endif #endif /* __M2M_WIFI_H__ */