alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'feat/multi_antenna_support' into 'master'

Browse Source 
feat(phy): refactor multiple antenna, support for WIFI/BT/BLE

Closes FCS-1279

See merge request espressif/esp-idf!26534
This commit is contained in:
Jiang Jiang Jian 2024-04-01 17:36:11 +08:00
commit 7347042d9a
27 changed files with 665 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
components/esp_phy/include/esp_phy.h Normal file
View File

@ -0,0 +1,112 @@
/*
* SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include <stdint.h>
#include <stdbool.h>
#include "esp_err.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @file
* PHY API
*/
/**
* @brief PHY antenna
*/
typedef enum {
ESP_PHY_ANT_ANT0, /*!< PHY antenna 0 */
ESP_PHY_ANT_ANT1, /*!< PHY antenna 1 */
ESP_PHY_ANT_MAX, /*!< Invalid PHY antenna */
} esp_phy_ant_t;
/**
* @brief PHY antenna mode
*/
typedef enum {
ESP_PHY_ANT_MODE_ANT0, /*!< Enable PHY antenna 0 only */
ESP_PHY_ANT_MODE_ANT1, /*!< Enable PHY antenna 1 only */
ESP_PHY_ANT_MODE_AUTO, /*!< Enable PHY antenna 0 and 1, automatically select an antenna, suggest not use this mode */
ESP_PHY_ANT_MODE_MAX, /*!< Invalid PHY enabled antenna */
} esp_phy_ant_mode_t;
/**
* @brief PHY GPIO configuration for antenna selection
*/
typedef struct {
uint8_t gpio_select: 1, /*!< Whether this GPIO is connected to external antenna switch */
gpio_num: 7; /*!< The GPIO number that connects to external antenna switch */
} esp_phy_ant_gpio_t;
/**
* @brief PHY GPIOs configuration for antenna selection
*/
typedef struct {
esp_phy_ant_gpio_t gpio_cfg[4]; /*!< The configurations of GPIOs that connect to external antenna switch */
} esp_phy_ant_gpio_config_t;
/**
* @brief PHY antenna configuration
*/
typedef struct {
esp_phy_ant_mode_t rx_ant_mode; /*!< PHY antenna mode for receiving */
esp_phy_ant_t rx_ant_default; /*!< Default antenna mode for receiving, it's ignored if rx_ant_mode is not ESP_PHY_ANT_MODE_AUTO */
esp_phy_ant_mode_t tx_ant_mode; /*!< PHY antenna mode for transmission, it can be set to ESP_PHY_ANT_MODE_ANT1 or ESP_PHY_ANT_MODE_ANT0 */
uint8_t enabled_ant0: 4, /*!< Index (in antenna GPIO configuration) of enabled ESP_PHY_ANT_MODE_ANT0 */
enabled_ant1: 4; /*!< Index (in antenna GPIO configuration) of enabled ESP_PHY_ANT_MODE_ANT1 */
} esp_phy_ant_config_t;
/**
* @brief Set antenna GPIO configuration
*
* @param config : Antenna GPIO configuration.
*
* @return
* - ESP_OK : success
* - other : failed
*/
esp_err_t esp_phy_set_ant_gpio(esp_phy_ant_gpio_config_t *config);
/**
* @brief Get current antenna GPIO configuration
*
* @param config : Antenna GPIO configuration.
*
* @return
* - ESP_OK : success
* - other : failed
*/
esp_err_t esp_phy_get_ant_gpio(esp_phy_ant_gpio_config_t *config);
/**
* @brief Set antenna configuration
*
* @param config : Antenna configuration.
*
* @return
* - ESP_OK : success
* - other : failed
*/
esp_err_t esp_phy_set_ant(esp_phy_ant_config_t *config);
/**
* @brief Get current antenna configuration
*
* @param config : Antenna configuration.
*
* @return
* - ESP_OK : success
* - other : failed
*/
esp_err_t esp_phy_get_ant(esp_phy_ant_config_t *config);
#ifdef __cplusplus
}
#endif

38
components/esp_phy/include/esp_private/phy.h
View File

@ -180,6 +180,44 @@ _lock_t phy_get_lock(void);
*
*/
void phy_track_pll(void);
/**
* @brief PHY antenna default configuration
*
*/
void ant_dft_cfg(bool default_ant);
/**
* @brief PHY tx antenna config
*
*/
void ant_tx_cfg(uint8_t ant0);
/**
* @brief PHY rx antenna config
*
*/
void ant_rx_cfg(bool auto_en, uint8_t ant0, uint8_t ant1);
/**
* @brief PHY antenna need update
*
*/
bool phy_ant_need_update(void);
/**
* @brief PHY antenna need update
*
*/
void phy_ant_clr_update_flag(void);
/**
* @brief PHY antenna configuration update
*
*/
void phy_ant_update(void);
#ifdef __cplusplus
}
#endif

2
components/esp_phy/lib

@ -1 +1 @@
Subproject commit 603b69583635ffcedf2a5e1d0f70da77edf82d10
Subproject commit c9c0fb3556623ca6e7f0b23fe9a234a177e2bae9

179
components/esp_phy/src/phy_common.c
View File

