feat(802.15.4): IEEE802.15.4 add documentation and refactor component structure

components/ieee802154/driver/esp_ieee802154_debug.c

@@ -401,15 +401,15 @@ void ieee802154_rx_buffer_statistic_print(void)
     for (uint8_t i = 0; i < (IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL + 1); i++) {
         total_times += s_rx_buffer_used_water_level[i];
     }
-    ESP_LOGW(IEEE802154_TAG, "+--------------------+-------------------------+-------------------------+");
+    ESP_LOGW(IEEE802154_TAG, "+-------------------------+-------------------------+");
-    ESP_LOGW(IEEE802154_TAG, "|%-20s|%-25s|%-25u|", "rx buff total size:", "", CONFIG_IEEE802154_RX_BUFFER_SIZE);
+    ESP_LOGW(IEEE802154_TAG, "|%25s|%-25u|", "rx buff total size:", CONFIG_IEEE802154_RX_BUFFER_SIZE);
-    ESP_LOGW(IEEE802154_TAG, "|%-20s|%-25s|%-25llu|", "buffer alloc times:", "", total_times);
+    ESP_LOGW(IEEE802154_TAG, "|%25s|%-25llu|", "buffer alloc times:", total_times);
-    ESP_LOGW(IEEE802154_TAG, "+--------------------+-------------------------+-------------------------+");
+    ESP_LOGW(IEEE802154_TAG, "+-------------------------+-------------------------+");
     for (uint8_t i = 0; i < (IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL); i++) {
-        ESP_LOGW(IEEE802154_TAG, "|%-20s|%4d%%%5s%4d%%%-10s|%-15llu%9.2f%%|", "", ((i) * 100 / IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL), "~", ((i + 1) * 100 / IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL), " used:", s_rx_buffer_used_water_level[i], ((float)s_rx_buffer_used_water_level[i] / (float)total_times)*100);
+        ESP_LOGW(IEEE802154_TAG, "|%4d%%%5s%4d%%%10s|%-15llu%9.2f%%|", ((i) * 100 / IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL), "~", ((i + 1) * 100 / IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL), " used:", s_rx_buffer_used_water_level[i], ((float)s_rx_buffer_used_water_level[i] / (float)total_times)*100);
     }
-    ESP_LOGW(IEEE802154_TAG, "|%-20s|%-25s|%-15llu%9.2f%%|", "", "full used:", s_rx_buffer_used_water_level[IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL], ((float)s_rx_buffer_used_water_level[IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL] / (float)total_times)*100);
+    ESP_LOGW(IEEE802154_TAG, "|%25s|%-15llu%9.2f%%|", "full used:", s_rx_buffer_used_water_level[IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL], ((float)s_rx_buffer_used_water_level[IEEE802154_RX_BUFFER_USED_TOTAL_LEVEL] / (float)total_times)*100);
-    ESP_LOGW(IEEE802154_TAG, "+--------------------+-------------------------+-------------------------+");
+    ESP_LOGW(IEEE802154_TAG, "+-------------------------+-------------------------+");
 }
 
 #endif // CONFIG_IEEE802154_RX_BUFFER_STATISTIC

examples/ieee802154/components/cmd_ieee802154_debug/CMakeLists.txt

