README.md

@@ -41,6 +41,8 @@
 
 1. [zh_vector](https://github.com/aZholtikov/zh_vector.git)
 
+## [Function description](http://zh-network.zh.com.ru)
+
 ## Using
 
 In an existing project, run the following command to install the component:
@@ -92,8 +94,8 @@ void app_main(void)
     esp_wifi_set_mode(WIFI_MODE_STA);
     esp_wifi_start();
     esp_wifi_set_max_tx_power(8); // Power reduction is for example and testing purposes only. Do not use in your own programs!
-    zh_network_init_config_t network_init_config = ZH_NETWORK_INIT_CONFIG_DEFAULT();
+    zh_network_init_config_t zh_network_init_config = ZH_NETWORK_INIT_CONFIG_DEFAULT();
-    zh_network_init(&network_init_config);
+    zh_network_init(&zh_network_init_config);
 #ifdef CONFIG_IDF_TARGET_ESP8266
     esp_event_handler_register(ZH_NETWORK, ESP_EVENT_ANY_ID, &zh_network_event_handler, NULL);
 #else
@@ -125,7 +127,7 @@ void zh_network_event_handler(void *arg, esp_event_base_t event_base, int32_t ev
         printf("Int %d\n", recv_message->int_value);
         printf("Float %f\n", recv_message->float_value);
         printf("Bool %d\n", recv_message->bool_value);
-        heap_caps_free(recv_data->data); // Do not delete to avoid memory leaks!
+        free(recv_data->data); // Do not delete to avoid memory leaks!
         break;
     case ZH_NETWORK_ON_SEND_EVENT:;
         zh_network_event_on_send_t *send_data = event_data;

include/zh_network.h

@@ -1,3 +1,9 @@
+/**
+ * @file
+ * Header file for the zh_network component.
+ *
+ */
+
 #pragma once
 
 #include "string.h"
@@ -17,8 +23,25 @@
 #include "esp_mac.h"
 #endif
 
-#define ZH_NETWORK_MAX_MESSAGE_SIZE 218 // Maximum value of the transmitted data size. @attention All devices on the network must have the same ZH_NETWORK_MAX_MESSAGE_SIZE.
+/**
+ * @brief Unique identifier of ESP-NOW interface events base. Used when registering the event handler.
+ *
+ */
+#define ESP_EVENT_BASE ZH_NETWORK
 
+/**
+ * @brief Maximum value of the transmitted data size.
+ *
+ * @note Value range from 1 to 218. Smaller size - higher transmission speed.
+ *
+ * @attention All devices on the network must have the same ZH_NETWORK_MAX_MESSAGE_SIZE.
+ */
+#define ZH_NETWORK_MAX_MESSAGE_SIZE 218
+
+/**
+ * @brief Default values for zh_network_init_config_t structure for initial initialization of ESP-NOW interface.
+ *
+ */
 #define ZH_NETWORK_INIT_CONFIG_DEFAULT() \
     {                                    \
         .network_id = 0xFAFBFCFD,        \
@@ -38,45 +61,72 @@ extern "C"
 {
 #endif
 
-    typedef struct // Structure for initial initialization of ESP-NOW interface.
+    /**
+     * @brief Structure for initial initialization of ESP-NOW interface.
+     *
+     * @note Before initialize ESP-NOW interface recommend initialize zh_network_init_config_t structure with default values.
+     *
+     * @code zh_network_init_config_t config = ZH_NETWORK_INIT_CONFIG_DEFAULT() @endcode
+     */
+    typedef struct
     {
-        uint32_t network_id;             // A unique ID for the mesh network. @attention The ID must be the same for all nodes in the network.
+        uint32_t network_id;             ///< A unique ID for the mesh network. @attention The ID must be the same for all nodes in the network.
-        uint8_t task_priority;           // Task priority for the ESP-NOW messages processing. @note It is not recommended to set a value less than 4.
+        uint8_t task_priority;           ///< Task priority for the ESP-NOW messages processing. @note It is not recommended to set a value less than 4.
-        uint16_t stack_size;             // Stack size for task for the ESP-NOW messages processing. @note The minimum size is 3072 bytes.
+        uint16_t stack_size;             ///< Stack size for task for the ESP-NOW messages processing. @note The minimum size is 3072 bytes.
-        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. It is not recommended to set the value less than 32.
+        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. It is not recommended to set the value less than 32.
-        uint16_t max_waiting_time;       // Maximum time to wait a response message from target node (in milliseconds). @note If a response message from the target node is not received within this time, the status of the sent message will be "sent fail".
+        uint16_t max_waiting_time;       ///< Maximum time to wait a response message from target node (in milliseconds). @note If a response message from the target node is not received within this time, the status of the sent message will be "sent fail".
-        uint16_t id_vector_size;         // Maximum size of unique ID of received messages. @note If the size is exceeded, the first value will be deleted. Minimum recommended value: number of planned nodes in the network + 10%.
+        uint16_t id_vector_size;         ///< Maximum size of unique ID of received messages. @note If the size is exceeded, the first value will be deleted. Minimum recommended value: number of planned nodes in the network + 10%.
-        uint16_t route_vector_size;      // The maximum size of the routing table. @note If the size is exceeded, the first route will be deleted. Minimum recommended value: number of planned nodes in the network + 10%.
+        uint16_t route_vector_size;      ///< The maximum size of the routing table. @note If the size is exceeded, the first route will be deleted. Minimum recommended value: number of planned nodes in the network + 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. @note The MAC address of the device depends on the selected WiFi interface.
-        uint8_t wifi_channel;            // Wi-Fi channel uses to send/receive ESPNOW data. @note Values from 1 to 14.
+        uint8_t wifi_channel;            ///< Wi-Fi channel uses to send/receive ESPNOW data. @note Values from 1 to 14.
-        uint8_t attempts;                // Maximum number of attempts to send a message. @note It is not recommended to set a value greater than 5.
+        uint8_t attempts;                ///< Maximum number of attempts to send a message. @note It is not recommended to set a value greater than 5.
     } zh_network_init_config_t;
 
-    ESP_EVENT_DECLARE_BASE(ZH_NETWORK);
+    /// \cond
+    ESP_EVENT_DECLARE_BASE(ESP_EVENT_BASE);
+    /// \endcond
 
-    typedef enum // Enumeration of possible ESP-NOW events.
+    /**
+     * @brief Enumeration of possible ESP-NOW events.
+     *
+     */
+    typedef enum
     {
-        ZH_NETWORK_ON_RECV_EVENT, // The event when the ESP-NOW message was received.
+        ZH_NETWORK_ON_RECV_EVENT, ///< The event when the ESP-NOW message was received.
-        ZH_NETWORK_ON_SEND_EVENT  // The event when the ESP-NOW message was sent.
+        ZH_NETWORK_ON_SEND_EVENT  ///< The event when the ESP-NOW message was sent.
     } zh_network_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_NETWORK_SEND_SUCCESS, // If ESP-NOW message was sent success.
+        ZH_NETWORK_SEND_SUCCESS, ///< If ESP-NOW message was sent success.
-        ZH_NETWORK_SEND_FAIL     // If ESP-NOW message was sent fail.
+        ZH_NETWORK_SEND_FAIL     ///< If ESP-NOW message was sent fail.
     } zh_network_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_NETWORK event base and ZH_NETWORK_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_NETWORK event base and ZH_NETWORK_ON_SEND_EVENT event.
+     */
+    typedef struct
     {
-        uint8_t mac_addr[6];                    // MAC address of the device to which the ESP-NOW message was sent.
+        uint8_t mac_addr[6];                    ///< MAC address of the device to which the ESP-NOW message was sent. @note
-        zh_network_on_send_event_type_t status; // Status of sent ESP-NOW message.
+        zh_network_on_send_event_type_t status; ///< Status of sent ESP-NOW message. @note
     } zh_network_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_NETWORK event base and ZH_NETWORK_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_NETWORK event base and ZH_NETWORK_ON_RECV_EVENT event.
+     */
+    typedef struct
     {
-        uint8_t mac_addr[6]; // MAC address of the sender ESP-NOW message.
+        uint8_t mac_addr[6]; ///< MAC address of the sender ESP-NOW message. @note
-        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. @note
-        uint8_t data_len;    // Size of the received ESP-NOW message.
+        uint8_t data_len;    ///< Size of the received ESP-NOW message. @note
     } zh_network_event_on_recv_t;
 
     /**

version.txt

@@ -1 +1 @@
-1.0.2
+1.0.1

zh_network.c

@@ -1,8 +1,15 @@
+/**
+ * @file
+ * The main code of the zh_network component.
+ */
+
 #include "zh_network.h"
 
+/// \cond
 #define DATA_SEND_SUCCESS BIT0
 #define DATA_SEND_FAIL BIT1
 #define MAC2STR(a) (a)[0], (a)[1], (a)[2], (a)[3], (a)[4], (a)[5]
+/// \endcond
 
 static void _send_cb(const uint8_t *mac_addr, esp_now_send_status_t status);
 #if defined CONFIG_IDF_TARGET_ESP8266 || ESP_IDF_VERSION_MAJOR == 4
@@ -27,6 +34,7 @@ static const uint8_t _broadcast_mac[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};
 static bool _is_initialized = false;
 static uint8_t _attempts = 0;
 
+/// \cond
 typedef struct
 {
     uint8_t original_target_mac[6];
@@ -65,6 +73,7 @@ typedef struct
 } _queue_t;
 
 ESP_EVENT_DEFINE_BASE(ZH_NETWORK);
+/// \endcond
 
 esp_err_t zh_network_init(const zh_network_init_config_t *config)
 {
@@ -77,7 +86,7 @@ esp_err_t zh_network_init(const zh_network_init_config_t *config)
     _init_config = *config;
     if (_init_config.wifi_channel < 1 || _init_config.wifi_channel > 14)
     {
-        ESP_LOGE(TAG, "ESP-NOW initialization fail. WiFi channel incorrect.");
+        ESP_LOGE(TAG, "ESP-NOW initialization fail. WiFi channel.");
         return ESP_ERR_INVALID_ARG;
     }
     esp_err_t err = esp_wifi_set_channel(_init_config.wifi_channel, WIFI_SECOND_CHAN_NONE);