@ -4,11 +4,20 @@
* SPDX-License-Identifier: Apache-2.0
*/
#include "esp_log.h"
#include <stdint.h>
#include <string.h>
#include "esp_timer.h"
#include "esp_log.h"
#include "esp_private/esp_gpio_reserve.h"
#include "soc/gpio_sig_map.h"
#include "driver/gpio.h"
#include "esp_rom_gpio.h"
#include "esp_phy_init.h"
#include "esp_private/phy.h"
#include <stdint.h>
#include "esp_phy.h"
#include "esp_attr.h"
static const char* TAG = "phy_comm";
static volatile uint16_t s_phy_modem_flag = 0;
@ -23,6 +32,9 @@ static volatile int64_t s_bt_154_prev_timestamp;
#define PHY_TRACK_PLL_PERIOD_IN_US 1000000
static void phy_track_pll_internal(void);
static esp_phy_ant_gpio_config_t s_phy_ant_gpio_config = { 0 };
static esp_phy_ant_config_t s_phy_ant_config = { 0 };
#if CONFIG_IEEE802154_ENABLED || CONFIG_BT_ENABLED || CONFIG_ESP_WIFI_ENABLED
bool phy_enabled_modem_contains(esp_phy_modem_t modem)
{
@ -119,3 +131,166 @@ esp_phy_modem_t phy_get_modem_flag(void)
{
return s_phy_modem_flag;
}
static DRAM_ATTR bool s_phy_ant_need_update_flag = false;
IRAM_ATTR bool phy_ant_need_update(void)
{
return s_phy_ant_need_update_flag;
}
void phy_ant_clr_update_flag(void)
{
s_phy_ant_need_update_flag = false;
}
static void phy_ant_set_gpio_output(uint32_t io_num)
{
gpio_config_t io_conf = {};
io_conf.intr_type = GPIO_INTR_DISABLE;
io_conf.mode = GPIO_MODE_OUTPUT;
io_conf.pin_bit_mask = (1ULL << io_num);
io_conf.pull_down_en = 0;
io_conf.pull_up_en = 0;
gpio_config(&io_conf);
}
esp_err_t esp_phy_set_ant_gpio(esp_phy_ant_gpio_config_t *config)
{
if (config == NULL) {
ESP_LOGE(TAG, "Invalid configuration");
return ESP_ERR_INVALID_ARG;
}
for (int i = 0; i < 4; i++) {
if (config->gpio_cfg[i].gpio_select == 1) {
if(esp_gpio_is_reserved(config->gpio_cfg[i].gpio_num)) {
ESP_LOGE(TAG, "gpio[%d] number: %d is reserved\n", i, config->gpio_cfg[i].gpio_num);
return ESP_ERR_INVALID_ARG;
}
}
}
for (int i = 0; i < 4; i++) {
if (config->gpio_cfg[i].gpio_select == 1) {
phy_ant_set_gpio_output(config->gpio_cfg[i].gpio_num);
esp_rom_gpio_connect_out_signal(config->gpio_cfg[i].gpio_num, ANT_SEL0_IDX + i, 0, 0);
}
}
memcpy(&s_phy_ant_gpio_config, config, sizeof(esp_phy_ant_gpio_config_t));
return ESP_OK;
}
esp_err_t esp_phy_get_ant_gpio(esp_phy_ant_gpio_config_t *config)
{
if (config == NULL) {
ESP_LOGE(TAG, "Invalid configuration");
return ESP_ERR_INVALID_ARG;
}
memcpy(config, &s_phy_ant_gpio_config, sizeof(esp_phy_ant_gpio_config_t));
return ESP_OK;
}
static bool phy_ant_config_check(esp_phy_ant_config_t *config)
{
if ((config->rx_ant_mode >= ESP_PHY_ANT_MODE_MAX)
||(config->tx_ant_mode >= ESP_PHY_ANT_MODE_MAX)
||(config->rx_ant_default >= ESP_PHY_ANT_MAX)) {
ESP_LOGE(TAG, "Invalid antenna: rx=%d, tx=%d, default=%d",
config->rx_ant_mode, config->tx_ant_mode, config->rx_ant_default);
return ESP_ERR_INVALID_ARG;
}
if ((config->tx_ant_mode == ESP_PHY_ANT_MODE_AUTO) && (config->rx_ant_mode != ESP_PHY_ANT_MODE_AUTO)) {
ESP_LOGE(TAG, "If tx ant is AUTO, also need to set rx ant to AUTO");
return ESP_ERR_INVALID_ARG;
}
return ESP_OK;
}
void phy_ant_update(void)
{
uint8_t rx_ant0 = 0, rx_ant1 = 0, tx_ant0 = 0;
esp_phy_ant_config_t *config = &s_phy_ant_config;
uint8_t ant0 = config->enabled_ant0;
uint8_t ant1 = config->enabled_ant1;
bool rx_auto = false;
uint8_t def_ant = 0;
switch (config->rx_ant_mode) {
case ESP_PHY_ANT_MODE_ANT0:
rx_ant0 = ant0;
rx_ant1 = ant0;
break;
case ESP_PHY_ANT_MODE_ANT1:
rx_ant0 = ant1;
rx_ant1 = ant1;
break;
case ESP_PHY_ANT_MODE_AUTO:
rx_ant0 = ant0;
rx_ant1 = ant1;
rx_auto = true;
break;
default:
rx_ant0 = ant0;
rx_ant1 = ant0;
}
switch (config->tx_ant_mode) {
case ESP_PHY_ANT_MODE_ANT0:
tx_ant0 = ant0;
break;
case ESP_PHY_ANT_MODE_ANT1:
tx_ant0 = ant1;
break;
default:
tx_ant0 = ant0;
}
switch (config->rx_ant_default) {
case ESP_PHY_ANT_ANT0:
def_ant = 0;
break;
case ESP_PHY_ANT_ANT1:
def_ant = 1;
break;
default:
def_ant = 0;
}
ant_dft_cfg(def_ant);
ant_tx_cfg(tx_ant0);
ant_rx_cfg(rx_auto, rx_ant0, rx_ant1);
}
esp_err_t esp_phy_set_ant(esp_phy_ant_config_t *config)
{
if (!config || (phy_ant_config_check(config) != ESP_OK)) {
return ESP_ERR_INVALID_ARG;
}
memcpy(&s_phy_ant_config, config, sizeof(esp_phy_ant_config_t));
if ( phy_get_modem_flag() == 0 ) {
// Set flag and will be updated when PHY enable
s_phy_ant_need_update_flag = true;
} else {
// Update immediately when PHY is enabled
phy_ant_update();
}
return ESP_OK;
}
esp_err_t esp_phy_get_ant(esp_phy_ant_config_t *config)
{
if (config == NULL) {
ESP_LOGE(TAG, "Invalid args");
return ESP_ERR_INVALID_ARG;
}
memcpy(config, &s_phy_ant_config, sizeof(esp_phy_ant_config_t));
return ESP_OK;
}

6
components/esp_phy/src/phy_init.c
View File

@ -279,6 +279,12 @@ void esp_phy_enable(esp_phy_modem_t modem)
#if !CONFIG_IDF_TARGET_ESP32
phy_track_pll_init();
#endif
if (phy_ant_need_update()) {
phy_ant_update();
phy_ant_clr_update_flag();
}
}
phy_set_modem_flag(modem);
#if !CONFIG_IDF_TARGET_ESP32

16
components/esp_wifi/include/esp_wifi.h
View File

