diff --git a/docs/en/additionalfeatures.rst b/docs/en/additionalfeatures.rst index d65988619..7128b327d 100644 --- a/docs/en/additionalfeatures.rst +++ b/docs/en/additionalfeatures.rst @@ -1,23 +1,24 @@ Additional IDE Features -=============================== -.. toctree:: - :maxdepth: 1 +======================= - LSP C/C++ Editor - CMake Editor - ESP-IDF Application Size Analysis - ESP-IDF Terminal - Install ESP-IDF Components - Heap Tracing - ESP-IDF OpenOCD Debugging - GDB Stub Debugging - Core Dump Debugging - Application Level Tracing - Partition Table Editor - NVS Partition Editor - Write Binary to Flash - DFU Flashing - Wokwi Simulator - Switch Between Languages +:link_to_translation:`zh_CN:[中文]` +.. toctree:: + :maxdepth: 1 + LSP C/C++ Editor + CMake Editor + ESP-IDF Application Size Analysis + ESP-IDF Terminal + Install ESP-IDF Components + Heap Tracing + ESP-IDF OpenOCD Debugging + GDB Stub Debugging + Core Dump Debugging + Application Level Tracing + Partition Table Editor + NVS Partition Editor + Write Binary to Flash + DFU Flashing + Wokwi Simulator + Switch Between Languages diff --git a/docs/en/configureproject.rst b/docs/en/configureproject.rst index 1accf07c9..33498e489 100644 --- a/docs/en/configureproject.rst +++ b/docs/en/configureproject.rst @@ -1,10 +1,13 @@ Configure Your Project -=============================== +====================== -Project configuration is stored in a single file called ``sdkconfig`` located in the root directory of the project. This configuration file can be modified using the ``SDK Configuration Editor``. +:link_to_translation:`zh_CN:[中文]` + +Project configuration is stored in a single file called ``sdkconfig`` located in the root directory of the project. This configuration file can be modified using the SDK Configuration Editor. .. note:: - sdkconfig file is generated only after the build. Hence, it is recommended to build the project once before configuring the project. + + ``sdkconfig`` file is generated only after the build. Hence, it is recommended to build the project once before configuring the project. To launch the SDK Configuration Editor: diff --git a/docs/en/connectdevice.rst b/docs/en/connectdevice.rst index e9428bb35..995510933 100644 --- a/docs/en/connectdevice.rst +++ b/docs/en/connectdevice.rst @@ -1,22 +1,24 @@ Connect Your Device -=============================== -Next, select the ESP target for your project (ignore this step if it was already set during project creation) and the serial port of your device by clicking on the gear icon. By default, the launch target dropdown will display all the supported targets provided by the plugin. +=================== + +:link_to_translation:`zh_CN:[中文]` + +Click the gear icon to select the ESP target for your project and the serial port of your device. Skip this step if these settings were configured during project creation. By default, the launch target dropdown will display all the supported targets provided by the plugin. .. image:: ../../media/target_selection.png -Clicking the gear icon opens the ESP Target Configuration dialog, where you can select the serial port for your device and specify the ESP board. The plugin will automatically detect serial ports connected to your machine. +Clicking the gear icon opens the ``ESP Target`` configuration dialog, where you can select the serial port for your device and specify the ESP board. The plugin will automatically detect serial ports connected to your machine. .. image:: ../../media/8_launch_target.png -Regarding the Serial ports and their patterns, please refer to the `ESP-IDF documentation `_. +Regarding the serial ports and their patterns, please refer to the `ESP-IDF documentation `_. Custom Target ----------------- +------------- + If you need to add a target that is not available in the launch target dropdown, please follow the instructions below: 1. Click on the launch target dropdown. 2. Select ``New Launch Target``. 3. Select ``ESP Target``. -4. Provide properties for the target where you would like to launch the application. Enter a ``Name`` for the target and select the ``Serial Port`` to which your ESP device is connected on your machine. - - +4. Specify the properties of the target device where you want to launch the application. Enter a ``Name`` for the target and select the ``Serial Port`` to which your ESP device is connected on your machine. diff --git a/docs/en/downloads.rst b/docs/en/downloads.rst index 2c20e47f2..e44d64e1e 100644 --- a/docs/en/downloads.rst +++ b/docs/en/downloads.rst @@ -1,33 +1,39 @@ .. _downloads: Espressif-IDE Downloads -========================= +======================= -You can find the latest Espressif-IDE release notes from `here `_. Provided below are the direct download links for various platforms. +:link_to_translation:`zh_CN:[中文]` -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| OS | Download | -+==============+===========================================================================================================================================+ -| Windows | `Espressif-IDE-win32.win32.x86_64 `_ | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| macOS x86_64 | `Espressif-IDE-macosx-cocoa-x86_64 `_ | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| macOS aarch64| `Espressif-IDE-macosx-cocoa-aarch64 `_ | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Linux | `Espressif-IDE-linux.gtk.x86_64 `_ | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +You can find the latest Espressif-IDE release notes at `here `_. Direct download links for various platforms are provided below. +.. list-table:: + :header-rows: 1 + :widths: 20 80 -macOS security notice (Applicable only for Nightly Builds) ------------------------------------------------------------- -On macOS, if you download the archive with the browser, the strict security checks on recent macOS will prevent it to run, and complain that the program is damaged. That’s obviously not true, and the fix is simple, you need to remove the `com.apple.quarantine` extended attribute. + * - OS + - Download + * - Windows + - `Espressif-IDE-win32.win32.x86_64 `_ + * - macOS x86_64 + - `Espressif-IDE-macosx-cocoa-x86_64 `_ + * - macOS aarch64 + - `Espressif-IDE-macosx-cocoa-aarch64 `_ + * - Linux + - `Espressif-IDE-linux.gtk.x86_64 `_ + + +macOS Security Notice (Applicable Only for Nightly Builds) +---------------------------------------------------------- + +On macOS, if you download the archive using a web browser, the strict security checks in recent macOS versions will prevent it from running and display a message that the program is damaged. This is not actually true, and the fix is simple: you just need to remove the ``com.apple.quarantine`` extended attribute. .. code-block:: shell $ xattr -d com.apple.quarantine ~/Downloads/Espressif-IDE-x.x.x-macosx.cocoa.x86_64.tar.gz -After un-archiving, if the application still complains, check/remove the attribute from the Espressif-IDE.app folder too: +After unpacking the archive, if the application still shows the same warning, check and remove the attribute from the ``Espressif-IDE.app`` folder as well: .. code-block:: shell - $ xattr -dr com.apple.quarantine ~/Downloads/Espressif-IDE.app \ No newline at end of file + $ xattr -dr com.apple.quarantine ~/Downloads/Espressif-IDE.app diff --git a/docs/en/faqs.rst b/docs/en/faqs.rst index 7e0d5505c..8f27adf7f 100644 --- a/docs/en/faqs.rst +++ b/docs/en/faqs.rst @@ -1,189 +1,209 @@ FAQ ==== +:link_to_translation:`zh_CN:[中文]` + How do I know the installed version of Java in my system? ---------------------------------------------------------- -You can check using `java -version` command from the terminal. + +You can check using ``java -version`` command from the terminal. How to check the Java version used by Eclipse? ---------------------------------------------- -- `Help > About Eclipse > Installation Details > Configuration` -- Look for `-vm` argument. -How to increase the heap memory for Java while working Eclipse IDE? --------------------------------------------------------------------- -- Locate the eclipse.ini or espressif-ide.ini -- Increase the Xmx value under the `-vmargs` args section. For example, you can set to `-Xmx2048m`. +1. Go to ``Help`` > ``About Eclipse`` > ``Installation Details`` > ``Configuration``. +2. Look for ``-vm`` argument. + +How to increase the heap memory for Java while using Eclipse IDE? +----------------------------------------------------------------- + +1. Locate the ``eclipse.ini`` or ``espressif-ide.ini``. +2. Increase the Xmx value under the ``-vmargs`` args section. For example, you can set to ``-Xmx2048m``. What are the operating systems the plugin supports? ----------------------------------------------------- +--------------------------------------------------- + - Windows -- macOSX +- macOS - Linux How do I provide Eclipse environment and plugins information? ------------------------------------------------------------- -`Help > About Eclipse > Installation Details > Configuration > Copy to Clipboard` + +``Help`` > ``About Eclipse`` > ``Installation Details`` > ``Configuration`` > ``Copy to Clipboard`` How do I know the installed IDF Eclipse Plugins version? ---------------------------------------------------------- -- You can check using the menu `Eclipse > About Eclipse > Installation Details > Installed Software` -- Search for `Espressif`. +-------------------------------------------------------- + +1. Go to the menu ``Eclipse`` > ``About Eclipse`` > ``Installation Details`` > ``Installed Software``. +2. Search for "Espressif". How do I uninstall IDF Eclipse Plugins from the Eclipse? ---------------------------------------------------------- -- `Eclipse > About Eclipse > Installation Details > Installed Software` -- Search for `Espressif`. -- Select the Espressif IDF Feature -- `Uninstall..`. +-------------------------------------------------------- + +1. Go to ``Eclipse`` > ``About Eclipse`` > ``Installation Details`` > ``Installed Software``. +2. Search for "Espressif". +3. Select ``Espressif IDF Feature``. +4. Click ``Uninstall..``. Unable to install IDF plugins in Eclipse? ----------------------------------------- -Please check the error log from the main menu, select `Window > Show View > Other`. Then select `General > Error Log`. -Espressif Menu options and Espressif IDF Project menu are not visible in my Eclipse CDT ---------------------------------------------------------------------------------------- -- Make sure you have installed Java 8 and above and Eclipse in the C/C++ perspective. -- Reset the perspective using `Window > Perspective > Reset Perspective..`. +Please check the error log from the main menu: + +1. Go to ``Window`` > ``Show View`` > ``Other``. +2. Then select ``General`` > ``Error Log``. + +Espressif Menu options and Espressif IDF Project menu are not visible in my Eclipse CDT. +---------------------------------------------------------------------------------------- + +1. Make sure you have installed Java 8 and above and Eclipse in the C/C++ perspective. +2. Reset the perspective using ``Window`` > ``Perspective`` > ``Reset Perspective..``. Do IDF Eclipse Plugins support CMake IDF project creation? ---------------------------------------------------------- -Yes, you can create IDF CMake project using `File > New > Espressif IDF Project`. + +Yes, you can create IDF CMake project using ``File`` > ``New`` > ``Espressif IDF Project``. Can I import my existing IDF project into Eclipse? --------------------------------------------------- -Yes, you can import using Import Menu. `Import... > Espressif > Existing IDF Project`. + +Yes, you can import using Import Menu. ``Import...`` > ``Espressif`` > ``Existing IDF Project``. Where can I find the IDF installed tools in my system? ------------------------------------------------------ -Default directory is `$HOME/.espressif` for Linux/MacOS users or `%USER_PROFILE%.espressif` for Windows users. -Why am I getting timeout errors when Installing tools? ------------------------------------------------------- -If you are getting errors when downloading or installing tools this can be due to some issue with the mirrors. You can try to set the mirrors in Eclipse `Preferences > Espressif` you will see two settings for Git and Pip Py Wheels please set these to proper mirror according to your region. Currently, these two mirrors are available. +Default directory is ``$HOME/.espressif`` for Linux/MacOS users or ``%USER_PROFILE%.espressif`` for Windows users. -### Mirror for GIT (IDF_GITHUB_ASSETS) -- dl.espressif.com/github_assets (default) -- dl.espressif.cn/github_assets +Why do deleted C/C++ build environment variables still appear? +-------------------------------------------------------------- -### Mirror for python wheels (PIP_EXTRA_INDEX_URL) -- https://dl.espressif.com/pypi (default) -- https://dl.espressif.cn/pypi +You need to uncheck the preference recorder. This can be performed by the following: -Deleted C/C++ build environment variables still appearing? ----------------------------------------------------------- -- You need to uncheck the preference recorder. This can be performed by following. Eclipse `Preferences > Oomph > Setup Tasks > Preference Recorder`. -- Uncheck `Record into`. +1. Go to ``Preferences`` > ``Oomph`` > ``Setup Tasks`` > ``Preference Recorder``. +2. Uncheck ``Record into``. How can I rollback to old ESP-IDF Eclipse plugin? ------------------------------------------------- -- Open Eclipse IDE and Uninstall the esp-idf plugin. -- Restart Eclipse IDE. -- Download the previous version of the ESP Eclipse Plugin from the release page -- Go to `Help > Install New Software`. -- Press the `Add` button, a window will open with the name of `Add Repository`. -- Press the `Archive` button and select the file downloaded. -- Proceed with the installation. -- Restart Eclipse. - -Where can I find Compiler_commands.json file for the project? --------------------------------------------------------------- -`/projectName/build/compile_commands.json` -compile_commands.json containing the exact compiler calls for all translation units of the project in machine-readable form which is used by the Eclipse CDT indexing for parsing and resolving headers. +1. Open Eclipse IDE and Uninstall the ESP-IDF plugin. +2. Restart Eclipse IDE. +3. Download the previous version of the ESP Eclipse Plugin from the release page. +4. Go to ``Help`` > ``Install New Software``. +5. Press the ``Add`` button, a window will open with the name of ``Add Repository``. +6. Press the ``Archive`` button and select the file downloaded. +7. Proceed with the installation. +8. Restart Eclipse. + +Where can I find the ``compile_commands.json`` file for the project? +-------------------------------------------------------------------- + +You can find it at ``/projectName/build/compile_commands.json``. + +``compile_commands.json`` contains the exact compiler calls for all translation units of the project in machine-readable. It is used by the Eclipse CDT indexer for parsing and resolving headers. How do I access CDT Parser error log? -------------------------------------- -Please follow this menu. `Project > C/C++ Index > Create Parser Log`. + +Please go to ``Project`` > ``C/C++ Index`` > ``Create Parser Log``. How do I access the error log? ------------------------------ -To view the Eclipse error log: From the main menu, select `Window > Show View > Other`. Then select `General > Error Log`. + +From the main menu, select ``Window`` > ``Show View`` > ``Other``. Then select ``General`` > ``Error Log``. How do I report a deadlock or Eclipse hang? ------------------------------------------- + You can find the detailed instructions here: https://wiki.eclipse.org/How_to_report_a_deadlock. -- On the command line, use `jps -v` to find the PIDs of Java processes and `jstack ` to show the stack trace of Java processes. -Here 32308 and 8824 are PIDs of Java processes. 8824 is jps itself and is of no interest for us. 32308 is an Eclipse process judging from the presence of `org.eclipse.equinox.launcher` in its command line. The `jstack` command saves the stack trace of the Eclipse process in a file `/tmp/jstack.txt`, attach the file to the bug report. +On the command line, use ``jps -v`` to find the PIDs of Java processes and ``jstack `` to show the stack trace of Java processes. + +Here 32308 and 8824 are PIDs of Java processes. 8824 is jps itself and is of no interest for us. 32308 is an Eclipse process judging from the presence of ``org.eclipse.equinox.launcher`` in its command line. The ``jstack`` command saves the stack trace of the Eclipse process in a file ``/tmp/jstack.txt``, attach the file to the bug report. -`sun.security.validator.ValidatorException: PKIX path building failed:` error +``sun.security.validator.ValidatorException: PKIX path building failed`` error ------------------------------------------------------------------------------ -This would have been caused by the Java version or Java certificates. Please make sure you've installed `Java 11 and later` to fix this error. -Check below links: + +This issue is likely caused by the Java version or missing Java certificates. Please ensure that **Java 11 or later** is installed to resolve the error. Refer to the links below for more details: + - https://esp32.com/viewtopic.php?f=13&t=12327&start=10#p50137 - https://stackoverflow.com/questions/6908948/java-sun-security-provider-certpath-suncertpathbuilderexception-unable-to-find -Why Java 11 recommended for IDF Eclipse Plugin? ------------------------------------------------ -We recommend using Java 11 (that's the latest LTS version from Oracle) and above while working with IDF Eclipse Plugin considering Eclipse 2020-06 has a requirement for Java 11 to work with the CDT. Here are some important pointers from Eclipse. +Why is Java 11 recommended for the IDF Eclipse Plugin? +------------------------------------------------------ + +We recommend using Java 11 (the latest LTS version from Oracle) or later when working with the IDF Eclipse Plugin. This is because Eclipse 2020-06 requires Java 11 to work properly with the CDT. Here are some important pointers from Eclipse: -### Installing CDT 9.11 on Eclipse 2020-06 and later requires a workaround when using Java 8 -Check this - https://wiki.eclipse.org/CDT/User/NewIn911#Release +- `Installing CDT 9.11 on Eclipse 2020-06 and later requires a workaround when using Java 8 `_. -CDT 9.11 only requires Java 8 to run. However, a new feature in Eclipse 2020-06 and later means that the install wizard may prevent installation. The workaround is to disable "Verify provisioning operation is compatible with the currently running JRE" in Windows -> Preferences -> Install/Update. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=564407#c1. + CDT 9.11 only requires Java 8 to run. However, a new feature in Eclipse 2020-06 and later means that the Install wizard may prevent installation. The workaround is to disable "Verify provisioning operation is compatible with the currently running JRE" in ``Windows`` > ``Preferences`` > ``Install/Update``. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=564407#c1. -### CDT 10.0 required Java 11 or later -Check this - https://wiki.eclipse.org/CDT/User/NewIn100 +- `CDT 10.0 requires Java 11 or later `_. -Starting with CDT 10.0, Java 11 or later is required to run CDT. This aligns with the requirements of Eclipse IDE which also requires Java 11 to run starting in 2020-09. + Starting with CDT 10.0, Java 11 or later is required to run CDT. This aligns with the requirements of Eclipse IDE which also requires Java 11 to run starting in 2020-09. -How to delete Launch Targets from the Eclipse +How to delete launch targets from the Eclipse --------------------------------------------- + There is no UI option to delete launch targets directly from Eclipse, however, this can be achieved by following the below instructions: -- Go to the Eclipse workspace directory. For example: In my case `/Users/myName/myTesteclipseWorkspace`. -- Navigate to `.metadata/.plugins/org.eclipse.core.runtime/.settings` folder in the workspace directory. -- Look for `org.eclipse.launchbar.core.prefs` file and open it in the editor. -- Search for the launch target name you want to delete and remove all those entries from the file. -- Save the file. -- Restart Eclipse. + +1. Go to the Eclipse workspace directory. For example, in my case: ``/Users/myName/myTesteclipseWorkspace``. +2. Navigate to ``.metadata/.plugins/org.eclipse.core.runtime/.settings`` folder in the workspace directory. +3. Look for ``org.eclipse.launchbar.core.prefs`` file and open it in the editor. +4. Search for the launch target name you want to delete and remove all those entries from the file. +5. Save the file. +6. Restart Eclipse. How do I access project build log? ----------------------------------- -- To enable logging, navigate to `Preferences > Project > C/C++ > Build > Logging`. -- Check `Enable global build logging`. -- Build the project. -- Export `global-build.log`. This is the same build console log which appears in the CDT build console, but the build console usually has a limited buffer size, hence it won't display everything. + +1. To enable logging, navigate to ``Preferences`` > ``Project`` > ``C/C++`` > ``Build`` > ``Logging``. +2. Check ``Enable global build logging``. +3. Build the project. +4. Export ``global-build.log``. This is the same build console log which appears in the CDT build console, but the build console usually has a limited buffer size, hence it won't display everything. How do I enable verbose debug output to my project build? ----------------------------------------------------------- +--------------------------------------------------------- + IDF Eclipse plugin uses CMake commands to build the project, so it's possible to pass CMake arguments from the build configuration wizard. To configure this: -- Click on the editor configuration wizard. -- Navigate to `Build Settings` tab. -- Add `--debug-output` or other + +1. Click on the editor configuration wizard. +2. Navigate to ``Build Settings`` tab. +3. Add ``--debug-output`` or other. How do I build multiple configurations in Espressif-IDE? ----------------------------------------------------------- -- Create a new project. -- Open the `Launch Configuration` dialog. -- Navigate to the `Build Settings` tab and enter `-B build_release` in the `Additional CMake Arguments` section. Here, `build_release` is the name of the build folder. -- Click the `OK` button to save the configuration. -- Reopen the `Launch Configuration` dialog. -- Click the `Duplicate` button (located at the bottom left corner). -- Navigate to the `Build Settings` tab and update the `Additional CMake Arguments` section to `-B build_dev`. Here, `build_dev` is the name of the build folder. -- Click the `OK` button to save the configuration. -- Click the Build icon from the toolbar (the leftmost icon) for the selected configuration. This will build the project and create a build folder for that configuration. Repeat the same process for the other configuration by selecting it from the dropdown. - -Can I Use My Old C/C++ Editor Formatter File (.xml) as a .clang-format File? ----------------------------------------------------------------------------- -No, you cannot directly use the old `.xml` (CDT formatter) file with ESP-IDF projects, as these now use the CDT LSP Editor, which relies on Clangd for code formatting. Clangd requires a `.clang-format` file, and there is no official tool to convert `.xml` formatter files to the Clang format. - -However, Clang provides several default formatting styles (such as LLVM, Google, Mozilla, etc.) that you can use as a starting point. You can generate a default `.clang-format` file using the following command: +-------------------------------------------------------- -.. code-block:: none +1. Create a new project. +2. Open the ``Launch Configuration`` dialog. +3. Navigate to the ``Build Settings`` tab and enter ``-B build_release`` in the ``Additional CMake Arguments`` section. Here, ``build_release`` is the name of the build folder. +4. Click the ``OK`` button to save the configuration. +5. Reopen the ``Launch Configuration`` dialog. +6. Click the ``Duplicate`` button at the bottom left corner. +7. Navigate to the ``Build Settings`` tab and update the ``Additional CMake Arguments`` section to ``-B build_dev``. Here, ``build_dev`` is the name of the build folder. +8. Click the ``OK`` button to save the configuration. +9. Click the ``Build`` icon from the toolbar (the leftmost icon) for the selected configuration. This will build the project and create a build folder for that configuration. Repeat the same process for the other configuration by selecting it from the dropdown. + +Can I use my old C/C++ editor formatter file (.xml) as a ``.clang-format`` file? +-------------------------------------------------------------------------------- + +No, you cannot directly use the old ``.xml`` (CDT formatter) file with ESP-IDF projects, as these now use the CDT LSP Editor, which relies on Clangd for code formatting. Clangd requires a ``.clang-format`` file, and there is no official tool to convert ``.xml`` formatter files to the Clang format. - clang-format -style=llvm -dump-config > .clang-format +However, Clang provides several default formatting styles (such as LLVM, Google, Mozilla, etc.) that you can use as a starting point. You can generate a default ``.clang-format`` file using the following command: + +.. code-block:: none -For new ESP-IDF projects, a `.clang-format` file is automatically created in the root directory with default settings. This file is picked up by Clangd automatically—no additional configuration is needed. + clang-format -style=llvm -dump-config > .clang-format -For existing projects, you can create this file manually by right-clicking the project and selecting: +For new ESP-IDF projects, a ``.clang-format`` file is automatically created in the root directory with default settings. This file is picked up by Clangd automatically — no additional configuration is needed. - ESP-IDF > Create Clangd File +For existing projects, you can create this file manually by right-clicking the project and selecting ``ESP-IDF`` > ``Create Clangd File``. If you would like to replicate your old formatter settings, you can either: -- Manually map your `.xml` settings to Clang format using Clang’s formatting guide. -- Or Use an AI tool(e.g: ChatGPT) to assist in converting your old configuration to the new one and then manually adjust if there are any discrepancies. +- Manually map your ``.xml`` settings to Clang format using Clang's formatting guide. +- Or use an AI tool (e.g., ChatGPT) to assist in converting your old configuration to the new one. After that, manually adjust any discrepancies. -More information on the Clang format can be found in the `Clang Format documentation `_ and formatting styles can be found in the `Clang Format Style Options `_. +More information on the Clang format can be found in the `ClangFormat documentation `_. +Formatting styles can be found in the `Clang-Format Style Options `_. diff --git a/docs/en/flashdevice.rst b/docs/en/flashdevice.rst index 24742de29..578fd358a 100644 --- a/docs/en/flashdevice.rst +++ b/docs/en/flashdevice.rst @@ -1,26 +1,26 @@ -Flash onto the Device -=============================== +Flash the Device +================ + +:link_to_translation:`zh_CN:[中文]` .. |run_icon| image:: ../../media/icons/run.png :height: 16px :align: middle -Flash operation can be initiated with just a click of a launch button |run_icon| and it's auto-configured to flash the application with the default flash command, i.e., ``idf.py -p PORT flash``. +You can start the flash operation by clicking the launch button |run_icon|. The process is automatically configured to flash the application using the default command: ``idf.py -p PORT flash``. .. image:: https://github.com/espressif/idf-eclipse-plugin/assets/8463287/3249c01b-af23-4863-811f-c3959008f257 :width: 767px :alt: flash -To provide customized flash arguments, please follow :ref:`this link ` for further instructions. - -To enable flash encryption, please see the :ref:`Flash Encryption guide `. - -To configure flashing via JTAG, please refer to this :ref:`JTAG Flashing guide ` +- To provide customized flash arguments, please refer to :ref:`this guide `. +- To enable flash encryption, please refer to :ref:`Flash Encryption `. +- To configure flashing via JTAG, please refer to :ref:`JTAG Flashing `. .. _customizeLaunchConfig: Customize Flash Arguments -------------------------------- +------------------------- To provide the customized launch configuration and flash arguments, follow the steps below: @@ -28,17 +28,17 @@ To provide the customized launch configuration and flash arguments, follow the s #. Switch to the ``Main`` tab. #. Specify the ``Location`` where this application has to run. Since ``idf.py`` is a Python file, configure the Python system path. Example: ``${system_path:python}``. #. Specify the ``Working directory`` of the application. Example: ``${workspace_loc:/hello_world}``. -#. In the **Arguments** field (see **1** in the image), the default value uses **dynamic variables**: +#. In the ``Arguments`` field (see ``1`` in the image), the default value uses **dynamic variables**: - ``${IDF_PY} -B ${BUILD_DIR} -p ${serial_port} ${flash_command}`` + ``${IDF_PY} -B ${BUILD_DIR} -p ${serial_port} ${flash_command}`` - This default setup automatically adapts to your project and board, so usually no manual changes are needed. + This default setup automatically adapts to your project and board, so usually no manual changes are needed. - - Use the **Preview icon** (see **2**) to switch between showing resolved values and the raw dynamic variables. - - The field is **modifiable only** when dynamic variables are shown (not resolved). - - If you are migrating from an older plugin version and the field does not contain dynamic variables, click **Restore Defaults** (see **3**) to reset it. + - Use the ``Preview`` icon (see ``2`` in the image) to switch between showing resolved values and the raw dynamic variables. + - The field is **modifiable only** when dynamic variables are shown (not resolved). + - If you are migrating from an older plugin version and the field does not contain dynamic variables, click ``Restore defaults`` (see ``3`` in the image) to reset it. -#. Click **OK** to save the settings. +#. Click ``OK`` to save the settings. #. Click on the ``Launch`` icon to flash the application to the selected board. .. image:: ../../media/launch_configuration.png @@ -55,37 +55,35 @@ Flash Encryption .. warning:: - Enabling flash encryption is an **irreversible operation**. - If configured incorrectly, the board may become permanently unusable. - Proceed with caution and only enable this option if you fully understand its implications. + Enabling flash encryption is an **irreversible operation**. If configured incorrectly, the board may become permanently unusable. Proceed with caution and only enable this option if you fully understand its implications. To enable flash encryption in ESP-IDF, follow these steps: -#. Open ``sdkconfig`` and enable the ``Enable flash encryption on boot`` option. +#. Open ``sdkconfig`` and enable the ``Enable flash encryption on boot`` option. -.. image:: ../../media/flash_encryption_1.png - :alt: Flash encryption sdkconfig + .. image:: ../../media/flash_encryption_1.png + :alt: Flash encryption sdkconfig -#. Perform a normal flash of the application. -#. Open the **Launch Configuration** dialog, edit the configuration, and check the **Enable Flash Encryption** box. +#. Perform a normal flash of the application. +#. Open the ``Launch Configuration`` dialog, edit the configuration, and check the ``Enable Flash Encryption`` box. -.. image:: ../../media/flash_encryption_2.png - :alt: Flash encryption checkbox + .. image:: ../../media/flash_encryption_2.png + :alt: Flash encryption checkbox -#. Flash the application again. +#. Flash the application again. Once enabled, flash encryption will automatically secure the contents of the flash memory according to ESP-IDF settings. -For more details, please refer to the official -`ESP-IDF Flash Encryption documentation `_. +For more details, please refer to the official `Flash Encryption `_ documentation. .. _JTAGFlashing: Upload Application via JTAG -------------------------------- +--------------------------- + +The default method for uploading applications is UART. To switch to JTAG, edit the launch configuration of your project and select the appropriate option. -The default option for uploading applications is UART. To change it to JTAG, you need to edit the launch configuration for your project and select the appropriate option. To do so, select your project in the launch configuration bar and click on the gear icon to edit the launch configuration: .. image:: ../../media/JtagFlash_1.png @@ -97,7 +95,7 @@ Then select the ``Flash Over JTAG`` option and complete the ``OpenOCD Setup`` se :width: 986px :alt: Flash over JTAG option -If the ``Flash Over JTAG`` option is not available and you see a message like this: +If the ``Flash Over JTAG`` option is not available, and you see a message like this: .. image:: ../../media/JtagFlash_3.png :alt: OpenOCD update required message @@ -107,15 +105,16 @@ It means that OpenOCD needs to be updated. You can find the latest OpenOCD versi Providing the Right Path for OpenOCD ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After downloading the necessary `OpenOCD version `_, extract it to a new folder in the `.espressif/tools/openocd-esp32/`. Follow these steps: +After downloading the necessary `OpenOCD version `_, extract it to a new folder in the ``.espressif/tools/openocd-esp32/``. -* Download the required `v0.10.0-esp32-20201202 `_ version or a higher one for JTAG Flashing. -* Go to `.../.espressif/tools/openocd-esp32/`, create a new folder named ``v0.10.0-esp32-20201202``, and extract OpenOCD there. -* The resulting path to OpenOCD might look like: ``.../.espressif/tools/openocd-esp32/v0.10.0-esp32-20201202/openocd-esp32/...`` +Follow these steps: -After completing this, update the ``OPENOCD_SCRIPT`` environment variable in Eclipse: +1. Download the required `v0.10.0-esp32-20201202 `_ version or a higher one for JTAG flashing. +2. Go to ``.../.espressif/tools/openocd-esp32/``, create a new folder named ``v0.10.0-esp32-20201202``, and extract OpenOCD there. +3. The resulting path to OpenOCD might look like: ``.../.espressif/tools/openocd-esp32/v0.10.0-esp32-20201202/openocd-esp32/...``. -* Go to ``Eclipse > Preferences > C/C++ > Build > Environment`` -* Edit the ``OPENOCD_SCRIPTS`` variable by providing the correct path to the ``openocd/scripts`` folder. -* The path to the OpenOCD scripts may look like this: ``.../.espressif/tools/openocd-esp32/v0.10.0-esp32-20201202/openocd-esp32/share/openocd/scripts`` +After completing this, update the ``OPENOCD_SCRIPT`` environment variable in Eclipse: +1. Go to ``Eclipse`` > ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment``. +2. Edit the ``OPENOCD_SCRIPTS`` variable by providing the correct path to the ``openocd/scripts`` folder. +3. The path to the OpenOCD scripts may look like this: ``.../.espressif/tools/openocd-esp32/v0.10.0-esp32-20201202/openocd-esp32/share/openocd/scripts``. diff --git a/docs/en/index.rst b/docs/en/index.rst index a39c38cb6..4e9050c5c 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,12 +1,14 @@ Espressif-IDE -========================= +============= + :link_to_translation:`zh_CN:[中文]` Espressif-IDE is an Integrated Development Environment (IDE) based on `Eclipse CDT `_ for developing IoT Applications using the `ESP-IDF `_. It's a standalone and customized IDE built specifically for ESP-IDF. Espressif-IDE comes with the IDF Eclipse plugins, essential Eclipse CDT plugins, and other third-party plugins from the Eclipse platform to support building ESP-IDF applications. -The plug-in runs on `macOS`, `Windows` and `Linux` platforms. +The plug-in runs on **macOS**, **Windows** and **Linux** platforms. + +.. note:: -.. note:: Espressif-IDE version 3.0 and later supports ESP-IDF version 5.x and above. For ESP-IDF version 4.x and earlier, please use Espressif-IDE version `2.12.1 `_. .. image:: ../../media/espressif-ide.png @@ -14,7 +16,7 @@ The plug-in runs on `macOS`, `Windows` and `Linux` platforms. :align: center Features ----------------- +-------- - Auto-configuration of the build environment variables - Integrated toolchain configuration @@ -23,7 +25,7 @@ Features - Pre-built function header and function definition navigation - ESP-IDF and ESP-IDF tools installation and configuration directly from the IDE - SDK configuration editor for project-specific settings -- Integrated CMake editor plug-in for editing CMake files such as CMakeLists.txt +- Integrated CMake editor plug-in for editing CMake files such as ``CMakeLists.txt`` - CMake-based build support - Support for UART and JTAG flashing - Customized ESP-IDF OpenOCD debugging with pre-built configuration and settings @@ -34,23 +36,24 @@ Features - Supports GDB stub debugging and application-level tracing - English and Chinese language support for the IDE -For more about this project please see https://github.com/espressif/idf-eclipse-plugin +For more about this project, please see https://github.com/espressif/idf-eclipse-plugin. Contents ----------------- +-------- + .. toctree:: :maxdepth: 1 Prerequisites Installation - Start a Project - Connect Your Device - Build the Project - Configure Your Project - Flash onto the Device - Monitor the Output - Debug Your Project - Additional IDE Features - Troubleshooting - FAQs - Downloads + Start Your Project + Connect Your Device + Build Your Project + Configure Your Project + Flash the Device + Monitor the Output + Debug Your Project + Additional IDE Features + Troubleshooting + FAQs + Downloads diff --git a/docs/en/monitoroutput.rst b/docs/en/monitoroutput.rst index c3b001d1a..dd4c52c85 100644 --- a/docs/en/monitoroutput.rst +++ b/docs/en/monitoroutput.rst @@ -1,9 +1,11 @@ .. _serialMonitor: Monitor the Output -=============================== +================== -To see the serial output in Eclipse, we need to configure the `ESP-IDF Serial Monitor` to connect to the serial port. This is integrated with the `IDF Monitor `_. +:link_to_translation:`zh_CN:[中文]` + +To view the serial output in Eclipse, you need to configure the ESP-IDF Serial Monitor to connect to the serial port. This is integrated with the `IDF Monitor `_. .. image:: ../../media/monitor.png :alt: Serial Monitor @@ -21,8 +23,9 @@ To launch the serial monitor in the IDE, follow the steps below: ESP-IDF Serial Monitor Settings ------------------------------- + ESP-IDF Serial Monitor will allow you to configure the default settings of the serial monitor character limit and number of lines. -1. Navigate to ``Espressif`` from the Eclipse ``Preferences``. +1. In Eclipse, go to ``Espressif`` > ``Preferences``. 2. Click on ``ESP-IDF Serial Monitor Settings``. -3. Provide ``Console Line Width`` and ``Limit Console Output``. \ No newline at end of file +3. Provide ``Console Line Width`` and ``Limit Console Output``. diff --git a/docs/en/openocddebugging.rst b/docs/en/openocddebugging.rst index 872bb3a56..2a18b1f7b 100644 --- a/docs/en/openocddebugging.rst +++ b/docs/en/openocddebugging.rst @@ -3,110 +3,125 @@ ESP-IDF GDB OpenOCD Debugging ============================= +:link_to_translation:`zh_CN:[中文]` + +Create a New Debug Configuration +-------------------------------- -Create a new debug configuration ---------------------------------- Please follow the below steps to create a new debug configuration: -* Right-click on the project -* ``Debug As`` > ``Debug Configurations...`` This will launch a debug configuration window -* On the left Panel, choose ``ESP-IDF GDB OpenOCD Debugging`` -* Right Click and create ``New Configuration`` This will create a new debug configuration for your project +1. Right-click on the project. +2. Go to ``Debug As`` > ``Debug Configurations...``. This will launch a debug configuration window. +3. On the left panel, choose ``ESP-IDF GDB OpenOCD Debugging``. +4. Right click and create ``New Configuration``. This will create a new debug configuration for your project. Please navigate through each tab and configure project specific settings. -.. note:: +.. note:: + Most of the settings are auto-configured by the plugin. .. image:: ../../media/OpenOCDDebug_4.png The other way to create a debug configuration is from the launch configuration bar: -* Expand list with launch/debug configurations -* Click on ``New Launch Configuration...`` -* Select ``ESP-IDF GDB OpenOCD Debugging`` and double click on it or on ``Next >`` button -* In the ``Debugger`` tab, check if the ``Config options`` is right for your board. -* Click on `Finish` +1. Expand list with launch/debug configurations. +2. Click on ``New Launch Configuration...``. +3. Select ``ESP-IDF GDB OpenOCD Debugging`` and double-click on it or on ``Next >`` button. +4. In the ``Debugger`` tab, check if the ``Config options`` is right for your board. +5. Click on ``Finish``. .. image:: ../../media/OpenOCDDebug_9.png Main Tab -------- + 1. Enter the ``Name`` of this configuration, the default name is "{project_name} Configuration". 2. On the ``Main`` tab below, under ``Project:``, press ``Browse`` button and select the project if it's not selected or you want to change it. -3. In the next line ``C/C++ Application:`` should be a relative path to the elf file, for example, "build\hello_world.elf" for `hello_world` project. If the elf file is not there, then likely this project has not been build yet. After building the project, the elf file will appear there, however, you can change it by pressing "Browse" button. +3. In the next line, ``C/C++ Application:`` should be a relative path to the elf file, for example, ``build/hello_world.elf`` for ``hello_world`` project. If the elf file is not there, then likely this project has not been build yet. After building the project, the elf file will appear there. However, you can change it by pressing ``Browse`` button. -The last section on the ``Main`` tab is ``Build (if required) before launching``. If you don't want to build the project each time you are pressing the ``Debug`` button, click ``Disable auto build``. +The last section on the ``Main`` tab is ``Build (if required) before launching``. If you don't want to build the project each time you click the ``Debug`` button, then select ``Disable auto build``. -Points 1 - 3 are shown below. +Points 1–3 are shown below. .. image:: ../../media/OpenOCDDebug_5.png Debugger Tab ------------ -In the ``Debugger`` tab, all parameters are automatically configured to start debugging, you just need to check if the ``Config options`` line is appropriate for your board. It automatically adjusts based on ``Flash voltage`` and ``Board`` options. If you expand the list of boards, only those that match the selected ``Target`` will appear. So, for example, if the selected target is ``esp32``, you will not see ``ESP32-S2-KALUGA-1`` in the list, to see it there, you need to change the target to ``esp32s2`` first. The second option in the debugger tab, which depends on the target, is the `gdb executable`, which is also automatically and dynamically configured based on the target you choose. -Let's take a look at some other options, that you need to check if they auto configured correctly for you: +In the ``Debugger`` tab, all parameters are automatically configured to start debugging, you just need to check if the ``Config options`` line is appropriate for your board. It automatically adjusts based on ``Flash voltage`` and ``Board`` options. If you expand the list of boards, only those that match the selected ``Target`` will appear. So, for example, if the selected target is ``esp32``, you will not see ``ESP32-S2-KALUGA-1`` in the list. To make it appear, you need to change the target to ``esp32s2`` first. The second option in the Debugger tab is ``GDB executable``, which also depends on the selected target and is automatically configured based on it. + +Let's take a look at some other options, that you need to check if they auto-configured correctly for you: -4. The "Executable path" for OpenOCD is based on eclipse preferences, which are configured after tools installation. Check if the "Actual executable" is correct and if it's not, then likely the tools installation went wrong, so you need to check if tools installed correctly to avoid possible problems. If it's still not correct after tools installation, click on "Browse" and select the path to `openocd.exe` manually. -5. In the next step, please make sure that the GDB port is 3333 if you want to use an internal gdb client and the Tcl port is 6666 if you want to use [Application Level Tracing](https://github.com/espressif/idf-eclipse-plugin#application-level-tracing). Also, check `Config options` as described above. -6. In the `GDB Client Setup` section as described above, the gdb executable should be automatically and dynamically configured based on the target you choose. You can change it, by clicking "Browse" button and selecting the path to the gdb executable. By default, the "Commands" line should be `set mem inaccessible-by-default off`. +4. The ``Executable path`` for OpenOCD is based on Eclipse preferences, which are configured after tools installation. Check if the ``Actual executable`` is correct. If it is not, the tools installation likely failed, so make sure tools are installed properly to avoid potential problems. If ``Actual executable`` is still not correct after tools installation, click on ``Browse`` and select the path to ``openocd.exe`` manually. -Points 4 - 6 are shown below. +5. In the next step, please make sure that the GDB port is 3333 if you want to use an internal GDB client, and the TCL port is 6666 if you want to use :doc:`additionalfeatures/appleveltracing`. Also, check ``Config options`` as described above. + +6. In the ``GDB Client Setup`` section as described above, the GDB executable should be automatically and dynamically configured based on the target you choose. You can change it, by clicking ``Browse`` button and selecting the path to the GDB executable. By default, the ``Commands`` line should be ``set mem inaccessible-by-default off``. + +Points 4-6 are shown below. .. image:: ../../media/OpenOCDDebug_6.png -.. note:: - Update the OpenOCD Config options based on the esp board you've choosen. Please check this `here `_. +.. note:: + + Update the OpenOCD ``Config options`` based on the ESP board you've chosen. See details `here `_. Startup Tab ----------- -7. By default, the binaries will be uploaded to your board before joining a debug session, so there is no need to flash them to the target separately. If for some reason you don't want to do that, you can uncheck the ``Flash every time with application binaries`` option. Also, you can check ``Enable verbose output`` option, this will enable debug level 3 - '-d3'. -8. Under ``Initialization Commands``, “Initial Reset.” and “Enable ARM semihosting” are enabled by default. Then, in entry field below, must be the following lines: - .. code-block:: text +7. By default, the binaries will be uploaded to your board before joining a debug session, so there is no need to flash them to the target separately. If for some reason you don't want to do that, you can uncheck the ``Flash every time with application binaries`` option. Also, you can check ``Enable verbose output`` option, which will enable debug level 3 - ``-d3``. + +8. Under ``Initialization Commands``, ``Initial Reset.`` and ``Enable ARM semihosting`` are enabled by default. Then, the following lines must be entered in the field below: - mon reset halt - flushregs - set remote hardware-watchpoint-limit 2 + .. code-block:: text -Points 7 - 8 are shown below. + mon reset halt + flushregs + set remote hardware-watchpoint-limit 2 + +Points 7-8 are shown below. .. image:: ../../media/OpenOCDDebug_7.png 9. Options ``Load Symbols`` and ``Use project binary`` are selected. -10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The plugin will set this breakpoint at the beginning of the function entered under ``Set break point at:``. Checkout this option and enter the name of the main function e.g. app_main in provided field. -11. Checkout ``Continue`` option. This will make the program to resume after ``mon reset halt`` is invoked per point 8. The program will then stop at breakpoint inserted at app_main. -Points 9 - 11 are shown below. +10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The plugin will set this breakpoint at the beginning of the function specified under ``Set break point at:``. Checkout this option and enter the name of the main function, e.g., ``app_main`` in provided field. + +11. Check the ``Continue`` option. This will make the program resume after ``mon reset halt`` is invoked as described in point 8. The program will then stop at breakpoint inserted at ``app_main``. + +Points 9-11 are shown below. .. image:: ../../media/OpenOCDDebug_8.png Common Tab ---------- -You can save your debug logs to an external file. To do this: -* Goto ``Common`` tab. -* Under ``Standard Input and Output`` section: Select Output file checkbox, enter log file name and path where you want logs to be redirected. -* Apply changes and run your application. +You can save your debug logs to an external file. To do this: -.. note:: - Path to the file can be relative if it's located in the workspace (see screenshot below) +1. Go to ``Common`` tab. +2. Under ``Standard Input and Output`` section, select the ``Output File`` checkbox, then enter the log file name and path where you want logs to be redirected. +3. Apply changes and run your application. .. note:: - When specifying a directory path (ending with a separator like ``/`` or ``\``), the system will automatically append ``openocd.log`` as the filename. For example, entering ``/tmp/logs/`` will create the file as ``/tmp/logs/openocd.log``. - .. image:: ../../media/OpenOCDDebug_13.png + - The path can be relative if the file is located in the workspace (see the screenshot below). + - When specifying a directory path (ending with a separator like ``/`` or ``\``), the system will automatically append ``openocd.log`` as the filename. For example, entering ``/tmp/logs/`` will create the file ``/tmp/logs/openocd.log``. + + +.. image:: ../../media/OpenOCDDebug_13.png Preferences for OpenOCD Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + OpenOCD path is auto-configured based on the ``OPENOCD_SCRIPTS`` path defined in the CDT Build environment variables. .. image:: ../../media/OpenOCDDebug_2.png Start Debugging --------------- -To start debugging, you need to select your debug configuration, change mode from ``Run`` to ``Debug`` and click on launch icon (bug icon). + +To start debugging, you need to select your debug configuration, change mode from ``Run`` to ``Debug`` and click on launch icon (i.e., bug icon). .. image:: ../../media/OpenOCDDebug_10.png @@ -114,18 +129,19 @@ After stopping the target at the default breakpoint, you will be suggested to sw .. image:: ../../media/OpenOCDDebug_11.png -You can customize the ``Debug perspective`` in your own way, for example, move some tabs, add additional views that you might find useful, or remove them. To add a view, follow these steps: +You can customize the ``Debug perspective`` to suit your preferences. For example, you can move some tabs, add additional views that you may find useful, or remove the ones you do not need. To add a view, follow these steps: -* On the top panel of the Eclipse click on ``Window`` -* ``Show View`` -* Select the view you want to add +1. On the top panel of the Eclipse, click on ``Window``. +2. Select ``Show View``. +3. Select the view you want to add. .. image:: ../../media/OpenOCDDebug_12.png Troubleshooting --------------- -* Please make sure you always have the latest `Espressif-IDE `_ . -* Please check `this `_ if the board has JTAG enabled. + +* Please make sure you always have the latest `Espressif-IDE `_. +* If your board supports JTAG, see `this page `_ for more details. * If there is any OpenOCD timeout issue, please increase the GDB server timeout value ``_ from the preferences. Usually, this happens while working with large-size applications. -* If you see any error while debugging, please check this OpenOCD troubleshooting `FAQ guide `_ and see if that helps to resolve the issue. -* If you have any issue and want to enable OpenOCD debugging verbose, please check Enable verbose output option from the startup tab. +* If you encounter any errors while debugging, please refer to the OpenOCD `Troubleshooting FAQ `_ to see if it helps resolve the issue. +* If you have any issue and want to enable OpenOCD debugging verbose, please check the ``Enable verbose output`` option from the ``Startup`` tab. diff --git a/docs/en/startproject.rst b/docs/en/startproject.rst index df41d5384..e2426b7df 100644 --- a/docs/en/startproject.rst +++ b/docs/en/startproject.rst @@ -1,54 +1,64 @@ .. _startproject: -Start a Project -=============================== +Start Your Project +================== + +:link_to_translation:`zh_CN:[中文]` To get started with the Espressif-IDE, you can create a new project or import an existing project. -1. :ref:`Create a New Project ` -2. :ref:`Create a New Project Using ESP-IDF Templates ` -3. :ref:`Import an Existing Project ` +- :ref:`Create a New Project ` +- :ref:`Create a New Project Using ESP-IDF Templates ` +- :ref:`Import an Existing Project ` .. _newproject: Create a New Project ---------------------- +-------------------- + To create a new Project in the Espressif-IDE, follow the steps below: -#. Go to ``File`` > ``New`` > ``Espressif IDF Project``. -#. Provide the ``Project name`` -#. Click ``Finish``. +#. Go to ``File`` > ``New`` > ``Espressif IDF Project``. + + .. image:: ../../media/newproject_menu.png + :alt: New Project Menu + +#. Provide the ``Project name``. +#. Click ``Finish``. .. Note:: + The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. -.. image:: ../../media/newproject_menu.png .. _newprojecttemplate: Create a New Project Using ESP-IDF Templates ---------------------------------------------- -Espressif-IDE also offers the ability to create a project using the ESP-IDF templates, which can be accessed by following the steps below: +-------------------------------------------- + +Espressif‑IDE also allows you to create a project from ESP‑IDF templates, which can be accessed by following the steps below: #. Go to ``File`` > ``New`` > ``Espressif IDF Project``. #. Choose a target board from the ``Select Project Target`` dropdown. -#. Click on ``Create a project using one of the templates`` from the Templates section. +#. Click on ``Create a project using one of the templates`` from the ``Template Selection`` section. #. Select the template you want to use and that automatically fills the project name based on the template selected. #. Click ``Finish``. - .. image:: ../../media/3_new_project_default.png - +.. image:: ../../media/3_new_project_default.png .. note:: - You may see numerous unresolved headers and symbols errors in the editor, and these will only be resolved after the build process. + + You may see numerous unresolved header and symbol errors in the editor. These will be resolved only after the build process. + .. _importproject: Import an Existing Project ---------------------------- +-------------------------- + To import an existing project into the Espressif-IDE, please make sure that is a CMake project. Follow the steps below: -#. Right-click in the ``Project Explorer``. +#. Right-click the ``Project Explorer``. #. Select ``Import..`` Menu. #. Select ``Existing IDF Project`` from ``Espressif`` import wizard menu list. #. Click ``Next``. @@ -57,6 +67,3 @@ To import an existing project into the Espressif-IDE, please make sure that is a #. Click ``Finish`` to import the selected project into Eclipse workspace as a CMake project. .. image:: ../../media/5_import_project.png - - - diff --git a/docs/zh_CN/additionalfeatures.rst b/docs/zh_CN/additionalfeatures.rst index 2e2908ad5..973d09afb 100644 --- a/docs/zh_CN/additionalfeatures.rst +++ b/docs/zh_CN/additionalfeatures.rst @@ -1 +1,24 @@ -.. include:: ../en/additionalfeatures.rst \ No newline at end of file +其他 IDE 功能 +============= + +:link_to_translation:`en:[English]` + +.. toctree:: + :maxdepth: 1 + + LSP C/C++ 编辑器 + CMake 编辑器 + ESP-IDF 应用程序大小分析 + ESP-IDF 终端 + 安装 ESP-IDF 组件 + 堆跟踪 + ESP-IDF OpenOCD 调试 + GDB stub 调试 + 核心转储调试 + 应用级跟踪 + 分区表编辑器 + NVS 分区编辑器 + 将二进制文件写入 flash + DFU 烧录 + Wokwi 仿真器 + 切换语言 diff --git a/docs/zh_CN/configureproject.rst b/docs/zh_CN/configureproject.rst index fc69f45cb..3866e6b6c 100644 --- a/docs/zh_CN/configureproject.rst +++ b/docs/zh_CN/configureproject.rst @@ -1 +1,20 @@ -.. include:: ../en/configureproject.rst +配置项目 +======== + +:link_to_translation:`en:[English]` + +项目配置保存在项目根目录下一个名为 ``sdkconfig`` 的文件中。可以使用 SDK 配置编辑器修改该配置文件。 + +.. note:: + + ``sdkconfig`` 文件仅在构建之后才会生成。因此，建议在配置项目之前先构建一次项目。 + +可参照下列步骤，启动 SDK 配置编辑器： + +#. 找到 ``sdkconfig`` 文件。 +#. 双击该文件以启动 SDK 配置编辑器。 +#. 根据操作系统使用 ``Ctrl+S`` 或 ``Command+S`` 保存更改。也可以使用 Eclipse 工具栏中的 ``Save`` 按钮来保存。 +#. 若想撤销在 SDK 配置编辑器中所做的更改，可以在不保存的情况下关闭编辑器，或右键单击 ``sdkconfig`` 文件并选择 ``Load sdkconfig``，在编辑器中还原更改。 + +.. image:: ../../media/13_sdkconfig_editor.png + :alt: SDK 配置编辑器 diff --git a/docs/zh_CN/connectdevice.rst b/docs/zh_CN/connectdevice.rst index 35eddd77b..ef2b643b3 100644 --- a/docs/zh_CN/connectdevice.rst +++ b/docs/zh_CN/connectdevice.rst @@ -1 +1,24 @@ -.. include:: ../en/connectdevice.rst +连接设备 +======== + +:link_to_translation:`en:[English]` + +点击齿轮图标，选择项目的目标芯片以及设备的串口。如果在创建项目时已完成设置，则忽略此步。默认情况下，启动目标下拉菜单会显示插件支持的所有目标芯片。 + +.. image:: ../../media/target_selection.png + +点击齿轮图标可以打开 ``ESP Target`` 配置对话框，选择设备的串口并指定乐鑫开发板。插件会自动检测连接到电脑的串口。 + +.. image:: ../../media/8_launch_target.png + +关于串口及其命名规则，请参考 `ESP-IDF 文档 `_。 + +自定义目标 +---------- + +如果需要添加不在启动目标下拉菜单中的目标，请参照以下步骤： + +1. 点击启动目标下拉菜单。 +2. 选择 ``New Launch Target``。 +3. 选择 ``ESP Target``。 +4. 指定要启动应用程序的目标设备属性。为该目标输入 ``Name``，并选择电脑上乐鑫设备所连接的 ``Serial Port``。 diff --git a/docs/zh_CN/downloads.rst b/docs/zh_CN/downloads.rst index b42d3a078..05f8ed2f2 100644 --- a/docs/zh_CN/downloads.rst +++ b/docs/zh_CN/downloads.rst @@ -1 +1,39 @@ -.. include:: ../en/downloads.rst +.. _downloads: + +下载 Espressif-IDE +=================== + +:link_to_translation:`en:[English]` + +点击 `此处 `_ 可查看最新的 Espressif-IDE 发行说明。下面提供了各平台的直接下载链接。 + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - 操作系统 + - 下载链接 + * - Windows + - `Espressif-IDE-win32.win32.x86_64 `_ + * - macOS x86_64 + - `Espressif-IDE-macosx-cocoa-x86_64 `_ + * - macOS aarch64 + - `Espressif-IDE-macosx-cocoa-aarch64 `_ + * - Linux + - `Espressif-IDE-linux.gtk.x86_64 `_ + + +macOS 安全注意事项（仅适用于每日自动构建的测试版本） +---------------------------------------------------- + +在 macOS 上，如果通过浏览器下载压缩包，则新版的 macOS 会严格进行安全检查，阻止其运行并提示程序已损坏。该提示并不属实，解决方法很简单：只需移除 ``com.apple.quarantine`` 扩展属性即可。 + +.. code-block:: shell + + $ xattr -d com.apple.quarantine ~/Downloads/Espressif-IDE-x.x.x-macosx.cocoa.x86_64.tar.gz + +解压缩文件后，如果应用程序仍然出现相同的警告，请检查 ``Espressif-IDE.app`` 文件夹并删除该属性： + +.. code-block:: shell + + $ xattr -dr com.apple.quarantine ~/Downloads/Espressif-IDE.app diff --git a/docs/zh_CN/faqs.rst b/docs/zh_CN/faqs.rst index 4cb537d7d..fd9819956 100644 --- a/docs/zh_CN/faqs.rst +++ b/docs/zh_CN/faqs.rst @@ -1 +1,209 @@ -.. include:: ../en/faqs.rst +常见问题 +======== + +:link_to_translation:`en:[English]` + +如何查看系统中已安装的 Java 版本？ +------------------------------------ + +可以在终端使用 ``java -version`` 命令进行检查。 + +如何查看 Eclipse 使用的 Java 版本？ +------------------------------------- + +1. 前往 ``Help`` > ``About Eclipse`` > ``Installation Details`` > ``Configuration``。 +2. 查找 ``-vm`` 参数。 + +使用 Eclipse IDE 时，如何增大 Java 的堆内存？ +---------------------------------------------- + +1. 找到 ``eclipse.ini`` 或 ``espressif-ide.ini``。 +2. 在 ``-vmargs`` 参数部分增大 Xmx 值。 例如，可以设置为 ``-Xmx2048m``。 + +该插件支持哪些操作系统？ +------------------------ + +- Windows +- macOS +- Linux + +如何提供 Eclipse 环境与插件信息？ +--------------------------------- + +``Help`` > ``About Eclipse`` > ``Installation Details`` > ``Configuration`` > ``Copy to Clipboard`` + +如何查看已安装的 IDF Eclipse 插件版本？ +---------------------------------------- + +1. 前往菜单栏 ``Eclipse`` > ``About Eclipse`` > ``Installation Details`` > ``Installed Software`` 查看。 +2. 搜索 Espressif。 + +如何从 Eclipse 卸载 IDF Eclipse 插件？ +-------------------------------------- + +1. 前往菜单栏 ``Eclipse`` > ``About Eclipse`` > ``Installation Details`` > ``Installed Software``。 +2. 搜索 Espressif。 +3. 选择 ``Espressif IDF Feature``。 +4. 点击 ``Uninstall..``。 + +为什么在 Eclipse 中无法安装 IDF 插件？ +--------------------------------------- + +请从主菜单检查错误日志: + +1. 前往 ``Window`` > ``Show View`` > ``Other``。 +2. 选择 ``General`` > ``Error Log``。 + +为什么在我的 Eclipse CDT 中看不到 Espressif 菜单选项和 Espressif IDF Project 菜单？ +--------------------------------------------------------------------------------------- + +1. 请确保已安装 Java 8 及以上版本，并在 Eclipse 中切换到 C/C++ 布局模式。 +2. 前往 ``Window`` > ``Perspective`` > ``Reset Perspective..`` 可重置布局模式。 + +IDF Eclipse 插件是否支持创建 CMake IDF 项目？ +---------------------------------------------------------- + +可以通过 ``File`` > ``New`` > ``Espressif IDF Project`` 创建 IDF CMake 项目。 + +是否可以将现有的 IDF 项目导入 Eclipse？ +---------------------------------------- + +可以通过导入菜单进行导入：``Import...`` > ``Espressif`` > ``Existing IDF Project``。 + +系统中 IDF 安装的工具位于哪里？ +---------------------------------- + +Linux/MacOS 用户的默认目录为 ``$HOME/.espressif``，Windows 用户为 ``%USER_PROFILE%.espressif``。 + +为什么删除的 C/C++ 构建环境变量仍然显示？ +------------------------------------------ + +你需要取消勾选首选项记录器。步骤如下： + +1. 在 Eclipse 中前往 ``Preferences`` > ``Oomph`` > ``Setup Tasks`` > ``Preference Recorder``。 +2. 取消勾选 ``Record into``。 + +如何回退到旧版 ESP-IDF Eclipse 插件？ +----------------------------------------- + +1. 打开 Eclipse IDE 并卸载 ESP-IDF 插件。 +2. 重启 Eclipse IDE。 +3. 从发布页面下载旧版 ESP Eclipse 插件。 +4. 前往 ``Help`` > ``Install New Software``。 +5. 点击 ``Add`` 按钮，会弹出名为 ``Add Repository`` 的窗口。 +6. 点击 ``Archive`` 按钮并选择已下载的文件。 +7. 继续安装。 +8. 重启 Eclipse。 + +在项目中哪里可以找到 ``compile_commands.json`` 文件？ +-------------------------------------------------------------- + +该文件存储在 ``/projectName/build/compile_commands.json``。 + +``compile_commands.json`` 以机器可读的格式记录了项目中所有翻译单元的完整编译器调用信息。Eclipse CDT 的索引器会使用该文件来解析代码并定位头文件。 + +如何访问 CDT 解析器的错误日志？ +----------------------------------- + +前往 ``Project`` > ``C/C++ Index`` > ``Create Parser Log``。 + +如何查看错误日志？ +------------------- + +在主菜单中选择 ``Window`` > ``Show View`` > ``Other``，然后选择 ``General`` > ``Error Log``。 + +如何报告死锁或 Eclipse 卡死？ +------------------------------------------- + +详细说明请参阅：https://wiki.eclipse.org/How_to_report_a_deadlock。 + +在命令行中，使用 ``jps -v`` 查找 Java 进程的 PID；使用 ``jstack `` 显示 Java 进程的堆栈跟踪。 + +此处 32308 和 8824 是 Java 进程的 PID。8824 是 jps 本身，与我们无关。根据其命令行中包含 ``org.eclipse.equinox.launcher`` 可以判断 32308 是一个 Eclipse 进程。``jstack`` 命令会将该 Eclipse 进程的堆栈跟踪保存到文件 ``/tmp/jstack.txt``，请将该文件附在问题报告中。 + +为什么会出现 ``sun.security.validator.ValidatorException: PKIX path building failed`` 报错？ +-------------------------------------------------------------------------------------------- + +这通常是由错误的 Java 版本或缺失的 Java 证书导致。请确保已安装 **Java 11 或更高版本** 以修复该问题。详情请查看以下链接： + +- https://esp32.com/viewtopic.php?f=13&t=12327&start=10#p50137 +- https://stackoverflow.com/questions/6908948/java-sun-security-provider-certpath-suncertpathbuilderexception-unable-to-find + +为何建议在 IDF Eclipse 插件中使用 Java 11？ +--------------------------------------------- + +我们建议在使用 IDF Eclipse 插件时采用 Java 11 及以上版本（这是 Oracle 最新的 LTS 版本），因为 Eclipse 2020-06 要求使用 Java 11 才能运行 CDT。以下是来自 Eclipse 的一些重要提示： + +- `在 Eclipse 2020-06 及之后版本上使用 Java 8 安装 CDT 9.11 时需要变通办法 `_。 + + 运行 CDT 9.11 仅需 Java 8。不过，Eclipse 2020-06 及之后版本中的一个新功能可能会阻止安装向导执行安装操作。变通办法是在 ``Windows`` > ``Preferences`` > ``Install/Update`` 中关闭 "Verify provisioning operation is compatible with the currently running JRE"。参见 https://bugs.eclipse.org/bugs/show_bug.cgi?id=564407#c1。 + +- `CDT 10.0 需要 Java 11 或更高版本 `_。 + + 从 CDT 10.0 开始，运行 CDT 需要 Java 11 或更高版本。这与 Eclipse IDE 的要求一致，后者自 2020-09 起也需要 Java 11 才能运行。 + +如何在 Eclipse 中删除运行目标？ +-------------------------------- + +Eclipse 中没有直接删除运行目标 (launch target) 的 UI 选项，不过可以参照以下步骤实现： + +1. 前往 Eclipse 工作区目录。 例如，我的路径是 ``/Users/myName/myTesteclipseWorkspace``。 +2. 在工作区目录中，进入 ``.metadata/.plugins/org.eclipse.core.runtime/.settings`` 文件夹。 +3. 找到 ``org.eclipse.launchbar.core.prefs`` 文件并在编辑器中打开。 +4. 搜索要删除的运行目标名称，并从文件中删除其对应的所有条目。 +5. 保存文件。 +6. 重启 Eclipse。 + +如何获取项目构建日志？ +---------------------- + +1. 若想启用日志记录，请前往 ``Preferences`` > ``Project`` > ``C/C++`` > ``Build`` > ``Logging``。 +2. 勾选 ``Enable global build logging``。 +3. 构建项目。 +4. 导出 ``global-build.log``。该日志与 CDT 构建控制台中显示的构建控制台日志相同，但构建控制台通常有 buffer 大小限制，因此不会显示全部内容。 + +如何为项目构建启用详细调试输出？ +-------------------------------- + +IDF Eclipse 插件使用 CMake 命令来构建项目，因此可以通过构建配置向导传递 CMake 参数。配置方法如下： + +1. 点击编辑器配置向导。 +2. 切换到 ``Build Settings`` 选项卡。 +3. 添加 ``--debug-output`` 或其他参数。 + +如何在 Espressif-IDE 中构建多个配置？ +---------------------------------------- + +1. 创建一个新项目。 +2. 打开 ``Launch Configuration`` 对话框。 +3. 进入 ``Build Settings`` 选项卡，在 ``Additional CMake Arguments`` 中输入 ``-B build_release``。其中，``build_release`` 是构建文件夹的名称。 +4. 点击 ``OK`` 按钮保存该配置。 +5. 重新打开 ``Launch Configuration`` 对话框。 +6. 点击左下角的 ``Duplicate`` 按钮。 +7. 进入 ``Build Settings`` 选项卡，将 ``Additional CMake Arguments`` 更新为 ``-B build_dev``。其中，``build_dev`` 是构建文件夹的名称。 +8. 点击 ``OK`` 按钮保存该配置。 +9. 在工具栏中点击所选配置的 ``Build`` 图标（最左侧图标），这将为该配置构建项目并创建一个构建文件夹。然后在下拉菜单中选择另一配置，重复相同的步骤。 + +可以将我之前的 C/C++ 编辑器格式化文件 (.xml) 用作 ``.clang-format`` 文件吗？ +---------------------------------------------------------------------------- + +不可以。不能在 ESP-IDF 项目中直接使用旧的 ``.xml`` （CDT 格式化工具）文件，因为目前使用的是 CDT LSP 编辑器，其代码格式化依赖 Clangd。Clangd 需要 ``.clang-format`` 文件，而且没有官方工具可以将 ``.xml`` 格式化文件转换为 Clang 格式。 + +不过，你可以参考 Clang 提供的若干默认的格式化风格（例如 LLVM、Google、Mozilla 等）。使用以下命令可以生成默认的 ``.clang-format`` 文件： + +.. code-block:: none + + clang-format -style=llvm -dump-config > .clang-format + +新建 ESP-IDF 项目时，根目录会自动创建带默认设置的 ``.clang-format`` 文件。Clangd 会自动识别该文件，无需额外配置。 + +对于现有项目，可以右键点击项目并选择 ``ESP-IDF`` > ``Create Clangd File``，手动创建 ``.clang-format`` 文件。 + +如果想复现旧的格式化设置，可以： + +- 手动依据 Clang 的格式化指南，将 ``.xml`` 设置映射到 Clang 格式。 +- 或者使用 AI 工具（例如 ChatGPT）将旧配置转换为新配置，然后再手动调整差异。 + +更多有关 Clang 格式的信息请参阅 `ClangFormat 文档 `_。 + +关于格式化风格，请参阅 `Clang-Format 风格选项 `_。 diff --git a/docs/zh_CN/flashdevice.rst b/docs/zh_CN/flashdevice.rst index 7bb5c3de5..a3cf45744 100644 --- a/docs/zh_CN/flashdevice.rst +++ b/docs/zh_CN/flashdevice.rst @@ -1 +1,120 @@ -.. include:: ../en/flashdevice.rst +烧录项目 +======== + +:link_to_translation:`en:[English]` + +.. |run_icon| image:: ../../media/icons/run.png + :height: 16px + :align: middle + +只需点击启动按钮 |run_icon| 即可开始烧录，该过程会自动使用默认命令 ``idf.py -p PORT flash`` 来烧录应用程序。 + +.. image:: https://github.com/espressif/idf-eclipse-plugin/assets/8463287/3249c01b-af23-4863-811f-c3959008f257 + :width: 767px + :alt: 烧录 + +- 如需自定义烧录参数，请参照 :ref:`本指南 ` 中的说明。 +- 如需启用 flash 加密，请参阅 :ref:`flash 加密 `。 +- 如需通过 JTAG 进行烧录，请参阅 :ref:`JTAG 烧录 `。 + +.. _customizeLaunchConfig: + +自定义烧录参数 +-------------- + +如需提供自定义的启动配置和烧录参数，请按以下步骤操作： + +#. 点击 ``Launch Configuration`` 编辑按钮。 +#. 切换到 ``Main`` 选项卡。 +#. 指定应用需运行的 ``Location``。``idf.py`` 是一个 Python 文件，所以请配置 Python 系统路径。例如：``${system_path:python}``。 +#. 指定应用的 ``Working directory``。例如：``${workspace_loc:/hello_world}``。 +#. 在 ``Arguments`` 字段中（见图片中的 ``1``），默认使用 **动态变量**： + + ``${IDF_PY} -B ${BUILD_DIR} -p ${serial_port} ${flash_command}`` + + 该默认设置会基于项目和开发板自动适配，通常无需手动更改。 + + - 点击 ``Preview`` 图标（见图片中的 ``2``）可在显示已解析的值与原始动态变量之间切换。 + - **仅在** 显示动态变量（未解析）时，此字段才可修改。 + - 如果从旧版本的插件迁移至新版本，则该字段不包含动态变量，请点击 ``Restore defaults`` （见图片中的 ``3``）进行重置。 + +#. 点击 ``OK`` 保存设置。 +#. 点击 ``Launch`` 图标，将应用烧录至所选开发板。 + +.. image:: ../../media/launch_configuration.png + :alt: 启动配置 + +.. image:: ../../media/12_flashing.png + :alt: 烧录过程 + + +.. _flashEncryption: + +flash 加密 +---------- + +.. warning:: + + 启用 flash 加密是 **不可逆的操作**。若配置不当，开发板可能会永久无法使用。请谨慎操作，仅在完全理解其影响时才启用该选项。 + +如需在 ESP‑IDF 中启用 flash 加密，请按以下步骤操作： + +#. 打开 ``sdkconfig``，启用 ``Enable flash encryption on boot`` 选项。 + + .. image:: ../../media/flash_encryption_1.png + :alt: flash 加密 sdkconfig + +#. 先正常烧录一次应用。 +#. 打开 ``Launch Configuration`` 对话框，编辑该配置，并勾选 ``Enable Flash Encryption`` 复选框。 + + .. image:: ../../media/flash_encryption_2.png + :alt: flash 加密复选框 + +#. 再次烧录应用。 + +启用该选项后，系统将根据 ESP‑IDF 设置自动对 flash 内容进行加密保护。 + +详情请参阅官方的 `flash 加密文档 `_。 + + +.. _JTAGFlashing: + +通过 JTAG 上传应用 +------------------ + +上传应用程序的默认方式是使用 UART。若要改用 JTAG，请编辑项目的启动配置并选择相应选项。 + +具体做法是，在启动配置栏中选择项目，点击齿轮图标以编辑启动配置： + +.. image:: ../../media/JtagFlash_1.png + :alt: 编辑启动配置 + +然后选择 ``Flash Over JTAG`` 选项，并完成 ``OpenOCD Setup`` 部分的配置。 + +.. image:: https://user-images.githubusercontent.com/24419842/226183857-f9d8569b-05b0-4b52-b0b2-293aac493020.png + :width: 986px + :alt: 通过 JTAG 烧录选项 + +如果没有 ``Flash Over JTAG`` 选项，并看到如下提示： + +.. image:: ../../media/JtagFlash_3.png + :alt: 需要更新 OpenOCD 的提示 + +这表示需要更新 OpenOCD。可在 `openocd-esp32 GitHub 页面 `_ 获取最新的 OpenOCD 版本。 + +为 OpenOCD 提供正确的路径 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +下载所需的 `OpenOCD 版本 `_，并将其解压到 ``.espressif/tools/openocd-esp32/`` 下的新文件夹中。 + +请参照以下步骤进行操作： + +1. 下载 JTAG 烧录所需的 `v0.10.0-esp32-20201202 `_ 版本或更高版本。 +2. 进入 ``.../.espressif/tools/openocd-esp32/`` 文件夹，并创建名为 ``v0.10.0-esp32-20201202`` 的新文件夹，将 OpenOCD 解压至此处。 +3. 最终的 OpenOCD 路径类似：``.../.espressif/tools/openocd-esp32/v0.10.0-esp32-20201202/openocd-esp32/...``。 + +完成上述操作后，在 Eclipse 中更新 ``OPENOCD_SCRIPT`` 环境变量： + +1. 前往 ``Eclipse`` > ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment``。 +2. 编辑 ``OPENOCD_SCRIPTS`` 变量，填入指向 ``openocd/scripts`` 文件夹的正确路径。 +3. OpenOCD 脚本的路径类似：``.../.espressif/tools/openocd-esp32/v0.10.0-esp32-20201202/openocd-esp32/share/openocd/scripts``。 diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst index 58446d485..43ef60c7a 100644 --- a/docs/zh_CN/index.rst +++ b/docs/zh_CN/index.rst @@ -1 +1,59 @@ -.. include:: ../en/index.rst \ No newline at end of file +Espressif-IDE +============= + +:link_to_translation:`en:[English]` + +Espressif-IDE 是基于 `Eclipse CDT `_ 的集成开发环境 (IDE)，用于开发 `ESP-IDF `_ 物联网应用。该独立 IDE 专为 ESP-IDF 打造，内置了 ESP-IDF 的 Eclipse 插件、Eclipse CDT 的基本插件，以及其他辅助开发的第三方插件，可支持 ESP-IDF 应用的构建。 + +该插件可在 **macOS**、**Windows** 和 **Linux** 平台上运行。 + +.. note:: + + Espressif-IDE 3.0 及以上版本支持 ESP-IDF 5.x 及以上版本。对于 ESP-IDF 4.x 及更早版本，请使用 Espressif-IDE `2.12.1 版本 `_。 + +.. image:: ../../media/espressif-ide.png + :alt: Espressif-IDE + :align: center + +功能 +---- + +- 自动配置构建环境的变量 +- 配置集成的工具链 +- 新建项目向导与 ESP-IDF 入门示例 +- 基于 LSP 的编辑器，提供高级编辑、编译及语法高亮功能 +- 自动生成函数声明与快速跳转到函数定义 +- 可在 IDE 中直接安装和配置 ESP-IDF 及 ESP-IDF 工具 +- 用于项目专属设置的 SDK 配置编辑器 +- 集成的 CMake 编辑器插件，用于编辑 CMake 文件，例如 ``CMakeLists.txt`` +- 基于 CMake 的构建支持 +- 支持通过 UART 与 JTAG 烧录 +- ESP-IDF 专用 OpenOCD 调试功能，且内置预设配置 +- 集成的 ESP-IDF 串口监视器 +- 已预先配置好 ESP-IDF 构建环境的 ESP-IDF 专用终端 +- 应用大小分析编辑器，用于分析应用的静态内存占用情况 +- 支持堆分析，用于内存使用情况分析和内存泄漏检测 +- 支持 GDB stub 调试与应用级跟踪 +- IDE 支持中英双语界面 + +更多有关该项目的信息请参阅 https://github.com/espressif/idf-eclipse-plugin。 + +目录 +---- + +.. toctree:: + :maxdepth: 1 + + 准备工作 + 安装 + 启动项目 + 连接设备 + 构建项目 + 配置项目 + 烧录设备 + 监视输出 + 调试项目 + 其他 IDE 功能 + 故障排查 + 常见问题 + 下载 diff --git a/docs/zh_CN/monitoroutput.rst b/docs/zh_CN/monitoroutput.rst index f8f89bd09..31aa385fd 100644 --- a/docs/zh_CN/monitoroutput.rst +++ b/docs/zh_CN/monitoroutput.rst @@ -1 +1,31 @@ -.. include:: ../en/monitoroutput.rst +.. _serialMonitor: + +监视输出 +======== + +:link_to_translation:`en:[English]` + +要在 Eclipse 中查看串口输出，需要将 ESP-IDF 串口监视器连接到串口。该监视器已与 `IDF 监视器 `_ 集成。 + +.. image:: ../../media/monitor.png + :alt: 串口监视器 + +要在 IDE 中启动串口监视器，请按以下步骤操作： + +1. 单击顶部工具栏中的 ``Open a Terminal`` 图标。 +2. 在终端下拉菜单中选择 ``ESP-IDF Serial Monitor``。 +3. 如果 IDE 未自动检测到你的开发版，则为其选择 ``Serial Port``。 +4. 配置串口监视器的 ``Filter Options`` 以过滤输出。 +5. 单击 ``OK`` 以启动监视器，监听 USB 端口。 + +.. image:: ../../media//10_serial_terminal.png + + +ESP-IDF 串口监视器设置 +----------------------- + +你可以自定义 ESP-IDF 串口监视器的默认字符数限制和行数。 + +1. 在 Eclipse 中，前往 ``Preferences`` > ``Espressif``。 +2. 单击 ``ESP-IDF Serial Monitor Settings``。 +3. 设置 ``Console Line Width`` 和 ``Limit Console Output``。 diff --git a/docs/zh_CN/openocddebugging.rst b/docs/zh_CN/openocddebugging.rst index df59e4d64..dc3a2bdee 100644 --- a/docs/zh_CN/openocddebugging.rst +++ b/docs/zh_CN/openocddebugging.rst @@ -1 +1,147 @@ -.. include:: ../en/openocddebugging.rst +.. _OpenOCDDebugging: + +ESP-IDF GDB OpenOCD 调试 +======================== + +:link_to_translation:`en:[English]` + +创建新的调试配置 +---------------- + +请按照以下步骤创建新的调试配置： + +1. 右键点击项目。 +2. 前往 ``Debug As`` > ``Debug Configurations...``，打开调试配置窗口。 +3. 在左侧面板中选择 ``ESP-IDF GDB OpenOCD Debugging``。 +4. 点击右键并创建 ``New Configuration``，为项目创建新的调试配置。 + +请逐个查看标签页并配置项目专属设置。 + +.. note:: + + 插件能自动配置大多数设置。 + +.. image:: ../../media/OpenOCDDebug_4.png + +也可以通过启动配置栏来创建调试配置： + +1. 展开启动或调试配置的列表。 +2. 点击 ``New Launch Configuration...``。 +3. 选择 ``ESP-IDF GDB OpenOCD Debugging`` 并双击此选项，也可以点击 ``Next >`` 按钮。 +4. 在 ``Debugger`` 标签页中，检查 ``Config options`` 是否适用于你的开发板。 +5. 点击 ``Finish``。 + +.. image:: ../../media/OpenOCDDebug_9.png + +Main 标签页 +------------ + +1. 输入此配置的 ``Name``，默认名称为 "{project_name} Configuration"。 +2. 在 ``Main`` 标签页中，找到 ``Project:`` 一栏，点击 ``Browse`` 按钮来选择或更改当前项目。 +3. 下一行的 ``C/C++ Application:`` 是指向 elf 文件的相对路径，例如 ``build/hello_world.elf``，对应 ``hello_world`` 项目。若不存在 elf 文件，则此项目可能尚未构建。构建项目后，该 elf 文件会出现，也可以点击 ``Browse`` 按钮进行更改。 + +``Main`` 标签页中的最后一栏是 ``Build (if required) before launching``。如果不想在每次点击 ``Debug`` 按钮时都构建项目，则选择 ``Disable auto build`` 选项。 + +上述第 1 至 3 点如下图所示。 + +.. image:: ../../media/OpenOCDDebug_5.png + +Debugger 标签页 +--------------- + +在 ``Debugger`` 标签页中，所有参数都会自动配置以开始调试，你只需检查 ``Config options`` 是否适用于你的开发板即可。该选项会根据 ``Flash voltage`` 和 ``Board`` 选项自动调整。展开开发板列表时，只会显示与所选 ``Target`` 相匹配的条目。举例来说，如果所选目标芯片是 ``esp32``，列表中不会显示 ``ESP32-S2-KALUGA-1``。若希望显示该开发版，需要先将目标芯片改为 ``esp32s2``。``Debugger`` 标签页中的第二个选项是 ``GDB executable``，该选项同样依赖于所选目标芯片，并会根据目标自动进行配置 + +还有一些其他选项，建议检查这些选项是否已自动正确配置： + +4. OpenOCD 的 ``Executable path`` 基于 Eclipse 的首选项，该路径会在安装工具后配置。请检查 ``Actual executable`` 是否正确，如果不正确，很可能是工具安装有问题，因此需要检查工具是否正确安装以避免潜在问题。若在安装工具后 ``Actual executable`` 仍不正确，则点击 ``Browse`` 并手动选择 ``openocd.exe`` 的路径。 + +5. 接下来，如果要使用内置 GDB 客户端，请确保 GDB 端口为 3333；如果要使用 :doc:`additionalfeatures/appleveltracing`，请确保 TCL 端口为 6666。另请按前文所述检查 ``Config options``。 + +6. 如上所述，在 ``GDB Client Setup`` 部分中，GDB 可执行文件会根据所选目标自动配置。你也可以点击 ``Browse`` 按钮，手动更改为 GDB 可执行文件的路径。默认情况下，``Commands`` 一行应为 ``set mem inaccessible-by-default off``。 + +上述第 4 至 6 点如下图所示。 + +.. image:: ../../media/OpenOCDDebug_6.png + +.. note:: + + 请根据已选择的乐鑫开发板更新 OpenOCD 的 ``Config options``。详情请参考 `此处 `_。 + +Startup 标签页 +-------------- + +7. 默认情况下，在加入调试会话前会将二进制文件烧录至开发板，因此无需单独将其烧录到目标芯片上。若出于某些原因不想自动烧录，可以取消勾选 ``Flash every time with application binaries`` 选项。也可以勾选 ``Enable verbose output`` 选项，启用第三调试等级 – ``-d3``。 + +8. 在 ``Initialization Commands`` 栏目下，``Initial Reset.`` 和 ``Enable ARM semihosting`` 已默认启用，且在输入框中必须填写如下几行内容： + + .. code-block:: text + + mon reset halt + flushregs + set remote hardware-watchpoint-limit 2 + +上述第 7 至 8 点如下图所示。 + +.. image:: ../../media/OpenOCDDebug_7.png + +9. 勾选 ``Load Symbols`` 和 ``Use project binary`` 选项。 + +10. 在 ``Startup`` 标签页中向下滚动，设置初始断点，以便在调试器复位 CPU 之后暂停 CPU 的运行。插件会在 ``Set break point at:`` 中指定的函数开头设置此断点。勾选该选项，并在输入框中输入主函数名，例如 ``app_main``。 + +11. 勾选 ``Continue`` 选项。这样，当按照第 8 步调用 ``mon reset halt`` 命令后，程序将自动继续执行，并在 ``app_main`` 函数的断点处停止。 + +上述第 9 至 11 点如下图所示。 + +.. image:: ../../media/OpenOCDDebug_8.png + +Common 标签页 +------------- + +可以将调试日志保存为外部文件。操作步骤如下所示： + +1. 打开 ``Common`` 标签页。 +2. 在 ``Standard Input and Output`` 部分，勾选 ``Output File`` 复选框，然后输入希望重定向日志的文件名和路径。 +3. 保存更改并运行应用程序。 + +.. note:: + + - 如果文件位于工作区中，则文件路径可以使用相对路径（见下方截图）。 + - 指定目录路径（以 ``/`` 或 ``\`` 等分隔符结尾）时，系统会自动追加 ``openocd.log`` 为文件名。例如输入 ``/tmp/logs/`` 将会创建 ``/tmp/logs/openocd.log``。 + + +.. image:: ../../media/OpenOCDDebug_13.png + +OpenOCD 配置首选项 +~~~~~~~~~~~~~~~~~~ + +OpenOCD 路径会根据 CDT 构建环境变量中定义的 ``OPENOCD_SCRIPTS`` 路径进行自动配置。 + +.. image:: ../../media/OpenOCDDebug_2.png + +开始调试 +-------- + +要开始调试，需要选择调试配置，将模式从 ``Run`` 改为 ``Debug``，并点击启动图标（即小甲虫图标）。 + +.. image:: ../../media/OpenOCDDebug_10.png + +当目标在断点处暂停后，系统会建议切换为 ``Debug perspective``。 + +.. image:: ../../media/OpenOCDDebug_11.png + +你可以根据个人偏好自定义 ``Debug perspective``。例如，你可以移动选项卡、添加你认为有用的其他视图，或移除不需要的视图。可参照以下步骤添加视图： + +1. 在 Eclipse 顶部菜单栏中点击 ``Window``。 +2. 选择 ``Show View``。 +3. 选择要添加的视图。 + +.. image:: ../../media/OpenOCDDebug_12.png + +故障排查 +-------- + +* 请确保你使用的是最新版 `Espressif-IDE `_。 +* 如果你的开发板支持或启用了 JTAG，请参考 `此文 `_ 了解更多信息。 +* 如果出现 OpenOCD 超时问题，请在首选项中增大 GDB 服务器超时设置值 ``_。通常在处理较大的应用时会出现超时问题。 +* 如果调试时遇到错误，可以参考 OpenOCD `故障排查 FAQ `_，尝试解决问题。 +* 如果你遇到问题，并希望启用 OpenOCD 调试的详细日志，请在 ``Startup`` 标签页中勾选 ``Enable verbose output`` 选项。 diff --git a/docs/zh_CN/startproject.rst b/docs/zh_CN/startproject.rst index bb7477bb5..2d37df3ab 100644 --- a/docs/zh_CN/startproject.rst +++ b/docs/zh_CN/startproject.rst @@ -1 +1,69 @@ -.. include:: ../en/startproject.rst +.. _startproject: + +开始项目 +======== + +:link_to_translation:`en:[English]` + +要开始使用 Espressif-IDE，可以创建一个新项目或导入现有项目。 + +- :ref:`创建新项目 ` +- :ref:`使用 ESP-IDF 模板创建新项目 ` +- :ref:`导入现有项目 ` + +.. _newproject: + +创建新项目 +---------- + +要在 Espressif-IDE 中创建新项目，请按以下步骤操作： + +#. 依此选择 ``File`` > ``New`` > ``Espressif IDF Project``。 + + .. image:: ../../media/newproject_menu.png + :alt: 新项目菜单栏 + +#. 填写 ``Project name``。 +#. 点击 ``Finish``。 + +.. Note:: + + ESP-IDF 构建系统不支持在 ESP-IDF 或项目的路径中使用空格。 + + +.. _newprojecttemplate: + +使用 ESP-IDF 模板创建新项目 +----------------------------- + +Espressif-IDE 还提供使用 ESP-IDF 模板创建项目的功能，按以下步骤操作： + +#. 依次选择 ``File`` > ``New`` > ``Espressif IDF Project``。 +#. 在 ``Select Project Target`` 下拉列表中选择目标开发板。 +#. 在 ``Template Selection`` 部分勾选 ``Create a project using one of the templates``。 +#. 选择要使用的模板，项目名称会根据所选模板自动填写。 +#. 点击 ``Finish``。 + +.. image:: ../../media/3_new_project_default.png + +.. note:: + + 你可能会在编辑器中看到大量未解析的头文件或符号错误，这些错误会在构建完成后被解析。 + + +.. _importproject: + +导入现有项目 +------------ + +要将现有项目导入到 Espressif-IDE，请确保它是一个 CMake 项目。按以下步骤操作： + +#. 右键点击 ``Project Explorer``。 +#. 选择 ``Import..`` 菜单。 +#. 从 ``Espressif`` 导入向导菜单列表中选择 ``Existing IDF Project``。 +#. 点击 ``Next``。 +#. 点击 ``Browse...`` 选择现有项目所在目录。 +#. 如果希望使用不同的名称，请填写 ``Project name``。 +#. 点击 ``Finish``，将所选项目作为 CMake 项目导入到 Eclipse 工作区。 + +.. image:: ../../media/5_import_project.png