examples: using xEventGroup bits properly

Closes IDF-1177

* changed
  ../../wifi/getting_started/station/README.md
  ../../wifi/getting_started/station/main/station_example_main.c

examples/protocols/esp_local_ctrl/main/app_main.c

@@ -32,9 +32,11 @@
 /* FreeRTOS event group to signal when we are connected*/
 static EventGroupHandle_t s_wifi_event_group;
 
-/* The event group allows multiple bits for each event, but we only care about one event
- * - are we connected to the AP with an IP? */
-const int WIFI_CONNECTED_BIT = BIT0;
+/* The event group allows multiple bits for each event, but we only care about two events:
+ * - we are connected to the AP with an IP
+ * - we failed to connect after the maximum amount of retries */
+#define WIFI_CONNECTED_BIT BIT0
+#define WIFI_FAIL_BIT      BIT1
 
 static const char *TAG = "local_ctrl_example";
 
@@ -48,9 +50,10 @@ static void event_handler(void* arg, esp_event_base_t event_base,
     } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
         if (s_retry_num < EXAMPLE_ESP_MAXIMUM_RETRY) {
             esp_wifi_connect();
-            xEventGroupClearBits(s_wifi_event_group, WIFI_CONNECTED_BIT);
             s_retry_num++;
             ESP_LOGI(TAG, "retry to connect to the AP");
+        } else {
+            xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT);
         }
         ESP_LOGI(TAG,"connect to the AP fail");
     } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
@@ -61,8 +64,9 @@ static void event_handler(void* arg, esp_event_base_t event_base,
     }
 }
 