@ -453,7 +453,7 @@ esp_err_t esp_wifi_deauth_sta(uint16_t aid);
*
* @param config configuration settings for scanning, if set to NULL default settings will be used
* of which default values are show_hidden:false, scan_type:active, scan_time.active.min:0,
* scan_time.active.max:120 miliseconds, scan_time.passive:360 miliseconds
* scan_time.active.max:120 milliseconds, scan_time.passive:360 milliseconds
*
* @param block if block is true, this API will block the caller until the scan is done, otherwise
* it will return immediately
@ -659,7 +659,7 @@ esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw);
* @attention 2. When device is in STA mode, this API should not be called when STA is scanning or connecting to an external AP
* @attention 3. When device is in softAP mode, this API should not be called when softAP has connected to external STAs
* @attention 4. When device is in STA+softAP mode, this API should not be called when in the scenarios described above
* @attention 5. The channel info set by this API will not be stored in NVS. So If you want to remeber the channel used before wifi stop,
* @attention 5. The channel info set by this API will not be stored in NVS. So If you want to remember the channel used before wifi stop,
* you need to call this API again after wifi start, or you can call `esp_wifi_set_config()` to store the channel info in NVS.
*
* @param primary for HT20, primary is the channel number, for HT40, primary is the primary channel
@ -1018,7 +1018,7 @@ esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx);
esp_err_t esp_wifi_set_max_tx_power(int8_t power);
/**
* @brief Get maximum transmiting power after WiFi start
* @brief Get maximum transmitting power after WiFi start
*
* @param power Maximum WiFi transmitting power, unit is 0.25dBm.
*
@ -1149,7 +1149,7 @@ esp_err_t esp_wifi_set_csi(bool en);
* - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
* - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc
*/
esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config);
esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config) __attribute__((deprecated("Please use esp_phy_set_ant_gpio instead")));
/**
* @brief Get current antenna GPIO configuration
@ -1161,7 +1161,7 @@ esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config);
* - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
* - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL
*/
esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config);
esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config) __attribute__((deprecated("Please use esp_phy_get_ant_gpio instead")));
/**
@ -1174,7 +1174,7 @@ esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config);
* - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
* - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid GPIO number
*/
esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config);
esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config) __attribute__((deprecated("Please use esp_phy_set_ant instead")));
/**
* @brief Get current antenna configuration
@ -1186,7 +1186,7 @@ esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config);
* - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
* - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL
*/
esp_err_t esp_wifi_get_ant(wifi_ant_config_t *config);
esp_err_t esp_wifi_get_ant(wifi_ant_config_t *config) __attribute__((deprecated("Please use esp_phy_get_ant instead")));
/**
* @brief Get the TSF time
@ -1311,7 +1311,7 @@ esp_err_t esp_wifi_ftm_resp_set_offset(int16_t offset_cm);
* valid FTM measurements in the buffer. Total number of entries can be found in the event
* WIFI_EVENT_FTM_REPORT as ftm_report_num_entries
* @attention 2. The internal FTM report is freed upon use of this API which means the API can only be used
* once afer every FTM session initiated
* once after every FTM session initiated
* @attention 3. Passing the buffer as NULL merely frees the FTM report
*
* @param report Pointer to the buffer for receiving the FTM report

2
components/esp_wifi/lib

@ -1 +1 @@
Subproject commit 1fbf7cd43098b06be5afe9226eb483c6998d46f1
Subproject commit 5ae2e01957e3d1e38f5e423a25bd241d3a6ef339

58
components/soc/esp32c5/beta3/include/soc/gpio_sig_map.h
View File

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@ -40,7 +40,18 @@
#define I2SO_SD1_OUT_IDX 18
#define USB_JTAG_TDO_BRIDGE_IDX 19
#define USB_JTAG_TRST_IDX 19
#define CPU_TESTBUS0_IDX 20
#define USB_OTG_32K_IN_IDX 21
#define CPU_TESTBUS1_IDX 21
#define USB_OTG_25M_IN_IDX 22
#define CPU_TESTBUS2_IDX 22
#define USB_OTG_PRB_IN_IDX 23
#define CPU_TESTBUS3_IDX 23
#define USB_OTG_SNS_IN_IDX 24
#define CPU_TESTBUS4_IDX 24
#define CPU_TESTBUS5_IDX 25
#define CPU_TESTBUS6_IDX 26
#define CPU_TESTBUS7_IDX 27
#define CPU_GPIO_IN0_IDX 28
#define CPU_GPIO_OUT0_IDX 28
#define CPU_GPIO_IN1_IDX 29
@ -57,6 +68,18 @@
#define CPU_GPIO_OUT6_IDX 34
#define CPU_GPIO_IN7_IDX 35
#define CPU_GPIO_OUT7_IDX 35
#define USB_JTAG_TCK_IDX 36
#define USB_JTAG_TMS_IDX 37
#define USB_JTAG_TDI_IDX 38
#define USB_JTAG_TDO_IDX 39
#define USB_EXTPHY_VP_IDX 40
#define USB_EXTPHY_OEN_IDX 40
#define USB_EXTPHY_VM_IDX 41
#define USB_EXTPHY_SPEED_IDX 41
#define USB_EXTPHY_RCV_IDX 42
#define USB_EXTPHY_VPO_IDX 42
#define USB_EXTPHY_VMO_IDX 43
#define USB_EXTPHY_SUSPND_IDX 44
#define I2CEXT0_SCL_IN_IDX 45
#define I2CEXT0_SCL_OUT_IDX 45
#define I2CEXT0_SDA_IN_IDX 46
@ -77,6 +100,13 @@
#define PARL_TX_DATA6_IDX 53
#define PARL_RX_DATA7_IDX 54
#define PARL_TX_DATA7_IDX 54
#define ANT_SEL4_IDX 55
#define ANT_SEL5_IDX 56
#define ANT_SEL6_IDX 57
#define ANT_SEL7_IDX 58
#define ANT_SEL8_IDX 59
#define ANT_SEL9_IDX 60
#define ANT_SEL10_IDX 61
#define SDIO_TOHOST_INT_OUT_IDX 62
#define FSPICLK_IN_IDX 63
#define FSPICLK_OUT_MUX_IDX 63
@ -108,6 +138,10 @@
#define TWAI1_BUS_OFF_ON_IDX 78
#define TWAI1_CLKOUT_IDX 79
#define TWAI1_STANDBY_IDX 80
#define EXTERN_PRIORITY_I_IDX 81
#define EXTERN_PRIORITY_O_IDX 81
#define EXTERN_ACTIVE_I_IDX 82
#define EXTERN_ACTIVE_O_IDX 82
#define PCNT_RST_IN0_IDX 83
#define GPIO_SD0_OUT_IDX 83
#define PCNT_RST_IN1_IDX 84
@ -129,8 +163,12 @@
#define PWM0_F2_IN_IDX 92
#define PWM0_OUT2B_IDX 92
#define PWM0_CAP0_IN_IDX 93
#define ANT_SEL0_IDX 93
#define PWM0_CAP1_IN_IDX 94
#define ANT_SEL1_IDX 94
#define PWM0_CAP2_IN_IDX 95
#define ANT_SEL2_IDX 95
#define ANT_SEL3_IDX 96
#define SIG_IN_FUNC_97_IDX 97
#define SIG_IN_FUNC97_IDX 97
#define SIG_IN_FUNC_98_IDX 98
@ -150,19 +188,35 @@
#define PCNT_SIG_CH0_IN1_IDX 105
#define FSPICS5_OUT_IDX 105
#define PCNT_SIG_CH1_IN1_IDX 106
#define USB_OTG_CHRG_OUT_IDX 106
#define PCNT_CTRL_CH0_IN1_IDX 107
#define USB_OTG_DISCHRG_OUT_IDX 107
#define PCNT_CTRL_CH1_IN1_IDX 108
#define USB_OTG_PRB_EN_OUT_IDX 108
#define PCNT_SIG_CH0_IN2_IDX 109
#define USB_OTG_SNS_EN_OUT_IDX 109
#define PCNT_SIG_CH1_IN2_IDX 110
#define ANT_SEL11_IDX 110
#define PCNT_CTRL_CH0_IN2_IDX 111
#define ANT_SEL12_IDX 111
#define PCNT_CTRL_CH1_IN2_IDX 112
#define ANT_SEL13_IDX 112
#define PCNT_SIG_CH0_IN3_IDX 113
#define ANT_SEL14_IDX 113
#define PCNT_SIG_CH1_IN3_IDX 114
#define SPICLK_OUT_MUX_IDX 114
#define PCNT_CTRL_CH0_IN3_IDX 115
#define SPICS0_OUT_IDX 115
#define PCNT_CTRL_CH1_IN3_IDX 116
#define SPICS1_OUT_IDX 116
#define GPIO_EVENT_MATRIX_IN0_IDX 117
#define GPIO_TASK_MATRIX_OUT0_IDX 117
#define GPIO_EVENT_MATRIX_IN1_IDX 118
#define GPIO_TASK_MATRIX_OUT1_IDX 118
#define GPIO_EVENT_MATRIX_IN2_IDX 119
#define GPIO_TASK_MATRIX_OUT2_IDX 119
#define GPIO_EVENT_MATRIX_IN3_IDX 120
#define GPIO_TASK_MATRIX_OUT3_IDX 120
#define SPIQ_IN_IDX 121
#define SPIQ_OUT_IDX 121
#define SPID_IN_IDX 122
@ -174,5 +228,5 @@
#define CLK_OUT_OUT1_IDX 125
#define CLK_OUT_OUT2_IDX 126
#define CLK_OUT_OUT3_IDX 127
// version date 2301100
#define SIG_GPIO_OUT_IDX 128
#define GPIO_MAP_DATE_IDX 0x2301100

21
docs/conf_common.py
View File

@ -175,7 +175,8 @@ ESP32_DOCS = ['api-reference/system/himem.rst',
'api-reference/peripherals/dac.rst',
'api-reference/peripherals/sd_pullup_requirements.rst',
'hw-reference/esp32/**',
'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS + QEMU_DOCS
'api-guides/RF_calibration.rst',
'api-guides/phy.rst'] + FTDI_JTAG_DOCS + QEMU_DOCS
ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-guides/usb-console.rst',
@ -183,26 +184,32 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-reference/peripherals/temp_sensor.rst',
'api-reference/system/async_memcpy.rst',
'api-reference/peripherals/touch_element.rst',
'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS
'api-guides/RF_calibration.rst',
'api-guides/phy.rst'] + FTDI_JTAG_DOCS + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
'api-reference/system/ipc.rst',
'api-guides/flash_psram_config.rst',
'api-reference/peripherals/sd_pullup_requirements.rst',
'api-guides/RF_calibration.rst'] + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS
'api-guides/RF_calibration.rst',
'api-guides/phy.rst'] + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS
# No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
ESP32C3_DOCS = ['hw-reference/esp32c3/**',
'api-guides/RF_calibration.rst'] + QEMU_DOCS
'api-guides/RF_calibration.rst',
'api-guides/phy.rst'] + QEMU_DOCS
ESP32C2_DOCS = ['api-guides/RF_calibration.rst']
ESP32C2_DOCS = ['api-guides/RF_calibration.rst',
'api-guides/phy.rst']
ESP32C5_DOCS = ['']
ESP32C6_DOCS = ['api-guides/RF_calibration.rst',
'api-reference/peripherals/sd_pullup_requirements.rst']
'api-reference/peripherals/sd_pullup_requirements.rst',
'api-guides/phy.rst']
ESP32H2_DOCS = ['api-guides/RF_calibration.rst']
ESP32H2_DOCS = ['api-guides/RF_calibration.rst',
'api-guides/phy.rst']
ESP32P4_DOCS = ['api-reference/system/ipc.rst',
'api-reference/peripherals/sd_pullup_requirements.rst']

1
docs/en/api-guides/index.rst
View File

@ -44,3 +44,4 @@ API Guides
:SOC_WIFI_SUPPORTED: wifi
:SOC_WIFI_SUPPORTED: wifi-security
low-power-mode
:SOC_WIFI_SUPPORTED or SOC_BT_SUPPORTED or SOC_IEEE802154_SUPPORTED: phy

96
docs/en/api-guides/phy.rst Normal file
View File

@ -0,0 +1,96 @@
PHY
==================
:link_to_translation:`zh_CN:[中文]`
Multiple Antennas
--------------------------
Principles and Components of Multiple Antennas
+++++++++++++++++++++++++++++++++++++++++++++++
Multi-antenna functionality primarily involves routing signals from internal antenna modules to specific IO pins, controlling external antenna switches through IO pins to select designated antennas, supporting up to 16 antennas.
The components of multiple antennas can be depicted as following picture::
___________________________________________________________________________
____|____ _________ |
|PHY |--antenna_select[0] --> | | |
___|Antenna 0|--antenna_select[1] --> | | |
/ |Module |--antenna_select[2] --> | | ____|____
/ |_________|--antenna_select[3] --> | IO MUX |--GPIO[x0] --> ant_sel_in[0]--| | --- antenna 0
RX/TX ___/ | | And |--GPIO[x1] --> ant_sel_in[1]--| Antenna | --- antenna 1
\ ____|____ | GPIO |--GPIO[x2] --> ant_sel_in[2]--| Switch | ... ...
\ |PHY |--antenna_select[0] --> | Matrix |--GPIO[x3] --> ant_sel_in[3]--|_________| --- antenna 15
\___|Antenna 1|--antenna_select[1] --> | |
|Module |--antenna_select[2] --> | |
|_________|--antenna_select[3] --> |_________|
{IDF_TARGET_NAME} Multiple antennas primarily consists of three parts: the PHY Antenna Module inside the chip, IO MUX and GPIO Matrix, and external antenna switches.
1. PHY Antenna Module:
- Both antenna modules support operation in transmit (TX) or receive (RX) mode, and can be configured via software to select a particular module for transmission or reception.
- Each antenna module supports outputting up to 4 antenna selection signals antenna_select[3:0], which can be configured by software and mapped to any IO pin individually.
- When an antenna module is in operation, the logic level of the IO pin corresponds to the configured signal value.
2. IO MUX and GPIO Matrix:
- Routes the internal 4-way antenna signals to specific IO pins.
3. External Antenna Switches:
- Typically multi-way selectors, they choose the working antenna based on the logic level of the ant_sel_in[x] pin. For example, ant_sel_in[3:0] as "0b1011" selects antenna 11.
Steps for Multi-Antenna Usage
++++++++++++++++++++++++++++++
1. Determine the IO pins used for controlling antenna switching based on hardware circuit design and external antenna switches.
2. Configure antenna selection signals to output to specified IO pins.
- API :cpp:func:`esp_phy_set_ant_gpio()` is used to configure antenna_selects[3:0] signals to connect with GPIO[x3:x0]. If GPIO[x0] is connected to antenna_select[0], gpio_config->gpio_cfg[x0].gpio_select should be set to 1, and the value of gpio_config->gpio_cfg[x0].gpio_num should be GPIO[x0].
3. Configure internal antenna operation mode and output signals.
- API :cpp:func:`esp_phy_set_ant()` is used to configure the use of internal antenna module 0 or 1 for transmission or reception, and to configure the output signal values when antenna module 0 or 1 is in operation.
- ESP_PHY_ANT_MODE_AUTO mode is currently not recommended for use.
Multi-Antenna Configuration Reference Example
+++++++++++++++++++++++++++++++++++++++++++++++
Typically, the following steps can be performed to configure multi-antenna:
- Configure antenna_selects to connect with which GPIOs. For example, if four antennas are supported and GPIO20/GPIO21 are connected to antenna_select[0]/antenna_select[1], the configuration is as follows:
.. code-block:: c
esp_phy_ant_gpio_config_t ant_gpio_config = {
.gpio_cfg[0] = { .gpio_select = 1, .gpio_num = 20 },
.gpio_cfg[1] = { .gpio_select = 1, .gpio_num = 21 }
};
- Configure which antennas are enabled and how enabled antennas are used for receiving/sending data. For example, if antennas 1 and 3 are enabled, data reception needs to automatically select the better antenna, with antenna 1 set as the default antenna, and data transmission always selecting antenna 3. The configuration is as follows:
.. code-block:: c
esp_phy_ant_config_t config = {
.rx_ant_mode = ESP_PHY_ANT_MODE_AUTO,
.rx_ant_default = ESP_PHY_ANT_ANT0,
.tx_ant_mode = ESP_PHY_ANT_MODE_ANT1,
.enabled_ant0 = 1,
.enabled_ant1 = 3
};
Notes
++++++++++++++++++++++++++
1. Different antenna switches may have invalid input values for `ant_sel_in[3:0]`, meaning the number of antennas supported by {IDF_TARGET_NAME} via external antenna switches may be less than 16. For example, ESP32-WROOM-DA uses RTC6603SP as the antenna switch, supporting only 2 antennas. The two antenna selection input pins are active high and are connected to two GPIOs. '0b01' indicates antenna 0 is selected, '0b10' indicates antenna 1 is selected. Input values '0b00' and '0b11' are invalid.
2. Despite supporting up to 16 antennas, only a maximum of two antennas can be enabled simultaneously for sending and receiving data.
3. The use of ESP_PHY_ANT_MODE_AUTO mode is currently not recommended, primarily due to the following limitations:
- For the antenna selection algorithm based on ESP_PHY_ANT_MODE_AUTO type for sending data, the antenna for sending data can only be set to ESP_PHY_ANT_MODE_AUTO when the antenna mode for receiving data is ESP_PHY_ANT_MODE_AUTO.
- When the receiving or sending antenna mode is configured as ESP_PHY_ANT_MODE_AUTO, frequent antenna switching may occur if RF signal degradation is detected. Unstable RF signals can lead to frequent antenna switching, resulting in the overall RF performance not meeting expectations.
Recommended Scenarios for Using Multiple Antennas
++++++++++++++++++++++++++++++++++++++++++++++++++
1. Applications can either select specified antennas or implement their own antenna selection algorithms based on collected information, such as selecting antenna modes according to application-specific criteria. Refer to the IDF example :idf_file:`examples/phy/antenna/README.md` for designing antenna selection algorithms.
2. Configure antenna modes for both receiving and sending data as ESP_PHY_ANT_MODE_ANT0 or ESP_PHY_ANT_MODE_ANT1.

65
docs/en/api-guides/wifi.rst
View File

@ -2175,69 +2175,8 @@ The Wi-Fi sniffer mode can be enabled in the Wi-Fi mode of :cpp:enumerator:`WIFI
Another noteworthy issue about the sniffer is the callback :cpp:type:`wifi_promiscuous_cb_t`. The callback will be called directly in the Wi-Fi driver task, so if the application has a lot of work to do for each filtered packet, the recommendation is to post an event to the application task in the callback and defer the real work to the application task.
Wi-Fi Multiple Antennas
--------------------------
The Wi-Fi multiple antennas selecting can be depicted as following picture::
__________
|Enabled |
___|Antenna 0 |\\ _________
|__________| \\ GPIO[0] <----> antenna_select[0] ---| | --- antenna 0
RX/TX ___ \\____\ GPIO[1] <----> antenna_select[1] ---| Antenna | --- antenna 1
\ __________ // / GPIO[2] <----> antenna_select[2] ---| Switch | ... ...
\ ___|Enabled | // GPIO[3] <----> antenna_select[3] ---|_________| --- antenna 15
\ |Antenna 1 |//
|__________|
{IDF_TARGET_NAME} supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. For example, the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', which means the antenna 0 is selected by default.
Up to four GPIOs are connected to the four active high antenna_select pins. {IDF_TARGET_NAME} can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
For the specific implementation of the antenna switch, there may be illegal values in `antenna_select[0:3]`. It means that {IDF_TARGET_NAME} may support less than sixteen antennas through the switch. For example, ESP32-WROOM-DA which uses RTC6603SP as the antenna switch, supports two antennas. Two GPIOs are connected to two active high antenna selection inputs. The value '0b01' means the antenna 0 is selected, the value '0b10' means the antenna 1 is selected. Values '0b00' and '0b11' are illegal.
Although up to sixteen antennas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled.
The enabled antennas selecting algorithm is also configured by :cpp:func:`esp_wifi_set_ant()`. The RX/TX antenna mode can be :cpp:enumerator:`WIFI_ANT_MODE_ANT0`, :cpp:enumerator:`WIFI_ANT_MODE_ANT1`, or :cpp:enumerator:`WIFI_ANT_MODE_AUTO`. If the antenna mode is :cpp:enumerator:`WIFI_ANT_MODE_ANT0`, the enabled antenna 0 is selected for RX/TX data. If the antenna mode is :cpp:enumerator:`WIFI_ANT_MODE_ANT1`, the enabled antenna 1 is selected for RX/TX data. Otherwise, Wi-Fi automatically selects the enabled antenna that has better signal.
If the RX antenna mode is :cpp:enumerator:`WIFI_ANT_MODE_AUTO`, the default antenna mode also needs to be set, because the RX antenna switching only happens when some conditions are met. For example, the RX antenna starts to switch if the RSSI is lower than -65 dBm or another antenna has better signal. RX uses the default antenna if the conditions are not met. If the default antenna mode is :cpp:enumerator:`WIFI_ANT_MODE_ANT1`, the enabled antenna 1 is used as the default RX antenna, otherwise the enabled antenna 0 is used.
Some limitations need to be considered:
- The TX antenna can be set to :cpp:enumerator:`WIFI_ANT_MODE_AUTO` only if the RX antenna mode is :cpp:enumerator:`WIFI_ANT_MODE_AUTO`, because TX antenna selecting algorithm is based on RX antenna in :cpp:enumerator:`WIFI_ANT_MODE_AUTO` type.
- When the TX antenna mode or RX antenna mode is configured to :cpp:enumerator:`WIFI_ANT_MODE_AUTO` the switching mode will easily trigger the switching phase, as long as there is deterioration of the RF signal. So in situations where the RF signal is not stable, the antenna switching will occur frequently, resulting in an RF performance that may not meet expectations.
- Currently, Bluetooth® does not support the multiple antennas feature, so please do not use multiple antennas related APIs.
Following is the recommended scenarios to use the multiple antennas:
- The applications can always choose to select a specified antenna or implement their own antenna selecting algorithm, e.g., selecting the antenna mode based on the information collected by the application. Refer to ESP-IDF example :idf_file:`examples/wifi/antenna/README.md` for the antenna selecting algorithm design.
- Both RX/TX antenna modes are configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1.
Wi-Fi Multiple Antennas Configuration
+++++++++++++++++++++++++++++++++++++
Generally, following steps can be taken to configure the multiple antennas:
- Configure which GPIOs are connected to the antenna_selects. For example, if four antennas are supported and GPIO20/GPIO21 are connected to antenna_select[0]/antenna_select[1], the configurations look like:
.. code-block:: c
wifi_ant_gpio_config_t ant_gpio_config = {
.gpio_cfg[0] = { .gpio_select = 1, .gpio_num = 20 },
.gpio_cfg[1] = { .gpio_select = 1, .gpio_num = 21 }
};
- Configure which antennas are enabled and how RX/TX use the enabled antennas. For example, if antenna1 and antenna3 are enabled, the RX needs to select the better antenna automatically and uses antenna1 as its default antenna, the TX always selects the antenna3. The configuration looks like:
.. code-block:: c
wifi_ant_config_t config = {
.rx_ant_mode = WIFI_ANT_MODE_AUTO,
.rx_ant_default = WIFI_ANT_ANT0,
.tx_ant_mode = WIFI_ANT_MODE_ANT1,
.enabled_ant0 = 1,
.enabled_ant1 = 3
};
---------------------------
Please refer to the :doc:`PHY <../api-guides/phy>`
.. only:: SOC_WIFI_CSI_SUPPORT

5
docs/en/migration-guides/release-5.x/5.2/wifi.rst
View File

@ -21,3 +21,8 @@ For the event WIFI_EVENT_STA_DISCONNECTED, the original reason code WIFI_REASON_
- REASON_NO_AP_FOUND_W_COMPATIBLE_SECURITY
For details, please refer to :ref:`esp_wifi_reason_code`.
WiFi Multiple Antennas
----------------------
WiFi multiple antennas api will be deprecated. Please use newer APIs from `esp_phy.h`.

1
docs/zh_CN/api-guides/index.rst
View File

@ -44,3 +44,4 @@ API 指南
:SOC_WIFI_SUPPORTED: wifi
:SOC_WIFI_SUPPORTED: wifi-security
low-power-mode
:SOC_WIFI_SUPPORTED or SOC_BT_SUPPORTED or SOC_IEEE802154_SUPPORTED: phy

97
docs/zh_CN/api-guides/phy.rst Normal file
View File

@ -0,0 +1,97 @@
PHY
==================
:link_to_translation:`en:[English]`
多根天线
-------------------
多根天线功能原理和组成
++++++++++++++++++++++++++++
多根天线功能主要通过将内部天线模块工作信号输出到具体 IO 引脚上，通过 IO 引脚控制外部天线切换器选择指定天线，最多支持 16 根天线。
下图描述多根天线功能组成::
___________________________________________________________________________
____|____ _________ |
|PHY |--antenna_select[0] --> | | |
___|Antenna 0|--antenna_select[1] --> | | |
/ |Module |--antenna_select[2] --> | | ____|____
/ |_________|--antenna_select[3] --> | IO MUX |--GPIO[x0] --> ant_sel_in[0]--| | --- antenna 0
RX/TX ___/ | | And |--GPIO[x1] --> ant_sel_in[1]--| Antenna | --- antenna 1
\ ____|____ | GPIO |--GPIO[x2] --> ant_sel_in[2]--| Switch | ... ...
\ |PHY |--antenna_select[0] --> | Matrix |--GPIO[x3] --> ant_sel_in[3]--|_________| --- antenna 15
\___|Antenna 1|--antenna_select[1] --> | |
|Module |--antenna_select[2] --> | |
|_________|--antenna_select[3] --> |_________|
{IDF_TARGET_NAME} 多根天线功能主要包含 3 个部分：芯片内部的 PHY 天线模块、IO MUX 和 GPIO Matrix、以及外部的天线切换器。
1.芯片内部的天线选择模块 PHY Antenna Module：
- 两个天线模块均支持工作于发送 (TX) 或接收 (RX) 模式，可以通过软件配置发送和接收选用某个模块。
- 每个天线模块最多支持输出 4 个天线选择信号 antenna_select[3:0]，该信号值可由软件配置并且可以一一映射到任意 IO 引脚。
- 当某个天线模块处于工作状态时，IO 引脚的高低电平值为软件配置的信号值。
2.IO MUX 和 GPIO Matrix：
- 将内部 4 路天线信号输出到具体的 IO 引脚上。
3.外部的天线切换器：
- 一般为多路选择器，通过 ant_sel_in[x] 引脚的电平，选择工作的天线，例如 ant_sel_in[3:0] 为 "0b1011"，表示选中天线 11。
多根天线使用步骤
+++++++++++++++++++++++++++
1.根据硬件电路设计及外部天线切换器确定用于控制天线切换的 IO 引脚。
2.配置天线选择信号输出到指定 IO 引脚
- API :cpp:func:`esp_phy_set_ant_gpio()` 用于配置 antenna_selects[3:0] 信号连接 GPIO[x3:x0]。如果 GPIO[x0] 连接到 antenna_select[0]，gpio_config->gpio_cfg[x0].gpio_select 应设置为 1，且 gpio_config->gpio_cfg[x0].gpio_num 的值为 GPIO[x0]。
3.配置内部天线工作模式及输出信号
- API :cpp:func:`esp_phy_set_ant()` 用于配置发送或接收时使用内部天线模块 0 或 1，并配置当天线模块 0 或 1 工作时的输出信号值。
- 对于 ESP_PHY_ANT_MODE_AUTO 模式目前不推荐使用。
多根天线配置参考例子
++++++++++++++++++++++++++++
通常，可以执行以下步骤来配置多根天线：
- 配置 antenna_selects 连接哪些 GPIOs，例如，如果支持四根天线，且 GPIO20/GPIO21 连接到 antenna_select[0]/antenna_select[1]，配置如下所示:
.. code-block:: c
esp_phy_ant_gpio_config_t ant_gpio_config = {
.gpio_cfg[0] = { .gpio_select = 1, .gpio_num = 20 },
.gpio_cfg[1] = { .gpio_select = 1, .gpio_num = 21 }
};
- 配置使能哪些天线、以及接收/发送数据如何使用使能的天线，例如，如果使能了天线 1 和天线 3，接收数据需要自动选择较好的天线，并将天线 1 作为默认天线，发送数据始终选择天线 3。配置如下所示:
.. code-block:: c
esp_phy_ant_config_t config = {
.rx_ant_mode = ESP_PHY_ANT_MODE_AUTO,
.rx_ant_default = ESP_PHY_ANT_ANT0,
.tx_ant_mode = ESP_PHY_ANT_MODE_ANT1,
.enabled_ant0 = 1,
.enabled_ant1 = 3
};
注意事项
++++++++++++++++++++++++++
1.不同天线切换器，`ant_sel_in[3:0]` 的输入值中可能存在非法值，即 {IDF_TARGET_NAME} 通过外部天线开关支持的天线数可能小于 16 根。例如，ESP32-WROOM-DA 使用 RTC6603SP 作为天线切换器，仅支持 2 根天线。两个天线选择输入管脚为高电平有效，连接到两个 GPIO。'0b01' 表示选中天线 0，'0b10' 表示选中天线 1。输入值 '0b00' 和 '0b11' 为非法值。
2.尽管最多支持 16 根天线，发送和接收数据时，最多仅能同时使能两根天线。
3.对于 ESP_PHY_ANT_MODE_AUTO 模式目前不推荐使用，主要有以下限制情况需要考虑：
- 因为发送数据天线基于 ESP_PHY_ANT_MODE_AUTO 类型的接收数据天线选择算法，只有接收数据的天线模式为 ESP_PHY_ANT_MODE_AUTO 时，发送数据天线才能设置为 ESP_PHY_ANT_MODE_AUTO。
- 接收或者发送天线模式配置为 ESP_PHY_ANT_MODE_AUTO 时，只要存在 RF 信号的恶化，很容易触发天线切换。如果射频信号不稳定，天线会频繁切换，使得总的射频性能无法达到预期效果。
推荐在以下场景中使用多根天线
++++++++++++++++++++++++++++
1.应用程序可以始终选择指定的天线，也可以执行自身天线选择算法，如根据应用程序收集的信息来选择天线模式等。请参考 IDF 示例 :idf_file:`examples/phy/antenna/README.md` 来设计天线选择算法。
2.接收/发送数据的天线模式均配置为 ESP_PHY_ANT_MODE_ANT0 或 ESP_PHY_ANT_MODE_ANT1。

63
docs/zh_CN/api-guides/wifi.rst
View File

@ -2144,68 +2144,7 @@ Wi-Fi Sniffer 模式可以通过 :cpp:func:`esp_wifi_set_promiscuous()` 使能
Wi-Fi 多根天线
--------------------------
下图描述 Wi-Fi 多根天线的选择过程::
__________
|Enabled |
___|Antenna 0 |\\ _________
|__________| \\ GPIO[0] <----> antenna_select[0] ---| | --- antenna 0
RX/TX ___ \\____\ GPIO[1] <----> antenna_select[1] ---| Antenna | --- antenna 1
\ __________ // / GPIO[2] <----> antenna_select[2] ---| Switch | ... ...
\ ___|Enabled | // GPIO[3] <----> antenna_select[3] ---|_________| --- antenna 15
\ |Antenna 1 |//
|__________|
{IDF_TARGET_NAME} 通过外部天线开关，最多支持 16 根天线。天线开关最多可由四个地址管脚控制 - antenna_select[0:3]。向 antenna_select[0:3] 输入不同的值，以选择不同的天线。例如，输入值 '0b1011' 表示选中天线 11。antenna_select[3:0] 的默认值为 "0b0000"，表示默认选择了天线 0。
四个高电平有效 antenna_select 管脚有多达四个 GPIO 连接。{IDF_TARGET_NAME} 可以通过控制 GPIO[0:3] 选择天线。API :cpp:func:`esp_wifi_set_ant_gpio()` 用于配置 antenna_selects 连接哪些 GPIO。如果 GPIO[x] 连接到 antenna_select[x]，gpio_config->gpio_cfg[x].gpio_select 应设置为 1，且要提供 gpio_config->gpio_cfg[x].gpio_num 的值。
天线开关的具体实现不同，`antenna_select[0:3]` 的输入值中可能存在非法值，即 {IDF_TARGET_NAME} 通过外部天线开关支持的天线数可能小于 16 根。例如，ESP32-WROOM-DA 使用 RTC6603SP 作为天线开关，仅支持 2 根天线。两个天线选择输入管脚为高电平有效，连接到两个 GPIO。'0b01' 表示选中天线 0，'0b10' 表示选中天线 1。输入值 '0b00' 和 '0b11' 为非法值。
尽管最多支持 16 根天线，发送和接收数据时，最多仅能同时使能两根天线。API :cpp:func:`esp_wifi_set_ant()` 用于配置使能哪些天线。
使能天线后，选择算法的过程同样可由 :cpp:func:`esp_wifi_set_ant()` 配置。接收/发送数据源的天线模式可以是 WIFI_ANT_MODE_ANT0、WIFI_ANT_MODE_ANT1 或 WIFI_ANT_MODE_AUTO。如果天线模式为 WIFI_ANT_MODE_ANT0，使能的天线 0 用于接收/发送数据。如果天线模式为 WIFI_ANT_MODE_ANT1，使能天线 1 用于接收/发送数据。否则，Wi-Fi 会自动选择使能天线中信号较好的天线。
如果接收数据的天线模式为 WIFI_ANT_MODE_AUTO，还需要设置默认天线模式。只有在满足某些条件时，接收数据天线才会切换，例如，如果 RSSI 低于 -65 dBm，或另一根天线信号更好。如果条件不满足，接收数据使用默认天线。如果默认天线模式为 WIFI_ANT_MODE_ANT1，则使能的天线 1 是默认接收数据天线，否则是使能的天线 0。
有一些限制情况需要考虑：
- 因为发送数据天线基于 WIFI_ANT_MODE_AUTO 类型的接收数据天线选择算法，只有接收数据的天线模式为 WIFI_ANT_MODE_AUTO 时，发送数据天线才能设置为 WIFI_ANT_MODE_AUTO。
- 接收或者发送天线模式配置为 WIFI_ANT_MODE_AUTO 时，只要存在 RF 信号的恶化，很容易触发天线切换。如果射频信号不稳定，天线会频繁切换，使得总的射频性能无法达到预期效果。
- 目前，Bluetooth® 不支持多根天线功能，请不要使用与多根天线有关的 API。
推荐在以下场景中使用多根天线：
- 应用程序可以始终选择指定的天线，也可以执行自身天线选择算法，如根据应用程序收集的信息来选择天线模式等。请参考 IDF 示例 :idf_file:`examples/wifi/antenna/README.md` 来设计天线选择算法。
- 接收/发送数据的天线模式均配置为 WIFI_ANT_MODE_ANT0 或 WIFI_ANT_MODE_ANT1。
Wi-Fi 多根天线配置
+++++++++++++++++++++++++++++++++++++
通常，可以执行以下步骤来配置多根天线：
- 配置 antenna_selects 连接哪些 GPIOs，例如，如果支持四根天线，且 GPIO20/GPIO21 连接到 antenna_select[0]/antenna_select[1]，配置如下所示:
.. code-block:: c
wifi_ant_gpio_config_t ant_gpio_config = {
.gpio_cfg[0] = { .gpio_select = 1, .gpio_num = 20 },
.gpio_cfg[1] = { .gpio_select = 1, .gpio_num = 21 }
};
- 配置使能哪些天线、以及接收/发送数据如何使用使能的天线，例如，如果使能了天线 1 和天线 3，接收数据需要自动选择较好的天线，并将天线 1 作为默认天线，发送数据始终选择天线 3。配置如下所示:
.. code-block:: c
wifi_ant_config_t config = {
.rx_ant_mode = WIFI_ANT_MODE_AUTO,
.rx_ant_default = WIFI_ANT_ANT0,
.tx_ant_mode = WIFI_ANT_MODE_ANT1,
.enabled_ant0 = 1,
.enabled_ant1 = 3
};
具体请参考 :doc:`PHY <../api-guides/phy>`。
.. only:: SOC_WIFI_CSI_SUPPORT

4
docs/zh_CN/migration-guides/release-5.x/5.2/wifi.rst
View File

@ -8,3 +8,7 @@ Wi-Fi 企业级安全
------------------------
在 `esp_wpa2.h` 中定义的 API 已弃用，请使用来自 `esp_eap_client.h` 的新 API。
Wi-Fi 多天线
------------------------
Wi-Fi 多天线相关的 API 将要被弃用，请使用来自 `esp_phy.h` 的新 API。

4
examples/phy/.build-test-rules.yml
View File

@ -1,5 +1,9 @@
# Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
examples/phy/antenna:
disable:
- if: IDF_TARGET in ["esp32p4", "esp32h2"]
reason: not supported
examples/phy/cert_test:
enable:
- if: IDF_TARGET in ["esp32c3", "esp32s3"]

0
examples/wifi/antenna/CMakeLists.txt → examples/phy/antenna/CMakeLists.txt
View File

4
examples/wifi/antenna/README.md → examples/phy/antenna/README.md
View File

@ -49,7 +49,7 @@ I (599) system_api: Base MAC address is not set, read default base MAC address f
I (599) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
I (629) wifi: wifi firmware version: 2d94f02
I (629) wifi: config NVS flash: enabled
I (629) wifi: config nano formating: disabled
I (629) wifi: config nano formatting: disabled
I (629) wifi: Init dynamic tx buffer num: 32
I (629) wifi: Init data frame dynamic rx buffer num: 32
I (639) wifi: Init management frame dynamic rx buffer num: 32
@ -94,7 +94,7 @@ I (599) system_api: Base MAC address is not set, read default base MAC address f
I (599) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
I (629) wifi: wifi firmware version: 2d94f02
I (629) wifi: config NVS flash: enabled
I (629) wifi: config nano formating: disabled
I (629) wifi: config nano formatting: disabled
I (629) wifi: Init dynamic tx buffer num: 32
I (629) wifi: Init data frame dynamic rx buffer num: 32
I (639) wifi: Init management frame dynamic rx buffer num: 32

0
examples/wifi/antenna/components/antenna_soft_switch/CMakeLists.txt → examples/phy/antenna/components/antenna_soft_switch/CMakeLists.txt
View File

49
examples/wifi/antenna/components/antenna_soft_switch/antenna_switch.c → examples/phy/antenna/components/antenna_soft_switch/antenna_switch.c
View File

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Unlicense OR CC0-1.0
*/
@ -16,6 +16,7 @@
#include "freertos/event_groups.h"
#include "freertos/queue.h"
#include "esp_wifi.h"
#include "esp_phy.h"
#include "esp_log.h"
#include "esp_check.h"
@ -46,17 +47,17 @@ static TaskHandle_t antenna_task_handle;
/**< Select the optimal antenna*/
static void antenna_switch_function(const wifi_antenna_auto_switch_config_t *config)
{
wifi_ant_config_t wifi_ant_config;
esp_phy_ant_config_t wifi_ant_config;
wifi_ap_record_t wifi_ap_record;
int16_t rssi_ant0 = INT16_MIN, rssi_ant1 = INT16_MIN, rssi_ant2 = INT16_MIN, rssi_max, rssi_min;
/**< Monitor antenna zero signal strength*/
wifi_ant_config.rx_ant_mode = WIFI_ANT_MODE_ANT0;
wifi_ant_config.rx_ant_default = WIFI_ANT_MODE_ANT0;
wifi_ant_config.tx_ant_mode = WIFI_ANT_MODE_ANT0;
wifi_ant_config.rx_ant_mode = ESP_PHY_ANT_MODE_ANT0;
wifi_ant_config.rx_ant_default = ESP_PHY_ANT_MODE_ANT0;
wifi_ant_config.tx_ant_mode = ESP_PHY_ANT_MODE_ANT0;
wifi_ant_config.enabled_ant0 = config->ant_zero;
wifi_ant_config.enabled_ant1 = config->ant_one;
ESP_ERROR_CHECK(esp_wifi_set_ant(&wifi_ant_config));
ESP_ERROR_CHECK(esp_phy_set_ant(&wifi_ant_config));
/**< Wait for parameters to take effect*/
vTaskDelay(100/portTICK_PERIOD_MS);
while(ESP_OK != esp_wifi_sta_get_ap_info(&wifi_ap_record)) {
@ -80,9 +81,9 @@ static void antenna_switch_function(const wifi_antenna_auto_switch_config_t *con
ESP_LOGD(TAG, "The signal strength of the antenna zero :%d", rssi_ant0);
/**< Monitor antenna one signal strength*/
wifi_ant_config.rx_ant_mode = WIFI_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = WIFI_ANT_MODE_ANT1;
ESP_ERROR_CHECK(esp_wifi_set_ant(&wifi_ant_config));
wifi_ant_config.rx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
ESP_ERROR_CHECK(esp_phy_set_ant(&wifi_ant_config));
/**< Wait for parameters to take effect*/
vTaskDelay(100/portTICK_PERIOD_MS);
while(ESP_OK != esp_wifi_sta_get_ap_info(&wifi_ap_record)) {
@ -107,10 +108,10 @@ static void antenna_switch_function(const wifi_antenna_auto_switch_config_t *con
if(config->ant_num == ANT_TOTAL_THREE) {
/**< Monitor antenna two signal strength*/
wifi_ant_config.rx_ant_mode = WIFI_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = WIFI_ANT_MODE_ANT1;
wifi_ant_config.rx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
wifi_ant_config.enabled_ant1 = config->ant_two;
ESP_ERROR_CHECK(esp_wifi_set_ant(&wifi_ant_config));
ESP_ERROR_CHECK(esp_phy_set_ant(&wifi_ant_config));
/**< Wait for parameters to take effect*/
vTaskDelay(100/portTICK_PERIOD_MS);
while(ESP_OK != esp_wifi_sta_get_ap_info(&wifi_ap_record)) {
@ -137,31 +138,31 @@ static void antenna_switch_function(const wifi_antenna_auto_switch_config_t *con
if(rssi_ant0 >= rssi_ant1 && rssi_ant0 >= rssi_ant2) {
/**< antenna zero signal strength best*/
ESP_LOGD(TAG, "Antenna soft switching selection ant0");
wifi_ant_config.rx_ant_mode = WIFI_ANT_MODE_ANT0;
wifi_ant_config.tx_ant_mode = WIFI_ANT_MODE_ANT0;
wifi_ant_config.rx_ant_mode = ESP_PHY_ANT_MODE_ANT0;
wifi_ant_config.tx_ant_mode = ESP_PHY_ANT_MODE_ANT0;
wifi_ant_config.enabled_ant0 = config->ant_zero;
wifi_ant_config.enabled_ant1 = config->ant_one;
ESP_ERROR_CHECK(esp_wifi_set_ant(&wifi_ant_config));
ESP_ERROR_CHECK(esp_phy_set_ant(&wifi_ant_config));
}
if(rssi_ant1 > rssi_ant0 && rssi_ant1 > rssi_ant2) {
/**< antenna one signal strength best*/
ESP_LOGD(TAG, "Antenna soft switching selection ant1");
wifi_ant_config.rx_ant_mode = WIFI_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = WIFI_ANT_MODE_ANT1;
wifi_ant_config.rx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
wifi_ant_config.enabled_ant0 = config->ant_zero;
wifi_ant_config.enabled_ant1 = config->ant_one;
ESP_ERROR_CHECK(esp_wifi_set_ant(&wifi_ant_config));
ESP_ERROR_CHECK(esp_phy_set_ant(&wifi_ant_config));
}
if(rssi_ant2 > rssi_ant0 && rssi_ant2 > rssi_ant1) {
/**< antenna two signal strength best*/
ESP_LOGD(TAG, "Antenna soft switching selection ant2");
wifi_ant_config.rx_ant_mode = WIFI_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = WIFI_ANT_MODE_ANT1;
wifi_ant_config.rx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
wifi_ant_config.tx_ant_mode = ESP_PHY_ANT_MODE_ANT1;
wifi_ant_config.enabled_ant0 = config->ant_zero;
wifi_ant_config.enabled_ant1 = config->ant_two;
ESP_ERROR_CHECK(esp_wifi_set_ant(&wifi_ant_config));
ESP_ERROR_CHECK(esp_phy_set_ant(&wifi_ant_config));
}
}
@ -243,13 +244,13 @@ static void antenna_soft_switching_task(void *arg)
if (rssi_flag > WAIT_TIME) {
ESP_LOGD(TAG, "End of listening rssi");
/**< Ambient noise factor: abs(rssi_last_sum - rssi_sum) * RSSI_KD*/
int16_t ans = abs(rssi_save_sum - rssi_sum) - abs(rssi_last_sum - rssi_sum) * RSSI_KD;
int16_t and = abs(rssi_save_sum - rssi_sum) - abs(rssi_last_sum - rssi_sum) * RSSI_KD;
rssi_flag = 0;
if(ans > (config->ant_switch)) {
if(and > (config->ant_switch)) {
/**< Determine that the signal has changed*/
queue_rssi_sum_size = 0;
queue_rssi_single_size = 0;
ESP_LOGD(TAG, "monitor result:%d > %d", ans, (config->ant_switch));
ESP_LOGD(TAG, "monitor result:%d > %d", and, (config->ant_switch));
/**< Select the optimal antenna*/
antenna_switch_function(config);
/**< Wait for parameters to take effect*/

0
examples/wifi/antenna/components/antenna_soft_switch/include/antenna_switch.h → examples/phy/antenna/components/antenna_soft_switch/include/antenna_switch.h
View File

2
examples/phy/antenna/main/CMakeLists.txt Normal file
View File

@ -0,0 +1,2 @@
idf_component_register(SRCS "antenna_switch_example_main.c"
REQUIRES nvs_flash esp_wifi esp_phy antenna_soft_switch)

4
examples/wifi/antenna/main/Kconfig.projbuild → examples/phy/antenna/main/Kconfig.projbuild
View File

@ -23,8 +23,8 @@ menu "Example Configuration"
default ESP_WIFI_AUTH_WPA2_PSK
help
The weakest authmode to accept in the scan mode.
This value defaults to ESP_WIFI_AUTH_WPA2_PSK incase password is present and ESP_WIFI_AUTH_OPEN is used.
Please select ESP_WIFI_AUTH_WEP/ESP_WIFI_AUTH_WPA_PSK incase AP is operating in WEP/WPA mode.
This value defaults to ESP_WIFI_AUTH_WPA2_PSK in case password is present and ESP_WIFI_AUTH_OPEN is used.
Please select ESP_WIFI_AUTH_WEP/ESP_WIFI_AUTH_WPA_PSK in case AP is operating in WEP/WPA mode.
config ESP_WIFI_AUTH_OPEN
bool "OPEN"

18
examples/wifi/antenna/main/antenna_switch_example_main.c → examples/phy/antenna/main/antenna_switch_example_main.c
View File

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Unlicense OR CC0-1.0
*/
@ -21,6 +21,7 @@
#include "esp_log.h"
#include "nvs_flash.h"
#include "esp_wifi.h"
#include "esp_phy.h"
#include "lwip/err.h"
#include "lwip/sys.h"
@ -116,7 +117,7 @@ void wifi_init_sta(void)
.sta = {
.ssid = EXAMPLE_ESP_WIFI_SSID,
.password = EXAMPLE_ESP_WIFI_PASS,
/* Authmode threshold resets to WPA2 as default if password matches WPA2 standards (pasword len => 8).
/* Authmode threshold resets to WPA2 as default if password matches WPA2 standards (password len => 8).
* If you want to connect the device to deprecated WEP/WPA networks, Please set the threshold value
* to WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK and set the password with length and format matching to
* WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK standards.
@ -128,7 +129,8 @@ void wifi_init_sta(void)
ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA) );
ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config) );
ESP_ERROR_CHECK(esp_wifi_start() );
/* PHY multiple antenna api should be called when PHY is enabled, disable WI-FI Modem sleep can keep PHY always enabled */
ESP_ERROR_CHECK(esp_wifi_set_ps(WIFI_PS_NONE) );
ESP_LOGI(TAG, "wifi_init_sta finished.");
/* Waiting until either the connection is established (WIFI_CONNECTED_BIT) or connection failed for the maximum
@ -165,13 +167,13 @@ void app_main(void)
ESP_LOGI(TAG, "ESP_WIFI_MODE_STA");
wifi_init_sta();
wifi_ant_gpio_config_t ant_gpio_config = {
esp_phy_ant_gpio_config_t ant_gpio_config = {
// ESP32-WROOM-DA boards default antenna pins
.gpio_cfg[0] = {.gpio_select = 1, .gpio_num = 21},
.gpio_cfg[1] = {.gpio_select = 1, .gpio_num = 22},
};
ESP_ERROR_CHECK(esp_wifi_set_ant_gpio(&ant_gpio_config));
ESP_ERROR_CHECK(esp_wifi_get_ant_gpio(&ant_gpio_config));
ESP_ERROR_CHECK(esp_phy_set_ant_gpio(&ant_gpio_config));
ESP_ERROR_CHECK(esp_phy_get_ant_gpio(&ant_gpio_config));
ESP_LOGI(TAG, "GPIO: [0].pin = %d, [1].pin = %d",ant_gpio_config.gpio_cfg[0].gpio_num, ant_gpio_config.gpio_cfg[1].gpio_num);
wifi_antenna_auto_switch_config_t wifi_antenna_auto_switch_config;
@ -183,8 +185,8 @@ void app_main(void)
ESP_ERROR_CHECK(esp_wifi_set_ant_soft_switch(&wifi_antenna_auto_switch_config));
while(true) {
wifi_ant_config_t ant_config;
esp_wifi_get_ant(&ant_config);
esp_phy_ant_config_t ant_config;
esp_phy_get_ant(&ant_config);
ESP_LOGI(TAG, "rx mode = %d, tx mode = %d, ant0_en = %d, ant1_en = %d",ant_config.rx_ant_mode, ant_config.tx_ant_mode, ant_config.enabled_ant0, ant_config.enabled_ant1);
vTaskDelay(500 / portTICK_PERIOD_MS);
}

2
examples/wifi/antenna/main/CMakeLists.txt
View File

@ -1,2 +0,0 @@
idf_component_register(SRCS "antenna_switch_example_main.c"
REQUIRES nvs_flash esp_wifi antenna_soft_switch)