Implement Network Scanning

Implemented Zigbee network scanning (async) to mostly match WiFi scan APIs.
Added Zigbee_Scan_Networks example

Author: P-R-O-C-H-Y

libraries/Zigbee/examples/Zigbee_Scan_Networks/Zigbee_Scan_Networks.ino

@@ -0,0 +1,109 @@
+// Copyright 2024 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.
+
+/**
+ * @brief This example demonstrates Zigbee Network Scanning.
+ *
+ * The example demonstrates how to use ESP Zigbee stack to scan for Zigbee networks.
+ *
+ * Any Zigbee mode can be selected in Tools->Zigbee mode
+ * with proper Zigbee partition scheme in Tools->Partition Scheme.
+ *
+ * Please check the README.md for instructions and more detailed description.
+ * 
+ * Created by Jan Procházka (https://github.com/P-R-O-C-H-Y/)
+ */
+
+#if !defined(ZIGBEE_MODE_ED) && !defined(ZIGBEE_MODE_ZCZR)
+#error "Zigbee device mode is not selected in Tools->Zigbee mode"
+#endif
+
+#include "Zigbee_core.h"
+
+#ifdef ZIGBEE_MODE_ZCZR
+zigbee_role_t role = ZIGBEE_ROUTER; // or can be ZIGBEE_COORDINATOR, but it wont scan itself
+#else
+zigbee_role_t role = ZIGBEE_END_DEVICE; 
+#endif
+
+void printScannedNetworks(uint16_t networksFound) {
+  if (networksFound == 0) {
+    Serial.println("No networks found");
+  } else {
+    zigbee_scan_result_t *scan_result = Zigbee.getScanResult();
+    Serial.println("\nScan done");
+    Serial.print(networksFound);
+    Serial.println(" networks found:");
+    Serial.println("Nr | PAN ID | CH | Permit Joining | Router Capacity | End Device Capacity | Extended PAN ID");
+    for (int i = 0; i < networksFound; ++i) {
+      // Print all available info for each network found
+      Serial.printf("%2d", i + 1);
+      Serial.print(" | ");
+      Serial.printf("0x%04hx", scan_result[i].short_pan_id);
+      Serial.print(" | ");
+      Serial.printf("%2ld", scan_result[i].logic_channel);
+      Serial.print(" | ");
+      Serial.printf("%-14.14s", scan_result[i].permit_joining ? "Yes" : "No");
+      Serial.print(" | ");
+      Serial.printf("%-15.15s", scan_result[i].router_capacity ? "Yes" : "No");
+      Serial.print(" | ");
+      Serial.printf("%-19.19s", scan_result[i].end_device_capacity ? "Yes" : "No");
+      Serial.print(" | ");
+      Serial.printf("%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x",  scan_result[i].extended_pan_id[7], scan_result[i].extended_pan_id[6], 
+                                                                scan_result[i].extended_pan_id[5], scan_result[i].extended_pan_id[4], 
+                                                                scan_result[i].extended_pan_id[3], scan_result[i].extended_pan_id[2], 
+                                                                scan_result[i].extended_pan_id[1], scan_result[i].extended_pan_id[0]);
+      Serial.println();
+      delay(10);
+    }
+    Serial.println("");
+    // Delete the scan result to free memory for code below.
+    Zigbee.scanDelete();
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+
+  // Initialize Zigbee stack without any EPs just for scanning
+  Zigbee.begin(role);
+
+  // Waint until Zigbee stack is ready
+  while (!Zigbee.isStarted()) {
+    delay(100);
+  }
+
+  Serial.println("Setup done");
+  // Start Zigbee Network Scan with default parameters (all channels, scan time 5)
+  Zigbee.scanNetworks();
+}
+
+void loop() {
+  // check Zigbee Network Scan process
+  int16_t ZigbeeScanStatus = Zigbee.scanComplete();
+  if (ZigbeeScanStatus < 0) {  // it is busy scanning or got an error
+    if (ZigbeeScanStatus == ZB_SCAN_FAILED) {
+      Serial.println("WiFi Scan has failed. Starting again.");
+      Zigbee.scanNetworks();
+    }
+    // other option is status ZB_SCAN_RUNNING - just wait.
+  } else {  // Found Zero or more Wireless Networks
+    printScannedNetworks(ZigbeeScanStatus);
+    Zigbee.scanNetworks();  // start over...
+  }
+
+  // Loop can do something else...
+  delay(500);
+  Serial.println("Loop running...");
+}

libraries/Zigbee/examples/Zigbee_simple/Zigbee_simple.ino

@@ -10,6 +10,8 @@ Zigbee_Core::Zigbee_Core() {
   _zb_ep_list = esp_zb_ep_list_create();
   _primary_channel_mask = ESP_ZB_TRANSCEIVER_ALL_CHANNELS_MASK;
   _open_network = 0;
+  _scan_status = ZB_SCAN_FAILED;
+  _started = false;
 }
 Zigbee_Core::~Zigbee_Core() {}
 
@@ -91,19 +93,22 @@ bool Zigbee_Core::zigbeeInit(esp_zb_cfg_t *zb_cfg, bool erase_nvs) {
   esp_zb_init(zb_cfg);
 
   // Register all Zigbee EPs in list 
-  log_d("Register all Zigbee EPs in list");
-  err = esp_zb_device_register(_zb_ep_list);
-  if (err != ESP_OK) {
-    log_e("Failed to register Zigbee EPs");
-    return false;
-  }
-  
-  //print the list of Zigbee EPs from ep_objects
-  log_i("List of registered Zigbee EPs:");
-  for (std::list<Zigbee_EP*>::iterator it = ep_objects.begin(); it != ep_objects.end(); ++it) {
-    log_i("Device type: %s, Endpoint: %d, Device ID: 0x%04x", getDeviceTypeString((*it)->_device_id), (*it)->_endpoint, (*it)->_device_id);
+  if(ep_objects.empty()) {
+    log_w("No Zigbee EPs to register");
+  } else {
+    log_d("Register all Zigbee EPs in list");
+    err = esp_zb_device_register(_zb_ep_list);
+    if (err != ESP_OK) {
+      log_e("Failed to register Zigbee EPs");
+      return false;
+    }
+    
+    //print the list of Zigbee EPs from ep_objects
+    log_i("List of registered Zigbee EPs:");
+    for (std::list<Zigbee_EP*>::iterator it = ep_objects.begin(); it != ep_objects.end(); ++it) {
+      log_i("Device type: %s, Endpoint: %d, Device ID: 0x%04x", getDeviceTypeString((*it)->_device_id), (*it)->_endpoint, (*it)->_device_id);
+    }
   }
-
   // Register Zigbee action handler
   esp_zb_core_action_handler_register(zb_action_handler);
   err = esp_zb_set_primary_network_channel_set(_primary_channel_mask);
@@ -159,7 +164,6 @@ void esp_zb_app_signal_handler(esp_zb_app_signal_t *signal_struct) {
   //coordinator variables
   esp_zb_zdo_signal_device_annce_params_t *dev_annce_params = NULL;
 
-  log_d("Zigbee role: %d", Zigbee._role);
   //main switch
   switch (sig_type) {
     case ESP_ZB_ZDO_SIGNAL_SKIP_STARTUP: // Common
@@ -183,8 +187,7 @@ void esp_zb_app_signal_handler(esp_zb_app_signal_t *signal_struct) {
 
         } else {
           log_i("Device rebooted");
-
-          // Implement opening network for joining after reboot if set
+          Zigbee._started = true;
           if ((zigbee_role_t)Zigbee._role == ZIGBEE_COORDINATOR && Zigbee._open_network > 0) {
             log_i("Openning network for joining for %d seconds", Zigbee._open_network);
             esp_zb_bdb_open_network(Zigbee._open_network);
@@ -213,6 +216,7 @@ void esp_zb_app_signal_handler(esp_zb_app_signal_t *signal_struct) {
       }
       break;
     case ESP_ZB_BDB_SIGNAL_STEERING: // Router and End Device
+      Zigbee._started = true;
       if ((zigbee_role_t)Zigbee._role == ZIGBEE_COORDINATOR) {
         if (err_status == ESP_OK) {
           log_i("Network steering started");
@@ -283,18 +287,56 @@ void Zigbee_Core::factoryReset() {
   esp_zb_factory_reset();
 }
 
+bool Zigbee_Core::isStarted() {
+  return _started;
+}
+
+void Zigbee_Core::scanCompleteCallback(esp_zb_zdp_status_t zdo_status, uint8_t count, esp_zb_network_descriptor_t *nwk_descriptor){
+  log_v("Zigbee network scan complete");
+  if(zdo_status == ESP_ZB_ZDP_STATUS_SUCCESS) {
+    log_v("Found %d networks", count);
+    //print Zigbee networks
+    for (int i = 0; i < count; i++) {
+      log_v("Network %d: PAN ID: 0x%04hx, Permit Joining: %s, Extended PAN ID: %02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x, Channel: %d, Router Capacity: %s, End Device Capacity: %s",
+        i, nwk_descriptor[i].short_pan_id, nwk_descriptor[i].permit_joining ? "Yes" : "No", nwk_descriptor[i].extended_pan_id[7], nwk_descriptor[i].extended_pan_id[6], nwk_descriptor[i].extended_pan_id[5], nwk_descriptor[i].extended_pan_id[4], nwk_descriptor[i].extended_pan_id[3], nwk_descriptor[i].extended_pan_id[2], nwk_descriptor[i].extended_pan_id[1], nwk_descriptor[i].extended_pan_id[0], nwk_descriptor[i].logic_channel, nwk_descriptor[i].router_capacity ? "Yes" : "No", nwk_descriptor[i].end_device_capacity ? "Yes" : "No");
+    }
+    //save scan result and update scan status
+    //copy network descriptor to _scan_result to keep the data after the callback
+    Zigbee._scan_result = (esp_zb_network_descriptor_t *)malloc(count * sizeof(esp_zb_network_descriptor_t));
+    memcpy(Zigbee._scan_result, nwk_descriptor, count * sizeof(esp_zb_network_descriptor_t));
+    Zigbee._scan_status = count;
+  } else {
+    log_e("Failed to scan Zigbee network (status: 0x%x)", zdo_status);
+    Zigbee._scan_status = ZB_SCAN_FAILED;
+    Zigbee._scan_result = nullptr;
+  }
+}
+
+void Zigbee_Core::scanNetworks(u_int32_t channel_mask, u_int8_t scan_duration) {
+  if(!_started) {
+    log_e("Zigbee stack is not started, cannot scan networks");
+    return;
+  }
+  log_v("Scanning Zigbee networks");
+  esp_zb_zdo_active_scan_request(channel_mask, scan_duration, scanCompleteCallback);
+  _scan_status = ZB_SCAN_RUNNING;
+}
+
+int16_t Zigbee_Core::scanComplete(){
+  return _scan_status;
+}
+
+zigbee_scan_result_t* Zigbee_Core::getScanResult() {
+  return _scan_result;
+}
 
-// TODO: Implement scanning network
-// /**
-//  * @brief   Active scan available network.
-//  *
-//  * Network discovery service for scanning available network
-//  *
-//  * @param[in] channel_mask Valid channel mask is from 0x00000800 (only channel 11) to 0x07FFF800 (all channels from 11 to 26)
-//  * @param[in] scan_duration Time to spend scanning each channel
-//  * @param[in] user_cb   A user callback to get the active scan result please refer to esp_zb_zdo_scan_complete_callback_t
-//  */
-// void esp_zb_zdo_active_scan_request(uint32_t channel_mask, uint8_t scan_duration, esp_zb_zdo_scan_complete_callback_t user_cb);
+void Zigbee_Core::scanDelete() {
+  if (_scan_result != nullptr) {
+    free(_scan_result);
+    _scan_result = nullptr;
+  }
+  _scan_status = ZB_SCAN_FAILED;
+}
 
 // NOTE: Binding functions to not forget
 // void esp_zb_zdo_device_bind_req(esp_zb_zdo_bind_req_param_t *cmd_req, esp_zb_zdo_bind_callback_t user_cb, void *user_ctx)