Merge branch 'feature/add_tx_callback_api_for_80211_tx' into 'master'

feat(wifi): Added tx callback function for 80211 tx

Closes WIFI-6820

See merge request espressif/esp-idf!37673

components/esp_wifi/include/esp_now.h

@@ -57,8 +57,8 @@ extern "C" {
  * @brief Status of sending ESPNOW data .
  */
 typedef enum {
-    ESP_NOW_SEND_SUCCESS = 0,       /**< Send ESPNOW data successfully */
-    ESP_NOW_SEND_FAIL,              /**< Send ESPNOW data fail */
+    ESP_NOW_SEND_SUCCESS = WIFI_SEND_SUCCESS,       /**< Send ESPNOW data successfully */
+    ESP_NOW_SEND_FAIL = WIFI_SEND_FAIL,             /**< Send ESPNOW data fail */
 } esp_now_send_status_t;
 
 /**
@@ -84,7 +84,7 @@ typedef struct esp_now_peer_num {
 } esp_now_peer_num_t;
 
 /**
- * @brief ESPNOW packet information
+ * @brief ESPNOW receive packet information
  */
 typedef struct esp_now_recv_info {
     uint8_t * src_addr;                      /**< Source address of ESPNOW packet */
@@ -92,6 +92,11 @@ typedef struct esp_now_recv_info {
     wifi_pkt_rx_ctrl_t * rx_ctrl;            /**< Rx control info of ESPNOW packet */
 } esp_now_recv_info_t;
 
+/**
+ * @brief ESPNOW sending packet information
+ */
+typedef wifi_tx_info_t esp_now_send_info_t;
+
 /**
  * @brief ESPNOW rate config
  */
@@ -108,10 +113,10 @@ typedef void (*esp_now_recv_cb_t)(const esp_now_recv_info_t * esp_now_info, cons
 
 /**
   * @brief     Callback function of sending ESPNOW data
-  * @param     mac_addr peer MAC address
-  * @param     status status of sending ESPNOW data (succeed or fail)
+  * @param     esp_now_send_info_t Sending information for ESPNOW data
+  * @param     status status of sending ESPNOW data (succeed or fail). This is will be removed later, since the tx_info->tx_status also works.
   */
-typedef void (*esp_now_send_cb_t)(const uint8_t *mac_addr, esp_now_send_status_t status);
+typedef void (*esp_now_send_cb_t)(const esp_now_send_info_t *tx_info, esp_now_send_status_t status);
 
 /**
   * @brief     Initialize ESPNOW function

components/esp_wifi/include/esp_wifi.h

@@ -1198,6 +1198,27 @@ esp_err_t esp_wifi_get_event_mask(uint32_t *mask);
 
 esp_err_t esp_wifi_80211_tx(wifi_interface_t ifx, const void *buffer, int len, bool en_sys_seq);
 
+/**
+  * @brief Callback function of 80211 tx data
+  *
+  * @param tx_info TX information of 80211 tx. The information can only be used in the callback context.
+  */
+typedef void (*esp_wifi_80211_tx_done_cb_t)(const esp_80211_tx_info_t *tx_info);
+
+/**
+  * @brief Register the TX callback function of 80211 tx data.
+  *
+  * @attention This callback will be executed in WiFi task, so avoid doing any time consuming activity in the callback.
+  *            Doing heavy work here can affect the WiFi performance.
+  *
+  * @param cb callback function. If the cb is NULL, then unregister the tx cb.
+  *
+  * @return
+  *    - ESP_OK: succeed
+  *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
+  */
+esp_err_t esp_wifi_register_80211_tx_cb(esp_wifi_80211_tx_done_cb_t cb);
+
 /**
   * @brief The RX callback function of Channel State Information(CSI)  data.
   *

components/esp_wifi/include/esp_wifi_types_generic.h

@@ -1486,6 +1486,29 @@ typedef struct {
     uint8_t regulatory_type; /**< regulatory type of country */
 } wifi_regdomain_t;
 
+/**
+  * @brief Status of wifi sending data
+  */
+typedef enum {
+    WIFI_SEND_SUCCESS = 0,    /**< Sending Wi-Fi data successfully */
+    WIFI_SEND_FAIL,           /**< Sending Wi-Fi data fail */
+} wifi_tx_status_t;
+
+/**
+  * @brief Information of wifi sending data
+  */
+typedef struct {
+    uint8_t *des_addr;           /**< The address of the receive device */
+    uint8_t *src_addr;           /**< The address of the sending device */
+    wifi_interface_t ifidx;      /**< Interface of sending 80211 tx data */
+    uint8_t *data;               /**< The data for 80211 tx, start from the MAC header */
+    uint8_t data_len;            /**< The frame body length for 80211 tx, excluding the MAC header */
+    wifi_phy_rate_t rate;        /**< Data rate */
+    wifi_tx_status_t tx_status;  /**< Status of sending 80211 tx data */
+} wifi_tx_info_t;
+
+typedef wifi_tx_info_t esp_80211_tx_info_t;
+
 #ifdef __cplusplus
 }
 #endif

docs/en/migration-guides/release-5.x/5.5/index.rst

@@ -9,3 +9,4 @@ Migration from 5.4 to 5.5
     system
     peripherals
     protocols
+    wifi

docs/en/migration-guides/release-5.x/5.5/wifi.rst

@@ -0,0 +1,10 @@
+Wi-Fi
+======
+
+:link_to_translation:`zh_CN:[中文]`
+
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+The parameters for the ESP-NOW sending data callback function has changed from ``uint8_t *mac_addr`` to ``esp_now_send_info_t *tx_info``.

docs/zh_CN/migration-guides/release-5.x/5.5/index.rst

@@ -9,3 +9,4 @@
     system
     peripherals
     protocols
+    wifi

docs/zh_CN/migration-guides/release-5.x/5.5/wifi.rst

@@ -0,0 +1,11 @@
+Wi-Fi
+=====
+
+:link_to_translation:`en:[English]`
+
+
+重大更新
+~~~~~~~~
+
+ESP-NOW 的发包回调函数的参数从 ``uint8_t *mac_addr`` 变为 ``esp_now_send_info_t *tx_info``。
+

examples/wifi/espnow/main/espnow_example_main.c

@@ -61,18 +61,18 @@ static void example_wifi_init(void)
 /* ESPNOW sending or receiving callback function is called in WiFi task.
  * Users should not do lengthy operations from this task. Instead, post
  * necessary data to a queue and handle it from a lower priority task. */
-static void example_espnow_send_cb(const uint8_t *mac_addr, esp_now_send_status_t status)
+static void example_espnow_send_cb(const esp_now_send_info_t *tx_info, esp_now_send_status_t status)
 {
     example_espnow_event_t evt;
     example_espnow_event_send_cb_t *send_cb = &evt.info.send_cb;
 
-    if (mac_addr == NULL) {
+    if (tx_info == NULL) {
         ESP_LOGE(TAG, "Send cb arg error");
         return;
     }
 
     evt.id = EXAMPLE_ESPNOW_SEND_CB;
-    memcpy(send_cb->mac_addr, mac_addr, ESP_NOW_ETH_ALEN);
+    memcpy(send_cb->mac_addr, tx_info->des_addr, ESP_NOW_ETH_ALEN);
     send_cb->status = status;
     if (xQueueSend(s_example_espnow_queue, &evt, ESPNOW_MAXDELAY) != pdTRUE) {
         ESP_LOGW(TAG, "Send send queue fail");