wlan.h

00001 /*****************************************************************************
00002 *
00003 *  wlan.h  - CC3000 Host Driver Implementation.
00004 *  Copyright (C) 2011 Texas Instruments Incorporated - http://www.ti.com/
00005 *
00006 *  Redistribution and use in source and binary forms, with or without
00007 *  modification, are permitted provided that the following conditions
00008 *  are met:
00009 *
00010 *    Redistributions of source code must retain the above copyright
00011 *    notice, this list of conditions and the following disclaimer.
00012 *
00013 *    Redistributions in binary form must reproduce the above copyright
00014 *    notice, this list of conditions and the following disclaimer in the
00015 *    documentation and/or other materials provided with the   
00016 *    distribution.
00017 *
00018 *    Neither the name of Texas Instruments Incorporated nor the names of
00019 *    its contributors may be used to endorse or promote products derived
00020 *    from this software without specific prior written permission.
00021 *
00022 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00023 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00024 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00025 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
00026 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
00027 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
00028 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00029 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00030 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
00031 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
00032 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00033 *
00034 *****************************************************************************/
00035 #ifndef __WLAN_H__
00036 #define    __WLAN_H__
00037 
00038 #include "cc3000_common.h"
00039 
00040 //*****************************************************************************
00041 //
00042 // If building with a C++ compiler, make all of the definitions in this header
00043 // have a C binding.
00044 //
00045 //*****************************************************************************
00046 #ifdef    __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 #define      WLAN_SEC_UNSEC (0)
00051 #define      WLAN_SEC_WEP    (1)
00052 #define      WLAN_SEC_WPA    (2)
00053 #define      WLAN_SEC_WPA2    (3)
00054 //*****************************************************************************
00055 //
00056 //! \addtogroup wlan_api
00057 //! @{
00058 //
00059 //*****************************************************************************
00060 
00061 
00062 //*****************************************************************************
00063 //
00064 //!  wlan_init
00065 //!
00066 //!  @param  sWlanCB   Asynchronous events callback.  
00067 //!                    0 no event call back.
00068 //!                  -call back parameters:
00069 //!                   1) event_type: HCI_EVNT_WLAN_UNSOL_CONNECT connect event,
00070 //!                     HCI_EVNT_WLAN_UNSOL_DISCONNECT disconnect event,
00071 //!                     HCI_EVNT_WLAN_ASYNC_SIMPLE_CONFIG_DONE config done,
00072 //!                     HCI_EVNT_WLAN_UNSOL_DHCP dhcp report, 
00073 //!                     HCI_EVNT_WLAN_ASYNC_PING_REPORT ping report OR 
00074 //!                     HCI_EVNT_WLAN_KEEPALIVE keepalive.
00075 //!                   2) data: pointer to extra data that received by the event
00076 //!                     (NULL no data).
00077 //!                   3) length: data length.
00078 //!                  -Events with extra data:
00079 //!                     HCI_EVNT_WLAN_UNSOL_DHCP: 4 bytes IP, 4 bytes Mask, 
00080 //!                     4 bytes default gateway, 4 bytes DHCP server and 4 bytes
00081 //!                     for DNS server.
00082 //!                     HCI_EVNT_WLAN_ASYNC_PING_REPORT: 4 bytes Packets sent, 
00083 //!                     4 bytes Packets received, 4 bytes Min round time, 
00084 //!                     4 bytes Max round time and 4 bytes for Avg round time.
00085 //!
00086 //!  @param    sFWPatches  0 no patch or pointer to FW patches 
00087 //!  @param    sDriverPatches  0 no patch or pointer to driver patches
00088 //!  @param    sBootLoaderPatches  0 no patch or pointer to bootloader patches
00089 //!  @param    sReadWlanInterruptPin    init callback. the callback read wlan 
00090 //!            interrupt status.
00091 //!  @param    sWlanInterruptEnable   init callback. the callback enable wlan 
00092 //!            interrupt.
00093 //!  @param    sWlanInterruptDisable   init callback. the callback disable wlan
00094 //!            interrupt.
00095 //!  @param    sWriteWlanPin      init callback. the callback write value 
00096 //!            to device pin.  
00097 //!
00098 //!  @return   none
00099 //!
00100 //!  @sa       wlan_set_event_mask , wlan_start , wlan_stop 
00101 //!
00102 //!  @brief    Initialize wlan driver
00103 //!
00104 //!  @warning This function must be called before ANY other wlan driver function
00105 //
00106 //*****************************************************************************
00107 extern void wlan_init(        tWlanCB         sWlanCB,
00108                    tFWPatches sFWPatches,
00109                    tDriverPatches sDriverPatches,
00110                    tBootLoaderPatches sBootLoaderPatches,
00111                 tWlanReadInteruptPin  sReadWlanInterruptPin,
00112                 tWlanInterruptEnable  sWlanInterruptEnable,
00113                 tWlanInterruptDisable sWlanInterruptDisable,
00114                 tWriteWlanPin         sWriteWlanPin);
00115 
00116 
00117 
00118 //*****************************************************************************
00119 //
00120 //!  wlan_start
00121 //!
00122 //!  @param   usPatchesAvailableAtHost -  flag to indicate if patches available
00123 //!                                    from host or from EEPROM. Due to the 
00124 //!                                    fact the patches are burn to the EEPROM
00125 //!                                    using the patch programmer utility, the 
00126 //!                                    patches will be available from the EEPROM
00127 //!                                    and not from the host.
00128 //!
00129 //!  @return        none
00130 //!
00131 //!  @brief        Start WLAN device. This function asserts the enable pin of 
00132 //!                the device (WLAN_EN), starting the HW initialization process.
00133 //!                The function blocked until device Initialization is completed.
00134 //!                Function also configure patches (FW, driver or bootloader) 
00135 //!                and calls appropriate device callbacks.
00136 //!
00137 //!  @Note          Prior calling the function wlan_init shall be called.
00138 //!  @Warning       This function must be called after wlan_init and before any 
00139 //!                 other wlan API
00140 //!  @sa            wlan_init , wlan_stop
00141 //!
00142 //
00143 //*****************************************************************************
00144 extern void wlan_start(unsigned short usPatchesAvailableAtHost);
00145 
00146 //*****************************************************************************
00147 //
00148 //!  wlan_stop
00149 //!
00150 //!  @param         none
00151 //!
00152 //!  @return        none
00153 //!
00154 //!  @brief         Stop WLAN device by putting it into reset state.
00155 //!
00156 //!  @sa            wlan_start
00157 //
00158 //*****************************************************************************
00159 extern void wlan_stop(void);
00160 
00161 //*****************************************************************************
00162 //
00163 //!  wlan_connect
00164 //!
00165 //!  @param    sec_type   security options:
00166 //!               WLAN_SEC_UNSEC, 
00167 //!               WLAN_SEC_WEP (ASCII support only),
00168 //!               WLAN_SEC_WPA or WLAN_SEC_WPA2
00169 //!  @param    ssid       up to 32 bytes and is ASCII SSID of the AP
00170 //!  @param    ssid_len   length of the SSID
00171 //!  @param    bssid      6 bytes specified the AP bssid
00172 //!  @param    key        up to 16 bytes specified the AP security key
00173 //!  @param    key_len    key length 
00174 //!
00175 //!  @return     On success, zero is returned. On error, negative is returned. 
00176 //!              Note that even though a zero is returned on success to trigger
00177 //!              connection operation, it does not mean that CCC3000 is already
00178 //!              connected. An asynchronous "Connected" event is generated when 
00179 //!              actual association process finishes and CC3000 is connected to
00180 //!              the AP. If DHCP is set, An asynchronous "DHCP" event is 
00181 //!              generated when DHCP process is finish.
00182 //!              
00183 //!
00184 //!  @brief      Connect to AP
00185 //!  @warning    Please Note that when connection to AP configured with security
00186 //!              type WEP, please confirm that the key is set as ASCII and not
00187 //!              as HEX.
00188 //!  @sa         wlan_disconnect
00189 //
00190 //*****************************************************************************
00191 #ifndef CC3000_TINY_DRIVER
00192 extern long wlan_connect(unsigned long ulSecType, char *ssid, long ssid_len,
00193                         unsigned char *bssid, unsigned char *key, long key_len);
00194 #else
00195 extern long wlan_connect(char *ssid, long ssid_len);
00196 
00197 #endif
00198 
00199 //*****************************************************************************
00200 //
00201 //!  wlan_disconnect
00202 //!
00203 //!  @return    0 disconnected done, other CC3000 already disconnected            
00204 //!
00205 //!  @brief      Disconnect connection from AP. 
00206 //!
00207 //!  @sa         wlan_connect
00208 //
00209 //*****************************************************************************
00210 
00211 extern long wlan_disconnect(void);
00212 
00213 //*****************************************************************************
00214 //
00215 //!  wlan_add_profile
00216 //!
00217 //!  @param    ulSecType  WLAN_SEC_UNSEC,WLAN_SEC_WEP,WLAN_SEC_WPA,WLAN_SEC_WPA2
00218 //!  @param    ucSsid    ssid  SSID up to 32 bytes
00219 //!  @param    ulSsidLen ssid length
00220 //!  @param    ucBssid   bssid  6 bytes
00221 //!  @param    ulPriority ulPriority profile priority. Lowest priority:0.
00222 //!  @param    ulPairwiseCipher_Or_TxKeyLen  key length for WEP security
00223 //!  @param    ulGroupCipher_TxKeyIndex  key index
00224 //!  @param    ulKeyMgmt        KEY management 
00225 //!  @param    ucPf_OrKey       security key
00226 //!  @param    ulPassPhraseLen  security key length for WPA\WPA2
00227 //!
00228 //!  @return    On success, zero is returned. On error, -1 is returned        
00229 //!
00230 //!  @brief     When auto start is enabled, the device connects to
00231 //!             station from the profiles table. Up to 7 profiles are supported. 
00232 //!             If several profiles configured the device choose the highest 
00233 //!             priority profile, within each priority group, device will choose 
00234 //!             profile based on security policy, signal strength, etc 
00235 //!             parameters. All the profiles are stored in CC3000 NVMEM.
00236 //!
00237 //!  @sa        wlan_ioctl_del_profile 
00238 //
00239 //*****************************************************************************
00240 
00241 extern long wlan_add_profile(unsigned long ulSecType, unsigned char* ucSsid,
00242                                          unsigned long ulSsidLen, 
00243                                          unsigned char *ucBssid,
00244                                          unsigned long ulPriority,
00245                                          unsigned long ulPairwiseCipher_Or_Key,
00246                                          unsigned long ulGroupCipher_TxKeyLen,
00247                                          unsigned long ulKeyMgmt,
00248                                          unsigned char* ucPf_OrKey,
00249                                          unsigned long ulPassPhraseLen);
00250 
00251 
00252 
00253 //*****************************************************************************
00254 //
00255 //!  wlan_ioctl_del_profile
00256 //!
00257 //!  @param    index   number of profile to delete
00258 //!
00259 //!  @return    On success, zero is returned. On error, -1 is returned        
00260 //!
00261 //!  @brief     Delete WLAN profile 
00262 //!
00263 //!  @Note      In order to delete all stored profile, set index to 255.
00264 //!
00265 //!  @sa        wlan_add_profile 
00266 //
00267 //*****************************************************************************
00268 extern long wlan_ioctl_del_profile(unsigned long ulIndex);
00269 
00270 //*****************************************************************************
00271 //
00272 //!  wlan_set_event_mask
00273 //!
00274 //!  @param    mask   mask option:
00275 //!       HCI_EVNT_WLAN_UNSOL_CONNECT connect event
00276 //!       HCI_EVNT_WLAN_UNSOL_DISCONNECT disconnect event
00277 //!       HCI_EVNT_WLAN_ASYNC_SIMPLE_CONFIG_DONE  smart config done
00278 //!       HCI_EVNT_WLAN_UNSOL_INIT init done
00279 //!       HCI_EVNT_WLAN_UNSOL_DHCP dhcp event report
00280 //!       HCI_EVNT_WLAN_ASYNC_PING_REPORT ping report
00281 //!       HCI_EVNT_WLAN_KEEPALIVE keepalive
00282 //!       HCI_EVNT_WLAN_TX_COMPLETE - disable information on end of transmission
00283 //!         Saved: no.
00284 //!
00285 //!  @return    On success, zero is returned. On error, -1 is returned        
00286 //!
00287 //!  @brief    Mask event according to bit mask. In case that event is 
00288 //!            masked (1), the device will not send the masked event to host. 
00289 //
00290 //*****************************************************************************
00291 extern long wlan_set_event_mask(unsigned long ulMask);
00292 
00293 //*****************************************************************************
00294 //
00295 //!  wlan_ioctl_statusget
00296 //!
00297 //!  @param none 
00298 //!
00299 //!  @return    WLAN_STATUS_DISCONNECTED, WLAN_STATUS_SCANING, 
00300 //!             STATUS_CONNECTING or WLAN_STATUS_CONNECTED      
00301 //!
00302 //!  @brief    get wlan status: disconnected, scanning, connecting or connected
00303 //
00304 //*****************************************************************************
00305 extern long wlan_ioctl_statusget(void);
00306 
00307 
00308 //*****************************************************************************
00309 //
00310 //!  wlan_ioctl_set_connection_policy
00311 //!
00312 //!  @param    should_connect_to_open_ap  enable(1), disable(0) connect to any 
00313 //!            available AP. This parameter corresponds to the configuration of 
00314 //!            item # 3 in the brief description.
00315 //!  @param    should_use_fast_connect enable(1), disable(0). if enabled, tries 
00316 //!            to connect to the last connected AP. This parameter corresponds 
00317 //!            to the configuration of item # 1 in the brief description.
00318 //!  @param    auto_start enable(1), disable(0) auto connect 
00319 //!            after reset and periodically reconnect if needed. This 
00320 //!              configuration configures option 2 in the above description.
00321 //!
00322 //!  @return     On success, zero is returned. On error, -1 is returned        
00323 //!
00324 //!  @brief      When auto is enabled, the device tries to connect according 
00325 //!              the following policy:
00326 //!              1) If fast connect is enabled and last connection is valid, 
00327 //!                 the device will try to connect to it without the scanning 
00328 //!                 procedure (fast). The last connection will be marked as
00329 //!                 invalid, due to adding/removing profile. 
00330 //!              2) If profile exists, the device will try to connect it 
00331 //!                 (Up to seven profiles).
00332 //!              3) If fast and profiles are not found, and open mode is
00333 //!                 enabled, the device will try to connect to any AP.
00334 //!              * Note that the policy settings are stored in the CC3000 NVMEM.
00335 //!
00336 //!  @sa         wlan_add_profile , wlan_ioctl_del_profile 
00337 //
00338 //*****************************************************************************
00339 extern long wlan_ioctl_set_connection_policy(
00340                                         unsigned long should_connect_to_open_ap,
00341                                         unsigned long should_use_fast_connect,
00342                                         unsigned long ulUseProfiles);
00343 
00344 //*****************************************************************************
00345 //
00346 //!  wlan_ioctl_get_scan_results
00347 //!
00348 //!  @param[in]    scan_timeout   parameter not supported
00349 //!  @param[out]   ucResults  scan result (_wlan_full_scan_results_args_t)
00350 //!
00351 //!  @return    On success, zero is returned. On error, -1 is returned        
00352 //!
00353 //!  @brief    Gets entry from scan result table.
00354 //!            The scan results are returned one by one, and each entry 
00355 //!            represents a single AP found in the area. The following is a 
00356 //!            format of the scan result: 
00357 //!             - 4 Bytes: number of networks found
00358 //!          - 4 Bytes: The status of the scan: 0 - aged results,
00359 //!                     1 - results valid, 2 - no results
00360 //!          - 42 bytes: Result entry, where the bytes are arranged as  follows:
00361 //!              
00362 //!                          - 1 bit isValid - is result valid or not
00363 //!                         - 7 bits rssi - RSSI value;     
00364 //!                 - 2 bits: securityMode - security mode of the AP:
00365 //!                           0 - Open, 1 - WEP, 2 WPA, 3 WPA2
00366 //!                         - 6 bits: SSID name length
00367 //!                         - 2 bytes: the time at which the entry has entered into 
00368 //!                            scans result table
00369 //!                         - 32 bytes: SSID name
00370 //!                 - 6 bytes:    BSSID 
00371 //!
00372 //!  @Note      scan_timeout, is not supported on this version.
00373 //!
00374 //!  @sa        wlan_ioctl_set_scan_params 
00375 //
00376 //*****************************************************************************
00377 
00378 
00379 extern long wlan_ioctl_get_scan_results(unsigned long ulScanTimeout,
00380                                        unsigned char *ucResults);
00381 
00382 //*****************************************************************************
00383 //
00384 //!  wlan_ioctl_set_scan_params
00385 //!
00386 //!  @param    uiEnable - start/stop application scan: 
00387 //!            1 = start scan with default interval value of 10 min. 
00388 //!            in order to set a different scan interval value apply the value 
00389 //!            in milliseconds. minimum 1 second. 0=stop). Wlan reset
00390 //!           (wlan_stop() wlan_start()) is needed when changing scan interval
00391 //!            value. Saved: No
00392 //!  @param   uiMinDwellTime   minimum dwell time value to be used for each 
00393 //!           channel, in milliseconds. Saved: yes
00394 //!           Recommended Value: 100 (Default: 20)
00395 //!  @param   uiMaxDwellTime    maximum dwell time value to be used for each
00396 //!           channel, in milliseconds. Saved: yes
00397 //!           Recommended Value: 100 (Default: 30)
00398 //!  @param   uiNumOfProbeRequests  max probe request between dwell time. 
00399 //!           Saved: yes. Recommended Value: 5 (Default:2)
00400 //!  @param   uiChannelMask  bitwise, up to 13 channels (0x1fff). 
00401 //!           Saved: yes. Default: 0x7ff
00402 //!  @param   uiRSSIThreshold   RSSI threshold. Saved: yes (Default: -80)
00403 //!  @param   uiSNRThreshold    NSR threshold. Saved: yes (Default: 0)
00404 //!  @param   uiDefaultTxPower  probe Tx power. Saved: yes (Default: 205)
00405 //!  @param   aiIntervalList    pointer to array with 16 entries (16 channels) 
00406 //!           each entry (unsigned long) holds timeout between periodic scan 
00407 //!           (connection scan) - in milliseconds. Saved: yes. Default 2000ms.
00408 //!
00409 //!  @return    On success, zero is returned. On error, -1 is returned        
00410 //!
00411 //!  @brief    start and stop scan procedure. Set scan parameters. 
00412 //!
00413 //!  @Note     uiDefaultTxPower, is not supported on this version.
00414 //!
00415 //!  @sa        wlan_ioctl_get_scan_results 
00416 //
00417 //*****************************************************************************
00418 extern long wlan_ioctl_set_scan_params(unsigned long uiEnable, unsigned long 
00419                                              uiMinDwellTime,unsigned long uiMaxDwellTime,
00420                                            unsigned long uiNumOfProbeRequests,
00421                                              unsigned long uiChannelMask,
00422                                            long iRSSIThreshold,unsigned long uiSNRThreshold,
00423                                            unsigned long uiDefaultTxPower, 
00424                                              unsigned long *aiIntervalList);
00425 
00426                                            
00427 //*****************************************************************************
00428 //
00429 //!  wlan_smart_config_start
00430 //!
00431 //!  @param    algoEncryptedFlag indicates whether the information is encrypted
00432 //!
00433 //!  @return   On success, zero is returned. On error, -1 is returned        
00434 //!
00435 //!  @brief   Start to acquire device profile. The device acquire its own 
00436 //!           profile, if profile message is found. The acquired AP information
00437 //!           is stored in CC3000 EEPROM only in case AES128 encryption is used.
00438 //!           In case AES128 encryption is not used, a profile is created by 
00439 //!           CC3000 internally.
00440 //!
00441 //!  @Note    An asynchronous event - Smart Config Done will be generated as soon
00442 //!           as the process finishes successfully.
00443 //!
00444 //!  @sa      wlan_smart_config_set_prefix , wlan_smart_config_stop
00445 //
00446 //*****************************************************************************                                        
00447 extern long wlan_smart_config_start(unsigned long algoEncryptedFlag);
00448 
00449 
00450 //*****************************************************************************
00451 //
00452 //!  wlan_smart_config_stop
00453 //!
00454 //!  @param    algoEncryptedFlag indicates whether the information is encrypted
00455 //!
00456 //!  @return   On success, zero is returned. On error, -1 is returned        
00457 //!
00458 //!  @brief   Stop the acquire profile procedure 
00459 //!
00460 //!  @sa      wlan_smart_config_start , wlan_smart_config_set_prefix
00461 //
00462 //*****************************************************************************
00463 extern long wlan_smart_config_stop(void);
00464 
00465 //*****************************************************************************
00466 //
00467 //!  wlan_smart_config_set_prefix
00468 //!
00469 //!  @param   newPrefix  3 bytes identify the SSID prefix for the Smart Config. 
00470 //!
00471 //!  @return   On success, zero is returned. On error, -1 is returned        
00472 //!
00473 //!  @brief   Configure station ssid prefix. The prefix is used internally 
00474 //!           in CC3000. It should always be TTT.
00475 //!
00476 //!  @Note    The prefix is stored in CC3000 NVMEM
00477 //!
00478 //!  @sa      wlan_smart_config_start , wlan_smart_config_stop
00479 //
00480 //*****************************************************************************
00481 extern long wlan_smart_config_set_prefix(char* cNewPrefix);
00482 
00483 //*****************************************************************************
00484 //
00485 //!  wlan_smart_config_process
00486 //!
00487 //!  @param   none 
00488 //!
00489 //!  @return   On success, zero is returned. On error, -1 is returned        
00490 //!
00491 //!  @brief   process the acquired data and store it as a profile. The acquired 
00492 //!           AP information is stored in CC3000 EEPROM encrypted.
00493 //!           The encrypted data is decrypted and stored as a profile.
00494 //!           behavior is as defined by connection policy.
00495 //
00496 //*****************************************************************************
00497 extern long wlan_smart_config_process(void);
00498 
00499 //*****************************************************************************
00500 //
00501 // Close the Doxygen group.
00502 //! @}
00503 //
00504 //*****************************************************************************
00505 
00506 
00507 
00508 //*****************************************************************************
00509 //
00510 // Mark the end of the C bindings section for C++ compilers.
00511 //
00512 //*****************************************************************************
00513 #ifdef    __cplusplus
00514 }
00515 #endif // __cplusplus
00516 
00517 #endif    // __WLAN_H__
00518