Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Scanning

         Here are listed all the functions that implement the Wifi Scanning APIs.

Functions

uint8 m2m_wifi_get_num_ap_found (void)
 Reads the number of AP's found in the last Scan Request, The function read the number of AP's from global variable which updated in the wifi_cb in M2M_WIFI_RESP_SCAN_DONE. More...
 
sint8 m2m_wifi_req_scan_result (uint8 index)
 Reads the AP information from the Scan Result list with the given index, the response received in wifi_cb M2M_WIFI_RESP_SCAN_RESULT, the response pointer should be casted with tstrM2mWifiscanResult structure. More...
 
sint8 m2m_wifi_request_scan (uint8 ch)
 Asynchronous API to request the WINC IC to scan for networks. More...
 
sint8 m2m_wifi_request_scan_passive (uint8 ch, uint16 scan_time)
 Similar to m2m_wifi_request_scan but performs passive scanning instead of active scanning. More...
 
sint8 m2m_wifi_request_scan_ssid_list (uint8 ch, uint8 *u8Ssidlist)
 Asynchronous wi-fi scan request on the given channel and the hidden scan list. More...
 
sint8 m2m_wifi_set_scan_options (tstrM2MScanOption *ptstrM2MScanOption)
 Synchronous API for configuring the behaviour of the WINC IC's network scanning functions. More...
 
sint8 m2m_wifi_set_scan_region (uint16 ScanRegion)
 Synchronous API for configuring the regulatory restrictions that may affect the WINC ICs scanning behaviour. More...
 
sint8 m2m_wifi_set_stop_scan_on_first (uint8 u8StopScanOption)
 Synchronous API for enabling/disabling the stop scan on first result of the WINC IC's network scanning functions. More...
 

NMI_API uint8 m2m_wifi_get_num_ap_found ( void  )

Reads the number of AP's found in the last Scan Request, The function read the number of AP's from global variable which updated in the wifi_cb in M2M_WIFI_RESP_SCAN_DONE.

Synchronous function to retrieve the number of AP's found during the last scan operation.

See Also
m2m_wifi_request_scan
Returns
Return the number of AP's found in the last Scan Request.
Precondition
m2m_wifi_request_scan need to be called first
Warning
That function need to be called in the wifi_cb in M2M_WIFI_RESP_SCAN_DONE, calling that function in any other place will return undefined/undated numbers. Function used only in STA mode only.
The function reads the number of APs from global variable which was updated in the Wi-Fi 
callback function through the @ref M2M_WIFI_RESP_SCAN_DONE event.
Function used only in STA mode only. 
See Also
m2m_wifi_request_scan M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT
Precondition
m2m_wifi_request_scan must be called first to ensure up to date results are available.
  • A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback is done through passing it to the m2m_wifi_init.
  • The event M2M_WIFI_RESP_SCAN_DONE must be handled in the callback to receive the requested scan information.
Warning
This function must be called only in the wi-fi callback function when the events M2M_WIFI_RESP_SCAN_DONE or M2M_WIFI_RESP_SCAN_RESULT are received. Calling this function in any other place will result in undefined/outdated numbers.
Returns
Return the number of AP's found in the last Scan Request.

Example

The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response.

#include "m2m_wifi.h"
#include "m2m_types.h"
void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
static uint8 u8ScanResultIdx = 0;
switch(u8WiFiEvent)
{
{
tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
if(pstrInfo->s8ScanState == M2M_SUCCESS)
{
u8ScanResultIdx = 0;
if(pstrInfo->u8NumofCh >= 1)
{
m2m_wifi_req_scan_result(u8ScanResultIdx);
u8ScanResultIdx ++;
}
else
{
printf("No AP Found Rescan\n");
}
}
else
{
printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
}
}
break;
{
tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found();
printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
pstrScanResult->u8index,pstrScanResult->s8rssi,
pstrScanResult->u8AuthType,
pstrScanResult->u8ch,
pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
pstrScanResult->au8SSID);
if(u8ScanResultIdx < u8NumFoundAPs)
{
// Read the next scan result
u8ScanResultIdx ++;
}
}
break;
default:
break;
}
}
int main()
{
param.pfAppWifiCb = wifi_event_cb;
if(!m2m_wifi_init(&param))
{
// Scan all channels
while(1)
{
}
}
}

References gu8ChNum.

Referenced by wifi_cb().

NMI_API sint8 m2m_wifi_req_scan_result ( uint8  index)

Reads the AP information from the Scan Result list with the given index, the response received in wifi_cb M2M_WIFI_RESP_SCAN_RESULT, the response pointer should be casted with tstrM2mWifiscanResult structure.

