Merge branch 'docs/update_get-started' into 'master'

docs: updated gpio and sync up line numbers Closes DOC-3350 and DOC-3390 See merge request espressif/esp-idf!19959
2024-10-05 20:47:46 -04:00 · 2022-09-09 17:24:32 +08:00 · 2022-09-09 17:24:32 +08:00 · 3ca44d4d0f
commit 3ca44d4d0f
parent c575dec8f3 49aaea7509
9 changed files with 119 additions and 118 deletions
--- a/components/driver/include/driver/gpio.h
+++ b/components/driver/include/driver/gpio.h
@ -93,8 +93,7 @@ esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type);
 * @note ESP32: Please do not use the interrupt of GPIO36 and GPIO39 when using ADC or Wi-Fi and Bluetooth with sleep mode enabled.
 *       Please refer to the comments of `adc1_get_raw`.
 *       Please refer to Section 3.11 of <a href="https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf">ESP32 ECO and Workarounds for Bugs</a> for the description of this issue.
- *       As a workaround, call adc_power_acquire() in the app. This will result in higher power consumption (by ~1mA),
- *       but will remove the glitches on GPIO36 and GPIO39.
+
 *
 * @param  gpio_num GPIO number. If you want to enable an interrupt on e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
 *
--- a/docs/en/api-reference/peripherals/adc_continuous.rst
+++ b/docs/en/api-reference/peripherals/adc_continuous.rst
@ -200,6 +200,7 @@ Dmax    Maximum of the output ADC raw digital reading result, which is 2^bitwidt

 To do further calbration to convert the ADC raw result to voltage in mV, please refer to calibration doc :doc:`adc_calibration`.

+.. _hardware_limitations_adc_continuous:

 Hardware Limitations
 ^^^^^^^^^^^^^^^^^^^^
--- a/docs/en/api-reference/peripherals/adc_oneshot.rst
+++ b/docs/en/api-reference/peripherals/adc_oneshot.rst
@ -143,6 +143,7 @@ Read Raw Result
    ESP_ERROR_CHECK(adc_oneshot_read(adc1_handle, EXAMPLE_ADC1_CHAN1, &adc_raw[0][1]));
    ESP_LOGI(TAG, "ADC%d Channel[%d] Raw Data: %d", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN1, adc_raw[0][1]);

+.. _hardware_limitations_adc_oneshot:

 Hardware Limitations
 ^^^^^^^^^^^^^^^^^^^^
--- a/docs/en/api-reference/peripherals/gpio.rst
+++ b/docs/en/api-reference/peripherals/gpio.rst
@ -198,7 +198,8 @@ Overview
        - JTAG: GPIO12-15 are usually used for inline debug.
        - GPI: GPIO34-39 can only be set as input mode and do not have software-enabled pullup or pulldown functions.
        - TXD & RXD are usually used for flashing and debugging.
-        - ADC2: ADC2 pins cannot be used when Wi-Fi is used. So, if you are having trouble getting the value from an ADC2 GPIO while using Wi-Fi, you may consider using an ADC1 GPIO instead, which should solve your problem. For more details, please refer to `ADC limitations <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/adc.html#adc-limitations>`_.
+        - ADC2: ADC2 pins cannot be used when Wi-Fi is used. So, if you are having trouble getting the value from an ADC2 GPIO while using Wi-Fi, you may consider using an ADC1 GPIO instead, which should solve your problem. For more details, please refer to :ref:`Hardware Limitations of ADC Continuous Mode <hardware_limitations_adc_continuous>` and :ref:`Hardware Limitations of ADC Oneshot Mode <hardware_limitations_adc_oneshot>`.
+        - Please do not use the interrupt of GPIO36 and GPIO39 when using ADC or Wi-Fi and Bluetooth with sleep mode enabled. Please refer to `ESP32 ECO and Workarounds for Bugs <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>`_ > Section 3.11 for the detailed description of the issue.


 .. only:: esp32s2
--- a/docs/en/hw-reference/esp32/user-guide-devkitm-1.rst
+++ b/docs/en/hw-reference/esp32/user-guide-devkitm-1.rst
@ -329,4 +329,4 @@ Related Documents
 * `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
 * `ESP Product Selector <https://products.espressif.com/#/product-selector?names=>`_

-For other design documentation for the board, please contact us at sales@espressif.com.
+For other design documentation for the board, please contact us at sales@espressif.com.
--- a/docs/zh_CN/api-guides/wifi.rst
+++ b/docs/zh_CN/api-guides/wifi.rst
@ -9,7 +9,7 @@

 .. only:: esp32 or esp32s2 or esp32c3 or esp32s3