@@ -1,3 +1,3 @@
-idf_component_register(SRCS "ieee802154_stats.c"
+idf_component_register(SRCS "ieee802154_debug.c"
                     INCLUDE_DIRS "."
                     REQUIRES ieee802154 console esp_phy)

examples/ieee802154/components/cmd_ieee802154_debug/README.md

@@ -0,0 +1,68 @@
+| Supported Targets | ESP32-C5 | ESP32-C6 | ESP32-H2 |
+| ----------------- | -------- | -------- | -------- |
+
+# IEEE802.15.4 RX Buffer Statistics Component
+
+This component is used to consolidate the RX buffer statistics for IEEE802.15.4. The use of this component is demonstrated in the `ieee802154_cli` example, but can be similarly implemented for other stack examples (e.g. Zigbee / Thread). 
+
+## How to use component 
+
+In addition to the necessary configurations described in the `ieee802154_cli` example, some additional steps are required for configuring the board to enable the RX buffer statistics component.
+
+```
+idf.py menuconfig
+```
+
+This component can be enabled through the menuconfig:
+
+```
+Component config → IEEE 802.15.4 → IEEE802154 Enable → Enable IEEE802154 Debug → Rx buffer statistic
+```
+
+### Build, Flash, and Run
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT build flash monitor
+```
+
+Now you'll get an IEEE802.15.4 command line shell.
+
+## IEEE802.15.4 Command List
+
+In addition to the commands available in the `ieee802154_cli` example, enabling this component provides a new command: 
+
+- [rxbufstat](#rxbufstat)
+
+### rxbufstat
+#### rxbufstat -p
+Print a summary table of rx buffer statistics.
+
+```bash
+> rxbufstat -p
+W (913011) ieee802154: +-------------------------+-------------------------+
+W (913011) ieee802154: |      rx buff total size:|20                       |
+W (913021) ieee802154: |      buffer alloc times:|80                       |
+W (913021) ieee802154: +-------------------------+-------------------------+
+W (913031) ieee802154: |   0%    ~  10%     used:|80                100.00%|
+W (913031) ieee802154: |  10%    ~  20%     used:|0                   0.00%|
+W (913041) ieee802154: |  20%    ~  30%     used:|0                   0.00%|
+W (913051) ieee802154: |  30%    ~  40%     used:|0                   0.00%|
+W (913051) ieee802154: |  40%    ~  50%     used:|0                   0.00%|
+W (913061) ieee802154: |  50%    ~  60%     used:|0                   0.00%|
+W (913061) ieee802154: |  60%    ~  70%     used:|0                   0.00%|
+W (913081) ieee802154: |  70%    ~  80%     used:|0                   0.00%|
+W (913091) ieee802154: |  80%    ~  90%     used:|0                   0.00%|
+W (913091) ieee802154: |  90%    ~ 100%     used:|0                   0.00%|
+W (913101) ieee802154: |               full used:|0                   0.00%|
+W (913101) ieee802154: +-------------------------+-------------------------+
+```
+
+#### rxbufstat -c
+Clear the rx buffer statistics.
+
+```bash
+> rxbufstat -c
+I (7971) i154cmd: clear the rx buffer statistics 
+```

examples/ieee802154/components/cmd_ieee802154_debug/ieee802154_debug.c

@@ -10,7 +10,7 @@
 #include "esp_ieee802154.h"
 #include "esp_console.h"
 #include "argtable3/argtable3.h"
-#include "ieee802154_stats.h"
+#include "ieee802154_debug.h"
 
 #if CONFIG_IEEE802154_DEBUG
 static const char* TAG = "i154cmd";
@@ -60,6 +60,7 @@ static int process_rx_buffer_statistic(int argc, char **argv)
     }
     if (rx_buff_stat_args.clear->count) {
         esp_ieee802154_rx_buffer_statistic_clear();
+        ESP_LOGI(TAG, "clear the rx buffer statistics");
     }
     if (!rx_buff_stat_args.print->count && !rx_buff_stat_args.clear->count) {
         ESP_LOGE(TAG, "no valid arguments");
@@ -71,14 +72,14 @@ static int process_rx_buffer_statistic(int argc, char **argv)
 static void register_rx_buffer_statistic(void)
 {
     rx_buff_stat_args.print =
-        arg_lit0("p", "print", "print the result of rx buffer statistic");
+        arg_lit0("p", "print", "print a summary table of rx buffer statistics");
     rx_buff_stat_args.clear =
-        arg_lit0("c", "clear", "clear the result of rx buffer statistic");
+        arg_lit0("c", "clear", "clear the rx buffer statistics");
     rx_buff_stat_args.end = arg_end(2);
 
     const esp_console_cmd_t cmd = {
         .command = "rxbufstat",
-        .help = "rx buffer statistic",
+        .help = "rx buffer statistics",
         .hint = NULL,
         .func = &process_rx_buffer_statistic,
         .argtable = &rx_buff_stat_args

examples/ieee802154/ieee802154_cli/main/CMakeLists.txt

@@ -7,5 +7,5 @@ set(include "."
 # the component can be registered as WHOLE_ARCHIVE
 idf_component_register(SRCS ${srcs}
                        PRIV_REQUIRES ieee802154 console fatfs nvs_flash esp_phy cmd_ieee802154
-                                     cmd_ieee802154_stats cmd_system
+                                     cmd_ieee802154_debug cmd_system
                        WHOLE_ARCHIVE)

examples/ieee802154/ieee802154_cli/main/esp_ieee802154_cli.c

@@ -16,7 +16,7 @@
 #include "esp_ieee802154.h"
 #include "esp_phy_init.h"
 #include "cmd_system.h"
-#include "ieee802154_stats.h"
+#include "ieee802154_debug.h"
 
 #define PROMPT_STR "ieee802154"
 

examples/ieee802154/ieee802154_cli/main/idf_component.yml

@@ -2,3 +2,5 @@
 dependencies:
   cmd_system:
     path: ${IDF_PATH}/examples/system/console/advanced/components/cmd_system
+  cmd_ieee802154_debug:
+    path: ${IDF_PATH}/examples/ieee802154/components/cmd_ieee802154_debug