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 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_passive (uint8 ch)
	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 network scanning functions. More...
sint8	m2m_wifi_set_scan_region (uint16 ScanRegion)
	Synchronous API for configuring the regulatory restrictions that may affect the WINC 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.

This function allows the application to recover the number of access points discovered during
the most recent scan activity. This is achieved via a global variable in the WINC driver that
is populated when receiving the @ref M2M_WIFI_RESP_SCAN_DONE event.
Function to be used 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

Returns 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)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8                 u8NumFoundAPs = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

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)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
            
            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
            
            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);
            
            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;
    
    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
        
        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

Referenced by app_wifi_handle_event(), and 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.

Asynchronous API to request the information of an access point discovered via scanning.

Parameters

[in]

index

Index 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

This function allows the information of any discovered access point to be retrieved. When a
scan is completed, the application is informed of the number of networks (access points)
discovered. Calling this function with an index, N, will return the information for the Nth
access point. The information will be returned to the application via a
@ref M2M_WIFI_RESP_SCAN_RESULT event, and the response data may be obtained through casting
the pointer (pvMsg) to @ref tstrM2mWifiscanResult.

Parameters

[in]

index

Index 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 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 in order to receive scan data after calling this function. Registration of the callback is done via 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

• This API is valid only for STA mode, it may be called regardless of the connection state (connected or disconnected).
• Calling this function without first issuing a scan request may lead to stale data being recovered.
• Application code should refrain from introducing significant delays between issuing the scan request and scan result requests.

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 the response.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    static uint8    u8ScanResultIdx = 0;

    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;

    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

Parameters

[in]

index

Index 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]

index

Index 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)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
            
            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
            
            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);
            
            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;
    
    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
        
        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

Referenced by app_wifi_handle_event(), and wifi_cb().

NMI_API sint8 m2m_wifi_request_scan

(

uint8

ch

)

Asynchronous API to request the WINC to scan for networks.

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]

ch

RF 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

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at initialization. Registration of the callback is done via m2m_wifi_init.
• The events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT must be handled in the (tpfAppWifiCb) callback.
• The m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

Warning

This API is valid only for STA mode, it may be called regardless of connection state (connected or disconnected states).

See 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)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;

    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult *pstrScanResult = (tstrM2mWifiscanResult*)pvMsg;
            uint8                 u8NumFoundAPs   = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam param;
    param.pfAppWifiCb = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

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]

ch

RF 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

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at initialization. Registration of the callback is done via m2m_wifi_init.
• The events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT must be handled in the (tpfAppWifiCb) callback.
• The m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

Warning

This API is valid only for STA mode, it may be called regardless of connection state (connected or disconnected states).

See 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)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
            
            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
            
            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);
            
            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;
    
    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
        
        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

Referenced by ble_prov_process_event(), main(), wifi_cb(), and wifi_provision_app_scanning_handler().

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]	ch	RF 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_time	The time in ms that passive scan is listening for beacons on each channel per one slot, enter 0 for default setting.

Warning

This function is not allowed in AP mode. It works only for STA mode (both connected or disconnected states).

Precondition

• 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 events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT. must be handled in the callback.
• The m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

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_passive

(

uint8

ch

)

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

Parameters

[in]

ch

RF 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.

Warning

This function is not allowed in P2P or AP modes. It works only for STA mode (both connected or disconnected states).

Precondition

• 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 events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT. must be handled in the callback.
• The m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

See Also

M2M_WIFI_RESP_SCAN_DONE M2M_WIFI_RESP_SCAN_RESULT tpfAppWifiCb tstrM2MScanOption 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 hif_send(), M2M_ERR_INVALID_ARG, M2M_REQ_GROUP_WIFI, M2M_SUCCESS, M2M_WIFI_CH_1, M2M_WIFI_CH_14, M2M_WIFI_CH_ALL, M2M_WIFI_REQ_PASSIVE_SCAN, NULL, 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]	ch	RF 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]	u8SsidList	u8SsidList is a buffer containing a list of hidden SSIDs to include during the scan. The first byte in the buffer, u8SsidList[0], is the number of SSIDs encoded in the string. The number of hidden SSIDs cannot exceed 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

• 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 events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT. must be handled in the callback.
• The m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

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)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    request_scan_hidden_demo_ap();
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

static void request_scan_hidden_demo_ap(void)
{
    uint8 list[9];
    char ssid[] = "DEMO_AP";
    uint8 len = (uint8)(sizeof(ssid)-1);

    list[0] = 1;
    list[1] = len;
    memcpy(&list[2], ssid, len); // copy 7 bytes
    // Scan all channels
    m2m_wifi_request_scan_ssid_list(M2M_WIFI_CH_ALL, list);
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        request_scan_hidden_demo_ap();
        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

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]	ch	RF 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]	u8SsidList	u8SsidList is a buffer containing a list of hidden SSIDs to include during the scan. The first byte in the buffer, u8SsidList[0], is the number of SSIDs encoded in the string. The number of hidden SSIDs cannot exceed 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

• 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 events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT. must be handled in the callback.
• The m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

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)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;
            
            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    request_scan_hidden_demo_ap();
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();
            
            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);
            
            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

static void request_scan_hidden_demo_ap(void)
{
    uint8 list[9];
    char ssid[] = "DEMO_AP";
    uint8 len = (uint8)(sizeof(ssid)-1);

    list[0] = 1;
    list[1] = len;
    memcpy(&list[2], ssid, len); // copy 7 bytes
    // Scan all channels
    m2m_wifi_request_scan_ssid_list(M2M_WIFI_CH_ALL, list);
}


int main()
{
    tstrWifiInitParam   param;
    
    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        request_scan_hidden_demo_ap();
        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

sint8 m2m_wifi_set_scan_options

(

tstrM2MScanOption *

ptstrM2MScanOption

)

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

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

This function allows the application to tune the scanning behaviour of the WINC using the
parameters described in @ref tstrM2MScanOption.

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

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

sint8 m2m_wifi_set_scan_region

(

uint16

ScanRegion

)

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

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 may legally scan given a geographic region.

For 2.4GHz, supported in the current release, the requested scan region cannot exceed the
maximum number of channels (14).

Parameters

[in]

ScanRegion

ASIA EUROPE 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

tenuM2mScanRegion m2m_wifi_request_scan

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]

ScanRegion

ASIA 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

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