1 // Copyright 2019 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef _PROV_WIFI_SCAN_H_ 16 #define _PROV_WIFI_SCAN_H_ 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 #include <esp_wifi.h> 23 24 #define WIFI_SSID_LEN sizeof(((wifi_ap_record_t *)0)->ssid) 25 #define WIFI_BSSID_LEN sizeof(((wifi_ap_record_t *)0)->bssid) 26 27 /** 28 * @brief Type of context data passed to each get/set/apply handler 29 * function set in `wifi_prov_scan_handlers` structure. 30 * 31 * This is passed as an opaque pointer, thereby allowing it be defined 32 * later in application code as per requirements. 33 */ 34 typedef struct wifi_prov_scan_ctx wifi_prov_scan_ctx_t; 35 36 /** 37 * @brief Structure of entries in the scan results list 38 */ 39 typedef struct { 40 /** 41 * SSID of Wi-Fi AP 42 */ 43 char ssid[WIFI_SSID_LEN]; 44 45 /** 46 * BSSID of Wi-Fi AP 47 */ 48 char bssid[WIFI_BSSID_LEN]; 49 50 /** 51 * Wi-Fi channel number 52 */ 53 uint8_t channel; 54 55 /** 56 * Signal strength 57 */ 58 int rssi; 59 60 /** 61 * Wi-Fi security mode 62 */ 63 uint8_t auth; 64 } wifi_prov_scan_result_t; 65 66 /** 67 * @brief Internal handlers for receiving and responding to protocomm 68 * requests from client 69 * 70 * This is to be passed as priv_data for protocomm request handler 71 * (refer to `wifi_prov_scan_handler()`) when calling `protocomm_add_endpoint()`. 72 */ 73 typedef struct wifi_prov_scan_handlers { 74 /** 75 * Handler function called when scan start command is received 76 * with various scan parameters : 77 * 78 * blocking (input) - If true, the function should return only 79 * when the scanning is finished 80 * 81 * passive (input) - If true, scan is to be started in passive 82 * mode (this may be slower) instead of active mode 83 * 84 * group_channels (input) - This specifies whether to scan 85 * all channels in one go (when zero) or perform scanning of 86 * channels in groups, with 120ms delay between scanning of 87 * consecutive groups, and the value of this parameter sets the 88 * number of channels in each group. This is useful when transport 89 * mode is SoftAP, where scanning all channels in one go may not 90 * give the Wi-Fi driver enough time to send out beacons, and 91 * hence may cause disconnection with any connected stations. 92 * When scanning in groups, the manager will wait for atleast 93 * 120ms after completing scan on a group of channels, and thus 94 * allow the driver to send out the beacons. For example, given 95 * that the total number of Wi-Fi channels is 14, then setting 96 * group_channels to 4, will create 5 groups, with each group 97 * having 3 channels, except the last one which will have 98 * 14 % 3 = 2 channels. So, when scan is started, the first 3 99 * channels will be scanned, followed by a 120ms delay, and then 100 * the next 3 channels, and so on, until all the 14 channels have 101 * been scanned. One may need to adjust this parameter as having 102 * only few channels in a group may slow down the overall scan 103 * time, while having too many may again cause disconnection. 104 * Usually a value of 4 should work for most cases. Note that 105 * for any other mode of transport, e.g. BLE, this can be safely 106 * set to 0, and hence achieve the fastest overall scanning time. 107 * 108 * period_ms (input) - Scan parameter specifying how long to 109 * wait on each channel (in milli-seconds) 110 */ 111 esp_err_t (*scan_start)(bool blocking, bool passive, 112 uint8_t group_channels, uint32_t period_ms, 113 wifi_prov_scan_ctx_t **ctx); 114 115 /** 116 * Handler function called when scan status is requested. Status 117 * is given the parameters : 118 * 119 * scan_finished (output) - When scan has finished this returns true 120 * 121 * result_count (output) - This gives the total number of results 122 * obtained till now. If scan is yet happening this number will 123 * keep on updating 124 */ 125 esp_err_t (*scan_status)(bool *scan_finished, 126 uint16_t *result_count, 127 wifi_prov_scan_ctx_t **ctx); 128 129 /** 130 * Handler function called when scan result is requested. Parameters : 131 * 132 * scan_result - For fetching scan results. This can be called even 133 * if scan is still on going 134 * 135 * start_index (input) - Starting index from where to fetch the 136 * entries from the results list 137 * 138 * count (input) - Number of entries to fetch from the starting index 139 * 140 * entries (output) - List of entries returned. Each entry consists 141 * of ssid, channel and rssi information 142 */ 143 esp_err_t (*scan_result)(uint16_t result_index, 144 wifi_prov_scan_result_t *result, 145 wifi_prov_scan_ctx_t **ctx); 146 147 /** 148 * Context pointer to be passed to above handler functions upon invocation 149 */ 150 wifi_prov_scan_ctx_t *ctx; 151 } wifi_prov_scan_handlers_t; 152 153 /** 154 * @brief Handler for sending on demand Wi-Fi scan results 155 * 156 * This is to be registered as the `prov-scan` endpoint handler 157 * (protocomm `protocomm_req_handler_t`) using `protocomm_add_endpoint()` 158 */ 159 esp_err_t wifi_prov_scan_handler(uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, 160 uint8_t **outbuf, ssize_t *outlen, void *priv_data); 161 162 #ifdef __cplusplus 163 } 164 #endif 165 166 #endif 167
