m2m_wifi.h

00001 /**
00002  *
00003  * \file
00004  *
00005  * \brief WINC WLAN Application Interface.
00006  *
00007  * Copyright (c) 2016-2017 Atmel Corporation. All rights reserved.
00008  *
00009  * \asf_license_start
00010  *
00011  * \page License
00012  *
00013  * Redistribution and use in source and binary forms, with or without
00014  * modification, are permitted provided that the following conditions are met:
00015  *
00016  * 1. Redistributions of source code must retain the above copyright notice,
00017  *    this list of conditions and the following disclaimer.
00018  *
00019  * 2. Redistributions in binary form must reproduce the above copyright notice,
00020  *    this list of conditions and the following disclaimer in the documentation
00021  *    and/or other materials provided with the distribution.
00022  *
00023  * 3. The name of Atmel may not be used to endorse or promote products derived
00024  *    from this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00027  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00028  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00029  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00030  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00031  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00032  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00033  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00034  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00035  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * \asf_license_stop
00039  *
00040  */
00041 
00042 #ifndef __M2M_WIFI_H__
00043 #define __M2M_WIFI_H__
00044 
00045 /** \defgroup m2m_wifi WLAN
00046  *
00047  */
00048 
00049 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00050 INCLUDES
00051 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00052 
00053 #include "common/include/nm_common.h"
00054 #include "driver/include/m2m_types.h"
00055 #include "driver/source/nmdrv.h"
00056 
00057 #ifdef CONF_MGMT
00058 
00059 
00060 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00061 MACROS
00062 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00063 /**@defgroup  WlanEnums DataTypes
00064  * @ingroup m2m_wifi
00065  * @{*/
00066 /*!
00067 @enum   \
00068     tenuWifiFrameType
00069 
00070 @brief
00071     Enumeration for Wi-Fi MAC frame type codes (2-bit) 
00072     The following types are used to identify the type of frame sent or received.
00073     Each frame type constitutes a number of frame subtypes as defined in @ref tenuSubTypes to specify the exact type of frame.
00074     Values are defined as per the IEEE 802.11 standard.
00075     
00076 @remarks
00077     The following frame types are useful for advanced user usage when monitoring mode is used (defining @ref CONF_MGMT)
00078     and the user application requires to monitor the frame transmission and reception.
00079 @see
00080     tenuSubTypes
00081 */
00082 typedef enum {
00083     MANAGEMENT             = 0x00,
00084     /*!< Wi-Fi Management frame (Probe Req/Resp, Beacon, Association Req/Resp ...etc).
00085     */
00086     CONTROL                = 0x04,
00087     /*!< Wi-Fi Control frame (eg. ACK frame).
00088     */
00089     DATA_BASICTYPE         = 0x08,
00090     /*!< Wi-Fi Data frame.
00091     */
00092     RESERVED              = 0x0C,
00093 
00094     M2M_WIFI_FRAME_TYPE_ANY  = 0xFF
00095 /*!< Set monitor mode to receive any of the frames types
00096 */
00097 }tenuWifiFrameType;
00098 
00099 
00100 /*!
00101 @enum   \
00102     tenuSubTypes
00103 
00104 @brief
00105     Enumeration for Wi-Fi MAC Frame subtype code (6-bit).
00106     The frame subtypes fall into one of the three frame type groups as defined in @ref tenuWifiFrameType
00107     (MANAGEMENT, CONTROL & DATA).
00108     Values are defined as per the IEEE 802.11 standard.
00109 @remarks
00110     The following sub-frame types are useful for advanced user usage when @ref CONF_MGMT is defined
00111     and the application developer requires to monitor the frame transmission and reception.
00112 @see
00113         tenuWifiFrameType
00114         tstrM2MWifiMonitorModeCtrl
00115 */
00116 typedef enum {
00117     /*!< Sub-Types related to Management Sub-Types */
00118     ASSOC_REQ              = 0x00,
00119     ASSOC_RSP             = 0x10,
00120     REASSOC_REQ           = 0x20,
00121     REASSOC_RSP           = 0x30,
00122     PROBE_REQ             = 0x40,
00123     PROBE_RSP             = 0x50,
00124     BEACON                = 0x80,
00125     ATIM                  = 0x90,
00126     DISASOC               = 0xA0,
00127     AUTH                  = 0xB0,
00128     DEAUTH                = 0xC0,
00129     ACTION                = 0xD0,
00130 /**@{*/ 
00131     /* Sub-Types related to Control */
00132     PS_POLL               = 0xA4,
00133     RTS                   = 0xB4,
00134     CTS                   = 0xC4,
00135     ACK                   = 0xD4,
00136     CFEND                 = 0xE4,
00137     CFEND_ACK             = 0xF4,
00138     BLOCKACK_REQ          = 0x84,
00139     BLOCKACK              = 0x94,
00140 /**@{*/ 
00141     /* Sub-Types related to Data */
00142     DATA                  = 0x08,
00143     DATA_ACK              = 0x18,
00144     DATA_POLL             = 0x28,
00145     DATA_POLL_ACK         = 0x38,
00146     NULL_FRAME            = 0x48,
00147     CFACK                 = 0x58,
00148     CFPOLL                = 0x68,
00149     CFPOLL_ACK            = 0x78,
00150     QOS_DATA              = 0x88,
00151     QOS_DATA_ACK          = 0x98,
00152     QOS_DATA_POLL         = 0xA8,
00153     QOS_DATA_POLL_ACK     = 0xB8,
00154     QOS_NULL_FRAME        = 0xC8,
00155     QOS_CFPOLL            = 0xE8,
00156     QOS_CFPOLL_ACK        = 0xF8,
00157     M2M_WIFI_FRAME_SUB_TYPE_ANY  = 0xFF
00158     /*!< Set monitor mode to receive any of the frames types
00159     */
00160 }tenuSubTypes;
00161 
00162 
00163 /*!
00164 @enum   \
00165     tenuInfoElementId
00166 
00167 @brief
00168     Enumeration for the Wi-Fi Information Element(IE) IDs, which indicates the specific type of IEs.
00169     IEs are management frame information included in management frames.
00170     Values are defined as per the IEEE 802.11 standard.
00171 
00172 */
00173 typedef enum {
00174     ISSID                = 0,
00175     /*!< Service Set Identifier (SSID)
00176     */
00177     ISUPRATES            = 1,
00178     /*!< Supported Rates
00179     */
00180     IFHPARMS             = 2,
00181     /*!< FH parameter set
00182     */
00183     IDSPARMS             = 3,
00184     /*!< DS parameter set
00185     */
00186     ICFPARMS             = 4,
00187     /*!< CF parameter set
00188     */
00189     ITIM                 = 5,
00190     /*!< Traffic Information Map
00191     */
00192     IIBPARMS             = 6,
00193     /*!< IBSS parameter set
00194     */
00195     ICOUNTRY             = 7,
00196     /*!< Country element.
00197     */
00198     IEDCAPARAMS          = 12,
00199     /*!< EDCA parameter set
00200     */
00201     ITSPEC               = 13,
00202     /*!< Traffic Specification
00203     */
00204     ITCLAS               = 14,
00205     /*!< Traffic Classification
00206     */
00207     ISCHED               = 15,
00208     /*!< Schedule.
00209     */
00210     ICTEXT               = 16,
00211     /*!< Challenge Text
00212     */
00213     IPOWERCONSTRAINT     = 32,
00214     /*!< Power Constraint.
00215     */
00216     IPOWERCAPABILITY     = 33,
00217     /*!< Power Capability
00218     */
00219     ITPCREQUEST          = 34,
00220     /*!< TPC Request
00221     */
00222     ITPCREPORT           = 35,
00223     /*!< TPC Report
00224     */
00225     ISUPCHANNEL         = 36,
00226     /* Supported channel list
00227     */
00228     ICHSWANNOUNC         = 37,
00229     /*!< Channel Switch Announcement
00230     */
00231     IMEASUREMENTREQUEST  = 38,
00232     /*!< Measurement request
00233     */
00234     IMEASUREMENTREPORT   = 39,
00235     /*!< Measurement report
00236     */
00237     IQUIET               = 40,
00238     /*!< Quiet element Info
00239     */
00240     IIBSSDFS             = 41,
00241     /*!< IBSS DFS
00242     */
00243     IERPINFO             = 42,
00244     /*!< ERP Information
00245     */
00246     ITSDELAY             = 43,
00247     /*!< TS Delay
00248     */
00249     ITCLASPROCESS        = 44,
00250     /*!< TCLAS Processing
00251     */
00252     IHTCAP               = 45,
00253     /*!< HT Capabilities
00254     */
00255     IQOSCAP              = 46,
00256     /*!< QoS Capability
00257     */
00258     IRSNELEMENT          = 48,
00259     /*!< RSN Information Element
00260     */
00261     IEXSUPRATES          = 50,
00262     /*!< Extended Supported Rates
00263     */
00264     IEXCHSWANNOUNC       = 60,
00265     /*!< Extended Ch Switch Announcement
00266     */
00267     IHTOPERATION         = 61,
00268     /*!< HT Information
00269     */
00270     ISECCHOFF            = 62,
00271     /*!< Secondary Channel Offset
00272     */
00273     I2040COEX            = 72,
00274     /*!< 20/40 Coexistence IE
00275     */
00276     I2040INTOLCHREPORT   = 73,
00277     /*!< 20/40 Intolerant channel report
00278     */
00279     IOBSSSCAN            = 74,
00280     /*!< OBSS Scan parameters
00281     */
00282     IEXTCAP              = 127,
00283     /*!< Extended capability
00284     */
00285     IWMM                 = 221,
00286     /*!< WMM parameters
00287     */
00288     IWPAELEMENT          = 221
00289     /*!< WPA Information Element
00290     */
00291 }tenuInfoElementId;
00292 
00293 
00294 /*!
00295 @struct \
00296     tenuWifiCapability
00297 
00298 @brief
00299     Enumeration for capability Information field bit. 
00300     The value of the capability information field from the 802.11 management frames received by the wireless LAN interface. 
00301     Defining the capabilities of the Wi-Fi system. Values are defined as per the IEEE 802.11 standard.
00302 
00303 @details
00304     Capabilities:-
00305     ESS/IBSS             : Defines whether a frame is coming from an AP or not.              
00306     POLLABLE            : CF Poll-able                  
00307     POLLREQ             : Request to be polled         
00308     PRIVACY             : WEP encryption supported     
00309     SHORTPREAMBLE   : Short Preamble is supported  
00310     SHORTSLOT           : Short Slot is supported      
00311     PBCC                :PBCC                         
00312     CHANNELAGILITY :Channel Agility              
00313     SPECTRUM_MGMT  :Spectrum Management          
00314     DSSS_OFDM      : DSSS-OFDM                    
00315 */
00316 typedef enum{
00317     ESS             = 0x01,
00318     /*!< ESS capability
00319     */
00320     IBSS            = 0x02,
00321     /*!< IBSS mode
00322     */
00323     POLLABLE        = 0x04,
00324     /*!< CF Pollable
00325     */
00326     POLLREQ         = 0x08,
00327     /*!< Request to be polled
00328     */
00329     PRIVACY         = 0x10,
00330     /*!< WEP encryption supported
00331     */
00332     SHORTPREAMBLE   = 0x20,
00333     /*!< Short Preamble is supported
00334     */
00335     SHORTSLOT       = 0x400,
00336     /*!< Short Slot is supported
00337     */
00338     PBCC            = 0x40,
00339     /*!< PBCC
00340     */
00341     CHANNELAGILITY  = 0x80,
00342     /*!< Channel Agility
00343     */
00344     SPECTRUM_MGMT   = 0x100,
00345     /*!< Spectrum Management
00346     */
00347     DSSS_OFDM       = 0x2000
00348     /*!< DSSS-OFDM
00349     */
00350 }tenuWifiCapability ;
00351 
00352 
00353 #endif
00354 
00355 /*!
00356 @typedef \
00357     tpfAppWifiCb
00358 
00359 @brief  
00360                 Wi-Fi's main callback function handler, for handling the M2M_WIFI events received on the Wi-Fi interface. 
00361                    Such notifications are received in response to Wi-Fi/P2P operations such as @ref m2m_wifi_request_scan,
00362                 @ref m2m_wifi_connect. 
00363                 Wi-Fi/P2P operations are implemented in an asynchronous mode, and all incoming information/status
00364                 are to be handled through this callback function when the corresponding notification is received.
00365                 Applications are expected to assign this wi-fi callback function by calling @ref m2m_wifi_init
00366 @param [in] u8MsgType
00367                 Type of notifications. Possible types are:
00368                 /ref M2M_WIFI_RESP_CON_STATE_CHANGED
00369                 /ref M2M_WIFI_RESP_CONN_INFO
00370                 /ref M2M_WIFI_REQ_DHCP_CONF
00371                 /ref M2M_WIFI_REQ_WPS
00372                 /ref M2M_WIFI_RESP_IP_CONFLICT 
00373                 /ref M2M_WIFI_RESP_SCAN_DONE
00374                 /ref M2M_WIFI_RESP_SCAN_RESULT
00375                 /ref M2M_WIFI_RESP_CURRENT_RSSI
00376                 /ref M2M_WIFI_RESP_CLIENT_INFO
00377                 /ref M2M_WIFI_RESP_PROVISION_INFO
00378                 /ref M2M_WIFI_RESP_DEFAULT_CONNECT
00379         
00380             In case Ethernet/Bypass mode is defined :
00381                 @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET
00382         
00383             In case monitoring mode is used:
00384                 @ref M2M_WIFI_RESP_WIFI_RX_PACKET
00385                 
00386 @param [in] pvMsg
00387                 A pointer to a buffer containing the notification parameters (if any). It should be
00388                 casted to the correct data type corresponding to the notification type.
00389 
00390 @see
00391     tstrM2mWifiStateChanged
00392     tstrM2MWPSInfo
00393     tstrM2mScanDone
00394     tstrM2mWifiscanResult
00395 */
00396 typedef void (*tpfAppWifiCb) (uint8 u8MsgType, void * pvMsg);
00397 
00398 /*!
00399 @typedef \
00400     tpfAppEthCb
00401 
00402 @brief  
00403     ETHERNET (bypass mode) notification callback function receiving Bypass mode events as defined in
00404     the Wi-Fi responses enumeration @ref tenuM2mStaCmd. 
00405 
00406 @param [in] u8MsgType
00407     Type of notification. Possible types are:
00408     - [M2M_WIFI_RESP_ETHERNET_RX_PACKET](@ref M2M_WIFI_RESP_ETHERNET_RX_PACKET)
00409 
00410 @param [in] pvMsg
00411     A pointer to a buffer containing the notification parameters (if any). It should be
00412     casted to the correct data type corresponding to the notification type.
00413     For example, it could be a pointer to the buffer holding the received frame in case of @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET
00414     event.
00415     
00416 @param [in] pvControlBuf
00417     A pointer to control buffer describing the accompanied message.
00418     To be casted to @ref tstrM2mIpCtrlBuf in case of @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET event.
00419 
00420 @warning
00421     Make sure that the application defines @ref ETH_MODE.
00422 
00423 @see
00424     m2m_wifi_init
00425 
00426 */
00427 typedef void (*tpfAppEthCb) (uint8 u8MsgType, void * pvMsg,void * pvCtrlBuf);
00428 
00429 /*!
00430 @typedef    \
00431     tpfAppMonCb
00432 
00433 @brief  
00434     Wi-Fi monitoring mode callback function. This function delivers all received wi-Fi packets through the Wi-Fi interface.
00435        Applications requiring to operate in the monitoring should call the asynchronous function m2m_wifi_enable_monitoring_mode
00436        and expect to receive the Wi-Fi packets through this callback function, when the event is received.
00437     To disable the monitoring mode a call to @ref m2m_wifi_disable_monitoring_mode should be made.
00438 @param [in] pstrWifiRxPacket
00439                 Pointer to a structure holding the Wi-Fi packet header parameters.
00440 
00441 @param [in] pu8Payload
00442                 Pointer to the buffer holding the Wi-Fi packet payload information required by the application starting from the
00443                 defined OFFSET by the application (when calling m2m_wifi_enable_monitoring_mode).
00444                 Could hold a value of NULL, if the application does not need any data from the payload.
00445 
00446 @param [in] u16PayloadSize
00447                 The size of the payload in bytes.
00448                 
00449 @see
00450     m2m_wifi_enable_monitoring_mode,m2m_wifi_init   
00451     
00452 @warning
00453     u16PayloadSize should not exceed the buffer size given through m2m_wifi_enable_monitoring_mode.
00454     
00455 */
00456 typedef void (*tpfAppMonCb) (tstrM2MWifiRxPacketInfo *pstrWifiRxPacket, uint8 * pu8Payload, uint16 u16PayloadSize);
00457 
00458 /**
00459 @struct     \
00460     tstrEthInitParam
00461     
00462 @brief      
00463     Structure to hold Ethernet interface parameters. 
00464     Structure is to be defined and have its attributes set,based on the application's functionality before 
00465     a call is made to  initialize the Wi-Fi operations by calling the  @ref m2m_wifi_init function.
00466     This structure is part of the Wi-Fi configuration structure @ref tstrWifiInitParam.
00467     Applications shouldn't need to define this structure, if the bypass mode is not defined.
00468     
00469 @see
00470     tpfAppEthCb
00471     tpfAppWifiCb
00472     m2m_wifi_init
00473 
00474 @warning
00475     Make sure that application defines @ref ETH_MODE before using @ref tstrEthInitParam. 
00476 
00477 */
00478 typedef struct {
00479     tpfAppWifiCb pfAppWifiCb;
00480     /*!<
00481         Callback for wifi notifications.
00482     */
00483     tpfAppEthCb  pfAppEthCb;
00484     /*!<
00485         Callback for Ethernet interface.
00486     */
00487     uint8 * au8ethRcvBuf;
00488     /*!<
00489         Pointer to Receive Buffer of Ethernet Packet
00490     */
00491     uint16 u16ethRcvBufSize;
00492     /*!<
00493         Size of Receive Buffer for Ethernet Packet
00494     */
00495     uint8 u8EthernetEnable;
00496     /*!<
00497         Enable Ethernet mode flag
00498     */
00499     uint8 __PAD8__;
00500     /*!<
00501         Padding
00502     */
00503 } tstrEthInitParam;
00504 /*!
00505 @struct \
00506     tstrM2mIpCtrlBuf
00507     
00508 @brief      
00509     Structure holding the incoming buffer's data size information, indicating the data size of the buffer and the remaining buffer's data size .
00510     The data of the buffer which holds the packet sent to the host when in the bypass mode, is placed in the @ref tstrEthInitParam structure in the 
00511     @ref au8ethRcvBuf attribute. This following information is retrieved in the host when an event @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET is received in 
00512     the Wi-Fi callback function @ref tpfAppWifiCb. 
00513 
00514     The application is expected to use this structure's information to determine if there is still incoming data to be received from the firmware.
00515     
00516  @see
00517      tpfAppEthCb
00518      tstrEthInitParam
00519  
00520  @warning
00521      Make sure that ETHERNET/bypass mode is defined before using @ref tstrM2mIpCtrlBuf
00522 
00523  */
00524 typedef struct{
00525     uint16  u16DataSize;
00526     /*!<
00527         Size of the received data in bytes.
00528     */
00529     uint16  u16RemainigDataSize;
00530     /*!<
00531         Size of the remaining data bytes to be delivered to host.
00532     */
00533 } tstrM2mIpCtrlBuf;
00534 
00535 
00536 /**
00537 @struct     \
00538     tstrWifiInitParam
00539 
00540 @brief      
00541     Structure, holding the Wi-fi configuration attributes such as the wi-fi callback , monitoring mode callback and Ethernet parameter initialization structure.
00542     Such configuration parameters are required to be set before calling the wi-fi initialization function @ref m2m_wifi_init.
00543     @ref pfAppWifiCb attribute must be set to handle the wi-fi callback operations.
00544     @ref pfAppMonCb attribute, is optional based on whether the application requires the monitoring mode configuration, and can there not
00545     be set before the initialization.
00546     @ref strEthInitParam structure, is another optional configuration based on whether the bypass mode is set.
00547 
00548  @see
00549      tpfAppEthCb
00550      tpfAppMonCb
00551      tstrEthInitParam
00552     
00553 */
00554 typedef struct {
00555     tpfAppWifiCb pfAppWifiCb;
00556     /*!<
00557         Callback for Wi-Fi notifications.
00558     */
00559     tpfAppMonCb  pfAppMonCb;
00560     /*!<
00561         Callback for monitoring interface.
00562     */
00563     tstrEthInitParam strEthInitParam ;
00564     /*!<
00565         Structure to hold Ethernet interface parameters.
00566     */
00567 
00568 } tstrWifiInitParam;
00569  //@}
00570 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00571 FUNCTION PROTOTYPES
00572 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00573 /** \defgroup WLANAPI Function
00574  *   @ingroup m2m_wifi
00575  */
00576 #ifdef __cplusplus
00577      extern "C" {
00578 #endif
00579  /** @defgroup WiFiDownloadFn m2m_wifi_download_mode
00580  *  @ingroup WLANAPI
00581  *      Synchronous download mode entry function that prepares the WINC board to enter the download mode, ready for the firmware or certificate download.
00582 *   The WINC board is prepared for download, through initializations for the WINC driver including bus initializations and interrupt enabling, it also halts the chip, to allow for the firmware downloads.
00583 *   Firmware can be downloaded through a number of interfaces, UART, I2C and SPI.
00584  */
00585  /**@{*/
00586 /*!
00587 @fn \
00588     NMI_API void  m2m_wifi_download_mode(void);
00589 @brief  Prepares the WINC broard before downloading any data (Firmware, Certificates .. etc)
00590 
00591         This function should called before starting to download any data to the WINC board. The WINC board is prepared for download, through initializations for the WINC driver including bus initializations 
00592         and interrupt enabling, it also halts the chip, to allow for the firmware downloads Firmware can be downloaded through a number of interfaces, UART, I2C and SPI.
00593 
00594 @return     
00595     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00596 */
00597 NMI_API sint8  m2m_wifi_download_mode(void);
00598 
00599  /**@}*/
00600  /** @defgroup WifiInitFn m2m_wifi_init
00601  *  @ingroup WLANAPI
00602  *  Synchronous initialization function for the WINC driver. This function initializes the driver by, registering the call back function for M2M_WIFI layer(also the call back function for bypass mode/monitoring mode if defined), 
00603  *  initializing the host interface layer and the bus interfaces. 
00604  *  Wi-Fi callback registering is essential to allow the handling of the events received, in response to the asynchronous Wi-Fi operations. 
00605 
00606 Following are the possible Wi-Fi events that are expected to be received through the call back function(provided by the application) to the M2M_WIFI layer are : 
00607 
00608         @ref M2M_WIFI_RESP_CON_STATE_CHANGED \n
00609         @ref M2M_WIFI_RESP_CONN_INFO \n
00610         @ref M2M_WIFI_REQ_DHCP_CONF \n
00611         @ref M2M_WIFI_REQ_WPS \n
00612         @ref M2M_WIFI_RESP_IP_CONFLICT \n 
00613         @ref M2M_WIFI_RESP_SCAN_DONE \n
00614         @ref M2M_WIFI_RESP_SCAN_RESULT \n
00615         @ref M2M_WIFI_RESP_CURRENT_RSSI \n
00616         @ref M2M_WIFI_RESP_CLIENT_INFO \n
00617         @ref M2M_WIFI_RESP_PROVISION_INFO  \n
00618         @ref M2M_WIFI_RESP_DEFAULT_CONNECT \n
00619     Example: \n
00620     In case Bypass mode is defined : \n
00621         @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET
00622         
00623     In case Monitoring mode is used: \n
00624         @ref M2M_WIFI_RESP_WIFI_RX_PACKET
00625         
00626     Any application using the WINC driver must call this function at the start of its main function.
00627  */
00628  /**@{*/
00629 /*!
00630 @fn \
00631     NMI_API sint8  m2m_wifi_init(tstrWifiInitParam * pWifiInitParam);
00632 
00633 @param [in] pWifiInitParam
00634     This is a pointer to the @ref tstrWifiInitParam structure which holds the pointer to the application WIFI layer call back function,
00635     monitoring mode call back and @ref tstrEthInitParam structure containing bypass mode parameters.
00636 
00637 @brief Initialize the WINC host driver.
00638       This function initializes the driver by, registering the call back function for M2M_WIFI layer(also the call back function for bypass mode/monitoring mode if defined), 
00639       initializing the host interface layer and the bus interfaces. 
00640  
00641 @pre 
00642     Prior to this function call, The application should initialize the BSP using "nm_bsp_init". 
00643     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.
00644     
00645 @warning
00646     Failure to successfully complete function indicates that the driver couldn't be initialized and a fatal error will prevent the application from proceeding. 
00647     
00648 @see
00649     nm_bsp_init
00650     m2m_wifi_deinit
00651     tenuM2mStaCmd
00652 
00653 @return     
00654     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00655 */
00656 NMI_API sint8  m2m_wifi_init(tstrWifiInitParam * pWifiInitParam);
00657  /**@}*/
00658  /** @defgroup WifiDeinitFn m2m_wifi_deinit
00659  *  @ingroup WLANAPI
00660  *   Synchronous de-initialization function to the WINC1500 driver. De-initializes the host interface and frees any resources used by the M2M_WIFI layer. 
00661  *   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. 
00662  */
00663 /**@{*/
00664 /*!
00665 @fn \
00666     NMI_API sint8  m2m_wifi_deinit(void * arg);
00667     
00668 @param [in] arg
00669         Generic argument. Not used in the current implementation.
00670 @brief  Deinitilize the WINC driver and host enterface. 
00671         This function must be called at the De-initilization stage of the application. Generally This function should be the last function before switching off the chip
00672         and it should be followed only by "nm_bsp_deinit" function call. Every function call of "nm_wifi_init" should be matched with a call to nm_wifi_deinit.
00673 @see
00674     nm_bsp_deinit
00675     nm_wifi_init
00676     
00677 @return     
00678     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00679 */
00680 NMI_API sint8  m2m_wifi_deinit(void * arg);
00681 
00682  /**@}*/
00683 /** @defgroup WifiHandleEventsFn m2m_wifi_handle_events
00684 *  @ingroup WLANAPI
00685 *   Synchronous M2M event handler function, responsible for handling interrupts received from the WINC firmware.
00686 *     Application developers should call this function periodically in-order to receive the events that are to be handled by the
00687 *     callback functions implemented by the application.
00688 
00689  */
00690  /**@{*/
00691 /*!
00692 @fn \
00693     NMI_API sint8 m2m_wifi_handle_events(void * arg);
00694 
00695 @pre
00696     Prior to receiving events, the WINC driver should have been successfully initialized by calling the @ref m2m_wifi_init function.
00697 
00698 @brief  Handle the varios events received from the WINC board.
00699         Whenever an event happen in the WINC board (e.g. Connection, Disconnection , DHCP .. etc), WINC will interrupt the host to let it know that a new 
00700         event has occured. The host driver will attempt to handle these events whenever the host driver decides to do that by calling the "m2m_wifi_handle_events" function.
00701         It's mandatory to call this function periodically and independantly of any other condition. It's ideal to include this function in the main and the most frequent loop of the 
00702         host application.
00703 @warning
00704     Failure to successfully complete this function indicates bus errors and hence a fatal error that will prevent the application from proceeding.
00705 
00706 @return     
00707     The function returns @ref M2M_SUCCESS for successful interrupt handling and a negative value otherwise.
00708 */
00709 
00710 NMI_API sint8 m2m_wifi_handle_events(void * arg);
00711 
00712  /**@}*/
00713 /** @defgroup WifiSendCRLFn m2m_wifi_send_crl
00714 *  @ingroup WLANAPI
00715 *   Asynchronous API that notifies the WINC with the Certificate Revocation List to be used for TLS.
00716 
00717  */
00718  /**@{*/
00719 /*!
00720 @fn \
00721     sint8 m2m_wifi_send_crl(tstrTlsCrlInfo* pCRL);
00722 
00723 @brief
00724     Asynchronous API that notifies the WINC with the Certificate Revocation List.
00725 
00726 @param [in] pCRL
00727     Pointer to the structure containing certificate revocation list details.
00728 
00729 @return
00730     The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC, 
00731     and a negative value otherwise.
00732 */
00733 
00734 sint8 m2m_wifi_send_crl(tstrTlsCrlInfo* pCRL);
00735 
00736  /**@}*/
00737 /** @defgroup WifiDefaultConnectFn m2m_wifi_default_connect
00738  *  @ingroup WLANAPI
00739  *   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. 
00740  *   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.
00741  *   Possible errors are: 
00742  *   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.
00743  *    only difference between this function and @ref m2m_wifi_connect, is the connection parameters. 
00744  *   Connection using this function is expected to connect using cached connection parameters. 
00745 
00746  */
00747  /**@{*/
00748 /*!
00749 @fn \
00750     NMI_API sint8 m2m_wifi_default_connect(void);
00751 
00752 @pre 
00753     Prior to connecting, the WINC driver should have been successfully initialized by calling the @ref m2m_wifi_init function.
00754 
00755 @brief  Connect to the last successfully connected AP from the cached connections. 
00756 
00757 @warning
00758  This function must be called in station mode only.
00759  It's important to note that successful completion of a call to m2m_wifi_default_connect() does not guarantee success of the WIFI connection, 
00760  and a negative return value indicates only locally-detected errors.
00761     
00762 @see
00763     m2m_wifi_connect
00764     
00765 @return     
00766     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00767 
00768 */
00769 NMI_API sint8 m2m_wifi_default_connect(void);
00770  /**@}*/
00771 /** @defgroup WifiConnectFn m2m_wifi_connect
00772  *   @ingroup WLANAPI
00773  *   Asynchronous wi-fi connection function to a specific AP. Prior to a successful connection, the application must define the SSID of the AP, the security type,
00774  *   the authentication information parameters and the channel number to which the connection will be established.
00775  *  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,
00776  *  successful connection is defined by @ref M2M_WIFI_CONNECTED
00777 *   
00778  *   The only difference between this function and @ref m2m_wifi_default_connect, is the connection parameters. 
00779  *   Connection using this function is expected to be made to a specific AP and to a specified channel.
00780  */
00781  /**@{*/
00782 /*!
00783 @fn \
00784     NMI_API sint8 m2m_wifi_connect(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch);
00785 
00786 @param [in] pcSsid
00787                 A buffer holding the SSID corresponding to the requested AP.
00788                 
00789 @param [in] u8SsidLen
00790                 Length of the given SSID (not including the NULL termination).
00791                 A length less than ZERO or greater than the maximum defined SSID @ref M2M_MAX_SSID_LEN will result in a negative error 
00792                 @ref M2M_ERR_FAIL.
00793                 
00794 @param [in] u8SecType
00795                 Wi-Fi security type security for the network. It can be one of the following types:
00796                 -@ref M2M_WIFI_SEC_OPEN
00797                 -@ref M2M_WIFI_SEC_WEP
00798                 -@ref M2M_WIFI_SEC_WPA_PSK
00799                 -@ref M2M_WIFI_SEC_802_1X
00800                 A value outside these possible values will result in a negative return error @ref M2M_ERR_FAIL.
00801 
00802 @param [in] pvAuthInfo
00803                 Authentication parameters required for completing the connection. It is type is based on the Security type.
00804                 If the authentication parameters are NULL or are greater than the maximum length of the authentication parameters length as defined by
00805                 @ref M2M_MAX_PSK_LEN a negative error will return @ref M2M_ERR_FAIL(-12) indicating connection failure.
00806 
00807 @param [in] u16Ch
00808                 Wi-Fi channel number as defined in @ref tenuM2mScanCh enumeration.
00809                 Channel number greater than @ref M2M_WIFI_CH_14 returns a negative error @ref M2M_ERR_FAIL(-12).
00810                 Except if the value is M2M_WIFI_CH_ALL(255), since this indicates that the firmware should scan all channels to find the SSID requested to connect to.
00811                 Failure to find the connection match will return a negative error @ref M2M_DEFAULT_CONN_SCAN_MISMATCH.
00812 @pre
00813         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
00814 @see
00815     tuniM2MWifiAuth
00816     tstr1xAuthCredentials
00817     tstrM2mWifiWepParams
00818     
00819 @warning
00820     -This function must be called in station mode only.
00821     -Successful completion of this function does not guarantee success of the WIFI connection, and
00822     a negative return value indicates only locally-detected errors.
00823     
00824 @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00825     
00826 */
00827 NMI_API sint8 m2m_wifi_connect(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch);
00828  /**@}*/
00829 /** @defgroup WifiConnectFn m2m_wifi_connect_sc
00830  *   @ingroup WLANAPI
00831  *   Asynchronous wi-fi connection function to a specific AP. Prior to a successful connection, the application developers must know the SSID of the AP, the security type,
00832  *   the authentication information parameters and the channel number to which the connection will be established.this API allows the user to choose
00833  *   whether to
00834  *  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,
00835  *  successful connection is defined by @ref M2M_WIFI_CONNECTED
00836  *   The only difference between this function and @ref m2m_wifi_connect, is the option to save the acess point info ( SSID, password...etc) or not.
00837  *   Connection using this function is expected to be made to a specific AP and to a specified channel.
00838  */
00839  /**@{*/
00840 /*!
00841 @fn \
00842     NMI_API sint8 m2m_wifi_connect_sc(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch,uint8 u8SaveCred);
00843 
00844 @param [in] pcSsid
00845                 A buffer holding the SSID corresponding to the requested AP.
00846                 
00847 @param [in] u8SsidLen
00848                 Length of the given SSID (not including the NULL termination).
00849                 A length less than ZERO or greater than the maximum defined SSID @ref M2M_MAX_SSID_LEN will result in a negative error 
00850                 @ref M2M_ERR_FAIL.
00851                 
00852 @param [in] u8SecType
00853                 Wi-Fi security type security for the network. It can be one of the following types:
00854                 -@ref M2M_WIFI_SEC_OPEN
00855                 -@ref M2M_WIFI_SEC_WEP
00856                 -@ref M2M_WIFI_SEC_WPA_PSK
00857                 -@ref M2M_WIFI_SEC_802_1X
00858                 A value outside these possible values will result in a negative return error @ref M2M_ERR_FAIL.
00859 
00860 @param [in] pvAuthInfo
00861                 Authentication parameters required for completing the connection. It is type is based on the Security type.
00862                 If the authentication parameters are NULL or are greater than the maximum length of the authentication parameters length as defined by
00863                 @ref M2M_MAX_PSK_LEN a negative error will return @ref M2M_ERR_FAIL(-12) indicating connection failure.
00864 
00865 @param [in] u16Ch
00866                 Wi-Fi channel number as defined in @ref tenuM2mScanCh enumeration.
00867                 Channel number greater than @ref M2M_WIFI_CH_14 returns a negative error @ref M2M_ERR_FAIL(-12).
00868                 Except if the value is M2M_WIFI_CH_ALL(255), since this indicates that the firmware should scan all channels to find the SSID requested to connect to.
00869                 Failure to find the connection match will return a negative error @ref M2M_DEFAULT_CONN_SCAN_MISMATCH.
00870                 
00871 @param [in] u8NoSaveCred
00872                 Option to store the acess point SSID and password into the WINC flash memory or not.
00873                 
00874 @pre
00875         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
00876 @see
00877     tuniM2MWifiAuth
00878     tstr1xAuthCredentials
00879     tstrM2mWifiWepParams
00880     
00881 @warning
00882     -This function must be called in station mode only.
00883     -Successful completion of this function does not guarantee success of the WIFI connection, and
00884     a negative return value indicates only locally-detected errors.
00885     
00886 @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00887     
00888 */
00889  NMI_API sint8 m2m_wifi_connect_sc(char *pcSsid, uint8 u8SsidLen, uint8 u8SecType, void *pvAuthInfo, uint16 u16Ch, uint8 u8SaveCred);
00890  /**@}*/
00891 /** @defgroup WifiDisconnectFn m2m_wifi_disconnect
00892  *   @ingroup WLANAPI
00893  *   Synchronous wi-fi disconnection function, requesting a Wi-Fi disconnection from the currently connected AP.
00894  */
00895  /**@{*/
00896 /*!
00897 @fn \
00898     NMI_API sint8 m2m_wifi_disconnect(void);
00899     
00900 @pre 
00901     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.
00902 
00903 @brief  Request a Wi-Fi disconnect from the currently connected AP.
00904         After the Disconnect is complete the driver should recieve a response of @ref M2M_WIFI_RESP_CON_STATE_CHANGED based on the states defined
00905         in @ref tenuM2mConnState, successful disconnection is defined by @ref M2M_WIFI_DISCONNECTED .
00906 @warning
00907     This function must be called in station mode only.
00908     
00909 @see
00910     m2m_wifi_connect
00911     m2m_wifi_default_connect
00912     
00913 @return     
00914     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00915 */
00916 NMI_API sint8 m2m_wifi_disconnect(void);
00917  
00918  /**@}*/
00919 /** @defgroup StartProvisionModeFn m2m_wifi_start_provision_mode
00920  *   @ingroup WLANAPI
00921  *    Asynchronous Wi-Fi provisioning function, which starts the WINC HTTP PROVISIONING mode.
00922     The function triggers the WINC to activate the Wi-Fi AP (HOTSPOT) mode with the passed configuration parameters and then starts the
00923     HTTP Provision WEB Server. 
00924     The provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO
00925  */
00926  /**@{*/
00927 /*!
00928 @fn \
00929     NMI_API sint8 m2m_wifi_start_provision_mode(tstrM2MAPConfig *pstrAPConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect);
00930     
00931 @param [in] pstrAPConfig
00932                 AP configuration parameters as defined in @ref tstrM2MAPConfig configuration structure.
00933                 A NULL value passed in, will result in a negative error @ref M2M_ERR_FAIL.
00934                 
00935 @param [in] pcHttpServerDomainName
00936                 Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page.
00937                 The domain name can have one of the following 3 forms:
00938                 1- "wincprov.com"
00939                 2- "http://wincprov.com"
00940                 3- "https://wincprov.com"
00941                 The forms 1 and 2 are equivalent, they both will start a plain http server, while form 3
00942                 will start a secure HTTP provisioning Session (HTTP over SSL connection).
00943 
00944 @param [in] bEnableHttpRedirect
00945                 A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server
00946                 domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS).
00947                 Possible values are:
00948                 - ZERO              DO NOT Use HTTP Redirect. In this case the associated device could open the provisioning page ONLY when
00949                                     the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser.
00950                 - Non-Zero value    Use HTTP Redirect. In this case, all http traffic (http://URL) from the associated
00951                                     device (Phone, PC, ...etc) will be redirected to the WINC HTTP Provisioning Home page.
00952 
00953 @pre    
00954     - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback
00955       is done through passing it to the initialization @ref m2m_wifi_init function.
00956     - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.
00957     
00958 @see
00959     tpfAppWifiCb
00960     m2m_wifi_init
00961     M2M_WIFI_RESP_PROVISION_INFO
00962     m2m_wifi_stop_provision_mode
00963     tstrM2MAPConfig
00964 
00965 @warning
00966         DO Not use ".local" in the pcHttpServerDomainName.
00967         
00968 @return
00969     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00970 
00971 \section Example
00972   The example demonstrates a code snippet for how provisioning is triggered and the response event received accordingly. 
00973 @code
00974     #include "m2m_wifi.h"
00975     #include "m2m_types.h"
00976 
00977 
00978     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
00979     {
00980         switch(u8WiFiEvent)
00981         {
00982         case M2M_WIFI_RESP_PROVISION_INFO:
00983             {
00984                 tstrM2MProvisionInfo    *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg;
00985                 if(pstrProvInfo->u8Status == M2M_SUCCESS)
00986                 {
00987                     m2m_wifi_connect((char*)pstrProvInfo->au8SSID, (uint8)strlen(pstrProvInfo->au8SSID), pstrProvInfo->u8SecType, 
00988                             pstrProvInfo->au8Password, M2M_WIFI_CH_ALL);
00989 
00990                     printf("PROV SSID : %s\n",pstrProvInfo->au8SSID);
00991                     printf("PROV PSK  : %s\n",pstrProvInfo->au8Password);
00992                 }
00993                 else
00994                 {
00995                     printf("(ERR) Provisioning Failed\n");
00996                 }
00997             }
00998             break;
00999 
01000             default:
01001             break;
01002         }
01003     }
01004 
01005     int main()
01006     {
01007         tstrWifiInitParam   param;
01008         
01009         param.pfAppWifiCb   = wifi_event_cb;
01010         if(!m2m_wifi_init(&param))
01011         {
01012             tstrM2MAPConfig     apConfig;
01013             uint8               bEnableRedirect = 1;
01014             
01015             strcpy(apConfig.au8SSID, "WINC_SSID");
01016             apConfig.u8ListenChannel    = 1;
01017             apConfig.u8SecType          = M2M_WIFI_SEC_OPEN;
01018             apConfig.u8SsidHide         = 0;
01019             
01020             // IP Address
01021             apConfig.au8DHCPServerIP[0] = 192;
01022             apConfig.au8DHCPServerIP[1] = 168;
01023             apConfig.au8DHCPServerIP[2] = 1;
01024             apConfig.au8DHCPServerIP[0] = 1;
01025 
01026             m2m_wifi_start_provision_mode(&apConfig, "atmelwincconf.com", bEnableRedirect);
01027                         
01028             while(1)
01029             {
01030                 m2m_wifi_handle_events(NULL);
01031             }
01032         }
01033     }
01034     
01035 @endcode
01036 */
01037 NMI_API sint8 m2m_wifi_start_provision_mode(tstrM2MAPConfig *pstrAPConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect);
01038  /**@}*/
01039 /** @defgroup StopProvisioningModeFn m2m_wifi_stop_provision_mode
01040  *   @ingroup WLANAPI
01041  *  Synchronous provision termination function which stops the provision mode if it is active.
01042  */
01043  /**@{*/
01044 /*!
01045 @fn \
01046     sint8 m2m_wifi_stop_provision_mode(void);
01047 
01048 @pre
01049     An active provisioning session must be active before it is terminated through this function.
01050 @see
01051     m2m_wifi_start_provision_mode
01052     
01053 @return
01054     The function returns ZERO for success and a negative value otherwise.
01055 */
01056 NMI_API sint8 m2m_wifi_stop_provision_mode(void);
01057  /**@}*/
01058 /** @defgroup GetConnectionInfoFn m2m_wifi_get_connection_info
01059  *   @ingroup WLANAPI
01060  *  Asynchronous connection status retrieval function, retrieves the status information of the currently connected AP. The result is passed to the Wi-Fi notification callback
01061 *    through the event @ref M2M_WIFI_RESP_CONN_INFO. Connection information is retrieved from the structure @ref tstrM2MConnInfo.
01062  */
01063  /**@{*/
01064 /*!
01065 @fn \
01066     sint8 m2m_wifi_get_connection_info(void);
01067 
01068 @brief
01069     Retrieve the current Connection information. The result is passed to the Wi-Fi notification callback
01070     with [M2M_WIFI_RESP_CONN_INFO](@ref M2M_WIFI_RESP_CONN_INFO).
01071 @pre    
01072     - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback
01073     is done through passing it to the initialization @ref m2m_wifi_init function.
01074     - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.
01075     
01076     Connection Information retrieved:
01077 
01078     
01079     -Connection Security
01080     -Connection RSSI
01081     -Remote MAC address
01082     -Remote IP address
01083 
01084     and in case of WINC station mode the SSID of the AP is also retrieved.
01085 @warning
01086     -In case of WINC AP mode or P2P mode, ignore the SSID field (NULL string).
01087 @sa
01088     M2M_WIFI_RESP_CONN_INFO,
01089     tstrM2MConnInfo
01090 @return
01091     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01092 \section Example
01093   The code snippet shows an example of how wi-fi connection information is retrieved .
01094 @code
01095 
01096     #include "m2m_wifi.h"
01097     #include "m2m_types.h"
01098 
01099 
01100     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
01101     {
01102         switch(u8WiFiEvent)
01103         {
01104         case M2M_WIFI_RESP_CONN_INFO:
01105             {
01106                 tstrM2MConnInfo     *pstrConnInfo = (tstrM2MConnInfo*)pvMsg;
01107                 
01108                 printf("CONNECTED AP INFO\n");
01109                 printf("SSID                : %s\n",pstrConnInfo->acSSID);
01110                 printf("SEC TYPE            : %d\n",pstrConnInfo->u8SecType);
01111                 printf("Signal Strength     : %d\n", pstrConnInfo->s8RSSI); 
01112                 printf("Local IP Address    : %d.%d.%d.%d\n", 
01113                     pstrConnInfo->au8IPAddr[0] , pstrConnInfo->au8IPAddr[1], pstrConnInfo->au8IPAddr[2], pstrConnInfo->au8IPAddr[3]);
01114             }
01115             break;
01116 
01117         case M2M_WIFI_REQ_DHCP_CONF:
01118             {
01119                 // Get the current AP information.
01120                 m2m_wifi_get_connection_info();
01121             }
01122             break;
01123         default:
01124             break;
01125         }
01126     }
01127 
01128     int main()
01129     {
01130         tstrWifiInitParam   param;
01131         
01132         param.pfAppWifiCb   = wifi_event_cb;
01133         if(!m2m_wifi_init(&param))
01134         {
01135             // connect to the default AP
01136             m2m_wifi_default_connect();
01137                         
01138             while(1)
01139             {
01140                 m2m_wifi_handle_events(NULL);
01141             }
01142         }
01143     }
01144     
01145 @endcode
01146 */
01147 NMI_API sint8 m2m_wifi_get_connection_info(void);
01148  /**@}*/
01149 /** @defgroup WifiSetMacAddFn m2m_wifi_set_mac_address
01150  *   @ingroup WLANAPI
01151  *  Synchronous MAC address assigning to the NMC1500. It is used for non-production SW. Assign MAC address to the WINC device. 
01152  */
01153  /**@{*/
01154 /*!
01155 @fn \
01156     NMI_API sint8 m2m_wifi_set_mac_address(uint8 au8MacAddress[6]);
01157 
01158 @brief  Assign a MAC address to the WINC board.
01159         This function override the already assigned MAC address of the WINC board with a user provided one. This is for experimental 
01160         use only and should never be used in the production SW.
01161 
01162 @param [in] au8MacAddress
01163                 MAC Address to be set to the WINC.
01164 
01165 @return     
01166     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01167 */
01168 NMI_API sint8 m2m_wifi_set_mac_address(uint8 au8MacAddress[6]);
01169  
01170  /**@}*/
01171 /** @defgroup WifiWpsFn m2m_wifi_wps
01172  *   @ingroup WLANAPI
01173  *   Asynchronous WPS triggering function.
01174  *   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
01175 *   with the event @ref M2M_WIFI_REQ_WPS.
01176  */
01177  /**@{*/
01178 /*!
01179 @fn \
01180     NMI_API sint8 m2m_wifi_wps(uint8 u8TriggerType,const char * pcPinNumber);
01181 
01182 @param [in] u8TriggerType
01183                 WPS Trigger method. Could be:
01184                 - [WPS_PIN_TRIGGER](@ref WPS_PIN_TRIGGER)   Push button method
01185                 - [WPS_PBC_TRIGGER](@ref WPS_PBC_TRIGGER)   Pin method
01186                 
01187 @param [in] pcPinNumber
01188                 PIN number for WPS PIN method. It is not used if the trigger type is WPS_PBC_TRIGGER. It must follow the rules
01189                 stated by the WPS standard.
01190 
01191 @warning
01192     This function is not allowed in AP or P2P modes.
01193     
01194 @pre    
01195     - A Wi-Fi notification callback of type (@ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback
01196       is done through passing it to the [m2m_wifi_init](@ref m2m_wifi_init).
01197     - The event [M2M_WIFI_REQ_WPS](@ref M2M_WIFI_REQ_WPS) must be handled in the callback to receive the WPS status.
01198     - The WINC device MUST be in IDLE or STA mode. If AP or P2P mode is active, the WPS will not be performed. 
01199     - The [m2m_wifi_handle_events](@ref m2m_wifi_handle_events) MUST be called periodically to receive the responses in the callback.
01200 @see
01201     tpfAppWifiCb
01202     m2m_wifi_init
01203     M2M_WIFI_REQ_WPS
01204     tenuWPSTrigger
01205     tstrM2MWPSInfo
01206 
01207 @return
01208     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01209 \section Example
01210   The code snippet shows an example of how Wi-Fi WPS is triggered .
01211 @code
01212 
01213     #include "m2m_wifi.h"
01214     #include "m2m_types.h"
01215 
01216     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
01217     {
01218         switch(u8WiFiEvent)
01219         {
01220         case M2M_WIFI_REQ_WPS:
01221             {
01222                 tstrM2MWPSInfo  *pstrWPS = (tstrM2MWPSInfo*)pvMsg;
01223                 if(pstrWPS->u8AuthType != 0)
01224                 {
01225                     printf("WPS SSID           : %s\n",pstrWPS->au8SSID);
01226                     printf("WPS PSK            : %s\n",pstrWPS->au8PSK);
01227                     printf("WPS SSID Auth Type : %s\n",pstrWPS->u8AuthType == M2M_WIFI_SEC_OPEN ? "OPEN" : "WPA/WPA2");
01228                     printf("WPS Channel        : %d\n",pstrWPS->u8Ch + 1);
01229                     
01230                     // establish Wi-Fi connection
01231                     m2m_wifi_connect((char*)pstrWPS->au8SSID, (uint8)m2m_strlen(pstrWPS->au8SSID),
01232                         pstrWPS->u8AuthType, pstrWPS->au8PSK, pstrWPS->u8Ch);
01233                 }
01234                 else
01235                 {
01236                     printf("(ERR) WPS Is not enabled OR Timed out\n");
01237                 }
01238             }
01239             break;
01240             
01241         default:
01242             break;
01243         }
01244     }
01245 
01246     int main()
01247     {
01248         tstrWifiInitParam   param;
01249         
01250         param.pfAppWifiCb   = wifi_event_cb;
01251         if(!m2m_wifi_init(&param))
01252         {
01253             // Trigger WPS in Push button mode.
01254             m2m_wifi_wps(WPS_PBC_TRIGGER, NULL);
01255             
01256             while(1)
01257             {
01258                 m2m_wifi_handle_events(NULL);
01259             }
01260         }
01261     }
01262     
01263 @endcode
01264 */
01265 NMI_API sint8 m2m_wifi_wps(uint8 u8TriggerType,const char  *pcPinNumber);
01266  /**@}*/
01267 /** @defgroup WifiWpsDisableFn m2m_wifi_wps_disable
01268  *   @ingroup WLANAPI
01269  * Disable the WINC1500 WPS operation.
01270  */
01271  /**@{*/
01272 /*!
01273 @fn \
01274     NMI_API sint8 m2m_wifi_wps_disable(void);
01275 
01276 @pre    WINC should be already in WPS mode using @ref m2m_wifi_wps 
01277 
01278 @brief  Stops the WPS ongoing session.
01279 
01280 @see 
01281     m2m_wifi_wps
01282     
01283 @return
01284     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01285 */
01286 NMI_API sint8 m2m_wifi_wps_disable(void);
01287  
01288  /**@}*/
01289 /** @defgroup WifiP2PFn m2m_wifi_p2p
01290  *   @ingroup WLANAPI
01291  *    Asynchronous  Wi-Fi direct (P2P) enabling mode function.
01292     The WINC supports P2P in device listening mode ONLY (intent is ZERO).
01293     The WINC P2P implementation does not support P2P GO (Group Owner) mode.
01294     Active P2P devices (e.g. phones) could find the WINC in the search list. When a device is connected to WINC, a Wi-Fi notification event
01295     @ref M2M_WIFI_RESP_CON_STATE_CHANGED is triggered. After a short while, the DHCP IP Address is obtained 
01296     and an event @ref M2M_WIFI_REQ_DHCP_CONF is triggered. Refer to the code examples for a more illustrative example.
01297  */
01298  /**@{*/
01299 /*!
01300 @fn \
01301     NMI_API sint8 m2m_wifi_p2p(uint8 u8Channel);
01302 
01303 @param [in] u8Channel
01304                 P2P Listen RF channel. According to the P2P standard It must hold only one of the following values 1, 6 or 11.
01305 
01306 @pre
01307     - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
01308       is done through passing it to the @ref m2m_wifi_init.
01309     - The events @ref M2M_WIFI_RESP_CON_STATE_CHANGED and @ref M2M_WIFI_REQ_DHCP_CONF 
01310       must be handled in the callback.
01311     - The @ref m2m_wifi_handle_events MUST be called to receive the responses in the callback.
01312 
01313 @warning
01314     This function is not allowed in AP or STA modes.
01315 
01316 @see
01317     tpfAppWifiCb
01318     m2m_wifi_init
01319     M2M_WIFI_RESP_CON_STATE_CHANGED
01320     M2M_WIFI_REQ_DHCP_CONF
01321     tstrM2mWifiStateChanged
01322 
01323 @return
01324     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01325 \section Example
01326   The code snippet shown an example of how the p2p mode operates.
01327 @code
01328     #include "m2m_wifi.h"
01329     #include "m2m_types.h"
01330     
01331     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
01332     {
01333         switch(u8WiFiEvent)
01334         {
01335         case M2M_WIFI_RESP_CON_STATE_CHANGED:
01336             {
01337                 tstrM2mWifiStateChanged *pstrWifiState = (tstrM2mWifiStateChanged*)pvMsg;
01338                 M2M_INFO("Wifi State :: %s :: ErrCode %d\n", pstrWifiState->u8CurrState? "CONNECTED":"DISCONNECTED",pstrWifiState->u8ErrCode);
01339                 
01340                 // Do something
01341             }
01342             break;
01343             
01344         case M2M_WIFI_REQ_DHCP_CONF:
01345             {
01346                 uint8   *pu8IPAddress = (uint8*)pvMsg;
01347 
01348                 printf("P2P IP Address \"%u.%u.%u.%u\"\n",pu8IPAddress[0],pu8IPAddress[1],pu8IPAddress[2],pu8IPAddress[3]);
01349             }
01350             break;
01351             
01352         default:
01353             break;
01354         }
01355     }
01356     
01357     int main()
01358     {
01359         tstrWifiInitParam   param;
01360         
01361         param.pfAppWifiCb   = wifi_event_cb;
01362         if(!m2m_wifi_init(&param))
01363         {
01364             // Trigger P2P
01365             m2m_wifi_p2p(M2M_WIFI_CH_1);
01366             
01367             while(1)
01368             {
01369                 m2m_wifi_handle_events(NULL);
01370             }
01371         }
01372     }
01373     
01374 @endcode
01375 
01376 */
01377 NMI_API sint8 m2m_wifi_p2p(uint8 u8Channel);
01378  /**@}*/
01379 /** @defgroup WifiP2PDisconnectFn m2m_wifi_p2p_disconnect
01380  *   @ingroup WLANAPI
01381  * Disable the WINC1500 device Wi-Fi direct mode (P2P). 
01382  */
01383  /**@{*/
01384 /*!
01385 @fn \
01386     NMI_API sint8 m2m_wifi_p2p_disconnect(void);
01387 @pre 
01388     The p2p mode must have be enabled and active before a disconnect can be called.
01389     
01390 @see
01391          m2m_wifi_p2p
01392 @return
01393     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01394 */
01395 NMI_API sint8 m2m_wifi_p2p_disconnect(void);
01396  /**@}*/
01397 /** @defgroup WifiEnableApFn m2m_wifi_enable_ap
01398  *   @ingroup WLANAPI
01399  *  Asynchronous Wi-FI hot-spot enabling function. 
01400  *    The WINC supports AP mode operation with the following limitations:
01401     - Only 1 STA could be associated at a time.
01402     - Open and WEP are the only supported security types
01403  */
01404  /**@{*/
01405 /*!
01406 @fn \
01407     NMI_API sint8 m2m_wifi_enable_ap(CONST tstrM2MAPConfig* pstrM2MAPConfig);
01408 
01409 @param [in] pstrM2MAPConfig
01410                 A structure holding the AP configurations.
01411 
01412 @warning
01413     This function is not allowed in P2P or STA modes.
01414     
01415 @pre
01416     - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
01417       is done through passing it to the [m2m_wifi_init](@ref m2m_wifi_init).
01418     - The event @ref M2M_WIFI_REQ_DHCP_CONF must be handled in the callback.
01419     - The @ref m2m_wifi_handle_events MUST be called to receive the responses in the callback.
01420 
01421 @see
01422     tpfAppWifiCb
01423     tenuM2mSecType
01424     m2m_wifi_init
01425     M2M_WIFI_REQ_DHCP_CONF
01426     tstrM2mWifiStateChanged
01427     tstrM2MAPConfig
01428 
01429 @return
01430     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01431 \section Example
01432   The code snippet demonstrates how the AP mode is enabled after the driver is initialized in the application's main function and the handling
01433   of the event @ref M2M_WIFI_REQ_DHCP_CONF, to indicate successful connection.
01434 @code
01435     #include "m2m_wifi.h"
01436     #include "m2m_types.h"
01437     
01438     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
01439     {
01440         switch(u8WiFiEvent)
01441         {
01442         case M2M_WIFI_REQ_DHCP_CONF:
01443             {
01444                 uint8   *pu8IPAddress = (uint8*)pvMsg;
01445 
01446                 printf("Associated STA has IP Address \"%u.%u.%u.%u\"\n",pu8IPAddress[0],pu8IPAddress[1],pu8IPAddress[2],pu8IPAddress[3]);
01447             }
01448             break;
01449             
01450         default:
01451             break;
01452         }
01453     }
01454     
01455     int main()
01456     {
01457         tstrWifiInitParam   param;
01458         
01459         param.pfAppWifiCb   = wifi_event_cb;
01460         if(!m2m_wifi_init(&param))
01461         {
01462             tstrM2MAPConfig     apConfig;
01463             
01464             strcpy(apConfig.au8SSID, "WINC_SSID");
01465             apConfig.u8ListenChannel    = 1;
01466             apConfig.u8SecType          = M2M_WIFI_SEC_OPEN;
01467             apConfig.u8SsidHide         = 0;
01468             
01469             // IP Address
01470             apConfig.au8DHCPServerIP[0] = 192;
01471             apConfig.au8DHCPServerIP[1] = 168;
01472             apConfig.au8DHCPServerIP[2] = 1;
01473             apConfig.au8DHCPServerIP[0] = 1;
01474             
01475             // Trigger AP
01476             m2m_wifi_enable_ap(&apConfig);
01477             
01478             while(1)
01479             {
01480                 m2m_wifi_handle_events(NULL);
01481             }
01482         }
01483     }
01484 
01485 @endcode
01486 
01487 */
01488 NMI_API sint8 m2m_wifi_enable_ap(CONST tstrM2MAPConfig* pstrM2MAPConfig);
01489  /**@}*/
01490 /** @defgroup WifiDisableApFn m2m_wifi_disable_ap
01491  *   @ingroup WLANAPI
01492  *    Synchronous Wi-Fi hot-spot disabling function. Must be called only when the AP is enabled through the @ref m2m_wifi_enable_ap
01493  *   function. Otherwise the call to this function will not be useful.
01494  */
01495  /**@{*/
01496 /*!
01497 @fn \
01498     NMI_API sint8 m2m_wifi_disable_ap(void);
01499 @see
01500          m2m_wifi_enable_ap
01501 @return
01502     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01503 */
01504 NMI_API sint8 m2m_wifi_disable_ap(void);
01505  /**@}*/
01506 /** @defgroup SetStaticIPFn m2m_wifi_set_static_ip
01507  *   @ingroup WLANAPI
01508  *   Synchronous static IP Address configuration function. 
01509  */
01510  /**@{*/
01511 /*!
01512 @fn \
01513     NMI_API sint8 m2m_wifi_set_static_ip(tstrM2MIPConfig * pstrStaticIPConf);
01514 
01515 @param [in] pstrStaticIPConf
01516                 Pointer to a structure holding the static IP Configurations (IP,
01517                 Gateway, subnet mask and DNS address).
01518 
01519 @pre    The application must disable auto DHCP using @ref m2m_wifi_enable_dhcp before assigning a static IP address. 
01520 
01521 @brief  Assign a static IP address to the WINC board.
01522         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 
01523         a predefined known IP address. The user must take in mind that assigning a static IP address might result in an IP address 
01524         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 
01525         in the wifi callback. The application is then responsible to either solve the conflict or assign another IP address. 
01526 @warning
01527     Normally this function normally should not be used. DHCP configuration is requested automatically after successful Wi-Fi connection is established.
01528     
01529 @see
01530     tstrM2MIPConfig
01531     
01532     
01533 @return
01534     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01535 */
01536 NMI_API sint8 m2m_wifi_set_static_ip(tstrM2MIPConfig * pstrStaticIPConf);
01537  
01538  /**@}*/
01539 /** @defgroup RequestDHCPClientFn m2m_wifi_request_dhcp_client
01540  *   @ingroup WLANAPI
01541  *  Starts the DHCP client operation(DHCP requested by the firmware automatically in STA/AP/P2P mode).
01542  *    
01543  */
01544  /**@{*/
01545 /*!
01546 @fn \
01547     NMI_API sint8 m2m_wifi_request_dhcp_client(void);
01548     
01549 @warning
01550     This function is legacy and exists only for compatability with older applications. DHCP configuration is requested automatically after successful Wi-Fi connection is established.
01551 
01552 @return
01553     The function returns @ref M2M_SUCCESS always.
01554 */
01555 NMI_API sint8 m2m_wifi_request_dhcp_client(void);
01556  /**@}*/
01557 /** @defgroup RequestDHCPServerFn m2m_wifi_request_dhcp_server
01558  *   @ingroup WLANAPI
01559  *   Dhcp requested by the firmware automatically in STA/AP/P2P mode).
01560  */
01561  /**@{*/
01562 /*!
01563 @fn \
01564     NMI_API sint8 m2m_wifi_request_dhcp_server(uint8* addr);
01565 
01566 @warning
01567     This function is legacy and exists only for compatability with older applications. DHCP server is started automatically when enabling the AP mode.
01568 
01569 
01570 @return
01571     The function returns @ref M2M_SUCCESS always.
01572 */
01573 NMI_API sint8 m2m_wifi_request_dhcp_server(uint8* addr);
01574  /**@}*/
01575 /** @defgroup WifiDHCPEnableFn m2m_wifi_enable_dhcp
01576  *   @ingroup WLANAPI
01577  *   Synchronous Wi-Fi DHCP enable function. This function Enable/Disable DHCP protocol.
01578  */
01579  /**@{*/
01580 /*!
01581 @fn \
01582     NMI_API  sint8 m2m_wifi_enable_dhcp(uint8  u8DhcpEn );
01583     
01584 @brief
01585     Enable/Disable the DHCP client after connection.
01586 
01587 @param [in]  u8DhcpEn 
01588                 Possible values:
01589                 1: Enable DHCP client after connection.
01590                 0: Disable DHCP client after connection.
01591 @warnings
01592     -DHCP client is enabled by default
01593     -This Function should be called before using m2m_wifi_set_static_ip()
01594 
01595     
01596 @sa
01597     m2m_wifi_set_static_ip()
01598     
01599 @return
01600     The function SHALL return @ref M2M_SUCCESS  for successful operation and a negative value otherwise.
01601 */
01602 NMI_API sint8 m2m_wifi_enable_dhcp(uint8  u8DhcpEn );
01603  /**@}*/
01604 /** @defgroup WifiSetScanOptionFn m2m_wifi_set_scan_options
01605  *   @ingroup WLANAPI
01606  *   Synchronous Wi-Fi scan settings function. This function sets the time configuration parameters for the scan operation.
01607  */
01608 
01609 /*!
01610 @fn \
01611     sint8 m2m_wifi_set_scan_options(tstrM2MScanOption* ptstrM2MScanOption)
01612 
01613 @param [in] ptstrM2MScanOption;
01614     Pointer to the structure holding the Scan Parameters.
01615 
01616 @see
01617     tenuM2mScanCh
01618     m2m_wifi_request_scan
01619     tstrM2MScanOption
01620     
01621 @return
01622     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01623 */
01624 NMI_API sint8 m2m_wifi_set_scan_options(tstrM2MScanOption* ptstrM2MScanOption);
01625  /**@}*/
01626 /** @defgroup WifiSetScanRegionFn m2m_wifi_set_scan_region
01627  *   @ingroup WLANAPI
01628  *  Synchronous wi-fi scan region setting function.
01629  *   This function sets the scan region, which will affect the range of possible scan channels. 
01630  *   For 2.5GHz supported in the current release, the requested scan region can't exceed the maximum number of channels (14).
01631  *@{*/
01632 /*!
01633 @fn \
01634     sint8 m2m_wifi_set_scan_region(uint16 ScanRegion)
01635 
01636 @param [in] ScanRegion;
01637         ASIA
01638         NORTH_AMERICA
01639 @see
01640     tenuM2mScanCh
01641     m2m_wifi_request_scan
01642     
01643 @return
01644     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01645 
01646 */
01647 NMI_API sint8 m2m_wifi_set_scan_region(uint16  ScanRegion);
01648  /**@}*/
01649 /** @defgroup WifiRequestScanFn m2m_wifi_request_scan
01650 *   @ingroup WLANAPI
01651 *    Asynchronous Wi-FI scan request on the given channel. The scan status is delivered in the wifi event callback and then the application
01652 *    is supposed to read the scan results sequentially. 
01653 *    The number of  APs found (N) is returned in event @ref M2M_WIFI_RESP_SCAN_DONE with the number of found
01654 *     APs.
01655 *   The application reads the list of APs by calling the function @ref m2m_wifi_req_scan_result N times.
01656 * 
01657 *@{*/
01658 /*!
01659 @fn \
01660     NMI_API sint8 m2m_wifi_request_scan(uint8 ch);
01661 
01662 @param [in] ch
01663               RF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh. 
01664               With a value of M2M_WIFI_CH_ALL(255)), means to scan all channels.
01665 
01666 @warning
01667     This function is not allowed in P2P or AP modes. It works only for STA mode (both connected or disconnected states).
01668                 
01669 @pre
01670     - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
01671       is done through passing it to the @ref m2m_wifi_init.
01672     - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT.
01673       must be handled in the callback.
01674     - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback.
01675 
01676 @see
01677     M2M_WIFI_RESP_SCAN_DONE
01678     M2M_WIFI_RESP_SCAN_RESULT
01679     tpfAppWifiCb
01680     tstrM2mWifiscanResult
01681     tenuM2mScanCh
01682     m2m_wifi_init
01683     m2m_wifi_handle_events
01684     m2m_wifi_req_scan_result
01685 
01686 @return
01687     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01688 \section Example
01689   The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of
01690   the events received in response.
01691 @code
01692 
01693     #include "m2m_wifi.h"
01694     #include "m2m_types.h"
01695     
01696     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
01697     {
01698         static uint8    u8ScanResultIdx = 0;
01699         
01700         switch(u8WiFiEvent)
01701         {
01702         case M2M_WIFI_RESP_SCAN_DONE:
01703             {
01704                 tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
01705                 
01706                 printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
01707                 if(pstrInfo->s8ScanState == M2M_SUCCESS)
01708                 {
01709                     u8ScanResultIdx = 0;
01710                     if(pstrInfo->u8NumofCh >= 1)
01711                     {
01712                         m2m_wifi_req_scan_result(u8ScanResultIdx);
01713                         u8ScanResultIdx ++;
01714                     }
01715                     else
01716                     {
01717                         printf("No AP Found Rescan\n");
01718                         m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
01719                     }
01720                 }
01721                 else
01722                 {
01723                     printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
01724                 }
01725             }
01726             break;
01727         
01728         case M2M_WIFI_RESP_SCAN_RESULT:
01729             {
01730                 tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
01731                 uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
01732                 
01733                 printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
01734                     pstrScanResult->u8index,pstrScanResult->s8rssi,
01735                     pstrScanResult->u8AuthType,
01736                     pstrScanResult->u8ch,
01737                     pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
01738                     pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
01739                     pstrScanResult->au8SSID);
01740                 
01741                 if(u8ScanResultIdx < u8NumFoundAPs)
01742                 {
01743                     // Read the next scan result
01744                     m2m_wifi_req_scan_result(index);
01745                     u8ScanResultIdx ++;
01746                 }
01747             }
01748             break;
01749         default:
01750             break;
01751         }
01752     }
01753     
01754     int main()
01755     {
01756         tstrWifiInitParam   param;
01757         
01758         param.pfAppWifiCb   = wifi_event_cb;
01759         if(!m2m_wifi_init(&param))
01760         {
01761             // Scan all channels
01762             m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
01763             
01764             while(1)
01765             {
01766                 m2m_wifi_handle_events(NULL);
01767             }
01768         }
01769     }
01770     
01771 @endcode
01772 */
01773 NMI_API sint8 m2m_wifi_request_scan(uint8 ch);
01774 
01775   /**@}*/
01776 /** @defgroup WifiRequestScanFn m2m_wifi_request_scan_passive
01777 *   @ingroup WLANAPI
01778 *    Same as m2m_wifi_request_scan but perform passive scanning while the other one perform active scanning.
01779 
01780 * 
01781 *@{*/
01782 /*!
01783 @fn \
01784     NMI_API sint8 m2m_wifi_request_scan_passive(uint8 ch, uint16 scan_time);
01785 
01786 @param [in] ch
01787               RF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh. 
01788               With a value of M2M_WIFI_CH_ALL(255)), means to scan all channels.
01789 
01790 @param [in] scan_time
01791               The time in ms that passive scan is listening to beacons on each channel per one slot, enter 0 for deafult setting.
01792 
01793 @warning
01794     This function is not allowed in P2P or AP modes. It works only for STA mode (both connected or disconnected states).
01795                 
01796 @pre
01797     - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
01798       is done through passing it to the @ref m2m_wifi_init.
01799     - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT.
01800       must be handled in the callback.
01801     - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback.
01802 
01803 @see
01804     m2m_wifi_request_scan
01805     M2M_WIFI_RESP_SCAN_DONE
01806     M2M_WIFI_RESP_SCAN_RESULT
01807     tpfAppWifiCb
01808     tstrM2mWifiscanResult
01809     tenuM2mScanCh
01810     m2m_wifi_init
01811     m2m_wifi_handle_events
01812     m2m_wifi_req_scan_result
01813 
01814 @return
01815     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01816 
01817 */
01818 NMI_API sint8 m2m_wifi_request_scan_passive(uint8 ch, uint16 scan_time);
01819 
01820   
01821  /**@}*/
01822 /** @defgroup WifiRequestScanFn m2m_wifi_request_scan_ssid_list
01823 *   @ingroup WLANAPI
01824 *    Asynchronous wi-fi scan request on the given channel and the hidden scan list. The scan status is delivered in the wi-fi event callback and then the application
01825 *    is to read the scan results sequentially. 
01826 *    The number of  APs found (N) is returned in event @ref M2M_WIFI_RESP_SCAN_DONE with the number of found
01827 *     APs.
01828 *   The application could read the list of APs by calling the function @ref m2m_wifi_req_scan_result N times.
01829 * 
01830 *@{*/
01831 /*!
01832 @fn \
01833     NMI_API sint8 m2m_wifi_request_scan_ssid_list(uint8 ch,uint8 * u8SsidList);
01834 
01835 @param [in] ch
01836               RF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh. 
01837               With a value of M2M_WIFI_CH_ALL(255)), means to scan all channels.
01838 @param [in] u8SsidList
01839               u8SsidList is a buffer containing a list of hidden SSIDs to 
01840               include during the scan. The first byte in the buffer, u8SsidList[0], 
01841               is the number of SSIDs encoded in the string. The number of hidden SSIDs 
01842               cannot exceed MAX_HIDDEN_SITES. All SSIDs are concatenated in the following 
01843               bytes and each SSID is prefixed with a one-byte header containing its length.  
01844               The total number of bytes in u8SsidList buffer, including length byte, cannot 
01845               exceed 133 bytes (MAX_HIDDEN_SITES SSIDs x 32 bytes each, which is max SSID length).
01846               For instance, encoding the two hidden SSIDs "DEMO_AP" and "TEST" 
01847               results in the following buffer content: 
01848 @code
01849               uint8 u8SsidList[14];
01850               u8SsidList[0] = 2; // Number of SSIDs is 2
01851               u8SsidList[1] = 7; // Length of the string "DEMO_AP" without NULL termination
01852               memcpy(&u8SsidList[2], "DEMO_AP", 7);  // Bytes index 2-9 containing the string DEMO_AP
01853               u8SsidList[9] = 4; // Length of the string "TEST" without NULL termination
01854               memcpy(&u8SsidList[10], "TEST", 4);  // Bytes index 10-13 containing the string TEST
01855 @endcode
01856 
01857 @warning
01858     This function is not allowed in P2P. It works only for STA/AP mode (connected or disconnected).
01859                 
01860 @pre
01861     - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
01862       is done through passing it to the @ref m2m_wifi_init.
01863     - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT.
01864       must be handled in the callback.
01865     - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback.
01866 
01867 @see
01868     M2M_WIFI_RESP_SCAN_DONE
01869     M2M_WIFI_RESP_SCAN_RESULT
01870     tpfAppWifiCb
01871     tstrM2mWifiscanResult
01872     tenuM2mScanCh
01873     m2m_wifi_init
01874     m2m_wifi_handle_events
01875     m2m_wifi_req_scan_result
01876 
01877 @return
01878     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
01879 \section Example
01880   The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of
01881   the events received in response.
01882 @code
01883 
01884     #include "m2m_wifi.h"
01885     #include "m2m_types.h"
01886 
01887     static void request_scan_hidden_demo_ap(void);
01888     
01889     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
01890     {
01891         static uint8    u8ScanResultIdx = 0;
01892         
01893         switch(u8WiFiEvent)
01894         {
01895         case M2M_WIFI_RESP_SCAN_DONE:
01896             {
01897                 tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
01898                 
01899                 printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
01900                 if(pstrInfo->s8ScanState == M2M_SUCCESS)
01901                 {
01902                     u8ScanResultIdx = 0;
01903                     if(pstrInfo->u8NumofCh >= 1)
01904                     {
01905                         m2m_wifi_req_scan_result(u8ScanResultIdx);
01906                         u8ScanResultIdx ++;
01907                     }
01908                     else
01909                     {
01910                         printf("No AP Found Rescan\n");
01911                         request_scan_hidden_demo_ap();
01912                     }
01913                 }
01914                 else
01915                 {
01916                     printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
01917                 }
01918             }
01919             break;
01920         
01921         case M2M_WIFI_RESP_SCAN_RESULT:
01922             {
01923                 tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
01924                 uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
01925                 
01926                 printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
01927                     pstrScanResult->u8index,pstrScanResult->s8rssi,
01928                     pstrScanResult->u8AuthType,
01929                     pstrScanResult->u8ch,
01930                     pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
01931                     pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
01932                     pstrScanResult->au8SSID);
01933                 
01934                 if(u8ScanResultIdx < u8NumFoundAPs)
01935                 {
01936                     // Read the next scan result
01937                     m2m_wifi_req_scan_result(index);
01938                     u8ScanResultIdx ++;
01939                 }
01940             }
01941             break;
01942         default:
01943             break;
01944         }
01945     }
01946 
01947     static void request_scan_hidden_demo_ap(void)
01948     {
01949         uint8 list[9];
01950         char ssid[] = "DEMO_AP";
01951         uint8 len = (uint8)(sizeof(ssid)-1);
01952 
01953         list[0] = 1;
01954         list[1] = len;
01955         memcpy(&list[2], ssid, len); // copy 7 bytes
01956         // Scan all channels
01957         m2m_wifi_request_scan_ssid_list(M2M_WIFI_CH_ALL, list);
01958     }
01959     
01960 
01961     int main()
01962     {
01963         tstrWifiInitParam   param;
01964         
01965         param.pfAppWifiCb   = wifi_event_cb;
01966         if(!m2m_wifi_init(&param))
01967         {
01968             request_scan_hidden_demo_ap();
01969 
01970             while(1)
01971             {
01972                 m2m_wifi_handle_events(NULL);
01973             }
01974         }
01975     }
01976     
01977 @endcode
01978 */
01979 NMI_API sint8 m2m_wifi_request_scan_ssid_list(uint8 ch,uint8 * u8Ssidlist);
01980 
01981 /**@}*/
01982 /** @defgroup WifiGetNumAPFoundFn m2m_wifi_get_num_ap_found
01983  *   @ingroup WLANAPI
01984 *  Synchronous function to retrieve the number of AP's found in the last scan request, The function reads the number of APs from global variable which was updated in the Wi-Fi callback function through the M2M_WIFI_RESP_SCAN_DONE event.
01985 *  Function used only in STA mode only. 
01986  */
01987  /**@{*/
01988 /*!
01989 @fn        NMI_API uint8 m2m_wifi_get_num_ap_found(void);
01990 
01991 @see       m2m_wifi_request_scan 
01992            M2M_WIFI_RESP_SCAN_DONE
01993            M2M_WIFI_RESP_SCAN_RESULT         
01994 @pre         m2m_wifi_request_scan need to be called first  
01995         - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
01996            is done through passing it to the @ref m2m_wifi_init.
01997         - The event @ref M2M_WIFI_RESP_SCAN_DONE must be handled in the callback to receive the requested scan information. 
01998 @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
01999            are received.
02000            Calling this function in any other place will result in undefined/outdated numbers.
02001 @return    Return the number of AP's found in the last Scan Request.
02002           
02003 \section Example
02004   The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of
02005   the events received in response.
02006 @code
02007 
02008     #include "m2m_wifi.h"
02009     #include "m2m_types.h"
02010     
02011     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
02012     {
02013         static uint8    u8ScanResultIdx = 0;
02014         
02015         switch(u8WiFiEvent)
02016         {
02017         case M2M_WIFI_RESP_SCAN_DONE:
02018             {
02019                 tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
02020                 
02021                 printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
02022                 if(pstrInfo->s8ScanState == M2M_SUCCESS)
02023                 {
02024                     u8ScanResultIdx = 0;
02025                     if(pstrInfo->u8NumofCh >= 1)
02026                     {
02027                         m2m_wifi_req_scan_result(u8ScanResultIdx);
02028                         u8ScanResultIdx ++;
02029                     }
02030                     else
02031                     {
02032                         printf("No AP Found Rescan\n");
02033                         m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
02034                     }
02035                 }
02036                 else
02037                 {
02038                     printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
02039                 }
02040             }
02041             break;
02042         
02043         case M2M_WIFI_RESP_SCAN_RESULT:
02044             {
02045                 tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
02046                 uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
02047                 
02048                 printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
02049                     pstrScanResult->u8index,pstrScanResult->s8rssi,
02050                     pstrScanResult->u8AuthType,
02051                     pstrScanResult->u8ch,
02052                     pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
02053                     pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
02054                     pstrScanResult->au8SSID);
02055                 
02056                 if(u8ScanResultIdx < u8NumFoundAPs)
02057                 {
02058                     // Read the next scan result
02059                     m2m_wifi_req_scan_result(index);
02060                     u8ScanResultIdx ++;
02061                 }
02062             }
02063             break;
02064         default:
02065             break;
02066         }
02067     }
02068     
02069     int main()
02070     {
02071         tstrWifiInitParam   param;
02072         
02073         param.pfAppWifiCb   = wifi_event_cb;
02074         if(!m2m_wifi_init(&param))
02075         {
02076             // Scan all channels
02077             m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
02078             
02079             while(1)
02080             {
02081                 m2m_wifi_handle_events(NULL);
02082             }
02083         }
02084     }
02085     
02086 @endcode             
02087 */
02088 NMI_API uint8 m2m_wifi_get_num_ap_found(void);
02089 /**@}*/
02090 /** @defgroup WifiReqScanResult m2m_wifi_req_scan_result
02091 *   @ingroup WLANAPI
02092 *   Synchronous call to read the AP information from the SCAN Result list with the given index.
02093 *   This function is expected to be called when the response events M2M_WIFI_RESP_SCAN_RESULT or
02094 *   M2M_WIFI_RESP_SCAN_DONE are received in the wi-fi callback function.
02095 *   The response information received can be obtained through the casting to the @ref tstrM2mWifiscanResult structure   
02096  */
02097  /**@{*/
02098 /*!
02099 @fn          NMI_API sint8 m2m_wifi_req_scan_result(uint8 index);
02100 @param [in]  index 
02101               Index for the requested result, the index range start from 0 till number of AP's found
02102 
02103 @see          tstrM2mWifiscanResult
02104            m2m_wifi_get_num_ap_found
02105            m2m_wifi_request_scan             
02106            
02107 @pre         @ref m2m_wifi_request_scan needs to be called first, then m2m_wifi_get_num_ap_found 
02108            to get the number of AP's found  
02109             - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback
02110             is done through passing it to the @ref m2m_wifi_init function.
02111             - The event @ref M2M_WIFI_RESP_SCAN_RESULT must be handled in the callback to receive the requested scan information.
02112 @warning     Function used  in STA mode only. the scan results are updated only if the scan request is called.
02113              Calling this function only without a scan request will lead to firmware errors. 
02114              Refrain from introducing a large delay  between the scan request and the scan result request, to prevent
02115              errors occurring.
02116              
02117 @return      The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02118 \section Example
02119   The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of
02120   the events received in response.
02121 @code
02122     #include "m2m_wifi.h"
02123     #include "m2m_types.h"
02124     
02125     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
02126     {
02127         static uint8    u8ScanResultIdx = 0;
02128         
02129         switch(u8WiFiEvent)
02130         {
02131         case M2M_WIFI_RESP_SCAN_DONE:
02132             {
02133                 tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
02134                 
02135                 printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
02136                 if(pstrInfo->s8ScanState == M2M_SUCCESS)
02137                 {
02138                     u8ScanResultIdx = 0;
02139                     if(pstrInfo->u8NumofCh >= 1)
02140                     {
02141                         m2m_wifi_req_scan_result(u8ScanResultIdx);
02142                         u8ScanResultIdx ++;
02143                     }
02144                     else
02145                     {
02146                         printf("No AP Found Rescan\n");
02147                         m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
02148                     }
02149                 }
02150                 else
02151                 {
02152                     printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
02153                 }
02154             }
02155             break;
02156         
02157         case M2M_WIFI_RESP_SCAN_RESULT:
02158             {
02159                 tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
02160                 uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
02161                 
02162                 printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
02163                     pstrScanResult->u8index,pstrScanResult->s8rssi,
02164                     pstrScanResult->u8AuthType,
02165                     pstrScanResult->u8ch,
02166                     pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
02167                     pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
02168                     pstrScanResult->au8SSID);
02169                 
02170                 if(u8ScanResultIdx < u8NumFoundAPs)
02171                 {
02172                     // Read the next scan result
02173                     m2m_wifi_req_scan_result(index);
02174                     u8ScanResultIdx ++;
02175                 }
02176             }
02177             break;
02178         default:
02179             break;
02180         }
02181     }
02182     
02183     int main()
02184     {
02185         tstrWifiInitParam   param;
02186         
02187         param.pfAppWifiCb   = wifi_event_cb;
02188         if(!m2m_wifi_init(&param))
02189         {
02190             // Scan all channels
02191             m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
02192             
02193             while(1)
02194             {
02195                 m2m_wifi_handle_events(NULL);
02196             }
02197         }
02198     }
02199     
02200 @endcode 
02201 */
02202 NMI_API sint8 m2m_wifi_req_scan_result(uint8 index);
02203 /**@}*/
02204 /** @defgroup WifiReqCurrentRssiFn m2m_wifi_req_curr_rssi
02205  *   @ingroup WLANAPI
02206  *   Asynchronous request for the current RSSI of the connected AP.
02207  *   The response received in through the @ref M2M_WIFI_RESP_CURRENT_RSSI event.
02208  */
02209  /**@{*/
02210 /*!
02211 @fn          NMI_API sint8 m2m_wifi_req_curr_rssi(void);
02212 @pre       - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered before initialization. Registering the callback
02213             is done through passing it to the [m2m_wifi_init](@ref m2m_wifi_init) through the @ref tstrWifiInitParam initialization structure.
02214            - The event @ref M2M_WIFI_RESP_CURRENT_RSSI must be handled in the callback to receive the requested Rssi information.       
02215 @return      The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.    
02216 \section Example
02217   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. 
02218 @code
02219 
02220     #include "m2m_wifi.h"
02221     #include "m2m_types.h"
02222     
02223     void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
02224     {
02225         static uint8    u8ScanResultIdx = 0;
02226         
02227         switch(u8WiFiEvent)
02228         {
02229         case M2M_WIFI_RESP_CURRENT_RSSI:
02230             {
02231                 sint8   *rssi = (sint8*)pvMsg;
02232                 M2M_INFO("ch rssi %d\n",*rssi);
02233             }
02234             break;
02235         default:
02236             break;
02237         }
02238     }
02239     
02240     int main()
02241     {
02242         tstrWifiInitParam   param;
02243         
02244         param.pfAppWifiCb   = wifi_event_cb;
02245         if(!m2m_wifi_init(&param))
02246         {
02247             // Scan all channels
02248             m2m_wifi_req_curr_rssi();
02249             
02250             while(1)
02251             {
02252                 m2m_wifi_handle_events(NULL);
02253             }
02254         }
02255     }
02256 
02257 @endcode    
02258 
02259 */
02260 NMI_API sint8 m2m_wifi_req_curr_rssi(void);
02261 /**@}*/
02262 /** @defgroup WifiGetOtpMacAddFn m2m_wifi_get_otp_mac_address
02263 *   @ingroup WLANAPI
02264 *   Request the MAC address stored on the One Time Programmable(OTP) memory of the device.
02265 *   The function is blocking until the response is received.
02266 */
02267  /**@{*/
02268 /*!
02269 @fn          NMI_API sint8 m2m_wifi_get_otp_mac_address(uint8 *pu8MacAddr, uint8 * pu8IsValid);
02270 
02271 @param [out] pu8MacAddr
02272             Output MAC address buffer of 6 bytes size. Valid only if *pu8Valid=1.
02273 @param [out] pu8IsValid
02274              Output boolean value to indicate the validity of pu8MacAddr in OTP. 
02275              Output zero if the OTP memory is not programmed, non-zero otherwise.
02276 @pre         m2m_wifi_init required to be called before any WIFI/socket function
02277 @see         m2m_wifi_get_mac_address             
02278 
02279 @return      The function returns @ref M2M_SUCCESS for success and a negative value otherwise.
02280 
02281 */
02282 NMI_API sint8 m2m_wifi_get_otp_mac_address(uint8 *pu8MacAddr, uint8 * pu8IsValid);
02283 /**@}*/
02284 /** @defgroup WifiGetMacAddFn m2m_wifi_get_mac_address
02285 *   @ingroup WLANAPI
02286 *   Function to retrieve the current MAC address. The function is blocking until the response is received.
02287 */
02288 /**@{*/
02289 /*!
02290 @fn          NMI_API sint8 m2m_wifi_get_mac_address(uint8 *pu8MacAddr)  
02291 @param [out] pu8MacAddr
02292              Output MAC address buffer of 6 bytes size. 
02293 @pre         m2m_wifi_init required to be called before any WIFI/socket function
02294 @see         m2m_wifi_get_otp_mac_address             
02295 @return      The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02296 
02297 */
02298 NMI_API sint8 m2m_wifi_get_mac_address(uint8 *pu8MacAddr);
02299 /**@}*/
02300 /** @defgroup SetSleepModeFn m2m_wifi_set_sleep_mode
02301  *   @ingroup WLANAPI
02302  *  This is one of the two synchronous power-save setting functions that
02303  *  allow the host MCU application to tweak the system power consumption. Such tweaking can be done through one of two ways:
02304 *  1) Changing the power save mode, to one of the allowed power save modes @ref tenuPowerSaveModes. This is done by setting the first parameter
02305 *  2) Configuring DTIM monitoring: Configuring beacon monitoring parameters by enabling or disabling the reception of broadcast/multicast data. 
02306 *   this is done by setting the second parameter.
02307  */
02308  /**@{*/
02309 /*!
02310 @fn         NMI_API sint8 m2m_wifi_set_sleep_mode(uint8 PsTyp, uint8 BcastEn);
02311 @param [in] PsTyp
02312             Desired power saving mode. Supported types are enumerated in @ref tenuPowerSaveModes.
02313 @param [in] BcastEn
02314             Broadcast reception enable flag. 
02315             If it is 1, the WINC1500 will be awake each DTIM beacon for receiving broadcast traffic.
02316             If it is 0, the WINC1500: disable broadcast traffic. Through this flag the WINC1500 will not wakeup at the DTIM beacon, but it will wakeup depends only 
02317             on the the configured Listen Interval. 
02318 
02319 @warning    The function called once after initialization.
02320 
02321 @see       tenuPowerSaveModes
02322            m2m_wifi_get_sleep_mode
02323            m2m_wifi_set_lsn_int
02324 
02325 @return    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02326 */
02327 NMI_API sint8 m2m_wifi_set_sleep_mode(uint8 PsTyp, uint8 BcastEn);
02328 /**@}*/
02329 /** @defgroup WifiRequestSleepFn m2m_wifi_request_sleep
02330  *   @ingroup WLANAPI
02331  *      Synchronous power-save sleep request function, which requests from the WINC1500 device to sleep in the currenlty configured power save mode as defined
02332  *      by the @ref m2m_wifi_set_sleep_mode, for a specific time as defined by the passed in parameter.
02333  *      This function should be used in the @ref M2M_PS_MANUAL power save mode only.
02334  *    A wake up request is automatically performed by the WINC1500 device when any host driver API function, e.g. Wi-Fi or socket operation is called.
02335  */
02336  /**@{*/
02337 /*!
02338 @fn         NMI_API sint8 m2m_wifi_request_sleep(uint32 u32SlpReqTime);
02339 @param [in] u32SlpReqTime
02340             Request sleep time in ms 
02341             The best recommended sleep duration is left to be determined by the application. Taking into account that if the application sends notifications very rarely, 
02342             sleeping for a long time can be a power-efficient decision. In contrast applications that are senstive for long periods of absence can experience  
02343             performance degradation in the connection if long sleeping times are used.
02344 @warning    The function should be called in @ref M2M_PS_MANUAL power save mode only. As enumerated in @ref tenuPowerSaveModes
02345             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 
02346             the sleep period is enlongated.
02347 @see            tenuPowerSaveModes 
02348             m2m_wifi_set_sleep_mode
02349 
02350 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02351 */
02352 NMI_API sint8 m2m_wifi_request_sleep(uint32 u32SlpReqTime);
02353 /**@}*/
02354 /** @defgroup GetSleepModeFn m2m_wifi_get_sleep_mode
02355  *   @ingroup WLANAPI
02356  *  Synchronous power save mode retrieval function.
02357  */
02358  /**@{*/
02359 /*!
02360 @fn         NMI_API uint8 m2m_wifi_get_sleep_mode(void);
02361 @see        tenuPowerSaveModes 
02362             m2m_wifi_set_sleep_mode
02363 @return     The current operating power saving mode based on the enumerated sleep modes @ref tenuPowerSaveModes.
02364 */
02365 NMI_API uint8 m2m_wifi_get_sleep_mode(void);
02366 /**@}*/
02367 /** @defgroup WifiReqClientCtrlFn m2m_wifi_req_client_ctrl
02368  *   @ingroup WLANAPI
02369  *  Asynchronous command sending function to the PS Client (An WINC1500 board running the ps_firmware)
02370 *   if the PS client send any command it will be received through the @ref M2M_WIFI_RESP_CLIENT_INFO event
02371  */
02372  /**@{*/
02373 /*!
02374 @fn         NMI_API sint8 m2m_wifi_req_client_ctrl(uint8 cmd);
02375 @brief      
02376 @param [in] cmd
02377             Control command sent from PS Server to PS Client (command values defined by the application)
02378 @pre        @ref m2m_wifi_req_server_init should be called first
02379 @warning           This mode is not supported in the current release.
02380 @see        m2m_wifi_req_server_init
02381             M2M_WIFI_RESP_CLIENT_INFO
02382 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02383 */
02384 NMI_API sint8 m2m_wifi_req_client_ctrl(uint8 cmd);
02385 /**@}*/
02386 /** @defgroup WifiReqServerInit m2m_wifi_req_server_init
02387  *   @ingroup WLANAPI
02388  *  Synchronous function to initialize the PS Server.
02389  *  The WINC1500 supports non secure communication with another WINC1500, 
02390 *   (SERVER/CLIENT) through one byte command (probe request and probe response) without any connection setup.
02391 *   The server mode can't be used with any other modes (STA/P2P/AP)
02392 */
02393  /**@{*/
02394 /*!
02395 @fn         NMI_API sint8 m2m_wifi_req_server_init(uint8 ch);
02396 @param [in] ch
02397             Server listening channel
02398 @see        m2m_wifi_req_client_ctrl
02399 @warning           This mode is not supported in the current release.
02400 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02401 */
02402 NMI_API sint8 m2m_wifi_req_server_init(uint8 ch);
02403 /**@}*/
02404 /** @defgroup WifiSetDeviceNameFn m2m_wifi_set_device_name
02405  *   @ingroup WLANAPI
02406  *  Sets the WINC device name. The name string is used as a device name in both (P2P) WiFi-Direct mode as well as DHCP hostname (option 12).
02407  *  For P2P devices to communicate a device name must be present. If it is not set through this function a default name is assigned.
02408  *  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, 
02409  *  then the default name is WINC-00-00.
02410  */
02411  /**@{*/
02412 /*!
02413 @fn         NMI_API sint8 m2m_wifi_set_device_name(uint8 *pu8DeviceName, uint8 u8DeviceNameLength);     
02414 @param [in] pu8DeviceName
02415             A Buffer holding the device name. Device name is a null terminated C string.
02416 @param [in] u8DeviceNameLength
02417             The length of the device name. Should not exceed the maximum device name's length @ref M2M_DEVICE_NAME_MAX (including null character).
02418 @warning    The function called once after initialization. 
02419             Used for the Wi-Fi Direct (P2P) as well as DHCP client hostname option (12). 
02420 @warning    Device name shall contain only characters allowed in valid internet host name as defined in RFC 952 and 1123.
02421 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02422 */
02423 NMI_API sint8 m2m_wifi_set_device_name(uint8 *pu8DeviceName, uint8 u8DeviceNameLength);
02424 /**@}*/
02425 /** @defgroup WifiSetLsnIntFn m2m_wifi_set_lsn_int
02426  *   @ingroup WLANAPI
02427 *   This is one of the two synchronous power-save setting functions that
02428 *   allow the host MCU application to tweak the system power consumption. Such tweaking can be done by modifying the 
02429 *   the Wi-Fi listen interval. The listen interval is how many beacon periods the station can sleep before it wakes up to receive data buffer in AP.  
02430 *     It is represented in units of AP beacon periods(100ms).  
02431 */
02432  /**@{*/
02433 /*!
02434 @fn         NMI_API sint8 m2m_wifi_set_lsn_int(tstrM2mLsnInt * pstrM2mLsnInt);
02435 
02436 @param [in] pstrM2mLsnInt
02437             Structure holding the listen interval configurations.
02438 @pre        Function @m2m_wifi_set_sleep_mode shall be called first, to set the power saving mode required.
02439 @warning        The function should be called once after initialization. 
02440 @see        tstrM2mLsnInt
02441                      m2m_wifi_set_sleep_mode
02442 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02443 
02444 */
02445 NMI_API sint8 m2m_wifi_set_lsn_int(tstrM2mLsnInt *pstrM2mLsnInt);
02446 /**@}*/
02447 /** @defgroup WifiEnableMonitorModeFn m2m_wifi_enable_monitoring_mode
02448  *   @ingroup WLANAPI
02449  *     Asynchronous Wi-Fi monitoring mode (Promiscuous mode) enabling function. This function enables the monitoring mode, thus allowing two operations to be performed:
02450  *    1) Transmission of manually configured frames, through using the @ref m2m_wifi_send_wlan_pkt function.
02451  *    2) Reception of frames based on a defined filtering criteria
02452  *    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 \n.
02453  *    All packets that meet the filtering criteria are passed to the application layer, to be handled by the assigned monitoring callback function \n.
02454  *    The monitoring callback function must be implemented before starting the monitoring mode, in-order to handle the packets received \n.
02455  *    Registering of the implemented callback function is through the callback pointer @ref tpfAppMonCb in the @ref tstrWifiInitParam structure\n.
02456  *    passed to @ref m2m_wifi_init function at initialization.
02457  *    
02458  */
02459  /**@{*/
02460 /*!
02461  * @fn             NMI_API sint8 m2m_wifi_enable_monitoring_mode(tstrM2MWifiMonitorModeCtrl *, uint8 *, uint16 , uint16);
02462  * @param [in]     pstrMtrCtrl
02463  *                      Pointer to @ref tstrM2MWifiMonitorModeCtrl structure holding the filtering parameters.
02464  * @param [in]     pu8PayloadBuffer
02465  *                 Pointer to a buffer allocated by the application. The buffer SHALL hold the Data field of 
02466  *                 the WIFI RX Packet (Or a part from it). If it is set to NULL, the WIFI data payload will 
02467  *                 be discarded by the monitoring driver.
02468  * @param [in]     u16BufferSize
02469  *                 The total size of the pu8PayloadBuffer in bytes.
02470  * @param [in]     u16DataOffset
02471  *                 Starting offset in the DATA FIELD of the received WIFI packet. The application may be interested
02472  *                 in reading specific information from the received packet. It must assign the offset to the starting
02473  *                 position of it relative to the DATA payload start.\n
02474  *                 \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.
02475  * @warning        When This mode is enabled, you can not be connected in any mode (Station, Access Point, or P2P).\n 
02476  * @see             tstrM2MWifiMonitorModeCtrl
02477                tstrM2MWifiRxPacketInfo
02478                tstrWifiInitParam
02479                tenuM2mScanCh
02480                m2m_wifi_disable_monitoring_mode  
02481                m2m_wifi_send_wlan_pkt
02482                m2m_wifi_send_ethernet_pkt
02483  * @return       The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02484 
02485 *\section Example
02486 *  The example demonstrates the main function where-by the monitoring enable function is called after the initialization of the driver and the packets are
02487 *   handled in the callback function.
02488 * @code
02489             
02490             #include "m2m_wifi.h"
02491             #include "m2m_types.h"
02492 
02493             //Declare receive buffer 
02494             uint8 gmgmt[1600];
02495     
02496             //Callback functions
02497             void wifi_cb(uint8 u8WiFiEvent, void * pvMsg)
02498             {
02499                 ; 
02500             }
02501             void wifi_monitoring_cb(tstrM2MWifiRxPacketInfo *pstrWifiRxPacket, uint8 *pu8Payload, uint16 u16PayloadSize)
02502             {
02503                 if((NULL != pstrWifiRxPacket) && (0 != u16PayloadSize)) {
02504                     if(MANAGEMENT == pstrWifiRxPacket->u8FrameType) {
02505                         M2M_INFO("***# MGMT PACKET #***\n");
02506                     } else if(DATA_BASICTYPE == pstrWifiRxPacket->u8FrameType) {
02507                         M2M_INFO("***# DATA PACKET #***\n");
02508                     } else if(CONTROL == pstrWifiRxPacket->u8FrameType) {
02509                         M2M_INFO("***# CONTROL PACKET #***\n");
02510                     }
02511                 }
02512             }
02513             
02514             int main()
02515             {
02516                 //Register wifi_monitoring_cb 
02517                 tstrWifiInitParam param;
02518                 param.pfAppWifiCb = wifi_cb;
02519                 param.pfAppMonCb  = wifi_monitoring_cb;
02520                 
02521                 nm_bsp_init();
02522                 
02523                 if(!m2m_wifi_init(&param)) {
02524                     //Enable Monitor Mode with filter to receive all data frames on channel 1
02525                     tstrM2MWifiMonitorModeCtrl  strMonitorCtrl = {0};
02526                     strMonitorCtrl.u8ChannelID      = M2M_WIFI_CH_1;
02527                     strMonitorCtrl.u8FrameType      = DATA_BASICTYPE;
02528                     strMonitorCtrl.u8FrameSubtype   = M2M_WIFI_FRAME_SUB_TYPE_ANY; //Receive any subtype of data frame
02529                     m2m_wifi_enable_monitoring_mode(&strMonitorCtrl, gmgmt, sizeof(gmgmt), 0);
02530                     
02531                     while(1) {
02532                         m2m_wifi_handle_events(NULL);
02533                     }
02534                 }
02535                 return 0;
02536             }
02537  * @endcode
02538  */
02539 NMI_API sint8 m2m_wifi_enable_monitoring_mode(tstrM2MWifiMonitorModeCtrl *pstrMtrCtrl, uint8 *pu8PayloadBuffer, 
02540                                            uint16 u16BufferSize, uint16 u16DataOffset);
02541 /**@}*/
02542 /** @defgroup WifiDisableMonitorModeFn m2m_wifi_disable_monitoring_mode
02543  *   @ingroup WLANAPI
02544  *   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
02545  *   no negative impact will reside.
02546  */
02547  /**@{*/
02548 /*!
02549  * @fn             NMI_API sint8 m2m_wifi_disable_monitoring_mode(void);
02550  * @see           m2m_wifi_enable_monitoring_mode               
02551  * @return      The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02552  */
02553 NMI_API sint8 m2m_wifi_disable_monitoring_mode(void);
02554  /**@}*/
02555  /** @defgroup SendWlanPktFn m2m_wifi_send_wlan_pkt
02556  *   @ingroup WLANAPI
02557  *   Synchronous function to transmit a WIFI RAW packet while the implementation of this packet is left to the application developer.
02558  */
02559  /**@{*/
02560 /*!
02561  * @fn             NMI_API sint8 m2m_wifi_send_wlan_pkt(uint8 *, uint16, uint16);
02562  
02563  * @param [in]     pu8WlanPacket
02564  *                       Pointer to a buffer holding the whole WIFI frame.
02565  * @param [in]     u16WlanHeaderLength
02566  *                The size of the WIFI packet header ONLY.
02567  * @param [in]     u16WlanPktSize
02568  *               The size of the whole bytes in packet. 
02569  * @see             m2m_wifi_enable_monitoring_mode
02570                m2m_wifi_disable_monitoring_mode
02571  * @pre              Enable Monitoring mode first using @ref m2m_wifi_enable_monitoring_mode
02572  * @warning        This function available in monitoring mode ONLY.\n  
02573  * @note             Packets are user's responsibility.
02574  * @return          The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02575  */
02576 NMI_API sint8 m2m_wifi_send_wlan_pkt(uint8 *pu8WlanPacket, uint16 u16WlanHeaderLength, uint16 u16WlanPktSize);
02577 /**@}*/
02578 /** @defgroup WifiSendEthernetPktFn m2m_wifi_send_ethernet_pkt
02579  *   @ingroup WLANAPI
02580  *   Synchronous function to transmit an Ethernet packet. 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. 
02581  *   The Ethernet packet composition is left to the application developer. 
02582  */
02583  /**@{*/
02584 /*!
02585  * @fn           NMI_API sint8 m2m_wifi_send_ethernet_pkt(uint8* pu8Packet,uint16 u16PacketSize)
02586  * @param [in]     pu8Packet
02587  *                        Pointer to a buffer holding the whole Ethernet frame.
02588  * @param [in]     u16PacketSize
02589  *                  The size of the whole bytes in packet.    
02590   * @warning     This function available in ETHERNET/Bypass mode ONLY. Make sure that application defines @ref ETH_MODE.\n  
02591  * @note            Packets are the user's responsibility.
02592  *  @sa            m2m_wifi_enable_mac_mcast,m2m_wifi_set_receive_buffer    
02593  * @return         The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02594 
02595  */
02596 NMI_API sint8 m2m_wifi_send_ethernet_pkt(uint8* pu8Packet,uint16 u16PacketSize);
02597 /**@}*/
02598 /** @defgroup WifiEnableSntpFn m2m_wifi_enable_sntp
02599  *   @ingroup WLANAPI
02600  *      Synchronous function to enable/disable the native Simple Network Time Protocol(SNTP) client in the WINC1500 firmware.\n
02601  *    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
02602  *      servers (e.g. "time-c.nist.gov"). The SNTP client uses a default update cycle of 1 day.
02603  *      The UTC is important for checking the expiration date of X509 certificates used while establishing
02604  *      TLS (Transport Layer Security) connections.
02605  *      It is highly recommended to use it if there is no other means to get the UTC time. If there is a RTC
02606  *      on the host MCU, the SNTP could be disabled and the host should set the system time to the firmware 
02607  *      using the @ref m2m_wifi_set_system_time function.
02608  */
02609  /**@{*/
02610 /*!
02611  * @fn                  NMI_API sint8 m2m_wifi_enable_sntp(uint8);
02612  * @param [in]     bEnable
02613 *               Enabling/Disabling flag
02614  *                        '0' :disable SNTP
02615  *                        '1' :enable SNTP  
02616  * @see             m2m_wifi_set_sytem_time       
02617  * @return        The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02618  */
02619 NMI_API sint8 m2m_wifi_enable_sntp(uint8 bEnable);
02620 /**@}*/
02621 /** @defgroup WifiSetSystemTime m2m_wifi_set_sytem_time
02622  *   @ingroup WLANAPI
02623  *    Synchronous function for setting the system time in time/date format (@ref uint32).\n
02624  *    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
02625  */
02626  /**@{*/
02627 /*!
02628  * @fn             NMI_API sint8 m2m_wifi_set_sytem_time(uint32);   
02629  * @param [in]     u32UTCSeconds
02630  *                    Seconds elapsed since January 1, 1900 (NTP Timestamp).  
02631  * @see            m2m_wifi_enable_sntp
02632  *            tstrSystemTime   
02633   * @note         If there is an RTC on the host MCU, the SNTP could be disabled and the host should set the system time to the firmware 
02634  *               using the API @ref m2m_wifi_set_sytem_time.
02635  * @return        The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02636  */
02637 NMI_API sint8 m2m_wifi_set_sytem_time(uint32 u32UTCSeconds);
02638 /**@}*/
02639 /** @defgroup WifiGetSystemTime m2m_wifi_get_sytem_time
02640  *   @ingroup WLANAPI
02641  *    Asynchronous function used to retrieve the system time through the use of the response @ref M2M_WIFI_RESP_GET_SYS_TIME.
02642  *    Response time retrieved is parsed into the members defined in the structure @ref tstrSystemTime.
02643  */
02644  /**@{*/
02645 /*!
02646  * @fn             NMI_API sint8 m2m_wifi_get_sytem_time(void);   
02647  * @see            m2m_wifi_enable_sntp
02648               tstrSystemTime   
02649  * @note         Get the system time from the SNTP client
02650  *              using the API @ref m2m_wifi_get_sytem_time.
02651  * @return        The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02652  */
02653 NMI_API sint8 m2m_wifi_get_sytem_time (void);
02654 /**@}*/
02655 /** @defgroup WifiSetCustInfoElementFn m2m_wifi_set_cust_InfoElement
02656  *   @ingroup WLANAPI
02657  *   Synchronous function to Add/Remove user-defined Information Element to the WIFIBeacon and Probe Response frames while chip mode is Access Point Mode.\n
02658  *   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
02659  *   information according to the sizes and ordering defined bellow. However, if it's required to delete these IEs, fill the buffer with zeros.
02660  */
02661  /**@{*/
02662 /*!
02663  * @fn             NMI_API sint8 m2m_wifi_set_cust_InfoElement(uint8*);
02664  * @param [in]     pau8M2mCustInfoElement
02665  *                        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. 
02666  * @warning        - Size of All elements combined must not exceed 255 byte.\n
02667  *                 - Used in Access Point Mode \n
02668  * @note              IEs Format will be follow the following layout:\n
02669  * @verbatim 
02670                --------------- ---------- ---------- ------------------- -------- -------- ----------- ----------------------  
02671               | Byte[0]       | Byte[1]  | Byte[2]  | Byte[3:length1+2] | ..... | Byte[n] | Byte[n+1] | Byte[n+2:lengthx+2]  | 
02672               |---------------|----------|----------|-------------------|-------- --------|-----------|------------------| 
02673               | #of all Bytes | IE1 ID   | Length1  | Data1(Hex Coded)  | ..... | IEx ID  | Lengthx   | Datax(Hex Coded)     | 
02674                --------------- ---------- ---------- ------------------- -------- -------- ----------- ---------------------- 
02675  * @endverbatim
02676  * @see             m2m_wifi_enable_sntp
02677  *                      tstrSystemTime               
02678  * @return        The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02679  \section Example
02680    The example demonstrates how the information elements are set using this function.
02681  *@code
02682  *
02683             char elementData[21];
02684             static char state = 0; // To Add, Append, and Delete
02685             if(0 == state) {    //Add 3 IEs
02686                 state = 1;
02687                 //Total Number of Bytes
02688                 elementData[0]=12;
02689                 //First IE
02690                 elementData[1]=200; elementData[2]=1; elementData[3]='A';
02691                 //Second IE
02692                 elementData[4]=201; elementData[5]=2; elementData[6]='B'; elementData[7]='C';
02693                 //Third IE
02694                 elementData[8]=202; elementData[9]=3; elementData[10]='D'; elementData[11]=0; elementData[12]='F';
02695             } else if(1 == state) { 
02696                 //Append 2 IEs to others, Notice that we keep old data in array starting with\n
02697                 //element 13 and total number of bytes increased to 20
02698                 state = 2; 
02699                 //Total Number of Bytes
02700                 elementData[0]=20;
02701                 //Fourth IE
02702                 elementData[13]=203; elementData[14]=1; elementData[15]='G';
02703                 //Fifth IE
02704                 elementData[16]=204; elementData[17]=3; elementData[18]='X'; elementData[19]=5; elementData[20]='Z';
02705             } else if(2 == state) { //Delete All IEs
02706                 state = 0; 
02707                 //Total Number of Bytes
02708                 elementData[0]=0;
02709             }
02710             m2m_wifi_set_cust_InfoElement(elementData); 
02711  * @endcode
02712  */
02713 NMI_API sint8 m2m_wifi_set_cust_InfoElement(uint8* pau8M2mCustInfoElement);
02714  /**@}*/
02715 /** @defgroup WifiSetPowerProfile m2m_wifi_set_power_profile
02716  *   @ingroup WLANAPI
02717  *    Change the power profile mode
02718  */
02719  /**@{*/
02720 /*!
02721 @fn         NMI_API sint8 m2m_wifi_set_power_profile(uint8 u8PwrMode);
02722 @brief       
02723 @param [in] u8PwrMode
02724             Change the WINC1500 power profile to different mode based on the enumeration
02725             @ref  tenuM2mPwrMode
02726 @pre        Must be called after the initializations and before any connection request and can't be changed in run time.
02727 @sa         tenuM2mPwrMode
02728             m2m_wifi_init
02729 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.    
02730 */
02731 sint8 m2m_wifi_set_power_profile(uint8 u8PwrMode);
02732   /**@}*/
02733   /** @defgroup WifiSetTxPower m2m_wifi_set_tx_power
02734  *   @ingroup WLANAPI
02735  *  Set the TX power tenuM2mTxPwrLevel
02736  */
02737  /**@{*/
02738 /*!
02739 @fn         NMI_API sint8 m2m_wifi_set_tx_power(uint8 u8TxPwrLevel);
02740 @param [in] u8TxPwrLevel
02741             change the TX power based on the enumeration tenuM2mTxPwrLevel
02742 @pre        Must be called after the initialization and before any connection request and can't be changed in runtime.
02743 @sa         tenuM2mTxPwrLevel
02744             m2m_wifi_init
02745 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.    
02746 */
02747 sint8 m2m_wifi_set_tx_power(uint8 u8TxPwrLevel);
02748  /**@}*/
02749 /** @defgroup WifiEnableFirmware m2m_wifi_enable_firmware_logs
02750 *   @ingroup WLANAPI
02751 *   Enable or Disable logs in run time (Disabling Firmware logs will 
02752 *   enhance the firmware start-up time and performance)
02753 */
02754  /**@{*/
02755 /*!
02756 @fn         NMI_API sint8 m2m_wifi_enable_firmware_logs(uint8 u8Enable);
02757 @param [in] u8Enable
02758             Set 1 to enable the logs, 0 for disable
02759 @pre        Must be called after intialization through the following function @ref m2m_wifi_init
02760 @sa         __DISABLE_FIRMWARE_LOGS__ (build option to disable logs from initializations)
02761             m2m_wifi_init
02762 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.     
02763 */
02764 sint8 m2m_wifi_enable_firmware_logs(uint8 u8Enable);
02765   /**@}*/
02766  /** @defgroup WifiSetBatteryVoltage m2m_wifi_set_battery_voltage
02767 *   @ingroup WLANAPI
02768 *   Set the battery voltage to update the firmware calculations
02769 */
02770  /**@{*/
02771 /*!
02772 @fn         NMI_API sint8 m2m_wifi_set_battery_voltage(uint8 u8BattVolt)
02773 @brief      Set the battery voltage to update the firmware calculations
02774 @param [in] dbBattVolt
02775             Battery Volt in double
02776 @pre        Must be called after intialization through the following function @ref m2m_wifi_init
02777 @sa             m2m_wifi_init
02778 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02779 */
02780 sint8 m2m_wifi_set_battery_voltage(uint16 u16BattVoltx100);
02781   /**@}*/
02782  /** @defgroup WifiSetGains m2m_wifi_set_gains
02783 *   @ingroup WLANAPI
02784 *   Set the chip gains mainly (PPA for 11b/11gn)
02785 */
02786  /**@{*/
02787 /*!
02788 @fn         sint8 m2m_wifi_set_gains(tstrM2mWifiGainsParams* pstrM2mGain);
02789 @brief      Set the chip PPA gain for 11b/11gn
02790 @param [in] pstrM2mGain
02791             tstrM2mWifiGainsParams contain gain parmaters as implemnted in rf document 
02792 @pre        Must be called after intialization through the following function @ref m2m_wifi_init
02793 @sa             m2m_wifi_init
02794 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02795 */
02796 sint8 m2m_wifi_set_gains(tstrM2mWifiGainsParams* pstrM2mGain);
02797  /**@}*/
02798 /** @defgroup WifiGetFirmwareVersion m2m_wifi_get_firmware_version
02799 *   @ingroup WLANAPI
02800 *  Get Firmware version info as defined in the structure @ref tstrM2mRev.
02801 */
02802  /**@{*/
02803 /*!
02804 @fn     m2m_wifi_get_firmware_version(tstrM2mRev* pstrRev)
02805 @param [out]    M2mRev
02806                Pointer to the structure @ref tstrM2mRev that contains the firmware version parameters
02807 @pre        Must be called after intialization through the following function @ref m2m_wifi_init
02808 @sa             m2m_wifi_init
02809 @return     The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02810 */
02811 sint8 m2m_wifi_get_firmware_version(tstrM2mRev *pstrRev);
02812 /**@}*/
02813 #ifdef ETH_MODE
02814 /** @defgroup WifiEnableMacMcastFn m2m_wifi_enable_mac_mcast
02815  *   @ingroup WLANAPI
02816  *   Synchronous function for filtering received MAC addresses from certain MAC address groups.
02817  *   This function allows the addtion/removal of certain MAC addresses, used in the multicast filter.
02818  */
02819  /**@{*/
02820 /*!
02821  * @fn             NMI_API sint8 m2m_wifi_enable_mac_mcast(uint8 *, uint8);
02822  * @brief        
02823  * @param [in]     pu8MulticastMacAddress
02824  *                        Pointer to MAC address
02825  * @param [in]     u8AddRemove
02826  *                        A flag to add or remove the MAC ADDRESS, based on the following values:
02827  *                        -  0 : remove MAC address
02828  *                        -  1 : add MAC address    
02829  * @warning    This function is available in ETHERNET/bypass mode ONLY. Make sure that the application defines @ref ETH_MODE.\n  
02830  * @note         Maximum number of MAC addresses that could be added is 8.
02831  * @sa      m2m_wifi_set_receive_buffer, m2m_wifi_send_ethernet_pkt
02832  * @return       The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02833  */
02834 NMI_API sint8 m2m_wifi_enable_mac_mcast(uint8* pu8MulticastMacAddress, uint8 u8AddRemove);
02835 /**@}*/
02836 /** @defgroup SetReceiveBufferFn m2m_wifi_set_receive_buffer
02837  *   @ingroup WLANAPI
02838  *    Synchronous function for setting or modifying the receiver buffer's length. 
02839  *    In the ETHERNET/bypass mode the application should define a callback of type @ref tpfAppEthCb, through which the application handles the received 
02840  *    ethernet frames. It is through this callback function that the user can dynamically modify the length of the currently used receiver buffer.
02841  *@{*/
02842 /*!
02843  * @fn             NMI_API sint8 m2m_wifi_set_receive_buffer(void *, uint16);
02844      
02845  * @param [in]     pvBuffer
02846  *                 Pointer to Buffer to receive data.
02847  *           NULL pointer causes a negative error @ref M2M_ERR_FAIL.
02848  *
02849  * @param [in]     u16BufferLen
02850  *                 Length of data to be received.  Maximum length of data should not exceed the size defined by TCP/IP
02851  *               defined as @ref SOCKET_BUFFER_MAX_LENGTH
02852  *           
02853  * @warning      This function is available in the Ethernet/bypass mode ONLY. Make sure that the application defines @ref ETH_MODE.\n 
02854  * @sa      m2m_wifi_enable_mac_mcast,m2m_wifi_send_ethernet_pkt    
02855  * @return       The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02856  */
02857 NMI_API sint8 m2m_wifi_set_receive_buffer(void* pvBuffer,uint16 u16BufferLen);
02858 /**@}*/
02859 #endif /* ETH_MODE */
02860 /** @defgroup GetPrngBytes m2m_wifi_prng_get_random_bytes
02861  *   @ingroup WLANAPI
02862  *    Asynchronous function for retrieving from the firmware a pseudo-random set of bytes as specifed in the size passed in as a parameter.
02863  *    The registered wifi-cb function retrieves the random bytes through the response @ref M2M_WIFI_RESP_GET_PRNG 
02864  *@{*/
02865 /*!
02866  * @fn                  sint8 m2m_wifi_prng_get_random_bytes(uint8 * pu8PRNGBuff,uint16 u16PRNGSize)
02867  * @param [out]      pu8PrngBuff
02868  *                      Pointer to a buffer to receive data.
02869  * @param [in]      u16PrngSize
02870  *              Request size in bytes  
02871  *@warning      Size greater than the maximum specified (@ref M2M_BUFFER_MAX_SIZE - sizeof(tstrPrng))
02872  *              causes a negative error @ref M2M_ERR_FAIL.
02873  *@see              tstrPrng    
02874  * @return          The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
02875  */
02876 sint8 m2m_wifi_prng_get_random_bytes(uint8 * pu8PrngBuff,uint16 u16PrngSize);
02877 /**@}*/
02878 #ifdef __cplusplus
02879 }
02880 #endif
02881 #endif /* __M2M_WIFI_H__ */
02882 
02883 
02884