mirror
/
esp-idf
kopia lustrzana https://github.com/espressif/esp-idf
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

docs(phy): rewrite multi antenna docs

pull/13550/head
alanmaxwell 2024-03-25 22:14:19 +08:00
rodzic 2b8b3f49bf
commit 1d763691ea
4 zmienionych plików z 115 dodań i 58 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

2
docs/en/api-guides/index.rst
Wyświetl plik

@ -44,4 +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
:(SOC_WIFI_SUPPORTED or SOC_BT_SUPPORTED or SOC_IEEE802154_SUPPORTED) and not esp32p4: phy

92
docs/en/api-guides/phy.rst
Wyświetl plik

@ -5,48 +5,58 @@ PHY
Multiple Antennas
--------------------------
The 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 |//
|__________|
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.
{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.
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.
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_phy_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.
2. IO MUX and GPIO Matrix:
- Routes the internal 4-way antenna signals to specific IO pins.
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.
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.
Although up to sixteen antennas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_phy_set_ant()` is used to configure which antennas are enabled.
Steps for Multi-Antenna Usage
++++++++++++++++++++++++++++++
The enabled antennas selecting algorithm is also configured by :cpp:func:`esp_phy_set_ant()`. The RX/TX antenna mode can be :cpp:enumerator:`ESP_PHY_ANT_MODE_ANT0`, :cpp:enumerator:`ESP_PHY_ANT_MODE_ANT1`, or :cpp:enumerator:`ESP_PHY_ANT_MODE_AUTO`. If the antenna mode is :cpp:enumerator:`ESP_PHY_ANT_MODE_ANT0`, the enabled antenna 0 is selected for RX/TX data. If the antenna mode is :cpp:enumerator:`ESP_PHY_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.
1. Determine the IO pins used for controlling antenna switching based on hardware circuit design and external antenna switches.
If the RX antenna mode is :cpp:enumerator:`ESP_PHY_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:`ESP_PHY_ANT_MODE_ANT1`, the enabled antenna 1 is used as the default RX antenna, otherwise the enabled antenna 0 is used.
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].
Some limitations need to be considered:
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.
- The TX antenna can be set to :cpp:enumerator:`ESP_PHY_ANT_MODE_AUTO` only if the RX antenna mode is :cpp:enumerator:`ESP_PHY_ANT_MODE_AUTO`, because TX antenna selecting algorithm is based on RX antenna in :cpp:enumerator:`ESP_PHY_ANT_MODE_AUTO` type.
- When the TX antenna mode or RX antenna mode is configured to :cpp:enumerator:`ESP_PHY_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.
Multi-Antenna Configuration Reference Example
+++++++++++++++++++++++++++++++++++++++++++++++
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/phy/antenna/README.md` for the antenna selecting algorithm design.
- Both RX/TX antenna modes are configured to ESP_PHY_ANT_MODE_ANT0 or ESP_PHY_ANT_MODE_ANT1.
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:
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
@ -55,7 +65,7 @@ Generally, following steps can be taken to configure the multiple antennas:
.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:
- 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
@ -66,3 +76,21 @@ Generally, following steps can be taken to configure the multiple antennas:
.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.

2
docs/zh_CN/api-guides/index.rst
Wyświetl plik

@ -44,4 +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
:(SOC_WIFI_SUPPORTED or SOC_BT_SUPPORTED or SOC_IEEE802154_SUPPORTED) and not esp32p4: phy

77
docs/zh_CN/api-guides/phy.rst
Wyświetl plik

@ -5,43 +5,53 @@ PHY
多根天线
-------------------
下图描述多根天线的选择过程::
__________
|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 |//
|__________|
多根天线功能原理和组成
++++++++++++++++++++++++++++
多根天线功能主要通过将内部天线模块工作信号输出到具体 IO 引脚上，通过 IO 引脚控制外部天线切换器选择指定天线，最多支持 16 根天线。
{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_phy_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 的值。
___________________________________________________________________________
____|____ _________ |
|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] --> |_________|
天线开关的具体实现不同，`antenna_select[0:3]` 的输入值中可能存在非法值，即 {IDF_TARGET_NAME} 通过外部天线开关支持的天线数可能小于 16 根。例如，ESP32-WROOM-DA 使用 RTC6603SP 作为天线开关，仅支持 2 根天线。两个天线选择输入管脚为高电平有效，连接到两个 GPIO。'0b01' 表示选中天线 0，'0b10' 表示选中天线 1。输入值 '0b00' 和 '0b11' 为非法值。
{IDF_TARGET_NAME} 多根天线功能主要包含 3 个部分：芯片内部的 PHY 天线模块、IO MUX 和 GPIO Matrix、以及外部的天线切换器。
尽管最多支持 16 根天线，发送和接收数据时，最多仅能同时使能两根天线。API :cpp:func:`esp_phy_set_ant()` 用于配置使能哪些天线。
1.芯片内部的天线选择模块 PHY Antenna Module：
- 两个天线模块均支持工作于发送 (TX) 或接收 (RX) 模式，可以通过软件配置发送和接收选用某个模块。
- 每个天线模块最多支持输出 4 个天线选择信号 antenna_select[3:0]，该信号值可由软件配置并且可以一一映射到任意 IO 引脚。
- 当某个天线模块处于工作状态时，IO 引脚的高低电平值为软件配置的信号值。
使能天线后，选择算法的过程同样可由 :cpp:func:`esp_phy_set_ant()` 配置。接收/发送数据源的天线模式可以是 ESP_PHY_ANT_MODE_ANT0、ESP_PHY_ANT_MODE_ANT1 或 ESP_PHY_ANT_MODE_AUTO。如果天线模式为 ESP_PHY_ANT_MODE_AUTO，使能的天线 0 用于接收/发送数据。如果天线模式为 ESP_PHY_ANT_MODE_ANT1，使能天线 1 用于接收/发送数据。否则，会自动选择使能天线中信号较好的天线。
2.IO MUX 和 GPIO Matrix：
- 将内部 4 路天线信号输出到具体的 IO 引脚上。
如果接收数据的天线模式为 ESP_PHY_ANT_MODE_AUTO，还需要设置默认天线模式。只有在满足某些条件时，接收数据天线才会切换，例如，如果 RSSI 低于 -65 dBm，或另一根天线信号更好。如果条件不满足，接收数据使用默认天线。如果默认天线模式为 ESP_PHY_ANT_MODE_ANT1，则使能的天线 1 是默认接收数据天线，否则是使能的天线 0。
3.外部的天线切换器：
- 一般为多路选择器，通过 ant_sel_in[x] 引脚的电平，选择工作的天线，例如 ant_sel_in[3:0] 为 "0b1011"，表示选中天线 11。
有一些限制情况需要考虑：
多根天线使用步骤
+++++++++++++++++++++++++++
- 因为发送数据天线基于 ESP_PHY_ANT_MODE_AUTO 类型的接收数据天线选择算法，只有接收数据的天线模式为 ESP_PHY_ANT_MODE_AUTO 时，发送数据天线才能设置为 ESP_PHY_ANT_MODE_AUTO。
- 接收或者发送天线模式配置为 ESP_PHY_ANT_MODE_AUTO 时，只要存在 RF 信号的恶化，很容易触发天线切换。如果射频信号不稳定，天线会频繁切换，使得总的射频性能无法达到预期效果。
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]。
- 应用程序可以始终选择指定的天线，也可以执行自身天线选择算法，如根据应用程序收集的信息来选择天线模式等。请参考 IDF 示例 :idf_file:`examples/phy/antenna/README.md` 来设计天线选择算法。
- 接收/发送数据的天线模式均配置为 ESP_PHY_ANT_MODE_ANT0 或 ESP_PHY_ANT_MODE_ANT1。
3.配置内部天线工作模式及输出信号
- API :cpp:func:`esp_phy_set_ant()` 用于配置发送或接收时使用内部天线模块 0 或 1，并配置当天线模块 0 或 1 工作时的输出信号值。
- 对于 ESP_PHY_ANT_MODE_AUTO 模式目前不推荐使用。
多根天线配置
多根天线配置参考例子
++++++++++++++++++++++++++++
通常，可以执行以下步骤来配置多根天线：
@ -66,3 +76,22 @@ PHY
.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。