-    - 支持 4 个虚拟接口，即STA、AP、Sniffer 和 reserved。
+    - 支持 4 个虚拟接口，即 STA、AP、Sniffer 和 reserved。
    - 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
    - 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n 和 API 配置协议模式
    - 支持 WPA/WPA2/WPA3/WPA2-企业版/WPA3-企业版/WAPI/WPS 和 DPP
@ -1395,6 +1395,7 @@ Wi-Fi 国家/地区代码
     - 该 station 与 station 模式、WIFI_COUNTRY_POLICY_MANUAL 策略下使用的国家/地区信息相同。
       该 AP 与 AP 模式、WIFI_COUNTRY_POLICY_MANUAL 策略下使用的国家/地区信息相同。

+
 主信道
 *************************

@ -1542,7 +1543,7 @@ AP 睡眠
         - iperf example
         - 15575346

-    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:` 示例/wifi/iperf/sdkconfig.defaults.esp32`。
+    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32`。

 .. only:: esp32s2

@ -1586,7 +1587,7 @@ AP 睡眠
          - iperf example
          - 15575346

-    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:` 示例/wifi/iperf/sdkconfig.defaults.esp32s2`。
+    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32s2`。

 .. only:: esp32c3

@ -1630,7 +1631,7 @@ AP 睡眠
          - iperf example
          - 15575346

-    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:` 示例/wifi/iperf/sdkconfig.defaults.esp32c3`。
+    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32c3`。

 .. only:: esp32s3

@ -1674,7 +1675,7 @@ AP 睡眠
          - iperf example
          - 15575346

-    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:` 示例/wifi/iperf/sdkconfig.defaults.esp32s3`。
+    使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32s3`。

 Wi-Fi 80211 数据包发送
 ---------------------------
--- a/docs/zh_CN/api-reference/peripherals/gpio.rst
+++ b/docs/zh_CN/api-reference/peripherals/gpio.rst
@ -198,7 +198,8 @@ GPIO & RTC GPIO
        - JTAG：GPIO12-15 通常用于在线调试。
        - GPI：GPIO34-39 只能设置为输入模式，不具备软件使能的上拉或下拉功能。
        - TXD & RXD 通常用于烧录和调试。
-        - ADC2：使用 Wi-Fi 时不能使用 ADC2 管脚。因此，如果您在使用 Wi-Fi 时无法从 ADC2 GPIO 获取值，可以考虑使用 ADC1 GPIO 来解决该问题。更多详情请参考 `ADC 限制 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/adc.html#adc-limitations>`_。
+        - ADC2：使用 Wi-Fi 时不能使用 ADC2 管脚。因此，如果您在使用 Wi-Fi 时无法从 ADC2 GPIO 获取值，可以考虑使用 ADC1 GPIO 来解决该问题。更多详情请参考 :ref:`ADC 连续转换模式下的硬件限制 <hardware_limitations_adc_continuous>` 以及 :ref:`ADC 单次转换模式下的硬件限制<hardware_limitations_adc_oneshot>`。
+        - 使用 ADC 或睡眠模式下使用 Wi-Fi 和蓝牙时，请不要使用 GPIO36 和 GPIO39 的中断。有关问题的详细描述，请参考 `ESP32 ECO 和 Bug 解决方法 <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_cn.pdf>`_ > 中的第 3.11 节。


 .. only:: esp32s2
--- a/docs/zh_CN/get-started/linux-macos-setup.rst
+++ b/docs/zh_CN/get-started/linux-macos-setup.rst
@ -189,7 +189,6 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。

    可运行您电脑 Python 文件夹中的 ``Install Certificates.command`` 安装证书。了解更多信息，请参考 `安装 ESP-IDF 工具时出现的下载错误 <https://github.com/espressif/esp-idf/issues/4775>`_。

-
 下载工具备选方案
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

--- a/docs/zh_CN/hw-reference/esp32/user-guide-devkitm-1.rst
+++ b/docs/zh_CN/hw-reference/esp32/user-guide-devkitm-1.rst
@ -10,9 +10,9 @@ ESP32-DevKitM-1 是乐鑫推出的一款基于 ESP32-MINI-1(1U) 模组的入门


 +------------------------+-------------------------+
-| |ESP32-DevKitM-1-正面| | |ESP32-DevKitM-1-侧面|  | 
+| |ESP32-DevKitM-1-正面| | |ESP32-DevKitM-1-侧面|  |
 +------------------------+-------------------------+
-|  ESP32-DevKitM-1-正面  |  ESP32-DevKitM-1-侧面   | 
+|  ESP32-DevKitM-1-正面  |  ESP32-DevKitM-1-侧面   |
 +------------------------+-------------------------+

 .. |ESP32-DevKitM-1-正面| image:: ../../../_static/esp32-DevKitM-1-front.png
@ -63,7 +63,7 @@ ESP32-DevKitM-1 开发板是一款小巧实用的开发板，具备以下特色

 批量订单请前往 https://www.espressif.com/zh-hans/contact-us/sales-questions。

