wifi_provisioning : Added Wi-Fi Scan list feature to Provisioning Man…

…ager

List of changes in components/wifi_provisioning:
* Manager version is now v1.1
* .proto files and protocomm handler added for sending Wi-Fi scan command and receiving scan results
* Implemented handlers for wifi_scan protocomm endpoint
* Update manager context data structure to hold scan state and results
* scheme_softap now runs Wi-Fi in APSTA mode
* Wi-Fi is started in AP mode when provisioning is started. This is necessary for scan list to work
* Docs updates with information about new wifi_scan endpoint

List of changes in tools/esp_prov:
* Added functions for sending and receiving protobuf messages compatible with wifi_scan protocomm endpoint
* Added feature to display/refresh scan results and accept user selection at runtime
* New functions:
  * get_version() : only returns the protocol version string
  * has_capability() : check is a capability is present according to proto-ver response
* wifi_scan feature is provided only if the `wifi_scan` capability is present

Other changes:
* Replace recursive mutex with plain mutex
* assert on return value of mutex give / take calls
* replace all calls with macros ACQUIRE_LOCK and RELEASE_LOCK
* some checks added in scanning related private APIs
* free and nullify scanning context and state if service is stopped while ongoing scan

.flake8

@@ -157,6 +157,7 @@ exclude =
         components/protocomm/python/sec0_pb2.py,
         components/protocomm/python/sec1_pb2.py,
         components/protocomm/python/session_pb2.py,
+        components/wifi_provisioning/python/wifi_scan_pb2.py,
         components/wifi_provisioning/python/wifi_config_pb2.py,
         components/wifi_provisioning/python/wifi_constants_pb2.py,
         examples/provisioning/custom_config/components/custom_provisioning/python/custom_config_pb2.py,

components/wifi_provisioning/CMakeLists.txt

@@ -1,9 +1,11 @@
 set(srcs "src/wifi_config.c"
+        "src/wifi_scan.c"
         "src/manager.c"
         "src/handlers.c"
         "src/scheme_softap.c"
         "src/scheme_console.c"
         "proto-c/wifi_config.pb-c.c"
+        "proto-c/wifi_scan.pb-c.c"
         "proto-c/wifi_constants.pb-c.c")
 
 if(CONFIG_BT_ENABLED)

components/wifi_provisioning/Kconfig

@@ -0,0 +1,10 @@
+menu "Wi-Fi Provisioning Manager"
+
+    config WIFI_PROV_SCAN_MAX_ENTRIES
+        int "Max Wi-Fi Scan Result Entries"
+        default 16
+        range 1 255
+        help
+            This sets the maximum number of entries of Wi-Fi scan results that will be kept by the provisioning manager
+
+endmenu

components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h

