perf: renamed task handle

README.md

@@ -3,7 +3,7 @@
 ## Tested on
 
 1. [ESP8266 RTOS_SDK v3.4](https://docs.espressif.com/projects/esp8266-rtos-sdk/en/latest/index.html#)
-2. [ESP32 ESP-IDF v5.4](https://docs.espressif.com/projects/esp-idf/en/release-v5.4/esp32/index.html)
+2. [ESP32 ESP-IDF v5.5](https://docs.espressif.com/projects/esp-idf/en/release-v5.5/esp32/index.html)
 
 ## Features
 

include/zh_espnow.h

@@ -1,3 +1,7 @@
+/**
+ * @file zh_espnow.h
+ */
+
 #pragma once
 
 #include "string.h"
@@ -9,6 +13,9 @@
 #include "esp_log.h"
 #include "esp_heap_caps.h"
 
+/**
+ * @brief ESP-NOW interface initial default values.
+ */
 #define ZH_ESPNOW_INIT_CONFIG_DEFAULT() \
     {                                   \
         .task_priority = 10,            \
@@ -24,49 +31,73 @@ extern "C"
 {
 #endif
 
-    typedef struct // Structure for initial initialization of ESP-NOW interface.
+    extern TaskHandle_t zh_espnow; /*!< ESP-NOW interface Task Handle. */
+
+    /**
+     * @brief Structure for initial initialization of ESP-NOW interface.
+     */
+    typedef struct
     {
-        uint8_t task_priority;           // Task priority for the ESP-NOW messages processing. @note The minimum size is 5.
+        uint8_t task_priority;           /*!< Task priority for the ESP-NOW messages processing. @note The minimum value is 5. */
-        uint16_t stack_size;             // Stack size for task for the ESP-NOW messages processing. @note The minimum size is 2048.
+        uint16_t stack_size;             /*!< Stack size for task for the ESP-NOW messages processing. @note The minimum size is 2048. */
-        uint8_t queue_size;              // Queue size for task for the ESP-NOW messages processing. @note The size depends on the number of messages to be processed. The minimum size is 16.
+        uint8_t queue_size;              /*!< Queue size for task for the ESP-NOW messages processing. @note The minimum value is 10. */
-        wifi_interface_t wifi_interface; // WiFi interface (STA or AP) used for ESP-NOW operation. @note The MAC address of the device depends on the selected WiFi interface.
+        wifi_interface_t wifi_interface; /*!< WiFi interface (STA or AP) used for ESP-NOW operation. */
-        uint8_t wifi_channel;            // Wi-Fi channel uses to send/receive ESP-NOW data. @note Values from 1 to 14.
+        uint8_t wifi_channel;            /*!< Wi-Fi channel uses to send/receive ESP-NOW data. */
-        uint8_t attempts;                // Maximum number of attempts to send a message. @note It is not recommended to set a value greater than 10.
+        uint8_t attempts;                /*!< Maximum number of attempts to send a message. @note It is not recommended to set a value greater than 10. */
-        bool battery_mode;               // Battery operation mode. If true the node does not receive messages.
+        bool battery_mode;               /*!< Battery operation mode. If true the node does not receive messages. */
     } zh_espnow_init_config_t;
 
     ESP_EVENT_DECLARE_BASE(ZH_ESPNOW);
 
-    typedef enum // Enumeration of possible ESP-NOW events.
+    /**
+     * @brief Enumeration of possible ESP-NOW events.
+     */
+    typedef enum
     {
-        ZH_ESPNOW_ON_RECV_EVENT, // The event when the ESP-NOW message was received.
+        ZH_ESPNOW_ON_RECV_EVENT, /*!< The event when the ESP-NOW message was received. */
-        ZH_ESPNOW_ON_SEND_EVENT  // The event when the ESP-NOW message was sent.
+        ZH_ESPNOW_ON_SEND_EVENT  /*!< The event when the ESP-NOW message was sent. */
     } zh_espnow_event_type_t;
 
-    typedef enum // Enumeration of possible status of sent ESP-NOW message.
+    /**
+     * @brief Enumeration of possible status of sent ESP-NOW message.
+     */
+    typedef enum
     {
-        ZH_ESPNOW_SEND_SUCCESS, // If ESP-NOW message was sent success.
+        ZH_ESPNOW_SEND_SUCCESS, /*!< If ESP-NOW message was sent success. */
-        ZH_ESPNOW_SEND_FAIL     // If ESP-NOW message was sent fail.
+        ZH_ESPNOW_SEND_FAIL     /*!< If ESP-NOW message was sent fail. */
     } zh_espnow_on_send_event_type_t;
 
-    typedef struct // Structure for sending data to the event handler when an ESP-NOW message was sent. @note Should be used with ZH_ESPNOW event base and ZH_ESPNOW_ON_SEND_EVENT event.
+    /**
+     * @brief Structure for sending data to the event handler when an ESP-NOW message was sent.
+     *
+     * @note Should be used with ZH_ESPNOW event base and ZH_ESPNOW_ON_SEND_EVENT event.
+     */
+    typedef struct
     {
-        uint8_t mac_addr[ESP_NOW_ETH_ALEN];    // MAC address of the device to which the ESP-NOW message was sent.
+        uint8_t mac_addr[ESP_NOW_ETH_ALEN];    /*!< MAC address of the device to which the ESP-NOW message was sent. */
-        zh_espnow_on_send_event_type_t status; // Status of sent ESP-NOW message.
+        zh_espnow_on_send_event_type_t status; /*!< Status of sent ESP-NOW message. */
     } zh_espnow_event_on_send_t;
 
-    typedef struct // Structure for sending data to the event handler when an ESP-NOW message was received. @note Should be used with ZH_ESPNOW event base and ZH_ESPNOW_ON_RECV_EVENT event.
+    /**
+     * @brief Structure for sending data to the event handler when an ESP-NOW message was received.
+     *
+     * @note Should be used with ZH_ESPNOW event base and ZH_ESPNOW_ON_RECV_EVENT event.
+     */
+    typedef struct
     {
-        uint8_t mac_addr[ESP_NOW_ETH_ALEN]; // MAC address of the sender ESP-NOW message.
+        uint8_t mac_addr[ESP_NOW_ETH_ALEN]; /*!< MAC address of the sender ESP-NOW message. */
-        uint8_t *data;                      // Pointer to the data of the received ESP-NOW message.
+        uint8_t *data;                      /*!< Pointer to the data of the received ESP-NOW message. */
-        uint16_t data_len;                  // Size of the received ESP-NOW message.
+        uint16_t data_len;                  /*!< Size of the received ESP-NOW message. */
     } zh_espnow_event_on_recv_t;
 
-    typedef struct // Structure for message statistics storage.
+    /**
+     * @brief Structure for message statistics storage.
+     */
+    typedef struct
     {
-        uint32_t sent_success; // Number of successfully sent messages.
+        uint32_t sent_success; /*!< Number of successfully sent messages. */
-        uint32_t sent_fail;    // Number of failed sent messages.
+        uint32_t sent_fail;    /*!< Number of failed sent messages. */
-        uint32_t received;     // Number of received messages.
+        uint32_t received;     /*!< Number of received messages. */
     } zh_espnow_stats_t;
 
     /**
@@ -187,6 +218,18 @@ extern "C"
      */
     esp_err_t zh_espnow_get_mac(uint8_t *mac_addr);
 
+    /**
+     * @brief Get the number of available places in the queue.
+     *
+     * @return Number of available places.
+     */
+    uint8_t zh_espnow_get_queue_space(void);
+
+    /**
+     * @brief Clean up the message queue.
+     */
+    void zh_espnow_clear_queue(void);
+
 #ifdef __cplusplus
 }
 #endif

version.txt

@@ -1 +1 @@
-1.7.0
+1.9.0

zh_espnow.c

@@ -14,6 +14,13 @@ static const char *TAG = "zh_espnow";
         return err;                          \
     }
 
+#define ZH_ESPNOW_CHECK_GOTO(cond, err, tag, msg, ...) \
+    if (!(cond))                                       \
+    {                                                  \
+        ZH_ESPNOW_LOGE_ERR(msg, err);                  \
+        goto tag;                                      \
+    }
+
 #define DATA_SEND_SUCCESS BIT0
 #define DATA_SEND_FAIL BIT1
 #define WAIT_CONFIRM_MAX_TIME 50
@@ -41,7 +48,12 @@ static esp_err_t _zh_espnow_init_resources(const zh_espnow_init_config_t *config
 static esp_err_t _zh_espnow_validate_config(const zh_espnow_init_config_t *config);
 static esp_err_t _zh_espnow_register_callbacks(bool battery_mode);
 static esp_err_t _zh_espnow_create_task(const zh_espnow_init_config_t *config);
+
+#if ESP_IDF_VERSION_MAJOR >= 5 && ESP_IDF_VERSION_MINOR >= 5
+static void _zh_espnow_send_cb(const esp_now_send_info_t *esp_now_info, esp_now_send_status_t status);
+#else
 static void _zh_espnow_send_cb(const uint8_t *mac_addr, esp_now_send_status_t status);
+#endif
 #if defined CONFIG_IDF_TARGET_ESP8266 || ESP_IDF_VERSION_MAJOR == 4
 static void _zh_espnow_recv_cb(const uint8_t *mac_addr, const uint8_t *data, int data_len);
 #else
@@ -51,9 +63,9 @@ static void _zh_espnow_process_send(_queue_t *queue);
 static void _zh_espnow_process_recv(_queue_t *queue);
 static void _zh_espnow_processing(void *pvParameter);
 
-static EventGroupHandle_t _event_group_handle = {0};
+TaskHandle_t zh_espnow = NULL;
-static QueueHandle_t _queue_handle = {0};
+static EventGroupHandle_t _event_group_handle = NULL;
-static TaskHandle_t _processing_task_handle = {0};
+static QueueHandle_t _queue_handle = NULL;
 static zh_espnow_init_config_t _init_config = {0};
 static zh_espnow_stats_t _stats = {0};
 static bool _is_initialized = false;
@@ -73,66 +85,24 @@ esp_err_t zh_espnow_init(const zh_espnow_init_config_t *config)
         return ESP_OK;
     }
     esp_err_t err = _zh_espnow_validate_config(config);
-    if (err != ESP_OK)
+    ZH_ESPNOW_CHECK(err == ESP_OK, err, "ESP-NOW initialization failed. Initial configuration check failed.");
-    {
-        ZH_ESPNOW_LOGE("ESP-NOW initialization failed. Initial configuration check failed.");
-        return err;
-    }
-    else
-    {
     ZH_ESPNOW_LOGI("ESP-NOW initial configuration check completed successfully.");
-    }
     _init_config = *config;
     err = _zh_espnow_init_wifi(config);
-    if (err != ESP_OK)
+    ZH_ESPNOW_CHECK(err == ESP_OK, err, "ESP-NOW initialization failed. WiFi initialization failed.");
-    {
-        ZH_ESPNOW_LOGE("ESP-NOW initialization failed. WiFi initialization failed.");
-        return err;
-    }
-    else
-    {
     ZH_ESPNOW_LOGI("WiFi initialization completed successfully.");
-    }
     err = _zh_espnow_init_resources(config);
-    if (err != ESP_OK)
+    ZH_ESPNOW_CHECK_GOTO(err == ESP_OK, err, CLEANUP, "ESP-NOW initialization failed. Resources initialization failed.");
-    {
-        ZH_ESPNOW_LOGE("ESP-NOW initialization failed. Resources initialization failed.");
-        goto CLEANUP;
-    }
-    else
-    {
     ZH_ESPNOW_LOGI("ESP-NOW resources initialization completed successfully.");
-    }
     err = esp_now_init();
-    if (err != ESP_OK)
+    ZH_ESPNOW_CHECK_GOTO(err == ESP_OK, err, CLEANUP, "ESP-NOW initialization failed. ESP-NOW driver initialization failed.");
-    {
-        ZH_ESPNOW_LOGE_ERR("ESP-NOW initialization failed. ESP-NOW driver initialization failed.", err);
-        goto CLEANUP;
-    }
-    else
-    {
     ZH_ESPNOW_LOGI("ESP-NOW driver initialization completed successfully.");
-    }
     err = _zh_espnow_register_callbacks(config->battery_mode);
-    if (err != ESP_OK)
+    ZH_ESPNOW_CHECK_GOTO(err == ESP_OK, err, CLEANUP, "ESP-NOW initialization failed. ESP-NOW callbacks registration failed.");
-    {
-        ZH_ESPNOW_LOGE("ESP-NOW initialization failed. ESP-NOW callbacks registration failed.");
-        goto CLEANUP;
-    }
-    else
-    {
     ZH_ESPNOW_LOGI("ESP-NOW callbacks registered successfully.");
-    }
     err = _zh_espnow_create_task(config);
-    if (err != ESP_OK)
+    ZH_ESPNOW_CHECK_GOTO(err == ESP_OK, err, CLEANUP, "ESP-NOW initialization failed. Processing task initialization failed.");
-    {
-        ZH_ESPNOW_LOGE("ESP-NOW initialization failed. Processing task initialization failed.");
-        goto CLEANUP;
-    }
-    else
-    {
     ZH_ESPNOW_LOGI("ESP-NOW processing task initialization completed successfully.");
-    }
     _is_initialized = true;
     ZH_ESPNOW_LOGI("ESP-NOW initialization completed successfully.");
     return ESP_OK;
@@ -204,10 +174,10 @@ esp_err_t zh_espnow_deinit(void)
     {
         ZH_ESPNOW_LOGI("ESP-NOW driver deinitialized.");
     }
-    if (_processing_task_handle != NULL)
+    if (zh_espnow != NULL)
     {
-        vTaskDelete(_processing_task_handle);
+        vTaskDelete(zh_espnow);
-        _processing_task_handle = NULL;
+        zh_espnow = NULL;
         ZH_ESPNOW_LOGI("Processing task deleted.");
     }
     _is_initialized = false;
@@ -272,7 +242,7 @@ static esp_err_t _zh_espnow_init_resources(const zh_espnow_init_config_t *config
     _event_group_handle = xEventGroupCreate();
     ZH_ESPNOW_CHECK(_event_group_handle != NULL, ESP_FAIL, "Event group creation failed.");
     _queue_handle = xQueueCreate(config->queue_size, sizeof(_queue_t));
-    ZH_ESPNOW_CHECK(_queue_handle != 0, ESP_FAIL, "Queue creation failed.");
+    ZH_ESPNOW_CHECK(_queue_handle != NULL, ESP_FAIL, "Queue creation failed.");
     return ESP_OK;
 }
 
@@ -284,7 +254,7 @@ static esp_err_t _zh_espnow_create_task(const zh_espnow_init_config_t *config)
         config->stack_size,
         NULL,
         config->task_priority,
-        &_processing_task_handle,
+        &zh_espnow,
         tskNO_AFFINITY);
     ZH_ESPNOW_CHECK(err == pdPASS, ESP_FAIL, "Task creation failed.");
     return ESP_OK;
@@ -312,6 +282,23 @@ static esp_err_t _zh_espnow_register_callbacks(bool battery_mode)
     return ESP_OK;
 }
 
+#if ESP_IDF_VERSION_MAJOR >= 5 && ESP_IDF_VERSION_MINOR >= 5
+static void IRAM_ATTR _zh_espnow_send_cb(const esp_now_send_info_t *esp_now_info, esp_now_send_status_t status)
+{
+    if (esp_now_info == NULL)
+    {
+        ZH_ESPNOW_LOGE("Send callback received NULL MAC address.");
+        return;
+    }
+    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
+    ZH_ESPNOW_LOGI("ESP-NOW send callback: %s for MAC %02X:%02X:%02X:%02X:%02X:%02X.", (status == ESP_NOW_SEND_SUCCESS) ? "SUCCESS" : "FAIL", MAC2STR(esp_now_info->des_addr));
+    xEventGroupSetBitsFromISR(_event_group_handle, (status == ESP_NOW_SEND_SUCCESS) ? DATA_SEND_SUCCESS : DATA_SEND_FAIL, &xHigherPriorityTaskWoken);
+    if (xHigherPriorityTaskWoken == pdTRUE)
+    {
+        portYIELD_FROM_ISR();
+    };
+}
+#else
 static void IRAM_ATTR _zh_espnow_send_cb(const uint8_t *mac_addr, esp_now_send_status_t status)
 {
     if (mac_addr == NULL)
@@ -327,6 +314,7 @@ static void IRAM_ATTR _zh_espnow_send_cb(const uint8_t *mac_addr, esp_now_send_s
         portYIELD_FROM_ISR();
     };
 }
+#endif
 
 #if defined CONFIG_IDF_TARGET_ESP8266 || ESP_IDF_VERSION_MAJOR == 4
 static void IRAM_ATTR _zh_espnow_recv_cb(const uint8_t *mac_addr, const uint8_t *data, int data_len)
@@ -562,11 +550,7 @@ esp_err_t zh_espnow_set_channel(uint8_t channel)
     ZH_ESPNOW_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "ESP-NOW channel set failed. ESP-NOW is not initialized.");
     ZH_ESPNOW_CHECK(channel > 0 && channel < 15, ESP_ERR_INVALID_ARG, "ESP-NOW channel set failed. Invalid channel.");
     esp_err_t err = esp_wifi_set_channel(channel, WIFI_SECOND_CHAN_NONE);