-组件介绍 
+组件介绍
 -----------

 ESP32-DevKitM-1 开发板的主要组件、接口及控制方式见下图。下文以板载 ESP32-MINI-1 的开发板为例进行说明。
@ -135,10 +135,10 @@ ESP32-DevKitM-1 的主要组件和连接方式如下图所示。

 .. figure:: ../../../_static/esp32-DevKitM-1_v1_SystemBlock.png
    :align: center
-    :alt: ESP32-DevKitM-1 
+    :alt: ESP32-DevKitM-1
    :figclass: align-center

-    ESP32-DevKitM-1 
+    ESP32-DevKitM-1


 电源选项
@ -161,142 +161,142 @@ ESP32-DevKitM-1 的主要组件和连接方式如下图所示。

 开发板两侧 I/O 管脚，其具体名称和功能见下表。外设管脚分配请参考 `《ESP32 技术规格书》`_。

-.. list-table::     
-   :header-rows: 1      
-   :widths: 10 12 12 66            
-      
-      
+.. list-table::
+   :header-rows: 1
+   :widths: 10 12 12 66
+
+
   * - 编号
-     - 名称 
+     - 名称
     - 类型 [1]_
-     - 功能     
+     - 功能
   * - 1
-     - GND 
-     - P 
-     - 接地     
+     - GND
+     - P
+     - 接地
   * - 2
-     - 3V3 
-     - P 
-     - 3.3 V 电源     
+     - 3V3
+     - P
+     - 3.3 V 电源
   * - 3
-     - I36 
-     - I 
-     - GPIO36, ADC1_CH0, RTC_GPIO0      
+     - I36
+     - I
+     - GPIO36, ADC1_CH0, RTC_GPIO0
   * - 4
-     - I37 
-     - I 
-     - GPIO37, ADC1_CH1, RTC_GPIO1       
+     - I37
+     - I
+     - GPIO37, ADC1_CH1, RTC_GPIO1
   * - 5
-     - I38 
-     - I 
-     - GPIO38, ADC1_CH2, RTC_GPIO2       
+     - I38
+     - I
+     - GPIO38, ADC1_CH2, RTC_GPIO2
   * - 6
-     - I39 
-     - I 
-     - GPIO39, ADC1_CH3, RTC_GPIO3       
+     - I39
+     - I
+     - GPIO39, ADC1_CH3, RTC_GPIO3
   * - 7
     - RST
     - I
-     - 复位；高电平：使能；低电平：关闭       
+     - 复位；高电平：使能；低电平：关闭
   * - 8
-     - I34 
-     - I 
-     - GPIO34, ADC1_CH6, RTC_GPIO4       
+     - I34
+     - I
+     - GPIO34, ADC1_CH6, RTC_GPIO4
   * - 9
-     - I35 
-     - I 
-     - GPIO35, ADC1_CH7, RTC_GPIO5       
+     - I35
+     - I
+     - GPIO35, ADC1_CH7, RTC_GPIO5
   * - 10
-     - IO32 
-     - I/O 
-     - GPIO32, XTAL_32K_P (32.768 kHz crystal oscillator input), ADC1_CH4, TOUCH9, RTC_GPIO9       
+     - IO32
+     - I/O
+     - GPIO32, XTAL_32K_P (32.768 kHz crystal oscillator input), ADC1_CH4, TOUCH9, RTC_GPIO9
   * - 11
-     - IO33 
-     - I/O 
-     - GPIO33, XTAL_32K_N (32.768 kHz crystal oscillator output), ADC1_CH5, TOUCH8, RTC_GPIO8     
+     - IO33
+     - I/O
+     - GPIO33, XTAL_32K_N (32.768 kHz crystal oscillator output), ADC1_CH5, TOUCH8, RTC_GPIO8
   * - 12
-     - IO25 
-     - I/O 
-     - GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0       
+     - IO25
+     - I/O
+     - GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
   * - 13
-     - IO26 
-     - I/O 
-     - GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1       
+     - IO26
+     - I/O
+     - GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
   * - 14
-     - IO27 
-     - I/O 
-     - GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17, EMAC_RX_DV      
+     - IO27
+     - I/O
+     - GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17, EMAC_RX_DV
   * - 15
-     - IO14 
-     - I/O 
-     - GPIO14, ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK, HS2_CLK, SD_CLK, EMAC_TXD2      
+     - IO14
+     - I/O
+     - GPIO14, ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK, HS2_CLK, SD_CLK, EMAC_TXD2
   * - 16
     - 5V
-     - P 
-     - 5 V 电源      
+     - P
+     - 5 V 电源
   * - 17
