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

docs: translate coexist from CN to EN

Browse Source
This commit is contained in:
xiongweichao 2021-07-29 11:20:52 +08:00 committed by BOT
parent 06df46e26a
commit 6514f9e94c
14 changed files with 461 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/soc/esp32/include/soc/Kconfig.soc_caps.in
View File

@ -95,6 +95,10 @@ config SOC_SIGMADELTA_SUPPORTED
bool
default y
config SOC_SUPPORT_COEXISTENCE
bool
default y
config SOC_ADC_RTC_CTRL_SUPPORTED
bool
default y

1
components/soc/esp32/include/soc/soc_caps.h
View File

@ -83,6 +83,7 @@
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1
#define SOC_SUPPORT_COEXISTENCE 1
/*-------------------------- ADC CAPS ----------------------------------------*/

4
components/soc/esp32c3/include/soc/Kconfig.soc_caps.in
View File

@ -103,6 +103,10 @@ config SOC_SIGMADELTA_SUPPORTED
bool
default y
config SOC_SUPPORT_COEXISTENCE
bool
default y
config SOC_AES_SUPPORT_DMA
bool
default y

1
components/soc/esp32c3/include/soc/soc_caps.h
View File

@ -50,6 +50,7 @@
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1
#define SOC_SUPPORT_COEXISTENCE 1
/*-------------------------- AES CAPS -----------------------------------------*/
#define SOC_AES_SUPPORT_DMA (1)

4
components/soc/esp32s2/include/soc/Kconfig.soc_caps.in
View File

@ -131,6 +131,10 @@ config SOC_SIGMADELTA_SUPPORTED
bool
default y
config SOC_SUPPORT_COEXISTENCE
bool
default n
config SOC_ADC_RTC_CTRL_SUPPORTED
bool
default y

1
components/soc/esp32s2/include/soc/soc_caps.h
View File

@ -71,6 +71,7 @@
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1
#define SOC_SUPPORT_COEXISTENCE 0
/*-------------------------- ADC CAPS ----------------------------------------*/

4
components/soc/esp32s3/include/soc/Kconfig.soc_caps.in
View File

@ -235,6 +235,10 @@ config SOC_SIGMADELTA_SUPPORTED
bool
default y
config SOC_SUPPORT_COEXISTENCE
bool
default y
config SOC_TEMP_SENSOR_SUPPORTED
bool
default y

1
components/soc/esp32s3/include/soc/soc_caps.h
View File

@ -59,6 +59,7 @@
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1
#define SOC_SUPPORT_COEXISTENCE 1
#define SOC_TEMP_SENSOR_SUPPORTED 1
/*-------------------------- SOC CAPS ----------------------------------------*/

BIN
docs/_static/coexist_wifi_connected_and_ble_connected_time_slice.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

3
docs/conf_common.py
View File

