1 /* 2 * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include <stdint.h> 10 #include <stdbool.h> 11 #include "esp_err.h" 12 #include "esp_wifi_he_types.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 19 /** 20 * @brief Set up an individual TWT agreement (NegotiationType=0) or change TWT parameters of the existing TWT agreement 21 * - TWT Wake Interval = TWT Wake Interval Mantissa * (2 ^ TWT Wake Interval Exponent), unit: us 22 * - e.g. TWT Wake Interval Mantissa = 512, TWT Wake Interval Exponent = 12, then TWT Wake Interval is 2097.152 ms 23 * Nominal Minimum Wake Duration = 255, then TWT Wake Duration is 65.28 ms 24 * 25 * @attention Support at most 8 TWT agreements, otherwise ESP_ERR_WIFI_TWT_FULL will be returned. 26 * Support sleep time up to (1 << 35) us. 27 * 28 * @param[in,out] setup_config pointer to itwt setup config structure. 29 * 30 * @return 31 * - ESP_OK: succeed 32 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 33 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 34 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 35 * - ESP_ERR_WIFI_NOT_CONNECT: The station is in disconnect status 36 * - ESP_ERR_WIFI_TWT_FULL: no available flow id 37 * - ESP_ERR_INVALID_ARG: invalid argument 38 */ 39 esp_err_t esp_wifi_sta_itwt_setup(wifi_twt_setup_config_t *setup_config); 40 41 /** 42 * @brief Tear down individual TWT agreements 43 * 44 * @param[in] flow_id The value range is [0, 7]. 45 * FLOW_ID_ALL indicates tear down all individual TWT agreements. 46 * 47 * @return 48 * - ESP_OK: succeed 49 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 50 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 51 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 52 * - ESP_ERR_WIFI_NOT_CONNECT: The station is in disconnect status 53 * - ESP_ERR_INVALID_ARG: invalid argument 54 */ 55 esp_err_t esp_wifi_sta_itwt_teardown(int flow_id); 56 57 /** 58 * @brief Send a TWT Information frame to AP for suspending/resuming established iTWT agreements. 59 * 60 * @param[in] flow_id The value range is [0, 7]. 61 * FLOW_ID_ALL indicates suspend all individual TWT agreements 62 * @param[in] suspend_time_ms If the value is 0, indicates the specified flow_id or all established agreements will be suspended until resume by users. 63 * If the value is greater than 0, indicates the specified flow_id or all established agreements will be suspended until suspend_time_ms timeout, unit: ms. 64 * 65 * @return 66 * - ESP_OK: succeed 67 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 68 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 69 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 70 * - ESP_ERR_WIFI_NOT_ASSOC: WiFi is not associated 71 * - ESP_ERR_INVALID_ARG: invalid argument 72 */ 73 esp_err_t esp_wifi_sta_itwt_suspend(int flow_id, int suspend_time_ms); 74 75 /** 76 * @brief Get flow id status 77 * 78 * @param[in] flow_id_bitmap Flow id status bitmap with 8 bit. Each bit represents that whether the corresponding flow id is setup. 79 * 1: setup, 0: not setup. 80 * 81 * @return 82 * - ESP_OK: succeed 83 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 84 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 85 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 86 * - ESP_ERR_WIFI_NOT_CONNECT: The station is in disconnect status 87 * - ESP_ERR_INVALID_ARG: invalid argument 88 */ 89 esp_err_t esp_wifi_sta_itwt_get_flow_id_status(int *flow_id_bitmap); 90 91 /** 92 * @brief Send probe to update TSF time 93 * 94 * @attention In bad network, timeout_ms is variable with the network 95 * 96 * @param[in] timeout_ms The estimated time includes sending probe request and receiving probe response, unit: ms. 97 * 98 * @return 99 * - ESP_OK: succeed 100 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 101 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 102 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 103 * - ESP_ERR_WIFI_NOT_ASSOC: WiFi is not associated 104 */ 105 esp_err_t esp_wifi_sta_itwt_send_probe_req(int timeout_ms); 106 107 /** 108 * @brief Set time offset with TBTT of target wake time field in itwt setup request frame. 109 * 110 * @param[in] offset_us Offset with TBTT of target wake time field in itwt setup request frame, range is [0, 102400], unit microseconds. 111 * 112 * @return 113 * - ESP_OK: succeed 114 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 115 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 116 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 117 * - ESP_ERR_WIFI_NOT_ASSOC: WiFi is not associated 118 * - ESP_ERR_INVALID_ARG: invalid argument 119 */ 120 esp_err_t esp_wifi_sta_itwt_set_target_wake_time_offset(int offset_us); 121 122 /** 123 * @brief Enable the reception statistics. 124 * 125 * @param[in] rx_stats indicate whether enable the reception statistics for HT, HE SU, HE ER SU and legacy 126 * @param[in] rx_mu_stats indicate whether enable the reception statistics for DL MU-MIMO and DL OFDMA 127 * 128 * @return 129 * - ESP_OK: succeed 130 * - ESP_ERR_NO_MEM: out of memory 131 */ 132 esp_err_t esp_wifi_enable_rx_statistics(bool rx_stats, bool rx_mu_stats); 133 134 /** 135 * @brief Enable the transmission statistics. 136 * 137 * @param[in] aci access category of the transmission 138 * @param[in] tx_stats indicate whether enable the transmission statistics 139 * 140 * @return 141 * - ESP_OK: succeed 142 * - ESP_ERR_NO_MEM: out of memory 143 */ 144 esp_err_t esp_wifi_enable_tx_statistics(esp_wifi_aci_t aci, bool tx_stats); 145 146 /** 147 * @brief Set WiFi TWT config 148 * 149 * @param[in] config pointer to the WiFi TWT configure structure. 150 * 151 * @return 152 * - ESP_OK: succeed 153 */ 154 esp_err_t esp_wifi_sta_twt_config(wifi_twt_config_t *config); 155 156 #ifdef __cplusplus 157 } 158 #endif 159
