provisioning_examples: Move older examples to legacy/ folder

Change the manager example folder name to wifi_prov_mgr to sound more meaningful.

Signed-off-by: Piyush Shah <piyush@espressif.com>

.flake8

@@ -162,4 +162,4 @@ exclude =
         components/wifi_provisioning/python/wifi_config_pb2.py,
         components/wifi_provisioning/python/wifi_constants_pb2.py,
         components/esp_local_ctrl/python/esp_local_ctrl_pb2.py,
-        examples/provisioning/custom_config/components/custom_provisioning/python/custom_config_pb2.py,
+        examples/provisioning/legacy/custom_config/components/custom_provisioning/python/custom_config_pb2.py,

docs/en/api-reference/provisioning/protocomm.rst

@@ -19,7 +19,7 @@ Note that the client still needs to establish session (only for protocomm_securi
 
 Transport Example (SoftAP + HTTP) with Security 1
 -------------------------------------------------
-For complete example see :example:`provisioning/softap_prov`
+For complete example see :example:`provisioning/legacy/softap_prov`
 
     .. highlight:: c
 
@@ -113,7 +113,7 @@ For complete example see :example:`provisioning/softap_prov`
 
 Transport Example (BLE) with Security 0
 ---------------------------------------
-For complete example see :example:`provisioning/ble_prov`
+For complete example see :example:`provisioning/legacy/ble_prov`
 
     .. highlight:: c
 

docs/en/api-reference/provisioning/provisioning.rst

@@ -144,15 +144,21 @@ Sample Code
 >>>>>>>>>>>
 Please refer to :doc:`protocomm` and :doc:`wifi_provisioning` for API guides and code snippets on example usage.
 
-Various use case implementations can be found as examples under :example:`provisioning`.
+Application implementation can be found as an example under :example:`provisioning`.
 
 Provisioning Tools
 >>>>>>>>>>>>>>>>>>
 
 Provisioning applications are available for various platforms, along with source code:
 
-* Android : `esp-idf-provisioning-android <https://github.com/espressif/esp-idf-provisioning-android>`_
+* Android:
-* iOS : `esp-idf-provisioning-ios <https://github.com/espressif/esp-idf-provisioning-ios>`_
+    * `BLE Provisioning app on Play Store <https://play.google.com/store/apps/details?id=com.espressif.provble>`_.
+    * `SoftAP Provisioning app on Play Store <https://play.google.com/store/apps/details?id=com.espressif.provsoftap>`_.
+    * Source code on GitHub: `esp-idf-provisioning-android <https://github.com/espressif/esp-idf-provisioning-android>`_.
+* iOS:
+    * `BLE Provisioning app on app store <https://apps.apple.com/in/app/esp-ble-provisioning/id1473590141>`_.
+    * `SoftAP Provisioning app on app Store <https://apps.apple.com/in/app/esp-softap-provisioning/id1474040630>`_.
+    * Source code on GitHub: `esp-idf-provisioning-ios <https://github.com/espressif/esp-idf-provisioning-ios>`_.
 * Linux/MacOS/Windows : :idf:`tools/esp_prov` (a python based command line tool for provisioning)
 
 The phone applications offer simple UI and thus more user centric, while the command line application is useful as a debugging tool for developers.

docs/en/api-reference/provisioning/wifi_provisioning.rst

@@ -274,7 +274,25 @@ The customized behavior is useful for applications which want the provisioning s
 Application Examples
 --------------------
 
-For complete example implementation see :example:`provisioning/manager`
+For complete example implementation see :example:`provisioning/wifi_prov_mgr`
+
+Provisioning Tools
+--------------------
+
+Provisioning applications are available for various platforms, along with source code:
+
+* Android:
+    * `BLE Provisioning app on Play Store <https://play.google.com/store/apps/details?id=com.espressif.provble>`_.
+    * `SoftAP Provisioning app on Play Store <https://play.google.com/store/apps/details?id=com.espressif.provsoftap>`_.
+    * Source code on GitHub: `esp-idf-provisioning-android <https://github.com/espressif/esp-idf-provisioning-android>`_.
+* iOS:
+    * `BLE Provisioning app on app store <https://apps.apple.com/in/app/esp-ble-provisioning/id1473590141>`_.
+    * `SoftAP Provisioning app on app Store <https://apps.apple.com/in/app/esp-softap-provisioning/id1474040630>`_.
+    * Source code on GitHub: `esp-idf-provisioning-ios <https://github.com/espressif/esp-idf-provisioning-ios>`_.
+* Linux/MacOS/Windows : :idf:`tools/esp_prov` (a python based command line tool for provisioning)
+
+The phone applications offer simple UI and thus more user centric, while the command line application is useful as a debugging tool for developers.
+
 
 API Reference
 -------------

examples/provisioning/README.md

@@ -1,6 +1,25 @@
 # Provisioning Application Examples
 
-These consist of the following examples :
+This primarily consists of a single unified example wifi_prov_mgr
+
+* wifi_prov_mgr
+    Abstracts out most of the complexity of Wi-Fi provisioning and allows easy switching between the SoftAP (using HTTP) and BLE transports.
+
+Provisioning applications are available for various platforms:
+
+* Android:
+    - [BLE Provisioning app on Play Store](https://play.google.com/store/apps/details?id=com.espressif.provble).
+    - [SoftAP Provisioning app on Play Store](https://play.google.com/store/apps/details?id=com.espressif.provsoftap).
+    - Source code on GitHub: [esp-idf-provisioning-android](https://github.com/espressif/esp-idf-provisioning-android).
+* iOS:
+    - [BLE Provisioning app on app store](https://apps.apple.com/in/app/esp-ble-provisioning/id1473590141)
+    - [SoftAP Provisioning app on app Store](https://apps.apple.com/in/app/esp-softap-provisioning/id1474040630)
+    - Source code on GitHub: [esp-idf-provisioning-ios](https://github.com/espressif/esp-idf-provisioning-ios)
+* For all other platforms a python based command line tool is provided under "$IDF_PATH/tools/esp_prov"
+
+## Legacy Examples
+
+The legacy examples require own implementation of provisioning functions and handlers. The Wi-Fi provisioning component abstracts out most of this complexity and provides a simpler interface and so, that is recommended for use. However, if you want to use lower level provisioning and protocomm APIs, you can check the these examples under legacy/ folder:
 
 * softap_prov
     Provisioning involves Wi-Fi station configuration via an HTTP server running on the device, which is initially configured to be in SoftAP mode. After provisioning, device runs in Wi-Fi station mode only and connects to the AP whose credentials were provided during provisioning.
@@ -14,10 +33,4 @@ These consist of the following examples :
 * custom_config
     Similar to softap_prov examples, but allows for configuration of custom (device-local) information during provisioning. This is intended as an example for implementing custom provisioning schemes.
 
-Provisioning applications are available for various platforms:
-
-* For Android, a provisioning application along with source code is available on GitHub : [esp-idf-provisioning-android](https://github.com/espressif/esp-idf-provisioning-android)
-* For iOS, a provisioning application along with source code is available on GitHub : [esp-idf-provisioning-ios](https://github.com/espressif/esp-idf-provisioning-ios)
-* For all other platforms a python based command line tool is provided under "$IDF_PATH/tools/esp_prov"
-
 Refer to the README.md files in each example directory for more information.

examples/provisioning/legacy/ble_prov/README.md

@@ -1,4 +1,6 @@
-# BLE based Provisioning Example
+# BLE based Provisioning Example (Legacy)
+
+> Note: It is recommended to use the new `wifi_prov_mgr` example which is based on the simpler `wifi_provisioning` APIs. Check this example only if you wish to use lower level provisioning and protocomm APIs and want more control over the handlers.
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 

examples/provisioning/legacy/ble_prov/ble_prov_test.py

@@ -29,7 +29,7 @@ esp_prov.config_throw_except = True
 @ttfw_idf.idf_example_test(env_tag="Example_WIFI_BT")
 def test_examples_provisioning_ble(env, extra_data):
     # Acquire DUT
-    dut1 = env.get_dut("ble_prov", "examples/provisioning/ble_prov", dut_class=ttfw_idf.ESP32DUT)
+    dut1 = env.get_dut("ble_prov", "examples/provisioning/legacy/ble_prov", dut_class=ttfw_idf.ESP32DUT)
 
     # Get binary file
     binary_file = os.path.join(dut1.app.binary_path, "ble_prov.bin")

examples/provisioning/legacy/console_prov/README.md

@@ -1,4 +1,6 @@
-# Console based Provisioning Example
+# Console based Provisioning Example (Legacy)
+
+> Check this example only if you wish to use console based provisioning. For any real applications, it is recommended to use the new `wifi_prov_mgr` example which is based on the simpler `wifi_provisioning` APIs.
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 

examples/provisioning/legacy/custom_config/README.md

@@ -1,4 +1,6 @@
-# SoftAP + HTTPD based Provisioning Example featuring Custom configuration
+# SoftAP + HTTPD based Provisioning Example featuring Custom configuration (Legacy)
+
+> Note: It is recommended to use the new `wifi_prov_mgr` example which is based on the simpler `wifi_provisioning` APIs. Check this example only if you wish to use lower level provisioning and protocomm APIs and want more control over the handlers.
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 

examples/provisioning/legacy/softap_prov/README.md

@@ -1,4 +1,6 @@
-# SoftAP + HTTPD based Provisioning Example
+# SoftAP + HTTPD based Provisioning Example (Legacy)
+
+> Note: It is recommended to use the new `wifi_prov_mgr` example which is based on the simpler `wifi_provisioning` APIs. Check this example only if you wish to use lower level provisioning and protocomm APIs and want more control over the handlers.
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 

examples/provisioning/legacy/softap_prov/softap_prov_test.py

@@ -30,7 +30,7 @@ esp_prov.config_throw_except = True
 @ttfw_idf.idf_example_test(env_tag="Example_WIFI_BT")
 def test_examples_provisioning_softap(env, extra_data):
     # Acquire DUT
-    dut1 = env.get_dut("softap_prov", "examples/provisioning/softap_prov", dut_class=ttfw_idf.ESP32DUT)
+    dut1 = env.get_dut("softap_prov", "examples/provisioning/legacy/softap_prov", dut_class=ttfw_idf.ESP32DUT)
 
     # Get binary file
     binary_file = os.path.join(dut1.app.binary_path, "softap_prov.bin")

tools/esp_prov/proto/__init__.py

@@ -41,4 +41,4 @@ wifi_scan_pb2      = _load_source("wifi_scan_pb2",      idf_path + "/components/
 
 # custom_provisioning component related python files generated from .proto files
 custom_config_pb2  = _load_source("custom_config_pb2",  idf_path +
-                                  "/examples/provisioning/custom_config/components/custom_provisioning/python/custom_config_pb2.py")
+                                  "/examples/provisioning/legacy/custom_config/components/custom_provisioning/python/custom_config_pb2.py")