@ -49,6 +49,8 @@ WIFI_DOCS = ['api-guides/wifi.rst',
'api-guides/wifi-security.rst',
'api-guides/wireshark-user-guide.rst']
COEXISTENCE_DOCS = ['api-guides/coexist.rst']
SDMMC_DOCS = ['api-reference/peripherals/sdmmc_host.rst',
'api-reference/peripherals/sd_pullup_requirements.rst']
@ -129,6 +131,7 @@ ESP32C3_DOCS = ['hw-reference/esp32c3/**',
conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
'SOC_WIFI_SUPPORTED':WIFI_DOCS,
'SOC_CLASSIC_BT_SUPPORTED':CLASSIC_BT_DOCS,
'SOC_SUPPORT_COEXISTENCE':COEXISTENCE_DOCS,
'SOC_SDMMC_HOST_SUPPORTED':SDMMC_DOCS,
'SOC_SDIO_SLAVE_SUPPORTED':SDIO_SLAVE_DOCS,
'SOC_MCPWM_SUPPORTED':MCPWM_DOCS,

217
docs/en/api-guides/coexist.rst Normal file
View File

@ -0,0 +1,217 @@
RF Coexistence
==================
:link_to_translation:`zh_CN:[中文]`
Overview
---------------
{IDF_TARGET_NAME} has only one 2.4 GHz ISM band RF module, which is shared by Bluetooth (BT & BLE) and Wi-Fi, so Bluetooth can't receive or transmit data while Wi-Fi is receiving or transmitting data and vice versa. Under such circumstances, {IDF_TARGET_NAME} uses the time-division multiplexing method to receive and transmit packets.
Supported Coexistence Scenario for {IDF_TARGET_NAME}
---------------------------------------------------------------------
.. only:: esp32c3 or esp32s3 or esp32
.. table:: Supported Features of Wi-Fi and BLE Coexistence
+-------+--------+-----------+-----+------------+-----------+----------+
| |BLE |
+ +-----+------------+-----------+----------+
| |Scan |Advertising |Connecting |Connected |
+-------+--------+-----------+-----+------------+-----------+----------+
| Wi-Fi |STA |Scan |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connecting |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connected |Y |Y |Y |Y |
+ +--------+-----------+-----+------------+-----------+----------+
| |SOFTAP |TX Beacon |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connecting |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connected |C1 |C1 |C1 |C1 |
+ +--------+-----------+-----+------------+-----------+----------+
| |Sniffer |RX |C2 |C2 |C2 |C2 |
+ +--------+-----------+-----+------------+-----------+----------+
| |ESP-NOW |RX |X |X |X |X |
+ + +-----------+-----+------------+-----------+----------+
| | |TX |Y |Y |Y |Y |
+-------+--------+-----------+-----+------------+-----------+----------+
.. only:: esp32
.. table:: Supported Features of Wi-Fi and Classic Bluetooth (BT) Coexistence
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
| |BR/EDR |
+ +--------+-------------+-----+----------+-----------+
| |Inquiry |Inquiry scan |Page |Page scan | Connected |
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
| Wi-Fi |STA |Scan |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connecting |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connected |Y |Y |Y |Y |Y |
+ +--------+-----------+--------+-------------+-----+----------+-----------+
| |SOFTAP |TX Beacon |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connecting |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connected |C1 |C1 |C1 |C1 |C1 |
+ +--------+-----------+--------+-------------+-----+----------+-----------+
| |Sniffer |RX |C2 |C2 |C2 |C2 |C2 |
+ +--------+-----------+--------+-------------+-----+----------+-----------+
| |ESP-NOW |RX |X |X |X |X |X |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |TX |Y |Y |Y |Y |Y |
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
.. note::
Y: supported and performance is stable
C1: supported but the performance is unstable
C2: supported but the packet loss rate of Sniffer is unstable
X: not supported
Coexistence Mechanism and Policy
------------------------------------------------
Coexistence Mechanism
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The RF resource allocation mechanism is based on priority. As shown below, both Bluetooth module and Wi-Fi module request RF resources from the coexistence module, and the coexistence module decides who will use the RF resource based on their priority.
.. blockdiag::
:scale: 100%
:caption: Coexistence Mechanism
:align: center
blockdiag {
# global attributes
node_height = 60;
node_width = 120;
span_width = 100;
span_height = 60;
default_shape = roundedbox;
default_group_color = none;
# node labels
Wi-Fi [shape = box];
Bluetooth [shape = box];
Coexistence [shape = box, label = 'Coexistence module'];
RF [shape = box, label = 'RF module'];
# node connections
Wi-Fi -> Coexistence;
Bluetooth -> Coexistence;
Coexistence -> RF;
}
Coexistence Policy
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Coexistence Period and Time Slice
""""""""""""""""""""""""""""""""""""""""
.. only:: esp32
Wi-Fi, BT, and BLE have their fixed time slice to use the RF. A coexistence period is divided into 3 time slices in the order of Wi-Fi, BT, and BLE. In the Wi-Fi slice, Wi-Fi's request to the coexistence arbitration module will have higher priority. Similarly, BT/BLE can enjoy higher priority at their own time slices. The duration of the coexistence period and the proportion of each time slice are divided into four categories according to the Wi-Fi status:
.. only:: esp32c3 or esp32s3
Wi-Fi and BLE have their fixed time slice to use the RF. In the Wi-Fi time slice, Wi-Fi will send a higher priority request to the coexistence arbitration module. Similarly, BLE can enjoy higher priority at their own time slice. The duration of the coexistence period and the proportion of each time slice are divided into four categories according to the Wi-Fi status:
.. list::
:esp32: 1) IDLE status: the coexistence of BT and BLE is controlled by Bluetooth module.
:esp32c3 or esp32s3: 1) IDLE status: RF module is controlled by Bluetooth module.
#) CONNECTED status: the coexistence period starts at the Target Beacon Transmission Time (TBTT) and is more than 100 ms.
#) SCAN status: Wi-Fi slice and coexistence period are longer than in the CONNECTED status. To ensure Bluetooth performance, the Bluetooth time slice will also be adjusted accordingly.
#) CONNECTING status: Wi-Fi slice is longer than in the CONNECTED status. To ensure Bluetooth performance, the Bluetooth time slice will also be adjusted accordingly.
According to the coexistence logic, different coexistence periods and time slice strategies will be selected based on the Wi-Fi and Bluetooth usage scenarios. A Coexistence policy corresponding to a certain usage scenarios is called a "coexistence scheme". For example, the scenario of Wi-Fi CONNECTED and BLE CONNECTED has a corresponding coexistence scheme. In this scheme, the time slices of Wi-Fi and BLE in a coexistence period each account for 50%. The time allocation is shown in the following figure:
.. figure:: ../../_static/coexist_wifi_connected_and_ble_connected_time_slice.png
:align: center
:alt: Time Slice Under the Status of Wi-Fi CONNECTED and BLE CONNECTED
:figclass: align-center
Time Slice Under the Status of Wi-Fi CONNECTED and BLE CONNECTED
Dynamic Priority
""""""""""""""""""""""""""""
The coexistence module assigns different priorities to different status of Wi-Fi and Bluetooth. And the priority for each status is dynamic. For example, in every N BLE Advertising events, there is always one event with high priority. If a high-priority BLE Advertising event occurs within the Wi-Fi time slice, the right to use the RF may be preempted by BLE.
How to Use the Coexistence Feature
--------------------------------------
Coexistence API
^^^^^^^^^^^^^^^^^^^^^^^^^^^
For most coexistence cases, {IDF_TARGET_NAME} will switch the coexistence status automatically without calling API. However, {IDF_TARGET_NAME} provides two APIs for the coexistence of BLE MESH and Wi-Fi. When the status of BLE MESH changes, call :code:`esp_coex_status_bit_clear` to clear the previous status first and then call :code:`esp_coex_status_bit_set` to set the current status.
BLE MESH Coexistence Status
""""""""""""""""""""""""""""""""""
As the firmware of Wi-Fi and Bluetooth are not aware of the current scenario of the upper layer application, some coexistence schemes require application code to call the coexistence API to take effect. The application layer needs to pass the working status of BLE MESH to the coexistence module for selecting the coexistence scheme.
- ESP_COEX_BLE_ST_MESH_CONFIG: network is provisioning
- ESP_COEX_BLE_ST_MESH_TRAFFIC: data is transmitting
- ESP_COEX_BLE_ST_MESH_STANDBY: in idle status with no significant data interaction
Coexistence API Error Codes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All coexistence APIs have custom return values, i.e. error codes. These error codes can be categorized as:
- No error. For example, the return value ESP_OK siginifies the API returned successfully.
- Recoverable errors. For example, the return value ESP_ERR_INVALID_ARG signifies API parameter errors.
Setting Coexistence Compile-time Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list::
- After writing the coexistence program, you must check :ref:`CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE` option through menuconfig to open coexistence configuration on software, otherwise the coexistence function mentioned above cannot be used.
:esp32: - To ensure better communication performance of Wi-Fi and Bluetooth in the case of coexistence, run the task of the Wi-Fi protocol stack, the task of the Bluetooth Controller and Host protocol stack on different CPUs. You can use :ref:`CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE` and :ref:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` (or :ref:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE`) to put the tasks of the Bluetooth controller and the host protocol stack on the same CPU, and then use :ref:`CONFIG_ESP32_WIFI_TASK_CORE_ID` to place the task of the Wi-Fi protocol stack on another CPU.
:esp32s3: - To ensure better communication performance of Wi-Fi and Bluetooth in the case of coexistence, run the task of the Wi-Fi protocol stack, the task of the Bluetooth Controller and Host protocol stack on different CPUs. You can use :ref:`CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE` and :ref:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` (or :ref:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE` ）to put the tasks of the Bluetooth controller and the host protocol stack on the same CPU, and then use :ref:`CONFIG_ESP32_WIFI_TASK_CORE_ID` to place the task of the Wi-Fi protocol stack on another CPU.
:esp32: - In the case of coexistence, BLE SCAN may be interrupted by Wi-Fi and Wi-Fi releases RF resources before the end of the current BLE scan window. In order to make BLE acquire RF resources again within the current scan window, you can check the FULL SCAN configuration option through :ref:`CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED`.
:esp32c3 or esp32s3: - When using LE Coded PHY during a BLE connection, to avoid affecting Wi-Fi performance due to the long duration of Bluetooth packets, you can select `BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN` in the sub-options of :ref:`CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM` to limit the maximum time of TX/RX.
- You can reduce the memory consumption by configuring the following options on menuconfig.
1) :ref:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY`: enable the configuration of dynamic memory for Bluetooth protocol stack.
#) :ref:`CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM`: reduce the number of Wi-Fi static RX buffers.
#) :ref:`CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM`: reduce the number of Wi-Fi dynamic RX buffers.
#) :ref:`CONFIG_ESP32_WIFI_TX_BUFFER`: enable the configuration of dynamic allocation TX buffers.
#) :ref:`CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM`: reduce the number of Wi-Fi dynamic TX buffers.
#) :ref:`CONFIG_ESP32_WIFI_TX_BA_WIN`: reduce the number of Wi-Fi Block Ack TX windows.
#) :ref:`CONFIG_ESP32_WIFI_RX_BA_WIN`: reduce the number of Wi-Fi Block Ack RX windows.
#) :ref:`CONFIG_ESP32_WIFI_MGMT_SBUF_NUM`: reduce the number of Wi-Fi Management Short Buffer.
#) :ref:`CONFIG_ESP32_WIFI_RX_IRAM_OPT`: turning off this configuration option will reduce the IRAM memory by approximately 17 KB.
#) :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT`: reduce the default TX buffer size for TCP sockets.
#) :ref:`CONFIG_LWIP_TCP_WND_DEFAULT`: reduce the default size of the RX window for TCP sockets.
#) :ref:`CONFIG_LWIP_TCP_RECVMBOX_SIZE`: reduce the size of the TCP receive mailbox.
#) :ref:`CONFIG_LWIP_UDP_RECVMBOX_SIZE`: reduce the size of the UDP receive mailbox.
#) :ref:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE`: reduce the size of TCPIP task receive mailbox.
.. note::
Since the coexistence configuration option depends on the Bluetooth configuration option, please turn on the Bluetooth configuration option first before configuring the coexistence feature in the Wi-Fi configuration option.

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

@ -20,7 +20,7 @@ API Guides
event-handling
fatal-errors
../security/flash-encryption
:esp32s3: flash_psram_config
:esp32s3: flash_psram_config
hardware-abstraction
:CONFIG_IDF_TARGET_ARCH_XTENSA: hlinterrupts
jtag-debugging/index
@ -42,3 +42,4 @@ API Guides
:SOC_USB_SERIAL_JTAG_SUPPORTED: usb-serial-jtag-console
:SOC_WIFI_SUPPORTED: wifi
:SOC_WIFI_SUPPORTED: wifi-security
:SOC_SUPPORT_COEXISTENCE: coexist

217
docs/zh_CN/api-guides/coexist.rst Normal file
View File

@ -0,0 +1,217 @@
RF 共存
==================
:link_to_translation:`en:[English]`
概览
-----
{IDF_TARGET_NAME} 只支持一路 RF，Bluetooth (BT 和 BLE）和 Wi-Fi 共享这一路 RF，无法同时收发数据，因此采用时分复用的方法进行收发数据包。
{IDF_TARGET_NAME} 支持的共存场景
------------------------------------
.. only:: esp32c3 or esp32s3 or esp32
.. table:: 表 1 Wi-Fi 和 BLE 共存支持功能
+-------+--------+-----------+-----+------------+-----------+----------+
| |BLE |
+ +-----+------------+-----------+----------+
| |Scan |Advertising |Connecting |Connected |
+-------+--------+-----------+-----+------------+-----------+----------+
| Wi-Fi |STA |Scan |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connecting |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connected |Y |Y |Y |Y |
+ +--------+-----------+-----+------------+-----------+----------+
| |SOFTAP |TX Beacon |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connecting |Y |Y |Y |Y |
+ + +-----------+-----+------------+-----------+----------+
| | |Connected |C1 |C1 |C1 |C1 |
+ +--------+-----------+-----+------------+-----------+----------+
| |Sniffer |RX |C2 |C2 |C2 |C2 |
+ +--------+-----------+-----+------------+-----------+----------+
| |ESP-NOW |RX |X |X |X |X |
+ + +-----------+-----+------------+-----------+----------+
| | |TX |Y |Y |Y |Y |
+-------+--------+-----------+-----+------------+-----------+----------+
.. only:: esp32
.. table:: 表 2 Wi-Fi 和经典蓝牙 (BT) 共存支持功能
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
| |BR/EDR |
+ +--------+-------------+-----+----------+-----------+
| |Inquiry |Inquiry scan |Page |Page scan | Connected |
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
| Wi-Fi |STA |Scan |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connecting |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connected |Y |Y |Y |Y |Y |
+ +--------+-----------+--------+-------------+-----+----------+-----------+
| |SOFTAP |TX Beacon |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connecting |Y |Y |Y |Y |Y |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |Connected |C1 |C1 |C1 |C1 |C1 |
+ +--------+-----------+--------+-------------+-----+----------+-----------+
| |Sniffer |RX |C2 |C2 |C2 |C2 |C2 |
+ +--------+-----------+--------+-------------+-----+----------+-----------+
| |ESP-NOW |RX |X |X |X |X |X |
+ + +-----------+--------+-------------+-----+----------+-----------+
| | |TX |Y |Y |Y |Y |Y |
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
.. note::
Y：支持且性能稳定。
C1：不能保证性能处于稳定状态。
C2：sniffer 无法保证丢包率。
X：不支持。
共存机制与策略
----------------------------------
共存机制
^^^^^^^^^^^^^^
基于优先级抢占的 RF 资源分配机制，如下图所示，Bluetooth 模块和 Wi-Fi 模块向共存模块申请 RF 资源，共存模块根据二者的优先级高低裁决 RF 归谁使用。
.. blockdiag::
:scale: 100%
:caption: 共存机制
:align: center
blockdiag {
# global attributes
node_height = 60;
node_width = 120;
span_width = 100;
span_height = 60;
default_shape = roundedbox;
default_group_color = none;
# node labels
Wi-Fi [shape = box];
Bluetooth [shape = box];
Coexistence [shape = box, label = 'Coexistence module'];
RF [shape = box, label = 'RF module'];
# node connections
Wi-Fi -> Coexistence;
Bluetooth -> Coexistence;
Coexistence -> RF;
}
共存策略
^^^^^^^^^^^^^^
共存周期和时间片
"""""""""""""""""""
.. only:: esp32
Wi-Fi、BT、BLE 三者对于 RF 的使用，主要是按照时间片来划分的。在一个共存周期内，按照 Wi-Fi、BT、BLE 的顺序划分时间片。在 Wi-Fi 的时间片内，Wi-Fi 会向共存仲裁模块发出较高优先级的请求，同理，BT/BLE 在自己的时间片内会具有较高优先级。共存周期大小和各个时间片占比根据 Wi-Fi 的状态分成四类：
.. only:: esp32c3 or esp32s3
Wi-Fi、BLE 二者对于 RF 的使用，主要是按照时间片来划分的。在 Wi-Fi 的时间片内，Wi-Fi 会向共存仲裁模块发出较高优先级的请求，在 Bluetooth 的时间片内，BLE 会具有较高优先级。共存周期大小和各个时间片占比根据 Wi-Fi 的状态分成四类：
.. list::
:esp32: 1) IDLE 状态：BT 和 BLE 共存由 Bluetooth 模块控制。
:esp32c3 or esp32s3: 1) IDLE 状态：RF 模块由 Bluetooth 模块控制。
#) CONNECTED 状态：共存周期以目标信标传输时间 (Target Beacon Transmission Time, TBTT) 点为起始点，周期大于 100 ms。
#) SCAN 状态：Wi-Fi 时间片以及共存周期都比在 CONNECTED 状态下的长。为了确保蓝牙的性能，蓝牙的时间片也会做相应的调整。
#) CONNECTING 状态：Wi-Fi 时间片比在 CONNECTED 状态下的长。为了确保蓝牙的性能，蓝牙的时间片也会做相应的调整。
共存逻辑会根据当前 Wi-Fi 和 Bluetooth 的使用场景来选取不同的共存周期和共存时间片的划分策略。对应一个使用场景的共存策略，我们称之为“共存模板”。比如，Wi-Fi CONNECTED 与 BLE CONNECTED 的场景，就对应有一个共存模板。在这个共存模板中，一个共存周期内 Wi-Fi 和 BLE 的时间片各占 50%，时间分配如下图所示：
.. figure:: ../../_static/coexist_wifi_connected_and_ble_connected_time_slice.png
:align: center
:alt: Wi-Fi CONNECTED 和 BLE CONNECTED 状态下时间片划分图
:figclass: align-center
Wi-Fi CONNECTED 和 BLE CONNECTED 共存状态下时间片划分图
动态优先级
"""""""""""""""""""
共存模块对 Wi-Fi 和 Bluetooth 不同的状态赋予其不同的优先级。每种状态下的优先级并不是一成不变的，例如每 N 个广播事件 (Advertising event) 中会有一个广播事件使用高优先级。如果高优先级的广播事件发生在 Wi-Fi 时间片内，RF 的使用权可能会被 BLE 抢占。
如何使用共存功能
----------------------------------
共存 API 的使用
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
在大多数共存情况下，{IDF_TARGET_NAME} 会自动进行共存状态切换，无需调用 API 对其进行干预。但是对于 BLE MESH 和 Wi-Fi 的共存，{IDF_TARGET_NAME} 对其提供了两个 API。当 BLE MESH 的状态发生变化时，应先调用 :code:`esp_coex_status_bit_clear` 对上一个状态进行清除，然后调用 :code:`esp_coex_status_bit_set` 设置当前状态。
BLE MESH 共存状态描述
""""""""""""""""""""""""""""
由于 Wi-Fi 和 Bluetooth 固件无法获知当前的上层应用的场景，一些共存模板需要应用代码调用共存的 API 才能生效。BLE MESH 的工作状态就需要由应用层通知给共存模块，用于选择共存模板。
- ESP_COEX_BLE_ST_MESH_CONFIG：正在组网。
- ESP_COEX_BLE_ST_MESH_TRAFFIC：正在传输数据。
- ESP_COEX_BLE_ST_MESH_STANDBY：处于空闲状态，无大量数据交互。
共存 API 错误代码
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
所有共存 API 都有自定义的返回值，即错误代码。这些代码可分类为：
- 无错误，例如：返回值为 ESP_OK 代表 API 成功返回。
- 可恢复错误，例如: 返回值为 ESP_ERR_INVALID_ARG 代表 API 参数错误。
设置共存编译时选项
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list::
- 在完成共存程序编写的时候，您必须通过 menuconfig 选择 :ref:`CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE` 打开软件共存配置选项，否则就无法使用上文中提到的共存功能。
:esp32: - 为了在共存情况下获得更好的 Wi-Fi 和蓝牙的通信性能，建议将 Wi-Fi 协议栈的 task 和蓝牙 Controller 以及 Host 协议栈的 task 运行在不同的 CPU 上。您可以通过 :ref:`CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE` 和 :ref:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` （或者 :ref:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE` ）选择将蓝牙 controller 以及 host 协议栈的 task 放在同一个 CPU 上，再通过 :ref:`CONFIG_ESP32_WIFI_TASK_CORE_ID` 选择将 Wi-Fi 协议栈 task 放在另一个 CPU 上。
:esp32s3: - 为了在共存情况下获得更好的 Wi-Fi 和蓝牙的通信性能，建议将 Wi-Fi 协议栈的 task 和蓝牙 Controller 以及 Host 协议栈的 task 运行在不同的 CPU 上，您可以通过 :ref:`CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE` 和 :ref:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` （或者 :ref:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE` ）选择将蓝牙 controller 以及 host 协议栈的 task 放在同一个 CPU 上，再通过 :ref:`CONFIG_ESP32_WIFI_TASK_CORE_ID` 选择将 Wi-Fi 协议栈 task 放在另一个 CPU 上。
:esp32: - 在共存情况下 BLE SCAN 可能会被 Wi-Fi 打断且 Wi-Fi 在当前的 BLE scan window 结束前释放了 RF 资源。为了使 BLE 在当前的 scan window 内再次获取 RF 资源，您可以通过 :ref:`CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED` 选择打开 FULL SCAN 配置选项。
:esp32c3 or esp32s3: - 在 BLE 连接过程中使用了 LE Coded PHY 时，为了防止蓝牙数据包持续时间较长而对 Wi-Fi 的性能产生严重影响，您可以在 :ref:`CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM` 的子选项中选择 `BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN` 选择打开对 TX/RX 最大时间的限制配置选项。
- 您可以通过修改以下 menuconfig 选项，以减小内存开销：
1) :ref:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY` 选择打开蓝牙协议栈动态内存配置选项。
#) :ref:`CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM` 选择减少 Wi-Fi 静态接收数据缓冲区的数量。
#) :ref:`CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM` 选择减少 Wi-Fi 动态接收数据缓冲区的数量。
#) :ref:`CONFIG_ESP32_WIFI_TX_BUFFER` 选择使用动态分配发送数据缓冲区配置选项。
#) :ref:`CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM` 选择减少 Wi-Fi 动态发送数据缓冲区的数量。
#) :ref:`CONFIG_ESP32_WIFI_TX_BA_WIN` 选择减少 Wi-Fi Block Ack TX 窗口的数量。
#) :ref:`CONFIG_ESP32_WIFI_RX_BA_WIN` 选择减少 Wi-Fi Block Ack RX 窗口的数量。
#) :ref:`CONFIG_ESP32_WIFI_MGMT_SBUF_NUM` 选择减少 Wi-Fi 管理短缓冲区的数量。
#) :ref:`CONFIG_ESP32_WIFI_RX_IRAM_OPT` 选择关闭此配置选项，关闭此配置选项将会减少大约 17 KB 的 IRAM 内存。
#) :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT` 选择减小 TCP 套接字默认发送缓存区大小。
#) :ref:`CONFIG_LWIP_TCP_WND_DEFAULT` 选择减小 TCP 套接字默认接收窗口的大小。
#) :ref:`CONFIG_LWIP_TCP_RECVMBOX_SIZE` 选择减小 TCP 接收邮箱的大小。
#) :ref:`CONFIG_LWIP_UDP_RECVMBOX_SIZE` 选择减小 UDP 接收邮箱的大小。
#) :ref:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE` 选择减小 TCPIP 任务接收邮箱大小。
.. note::
由于共存配置选项依赖于蓝牙配置选项，所以请先打开蓝牙配置选项，然后在 Wi-Fi 配置选项中打开共存配置选项。

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

@ -20,7 +20,7 @@ API 指南
event-handling
fatal-errors
../security/flash-encryption
:esp32s3: flash_psram_config
:esp32s3: flash_psram_config
hardware-abstraction
:CONFIG_IDF_TARGET_ARCH_XTENSA: hlinterrupts
jtag-debugging/index
@ -42,3 +42,4 @@ API 指南
:SOC_USB_SERIAL_JTAG_SUPPORTED: usb-serial-jtag-console
:SOC_WIFI_SUPPORTED: wifi
:SOC_WIFI_SUPPORTED: wifi-security
:SOC_SUPPORT_COEXISTENCE: coexist