-void wifi_init_sta(void)
+esp_err_t wifi_init_sta(void)
 {
+    esp_err_t ret_value = ESP_OK;
     s_wifi_event_group = xEventGroupCreate();
 
     ESP_ERROR_CHECK(esp_netif_init());
@@ -88,8 +92,33 @@ void wifi_init_sta(void)
     ESP_ERROR_CHECK(esp_wifi_start() );
 
     ESP_LOGI(TAG, "wifi_init_sta finished.");
-    ESP_LOGI(TAG, "connect to ap SSID:%s password:%s",
-             EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS);
+
+    /* Waiting until either the connection is established (WIFI_CONNECTED_BIT) or connection failed for the maximum
+     * number of re-tries (WIFI_FAIL_BIT). The bits are set by event_handler() (see above) */
+    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group,
+            WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
+            pdFALSE,
+            pdFALSE,
+            portMAX_DELAY);
+
+    /* xEventGroupWaitBits() returns the bits before the call returned, hence we can test which event actually
+     * happened. */
+    if (bits & WIFI_CONNECTED_BIT) {
+        ESP_LOGI(TAG, "connected to ap SSID:%s password:%s",
+                 EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS);
+    } else if (bits & WIFI_FAIL_BIT) {
+        ESP_LOGI(TAG, "Failed to connect to SSID:%s, password:%s",
+                 EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS);
+        ret_value = ESP_FAIL;
+    } else {
+        ESP_LOGE(TAG, "UNEXPECTED EVENT");
+        ret_value = ESP_ERR_INVALID_STATE;
+    }
+
+    ESP_ERROR_CHECK(esp_event_handler_unregister(IP_EVENT, IP_EVENT_STA_GOT_IP, &event_handler));
+    ESP_ERROR_CHECK(esp_event_handler_unregister(WIFI_EVENT, ESP_EVENT_ANY_ID, &event_handler));
+    vEventGroupDelete(s_wifi_event_group);
+    return ret_value;
 }
 
 /* Function responsible for configuring and starting the esp_local_ctrl service.
@@ -107,6 +136,9 @@ void app_main(void)
     ESP_ERROR_CHECK(ret);
 
     ESP_LOGI(TAG, "ESP_WIFI_MODE_STA");
-    wifi_init_sta();
-    start_esp_local_ctrl_service();
+    if (wifi_init_sta() == ESP_OK) {
+        start_esp_local_ctrl_service();
+    } else {
+        ESP_LOGI(TAG, "Connection failed, not starting esp_local_ctrl service");
+    }
 }

examples/wifi/getting_started/station/README.md

@@ -28,70 +28,82 @@ idf.py -p PORT flash monitor
 See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
 
 ## Example Output
+Note that the output, in particular the order of the output, may vary depending on the environment.
 
-There is the console output for station connects to ap successfully:
+Console output if station connects to AP successfully:
 ```
-I (727) wifi station: ESP_WIFI_MODE_STA
-I (727) wifi: wifi driver task: 3ffc0c68, prio:23, stack:3584, core=0
-I (727) wifi: wifi firmware version: 19b3110
-I (727) wifi: config NVS flash: enabled
-I (727) wifi: config nano formating: disabled
-I (737) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
-I (747) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
-I (777) wifi: Init dynamic tx buffer num: 32
-I (777) wifi: Init data frame dynamic rx buffer num: 32
-I (777) wifi: Init management frame dynamic rx buffer num: 32
-I (777) wifi: Init static rx buffer size: 1600
-I (787) wifi: Init static rx buffer num: 10
-I (787) wifi: Init dynamic rx buffer num: 32
-I (907) phy: phy_version: 3960, 5211945, Jul 18 2018, 10:40:07, 0, 0
-I (907) wifi: mode : sta (30:ae:a4:80:45:68)
-I (907) wifi station: wifi_init_sta finished.
-I (907) wifi station: connect to ap SSID:myssid password:mypassword
-I (1027) wifi: n:6 0, o:1 0, ap:255 255, sta:6 0, prof:1
-I (2017) wifi: state: init -> auth (b0)
-I (2017) wifi: state: auth -> assoc (0)
-I (2027) wifi: state: assoc -> run (10)
-I (2067) wifi: connected with myssid, channel 6
-I (2067) wifi: pm start, type: 1
-
-I (3227) event: sta ip: 172.20.10.7, mask: 255.255.255.240, gw: 172.20.10.1
-I (3227) wifi station: got ip:172.20.10.7
+I (589) wifi station: ESP_WIFI_MODE_STA
+I (599) wifi: wifi driver task: 3ffc08b4, prio:23, stack:3584, core=0
+I (599) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
+I (599) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
+I (629) wifi: wifi firmware version: 2d94f02
+I (629) wifi: config NVS flash: enabled
+I (629) wifi: config nano formating: disabled
+I (629) wifi: Init dynamic tx buffer num: 32
+I (629) wifi: Init data frame dynamic rx buffer num: 32
+I (639) wifi: Init management frame dynamic rx buffer num: 32
+I (639) wifi: Init management short buffer num: 32
+I (649) wifi: Init static rx buffer size: 1600
+I (649) wifi: Init static rx buffer num: 10
+I (659) wifi: Init dynamic rx buffer num: 32
+I (759) phy: phy_version: 4180, cb3948e, Sep 12 2019, 16:39:13, 0, 0
+I (769) wifi: mode : sta (30:ae:a4:d9:bc:c4)
+I (769) wifi station: wifi_init_sta finished.
+I (889) wifi: new:<6,0>, old:<1,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (889) wifi: state: init -> auth (b0)
+I (899) wifi: state: auth -> assoc (0)
+I (909) wifi: state: assoc -> run (10)
+I (939) wifi: connected with #!/bin/test, aid = 1, channel 6, BW20, bssid = ac:9e:17:7e:31:40
+I (939) wifi: security type: 3, phy: bgn, rssi: -68
+I (949) wifi: pm start, type: 1
+
+I (1029) wifi: AP's beacon interval = 102400 us, DTIM period = 3
+I (2089) esp_netif_handlers: sta ip: 192.168.77.89, mask: 255.255.255.0, gw: 192.168.77.1
+I (2089) wifi station: got ip:192.168.77.89
+I (2089) wifi station: connected to ap SSID:myssid password:mypassword
 ```
 
-There is the console output for station connects to ap failed:
+Console output if the station failed to connect to AP:
 ```
-I (728) wifi station: ESP_WIFI_MODE_STA
-I (728) wifi: wifi driver task: 3ffc0c68, prio:23, stack:3584, core=0
-I (728) wifi: wifi firmware version: 19b3110
-I (728) wifi: config NVS flash: enabled
-I (738) wifi: config nano formating: disabled
-I (738) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
-I (748) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
-I (778) wifi: Init dynamic tx buffer num: 32
-I (778) wifi: Init data frame dynamic rx buffer num: 32
-I (778) wifi: Init management frame dynamic rx buffer num: 32
-I (788) wifi: Init static rx buffer size: 1600
-I (788) wifi: Init static rx buffer num: 10
-I (788) wifi: Init dynamic rx buffer num: 32
-I (908) phy: phy_version: 3960, 5211945, Jul 18 2018, 10:40:07, 0, 0
-I (908) wifi: mode : sta (30:ae:a4:80:45:68)
-I (908) wifi station: wifi_init_sta finished.
-I (918) wifi station: connect to ap SSID:myssid password:mypassword
-I (3328) wifi station: retry to connect to the AP
-I (3328) wifi station: connect to the AP fail
-
-I (5738) wifi station: retry to connect to the AP
-I (5738) wifi station: connect to the AP fail
-
-I (8148) wifi station: retry to connect to the AP
-I (8148) wifi station: connect to the AP fail
-
-I (10558) wifi station: retry to connect to the AP
-I (10558) wifi station: connect to the AP fail
-
-I (12968) wifi station: retry to connect to the AP
-I (12968) wifi station: connect to the AP fail
-
-I (15378) wifi station: connect to the AP fail
+I (589) wifi station: ESP_WIFI_MODE_STA
+I (599) wifi: wifi driver task: 3ffc08b4, prio:23, stack:3584, core=0
+I (599) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
+I (599) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
+I (629) wifi: wifi firmware version: 2d94f02
+I (629) wifi: config NVS flash: enabled
+I (629) wifi: config nano formating: disabled
+I (629) wifi: Init dynamic tx buffer num: 32
+I (629) wifi: Init data frame dynamic rx buffer num: 32
+I (639) wifi: Init management frame dynamic rx buffer num: 32
+I (639) wifi: Init management short buffer num: 32
+I (649) wifi: Init static rx buffer size: 1600
+I (649) wifi: Init static rx buffer num: 10
+I (659) wifi: Init dynamic rx buffer num: 32
+I (759) phy: phy_version: 4180, cb3948e, Sep 12 2019, 16:39:13, 0, 0
+I (759) wifi: mode : sta (30:ae:a4:d9:bc:c4)
+I (769) wifi station: wifi_init_sta finished.
+I (889) wifi: new:<6,0>, old:<1,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (889) wifi: state: init -> auth (b0)
+I (1889) wifi: state: auth -> init (200)
+I (1889) wifi: new:<6,0>, old:<6,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (1889) wifi station: retry to connect to the AP
+I (1899) wifi station: connect to the AP fail
+I (3949) wifi station: retry to connect to the AP
+I (3949) wifi station: connect to the AP fail
+I (4069) wifi: new:<6,0>, old:<6,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (4069) wifi: state: init -> auth (b0)
+I (5069) wifi: state: auth -> init (200)
+I (5069) wifi: new:<6,0>, old:<6,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (5069) wifi station: retry to connect to the AP
+I (5069) wifi station: connect to the AP fail
+I (7129) wifi station: retry to connect to the AP
+I (7129) wifi station: connect to the AP fail
+I (7249) wifi: new:<6,0>, old:<6,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (7249) wifi: state: init -> auth (b0)
+I (8249) wifi: state: auth -> init (200)
+I (8249) wifi: new:<6,0>, old:<6,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (8249) wifi station: retry to connect to the AP
+I (8249) wifi station: connect to the AP fail
+I (10299) wifi station: connect to the AP fail
+I (10299) wifi station: Failed to connect to SSID:myssid, password:mypassword
 ```

examples/wifi/getting_started/station/main/station_example_main.c

@@ -31,15 +31,17 @@
 /* FreeRTOS event group to signal when we are connected*/
 static EventGroupHandle_t s_wifi_event_group;
 