@@ -0,0 +1,166 @@
+// Copyright 2019 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef _PROV_WIFI_SCAN_H_
+#define _PROV_WIFI_SCAN_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <esp_wifi.h>
+
+#define WIFI_SSID_LEN  sizeof(((wifi_ap_record_t *)0)->ssid)
+#define WIFI_BSSID_LEN sizeof(((wifi_ap_record_t *)0)->bssid)
+
+/**
+ * @brief   Type of context data passed to each get/set/apply handler
+ *           function set in `wifi_prov_scan_handlers` structure.
+ *
+ * This is passed as an opaque pointer, thereby allowing it be defined
+ * later in application code as per requirements.
+ */
+typedef struct wifi_prov_scan_ctx wifi_prov_scan_ctx_t;
+
+/**
+ * @brief   Structure of entries in the scan results list
+ */
+typedef struct {
+    /**
+     * SSID of Wi-Fi AP
+     */
+    char ssid[WIFI_SSID_LEN];
+
+    /**
+     * BSSID of Wi-Fi AP
+     */
+    char bssid[WIFI_BSSID_LEN];
+
+    /**
+     * Wi-Fi channel number
+     */
+    uint8_t channel;
+
+    /**
+     * Signal strength
+     */
+    int rssi;
+
+    /**
+     * Wi-Fi security mode
+     */
+    uint8_t auth;
+} wifi_prov_scan_result_t;
+
+/**
+ * @brief   Internal handlers for receiving and responding to protocomm
+ *          requests from client
+ *
+ * This is to be passed as priv_data for protocomm request handler
+ * (refer to `wifi_prov_scan_handler()`) when calling `protocomm_add_endpoint()`.
+ */
+typedef struct wifi_prov_scan_handlers {
+    /**
+     * Handler function called when scan start command is received
+     * with various scan parameters :
+     *
+     * blocking (input) - If true, the function should return only
+     * when the scanning is finished
+     *
+     * passive (input) - If true, scan is to be started in passive
+     * mode (this may be slower) instead of active mode
+     *
+     * group_channels (input) - This specifies whether to scan
+     * all channels in one go (when zero) or perform scanning of
+     * channels in groups, with 120ms delay between scanning of
+     * consecutive groups, and the value of this parameter sets the
+     * number of channels in each group. This is useful when transport
+     * mode is SoftAP, where scanning all channels in one go may not
+     * give the Wi-Fi driver enough time to send out beacons, and
+     * hence may cause disconnection with any connected stations.
+     * When scanning in groups, the manager will wait for atleast
+     * 120ms after completing scan on a group of channels, and thus
+     * allow the driver to send out the beacons. For example, given
+     * that the total number of Wi-Fi channels is 14, then setting
+     * group_channels to 4, will create 5 groups, with each group
+     * having 3 channels, except the last one which will have
+     * 14 % 3 = 2 channels. So, when scan is started, the first 3
+     * channels will be scanned, followed by a 120ms delay, and then
+     * the next 3 channels, and so on, until all the 14 channels have
+     * been scanned. One may need to adjust this parameter as having
+     * only few channels in a group may slow down the overall scan
+     * time, while having too many may again cause disconnection.
+     * Usually a value of 4 should work for most cases. Note that
+     * for any other mode of transport, e.g. BLE, this can be safely
+     * set to 0, and hence achieve the fastest overall scanning time.
+     *
+     * period_ms (input) - Scan parameter specifying how long to
+     * wait on each channel (in milli-seconds)
+     */
+    esp_err_t (*scan_start)(bool blocking, bool passive,
+                            uint8_t group_channels, uint32_t period_ms,
+                            wifi_prov_scan_ctx_t **ctx);
+
+    /**
+     * Handler function called when scan status is requested. Status
+     * is given the parameters :
+     *
+     * scan_finished (output) - When scan has finished this returns true
+     *
+     * result_count (output) - This gives the total number of results
+     * obtained till now. If scan is yet happening this number will
+     * keep on updating
+     */
+    esp_err_t (*scan_status)(bool *scan_finished,
+                             uint16_t *result_count,
+                             wifi_prov_scan_ctx_t **ctx);
+
+    /**
+     * Handler function called when scan result is requested. Parameters :
+     *
+     * scan_result - For fetching scan results. This can be called even
+     * if scan is still on going
+     *
+     * start_index (input) - Starting index from where to fetch the
+     * entries from the results list
+     *
+     * count (input) - Number of entries to fetch from the starting index
+     *
+     * entries (output) - List of entries returned. Each entry consists
+     * of ssid, channel and rssi information
+     */
+    esp_err_t (*scan_result)(uint16_t result_index,
+                             wifi_prov_scan_result_t *result,
+                             wifi_prov_scan_ctx_t **ctx);
+
+    /**
+     * Context pointer to be passed to above handler functions upon invocation
+     */
+    wifi_prov_scan_ctx_t *ctx;
+} wifi_prov_scan_handlers_t;
+
+/**
+ * @brief   Handler for sending on demand Wi-Fi scan results
+ *
+ * This is to be registered as the `prov-scan` endpoint handler
+ * (protocomm `protocomm_req_handler_t`) using `protocomm_add_endpoint()`
+ */
+esp_err_t wifi_prov_scan_handler(uint32_t session_id, const uint8_t *inbuf, ssize_t inlen,
+                                 uint8_t **outbuf, ssize_t *outlen, void *priv_data);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif