WifiScan Development Guide_Rev1.1

中文

Revision History

Version	Date	Author	Revision Content
Rev1.0	2023-09-12	WTY	Initial document creation
Rev1.1	2024-03-25	sxx	Changed document name

1 Introduction

This document introduces the LTE-EC71X Wifi Scan interface APIs. The API interfaces are declared in the file components/kernel/lierda_api/liot_wifiscan/liot_wifiscan.h.

New

2 API Function Overview

Function	Description
liot_wifiscan_open()	Enable Wi-Fi Scan
liot_wifiscan_close()	Disable Wi-Fi Scan
liot_wifiscan_option_set()	Configure Wi-Fi Scan parameters
liot_wifiscan_do()	Perform Wi-Fi Scan synchronous mode scanning
liot_wifiscan_register_cb()	Start Wi-Fi Scan asynchronous mode scanning
liot_wifiscan_async()	Register callback function

Note:

1. Unless otherwise specified, the Wi-Fi Scan API interface functions mentioned in this document do not support concurrent calls, and cannot be called in any callback function, otherwise it will affect the processing of subsequent messages.

2. It is not supported to enable Wi-Fi Scan when doing data services on LTE network.

3 Type Descriptions

3.1 liot_wifiscan_errcode_e

Wi-Fi Scan error code definition enumeration is as follows:

1. Declaration

typedef enum
{
    LIOT_WIFISCAN_SUCCESS = 0,
    LIOT_WIFISCAN_EXECUTE_ERR = 1 | LIOT_WIFISCAN_ERRCODE_BASE,
    LIOT_WIFISCAN_MEM_ADDR_NULL_ERR,
    LIOT_WIFISCAN_INVALID_PARAM_ERR,
    LIOT_WIFISCAN_SEMAPHORE_WAIT_ERR,
    LIOT_WIFISCAN_MUTEX_TIMEOUT_ERR,
    LIOT_WIFISCAN_OPEN_FAIL,
    LIOT_WIFISCAN_BUSY_ERR,
    LIOT_WIFISCAN_ALREADY_OPEN_ERR,
    LIOT_WIFISCAN_NOT_OPEN_ERR,
    LIOT_WIFISCAN_HW_OCCUPIED_ERR,
    LIOT_WIFISCAN_NO_SET_CB_ERR,
} liot_wifiscan_errcode_e;

2. Parameters

• LIOT_WIFISCAN_SUCCESS: Execution successful

• LIOT_WIFISCAN_EXECUTE_ERR: Execution failed

• LIOT_WIFISCAN_MEM_ADDR_NULL_ERR: Memory allocation failed

• LIOT_WIFISCAN_INVALID_PARAM_ERR: Invalid parameter

• LIOT_WIFISCAN_SEMAPHORE_WAIT_ERR: Semaphore wait exception

• LIOT_WIFISCAN_MUTEX_TIMEOUT_ERR: Mutex acquisition exception

• LIOT_WIFISCAN_OPEN_FAIL: Wi-Fi Scan enable exception

• LIOT_WIFISCAN_BUSY_ERR: Wi-Fi Scan repeated enable error

• LIOT_WIFISCAN_ALREADY_OPEN_ERR: Wi-Fi Scan not enabled

• LIOT_WIFISCAN_NOT_OPEN_ERR: Wi-Fi Scan busy (such as scanning in progress)

• LIOT_WIFISCAN_HW_OCCUPIED_ERR: Hardware occupied

• LIOT_WIFISCAN_NO_SET_CB_ERR: Callback function not set

3.2 liot_wifi_ap_info_s

Scanned Wi-Fi AP specific information structure definition is as follows:

1. Declaration

typedef struct
{
    UINT8 bssidNum; // rssi number
    UINT8 rsvd;
    UINT8 ssidHexLen[LIOT_WIFI_SCAN_MAX_AP_CNT];  // the length of Wifi SSID Name hex data
    UINT8 ssidHex[LIOT_WIFI_SCAN_MAX_AP_CNT][32]; // the hex data of WiFi SSID Name
    INT8 rssi[LIOT_WIFI_SCAN_MAX_AP_CNT];         // rssi value of scanned bssid
    UINT8 channel[LIOT_WIFI_SCAN_MAX_AP_CNT]; // record channel index of bssid, 2412MHz ~ 2472MHz corresponding to 1 ~ 13
    UINT8 bssid[LIOT_WIFI_SCAN_MAX_AP_CNT][6]; // mac address is fixed to 6 digits
} liot_wifi_ap_info_s;

2. Parameters

• bssidNum: Number of scanned WIFI APs

• rsvd: Reserved parameter

• ssidHexLen: SSID length

• ssidHex: SSID data

• rssi: AP signal strength

• channel: WIFI AP channel

• bssid: WIFI AP MAC address

3.3 liot_wifiscan_callback

Wi-Fi Scan callback function pointer definition is as follows:

1. Declaration

typedef void (*liot_wifiscan_callback)(liot_wifiscan_ind_msg_s *msg_buf);

3.4 liot_wifiscan_ind_msg_s

Kernel notification information structure definition to APP side through callback function is as follows:

1. Declaration

typedef struct
{
    uint32_t msg_err_code;
    void *msg_data;
} liot_wifiscan_ind_msg_s;

2. Parameters

• msg_err_code: Execution result code, please refer to section 3.1.

• msg_data: Specific notification data, can be converted to liot_wifi_ap_info_s type structure to read data

4 API Function Details

4.1 liot_wifiscan_open

This function is used to enable Wi-Fi Scan.

1. Declaration

liot_wifiscan_errcode_e liot_wifiscan_open(void);

2. Parameters

None

3. Return Value

liot_wifiscan_errcode_e: Execution result code, please refer to section 3.1.

4.2 liot_wifiscan_close

This function is used to disable Wi-Fi Scan.

1. Declaration

liot_wifiscan_errcode_e liot_wifiscan_close(void);

2. Parameters

None

3. Return Value

liot_wifiscan_errcode_e: Execution result code, please refer to section 3.1.

4.3 liot_wifiscan_option_set

This function is used to configure Wi-Fi Scan scanning parameters.

1. Declaration

liot_wifiscan_errcode_e liot_wifiscan_option_set(int32 maxTimeOut,
                                                uint8 round,
                                                uint8 maxBssidNum,
                                                uint8 scanTimeOut,
                                                uint8 wifiPriority);

2. Parameters

• maxTimeOut: [In] If there is no scan result after timeout, an error will be reported, range: 4000 ~ 255000, default value: 12000, unit: milliseconds;

• round: [In] Number of Wi-Fi Scan rounds, range: 1~3, default value: 1;

• maxBssidNum: [In] Expected number of Wi-Fi hotspots to be scanned, range: 4~10, default value: 5;

• scanTimeOut: [In] Wi-Fi Scan RRC polling timeout, range: 0~255, default value: 5, unit: seconds;

• wifiPriority: [In] Wi-Fi Scan priority parameter, 0: data priority, 1: Wi-Fi Scan priority. (Note: In data priority mode, wifi scanning will only start when CFUN=0 or UE is in IDLE state; In Wi-Fi Scan priority mode, if UE is in connected state, regardless of whether there is data service, it will interrupt the current connected state and return to idle to initiate wifi network search)

3. Return Value

liot_wifiscan_errcode_e: Execution result code, please refer to section 3.1.

4.4 liot_wifiscan_do

This function is used to perform Wi-Fi Scan synchronous mode scanning.

1. Declaration

liot_wifiscan_errcode_e liot_wifiscan_do(liot_wifi_ap_info_s *p_ap_infos);

2. Parameters

p_ap_infos: [Out] Information of all scanned APs. See 3.2 liot_wifi_ap_info_s for details.

3. Return Value

liot_wifiscan_errcode_e: Execution result code, please refer to section 3.1.

4.5 liot_wifiscan_register_cb

This function is used to register Wifi-Scan asynchronous mode callback function.

1. Declaration

liot_wifiscan_errcode_e liot_wifiscan_register_cb(liot_wifiscan_callback wifiscan_cb);

2. Parameters

wifiscan_cb: [In] Interrupt callback function, which will be entered when scanning is completed after calling the asynchronous scanning function. Callback function format see 3.3 liot_wifiscan_callback

3. Return Value

liot_wifiscan_errcode_e: Execution result code, please refer to section 3.1.

4.6 liot_wifiscan_async

This function is used to start Wi-Fi Scan asynchronous mode scanning.

1. Declaration