-/* The event group allows multiple bits for each event, but we only care about one event 
- * - are we connected to the AP with an IP? */
-const int WIFI_CONNECTED_BIT = BIT0;
+/* The event group allows multiple bits for each event, but we only care about two events:
+ * - we are connected to the AP with an IP
+ * - we failed to connect after the maximum amount of retries */
+#define WIFI_CONNECTED_BIT BIT0
+#define WIFI_FAIL_BIT      BIT1
 
 static const char *TAG = "wifi station";
 
 static int s_retry_num = 0;
 
-static void event_handler(void* arg, esp_event_base_t event_base, 
+static void event_handler(void* arg, esp_event_base_t event_base,
                                 int32_t event_id, void* event_data)
 {
     if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
@@ -47,9 +49,10 @@ static void event_handler(void* arg, esp_event_base_t event_base,
     } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
         if (s_retry_num < EXAMPLE_ESP_MAXIMUM_RETRY) {
             esp_wifi_connect();
-            xEventGroupClearBits(s_wifi_event_group, WIFI_CONNECTED_BIT);
             s_retry_num++;
             ESP_LOGI(TAG, "retry to connect to the AP");
+        } else {
+            xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT);
         }
         ESP_LOGI(TAG,"connect to the AP fail");
     } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
@@ -72,7 +75,6 @@ void wifi_init_sta(void)
     wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
     ESP_ERROR_CHECK(esp_wifi_init(&cfg));
 
