alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-20 00:36:01 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'docs_add_usb_flash_procedure' into 'master'

Browse Source 
[Docs] Added procedures for the USB peripheral flashing

See merge request espressif/esp-idf!18484
This commit is contained in:
Pedro Minatel 2022-08-09 22:28:17 +08:00
commit fe2bd5cdf2
14 changed files with 502 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
docs/en/get-started/establish-serial-connection.rst
View File

@ -3,20 +3,187 @@ Establish Serial Connection with {IDF_TARGET_NAME}
:link_to_translation:`zh_CN:[中文]`
This section provides guidance how to establish serial connection between {IDF_TARGET_NAME} and PC.
.. only:: not SOC_USB_OTG_SUPPORTED and not SOC_USB_SERIAL_JTAG_SUPPORTED
Establishing a serial connection with the {IDF_TARGET_NAME} target device could be done using a USB-to-UART bridge.
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
Establishing a serial connection with the {IDF_TARGET_NAME} target device could be done using USB-to-UART bridge or USB peripheral supported in {IDF_TARGET_NAME}.
Some development boards have the USB-to-UART bridge installed. If a board does not have a bridge then an external bridge may be used.
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
Supported USB Peripheral
------------------------
The {IDF_TARGET_NAME} supports the USB peripheral. In this case, the USB-to-UART bridge is not needed and the device can be flashed directly.
.. blockdiag::
:scale: 70%
:caption: SoC with Supported USB
:align: center
blockdiag usb_capable_esp {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\n Computer"];
CHIP [label="{IDF_TARGET_NAME}", width=120];
DUMMY [shape=none, width=1]
# node connections
PC <- DUMMY [label = "USB", fontsize=14];
DUMMY -> CHIP [fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Development Board\n\n\n";
CHIP; DUMMY;
}
}
Apart from the USB peripheral, some development boards also include the USB-to-UART bridge.
USB-to-UART Bridge on Development Board
---------------------------------------
For boards with an installed USB-to-UART bridge, the connection between the personal computer and the bridge is USB and between the bridge and {IDF_TARGET_NAME} is UART.
.. blockdiag::
:caption: Development Board with USB-to-UART Bridge
:align: center
blockdiag esp_dev_board_with_usb_to_uart_bridge {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\nComputer"];
BRIDGE [label="USB-to-UART\n Bridge"];
CHIP [label="{IDF_TARGET_NAME}", width=120];
# node connections
PC <-> BRIDGE [label = "USB", fontsize=14];
BRIDGE <-> CHIP [label = "UART", fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Developmment Board\n\n\n";
BRIDGE; CHIP;
}
}
External USB-to-UART Bridge
---------------------------
Sometimes the USB-to-UART bridge is external. This is often used in small development boards or finished products when space and costs are crucial.
.. blockdiag::
:caption: External USB-to-UART Bridge
:align: center
blockdiag external_usb_to_uart_bridge_to_esp {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\n Computer"];
BRIDGE [label="USB-to-UART\n Bridge", width=180];
CHIP [label="{IDF_TARGET_NAME}", width=120];
DUMMY [shape=none, width=1]
# node connections
PC <-> BRIDGE [label = "USB", fontsize=14];
BRIDGE <- DUMMY [label = "UART", fontsize=14];
DUMMY -> CHIP [fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Programmmer Board\n\n\n";
BRIDGE
}
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Development Board\n\n\n";
CHIP; DUMMY;
}
}
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
Flash using USB
---------------
For the {IDF_TARGET_NAME}, the USB peripheral is available, allowing you to flash the binaries without the need for an external USB-to-UART bridge.
{IDF_TARGET_USB_PIN_DM:default="Not Updated!", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19"}
{IDF_TARGET_USB_PIN_DP:default="Not Updated!", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20"}
The USB on the {IDF_TARGET_NAME} uses the **{IDF_TARGET_USB_PIN_DP}** for **D+** and **{IDF_TARGET_USB_PIN_DM}** for **D-**.
.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
.. note:: The {IDF_TARGET_NAME} supports only *USB CDC and JTAG*.
If you are flashing for the first time, you need to get the {IDF_TARGET_NAME} into the download mode manually. To do so, press and hold the ``BOOT`` button and then press the ``RESET`` button once. After that release the ``BOOT`` button.
.. only:: esp32s2
After flashing the binaries, a manual reset is needed.
Flash using UART
----------------
This section provides guidance on how to establish a serial connection between {IDF_TARGET_NAME} and PC using USB-to-UART Bridge, either installed on the development board or external.
Connect {IDF_TARGET_NAME} to PC
----------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them.
Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB-to-UART bridge on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them.
Below is the list of USB to serial converter chips installed on most of the {IDF_TARGET_NAME} boards produced by Espressif together with links to the drivers:
* CP210x: `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers>`_
* FTDI: `FTDI Virtual COM Port Drivers <https://ftdichip.com/drivers/vcp-drivers/>`_
Please check the board user guide for specific USB to serial converter chip used. The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with an operating system and automatically installed upon connecting the board to the PC.
Please check the board user guide for specific USB-to-UART bridge chip used. The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with an operating system and automatically installed upon connecting the board to the PC.
For devices downloaded using a USB-to-UART bridge, you can run the following command including the optional argument to define the baud rate.
.. code-block:: bash
idf.py -p PORT [-b BAUD] flash
You can change the flasher baud rate by replacing ``BAUD`` with the baud rate you need. The default baud rate is ``460800``.
.. note::
If the device does not support the auto download mode, you need to get into the download mode manually. To do so, press and hold the ``BOOT`` button and then press the ``RESET`` button once. After that release the ``BOOT`` button.
Check port on Windows
---------------------
@ -39,7 +206,6 @@ Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
Check port on Linux and macOS
-----------------------------
@ -57,7 +223,6 @@ macOS ::
macOS users: if you don't see the serial port then check you have the USB/serial drivers installed. See Section `Connect {IDF_TARGET_NAME} to PC`_ for links to drivers. For macOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
.. _linux-dialout-group:
Adding user to ``dialout`` on Linux
@ -73,7 +238,6 @@ on Arch Linux this is done by adding the user to ``uucp`` group with the followi
Make sure you re-login to enable read and write permissions for the serial port.
Verify serial connection
------------------------
@ -100,7 +264,6 @@ Run terminal, set identified serial port, baud rate = 115200, data bits = 8, sto
Setting Serial Communication in PuTTY on Linux
Then open serial port in terminal and check, if you see any log printed out by {IDF_TARGET_NAME}. The log contents will depend on application loaded to {IDF_TARGET_NAME}, see `Example Output`_.
.. note::
@ -108,7 +271,7 @@ Then open serial port in terminal and check, if you see any log printed out by {
Close the serial terminal after verification that communication is working. If you keep the terminal session open, the serial port will be inaccessible for uploading firmware later.
macOS
^^^^^^^^
^^^^^
To spare you the trouble of installing a serial terminal program, macOS offers the **screen** command.
@ -132,7 +295,6 @@ To spare you the trouble of installing a serial terminal program, macOS offers t
Do not forget to **exit the screen session** after verifying that the communication is working. If you fail to do it and just close the terminal window, the serial port will be inaccessible for uploading firmware later.
Example Output
^^^^^^^^^^^^^^
@ -158,7 +320,6 @@ An example log is shown below. Reset the board if you do not see anything.
entry 0x40080034
I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
I (45) boot: compile time 18:48:10
...
If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to {IDF_TARGET_NAME}.

24
docs/en/get-started/flashing-troubleshooting.rst Normal file
View File

@ -0,0 +1,24 @@
Flashing Troubleshooting
========================
:link_to_translation:`zh_CN:[中文]`
Failed to Connect
-----------------
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is to manually reset as described below. If it does not help, you can find more details about possible issues in the `esptool troubleshooting <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ page.
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB-to-UART bridge, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
In general, you should have no problems with the `official esp-idf development boards <https://www.espressif.com/en/products/devkits>`_. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``.
- The DTR and RTS lines are configured differently.
- There are no such serial control lines at all.
Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an ESP-IDF development board, hold down the ``Boot`` button (``{IDF_TARGET_STRAP_GPIO}``) and press the ``EN`` button (``CHIP_PU``).
- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_GPIO}`` down.

1
docs/en/get-started/linux-macos-setup.rst
View File

@ -284,6 +284,7 @@ Related Documents
:maxdepth: 1
establish-serial-connection
flashing-troubleshooting
../api-guides/tools/idf-monitor
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

17
docs/en/get-started/linux-macos-start-project.rst
View File

@ -76,3 +76,20 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
.. only:: esp32 or esp32s2 or esp32s3
If you are using one of the supported development boards, you can speed up your development by using Board Support Package. See `Additional Tips <#additional-tips>`__ for more information.
.. only:: esp32s2
Console Output Configuration
----------------------------
If you are using the USB for flashing the {IDF_TARGET_NAME}, you need to change the channel for the console output from UART (default) to USB.
1. Navigate to the option ``Channel for console output``.
``Component config`` > ``ESP System Settings`` > ``Channel for console output``
2. Change to the option (the default will be always UART):
``USB CDC``
3. Save the new configuration and exit the ``menuconfig`` screen.

47
docs/en/get-started/start-project.rst
View File

@ -41,41 +41,21 @@ If there are no errors, the build will finish by generating the firmware binary
Flash onto the Device
=====================
Flash the binaries that you just built (bootloader.bin, partition-table.bin and hello_world.bin) onto your {IDF_TARGET_NAME} board by running:
To flash the binaries that you just built for the {IDF_TARGET_NAME} in the previous step, you need to run the following command:
.. code-block:: bash
idf.py -p PORT [-b BAUD] flash
idf.py -p PORT flash
Replace PORT with your {IDF_TARGET_NAME} board's serial port name.
Replace ``PORT`` with your {IDF_TARGET_NAME} board's USB port name. If the ``PORT`` is not defined, the :ref:`idf.py` will try to connect automatically using the available USB ports.
You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``.
For more information on idf.py arguments, see :ref:`idf.py`.
For more information on ``idf.py`` arguments, see :ref:`idf.py`.
.. note::
The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary.
Encountered Issues While Flashing?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset described below, and if it does not help you can find more details about possible issues in `Troubleshooting <https://github.com/espressif/esptool#bootloader-wont-respond>`_.
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
In general, you should have no problems with the `official esp-idf development boards <https://www.espressif.com/en/products/devkits>`_. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``
- The DTR and RTS lines are configured differently
- There are no such serial control lines at all
Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an ESP-IDF development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_GPIO}``) and press the **EN** button (``CHIP_PU``).
- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_GPIO}`` down.
Encountered Issues While Flashing? See this :doc:`flashing-troubleshooting` page or :doc:`establish-serial-connection` for more detailed information.
Normal Operation
~~~~~~~~~~~~~~~~
@ -428,3 +408,20 @@ ESP-IDF supports Python 3.7 or newer. It is recommended to upgrade your operatin
idf.py add-dependency esp-box
More examples of BSP usage can be found in `BSP examples folder <https://github.com/espressif/esp-bsp/tree/master/examples>`_.
Flash Erase
~~~~~~~~~~~
Erasing the flash is also possible. To erase the entire flash memory you can run the following command:
.. code-block:: bash
idf.py -p PORT erase-flash
For erasing the OTA data, if present, you can run this command:
.. code-block:: bash
idf.py -p PORT erase-otadata
The flash erase command can take a while to be done. Do not disconnect your device while the flash erasing is in progress.