Synchronous call to read the AP information from the SCAN Result list.

Parameters
[in]indexIndex for the requested result, the index range start from 0 till number of AP's found
See Also
tstrM2mWifiscanResult,m2m_wifi_get_num_ap_found,m2m_wifi_request_scan
Returns
The function shall return M2M_SUCCESS for success and a negative value otherwise
Precondition
m2m_wifi_request_scan need to be called first, then m2m_wifi_get_num_ap_found to get the number of AP's found
Warning
Function used only in STA mode only. the scan result updated only if scan request called, else it will be cashed in firmware for the host scan request result, which mean if large delay occur between the scan request and the scan result request, the result will not be up-to-date
Synchronous call to read the AP information from the SCAN Result list with the given index.
This function is expected to be called when the response events @ref M2M_WIFI_RESP_SCAN_RESULT or
@ref M2M_WIFI_RESP_SCAN_DONE are received in the wi-fi callback function.
The response information received can be obtained through the casting to the 
@ref tstrM2mWifiscanResult structure.
Parameters
[in]indexIndex for the requested result, the index range start from 0 till number of AP's found.
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
See Also
tstrM2mWifiscanResult m2m_wifi_get_num_ap_found m2m_wifi_request_scan
Precondition
  • m2m_wifi_request_scan needs to be called first, then m2m_wifi_get_num_ap_found to get the number of AP's found.
  • A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the m2m_wifi_init function.
  • The event M2M_WIFI_RESP_SCAN_RESULT must be handled in the callback to receive the requested scan information.
Warning
  • Function used in STA mode only. the scan results are updated only if the scan request is called.
  • Calling this function only without a scan request will lead to firmware errors.
  • Application code should refrain from introducing a large delay between the scan request and the scan result request, to prevent errors occurring.

Example

The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response.

#include "m2m_wifi.h"
#include "m2m_types.h"
void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
static uint8 u8ScanResultIdx = 0;
switch(u8WiFiEvent)
{
{
tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
if(pstrInfo->s8ScanState == M2M_SUCCESS)
{
u8ScanResultIdx = 0;
if(pstrInfo->u8NumofCh >= 1)
{
m2m_wifi_req_scan_result(u8ScanResultIdx);
u8ScanResultIdx ++;
}
else
{
printf("No AP Found Rescan\n");
}
}
else
{
printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
}
}
break;
{
tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found();
printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
pstrScanResult->u8index,pstrScanResult->s8rssi,
pstrScanResult->u8AuthType,
pstrScanResult->u8ch,
pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
pstrScanResult->au8SSID);
if(u8ScanResultIdx < u8NumFoundAPs)
{
// Read the next scan result
u8ScanResultIdx ++;
}
}
break;
default:
break;
}
}
int main()
{
param.pfAppWifiCb = wifi_event_cb;
if(!m2m_wifi_init(&param))
{
// Scan all channels
while(1)
{
}
}
}

References hif_send(), M2M_REQ_GROUP_WIFI, M2M_SUCCESS, M2M_WIFI_REQ_SCAN_RESULT, NULL, and tstrM2mReqScanResult::u8Index.

Referenced by wifi_cb().

NMI_API sint8 m2m_wifi_request_scan ( uint8  ch)

Asynchronous API to request the WINC IC to scan for networks.

Scan statuses are delivered to the application via the Wi-Fi event callback (@ref tpfAppWifiCb) in
three stages. The first step involves the event @ref M2M_WIFI_RESP_SCAN_DONE which, if successful,
provides the number of detected networks (access points). The application must then read the list
of access points via multiple calls to the asynchronous @ref m2m_wifi_req_scan_result API. For
each call to this function, the application will receive (step three) the event
@ref M2M_WIFI_RESP_SCAN_RESULT.
Parameters
[in]chRF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh, with a value of M2M_WIFI_CH_ALL to scan all channels.
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
Precondition
Warning
This API is valid only for STA mode, it may be called regardless of connection state (connected or disconnected states).
See Also
M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT tpfAppWifiCb tstrM2mWifiscanResult tenuM2mScanCh m2m_wifi_init m2m_wifi_handle_events m2m_wifi_req_scan_result

Example

The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response.