-    if (err != ESP_OK)
+    ZH_ESPNOW_CHECK(err == ESP_OK, err, "ESP-NOW channel set failed.");
-    {
-        ZH_ESPNOW_LOGE_ERR("ESP-NOW channel set failed.", err);
-        return err;
-    }
     _init_config.wifi_channel = channel;
     ZH_ESPNOW_LOGI("ESP-NOW channel set successfully.");
     return err;
@@ -598,3 +582,28 @@ esp_err_t zh_espnow_get_mac(uint8_t *mac_addr)
 {
     return esp_wifi_get_mac(_init_config.wifi_interface, mac_addr);
 }
+
+uint8_t zh_espnow_get_queue_space(void)
+{
+    if (_queue_handle == NULL)
+    {
+        return 0;
+    }
+    return uxQueueSpacesAvailable(_queue_handle);
+}
+
+void zh_espnow_clear_queue(void)
+{
+    if (_queue_handle != NULL)
+    {
+        _queue_t queue = {0};
+        while (xQueueReceive(_queue_handle, &queue, 0) == pdTRUE)
+        {
+            if (queue.data.payload != NULL)
+            {
+                heap_caps_free(queue.data.payload);
+            }
+        }
+        ZH_ESPNOW_LOGI("Queue clear completed successfully.");
+    }
+}