1
docs/en/get-started/windows-setup.rst
View File

@ -131,6 +131,7 @@ For advanced users who want to customize the install process:
windows-setup-update
establish-serial-connection
flashing-troubleshooting
../api-guides/tools/idf-monitor
.. _CMake: https://cmake.org/download/

14
docs/en/get-started/windows-start-project.rst
View File

@ -76,3 +76,17 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
.. only:: esp32 or esp32s2 or esp32s3
If you are using one of the supported development boards, you can speed up your development by using Board Support Package. See `Additional Tips <#additional-tips>`__ for more information.
.. only:: esp32s2
To use the USB for flashing the {IDF_TARGET_NAME}, you need to change the channel for the console output to USB. For the {IDF_TARGET_NAME}, the default console output channel is the UART.
1. Navigate to the option ``Channel for console output``.
``Component config ---> ESP System Settings ---> Channel for console output``
2. Change to the option (the default will be always UART):
``USB CDC``
3. Save the new configuration and exit the ``menuconfig`` screen.

181
docs/zh_CN/get-started/establish-serial-connection.rst
View File

@ -3,20 +3,187 @@
:link_to_translation:`en:[English]`
本章节主要介绍如何创建 {IDF_TARGET_NAME} 和 PC 之间的串口连接。
.. only:: not SOC_USB_OTG_SUPPORTED and not SOC_USB_SERIAL_JTAG_SUPPORTED
可以使用 USB 至 UART 桥，与 {IDF_TARGET_NAME} 创建串口连接。
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
可以使用 USB 至 UART 桥或 {IDF_TARGET_NAME} 支持的 USB 外设，与 {IDF_TARGET_NAME} 创建串口连接。
部分开发板中已经安装有 USB 至 UART 桥。如未安装，可使用外部桥。
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
支持的 USB 外设
------------------------
{IDF_TARGET_NAME} 支持 USB 外设。无需 USB 至 UART 桥，便可直接烧录设备。
.. blockdiag::
:scale: 70%
:caption: 支持 USB 的 SoC
:align: center
blockdiag usb_capable_esp {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\n Computer"];
CHIP [label="{IDF_TARGET_NAME}", width=120];
DUMMY [shape=none, width=1]
# node connections
PC <- DUMMY [label = "USB", fontsize=14];
DUMMY -> CHIP [fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Development Board\n\n\n";
CHIP; DUMMY;
}
}
部分支持 USB 外设的开发板同时也包含 USB 至 UART 桥。
安装有 USB 至 UART 桥的开发板
---------------------------------------
在安装有 USB 至 UART 桥的开发板中，PC 和桥之间通过 USB 连接，桥和 {IDF_TARGET_NAME} 之间通过 UART 连接。
.. blockdiag::
:caption: 安装有 USB 至 UART 桥的开发板
:align: center
blockdiag esp_dev_board_with_usb_to_uart_bridge {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\nComputer"];
BRIDGE [label="USB-to-UART\n Bridge"];
CHIP [label="{IDF_TARGET_NAME}", width=120];
# node connections
PC <-> BRIDGE [label = "USB", fontsize=14];
BRIDGE <-> CHIP [label = "UART", fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Developmment Board\n\n\n";
BRIDGE; CHIP;
}
}
外部 USB 至 UART 桥
---------------------------
部分开发板使用外部 USB 至 UART 桥。这种情况通常出现在需要控制空间和成本的产品中，例如一些小型开发板或成品。
.. blockdiag::
:caption: 外部 USB 至 UART 桥
:align: center
blockdiag external_usb_to_uart_bridge_to_esp {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\n Computer"];
BRIDGE [label="USB-to-UART\n Bridge", width=180];
CHIP [label="{IDF_TARGET_NAME}", width=120];
DUMMY [shape=none, width=1]
# node connections
PC <-> BRIDGE [label = "USB", fontsize=14];
BRIDGE <- DUMMY [label = "UART", fontsize=14];
DUMMY -> CHIP [fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Programmmer Board\n\n\n";
BRIDGE
}
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Development Board\n\n\n";
CHIP; DUMMY;
}
}
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
使用 USB 进行烧录
------------------
{IDF_TARGET_NAME} 支持 USB 外设，无需外部 USB 至 UART 桥，即可烧录二进制文件。
{IDF_TARGET_USB_PIN_DM:default="尚未更新！", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19"}
{IDF_TARGET_USB_PIN_DP:default="尚未更新！", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20"}
{IDF_TARGET_NAME} 上的 USB 使用 **{IDF_TARGET_USB_PIN_DP}** 作为 **D+**， **{IDF_TARGET_USB_PIN_DM}** 作为 **D-**。
.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
.. note:: {IDF_TARGET_NAME} 仅支持 *USB CDC and JTAG*。
首次烧录需要手动设置 {IDF_TARGET_NAME} 进入下载模式。请按住 ``BOOT`` 按钮，同时按一下 ``RESET`` 按钮。之后，松开 ``BOOT`` 按钮。
.. only:: esp32s2
二进制文件烧录完成后，需要手动进行复位。
使用 UART 进行烧录
---------------------
本节描述如何使用 USB 至 UART 桥在 {IDF_TARGET_NAME} 和 PC 之间建立串行连接。板上桥与外部桥均适用。
连接 {IDF_TARGET_NAME} 和 PC
------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
用 USB 线将 {IDF_TARGET_NAME} 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 {IDF_TARGET_NAME} 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。
用 USB 线将 {IDF_TARGET_NAME} 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 {IDF_TARGET_NAME} 开发板上的 USB 至 UART 桥（或外部转 UART 适配器）型号，然后在网上搜索驱动程序，并进行手动安装。
以下是乐鑫 {IDF_TARGET_NAME} 开发板驱动程序的链接：
* CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 <https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers>`_
* FTDI: `FTDI 虚拟 COM 端口驱动程序 <https://ftdichip.com/drivers/vcp-drivers/>`_
以上驱动仅供参考，请参考开发板用户指南，查看开发板具体使用的 USB 转串口芯片。一般情况下，当 {IDF_TARGET_NAME} 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。
以上驱动仅供参考，请查看开发板用户指南，了解开发板具体使用的 USB 至 UART 桥芯片。一般情况下，当 {IDF_TARGET_NAME} 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。
对于使用 USB 至 UART 桥下载的设备，您可以运行以下命令，包括定义波特率的可选参数。
.. code-block:: bash
idf.py -p PORT [-b BAUD] flash
如需改变烧录器的波特率，请用需要的波特率代替 ``BAUD``。默认的波特率为 ``460800``。
.. note::
如果设备不支持自动下载模式，则需要手动进入下载模式。请按住 ``BOOT`` 按钮，同时按一下 ``RESET`` 按钮。之后，松开 ``BOOT`` 按钮。
在 Windows 上查看端口
---------------------
@ -39,7 +206,6 @@
Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
在 Linux 和 macOS 上查看端口
-----------------------------
@ -57,7 +223,6 @@ macOS::
对于 macOS 用户：若没有看到串口，请检查是否安装 USB/串口驱动程序。具体应使用的驱动程序，见章节 `连接 {IDF_TARGET_NAME} 和 PC`_。对于 macOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。
.. _linux-dialout-group:
在 Linux 中添加用户到 ``dialout``
@ -73,7 +238,6 @@ macOS::
请重新登录，确保串口读写权限生效。
确认串口连接
------------------------
@ -100,7 +264,6 @@ Windows 和 Linux 操作系统
在 Linux 操作系统中使用 PuTTY 设置串口通信参数
然后，请检查 {IDF_TARGET_NAME} 是否有打印日志。如有，请在终端打开串口进行查看。这里的日志内容取决于加载到 {IDF_TARGET_NAME} 的应用程序，请参考 `输出示例`_。
.. 注解::
@ -132,7 +295,6 @@ macOS 提供了 **屏幕** 命令，因此您不用安装串口终端程序。
请在验证完串口通信正常后，关闭 **屏幕** 会话。如果直接关闭终端窗口而没有关闭 **屏幕**，之后上传固件时将无法访问串口。
输出示例
^^^^^^^^^^^
@ -158,7 +320,6 @@ macOS 提供了 **屏幕** 命令，因此您不用安装串口终端程序。
entry 0x40080034
I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
I (45) boot: compile time 18:48:10
...
如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，您可以继续进行安装，并最终将应用程序上载到 {IDF_TARGET_NAME}。

24
docs/zh_CN/get-started/flashing-troubleshooting.rst Normal file
View File

@ -0,0 +1,24 @@
烧录故障排除
========================
:link_to_translation:`en:[English]`
连接失败
-----------------
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
如果在运行给定命令时出现如“连接失败”这样的错误，造成该错误的原因之一可能是运行 ``esptool.py`` 时出现错误。 ``esptool.py`` 是构建系统调用的程序，用于重置芯片、与 ROM 引导加载器交互以及烧录固件的工具。可以按照以下步骤进行手动复位，轻松解决该问题。如果问题仍未解决，请参考 `esptool 故障排除 <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ 获取更多信息。
``esptool.py`` 通过使 USB 至 UART 桥（如 FTDI 或 CP210x）的 DTR 和 RTS 控制线生效来自动复位 {IDF_TARGET_NAME}（请参考 :doc:`establish-serial-connection` 获取更多详细信息）。DTR 和 RTS 控制线又连接到 {IDF_TARGET_NAME} 的 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CHIP_PU`` (EN) 管脚上，因此 DTR 和 RTS 的电压电平变化会使 {IDF_TARGET_NAME} 进入固件下载模式。相关示例可查看 ESP32 DevKitC 开发板的 `原理图 <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_。
一般来说，使用官方的 ESP-IDF 开发板不会出现问题。但是， ``esptool.py`` 在以下情况下不能自动重置硬件：
- 您的硬件没有连接到 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CIHP_PU`` 的 DTR 和 RTS 控制线。
- DTR 和 RTS 控制线的配置方式不同。
- 不存在这样的串行控制线路。
根据硬件的种类，也可以将您的 {IDF_TARGET_NAME} 开发板手动设置为固件下载模式（复位）。
- 对于乐鑫开发板，您可以参考对应开发板的入门指南或用户指南。例如，可以通过按住 ``Boot`` 按钮 (``{IDF_TARGET_STRAP_GPIO}``) 再按住 ``EN`` 按钮 (``CHIP_PU``) 来手动复位 ESP-IDF 开发板。
- 对于其他类型的硬件，可以尝试将 ``{IDF_TARGET_STRAP_GPIO}`` 拉低。

1
docs/zh_CN/get-started/linux-macos-setup.rst
View File

@ -285,6 +285,7 @@ ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具，
:maxdepth: 1
establish-serial-connection
flashing-troubleshooting
../api-guides/tools/idf-monitor
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

20
docs/zh_CN/get-started/linux-macos-start-project.rst
View File

@ -75,4 +75,22 @@
.. only:: esp32 or esp32s2 or esp32s3
如果您使用的是支持的开发板，可以通过板级支持包 (BSP) 来协助您的开发。更多信息，请见 `其他提示 <#additional-tips>`__。
如果您使用的是支持的开发板，可以通过板级支持包 (BSP) 来协助您的开发。更多信息，请见 `其他提示 <#additional-tips>`__。
.. only:: esp32s2
控制台输出配置
----------------------------
如需使用 USB 烧录 {IDF_TARGET_NAME}，请将控制台的输出通道改为 USB。对于 {IDF_TARGET_NAME}，默认的控制台输出通道为 UART。
1. 前往选项 ``Channel for console output``。
``Component config`` > ``ESP System Settings`` > ``Channel for console output``
2. 将默认选项 UART 改为：
``USB CDC``
3. 保存设置，退出 ``menuconfig`` 界面。

45
docs/zh_CN/get-started/start-project.rst
View File

@ -41,15 +41,13 @@
烧录到设备
=============================
请使用以下命令，将刚刚生成的二进制文件 (bootloader.bin、partition-table.bin 和 hello_world.bin) 烧录至您的 {IDF_TARGET_NAME} 开发板：
请运行以下命令，将刚刚生成的二进制文件烧录至您的 {IDF_TARGET_NAME} 开发板：
.. code-block:: bash
idf.py -p PORT [-b BAUD] flash
idf.py -p PORT flash
请将 PORT 替换为 {IDF_TARGET_NAME} 开发板的串口名称。
您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
请将 PORT 替换为 {IDF_TARGET_NAME} 开发板的串口名称。如果 ``PORT`` 未经定义，:ref:`idf.py` 将尝试使用可用的串口自动连接。
更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。
@ -57,25 +55,7 @@
勾选 ``flash`` 选项将自动编译并烧录工程，因此无需再运行 ``idf.py build``。
烧录过程中可能遇到的问题
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
如果在运行给定命令时出现如“连接失败”这样的错误，造成该错误的原因之一可能是运行 ``esptool.py`` 时出现错误。``esptool.py`` 是构建系统调用的程序，用于重置芯片、与 ROM 引导加载器交互以及烧录固件的工具。可以按照以下步骤进行手动复位，轻松解决该问题。如果问题仍未解决，请参考 `Troubleshooting <https://github.com/espressif/esptool#bootloader-wont-respond>`_. 获取更多信息。
``esptool.py`` 通过使 USB 转串口转接器芯片（如 FTDI 或 CP210x）的 DTR 和 RTS 控制线生效来自动复位 {IDF_TARGET_NAME}（请参考 :doc:`establish-serial-connection` 获取更多详细信息)。DTR 和 RTS 控制线又连接到 {IDF_TARGET_NAME} 的 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CHIP_PU`` (EN) 管脚上，因此 DTR 和 RTS 的电压电平变化会使 {IDF_TARGET_NAME} 进入固件下载模式。相关示例可查看 ESP32 DevKitC 开发板的 `原理图 <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_。
一般来说，使用官方的 ESP-IDF 开发板不会出现问题。但是，``esptool.py`` 在以下情况下不能自动重置硬件。
- 您的硬件没有连接到 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CIHP_PU`` 的 DTR 和 RTS 控制线。
- DTR 和 RTS 控制线的配置方式不同
- 根本没有这样的串行控制线路
根据您硬件的种类，也可以将您 {IDF_TARGET_NAME} 开发板手动设置成固件下载模式（复位）。
- 对于 Espressif 的开发板，您可以参考对应开发板的入门指南或用户指南。例如，可以通过按住 **Boot** 按钮 (``{IDF_TARGET_STRAP_GPIO}``) 再按住 **EN** 按钮(``CHIP_PU``) 来手动复位 ESP-IDF 开发板。
- 对于其他类型的硬件，可以尝试将 ``{IDF_TARGET_STRAP_GPIO}`` 拉低。
若在烧录过程中遇到问题，请前往 :doc:`flashing-troubleshooting` 或 :doc:`establish-serial-connection` 获取更多详细信息。
常规操作
~~~~~~~~~~~~~~~~
@ -428,3 +408,20 @@ ESP-IDF 支持 Python 3.7 及以上版本，建议升级操作系统到最新版
idf.py add-dependency esp-box
更多有关使用 BSP 的示例，请前往 `BSP 示例文件夹 <https://github.com/espressif/esp-bsp/tree/master/examples>`_。
擦除 flash
~~~~~~~~~~~
ESP-IDF 支持擦除 flash。请运行以下命令，擦除整个 flash：
.. code-block:: bash
idf.py -p PORT erase-flash
若存在需要擦除的 OTA 数据，请运行以下命令：
.. code-block:: bash
idf.py -p PORT erase-otadata
擦除 flash 需要一段时间，在擦除过程中，请勿断开设备连接。

1
docs/zh_CN/get-started/windows-setup.rst
View File

@ -131,6 +131,7 @@ ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF
windows-setup-update
establish-serial-connection
flashing-troubleshooting
../api-guides/tools/idf-monitor
.. _CMake: https://cmake.org/download/

15
docs/zh_CN/get-started/windows-start-project.rst
View File

@ -76,4 +76,17 @@ Windows
.. only:: esp32 or esp32s2 or esp32s3
如果您使用的是支持的开发板，可以通过板级支持包 (BSP) 来协助您的开发。更多信息，请见 `其他提示 <#additional-tips>`__。
.. only:: esp32s2
如需使用 USB 烧录 {IDF_TARGET_NAME}，请将控制台的输出通道改为 USB。对于 {IDF_TARGET_NAME}，默认的控制台输出通道为 UART。
1. 前往选项 ``Channel for console output``。
``Component config ---> ESP System Settings ---> Channel for console output``
2. 将默认选项 UART 改为：
``USB CDC``
3. 保存设置，退出 ``menuconfig`` 界面。