-     - IO12 
-     - I/O 
-     - GPIO12, ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI [2]_, HSPIQ, HS2_DATA2, SD_DATA2, EMAC_TXD3       
+     - IO12
+     - I/O
+     - GPIO12, ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI [2]_, HSPIQ, HS2_DATA2, SD_DATA2, EMAC_TXD3
   * - 18
-     - IO13 
-     - I/O 
-     - GPIO13, ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID, HS2_DATA3, SD_DATA3, EMAC_RX_ER      
+     - IO13
+     - I/O
+     - GPIO13, ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID, HS2_DATA3, SD_DATA3, EMAC_RX_ER
   * - 19
-     - IO15 
-     - I/O 
-     - GPIO15, ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO [2]_, HSPICS0, HS2_CMD, SD_CMD, EMAC_RXD3      
+     - IO15
+     - I/O
+     - GPIO15, ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO [2]_, HSPICS0, HS2_CMD, SD_CMD, EMAC_RXD3
   * - 20
-     - IO2 
-     - I/O 
-     - GPIO2 [2]_, ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP, HS2_DATA0, SD_DATA0      
+     - IO2
+     - I/O
+     - GPIO2 [2]_, ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP, HS2_DATA0, SD_DATA0
   * - 21
-     - IO0 
-     - I/O 
-     - GPIO0 [2]_, ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1, EMAC_TX_CLK      
+     - IO0
+     - I/O
+     - GPIO0 [2]_, ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1, EMAC_TX_CLK
   * - 22
-     - IO4 
-     - I/O 
-     - GPIO4, ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD, HS2_DATA1, SD_DATA1, EMAC_TX_ER      
+     - IO4
+     - I/O
+     - GPIO4, ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD, HS2_DATA1, SD_DATA1, EMAC_TX_ER
   * - 23
-     - IO9 
-     - I/O 
-     - GPIO9, HS1_DATA2, U1RXD, SD_DATA2       
+     - IO9
+     - I/O
+     - GPIO9, HS1_DATA2, U1RXD, SD_DATA2
   * - 24
-     - IO10 
-     - I/O 
-     - GPIO10, HS1_DATA3, U1TXD, SD_DATA3     
+     - IO10
+     - I/O
+     - GPIO10, HS1_DATA3, U1TXD, SD_DATA3
   * - 25
-     - IO5 
-     - I/O 
-     - GPIO5 [2]_, HS1_DATA6, VSPICS0, EMAC_RX_CLK      
+     - IO5
+     - I/O
+     - GPIO5 [2]_, HS1_DATA6, VSPICS0, EMAC_RX_CLK
   * - 26
-     - IO18 
-     - I/O 
-     - GPIO18, HS1_DATA7, VSPICLK      
+     - IO18
+     - I/O
+     - GPIO18, HS1_DATA7, VSPICLK
   * - 27
-     - IO23 
-     - I/O 
-     - GPIO23, HS1_STROBE, VSPID       
+     - IO23
+     - I/O
+     - GPIO23, HS1_STROBE, VSPID
   * - 28
-     - IO19 
-     - I/O 
-     - GPIO19, VSPIQ, U0CTS, EMAC_TXD0       
+     - IO19
+     - I/O
+     - GPIO19, VSPIQ, U0CTS, EMAC_TXD0
   * - 29
-     - IO22 
-     - I/O 
-     - GPIO22, VSPIWP, U0RTS, EMAC_TXD1      
+     - IO22
+     - I/O
+     - GPIO22, VSPIWP, U0RTS, EMAC_TXD1
   * - 30
-     - IO21 
-     - I/O 
-     - GPIO21, VSPIHD, EMAC_TX_EN     
+     - IO21
+     - I/O
+     - GPIO21, VSPIHD, EMAC_TX_EN
   * - 31
-     - TXD0 
-     - I/O 
-     - GPIO1, U0TXD, CLK_OUT3, EMAC_RXD2      
+     - TXD0
+     - I/O
+     - GPIO1, U0TXD, CLK_OUT3, EMAC_RXD2
   * - 32
-     - RXD0 
-     - I/O 
+     - RXD0
+     - I/O
     - GPIO3, U0RXD, CLK_OUT2

 .. [1] P：电源；I：输入；O：输出。
@ -305,8 +305,6 @@ ESP32-DevKitM-1 的主要组件和连接方式如下图所示。
 管脚布局
 ^^^^^^^^

-ESP32-DevKitM-1 的主要组件和连接方式如下图所示。
-
 .. figure:: ../../../_static/ESP32_DevKitM-1_pinlayout.png
    :align: center
    :scale: 43%
@ -331,4 +329,4 @@ ESP32-DevKitM-1 的主要组件和连接方式如下图所示。
 * `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`_
 * `《ESP32 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>`_ (PDF)

-有关本开发板的更多设计文档，请联系我们的商务部门 sales@espressif.com。
+有关本开发板的更多设计文档，请联系我们的商务部门 sales@espressif.com。