liot_wifiscan_errcode_e liot_wifiscan_async(void);

2. Parameters

None

3. Return Value

liot_wifiscan_errcode_e: Execution result code, please refer to section 3.1.

5 Code Example

Sample code reference: examples/demo/src/demo_wifiscan.c file.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "lierda_app_main.h"
#include "liot_os.h"
#include "liot_type.h"
#include "liot_wifiscan.h"

/*===========================================================================
 * Functions
 ===========================================================================*/
void liot_wifiscan_ap_info_output(liot_wifi_ap_info_s *p_ap_infos)
{
    if (NULL == p_ap_infos)
    {
        return;
        liot_trace("result NULL");
    }

    for (uint16 i = 0; i < p_ap_infos->bssidNum; i++)
    {
        liot_trace("WIFISCAN:(-,-,%d,\"%02X:%02X:%02X:%02X:%02X:%02X\",%d",
                   p_ap_infos->rssi[i],
                   p_ap_infos->bssid[i][0],
                   p_ap_infos->bssid[i][1],
                   p_ap_infos->bssid[i][2],
                   p_ap_infos->bssid[i][3],
                   p_ap_infos->bssid[i][4],
                   p_ap_infos->bssid[i][5],
                   p_ap_infos->channel[i]);
    }
}

// all memory of msg_buf and it's sub item will be released by core after the call of callback.
void liot_wifiscan_app_callback(liot_wifiscan_ind_msg_s *msg_buf)
{
    liot_wifiscan_close();

    if ((LIOT_WIFISCAN_SUCCESS == msg_buf->msg_err_code) && (NULL != msg_buf->msg_data))
    {
        liot_wifi_ap_info_s *scan_result = msg_buf->msg_data;
        liot_trace("ap_cnt=%d", scan_result->bssidNum);
        liot_wifiscan_ap_info_output(scan_result);
    }
}

// to start a async scan
void liot_wifiscan_async_start(void)
{
    if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_option_set(LIOT_WIFI_SCAN_TIME_VAL_DEF,
                                                          LIOT_WIFI_SCAN_DEFAULT_ROUND,
                                                          LIOT_WIFI_SCAN_DEFAULT_AP_CNT,
                                                          LIOT_WIFI_SCAN_SCANTIMEOUT_VAL_DEF,
                                                          LIOT_WIFI_SCAN_PRIORITY_VAL_DEF)

    )
    {
        liot_trace("option set err");
        return;
    }
    if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_register_cb(liot_wifiscan_app_callback))
    {
        liot_trace("register cb err");
        return;
    }
    if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_open())
    {
        liot_trace("device open err");
        return;
    }
    if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_async())
    {
        liot_wifiscan_close();
        liot_trace("to do a async scan err");
        return;
    }
}

// complete flow to do one time scan: option->open->scan->close->output
void liot_wifiscan_synchro_complete_flow(void)
{
    if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_option_set(LIOT_WIFI_SCAN_TIME_VAL_DEF,
                                                          LIOT_WIFI_SCAN_DEFAULT_ROUND,
                                                          LIOT_WIFI_SCAN_DEFAULT_AP_CNT,
                                                          LIOT_WIFI_SCAN_SCANTIMEOUT_VAL_DEF,
                                                          LIOT_WIFI_SCAN_PRIORITY_VAL_DEF))
    {
        liot_trace("option set err");
        return;
    }

    if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_open())
    {
        liot_trace("device open err");
        return;
    }

    liot_wifi_ap_info_s ap_infos = {0};

    if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_do(&ap_infos))
    {
        liot_wifiscan_close();
        liot_trace("to do a scan err");
        return;
    }

    liot_trace("ap_cnt=%d", ap_infos.bssidNum);
    liot_wifiscan_close();
    liot_wifiscan_ap_info_output(&ap_infos);
}

void liot_wifiscan_demo_thread(void *argv)
{
    liot_trace("==========wifiscandemo start==========");
    liot_rtos_task_sleep_ms(1000);
    while (1)
    {
        liot_wifiscan_synchro_complete_flow();
        liot_rtos_task_sleep_ms(5000);
        liot_wifiscan_async_start();
        liot_rtos_task_sleep_ms(15000);
    }
}

Running Result:

As shown in the figure above, it indicates that all information has been obtained normally.