-
     ESP_ERROR_CHECK(esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &event_handler, NULL));
     ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &event_handler, NULL));
 
@@ -87,8 +89,30 @@ void wifi_init_sta(void)
     ESP_ERROR_CHECK(esp_wifi_start() );
 
     ESP_LOGI(TAG, "wifi_init_sta finished.");
-    ESP_LOGI(TAG, "connect to ap SSID:%s password:%s",
-             EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS);
+
+    /* Waiting until either the connection is established (WIFI_CONNECTED_BIT) or connection failed for the maximum
+     * number of re-tries (WIFI_FAIL_BIT). The bits are set by event_handler() (see above) */
+    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group,
+            WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
+            pdFALSE,
+            pdFALSE,
+            portMAX_DELAY);
+
+    /* xEventGroupWaitBits() returns the bits before the call returned, hence we can test which event actually
+     * happened. */
+    if (bits & WIFI_CONNECTED_BIT) {
+        ESP_LOGI(TAG, "connected to ap SSID:%s password:%s",
+                 EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS);
+    } else if (bits & WIFI_FAIL_BIT) {
+        ESP_LOGI(TAG, "Failed to connect to SSID:%s, password:%s",
+                 EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS);
+    } else {
+        ESP_LOGE(TAG, "UNEXPECTED EVENT");
+    }
+
+    ESP_ERROR_CHECK(esp_event_handler_unregister(IP_EVENT, IP_EVENT_STA_GOT_IP, &event_handler));
+    ESP_ERROR_CHECK(esp_event_handler_unregister(WIFI_EVENT, ESP_EVENT_ANY_ID, &event_handler));
+    vEventGroupDelete(s_wifi_event_group);
 }
 
 void app_main(void)
@@ -100,7 +124,7 @@ void app_main(void)
       ret = nvs_flash_init();
     }
     ESP_ERROR_CHECK(ret);
-    
+
     ESP_LOGI(TAG, "ESP_WIFI_MODE_STA");
     wifi_init_sta();
 }