#include "m2m_wifi.h"
#include "m2m_types.h"
void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
static uint8 u8ScanResultIdx = 0;
switch(u8WiFiEvent)
{
{
tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
if(pstrInfo->s8ScanState == M2M_SUCCESS)
{
u8ScanResultIdx = 0;
if(pstrInfo->u8NumofCh >= 1)
{
m2m_wifi_req_scan_result(u8ScanResultIdx);
u8ScanResultIdx ++;
}
else
{
printf("No AP Found Rescan\n");
}
}
else
{
printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
}
}
break;
{
tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found();
printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
pstrScanResult->u8index,pstrScanResult->s8rssi,
pstrScanResult->u8AuthType,
pstrScanResult->u8ch,
pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
pstrScanResult->au8SSID);
if(u8ScanResultIdx < u8NumFoundAPs)
{
// Read the next scan result
u8ScanResultIdx ++;
}
}
break;
default:
break;
}
}
int main()
{
param.pfAppWifiCb = wifi_event_cb;
if(!m2m_wifi_init(&param))
{
// Scan all channels
while(1)
{
}
}
}

References gu8scanInProgress, hif_send(), M2M_ERR_INVALID_ARG, M2M_ERR_SCAN_IN_PROGRESS, M2M_REQ_GROUP_WIFI, M2M_SUCCESS, M2M_WIFI_CH_1, M2M_WIFI_CH_14, M2M_WIFI_CH_ALL, M2M_WIFI_REQ_SCAN, NULL, and tstrM2MScan::u8ChNum.

Referenced by main(), and wifi_cb().

NMI_API sint8 m2m_wifi_request_scan_passive ( uint8  ch,
uint16  scan_time 
)

Similar to m2m_wifi_request_scan but performs passive scanning instead of active scanning.

Parameters
[in]chRF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh. With a value of M2M_WIFI_CH_ALL, means to scan all channels.
[in]scan_timeThe time in ms that passive scan is listening for beacons on each channel per one slot, enter 0 for default setting.
Warning
This function is not allowed in AP mode. It works only for STA mode (both connected or disconnected states).
Precondition
See Also
M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT tpfAppWifiCb tstrM2mWifiscanResult tenuM2mScanCh m2m_wifi_init m2m_wifi_request_scan m2m_wifi_handle_events m2m_wifi_req_scan_result
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.

References gu8scanInProgress, hif_send(), M2M_ERR_INVALID_ARG, M2M_ERR_SCAN_IN_PROGRESS, M2M_REQ_GROUP_WIFI, M2M_SUCCESS, M2M_WIFI_CH_1, M2M_WIFI_CH_14, M2M_WIFI_CH_ALL, M2M_WIFI_REQ_PASSIVE_SCAN, NULL, tstrM2MScan::u16PassiveScanTime, and tstrM2MScan::u8ChNum.

NMI_API sint8 m2m_wifi_request_scan_ssid_list ( uint8  ch,
uint8 u8SsidList 
)

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
is to read the scan results sequentially. 
The number of  APs found (N) is returned in event @ref M2M_WIFI_RESP_SCAN_DONE with the number of found
APs.
The application could read the list of APs by calling the function @ref m2m_wifi_req_scan_result N times.
Parameters
[in]chRF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh. With a value of M2M_WIFI_CH_ALL, means to scan all channels.
[in]u8SsidListu8SsidList is a buffer containing a list of hidden SSIDs to include during the scan. The first byte in the buffer, u8SsidList[0], is the number of SSIDs encoded in the string. The number of hidden SSIDs cannot exceed MAX_HIDDEN_SITES. All SSIDs are concatenated in the following bytes and each SSID is prefixed with a one-byte header containing its length. The total number of bytes in u8SsidList buffer, including length byte, cannot exceed 133 bytes (MAX_HIDDEN_SITES SSIDs x 32 bytes each, which is max SSID length). For instance, encoding the two hidden SSIDs "DEMO_AP" and "TEST" results in the following buffer content:
uint8 u8SsidList[14];
u8SsidList[0] = 2; // Number of SSIDs is 2
u8SsidList[1] = 7; // Length of the string "DEMO_AP" without NULL termination
memcpy(&u8SsidList[2], "DEMO_AP", 7); // Bytes index 2-9 containing the string DEMO_AP
u8SsidList[9] = 4; // Length of the string "TEST" without NULL termination
memcpy(&u8SsidList[10], "TEST", 4); // Bytes index 10-13 containing the string TEST
Note
It works with STA/AP mode (connected or disconnected).
Precondition
See Also
M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT tpfAppWifiCb tstrM2mWifiscanResult tenuM2mScanCh m2m_wifi_init m2m_wifi_handle_events m2m_wifi_req_scan_result
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.

Example

The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of the events received in response.

#include "m2m_wifi.h"
#include "m2m_types.h"
static void request_scan_hidden_demo_ap(void);
void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
static uint8 u8ScanResultIdx = 0;
switch(u8WiFiEvent)
{
{
tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
if(pstrInfo->s8ScanState == M2M_SUCCESS)
{
u8ScanResultIdx = 0;
if(pstrInfo->u8NumofCh >= 1)
{
m2m_wifi_req_scan_result(u8ScanResultIdx);
u8ScanResultIdx ++;
}
else
{
printf("No AP Found Rescan\n");
request_scan_hidden_demo_ap();
}
}
else
{
printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
}
}
break;
{
tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
uint8 u8NumFoundAPs = m2m_wifi_get_num_ap_found();
printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
pstrScanResult->u8index,pstrScanResult->s8rssi,
pstrScanResult->u8AuthType,
pstrScanResult->u8ch,
pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
pstrScanResult->au8SSID);
if(u8ScanResultIdx < u8NumFoundAPs)
{
// Read the next scan result
u8ScanResultIdx ++;
}
}
break;
default:
break;
}
}
static void request_scan_hidden_demo_ap(void)
{
uint8 list[9];
char ssid[] = "DEMO_AP";
uint8 len = (uint8)(sizeof(ssid)-1);
list[0] = 1;
list[1] = len;
memcpy(&list[2], ssid, len); // copy 7 bytes
// Scan all channels
}
int main()
{
param.pfAppWifiCb = wifi_event_cb;
if(!m2m_wifi_init(&param))
{
request_scan_hidden_demo_ap();
while(1)
{
}
}
}

References gu8scanInProgress, hif_send(), M2M_ERR_INVALID_ARG, M2M_ERR_SCAN_IN_PROGRESS, M2M_MAX_SSID_LEN, M2M_REQ_DATA_PKT, M2M_REQ_GROUP_WIFI, M2M_SUCCESS, M2M_WIFI_CH_1, M2M_WIFI_CH_14, M2M_WIFI_CH_ALL, M2M_WIFI_REQ_SCAN_SSID_LIST, MAX_HIDDEN_SITES, NULL, and tstrM2MScan::u8ChNum.

sint8 m2m_wifi_set_scan_options ( tstrM2MScanOption ptstrM2MScanOption)

Synchronous API for configuring the behaviour of the WINC IC's network scanning functions.

This function sets the configuration parameters for the scan operation.
Parameters
[in]ptstrM2MScanOption;Pointer to the structure holding the Scan Parameters.
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
See Also
tenuM2mScanCh m2m_wifi_request_scan tstrM2MScanOption

References hif_send(), M2M_ERR_FAIL, M2M_REQ_GROUP_WIFI, M2M_SUCCESS, m2m_validate_scan_options(), M2M_WIFI_REQ_SET_SCAN_OPTION, and NULL.

sint8 m2m_wifi_set_scan_region ( uint16  ScanRegion)

Synchronous API for configuring the regulatory restrictions that may affect the WINC ICs scanning behaviour.

This function sets a property called the scan region, a parameter that affects the range of 
channels that the WINC IC may legally scan given a geographic region.

For 2.4GHz, supported in the current release, the requested scan region can't exceed the
maximum number of channels (14).
Parameters
[in]ScanRegionASIA NORTH_AMERICA
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
See Also
tenuM2mScanCh m2m_wifi_request_scan

References hif_send(), M2M_ERR_FAIL, M2M_REQ_GROUP_WIFI, M2M_WIFI_REQ_SET_SCAN_REGION, NULL, and tstrM2MScanRegion::u16ScanRegion.

sint8 m2m_wifi_set_stop_scan_on_first ( uint8  u8StopScanOption)

Synchronous API for enabling/disabling the stop scan on first result of the WINC IC's network scanning functions.

Allows for enabling/disabling of stop scan on first result. When enabled, the WINC will stop the scan as soon as
it detects a network and return the results to the host. Setting is persistent and will need to be explicitly
reverted back by the application if it no longer wishes for it to be enabled.
Parameters
[in]u8StopScanOption;Setting for enabling or disabling Stopping Scan on first result. 1 = Enabled, 0 = Disabled (Default)
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
See Also
tenuM2mScanCh tstrM2MScanOption tstrM2MStopScanOption m2m_wifi_request_scan m2m_wifi_set_scan_options

References hif_send(), M2M_ERR_FAIL, M2M_ERR_INVALID_ARG, M2M_INFO, M2M_REQ_GROUP_WIFI, M2M_WIFI_REQ_SET_STOP_SCAN_OPTION, NULL, and tstrM2MStopScanOption::u8StopOnFirstResult.