diff --git a/docs_espressif/en/buildproject.rst b/docs_espressif/en/buildproject.rst index 78f7662da..768b6a639 100644 --- a/docs_espressif/en/buildproject.rst +++ b/docs_espressif/en/buildproject.rst @@ -1,25 +1,26 @@ -Build the Project -=============================== +.. _build the project: -1. Build the project: +Build Your Project +================== -- Navigate to **View** > **Command Palette**. +:link_to_translation:`zh_CN:[中文]` -- Type **ESP-IDF: Build your Project** and select the command to build the project. +1. Build your project: Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Build your Project`` and choose the command to build the project. -2. A new terminal being launched with the build output and a notification bar with Building Project message until it is done then a Build done message when finished. +2. A new terminal will open with the build output. A notification bar will display the "Building project" message, followed by a "Building done" message when the process is complete. -.. image:: ../../media/tutorials/basic_use/build.png + .. image:: ../../media/tutorials/basic_use/build.png -.. note:: - There is a **idf.notificationMode** configuration setting if you do not want to see the output automatically. Please review `ESP-IDF Settings <settings>` to see how to modify this configuration setting. + .. note:: -You could modify the behavior of the build task with **idf.cmakeCompilerArgs** for Cmake configure step and **idf.ninjaArgs** for Ninja step. For example, using ``idf.ninjaArgs: [-j N]`` where N is the number of jobs run in parallel. + There is an ``idf.notificationMode`` configuration setting if you prefer not to see the output automatically. Please refer to :ref:`ESP-IDF Settings <settings>` to learn how to modify this configuration. -3. After building the application, the size analysis task will be executed in a terminal, showing the binaries size analysis results. You can enable or disable this task being executed with **idf.enableSizeTaskAfterBuildTask** in your settings.json. + You can adjust the behavior of the build task with ``idf.cmakeCompilerArgs`` for the Cmake configure step and ``idf.ninjaArgs`` for the Ninja step. For example, use ``idf.ninjaArgs: [-j N]`` where **N** is the number of jobs to run in parallel. -.. image:: ../../media/tutorials/basic_use/size_terminal.png +3. After building the application, the size analysis task will run in a terminal, showing the binary size analysis results. You can enable or disable this task with ``idf.enableSizeTaskAfterBuildTask`` in the ``settings.json``. -ESP-IDF build output will try to suggest hints to solve errors that can be shown using the :ref:`Hints viewer <hints viewer>`. + .. image:: ../../media/tutorials/basic_use/size_terminal.png -Next step is to :ref:`Flash onto the device <flash the device>`. \ No newline at end of file +The ESP-IDF build output will provide hints to resolve errors, which can be viewed using the :ref:`Hints Viewer <hints viewer>`. + +Next, proceed to :ref:`Flash onto the Device <flash the device>`. diff --git a/docs_espressif/en/configureproject.rst b/docs_espressif/en/configureproject.rst index 191cd16f7..d5414b058 100644 --- a/docs_espressif/en/configureproject.rst +++ b/docs_espressif/en/configureproject.rst @@ -1,57 +1,63 @@ +.. _configure_your_project: + Configure Your Project -=============================== +====================== + +:link_to_translation:`zh_CN:[中文]` -Select an Espressif target (esp32, esp32s2, etc.) by selecting menu **View** > **Command Palette** and typing **ESP-IDF: Set Espressif Device Target** command. +Select an Espressif target (esp32, esp32s2, etc.) by going to ``View`` > ``Command Palette`` and entering ``ESP-IDF: Set Espressif Device Target`` command. -Select menu **View** > **Command Palette** and type the **ESP-IDF: Select OpenOCD Board Configuration** to choose the openOCD configuration files for the extension openOCD server. +Go to ``View`` > ``Command Palette`` and enter ``ESP-IDF: Select OpenOCD Board Configuration`` to choose the openOCD configuration files for the extension openOCD server. .. note:: - * Please review `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to understand which board or configuration to use for your specific hardware. -Next configure your project. Select menu **View** > **Command Palette** and type **ESP-IDF: SDK Configuration Editor** command ESP-IDF project settings. + Please refer to `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to select the appropriate OpenOCD configuration file based on your hardware. + +Next, configure your project. Go to ``View`` > ``Command Palette`` and enter ``ESP-IDF: SDK Configuration Editor`` to adjust ESP-IDF project settings. .. image:: ../../media/tutorials/basic_use/gui_menuconfig.png -After all changes are made, click save and close this window. +After making changes, click ``save`` and close the window. -Next step is to :ref:`Build the project <build the project>`. +Next, proceed to :ref:`Build Your project <build the project>`. -C and C++ Code navigation and syntax highlight ------------------------------------------------------ +C and C++ Code Navigation and Syntax Highlighting +------------------------------------------------- .. note:: - * C and C++ code navigation doesn't need to be configured if you create the project as described in :ref:`Configure your project <configure your project>` as these commands will create the ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json`` file. -For code navigation and C/C++ syntax highlight you could use either the `Microsoft C/C++ Extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_, `LLVM CLangd extension <https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_ or any other extension you desire. + C and C++ code navigation is automatically configured if you create the project as described in :ref:`Configure Your Project <configure_your_project>`. Those commands generate the ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json`` file. + +For code navigation and C/C++ syntax highlighting, you can use `Microsoft C/C++ extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_, `LLVM clangd extension <https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_, or any other preferred extension. -Usually C/C++ language extensions rely on a file called ``compile_commands.json`` which is located on your project build directory. You can generate this file using the **ESP-IDF: Run idf.py reconfigure task**. +Usually C/C++ language extensions rely on a file called ``compile_commands.json``, which is located in your project build directory. You can generate this file using the ``ESP-IDF: Run idf.py reconfigure task``. -For LLVM CLangd extension, only the compile_commands.json is needed. For Microsoft C/C++ extension, a configuration file is located in ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json`` and can be generated by creating a project using **ESP-IDF: New Project**, **ESP-IDF: Show Examples Projects** command or using the **ESP-IDF: Add .vscode Configuration Folder** command on an existing ESP-IDF projects. +For LLVM clangd extension, only ``compile_commands.json`` is needed. For Microsoft C/C++ extension, a configuration file is located at ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json``. This file can be generated by creating a project using ``ESP-IDF: New Project``, ``ESP-IDF: Show Example Projects`` command, or by using the ``ESP-IDF: Add .vscode Configuration Folder`` command on an existing ESP-IDF projects. -The file looks like this: +The file structure is as follows: .. code-block:: JSON - { - "configurations": [ - { - "name": "ESP-IDF", - "compilerPath": "/path/to/toolchain-gcc", - "compileCommands": "${workspaceFolder}/build/compile_commands.json", - "includePath": [ - "${config:idf.espIdfPath}/components/**", - "${config:idf.espIdfPathWin}/components/**", - "${workspaceFolder}/**" - ], - "browse": { - "path": [ - "${config:idf.espIdfPath}/components", - "${config:idf.espIdfPathWin}/components", - "${workspaceFolder}" - ] - } - } - ] - } - -If ``compile_commands.json`` is not defined, the Microsoft C/C++ extension will browse the provided ESP-IDF path to provide code navigation resolution. + { + "configurations": [ + { + "name": "ESP-IDF", + "compilerPath": "/path/to/toolchain-gcc", + "compileCommands": "${workspaceFolder}/build/compile_commands.json", + "includePath": [ + "${config:idf.espIdfPath}/components", + "${config:idf.espIdfPathWin}/components/", + "${workspaceFolder}/" + ], + "browse": { + "path": [ + "${config:idf.espIdfPath}/components", + "${config:idf.espIdfPathWin}/components", + "${workspaceFolder}" + ] + } + } + ] + } + +If ``compile_commands.json`` is not defined, Microsoft C/C++ extension will browse the provided ESP-IDF path to resolve code navigation. diff --git a/docs_espressif/en/connectdevice.rst b/docs_espressif/en/connectdevice.rst index f3f221623..5a22d4aed 100644 --- a/docs_espressif/en/connectdevice.rst +++ b/docs_espressif/en/connectdevice.rst @@ -1,10 +1,12 @@ .. _connectdevice: Connect Your Device -=============================== +=================== -In Visual Studio Code, select menu **View** > **Command Palette** and type **ESP-IDF: Select Port to Use:** and choose the serial port that your device is connected. +:link_to_translation:`zh_CN:[中文]` -Please review `Establish serial communication <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_ if you are not sure about the serial port name. +In Visual Studio Code, go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Select Port to Use``, and choose the serial port that your device is connected. -Next step is to :ref:`Configure your project <configure your project>`. +If you are not sure about the serial port name, refer to `Establish Serial Communication <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_. + +Next, proceed to :ref:`Configure your project <configure_your_project>`. diff --git a/docs_espressif/en/debugproject.rst b/docs_espressif/en/debugproject.rst index 37253fc83..7d57ae84e 100644 --- a/docs_espressif/en/debugproject.rst +++ b/docs_espressif/en/debugproject.rst @@ -4,7 +4,7 @@ Debug Your Project :link_to_translation:`zh_CN:[中文]` Table of Contents -================== +----------------- .. contents:: :depth: 2 @@ -18,15 +18,15 @@ Before debugging the project, you need to specify the serial port of the device: 1. Select the serial port -- Navigate to ``View`` > ``Command Palette``. +- Go to ``View`` > ``Command Palette`` -- Type **ESP-IDF: Select Port to Use** and select the command to specify the serial port of your device. +- Enter ``ESP-IDF: Select Port to Use`` and choose the command to specify the serial port of your device 2. Make sure that OpenOCD configuration files are correct -- Navigate to ``View`` > ``Command Palette``. +- Go to ``View`` > ``Command Palette`` -- Type **ESP-IDF: Select OpenOCD Board Configuration** and select the command to choose the OpenOCD configuration files for the extension OpenOCD server. +- Enter ``ESP-IDF: Select OpenOCD Board Configuration`` and choose the command to specify the OpenOCD configuration files for the extension OpenOCD server .. note:: @@ -211,5 +211,5 @@ Post-mortem Debugging Use Cases You can start a monitor session to capture fatal error events with **ESP-IDF: Launch IDF Monitor for Core Dump Mode/GDB Stub Modec** command. If configured in your project's sdkconfig, it can trigger the start of a debug session for GDB remote protocol server (GDBStub) or `ESP-IDF Core Dump <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/core_dump.html#core-dump>`_ when an error occurrs. For more information, see `Panic Handler <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/fatal-errors.html#panic-handler>`_. -- **Core Dump** is configured when **Core Dump's Data Destination** is set to either ``UART`` or ``FLASH`` using the **ESP-IDF: SDK Configuration Editor** extension command or ``idf.py menuconfig`` in a terminal. -- **GDB Stub** is configured when ``Panic Handler Behaviour`` is set to ``Invoke GDBStub`` using the **ESP-IDF: SDK Configuration Editor** extension command or ``idf.py menuconfig`` in a terminal. +- **Core Dump** is configured when **Core Dump's Data Destination** is set to either ``UART`` or ``FLASH`` using the ``ESP-IDF: SDK Configuration Editor`` extension command or ``idf.py menuconfig`` in a terminal. +- **GDB Stub** is configured when **Panic Handler Behaviour** is set to ``Invoke GDBStub`` using the ``ESP-IDF: SDK Configuration Editor`` extension command or ``idf.py menuconfig`` in a terminal. diff --git a/docs_espressif/en/flashdevice.rst b/docs_espressif/en/flashdevice.rst index ea2604c87..5723b1937 100644 --- a/docs_espressif/en/flashdevice.rst +++ b/docs_espressif/en/flashdevice.rst @@ -1,58 +1,48 @@ .. _flash the device: Flash onto the Device -=============================== +===================== -1. Select the Serial Port: +:link_to_translation:`zh_CN:[中文]` -- Navigate to **View** > Command Palette. +1. **Select the serial port**: Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Select Port to Use``, and choose the command to specify the serial port of your device. -- Type **ESP-IDF: Select Port to Use** and select the command to specify the serial port of your device. +2. **Start flashing the device**: Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Flash your Project``, and choose the command to start flashing your device. You can choose ``UART``, ``JTAG`` or ``DFU`` flashing method. -2. Start flashing the device: + .. note:: -- Go to **View** > **Command Palette**. + * ``UART`` is the most common option for most Espressif devices. + * If you are using ``JTAG``, ensure OpenOCD is properly configured. Go to ``View`` > ``Command Palette`` and enter ``ESP-IDF: Select OpenOCD Board Configuration`` to select the correct configuration for your board. -- Type **ESP-IDF: Flash your Project** and select the command to start flashing your device. + .. note:: -- Choose ``UART``, ``JTAG`` or ``DFU`` flash mode. + There is an ``idf.flashBaudRate`` configuration setting to modify the flashing baud rate. -3. The flashing task will beign on the previously selected serial port, launching a new terminal displaying the flash task output. While flashing is in progress, a notification bar will display ``ESP-IDF: Flashing project`` Once the process is complete, the message will change to ``Flash Done ⚡️``. +3. The flashing task will begin on the selected serial port, launching a new terminal displaying the flashing task output. While flashing is in progress, a notification bar will display ``ESP-IDF: Flashing project``. Once the process is complete, the message will change to ``Flash Done ⚡️``. -.. note:: - ``UART`` is the most common option for most Espressif devices. + .. image:: ../../media/tutorials/basic_use/flash.png -.. note:: - * If you are using ``JTAG`` make sure to have OpenOCD properly configured using menu **View** > **Command Palette** and type **ESP-IDF: Select OpenOCD Board Configuration** to select the right configuration for your board. - * Please review `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to understand which board or configuration to use for your specific hardware. - * Make sure to configure your drivers as mentioned in ESP-IDF `Configure JTAG Interface <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html>`_ documentation. +Please refer to `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to select the appropriate OpenOCD configuration file based on your hardware. -.. image:: ../../media/tutorials/basic_use/flash.png +Make sure to configure your drivers as mentioned in `Configure JTAG Interface <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html>`_. -.. note:: - * There is an **idf.flashBaudRate** configuration settings to modify the flashing baud rate. +Next, proceed to :ref:`Monitor the Output <monitor_the_output>`. -Next step is to :ref:`Monitor the output <monitor the output>`. +Other Flashing Commands +----------------------- -Other flashing commands --------------------------- +You can also choose the flashing method ``UART``, ``JTAG``, or ``DFU`` (ESP32-S2 or ESP32-S3) based on your hardware connection. -You can also choose the flashing type ``UART``, ``JTAG`` or ``DFU`` (esp32s2 or esp32s3) based on your hardware connection. +- Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Select Flash Method``, and select the flashing method for your device. The selected choice will be saved in the ``idf.flashType`` configuration setting. +- You can also use the following commands to flash with a specific flashing method: -- Go to **View** > **Command Palette**. + 1. ``ESP-IDF: Flash (UART) your Project`` for UART flashing + 2. ``ESP-IDF: Flash (DFU) your Project`` to flash using DFU (only for ESP32-S2 and ESP32-S3) + 3. ``ESP-IDF: Flash (with JTAG)`` to flash using JTAG and OpenOCD -- Type **ESP-IDF: Select Flash Method and Flash** and select the flashing type for your device. -- Selected choice will be saved in the **idf.flashType** configuration setting. +Related Documentation +--------------------- -You can also use these commands to flash with an specific flash type: - -1. **ESP-IDF: Flash (UART) your Project** for UART flashing. -2. **ESP-IDF: Flash (DFU) your Project** to flash using DFU (only for ESP32-S2 and ESP32-S3). -3. **ESP-IDF: Flash (with JTag)** to flash using JTAG and OpenOCD. - -Links -------------------- - -* `ESP-PROG guide <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html>`_ for hardware connection and configuration. -* `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to understand which board or configuration to use for your specific hardware. -* `Establishing serial connection <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_ with Espressif serial device. \ No newline at end of file +* `ESP-PROG Guide <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html>`_ for hardware connection and configuration +* `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to select the appropriate OpenOCD configuration file based on your hardware +* `Establishing Serial Connection <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_ with Espressif serial device diff --git a/docs_espressif/en/monitoroutput.rst b/docs_espressif/en/monitoroutput.rst index 15c3867d2..95c14fd61 100644 --- a/docs_espressif/en/monitoroutput.rst +++ b/docs_espressif/en/monitoroutput.rst @@ -1,23 +1,28 @@ +.. _monitor_the_output: + Monitor the Output -=============================== +================== + +:link_to_translation:`zh_CN:[中文]` To view the serial monitor output from your device, please follow the instructions below: -1. Select the Serial Port: +1. Select the serial port: + + - Go to ``View`` > ``Command Palette`` -- Navigate to **View** > **Command Palette**. + - Enter ``ESP-IDF: Select Port to Use`` and choose the command to specify the serial port of your device -- Type **ESP-IDF: Select Port to Use** and select the command to specify the serial port of your device. +2. Start monitoring: -2. Start Monitoring: + - Go to ``View`` > ``Command Palette`` -- Go to **View** > **Command Palette**. + - Enter ``ESP-IDF: Monitor Device`` and choose the command to start monitoring your device -- Type **ESP-IDF: Monitor Device** and select the command to start monitoring your device. + .. image:: ../../media/tutorials/basic_use/monitor.png -.. image:: ../../media/tutorials/basic_use/monitor.png + .. note:: -Next step is to :doc:`debug your project <debugproject>`. + The monitor baud rate is defined with ``CONFIG_ESPTOOLPY_MONITOR_BAUD`` in the project's SDK Configuration Editor. You can override it by setting a value in ``idf.monitorBaudRate``. -.. note:: - * The monitor baud rate is defined with ``CONFIG_ESPTOOLPY_MONITOR_BAUD`` from project's SDK Configuration Editor. You can override it by setting a value in **idf.monitorBaudRate**. \ No newline at end of file +Next, proceed to :doc:`debug your project <debugproject>`. \ No newline at end of file diff --git a/docs_espressif/en/settings.rst b/docs_espressif/en/settings.rst index 409b4b269..acb42eebb 100644 --- a/docs_espressif/en/settings.rst +++ b/docs_espressif/en/settings.rst @@ -1,3 +1,5 @@ +.. _settings: + ESP-IDF Settings ================ diff --git a/docs_espressif/zh_CN/buildproject.rst b/docs_espressif/zh_CN/buildproject.rst index c81f44ad2..f4d501ba7 100644 --- a/docs_espressif/zh_CN/buildproject.rst +++ b/docs_espressif/zh_CN/buildproject.rst @@ -1 +1,26 @@ -.. include:: ../en/buildproject.rst \ No newline at end of file +.. _build the project: + +构建项目 +======== + +:link_to_translation:`en:[English]` + +1. 构建项目:前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:构建项目``,点击该命令开始构建项目。 + +2. 一个新的终端自动开启并显示构建输出。通知栏中会出现 "Building project" 的信息,构建完成后则会显示 "Building done"。 + + .. image:: ../../media/tutorials/basic_use/build.png + + .. note:: + + 如果你不想自动查看输出,可以修改 ``idf.notificationMode`` 设置。请查看 :ref:`ESP-IDF 设置 <settings>`,了解如何修改此配置。 + + 若想修改构建任务的行为,可以在配置 Cmake 时使用 ``idf.cmakeCompilerArgs`` 参数,或在配置 Ninja 时使用 ``idf.ninjaArgs`` 参数。例如,可以使用 ``idf.ninjaArgs: [-j N]`` 来设置并行作业数,其中 **N** 是并行作业的数量。 + +3. 完成应用程序构建后,终端中将执行二进制文件大小分析任务,并显示分析结果。可以在 ``settings.json`` 中通过 ``idf.enableSizeTaskAfterBuildTask`` 配置项启用或禁用此分析任务。 + + .. image:: ../../media/tutorials/basic_use/size_terminal.png + +ESP-IDF 构建输出中会提示如何解决构建错误,这些提示可以通过 :ref:`提示查看器 <hints viewer>` 显示。 + +接下来请 :ref:`烧录项目 <flash the device>`。 diff --git a/docs_espressif/zh_CN/configureproject.rst b/docs_espressif/zh_CN/configureproject.rst index 8975b676e..eeb165442 100644 --- a/docs_espressif/zh_CN/configureproject.rst +++ b/docs_espressif/zh_CN/configureproject.rst @@ -1 +1,63 @@ -.. include:: ../en/configureproject.rst \ No newline at end of file +.. _configure_your_project: + +配置项目 +======== + +:link_to_translation:`en:[English]` + +前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:设置乐鑫设备目标``,选择目标设备(如 esp32, esp32s2 等)。 + +前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:选择 OpenOCD 开发板配置``,选择扩展中 OpenOCD 服务器的配置文件。 + +.. note:: + + 请查看 `根据目标芯片配置 OpenOCD <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_,为你的硬件选择合适的 OpenOCD 配置文件。 + +接下来请配置你的项目。前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:SDK 配置编辑器``,开始调整 ESP-IDF 项目设置。 + +.. image:: ../../media/tutorials/basic_use/gui_menuconfig.png + +完成更改后,点击 ``保存`` 并关闭此窗口。 + +接下来请 :ref:`构建项目 <build the project>`。 + +C 和 C++ 代码导航及语法高亮 +--------------------------- + +.. note:: + + 只要按照 :ref:`配置项目 <configure_your_project>` 中的描述创建项目,就无需额外配置 C 和 C++ 代码导航,因为 :ref:`配置项目 <configure_your_project>` 中提到的命令将自动生成 ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json`` 文件。 + +若想使用代码导航和 C/C++ 语法高亮,可以下载 `微软 C/C++ 扩展 <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_、`LLVM clangd 扩展 <https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_ 或其他偏好的扩展。 + +C/C++ 语言扩展通常都依赖于 ``compile_commands.json`` 文件,该文件位于项目的构建目录中,可以使用 ``ESP-IDF:运行 idf.py reconfigure 任务`` 命令来生成。 + +LLVM CLangd 扩展只需要用到 ``compile_commands.json`` 文件;而 Microsoft C/C++ 扩展的配置文件位于 ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json``,可以使用 ``ESP-IDF:新建项目``、``ESP-IDF:展示示例项目`` 命令或在现有的 ESP-IDF 项目中使用 ``ESP-IDF:添加 .vscode 配置文件夹`` 命令来生成该文件。 + +配置文件的格式如下: + +.. code-block:: JSON + + { + "configurations": [ + { + "name": "ESP-IDF", + "compilerPath": "/path/to/toolchain-gcc", + "compileCommands": "${workspaceFolder}/build/compile_commands.json", + "includePath": [ + "${config:idf.espIdfPath}/components", + "${config:idf.espIdfPathWin}/components/", + "${workspaceFolder}/" + ], + "browse": { + "path": [ + "${config:idf.espIdfPath}/components", + "${config:idf.espIdfPathWin}/components", + "${workspaceFolder}" + ] + } + } + ] + } + +如果未定义 ``compile_commands.json`` 文件,Microsoft C/C++ 扩展将浏览所提供的 ESP-IDF 路径以实现代码导航。 diff --git a/docs_espressif/zh_CN/connectdevice.rst b/docs_espressif/zh_CN/connectdevice.rst index e42d0688e..52e8dfc60 100644 --- a/docs_espressif/zh_CN/connectdevice.rst +++ b/docs_espressif/zh_CN/connectdevice.rst @@ -1 +1,12 @@ -.. include:: ../en/connectdevice.rst \ No newline at end of file +.. _connectdevice: + +连接设备 +======== + +:link_to_translation:`en:[English]` + +在 VS Code 中,前往菜单栏 ``查看`` > ``命令面板``,输入 ``ESP-IDF:选择要使用的端口``,并选择你的设备所连接的串口。 + +如果不确定串口名称,请参考 `创建串口连接 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/establish-serial-connection.html>`_。 + +接下来请开始 :ref:`配置项目 <configure_your_project>`。 diff --git a/docs_espressif/zh_CN/debugproject.rst b/docs_espressif/zh_CN/debugproject.rst index b5e66c0d3..7056da4f0 100644 --- a/docs_espressif/zh_CN/debugproject.rst +++ b/docs_espressif/zh_CN/debugproject.rst @@ -4,7 +4,7 @@ :link_to_translation:`en:[English]` 目录 -==== +---- .. contents:: :depth: 2 @@ -18,15 +18,15 @@ 1. 选择串口: -- 点击 ``查看`` > ``命令面板``。 +- 点击 ``查看`` > ``命令面板`` -- 输入 **ESP-IDF:选择要使用的端口**,指定设备的串口。 +- 输入 ``ESP-IDF:选择要使用的端口``,指定设备的串口 2. 确保 OpenOCD 配置文件正确 -- 点击 ``查看`` > ``命令面板``。 +- 点击 ``查看`` > ``命令面板`` -- 输入 **ESP-IDF:选择 OpenOCD 开发板配置**,选择扩展中 OpenOCD 服务器的配置文件。 +- 输入 ``ESP-IDF:选择 OpenOCD 开发板配置``,选择扩展中 OpenOCD 服务器的配置文件 .. note:: @@ -211,5 +211,5 @@ ESP-IDF 扩展在 ``运行和调试`` 视图中提供了 ``ESP-IDF:外设视 启动监视会话,通过 **ESP-IDF:启动 IDF 监视器以支持核心转储模式/GDB 存根模式** 命令找到致命错误事件。若提前在项目的 sdkconfig 文件中启用了特定选项,那么上述命令发现错误时就会触发 GDB 远程协议服务器 (GDBStub) 或 `ESP-IDF 核心转储 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/core_dump.html#id1>`_。详情请参阅 `紧急处理程序 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/fatal-errors.html#id3>`_。 -- 配置 **核心转储**:在扩展中使用命令 **ESP-IDF:SDK 配置编辑器** 或在终端中使用 ``idf.py menuconfig``,将 **核心转储的数据目标** 设置为 ``UART`` 或 ``FLASH``。 -- 配置 **GDB Stub**:在扩展中使用命令 **ESP-IDF:SDK 配置编辑器** 或在终端中使用 ``idf.py menuconfig``,将 **紧急处理程序行为** 设置为 ``Invoke GDBStub``。 +- 配置 **核心转储**:在扩展中使用命令 ``ESP-IDF:SDK 配置编辑器`` 或在终端中使用 ``idf.py menuconfig``,将 **核心转储的数据目标** 设置为 ``UART`` 或 ``FLASH``。 +- 配置 **GDB Stub**:在扩展中使用命令 ``ESP-IDF:SDK 配置编辑器`` 或在终端中使用 ``idf.py menuconfig``,将 **紧急处理程序行为** 设置为 ``Invoke GDBStub``。 diff --git a/docs_espressif/zh_CN/flashdevice.rst b/docs_espressif/zh_CN/flashdevice.rst index 6693655e0..3fca6a8a6 100644 --- a/docs_espressif/zh_CN/flashdevice.rst +++ b/docs_espressif/zh_CN/flashdevice.rst @@ -1 +1,48 @@ -.. include:: ../en/flashdevice.rst \ No newline at end of file +.. _flash the device: + +烧录项目 +======== + +:link_to_translation:`en:[English]` + +1. **选择串口**:前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:选择要使用的端口``,选中该命令并指定设备的串口。 + +2. **烧录设备**:前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:烧录项目``,选中该命令以烧录设备。在开始烧录前可以选择 ``UART``、``JTAG`` 或 ``DFU`` 串口进行烧录。 + + .. note:: + + * 大多数乐鑫设备通常选用 ``UART`` 串口进行烧录。 + * 如果选用了 ``JTAG``,请确保正确配置 OpenOCD。前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:选择 OpenOCD 开发板配置``,为你使用的开发板选择正确的配置。 + + .. note:: + + 可以通过配置 ``idf.flashBaudRate`` 选项来修改烧录的波特率值。 + +3. 烧录任务将在所选的串口上开始,并启动新的终端窗口来显示烧录任务的输出信息。烧录时,通知栏将显示 ``ESP-IDF: Flashing project``;烧录完成后,消息将变为 ``Flash Done ⚡️``。 + + .. image:: ../../media/tutorials/basic_use/flash.png + +请查看 `根据目标芯片配置 OpenOCD <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_,为你的硬件选择合适的 OpenOCD 配置文件。 + +请确保按照 `配置 JTAG 接口 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html>`_ 中的指导来配置驱动程序。 + +接下来请 :ref:`监视输出 <monitor_the_output>`。 + +其他烧录命令 +------------ + +你也可以根据硬件连接方式来选择合适的烧录方式:``UART``、``JTAG`` 或 ``DFU`` (仅适用于 ESP32-S2 或 ESP32-S3)。 + +- 前往菜单栏 ``查看`` > ``命令面板`` 并输入 ``ESP-IDF:选择烧录方式``,为设备选择合适的烧录方式。该烧录方式将被保存在 ``idf.flashType`` 配置设置中。 +- 也可以使用以下命令来选择特定的烧录方式进行烧录: + + 1. ``ESP-IDF:通过 UART 接口烧录项目`` + 2. ``ESP-IDF:通过 DFU 接口烧录项目`` (仅适用于 ESP32-S2 和 ESP32-S3) + 3. ``ESP-IDF:通过 JTAG 接口烧录项目`` (使用 JTAG 和 OpenOCD 进行烧录) + +相关文档 +-------- + +* 参考 `ESP-PROG 指南 <https://docs.espressif.com/projects/esp-iot-solution/zh_CN/latest/hw-reference/ESP-Prog_guide.html>`_ 进行硬件连接和配置 +* `为特定目标配置 OpenOCD <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ +* 与乐鑫串行设备 `创建串口连接 <https://docs.espressif.com/projects/esp-idf/cn/latest/esp32/get-started/establish-serial-connection.html>`_ diff --git a/docs_espressif/zh_CN/monitoroutput.rst b/docs_espressif/zh_CN/monitoroutput.rst index 25320680f..900616e25 100644 --- a/docs_espressif/zh_CN/monitoroutput.rst +++ b/docs_espressif/zh_CN/monitoroutput.rst @@ -1 +1,28 @@ -.. include:: ../en/monitoroutput.rst \ No newline at end of file +.. _monitor_the_output: + +监视输出 +======== + +:link_to_translation:`en:[English]` + + 请参照以下说明,查看设备的串行监视器输出: + +1. 选择串行端口: + + - 前往菜单栏 ``查看`` > ``命令面板`` + + - 输入 ``ESP-IDF:选择要使用的端口``,选中该命令并指定设备的串口 + +2. 开始监视: + + - 前往菜单栏 ``查看`` > ``命令面板`` + + - 输入 ``ESP-IDF:监视设备``,选中该命令,开始监视设备 + + .. image:: ../../media/tutorials/basic_use/monitor.png + + .. note:: + + 可以在项目的 SDK 配置编辑器中通过 ``CONFIG_ESPTOOLPY_MONITOR_BAUD`` 配置项指定串行监视器的波特率。在 ``idf.monitorBaudRate`` 配置项中设置新的值可以覆盖 SDK 配置。 + +接下来请 :doc:`调试项目 <debugproject>`。 diff --git a/docs_espressif/zh_CN/settings.rst b/docs_espressif/zh_CN/settings.rst index eaadbaf81..84919b539 100644 --- a/docs_espressif/zh_CN/settings.rst +++ b/docs_espressif/zh_CN/settings.rst @@ -1,3 +1,5 @@ +.. _settings: + ESP-IDF 设置 ============