From 7ac99a27664adee0b5cb8f58c9d534cdd521d93a Mon Sep 17 00:00:00 2001 From: shenmengjing Date: Thu, 26 Sep 2024 11:51:23 +0800 Subject: [PATCH] docs: Update the README_CN file --- README.md | 455 +++++++++++++++++--------------- README_CN.md | 729 +++++++++++++++++++++++++-------------------------- 2 files changed, 608 insertions(+), 576 deletions(-) diff --git a/README.md b/README.md index 26a968beb..7286ede91 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ # ESP-IDF Eclipse Plugin (Espressif-IDE) ESP-IDF Eclipse Plugin brings developers an easy-to-use Eclipse-based development environment for developing ESP32-based IoT applications. -It provides better tooling capabilities, which simplifies and enhances standard Eclipse CDT for developing and debugging ESP32 IoT applications. It offers advanced editing, compiling, flashing and debugging features with the addition of Installing the tools, SDK configuration and CMake editors. + +It provides better tooling capabilities, which simplifies and enhances standard Eclipse CDT for developing and debugging ESP32 IoT applications. It offers advanced editing, compiling, flashing and debugging features with the addition of installing the tools, SDK configuration and CMake editors. The plug-in runs on `macOS`, `Windows` and `Linux` platforms. @@ -22,129 +23,142 @@ To get a quick understanding of ESP-IDF and Eclipse plugin features, check our s
Get Started -* [ Installation](#Installation)
-* [ Creating a new Project ](#NewProjectUsingDefault)
-* [ Configuring Launch Target ](#ConfigureLaunchTarget)
-* [ Compiling the Project ](#BuildApplication)
-* [ Flashing the Project ](#FlashApplication)
-* [ Viewing Serial Output ](#ConfigureLaunchTerminal)
-* [ Debugging the Project ](#debugging)
-* [ Troubleshooting Guide](#troubleshooting)
+* [Installation](#Installation)
+* [Creating a new Project](#NewProjectUsingDefault)
+* [Configuring Launch Target](#ConfigureLaunchTarget)
+* [Compiling the Project](#BuildApplication)
+* [Flashing the Project](#FlashApplication)
+* [Viewing Serial Output](#ConfigureLaunchTerminal)
+* [Debugging the Project](#debugging)
+* [Troubleshooting Guide](#troubleshooting)
* FAQ
Other IDE Features -* [ Configuring the Project using sdkconfig Editor](#projectconfigure)
-* [ CMake Editor](#cmakeproject)
-* [ ESP-IDF Application Size Analysis Editor](#sizeanalysiseditor)
-* [ Installing ESP-IDF Components](#espidfcomponents)
-* [ ESP-IDF Terminal](#idfterminal)
-* [ Configuring Build Environment Variables ](#configureEnvironmentVariables)
-* [ Configuring Core Build Toolchain ](#ConfigureToolchains)
-* [ Configuring CMake Toolchain ](#ConfigureCMakeToolchain)
-* [ Selecting Clang Toolchain](#SelectDifferentToolchain)
-* [ Configuring the flash arguments ](#customizeLaunchConfig)
-* [ Installing IDF Eclipse Plugin from Eclipse Market Place](#installPluginsFromMarketPlace)
-* [ Installing IDF Eclipse Plugin using local archive ](#installPluginsUsingLocalFile)
-* [ Upgrading IDF Eclipse Plugin ](#upgradePlugins)
-* [ Importing an existing IDF Project ](#ImportProject)
-* [ Importing an existing Debug launch configuration ](#importDebugLaunchConfig)
-* [ Device Firmware Upgrade (DFU) through USB ](#deviceFirmwareUpgrade)
-* [ GDBStub Debugging ](#gdbStubDebugging)
-* [ Core Dump Debugging ](#coreDumpDebugging)
-* [ Application Level Tracing ](#appLvlTracing)
-* [ NVS Table Editor](#nvsTableEditor)
-* [ Write Binary Data to Flash](#writeFlashBinary)
-* [ Changing Language ](#changeLanguage)
-* [ Wokwi Simulator](#wokwisimulator)
+* [Configuring the Project using sdkconfig Editor](#projectconfigure)
+* [CMake Editor](#cmakeproject)
+* [ESP-IDF Application Size Analysis Editor](#sizeanalysiseditor)
+* [Installing ESP-IDF Components](#espidfcomponents)
+* [ESP-IDF Terminal](#idfterminal)
+* [Configuring Build Environment Variables](#configureEnvironmentVariables)
+* [Configuring Core Build Toolchain](#ConfigureToolchains)
+* [Configuring CMake Toolchain](#ConfigureCMakeToolchain)
+* [Selecting Clang Toolchain](#SelectDifferentToolchain)
+* [Configuring the Flash Arguments](#customizeLaunchConfig)
+* [Installing IDF Eclipse Plugin from Eclipse Market Place](#installPluginsFromMarketPlace)
+* [Installing IDF Eclipse Plugin Using Local Archive](#installPluginsUsingLocalFile)
+* [Upgrading IDF Eclipse Plugin](#upgradePlugins)
+* [Importing an existing IDF Project](#ImportProject)
+* [Importing an existing Debug Launch Configuration](#importDebugLaunchConfig)
+* [Device Firmware Upgrade (DFU) through USB](#deviceFirmwareUpgrade)
+* [GDBStub Debugging](#gdbStubDebugging)
+* [Core Dump Debugging](#coreDumpDebugging)
+* [Application Level Tracing](#appLvlTracing)
+* [NVS Table Editor](#nvsTableEditor)
+* [Write Binary Data to Flash](#writeFlashBinary)
+* [Changing Language](#changeLanguage)
+* [Wokwi Simulator](#wokwisimulator)
# Installation + We recommend using the Espressif-IDE instead of the Eclipse CDT + IEP Plugin update approach to avoid the hassles of updating. ## Espressif-IDE for Windows + * Download the [Espressif-IDE with ESP-IDF Offline Windows Installer](https://dl.espressif.com/dl/esp-idf/) and follow the instructions provided [here](https://github.com/espressif/idf-eclipse-plugin/blob/master/docs_readme/Espressif-IDE-Windows-Installer.md). This guide will walk you through the installation process for Java, Git, CMake, ESP-IDF, IDF Tools, Device Drivers, and Espressif-IDE to help you get started. ## Espressif-IDE for macOS and Linux -* To begin, download the [Espressif-IDE](https://github.com/espressif/idf-eclipse-plugin/blob/master/docs_readme/Espressif-IDE.md#downloads) for your respective operating system. Following this, launch the IDE and proceed to install the necessary ESP-IDF and related tools. Please note that prior to launching the IDE, you must ensure that Java, Python, and Git are installed as [prerequisites](#Prerequisites). and available in the system path. -If you plan to use Eclipse CDT and update it through the IDF Eclipse plugin, please ensure that you download the supported version for your operating system from here . +* To begin, download the [Espressif-IDE](https://github.com/espressif/idf-eclipse-plugin/blob/master/docs_readme/Espressif-IDE.md#downloads) for your respective operating system. Following this, launch the IDE and proceed to install the necessary ESP-IDF and related tools. Please note that prior to launching the IDE, you must ensure that Java, Python, and Git are installed as [prerequisites](#Prerequisites), and are available in the system path. + +If you plan to use Eclipse CDT and update it through the IDF Eclipse plugin, please ensure that you download the supported version for your operating system from here. + ## Prerequisites The minimum requirements for running the Espressif-IDE are below. -* **Java 17 and above** : Download and install Java SE from here. -* **Python 3.8 and above** : Download and install Python from here. -* **Git** : Get the latest git from here. + +* **Java 17 and above**: Download and install Java SE from here. +* **Python 3.8 and above**: Download and install Python from here. +* **Git**: Get the latest git from here. > **Note:** Make sure Java, Python and Git are available on the system environment PATH. -# Installing IDF Plugin using update site URL +# Installing IDF Plugin Using Update Site URL You can install the IDF Eclipse plugin into an existing IDE using the update site URL. First, add the release repository URL as follows: 1. Go to `Help` > `Install New Software`. -1. Click `Add…`, and in the pop-up window: +2. Click `Add…`, and in the pop-up window: * Enter `Name` as `Espressif IDF Plugin for Eclipse` * Enter `Location` of the repository: - * Stable release: https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/ + * Stable release: https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/ * Click `Add`. -1. Select `Espressif IDF` from the list and proceed with the installation. +3. Select `Espressif IDF` from the list and proceed with the installation. -For adding beta and nightly builds, you can use the following update site urls. - * Beta version: https://dl.espressif.com/dl/idf-eclipse-plugin/updates/beta/ - * Nightly build: https://dl.espressif.com/dl/idf-eclipse-plugin/updates/nightly/ +For adding beta and nightly builds, you can use the following update site URLs. + * Beta version: https://dl.espressif.com/dl/idf-eclipse-plugin/updates/beta/ + * Nightly build: https://dl.espressif.com/dl/idf-eclipse-plugin/updates/nightly/ > **Note:** While the screenshots are captured on macOS, the installation instructions are applicable to Windows, Linux, and macOS. ![](docs_readme/images/idf_update_site_install.png) + # Installing ESP-IDF Please follow the instructions below for installing ESP-IDF in the Espressif-IDE. 1. Go to `Espressif` > `ESP-IDF Manager`. The following editor will open + ![](docs_readme/images/ToolsManager/ESP-IDF_Manager_Editor_Screen.png) -1. Click on `Add ESP-IDF` button. +2. Click on `Add ESP-IDF` button. + ![](docs_readme/images/ToolsManager/ESP-IDF_Configuration_Download_or_Use_ESP-IDF.png) -From the screen shown above you can choose an already downloaded ESP-IDF Directory or you can select and download directly from the given dialog. The `Git` and `Python` must be installed and if it is configured in system PATH it will be preloaded in the given view. If not you can Browse to the directory and select the proper executables. -1. Click on `Finish` which will be enabled after all the paths and executables are properly configured. +From the screen shown above you can either choose an already downloaded ESP-IDF directory or select and download one directly from the given dialog. The `Git` and `Python` must be installed and if they are configured in system PATH, they will be preloaded in the given view. If not, you can Browse to the directory and select the proper executables. + +3. Click on `Finish`, which will be enabled after all the paths and executables are properly configured. + +> **Note** Please note that the python executable is not the one from the virtual environment created from the installation of the ESP-IDF via other means like from CLI. If you are selecting an already installed ESP-IDF directory, IDE will automatically pick up the python once you have installed the tools. -> **Note** Please note that the python executable is not the one from the virtual environment created from the installation of the ESP-IDF via other means like from CLI. If you are selecting an already installed ESP-IDF directory IDE will automatically pick up the python once you have installed the tools. To configure an existing ESP-IDF: -After you have clicked `Finish` you will see the progress on console for the tools getting installed. Once the installation is done and this is the very first set of ESP-IDF installed in the IDE it will be activated as well and you will see a similar entry in the editor for ESP-IDF Manager +After you have clicked `Finish`, you will see the progress on console for the tools getting installed. Once the installation is done and this is the very first set of ESP-IDF installed in the IDE, it will be activated as well, and you will see a similar entry in the editor for ESP-IDF Manager. + ![](docs_readme/images/ToolsManager/Tool_installed_and_activated.png) -You can add as many version of ESP-IDF as you want but only one of the version can be set active and that will be used to compile and index projects in your workspace. This new feature can help you in swithcing between versions in the workspace easily. +You can add as many version of ESP-IDF as you want, but only one of the version can be set active and that will be used to compile and index projects in your workspace. This new feature can help you in swithcing between versions in the workspace easily. + +Let's take a look at how the multiple versions will look like. You have to follow the same steps as done previously to add another ESP-IDF version to the IDE. -Lets take a look at how the multiple versions will look like. You have to follow the same steps as done previously to add another ESP-IDF version to the IDE. ![](docs_readme/images/ToolsManager/ESP-IDF_Manager_Multiple_versions.png) -To activate any specific version simply click on the radio button next to it in the `Active` column. +To activate any specific version, simply click on the radio button next to it in the `Active` column. -The refresh button in last column for the active ESP-IDF version can be used to reload any changes in the directory you made. +The refresh button in last column for the active ESP-IDF version can be used to reload any changes in the directory you made. -> **Note** Please note that you can not delete an active ESP-IDF Version you need to activate another version before deleting that. +> **Note** Please note that you can not delete an active ESP-IDF version. You need to activate another version before deleting that. + # Create a new Project 1. Make sure you are in `C/C++ Perspective`. -1. Go to `File` > `New` > `Espressif IDF Project` -1. Provide the `Project name` (The ESP-IDF build system does not support spaces in the project path). -1. Click `Finish`. +2. Go to `File` > `New` > `Espressif IDF Project`. +3. Provide the `Project name` (The ESP-IDF build system does not support spaces in the project path). +4. Click `Finish`. To create a project using existing ESP-IDF templates, please refer to [this](#NewProjectUsingTemplates). @@ -153,6 +167,7 @@ To create a project using existing ESP-IDF templates, please refer to [this](#Ne ![](docs_readme/images/3_new_project_default.png) + # Configuring build target Next, you should select the ESP target for your project. By default, the launch target drop-down will display all the supported targets by the plugin. @@ -160,25 +175,28 @@ Next, you should select the ESP target for your project. By default, the launch target However, if you would like to add a target that is not available in the launch target drop-down, please follow the instructions below. + 1. Click on the launch target dropdown. -1. Select `New Launch Target`. -1. Select `ESP Target`. -1. Provide properties for the target where you would like to launch the application. Enter a `Name` for the target and select the `Serial Port` your ESP device is connected to on your machine. +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` your ESP device is connected to on your machine. ![](docs_readme/images/8_launch_target.png) + # Compiling the Project 1. Select a project from the `Project Explorer`. -1. Select `Run` from the first drop-down, which is called `Launch Mode`. -1. Select your application from the second drop-down, which is called `Launch Configuration`(Auto-detected). -1. Select a target from the third drop-down, which is called `Launch Target`. -1. Now click on the `Build` ![](docs_readme/images/icons/build.png) button to start with a build process. +2. Select `Run` from the first drop-down, which is called `Launch Mode`. +3. Select your application from the second drop-down, which is called `Launch Configuration` (Auto-detected). +4. Select a target from the third drop-down, which is called `Launch Target`. +5. Now click on the `Build` ![](docs_readme/images/icons/build.png) button to start with a build process. ![](docs_readme/images/9_cmake_build.png) + # Flashing the Project Flash operation can be initiated with just a click of a launch button ![](docs_readme/images/icons/run.png) and it's auto-configured to flash the application with the default flash command i.e, `idf.py -p PORT flash`. @@ -187,9 +205,10 @@ Flash operation can be initiated with just a click of a launch button ![](docs_r To provide the customized flash arguments, please follow [this](#customizeLaunchConfig) link for further instructions. -To configure flashing via JTAG, please refer to this JTAG Flashing guide. +To configure flashing via JTAG, please refer to this JTAG Flashing Guide. + # Viewing Serial 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`. Please check more details here. @@ -197,10 +216,10 @@ To see the serial output in Eclipse, we need to configure the `ESP-IDF Serial Mo monitor 1. Click on the `Open a Terminal` icon from the toolbar. -1. Choose `ESP-IDF Serial Monitor` from the terminal drop-down. -1. Select `Serial Port` for your board if it's not detected. -1. Configure serial monitor filter options for output filtering. -1. Click on `OK` to launch the terminal, which will listen to the USB port. +2. Choose `ESP-IDF Serial Monitor` from the terminal drop-down. +3. Select `Serial Port` for your board if it's not detected. +4. Configure serial monitor `Filter Options` for output filtering. +5. Click on `OK` to launch the terminal, which will listen to the USB port. ![](docs_readme/images/10_serial_terminal.png) @@ -209,19 +228,21 @@ To see the serial output in Eclipse, we need to configure the `ESP-IDF Serial Mo 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. Click on `ESP-IDF Serial Monitor Settings`. -1. Provide `Console Line Width` and `Limit Console Output`. +2. Click on `ESP-IDF Serial Monitor Settings`. +3. Provide `Console Line Width` and `Limit Console Output`. + # Debugging the Project -In most cases, only two things are required to start debugging an esp-idf project: + +In most cases, only two things are required to start debugging an ESP-IDF project: 1) Create a debug configuration 2) Check whether the board in the created configuration corresponds to the board in use. > **Note:** If you're using Windows, you may need to install drivers using Zadig to run a debug session successfully. For detailed instructions, please refer to this [guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html#configure-usb-drivers). The fastest way to create a debug configuration is to expand the configuration list in the launch bar and click `New Launch Configuration...`. Then select `ESP-IDF GDB OpenOCD Debugging` -> Double Click or `Next`. After that, the preview for the new debug configuration will open where it's necessary to check the board. -After creating the debug configuration, you can go ahead and debug the project. Select the configuration you just created, select debug mode, and click on the "Debug" icon ![](docs_readme/images/icons/debug.png) to start debugging: +After creating the debug configuration, you can go ahead and debug the project. Select the configuration you just created, select debug mode, and click on the `Debug` icon ![](docs_readme/images/icons/debug.png) to start debugging: ![Debugging_process](https://github.com/espressif/idf-eclipse-plugin/assets/24419842/1fb0fb9b-a02a-4ed1-bdba-b4b4d36d100f) @@ -231,15 +252,15 @@ To learn more about the debug configuration, please refer to -## Create a new project using ESP-IDF Templates +## Create a New Project Using ESP-IDF Templates 1. Make sure you're in `C/C++ Perspective`. -1. Go to `File` > `New` > `Espressif IDF Project` (If you don't see this, please reset the perspective from `Window` > `Perspective` > `Reset Perspective..`). -1. Provide the `Project name`. -1. Click `Next`. -1. Check `Create a project using one of the templates`. -1. Select the required template from the tree. -1. Click `Finish`. +2. Go to `File` > `New` > `Espressif IDF Project` (If you don't see this, please reset the perspective from `Window` > `Perspective` > `Reset Perspective..`). +3. Provide the `Project name`. +4. Click `Next`. +5. Check `Create a project using one of the templates`. +6. Select the required template from the tree. +7. Click `Finish`. > **Note:** You will see a lot of unresolved inclusion errors in the editor and those will be resolved only after the build. @@ -247,23 +268,23 @@ To learn more about the debug configuration, please refer to -# SDK Configuration editor +# SDK Configuration Editor Project configuration is held in a single file called `sdkconfig` in the root directory of the project. This configuration file can be modified using `SDK Configuration Editor` To launch the SDK Configuration editor: 1. Navigate to `sdkconfig` file. -1. Double-click on the file to launch the SDK configuration editor. -1. Use `Ctrl+S` or `Command+S` based on the OS environment to save the changes. You can also use Eclipse `Save` button from the toolbar. -1. To revert the sdkconfig editor changes, you can either close the editor without saving them or you can right-click on the `sdkconfig` file and select `Load sdkconfig` menu option to revert the changes from the editor. +2. Double-click on the file to launch the SDK configuration editor. +3. Use `Ctrl+S` or `Command+S` based on the OS environment to save the changes. You can also use Eclipse `Save` button from the toolbar. +4. To revert the sdkconfig editor changes, you can either close the editor without saving them or you can right-click on the `sdkconfig` file and select `Load sdkconfig` menu option to revert the changes from the editor. ![](docs_readme/images/13_sdkconfig_editor.png) # CMake Editor -CMake Editor Plug-in is integrated with IDF Plugin for editing CMake files such as CMakeLists.txt. It provides syntax coloring, CMake command content assist, and code templates. +CMake Editor Plug-in is integrated with IDF Plugin for editing CMake files such as `CMakeLists.txt`. It provides syntax coloring, CMake command content assist, and code templates. ![](docs_readme/images/cmake_editor_ca.png) @@ -283,7 +304,7 @@ The Application Size Analysis editor provides a way to analyze the static memory To launch the Application Size Analysis editor: 1. Right-click on the project. -1. Select `ESP-IDF` > `Application Size Analysis` menu option to launch the editor. +2. Select `ESP-IDF` > `Application Size Analysis` menu option to launch the editor. **Application Size Analysis - Overview** @@ -296,7 +317,7 @@ To launch the Application Size Analysis editor: # ESP-IDF Terminal -This would launch a local terminal with all the environment variables which are set under `Preferences` > `C/C++` > `Build` > `Environment`. The default working directory would be either the currently selected project or IDF_PATH if there is no project selected. +This would launch a local terminal with all the environment variables which are set under `Preferences` > `C/C++` > `Build` > `Environment`. The default working directory would be either the currently selected project or `IDF_PATH` if there is no project selected. The terminal PATH is also configured with `esptool`, `espcoredump`, `partition_table`, and `app_update` component paths so that it will be handy to access them directly from the ESP-IDF terminal. @@ -312,21 +333,22 @@ To launch the ESP-IDF Terminal: You can install the ESP-IDF Components directly into your project from the available components online. Follow the steps below: -* Right-click on the project from `Project Explorer` in which you want to add the component to and Select `Install ESP-IDF Components`. +* Right-click on the project from `Project Explorer` in which you want to add the component to and select `Install ESP-IDF Components`. - ![](docs_readme/images/ESP-IDF_Components/install_components.png) + ![](docs_readme/images/ESP-IDF_Components/install_components.png) - A new window will open up showing all the available component to be installed. + A new window will open up showing all the available component to be installed. * From the window, you can click on `Install` button to add that component to the project. To get to the readme file for that component you can click on `More Info` which will open the browser link to the readme file of that component. - ![](docs_readme/images/ESP-IDF_Components/components_window.png) + + ![](docs_readme/images/ESP-IDF_Components/components_window.png) Already added components are also shown but the `Install` button changes text to `Already Added` and is disabled. # Configuring Environment Variables -All the required environment variables are automatically configured by the IDE during the ESP-IDF and Tools installation process (Espressif > ESP-IDF Manager > Add ESP-IDF). You can verify them in the Preferences page under `C/C++` > `Build` > `Environment`. +All the required environment variables are automatically configured by the IDE during the ESP-IDF and Tools installation process (`Espressif` > `ESP-IDF Manager` > `Add ESP-IDF`). You can verify them in the Preferences page under `C/C++` > `Build` > `Environment`. ![](docs_readme/images/2_environment_pref.png) @@ -339,16 +361,16 @@ If these toolchains are not detected for any reason, please follow the step-by-s # Configuring Core Build Toolchains -1. Open Eclipse Preferences. -1. Navigate to `C/C++` > `Core Build Toolchains` preference page. -1. Click on `Add..` from the user-defined toolchains tables. -1. Select `GCC` as a toolchain type. -1. Click on `Next`. -1. Provide the GCC toolchain settings: +1. Open Eclipse `Preferences`. +2. Navigate to `C/C++` > `Core Build Toolchains` preference page. +3. Click on `Add...` from the user-defined toolchains tables. +4. Select `GCC` as a toolchain type. +5. Click on `Next`. +6. Provide the GCC toolchain settings: - * **Compiler:** /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc, - * **Operating System:** esp32, - * **CPU Architecture:** xtensa + * **Compiler:** /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc + * **Operating System:** esp32 + * **CPU Architecture:** xtensa ![](docs_readme/images/6_core_build_toolchains.png) @@ -358,9 +380,9 @@ If these toolchains are not detected for any reason, please follow the step-by-s We now need to tell CDT which toolchain to use when building the project. This will pass the required arguments to CMake when generating the Ninja files. 1. Navigate to `C/C++` > `CMake` preference page. -1. Click `Add...` and this will launch the New CMake toolchain configuration dialog. -1. Browse CMake toolchain `Path`. Example: `/Users/user-name/esp/esp-idf/tools/cmake/toolchain-esp32.cmake`. -1. Select GCC Xtensa toolchain compiler from the drop-down list. Example: `esp32 xtensa /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc`. +2. Click `Add...` and this will launch the New CMake toolchain configuration dialog. +3. Browse CMake toolchain `Path`. Example: `/Users/user-name/esp/esp-idf/tools/cmake/toolchain-esp32.cmake`. +4. Select GCC Xtensa toolchain compiler from the drop-down list. Example: `esp32 xtensa /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc`. > **Note:** Eclipse CDT has a bug in saving the toolchain preferences, hence it's recommended to restart Eclipse before we move further configuring the launch target. @@ -369,12 +391,15 @@ We now need to tell CDT which toolchain to use when building the project. This w # Selecting Clang Toolchain -1. After creating a new project, edit the project configuration +1. After creating a new project, edit the project configuration. + ![image](https://user-images.githubusercontent.com/24419842/194882285-9faadb5d-0fe2-4012-bb6e-bc23dedbdbd2.png) -1. Go to the `Build Settings` tab and select clang toolchain there: + +2. Go to the `Build Settings` tab and select clang toolchain there: + ![image](https://user-images.githubusercontent.com/24419842/194882462-3c0fd660-b223-4caf-964d-58224d91b518.png) -> **Note:** Clang toolchain now is an experimental feature and you may face some build issues due to the incompatibility of esp-idf. Below is a description of how to fix the most common build issue on the current ESP-IDF master (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty). To work around clang build errors please refer to [this](https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS.md#clang-toolchain-buid-errors). +> **Note:** Clang toolchain now is an experimental feature and you may face some build issues due to the incompatibility of ESP-IDF. Below is a description of how to fix the most common build issues on the current ESP-IDF master (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty). To work around clang build errors please refer to [this](https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS.md#clang-toolchain-buid-errors). # Launch Configuration @@ -382,13 +407,13 @@ We now need to tell CDT which toolchain to use when building the project. This w To provide the customized launch configuration and flash arguments, please follow the step-by-step instructions below. 1. Click on the `Launch Configuration` edit button. -1. Switch to the `Main` tab. -1. Specify the `Location` where this application has to run. Since `idf.py` is a Python file, will configure the Python system path. Example:`${system_path:python}`. -1. Specify the `Working directory` of the application. Example: `${workspace_loc:/hello_world}`. -1. In additional arguments, provide a flashing command which will run in the specified working directory. -1. Flash command looks like this: `/Users/user-name/esp/esp-idf/tools/idf.py -p /dev/cu.SLAB_USBtoUART flash`. -1. Click OK to save the settings. -1. Click on the `Launch` icon to flash the application to the selected board. +2. Switch to the `Main` tab. +3. Specify the `Location` where this application has to run. Since `idf.py` is a Python file, the system will configure the Python path. Example: `${system_path:python}`. +4. Specify the `Working Directory` of the application. Example: `${workspace_loc:/hello_world}`. +5. In additional arguments, provide a flashing command which will run in the specified working directory. +6. Flash command looks like this: `/Users/user-name/esp/esp-idf/tools/idf.py -p /dev/cu.SLAB_USBtoUART flash`. +7. Click OK to save the settings. +8. Click on the `Launch` icon to flash the application to the selected board. ![](docs_readme/images/11_launch_configuration.png) @@ -397,12 +422,12 @@ To provide the customized launch configuration and flash arguments, please follo # Changing Language -To change the plugin language a menu is provided to show the list of available languages for the plugin. +To change the plugin language, a menu is provided to show the list of available languages for the plugin. 1. Click on the `Espressif` menu from the menu bar. -1. Select the `Change Language` from the drop-down menu. -1. From the sub menu select the language you want. -1. IDE will restart with the selected language. +2. Select the `Change Language` from the drop-down menu. +3. From the sub menu select the language you want. +4. IDE will restart with the selected language. ![](docs_readme/images/change_language.png) @@ -414,13 +439,14 @@ Remember this will only change the language of the Eclipse if the required langu ## Suggestions for Solving Errors from ESP-IDF by Hints Viewer If you run into a problem during a build, chances are that there is a hint for this error in the ESP-IDF hint database, which is stored in `tools/idf_py_actions/hints.yml` of ESP-IDF. The ESP-IDF Eclipse plugin provides a hint viewer where you can type an error message and find a hint for it. -Prerequisites for it is to have `hints.yml`, which is available from ESP-IDF v5.0 and higher. If you are using lower versions of ESP-IDF, you can still use the hints viewer. To do it, you have to manually download the hints.yml file from [here](https://github.com/espressif/esp-idf/blob/master/tools/idf_py_actions/hints.yml) and put it to your `esp-idf/tools/idf_py_actions/` path. To download a file from GitHub, right-click the `Raw` button and then `Save as...`. -To open the hints viewer go to `Windows` -> `Show View` -> `Other...` -> `Espressif` -> `Hints`. You will see the following view: +Prerequisites for it is to have `hints.yml`, which is available from ESP-IDF v5.0 and higher. If you are using lower versions of ESP-IDF, you can still use the hints viewer. To do it, you have to manually download the `hints.yml` file from [here](https://github.com/espressif/esp-idf/blob/master/tools/idf_py_actions/hints.yml) and put it to your `esp-idf/tools/idf_py_actions/` path. To download a file from GitHub, right-click the `Raw` button and then `Save as...`. + +To open the hints viewer, go to `Windows` -> `Show View` -> `Other...` -> `Espressif` -> `Hints`. You will see the following view: + ![image](https://user-images.githubusercontent.com/24419842/189666994-78cc8b24-b934-426f-9df5-79af28c50c55.png) -Now you can type or copy paste some error from the build log, for example: -`ccache error: Failed to create temporary file for esp-idf/libsodium/CMakeFiles/..../....: No such file or directory` +Now you can type or copy paste some error from the build log, for example: `ccache error: Failed to create temporary file for esp-idf/libsodium/CMakeFiles/..../....: No such file or directory` ![image](https://user-images.githubusercontent.com/24419842/189672552-994624f3-c0c5-48e6-aa2c-61e4ed8915e5.png) @@ -430,9 +456,9 @@ Double-clicking on the row will give you a hint message, so you can clearly see ## Error Log -The Error Log view captures all the warnings and errors logged by plug-ins. The underlying log file is a .log file stored in the .metadata subdirectory of the workspace. +The `Error Log` view captures all the warnings and errors logged by plug-ins. The underlying log file is a .log file stored in the .metadata subdirectory of the workspace. -The Error Log view is available in `Window` > `Show View` > `Error Log`. +The `Error Log` view is available in `Window` > `Show View` > `Error Log`. To export the current log view content into a file, press the Export Log toolbar button or select `Export Log...` from the context menu. Then, enter a file name. @@ -442,9 +468,9 @@ Always provide an error log when reporting an issue. ## Console View Log -The Console View provides all the warnings and errors related to the current running process or build. To access the console view. +The `Console` view provides all the warnings and errors related to the current running process or build. -From the menu bar, `Window` > `Show View` > `Console`. +To access the console view, go to the menu bar and select `Window` > `Show View` > `Console`. ![](docs_readme/images/CDT_Build_Console.png) @@ -454,11 +480,11 @@ Go to `Preferences > C/C++ > Build > Logging` ## Espressif IDF Tools Console -The Espressif IDF Tools Console is part of the Console view, this will be opened only during the installation of IDF tools from the Eclipse. +The Espressif IDF Tools Console is part of the `Console` view, this will be opened only during the installation of IDF tools from the Eclipse. If you encounter any issue while installing the IDF tools using `Espressif` > `ESP-IDF Tools Manager` > `Install tools`, please check the Espressif IDF Tools Console to see the errors reported. -If this is not active, it can be switched by clicking on the `Display Selected Console` icon from the console view. +If this is not active, it can be switched by clicking on the `Display Selected Console` icon from the `Console` view. ![](docs_readme/images/IDF_tools_console.png) @@ -472,9 +498,9 @@ Please refer to -# Importing an existing IDF Project +# Importing an Existing IDF Project 1. Make sure you're in `C/C++ Perspective`. -1. Right-click in the `Project Explorer`. -1. Select `Import..` Menu. -1. Select `Existing IDF Project` from `Espressif` import wizard menu list. -1. Click `Next`. -1. Click on `Browse...` to choose an existing project location directory. -1. Provide `Project name` if you wish you have a different name. -1. Click `Finish` to import the selected project into Eclipse workspace as a CMake project. +2. Right-click on the `Project Explorer`. +3. Select `Import...` Menu. +4. Select `Existing IDF Project` from `Espressif` import wizard menu list. +5. Click `Next`. +6. Click on `Browse...` to choose an existing project location directory. +7. Provide `Project name` if you wish you have a different name. +8. Click `Finish` to import the selected project into Eclipse workspace as a CMake project. ![](docs_readme/images/5_import_project.png) -# Importing an existing Debug launch configuration +# Importing an Existing Debug Launch Configuration To import an existing launch configuration into Eclipse: 1. Select `Import...` from the `File` menu. -1. In the Import dialog box, expand the `Run/Debug` group and select `Launch Configurations`. -1. Click on `Next`. -1. Click on `Browse...` to select the required location in the local file system. -1. Select the folder containing the launch files and then click `OK`. -1. Select the checkboxes for the required folder and launch file. -1. If you are replacing an existing configuration with the same name then select `Overwrite existing launch configurations without warning`. -1. Click on `Finish`. +2. In the Import dialog box, expand the `Run/Debug` group and select `Launch Configurations`. +3. Click on `Next`. +4. Click on `Browse...` to select the required location in the local file system. +5. Select the folder containing the launch files and then click `OK`. +6. Select the checkboxes for the required folder and launch file. +7. If you are replacing an existing configuration with the same name then select `Overwrite existing launch configurations without warning`. +8. Click on `Finish`. # GDBStub Debugging @@ -544,10 +570,12 @@ You can now use the GDBStub debugging inside our Eclipse plugin to help you diag To enable GDBStub debugging for a project: -1. Launch the `sdkconfig` in project root by double-clicking on it which will open the configuration editor. +1. Launch the `sdkconfig` in project root by double-clicking on it, and it will open the configuration editor. + ![](docs_readme/images/GDBStubDebugging/sdkconfig_editor.png) -1. Expand the `Component Config` section and select `ESP System Settings`. From the settings on the right for `Panic Handler behaviour` select the `GDBStub on Panic option` from the list. +2. Expand the `Component Config` section and select `ESP System Settings`. From the settings on the right of `Panic handler behaviour`, select the `GDBStub on Panic` option from the list. + ![](docs_readme/images/GDBStubDebugging/sdkconfig_editor_panic_behavior.png) Now you will be taken to the GDBStub debugger automatically when you connect the serial monitor and there is a panic for this example. @@ -556,30 +584,31 @@ To use the GDBStub debugging for a project: 1. Create a template `hello_world` project and add the following lines in the main c file. - ``` - This is a global variable
- COREDUMP_DRAM_ATTR uint8_t global_var; - ``` + ``` + This is a global variable
+ COREDUMP_DRAM_ATTR uint8_t global_var; + ``` -1. Now add these two lines just above the `esp_restart()` function +2. Now add these two lines just above the `esp_restart()` function - ``` - global_var = 25; - assert(0); - ``` + ``` + global_var = 25; + assert(0); + ``` The final file should be something like this: + ![](docs_readme/images/GDBStubDebugging/code_example.png) Build and flash the project and launch the serial monitor. On line number 45, we are signaling for a failing assert which will put the chip in panic mode and when that line reaches, you will be prompted to switch the perspective to debug mode and the chip will be halted. -Remember that this is a panic mode and you cannot continue the execution from here, you will have to stop and restart the chip through IDF commands or simply restart the serial monitor. +Remember that this is a panic mode and you can not continue the execution from here, you will have to stop and restart the chip through IDF commands or simply restart the serial monitor. ![](docs_readme/images/GDBStubDebugging/debug_panic_mode.png) You can view the registers stack trace and even view the value of variables in the stack frame. -To exit the debug session simply press `stop` button. +To exit the debug session: simply press `Stop` button. @@ -589,16 +618,17 @@ The IDF-Eclipse plugin allows you to debug the core dump if any crash occurs on To enable core dump debugging for a project: -1. You need to enable it first in `sdkconfig`. Launch the `sdkconfig` in the project root by double-clicking on it which will open the configuration editor +1. You need to enable it first in `sdkconfig`. Launch the `sdkconfig` in the project root by double-clicking on it, and it will open the configuration editor. + +2. Click on the `Core Dump` from the settings on the left and select `Data Destination` as `UART`. -1. Click on the `Core Dump` from the settings on the left and select `Data Destination` as `UART`. ![](docs_readme/images/CoreDumpDebugging/sdkconfig_editor.png) -This will enable the core dump debugging and whenever you connect a serial monitor for that project if any crash occurs it will load the dump and open a debug perspective in Eclipse to let you diagnose the dump where you can view all the information in the core dump. +This will enable the core dump debugging and whenever you connect a serial monitor for that project if any crash occurs, it will load the dump and open a debug perspective in Eclipse to let you diagnose the dump where you can view all the information in the core dump. You can view the registers stack trace and even view the value of variables in stack frame. -To exit the debug session: simply press stop button. +To exit the debug session: simply press `Stop` button. # Device Firmware Upgrade (DFU) through USB @@ -618,7 +648,8 @@ Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of devic After meeting the above requirements: 1. The chip needs to be in bootloader mode for the detection as a DFU device and flashing. This can be achieved by pulling GPIO0 down (e.g. pressing the BOOT button), pulsing RESET down for a moment and releasing GPIO0. - + + 1. Install USB drivers (Windows only). The drivers can be installed by the [Zadig tool](https://zadig.akeo.ie/). - Please make sure that the device is in download mode before running the tool and that it detects the device before installing the drivers. - The Zadig tool might detect several USB interfaces of the target. Please install the WinUSB driver for only that interface for which there is no driver installed (probably it is Interface 2) and don't re-install the driver for the other interface. @@ -627,9 +658,9 @@ After meeting the above requirements: After meeting the above requirements, you are free to build and flash via DFU. How to use DFU: 1. Edit the active launch configuration. -1. In the main tab, select the `Flash over DFU` option. -1. Select a suitable IDF target for DFU -1. Now, if you use the build command, an extra file (dfu.bin) will be created, which can be used later for flashing. +2. In the main tab, select the `Flash over DFU` option. +3. Select a suitable IDF target for DFU +4. Now, if you use the build command, an extra file (dfu.bin) will be created, which can be used later for flashing. ![DFU actions](https://user-images.githubusercontent.com/24419842/226182180-286099d3-9c1c-4394-abb0-212d43054529.png) @@ -638,7 +669,8 @@ Additional information, including common errors and known issues, is mentioned i # Application Level Tracing -ESP-IDF provides a useful feature for program behavior analysis called [Application Level Tracing](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/app_trace.html?). IDF-Eclipse plugin has UI, that allows the use of start, and stop tracing commands and process received data. To familiarize yourself with this library, you can use the [app_trace_to_host](https://github.com/espressif/esp-idf/tree/release/v5.0/examples/system/app_trace_to_host) project or the [app_trace_basic](https://github.com/espressif/esp-idf/tree/release/v5.1/examples/system/app_trace_basic) project if you are using esp-idf 5.1 and higher. These projects can be created from the plugin itself: +ESP-IDF provides a useful feature for program behavior analysis called [Application Level Tracing](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/app_trace.html?). IDF-Eclipse plugin has UI, that allows the use of start, and stop tracing commands and process received data. To familiarize yourself with this library, you can use the [app_trace_to_host](https://github.com/espressif/esp-idf/tree/release/v5.0/examples/system/app_trace_to_host) project or the [app_trace_basic](https://github.com/espressif/esp-idf/tree/release/v5.1/examples/system/app_trace_basic) project if you are using ESP-IDF 5.1 and higher. These projects can be created from the plugin itself: + ![](docs_readme/images/AppLvlTracing_1.png) Before you start using application-level tracing, it is important to create a debug configuration for the project where you must select the board you are using in order to successfully start the OpenOCD server. @@ -656,10 +688,10 @@ Start command: * Syntax: `start [poll_period [trace_size [stop_tmo [wait4halt [skip_size]]]]` * Argument: * `outfile`: Path to file to save data from both CPUs. This argument should have the following format: ``file://path/to/file``. - * `poll_period`: Data polling period (in ms) for available trace data. If greater than 0 then command runs in non-blocking mode. By default, 1 ms. + * `poll_period`: Data polling period (in ms) for available trace data. If greater than 0, then command runs in non-blocking mode. By default, 1 ms. * `trace_size`: Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled). * `stop_tmo`: Idle timeout (in sec). Tracing is stopped if there is no data for a specified period of time. By default -1 (disable this stop trigger). Optionally set it to a value longer than the longest pause between tracing commands from the target. - * `wait4halt`: If 0 start tracing immediately, otherwise command waits for the target to be halted (after reset, by breakpoint etc.) and then automatically resumes it and starts tracing. By default, 0. + * `wait4halt`: If 0, start tracing immediately, otherwise command waits for the target to be halted (after reset, by breakpoint etc.) and then automatically resumes it and starts tracing. By default, 0. * `skip_size`: Number of bytes to skip at the start. By default, 0. Additional information can be found [here](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/app_trace.html?). @@ -704,7 +736,7 @@ To use a customized partition table: # NVS Table Editor -The NVS Table Editor helps to create a binary file based on key-value pairs provided in a CSV file. The resulting binary file is compatible with NVS architecture defined in [ESP_IDF Non Volatile Storage](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_flash.html). The expected CSV format is: +The NVS Table Editor helps to create a binary file based on key-value pairs provided in a CSV file. The resulting binary file is compatible with NVS architecture defined in [ESP-IDF Non-Volatile Storage Library](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_flash.html). The expected CSV format is: ``` key,type,encoding,value <-- column header (must be the first line) @@ -712,42 +744,43 @@ The NVS Table Editor helps to create a binary file based on key-value pairs prov key1,data,u8,1 key2,file,string,/path/to/file ``` -> Note: This is based on ESP-IDF [NVS Partition Generator Utility](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_partition_gen.html). + +> **Note:** This is based on ESP-IDF [NVS Partition Generator Utility](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_partition_gen.html). Steps: 1. Right-click on a project in the `Project Explorer` -2. Click on the `ESP-IDF` > `NVS Table Editor` menu option: +2. Click on the `ESP-IDF` > `NVS Table Editor` menu option ![NVS Table Editor](https://user-images.githubusercontent.com/24419842/216114697-9f231211-f5dd-431b-9432-93ecc656cfec.png) 3. Make desired changes to CSV data -4. Save changes by clicking the `Save` button. If everything is ok, you will see an information message at the top of the dialog: +4. Save changes by clicking the `Save` button. If everything is ok, you will see an information message at the top of the dialog ![NVS_TABLE_EDITOR_2png](https://user-images.githubusercontent.com/24419842/216115906-9bb4fe55-293b-4c6b-8d22-0aa3520581ab.png) -5. Generate the partition binary (Choose `encrypt` to encrypt the binary and disable the generate key option to use your own key if desired). You will see an information message at the top of the dialog about the result of generated binaries. You can hover your mouse over it to read the whole message if it's too long: +5. Generate the partition binary (Choose `encrypt` to encrypt the binary and disable the `generate key` option to use your own key if desired). You will see an information message at the top of the dialog about the result of generated binaries. You can hover your mouse over it to read the whole message if it's too long ![NVS_Table_Editor_4](https://user-images.githubusercontent.com/24419842/216117261-9bee798a-3a9e-4be5-9466-fc9d3847834b.png) - > Note: If there are any errors, you will see them highlight, hover on the error icon to read more about the error. Also, you will see an error message at the top of the dialog if saving the CSV file is not successful: + > **Note:** If there are any errors, you will see them highlighted. Hover over the error icon to read more about the error. Also, you will see an error message at the top of the dialog if saving the CSV file is not successful. ![NVS_Table_editor_5](https://user-images.githubusercontent.com/24419842/216118486-69f819fa-7a95-49ae-805e-473cd2c424e8.png) After all these steps, you should see `nvs.csv` and `nvs.bin` files in the project directory. - + # Write Binary to Flash Binary data can be written to the ESP’s flash chip via `ESP-IDF` > `Write Binary Data to Flash` command accessible by right click on the project in the project explorer: Screenshot 2023-10-16 at 10 51 52 -After clicking this command, the `Write Binary Data to Flash` dialog box will open. Editable default values ​​are provided for binary path and offset. The correct offset can be checked by looking at the partition table via `ESP-IDF` > `Partition Table Editor` or manually by opening the partitions.csv file +After clicking this command, the `Write Binary Data to Flash` dialog box will open. Editable default values ​​are provided for binary path and offset. The correct offset can be checked by looking at the partition table via `ESP-IDF` > `Partition Table Editor` or manually by opening the ``partitions.csv`` file. Screenshot 2023-10-16 at 10 51 27 -After clicking on the `Flash` button the result of the flash command will be printed inside of this dialog. +After clicking on the `Flash` button, the result of the flash command will be printed inside of this dialog. # How to build locally @@ -770,21 +803,21 @@ This artifact can be installed using the mechanism mentioned here. -1. Click on a :white_check_mark: green tick mark. -1. Click on `Details`. -1. Click on `Summary` on the left. -1. Scroll down to see the `Artifacts` section. -1. Download `com.espressif.idf.update` p2 update site archive and install as per the instructions mentioned here. # Custom IDE Configuration -## Custom build directory +## Custom Build Directory IDE allows configuring a custom build directory to the project: -1. Select a project and click on a launch configuration `Edit` button from the top toolbar and this will the launch `Edit Configuration` window. +1. Select a project and click on a launch configuration `Edit` button from the top toolbar and this will launch the `Edit Configuration` window. 2. Navigate to the `Build Settings` tab. -3. In the `Additional CMake Arguments` section, provide a custom build directory with arguments `-B ` with an absolute path. Customized build directory path could be within the project or a path from the file system. For example: `-B /Users/myUser/esp/generated`. +3. In the `Additional CMake arguments` section, provide a custom build directory with arguments `-B ` with an absolute path. Customized build directory path could be within the project or a path from the file system. For example: `-B /Users/myUser/esp/generated`. 4. Click on `Ok` and build the project. Note this configuration changes where all the project build artifacts will be generated. @@ -795,23 +828,23 @@ Note this configuration changes where all the project build artifacts will be ge # Wokwi Simulator 1. Install `wokwi-server` as mentioned [here](https://github.com/MabezDev/wokwi-server/) -1. In the Eclipse CDT build environment variables, configure `WOKWI_SERVER_PATH` with the wokwi-server executable path (`Preferences` > `C/C++` > `Build` > `Environment`). -1. Create a new `Run launch configuration` with the `Wokwi Simulator`. -1. Choose a project and add the project ID of the Wokwi project. The ID of a Wokwi project can be found in the URL. E.g., the URL of project ESP32 Rust Blinky is [https://wokwi.com/projects/345932416223806035](https://wokwi.com/projects/345932416223806035) and the project ID is 345932416223806035. -1. Click `Finish` to save the changes. -1. From the IDE Toolbar, click on the `Launch` button to launch the Wokwi simulator. -1. Wokwi Simulator will be launched in the external browser. The serial monitor output is also displayed in the Eclipse CDT build console. -1. To kill a Wokwi simulator, click on the `Stop` button from the toolbar. +2. In the Eclipse CDT build environment variables, configure `WOKWI_SERVER_PATH` to set the wokwi-server executable path (`Preferences` > `C/C++` > `Build` > `Environment`). +3. Create a new `Run Launch Configuration` with the `Wokwi Simulator`. +4. Choose a project and add the project ID of the Wokwi project. The ID of a Wokwi project can be found in the URL. For example, the URL of project ESP32 Rust Blinky is [https://wokwi.com/projects/345932416223806035](https://wokwi.com/projects/345932416223806035) and the project ID is 345932416223806035. +5. Click `Finish` to save the changes. +6. From the IDE Toolbar, click on the `Launch` button to launch the Wokwi simulator. +7. Wokwi Simulator will be launched in the external browser. The serial monitor output is also displayed in the Eclipse CDT build console. +8. To kill a Wokwi simulator, click on the `Stop` button from the toolbar. # ESP-IDF Eclipse Plugin Compatibility Matrix | IEP | Eclipse | Java | Installer | Description | | ------ | ------ | ------ |------ | ------ | | IEP 2.12.1 | Eclipse 2023-03 to Eclipse 2023-12 |Java 17 and above |[espressif-ide-setup-2.12.1-with-esp-idf-5.2.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.12.1-esp-idf-5.2/espressif-ide-setup-2.12.1-with-esp-idf-5.2.exe) | -| IEP 2.12.0 | Eclipse 2023-03, Eclipse 2023-06, Eclipse 2023-09 |Java 17 and above | [espressif-ide-setup-2.12.0-with-esp-idf-5.1.2](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.12.0-esp-idf-5.1.2/espressif-ide-setup-2.12.0-with-esp-idf-5.1.2.exe) | -| IEP 2.11.0 | Eclipse 2023-03, Eclipse 2023-06, Eclipse 2023-09 |Java 17 and above |[espressif-ide-setup-2.11.0-with-esp-idf-5.1.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.11.0-esp-idf-5.1.1/espressif-ide-setup-2.11.0-with-esp-idf-5.1.1.exe) | -| IEP 2.10.0 | Eclipse 2022-09,2022-12,2023-03 |Java 17 and above | [espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/untagged-52aeb689780472c126c1/espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe)| -| IEP 2.9.1 | Eclipse 2022-09 and Eclipse 2022-12 |Java 17 and above | [espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.9.0-esp-idf-5.0.1/espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe) | For Windows Users, it's recommended to use the Windows Offline Installer and upgrade to the latest IEP v2.9.1 plugin| +| IEP 2.12.0 | Eclipse 2023-03, 2023-06, 2023-09 |Java 17 and above | [espressif-ide-setup-2.12.0-with-esp-idf-5.1.2](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.12.0-esp-idf-5.1.2/espressif-ide-setup-2.12.0-with-esp-idf-5.1.2.exe) | +| IEP 2.11.0 | Eclipse 2023-03, 2023-06, 2023-09 |Java 17 and above |[espressif-ide-setup-2.11.0-with-esp-idf-5.1.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.11.0-esp-idf-5.1.1/espressif-ide-setup-2.11.0-with-esp-idf-5.1.1.exe) | +| IEP 2.10.0 | Eclipse 2022-09, 2022-12, 2023-03 |Java 17 and above | [espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/untagged-52aeb689780472c126c1/espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe)| +| IEP 2.9.1 | Eclipse 2022-09 and Eclipse 2022-12 |Java 17 and above | [espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.9.0-esp-idf-5.0.1/espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe) | For Windows Users, it's recommended to use the Windows Offline Installer and upgrade to the latest IEP v2.9.1 plugin| | IEP 2.9.0 | Eclipse 2022-09 |Java 17 and above | [espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.9.0-esp-idf-5.0.1/espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe) | For Windows, it's recommended to use the Windows Offline Installer| diff --git a/README_CN.md b/README_CN.md index ed87d979b..4f7ba6196 100644 --- a/README_CN.md +++ b/README_CN.md @@ -2,10 +2,11 @@ [English](./README.md) -# ESP-IDF Eclipse 插件 +# ESP-IDF Eclipse 插件 (Espressif-IDE) -ESP-IDF Eclipse 插件可便利开发人员在 Eclipse 开发环境中开发基于 ESP32 的 IoT 应用程序。 -本插件集成了编辑、编译、烧录和调试等基础功能，还有安装工具、SDK 配置和 CMake 编辑器等附加功能，可简化并增强开发人员在使用标准 Eclipse CDT 开发和调试 ESP32 IoT 应用程序时的开发体验。 +使用 ESP-IDF Eclipse 插件，开发者很容易就能在 Eclipse 开发环境中开发基于 ESP32 的 IoT 应用程序。 + +本插件集成了编辑、编译、烧录和调试等进阶功能，还有安装工具、SDK 配置和 CMake 编辑器等附加功能，简化并增强了标准 Eclipse CDT，用于开发和调试 ESP32 IoT 应用程序，从而优化开发体验。 ESP-IDF Eclipse 插件支持 `macOS`、`Windows` 和 `Linux` 操作系统。 @@ -14,16 +15,16 @@ ESP-IDF Eclipse 插件支持 `macOS`、`Windows` 和 `Linux` 操作系统。 ![](docs_readme/images/linux-logo.png) -> **Note:** 本插件支持基于 `esp32`、`esp32s2`、`esp32s3` 和 `esp32c3` 开发的 ESP-IDF CMake 项目（4.x 及以上）。 +> **注意：** 本插件支持基于 ESP-IDF CMake 的项目（4.x 及以上）。 -快速了解 ESP-IDF 和 Eclipse 插件，请见我们在 EclipseCon 2020 中的视频介绍。 +想要快速了解 ESP-IDF 和 Eclipse 插件，请观看 EclipseCon 2020 中的介绍。 # 目录
入门指南 * [安装依赖资源](#Installation)
-* [创建一个新项目](#NewProjectUsingDefault)
+* [创建新项目](#NewProjectUsingDefault)
* [配置启动目标](#ConfigureLaunchTarget)
* [编译项目](#BuildApplication)
* [烧录项目](#FlashApplication)
@@ -36,7 +37,6 @@ ESP-IDF Eclipse 插件支持 `macOS`、`Windows` 和 `Linux` 操作系统。
其他 IDE 功能 -* [使用工具安装助手，安装 ESP-IDF 和相关工具](#InstallToolsWizard)
* [使用 sdkconfig 编辑器配置项目](#projectconfigure)
* [CMake 编辑器](#cmakeproject)
* [ESP-IDF 应用程序内存分析编辑器](#sizeanalysiseditor)
@@ -50,367 +50,356 @@ ESP-IDF Eclipse 插件支持 `macOS`、`Windows` 和 `Linux` 操作系统。 * [从 Eclipse 市场安装 IDF Eclipse 插件](#installPluginsFromMarketPlace)
* [使用本地文件安装 IDF Eclipse 插件](#installPluginsUsingLocalFile)
* [升级 IDF Eclipse 插件](#upgradePlugins)
-* [导入一个现有的 IDF 项目](#ImportProject)
-* [导入一个现有的 Debug 启动配置](#importDebugLaunchConfig)
+* [导入现有的 IDF 项目](#ImportProject)
+* [导入现有的 Debug 启动配置](#importDebugLaunchConfig)
* [通过 USB 升级设备固件 (DFU)](#deviceFirmwareUpgrade)
* [GDBStub 调试](#gdbStubDebugging)
* [Core Dump 调试](#coreDumpDebugging)
* [应用层追踪](#appLvlTracing)
-* [ESP-IDF master 分支更新](#updateEspIdfMaster)
* [ESP-IDF 分区表编辑器界面](#partitionTableEditor)
* [NVS 表编辑器](#nvsTableEditor)
+* [将二进制数据写入 flash](#writeFlashBinary)
* [更改语言](#changeLanguage)
* [Wokwi 模拟器](#wokwisimulator)
-# 安装依赖资源 -IDF Eclipse 插件的运行环境要求如下。 +# 安装 + +建议直接使用 Espressif-IDE，而不是借用 Eclipse CDT + IEP 插件更新，从而省去定期更新的麻烦。 + +# Windows 版 Espressif-IDE + +下载 [适用于 Windows 的 ESP-IDF 离线安装程序](https://dl.espressif.com/dl/esp-idf/)，并按照[此处](https://github.com/espressif/idf-eclipse-plugin/blob/master/docs_readme/Espressif-IDE-Windows-Installer.md)提供的说明进行操作。该指南将引导你完成 Java、Git、CMake、ESP-IDF、IDF 工具、设备驱动程序和 Espressif-IDE 的安装，帮助你快速入门。 + +# macOS 和 Linux 版 Espressif-IDE -* **Java 17 及以上**：点击这里下载并安装 Java SE.。 -* **Python 3.6 及以上**：点击这里下载并安装 Python。 -* **Eclipse IDE C/C++ 开发工具 2023-03**：点击这里下载并安装 Eclipse CDT 安装包。 -* **Git**：点击这里获得最新 Git。 -* **ESP-IDF 4.0 及以上**：点击这里克隆 ESP-IDF 仓库。 +* 首先，下载适用于你操作系统的 [Espressif-IDE](https://github.com/espressif/idf-eclipse-plugin/blob/master/docs_readme/Espressif-IDE.md#downloads)。接下来，启动 IDE 并继续安装所需的 ESP-IDF 和相关工具。请注意，在启动 IDE 之前，必须确保已完成[准备工作](#Prerequisites)，即安装好了 Java、Python 和 Git，并且已将它们添加到系统路径中。 -> **Note:** 请确保系统环境 `PATH` 可以访问 Java、Python 和 Git。 +如果想要使用 Eclipse CDT 并通过 IDF Eclipse 插件进行更新，请确保从下载适用于你操作系统的版本。 -此外，我们还为 Windows 用户提供 `Espressif-IDE 离线安装器`，集成了 OpenJDK、Python、CMake、Git、ESP-IDF、Eclipse IDE、IDF Eclipse 插件及相关构建工具，请见 Espressif-IDE 离线安装器 。 + -更多有关 Espressif-IDE 的信息，请见 这里。 +## 准备工作 + +运行 Espressif-IDE 的最低要求如下： + +* **Java 17 及以上**：从此处下载并安装 Java SE。 +* **Python 3.8 及以上**：从此处下载并安装 Python。 +* **Git**：从此处获取最新的 Git。 + +> **注意：** 请确保 Java、Python 和 Git 已添加到系统环境路径中。 -# 使用更新站点 URL 安装插件 +# 使用更新站点 URL 安装 IDF 插件 + +可以使用更新站点 URL 将 IDF Eclipse 插件安装至现有的 IDE 中。首先，参照下列步骤添加发布仓库的 URL： -您可以使用`更新站点 URL` 将 ESP-IDF Eclipse 插件安装至您的 Eclipse CDT 环境中，具体步骤见下： +1. 前往 `帮助` > `安装新软件`。 +2. 点击 `添加…`，并在弹出的对话窗中： + * 将 `名称` 设为 `ESP-IDF Eclipse 插件`。 + * 将 `仓库位置` 设为： + * 稳定版: https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/ + * 点击 `添加`。 +3. 在列表中选择 `Espressif IDF`，并按照提示完成所有安装步骤。 -1. 前往`帮助`>`安装新软件`。 -1. 点击`添加…`，并在弹出的对话窗中： - * 输入`名称`为 `乐鑫 ESP-IDF Eclipse 插件`。 - * 输入`仓库位置`为： - * 稳定版：https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/ - * 测试版：https://dl.espressif.com/dl/idf-eclipse-plugin/updates/beta/ - * 每日构建版：https://dl.espressif.com/dl/idf-eclipse-plugin/updates/nightly/ - * 点击`添加`。 -1. 从列表中选择 `Espressif IDF`，并按照提示完成所有安装步骤。 +若想要添加测试版和每日构建版，请使用以下更新站点 URL。 + * 测试版：https://dl.espressif.com/dl/idf-eclipse-plugin/updates/beta/ + * 每日构建版：https://dl.espressif.com/dl/idf-eclipse-plugin/updates/nightly/ -> **Note:** 本文档中的所有截图均来自 `macOS` 操作系统，但安装步骤同时适用于 `Windows`、`Linux` 和 `macOS` 操作系统。 +> **注意：** 本文档中的所有截图均来自 macOS 操作系统，但安装步骤同时适用于 Windows、Linux 和 macOS 操作系统。 -![](docs_readme/images/zh/idf_update_site_install.png) +![](docs_readme/images/idf_update_site_install.png) + # 安装 ESP-IDF -通过 Eclipse 直接安装 ESP-IDF： +请按照以下说明在 Espressif-IDE 中安装 ESP-IDF。 + +1. 点击 `乐鑫` > `ESP-IDF 管理器`。将打开以下编辑器： + +![](docs_readme/images/ToolsManager/ESP-IDF_Manager_Editor_Screen.png) + +2. 点击 `添加 ESP-IDF` 按钮： -1. 前往`乐鑫`>`下载并配置 ESP-IDF`。 -1. 在`下载 ESP-IDF`部分，选择需要下载的 ESP-IDF 版本和保存路径。 -1. 点击`完成`。 +![](docs_readme/images/ToolsManager/ESP-IDF_Configuration_Download_or_Use_ESP-IDF.png) -使用现有的本地 ESP-IDF： +在这一步中，可以选择已下载的 ESP-IDF 文件夹，也可以自行选择文件夹并下载。在此之前，必须预先安装好 `Git` 和 `Python`。如果二者已配置到系统路径中，则将预加载到以上界面中；如果没有，请点击 `浏览`，在文件夹中选择适当的可执行文件。 -1. 前往`乐鑫`>`下载并配置 ESP-IDF`。 -1. 勾选`使用文件系统中现有的 ESP-IDF 目录`。 -1. 选择一个文件系统中现有的 ESP-IDF 目录。 -1. 点击`完成`。 +3. 点击 `完成`。该按钮将在所有路径和可执行文件得到正确配置后自动启用。 -本操作将下载指定的 ESP-IDF 版本，并配置 Eclipse CDT 构建环境变量中的 `IDF_PATH`。 +> **注意：** 通过其他方式（如 CLI）安装 ESP-IDF 时创建的虚拟环境中的 Python 不可用作此处提到的 Python 可执行文件。如果在第二步中选择已下载的 ESP-IDF 文件夹，那么只要提前安装好了工具，IDE 就能自动检测到 Python。 -![](docs_readme/images/zh/espidf_download.png) +配置现有的 ESP-IDF： -# 安装 ESP-IDF 工具集 +点击 `完成` 按钮后，可以在控制台上看到工具安装的进度。安装完成后，如果这是在 IDE 中安装的第一个 ESP-IDF，则系统会将其激活，且能在 ESP-IDF Manager 编辑器中看到类似下图中的条目： -ESP-IDF 在构建固件时需要一些工具，包括 Python、Git、交叉编译器、menuconfig 工具、CMake 和 Ninja 构建工具等。 +![](docs_readme/images/ToolsManager/Tool_installed_and_activated.png) -具体可按照以下步骤，安装 ESP-IDF 工具集。 +可以在 IDE 中添加多个版本的 ESP-IDF，但只能激活其中一个，且该版本将用于编译和索引工作区中的项目。这个新功能可用于在工作区中轻松切换 ESP-IDF 版本。 -1. 前往`乐鑫`>`ESP-IDF 工具管理器`>`安装工具`。 -1. 输入 `ESP-IDF 目录`的所在路径。 -1. 输入 `Git` 和 `Python` 可执行文件的位置（如未能自动检测填充）。 -1. 点击`安装工具`，并按照提示完成所有安装步骤。如需了解安装详情，请查看`控制台`。 -1. 本操作需要下载并安装 `xtensa-esp32-elf`、`esp32ulp-elf`、CMake、`openocd-esp32` 和 Ninja 等工具集。因此，如果您是首次进行本操作，则可能需要等待较长时间。 +以下图片展示了添加多个 ESP-IDF 版本后编辑器呈现出的效果。只需按照之前的步骤将其他 ESP-IDF 版本添加到 IDE 中即可： -> **Note:** 本步骤将按照 `idf_tools.py export` 命令，将 `IDF_PATH`、`PATH`、`OPENOCD_SCRIPTS` 和 `IDF_PYTHON_ENV_PATH` 设置为 Eclipse CDT 构建环境。因此，即使您以前已安装过上述工具，也不可跳过该步骤。 +![](docs_readme/images/ToolsManager/ESP-IDF_Manager_Multiple_versions.png) -![](docs_readme/images/install_tools.png) +若想激活某一版本，请点击 `激活` 列中对应的单选按钮。 -ESP-IDF 目录选择对话框： +编辑器中中最后一列的刷新按钮可用于重新加载目录中所做的任何更改。 -![](docs_readme/images/zh/esp_idf_dir.png) +> **注意：** 已经激活的 ESP-IDF 版本是无法删除的，需要先激活其他版本再进行删除操作。 + # 创建一个新项目 -1. 请首先确保您处于 `C/C++ 视图`之下。 -1. 前往`文件`>`新建`>`乐鑫 IDF 项目`（如果您未看到该选项，请前往`窗口`>`视图`>`重置视图...`）。 -1. 输入 `项目名称` （注意，ESP-IDF 构建系统路径中不允许空格）。 -1. 点击`完成`。 +1. 首先请确保处于 `C/C++ 视图`。 +2. 点击 `文件` > `新建` > `乐鑫 IDF 项目` +3. 输入 `项目名` （注意，ESP-IDF 构建系统不允许项目路径中出现空格）。 +4. 点击 `完成`。 -如需使用现有 ESP-IDF 模版创建一个新项目，请见[这里](#NewProjectUsingTemplates)。 +如需使用现有 ESP-IDF 模版创建一个新项目，请参考[此处](#NewProjectUsingTemplates)。 -> **Note:** 完成以上操作后，您将在编辑器中看到许多未解决的 include 错误。这些错误仅在构建完成后才能解决。 +> **注意：** 完成以上操作后，编辑器中可能会出现许多未解决的头文件和符号错误，这些错误仅在构建完成后才能解决。 -![](docs_readme/images/zh/3_new_project_default.png) +![](docs_readme/images/3_new_project_default.png) -# 配置启动目标 -接下来，我们需要告诉 CDT 应在项目中使用我们的工具链，确保所有的头文件均可索引和使用。本步骤需在`启动栏`完成。注意，`启动栏`位于工具栏的最左边，仅在`项目管理器`中存在项目时出现。 +# 配置构建目标 + +接下来，需要为项目选择 ESP 目标。默认情况下，启动目标选项的下拉菜单栏会显示插件支持的所有目标。 + +target + +如果启动目标选项的下拉菜单中没有你想要添加的目标，可以参照以下步骤： -1. 点击顶部工具栏中左起第三个下拉窗口`启动目标`。 -1. 选择`新的启动目标`。 -1. 选择 `ESP 目标`。 -1. 提供目标属性，即您希望启动应用程序的位置。输入目标`名称`，并选择您连接 ESP 设备的`串口`。 +1. 点击启动目标选项的下拉菜单。 +2. 选择 `新建启动目标`。 +3. 选择 `ESP 目标`。 +4. 为应用程序的 ESP 目标提供属性。输入目标的 `名称`，并选择连接 ESP 设备的 `串口`。 -![](docs_readme/images/zh/8_launch_target.png) +![](docs_readme/images/8_launch_target.png) + # 编译项目 -1. 从`项目浏览器`中选择一个项目。 -1. 点击顶部工具栏中左起第一个下拉窗口`启动模式`，选择`运行`。 -1. 点击顶部工具栏中左起第二个下拉窗口`启动配置`，选择您的应用程序（自动检测）。 -1. 点击顶部工具栏中左起第三个下拉窗口`启动目标`，选择您需要启动的目标。 -1. 现在，点击顶部工具栏左上角的`构建`按钮。 +1. 从 `项目资源管理器` 中选择一个项目。 +2. 选择顶部工具栏中左起第一个下拉窗口 `启动模式`，点击 `运行`。 +3. 点击顶部工具栏中左起第二个下拉窗口 `启动配置`，选择要运行的应用程序（系统会自动检测）。 +4. 点击顶部工具栏中左起第三个下拉窗口 `启动目标`，选定目标。 +5. 点击顶部工具栏左上角的 `构建` ![](docs_readme/images/icons/build.png) 按钮。 ![](docs_readme/images/9_cmake_build.png) + # 烧录项目 -ESP-IDF 的 `idf.py` 工具可以打包 `make flash` 命令和常用指令。用户只需点击`启动`按钮（顶部工具栏左起第二个按钮）即可启动烧录操作，即使用默认的烧录命令 `idf.py -p PORT flash` 烧录应用程序。 +点击 `启动` 按钮 ![](docs_readme/images/icons/run.png) 即可进行烧录，且默认使用 `idf.py -p PORT flash` 命令来烧录应用程序。 + +flash -如需使用自定义烧录参数，请前往[这里](#customizeLaunchConfig) 获取详细步骤。 +如需使用自定义烧录参数，请点击[此处](#customizeLaunchConfig)获取详细信息。 -如需通过 JTAG 进行烧录，请见 JTAG 烧录指南。 +如需通过 JTAG 进行烧录，请参考 JTAG 烧录指南。 + # 查看串口输出 -为了查看 Eclipse 的串口输出，我们需要在`ESP-IDF 串口监视器`中配置需要监测的串口。本功能已经集成至`IDF 监视器`。更多详情，请见 这里。 +想要查看 Eclipse 的串口输出，需要先在 `ESP-IDF 串口监视器` 中配置需要监测的串口。本功能已经集成至 `IDF 监视器` 中。详情见 此处。 + +monitor 1. 点击工具栏中的`打开终端`图标。 -1. 从终端下拉菜单中选择 `ESP-IDF 串口监视器`。 -1. 手动选择开发板连接的`串口`（如未能自动检测）。 -1. 配置`串口监视器`过滤器，对串口输出进行过滤。 -1. 点击 `OK` 启动终端，开始监听 USB 端口。 +2. 从终端下拉菜单中选择 `ESP-IDF 串口监视器`。 +3. 若系统未能自动检测到相应串口，请手动选择开发板连接的`串口`。 +4. 配置串口监视器`过滤器选项`，对串口输出进行过滤。 +5. 点击 `OK`，启动终端，开始监听 USB 端口。 ![](docs_readme/images/zh/10_serial_terminal.png) ### ESP-IDF 串口监视器设置 -设置 ESP-IDF 串口监视器的字符和行数上限： +设置 ESP-IDF 串口监视器默认的字符和行数上限： -1. 进入 Eclipse 偏好设置，选择 `乐鑫`。 -1. 点击 `ESP-IDF 串口监视器设置`。 -1. 配置 `控制台行宽 (Console Line Width)` 和 `控制台输出上限 (Limit Console Output)`。 +1. 进入 Eclipse 偏好设置，选择`乐鑫`。 +2. 点击 `ESP-IDF 串口监视器设置`。 +3. 配置`控制台行宽`和`控制台输出上限`。 + # 调试项目 -## GDB 硬件调试 +大多数情况下，调试 ESP-IDF 项目只需要两步： +1) 创建调试配置 +2) 检查创建配置中的开发板与实际使用的开发板是否对应 +> **注意：** 如果使用 Windows 系统，则可能需要使用 Zadig 来安装驱动程序，以成功运行调试会话。详细说明请参考此[指南](https://docs.espressif.com/projects/esp-idf/zh/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html#configure-usb-drivers)。 + +创建调试配置的最快方式是展开启动栏中的配置列表并点击`新的启动配置...`。然后选择 `ESP-IDF GDB OpenOCD 调试` -> 双击或点击`下一步`。接下来会打开新的调试配置预览页面，请仔细检查开发板的设置。 -请见 GDB 硬件调试指南。 +创建调试配置后就可以开始调试项目了。选择刚才创建的配置，选择调试模式，然后点击`调试`图标 ![](docs_readme/images/icons/debug.png) 开始调试： -## GDB OpenOCD 调试 +![Debugging_process](https://github.com/espressif/idf-eclipse-plugin/assets/24419842/1fb0fb9b-a02a-4ed1-bdba-b4b4d36d100f) + +更多关于调试配置的信息，请参考 GDB OpenOCD 调试指南。 -请见 GDB OpenOCD 调试。 # 其他 IDE 功能 ## 使用 ESP-IDF 模板创建一个新项目 -1. 请首先确保您处于`C/C++ 视图`之下。 -1. 前往`文件`>`新建`>`乐鑫 IDF 项目`（如果您未找到该选项，请前往`窗口`>`视图`>`重置视图...`）。 -1. 输入`项目名称`。 -1. 点击`下一步`。 -1. 勾选`使用其中一个模板创建项目`。 -1. 从目录中选择一个模板。 -1. 点击`完成`。 +1. 首先请确保处于 `C/C++ 视图`。 +2. 选择`文件` > `新建` > `乐鑫 IDF 项目`（如果未找到该选项，请选择`窗口` > `视图` > `重置视图...`）。 +3. 输入`项目名`。 +4. 点击`下一步`。 +5. 勾选`使用模板创建项目`。 +6. 从目录中选择一个模板。 +7. 点击`完成`。 -> **Note:** 完成以上操作后，您将在编辑器中看到许多未解决的 include 错误。这些错误仅在构建完成后才能解决。 +> **注意：** 完成以上操作后，编辑器中可能会出现许多未解决的包含错误，这些错误仅在构建完成后才能解决。 ![](docs_readme/images/4_new_project_templates.png) - -# 工具安装助手 - -您可以使用工具安装助手，安装相关工具，优势在于可以简化安装过程，且仅安装 ESP-IDF 框架下您需要的工具。 - -具体步骤如下： - -1. 前往 `乐鑫` > `ESP-IDF 工具管理器` > `工具安装助手（预览版）`。 -![](docs_readme/images/ToolsManager/install_tools_manager.png) - -1. 等待安装助手启动，选择 Git 和 Python 的安装路径（如您已添加系统 PATH，则路径可自动填充）。然后，点击 `下一步`。 -![](docs_readme/images/ToolsManager/git_python_selection.png) - -1. 选择本地已安装 ESP-IDF 文件夹，或从下拉菜单中选择不同版本安装 ESP-IDF，比如选择列表中的 master 可以帮您从 GitHub 中克隆 ESP-IDF 的 master 分支。 -![](docs_readme/images/ToolsManager/select_or_download_new_esp_idf.png) - -1. 点击 `下一步` 查看针对您的 ESP-IDF 版本的可用工具。此时，您可以选择安装所有推荐工具，或仅选择您需要的工具（可按照工具名称或目标进行筛选）。接着，安装助手将下载并安装所有所需的工具。安装完成后，您就可以创建项目了。 -![](docs_readme/images/ToolsManager/manage_tools_installation.png) # SDK 配置编辑器 -ESP-IDF Eclipse 插件允许用户直接在 Eclipse 环境中配置 `sdkconfig`。项目配置保存在项目根目录下的 `sdkconfig` 配置文件中，用户可通过`SDK 配置编辑器`进行修改。 +项目配置保存在项目根目录下的 `sdkconfig` 配置文件中，可通过 `SDK 配置编辑器`进行修改。 启动 `SDK 配置编辑器`： 1. 前往 `sdkconfig` 文件。 -1. 双击文件，启动 SDK 配置编辑器。 -1. 完成更改后，可使用 `Ctrl+S` 或 `Command+S` 保存更改。也可以点击 Eclipse 工具栏中的`保存`按钮进行保存。 -1. 如需撤回对 sdkconfig 编辑器的更改，用户可选择不保存退出编辑器；也可右键 `sdkconfig` 文件并选择`加载 sdkconfig` 菜单选项，恢复对编辑器的修改。 +2. 双击文件，启动 SDK 配置编辑器。 +3. 完成更改后，可使用 `Ctrl+S` 或 `Command+S` 保存更改，也可以点击 Eclipse 工具栏中的`保存`按钮进行保存。 +4. 如需撤回对 sdkconfig 编辑器的更改，可选择不保存直接退出编辑器；也可右键 `sdkconfig` 文件并选择`加载 sdkconfig` 菜单选项，恢复对编辑器的修改。 ![](docs_readme/images/13_sdkconfig_editor.png) # CMake 编辑器 -ESP-IDF Eclipse 插件中还集成了一个 CMake 编辑器，允许用户编辑 CMakeList.txt 等 CMake 文件，支持语法高亮、CMake 命令助手、代码模板等功能。 +ESP-IDF Eclipse 插件中还集成了 CMake 编辑器，允许用户编辑 `CMakeList.txt` 等 CMake 文件，支持语法高亮、CMake 命令助手、代码模板等功能。 ![](docs_readme/images/cmake_editor_ca.png) -如需配置 CMake 编辑器，请前往 Eclipse 的 `偏好设置` > `CMakeEd`。 +如需配置 CMake 编辑器，请前往 Eclipse 的`偏好设置` > `CMakeEd`。 -![](docs_readme/images/zh/cmake_editor_preferences.png) +![](docs_readme/images/cmake_editor_preferences.png) # ESP-IDF 应用程序内存分析 -内存分析编辑器可分析应用程序的静态内存使用情况：概述和详情。 -- `概述`选项卡可简要提供应用程序的内存使用情况； -- `详情`选项卡可详细介绍应用程序中各组件和各符号文件的内存使用情况。 +内存分析编辑器可分析应用程序的静态内存使用情况，并且具有两种选项： +- **概述** 选项卡可简要提供应用程序的内存使用情况； +- **详情** 选项卡可详细介绍应用程序中各组件和各符号文件的内存使用情况。 -其中，`详情`选项卡还支持搜索和排序功能。 +其中，**详情** 选项卡还支持搜索和排序功能。 -启动`应用程序内存分析编辑器`： +启动应用程序内存分析编辑器： 1. 右键点击项目。 -1. 选择 `ESP-IDF：应用程序内存分析`菜单，启动编辑器。 +2. 选择 `ESP-IDF` > `应用程序内存分析`菜单选项，启动编辑器。 **应用程序内存分析 - 概述** -![](docs_readme/images/zh/sizeanalysis_overview.png) +![](docs_readme/images/sizeanalysis_overview.png) **应用程序内存分析 - 详情** -![](docs_readme/images/zh/sizeanalysis_details.png) +![](docs_readme/images/sizeanalysis_details.png) # ESP-IDF 终端 -`ESP-IDF 终端`可为用户在 Eclipse 环境中启动一个本地终端窗口。用户可通过`偏好设置`>`C/C++`>`构建`>`环境`配置所有环境变量。本终端窗口的默认工作目录为当前选定的项目或 `IDF_PATH`（如未选定项目）。 +`ESP-IDF 终端`可为用户在 Eclipse 环境中启动一个本地终端窗口，所有环境变量均可通过`偏好设置` > `C/C++` > `构建` > `环境`进行配置。本终端窗口的默认工作目录为当前选定的项目或 `IDF_PATH`（若未选定项目）。 -终端 PATH 还将同时配置 `esptool`、`espcoredump`、`partition_table` 和 `app_update` 组件路径，允许用户从 ESP-IDF 终端直接进行访问。 +终端 PATH 还将同时配置 `esptool`、`espcoredump`、`partition_table` 和 `app_update` 组件的路径，能够直接从 ESP-IDF 终端直接进行访问。 -启动 `ESP-IDF 终端`： +启动 ESP-IDF 终端： -1. 点击工具栏中的`打开终端`图标。 -1. 从终端下拉菜单中选择`ESP-IDF 终端`，并点击`OK`启动终端。 +* 点击工具栏中的`打开终端`图标。 +* 从终端下拉菜单中选择 `ESP-IDF 终端`，点击 `OK`，启动终端。 -![](docs_readme/images/zh/idf_terminal.png) +![](docs_readme/images/idf_terminal.png) # 安装 ESP-IDF 组件 -直接向您的项目中安装 ESP-IDF 组件： +直接从在线可用的组件中将 ESP-IDF 组件安装到项目中。请按照以下步骤进行操作： -* 从`项目浏览器`中选择需要安装组件的项目，并选择 `安装 ESP-IDF 组件`。 +* 在`项目资源管理器`中右键点击要添加组件的项目，并选择`安装 ESP-IDF 组件`。 - ![](docs_readme/images/ESP-IDF_Components/install_components.png) + ![](docs_readme/images/ESP-IDF_Components/install_components.png) - 查看所有可安装的组件。 + 打开的新窗口中将显示所有可安装的组件。 -* 选中需要安装的组件，并点击 `安装`。此外，您还可以点击 `更多信息`，查看具体组件的更多信息。 - ![](docs_readme/images/ESP-IDF_Components/components_window.png) +* 选中需要安装的组件，并点击`安装`。此外，点击`更多信息`还可以查看组件的使用教程。 -注意，已经安装的组件也会出现的列表中，但 `安装` 选项（`已安装`选项旁边）将禁用。 + ![](docs_readme/images/ESP-IDF_Components/components_window.png) + +已经安装的组件也会出现在列表中，但`已安装`选项旁边的`安装`选项将被禁用。 # 配置环境变量 -如您的 IDF 工具是通过`乐鑫`>`ESP-IDF 工具管理器`>`安装工具`菜单选项安装的，则 Eclipse 将帮您自动填充`偏好设置`>`C/C++ 构建`>`环境`配置所需的环境变量，具体包括： - -* `IDF_PATH` -* `PATH` -* `OPENOCD_SCRIPTS` -* `IDF_PYTHON_ENV_PATH` +在 ESP-IDF 和工具安装过程中，所有必需的环境变量都会由 IDE 自动配置（`乐鑫` > `ESP-IDF 管理器` > `添加 ESP-IDF`）。这些配置可以在 `C/C++` > `构建` > `环境`的偏好设置页面中进行验证。 -如上述环境变量未能自动正确配置，请按照以下步骤操作。 - -1. 前往 `C/C++ 构建`下的`环境`偏好设置页。 -1. 再次点击`添加...`，并输入 `IDF_PATH`，即 ESP-IDF 的完整安装路径。 -1. 按照相同步骤，配置 `OPENOCD_SCRIPTS`、`IDF_PYTHON_ENV_PATH` 和 `PATH` 环境变量。 - -以下均为示例： - -##### IDF_PATH ##### -`/Users/user-name/esp/esp-idf` - -##### OPENOCD_SCRIPTS ##### -`/Users/user-name/.espressif/tools/openocd-esp32/v0.10.0-esp32-20190313/openocd-esp32/share/openocd/scripts` - -##### IDF_PYTHON_ENV_PATH ##### -`/Users/user-name/.espressif/python_env/idf4.0_py3.7_env` - -##### PATH ##### -`/Users/user-name/.espressif/tools/xtensa-esp32-elf/esp32-2019r1-8.2.0/xtensa-esp32-elf/bin:/Users/user-name/.espressif/tools/esp32ulp-elf/2.28.51.20170517/esp32ulp-elf-binutils/bin:/Users/user-name/.espressif/tools/cmake/3.13.4/CMake.app/Contents/bin:/Users/user-name/.espressif/tools/openocd-esp32/v0.10.0-esp32-20190313/openocd-esp32/bin:/Users/user-name/.espressif/tools/ninja/1.9.0/:/Users/user-name/.espressif/python_env/idf4.0_py3.7_env/bin:/Users/user-name/esp/esp-idf/tools:$PATH` - -![](docs_readme/images/zh/2_environment_pref.png) +![](docs_readme/images/2_environment_pref.png) # 配置工具链 -我们需要告诉 Eclipse CDT 在构建项目时需要使用什么核心构建工具链和 CMake 工具链。如您的 IDF 工具是通过`工具`>`ESP-IDF 工具管理器`>`安装工具`菜单选项安装的，则 Eclipse 可自动检测到需要使用的工具链。 +Eclipse CDT 需要被告知在构建项目时使用什么核心构建工具链和 CMake 工具链。若 IDF 工具是通过`乐鑫` > `ESP-IDF 管理器` > `添加 ESP-IDF` 菜单选项安装的，则 IDE 可自动检测到需要使用的工具链。 -如未能自动检测所需工具链，请按照以下步骤操作。 +若插件未能自动检测所需工具链，请按照以下步骤操作。 # 配置核心构建工具链 1. 打开 Eclipse `偏好设置`。 -1. 前往`C/C++`>`核心构建工具链`偏好设置页。 -1. 选中用户定义工具链，点击`添加...`。 -1. 选择 `GCC` 为工具链类型。 -1. 点击`下一步`。 -1. 提供 GCC 工具链设置： +2. 前往 `C/C++` > `核心构建工具链`偏好设置页。 +3. 在用户定义工具链表格右侧，点击`添加...`。 +4. 选择 `GCC` 为工具链类型。 +5. 点击`下一步`。 +6. 提供 GCC 工具链设置： - * **编译器：** /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc, - * **操作系统：** esp32, - * **CPU 架构：** xtensa + * **编译器：** /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc + * **操作系统：** esp32 + * **CPU 架构：** xtensa ![](docs_readme/images/6_core_build_toolchains.png) # 配置 CMake 工具链 -现在，我们需要告诉 CDT 在构建项目时需要使用哪种工具链。这可以在生成 Ninja 文件时将所需的参数传递给 CMake。 +CDT 在构建项目时需要被告知构建项目时使用哪种工具链。这可以在生成 Ninja 文件时将所需的参数传递给 CMake。 -1. 前往 `C/C++`>`CMake`偏好设置页。 -1. 点击`添加...`，启动新的 CMake 工具链配置对话框。 -1. 浏览 CMake 工具链 `Path`。示例：`/Users/user-name/esp/esp-idf/tools/cmake/toolchain-esp32.cmake`。 -1. 从下拉列表中选择 `GCC Xtensa 工具链`编译器。示例：`esp32 xtensa /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc`。 +1. 前往 `C/C++` > `CMake` 偏好设置页。 +2. 点击`添加...`，启动新的 CMake 工具链配置对话框。 +3. 浏览 CMake 工具链 `Path`。例如：`/Users/user-name/esp/esp-idf/tools/cmake/toolchain-esp32.cmake`。 +4. 从下拉列表中选择 GCC Xtensa 工具链编译器。例如：`esp32 xtensa /Users/user-name/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc`。 -> **Note:** Eclipse CDT 在保存工具链偏好设置时有一个已知 bug。因此，我们建议在进行后续操作前，重新启动 Eclipse。 +> **注意：** Eclipse CDT 在保存工具链偏好设置时有一个已知 bug。因此，建议在进行后续操作前，先重新启动 Eclipse。 ![](docs_readme/images/7_cmake_toolchain.png) # 选择 Clang 工具链 -ESP-IDF Eclipse 插件 v2.7.0 及以上版本支持使用 Clang 工具链构建项目。 +1. 创建新项目后，编辑项目配置。 -1. 在升级至或安装 ESP-IDF Eclipse 插件 v2.7.0 或以上版本后，请前往 `乐鑫` > `ESP-IDF 工具管理` > `安装工具` 更新工具链列表及 Clang 工具链所需要的环境变量。 -1. 创建新项目，并编辑项目配置。 ![image](https://user-images.githubusercontent.com/24419842/194882285-9faadb5d-0fe2-4012-bb6e-bc23dedbdbd2.png) -1. 前往 `构建设置`，并选择 clang 工具链。 + +2. 前往`构建设置`并选择 clang 工具链。 + ![image](https://user-images.githubusercontent.com/24419842/194882462-3c0fd660-b223-4caf-964d-58224d91b518.png) -> **Note:** Clang 工具链目前仅供研发试用，可能会出现一些与 ESP-IDF 不兼容的构建错误。下方针对目前的 ESP-IDF master 分支 (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty)，罗列了一些与 Clang 工具链有关的常见问题及解决方法，详情请见[这里](https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS__CN.md#clang-toolchain-buid-errors). +> **注意：** Clang 工具链目前仅供研发试用，可能会出现一些与 ESP-IDF 不兼容的构建错误。针对目前 ESP-IDF 的 master 分支 (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty)，下面罗列了一些与 Clang 工具链有关的常见问题及解决方法，详情请见[此处](https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS__CN.md#clang-toolchain-buid-errors)。 # 启动配置 @@ -418,13 +407,13 @@ ESP-IDF Eclipse 插件 v2.7.0 及以上版本支持使用 Clang 工具链构建 如需使用自定义启动配置和烧录参数，请按照以下步骤操作。 1. 点击`启动配置`编辑按钮。 -1. 切换至`主选项卡`。 -1. 指定应用程序的运行 `位置`。由于 `idf.py` 是一个 Python 文件，因此还将配置 Python 系统路径。示例：`${system_path:python}`。 -1. 指定应用程序的`工作目录`。示例：`${workspace_loc:/hello_world}`。 -1. 在其他`参数`编辑框，新增一条将在指定工作目录下运行的烧录命令。 -1. 烧录命令示例：`/Users/user-name/esp/esp-idf/tools/idf.py -p /dev/cu.SLAB_USBtoUART flash`。 -1. 点击 `OK`，保存设置。 -1. 点击`启动`图标，将应用程序烧录到选定的开发板中。 +2. 切换至`主选项卡`。 +3. 指定应用程序的运行`位置`。由于 `idf.py` 是一个 Python 文件，因此系统还将配置 Python 的系统路径。例如：`${system_path:python}`。 +4. 指定应用程序的`工作目录`。例如：`${workspace_loc:/hello_world}`。 +5. 在其他`参数`编辑框，新增一条将在指定工作目录下运行的烧录命令。 +6. 烧录命令示例：`/Users/user-name/esp/esp-idf/tools/idf.py -p /dev/cu.SLAB_USBtoUART flash`。 +7. 点击 `OK`，保存设置。 +8. 点击`启动`图标，将应用程序烧录到选定的开发板中。 ![](docs_readme/images/zh/11_launch_configuration.png) @@ -433,12 +422,12 @@ ESP-IDF Eclipse 插件 v2.7.0 及以上版本支持使用 Clang 工具链构建 # 更改语言 -IDF Eclipse 插件可支持不同语言。如需更改，请按照以下步骤操作。 +IDF Eclipse 插件支持不同的语言。如需更改，请按照以下步骤操作。 1. 前往菜单栏，点击`乐鑫`。 -1. 在下拉菜单中选择`更改语言`。 -1. 在子下拉菜单中选择所需的语言。 -1. 此后，Eclipse 重启后将切换至所选择的语言。 +2. 在下拉菜单中选择`更改语言`。 +3. 在子下拉菜单中选择所需的语言。 +4. Eclipse 将在重启后切换至所选择的语言。 ![](docs_readme/images/change_language.png) @@ -450,199 +439,204 @@ IDF Eclipse 插件可支持不同语言。如需更改，请按照以下步骤 ## 有关借助提示查看器解决 ESP-IDF 常见问题的建议 ESP-IDF 项目构建中的大多数常见错误均可从提示数据库 (`tools/idf_py_actions/hints.yml`) 中找到答案。ESP-IDF Eclipse 插件专门提供了一个提示查看器，允许用户查找错误信息。 -使用提示查看器必须首先拥有 `hints.yml` 文件（ESP-IDF v5.0 及以上版本均支持）。如果你的 ESP-IDF 版本较低，则可从[这里](https://github.com/espressif/esp-idf/blob/master/tools/idf_py_actions/hints.yml)手动下载 `hints.yml` 并将其保存至 `esp-idf/tools/idf_py_actions/` 目录下。如需从 GitHub 下载文件，请单击 `Raw` 按钮并选择 `Save as...`。 -打开提示查看器：前往 `窗口` > `显示视图` > `其他` > `乐鑫` > `提示`，即可打开如下视图： +使用提示查看器必须首先拥有 `hints.yml` 文件（ESP-IDF v5.0 及以上版本均支持）。如果你的 ESP-IDF 版本较低，则可从[此处](https://github.com/espressif/esp-idf/blob/master/tools/idf_py_actions/hints.yml)手动下载 `hints.yml` 并将其保存至 `esp-idf/tools/idf_py_actions/` 目录下。如需从 GitHub 下载文件，请单击 `Raw` 按钮并选择 `Save as...`。 + +若想打开提示查看器，请前往`窗口` > `显示视图` > `其他...` > `乐鑫` > `提示`，就能看到如下视图： + ![image](https://user-images.githubusercontent.com/24419842/189666994-78cc8b24-b934-426f-9df5-79af28c50c55.png) -现在，你可以直接输入或从构建日志复制粘贴错误信息，比如： -`ccache error: Failed to create temporary file for esp-idf/libsodium/CMakeFiles/..../....: No such file or directory` +现在，你可以直接输入或从构建日志复制粘贴错误信息，例如：`ccache error: Failed to create temporary file for esp-idf/libsodium/CMakeFiles/..../....: No such file or directory` ![image](https://user-images.githubusercontent.com/24419842/189672552-994624f3-c0c5-48e6-aa2c-61e4ed8915e5.png) -此外，双击错误信息还可以放大提示信息。 +此外，双击错误类型还会跳出新窗口，展现详细提示。 ![image](https://user-images.githubusercontent.com/24419842/189673174-8ce40cda-6933-4dc4-a555-5d2ca617256e.png) ## 错误日志 -`错误日志`视图可以显示插件记录的所有警告和错误，其底层日志文件（.log 文件）保存在工作空间的 .metadata 子目录下。 +`错误日志` 视图可以显示插件记录的所有警告和错误，其底层日志文件（.log 文件）保存在工作区的 .metadata 子目录下。 -打开`错误日志`视图，请前往`窗口`>`显示视图`>`错误日志`。 +若想打开`错误日志`视图，请前往`窗口` > `显示视图` > `错误日志`。 -保存当前日志内容至本地文件，请从工具栏中点击`导出日志`按钮或右键选择`导出日志...`。此后，输入文件名即可保存日志至本地文件。 +若想保存当前日志内容至本地文件，请从工具栏中点击`导出日志`按钮或右键选择`导出日志...`，输入文件名即可保存日志至本地文件。 注意，在提交问题时一定要提供错误日志。 -![](docs_readme/images/zh/export_log.png) +![](docs_readme/images/export_log.png) ## 控制台视图日志 `控制台`视图可显示与当前运行或构建有关的所有警告和错误。 -打开`控制台`视图，请前往`窗口`>`显示视图`>`控制台`。 +若想打开`控制台`视图，请前往`窗口` > `显示视图` > `控制台`。 ![](docs_readme/images/CDT_Build_Console.png) ## CDT 全局构建日志 -打开 CDT 全局构建日志，请前往`偏好设置`>`C/C++`>`构建`>`日志`。 +若想打开 CDT 全局构建日志，请前往`偏好设置` > `C/C++` > `构建` > `日志`。 ## 乐鑫 IDF 工具集控制台 -`乐鑫 IDF 工具控制台`为`控制台`视图的组成部分，通常仅在通过 Eclipse 安装 IDF 工具集时使用。 +乐鑫 IDF 工具控制台是`控制台`视图的组成部分，通常仅在通过 Eclipse 安装 IDF 工具集时使用。 -如您在通过`乐鑫`>`ESP-IDF 工具管理器`>`安装工具`方式安装 IDF 工具集时出现任何问题，即可使用本控制台查看错误报告。 +通过`乐鑫` > `ESP-IDF 工具管理器` > `安装工具`的方式安装 IDF 工具集时如果出现任何问题，请使用本控制台查看错误报告。 -如本控制台未自动启动，请前往`中控台`视图，点击`显示选中的中控台`按钮。 +若本控制台未自动启动，请前往`控制台`视图，点击`显示选中的中控台`按钮。 ![](docs_readme/images/zh/IDF_tools_console.png) ## 堆栈追踪 -详见这里。 +详见此处。 # 从 Eclipse 市场安装 IDF Eclipse 插件 -从 Eclipse 市场安装 IDF Eclipse 插件，请按照以下步骤操作。 +请按照以下步骤，从 Eclipse 市场安装 IDF Eclipse 插件。 -1. 打开 Eclipse，前往`帮助`>`Eclipse 市场...`。 -1. 在搜索框中输入 `ESP-IDF Eclipse Plugin`，并点击`Go`。 -1. 点击`安装`，并按照提示完成所有安装步骤。 -1. 重启 Eclipse。 +1. 打开 Eclipse，前往`帮助` > `Eclipse 市场...`。 +2. 在搜索框中输入 `ESP-IDF Eclipse Plugin`，并点击`前往`。 +3. 点击`安装`，并按照提示完成所有安装步骤。 +4. 重启 Eclipse。 ![](docs_readme/images/market_place.png) # 从本地文件安装 IDF Eclipse 插件 -1. 下载最新版 ESP-IDF Eclipse 插件：https://github.com/espressif/idf-eclipse-plugin/releases -1. 打开 Eclipse，前往`帮助`>`安装新软件`。 -1. 点击`添加`按钮。 -1. 在`添加`仓库对话框中选择`存档`> `com.espressif.idf.update-vxxxxxxx.zip` 文件。 -1. 点击`添加`。 -1. 从列表中选择 `Espressif IDF`，并按照提示完成所有安装步骤。 -1. 重启 Eclipse。 +1. 下载最新版 ESP-IDF Eclipse 插件：https://github.com/espressif/idf-eclipse-plugin/releases。 +2. 打开 Eclipse，前往`帮助` > `安装新软件`。 +3. 点击`添加...`按钮。 +4. 在添加仓库对话框中选择`存档` > `com.espressif.idf.update-vxxxxxxx.zip` 文件。 +5. 点击`添加`。 +6. 从列表中选择 `Espressif IDF`，并按照提示完成所有安装步骤。 +7. 重启 Eclipse。 ![](docs_readme/images/zh/1_idffeature_install.png) -# 如何升级我的 IDF Eclipse 插件？ +# 如何升级 IDF Eclipse 插件？ -如您是首次在 Eclipse 软件中安装 IDF 插件，则首先需要按照以下步骤`添加`最新插件地址： +如果首次在 Eclipse 软件中安装 IDF 插件，则需要先按照以下步骤添加最新插件地址： -1. 前往`窗口`>`偏好设置`>`安装/更新`>`可用软件站点`。 -1. 点击`添加`。 -1. 输入最新仓库的地址：https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/ -1. 点击 `OK`。 +1. 前往`窗口` > `偏好设置` > `安装/更新` > `可用软件站点`。 +2. 点击`添加`。 +3. 输入最新仓库的地址：https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/。 +4. 点击 `OK`。 -如果您已经使用最新仓库的 URL 安装了 IDF Eclipse 插件，则可以按照以下步骤获取更新。 +如果已经使用最新仓库的 URL 安装了 IDF Eclipse 插件，则可以按照以下步骤获取更新。 -1. 前往`帮助`>`检查更新`。 -1. 如有新的更新，请选择`乐鑫 IDF 插件`，并取消勾选所有其他项目。 -1. 点击`下一步`，并按照提示完成所有安装步骤。 +1. 前往`帮助` > `检查更新`。 +2. 如有新的更新，请选择 `ESP-IDF Eclipse 插件`，并取消勾选所有其他项目。 +3. 点击`下一步`，并按照提示完成所有安装步骤。 ![](docs_readme/images/Update_plugins.png) # 导入一个现有的 IDF 项目 -1. 请首先确保您处于 `C/C++ 视图`之下。 -1. 右键点击`项目资源管理器`。 -1. 选择`导入...`菜单。 -1. 前往`乐鑫导入向导`菜单，选择`现有 IDF 项目`。 -1. 点击`下一步`。 -1. 点击`浏览...`，选择一个本地项目的位置。 -1. 更改 `项目名称`（否则将使用默认名称）。 -1. 点击`完成`，将选定项目作为一个 CMake 项目导入 Eclipse 工作空间。 +1. 首先请确保处于 `C/C++ 视图`。 +2. 右键点击`项目资源管理器`。 +3. 选择`导入...`菜单。 +4. 前往`乐鑫`导入向导菜单，选择`现有 IDF 项目`。 +5. 点击`下一步`。 +6. 点击`浏览...`，选择现有项目的目录位置。 +7. 更改`项目名称`，否则将使用默认名称。 +8. 点击`完成`，将选定项目作为一个 CMake 项目导入 Eclipse 工作区。 ![](docs_readme/images/zh/5_import_project.png) -# 导入一个现有的 Debug 启动配置 +# 导入现有的 Debug 启动配置 将一个现有的启动配置导入 Eclipse： -1. 前往`文件`>`导入...`。 -1. 在`导入`对话框中，扩展`运行/调试`组，并选择`启动配置`。 -1. 点击`下一步`。 -1. 点击`浏览...`，选择本地文件系统中所需的位置。 -1. 选择包含启动文件的文件夹，然后点击 `OK`。 -1. 勾选所需的文件夹并启动文件。 -1. 如果您正在使用新的配置文件替代先前一个相同名称的配置，请选择`覆盖现有启动配置（忽略警告）`。 -1. 点击`完成`。 +1. 前往`文件` > `导入...`。 +2. 在`导入`对话框中，扩展`运行/调试`组，并选择`启动配置`。 +3. 点击`下一步`。 +4. 点击`浏览...`，选择本地文件系统中所需的位置。 +5. 选择包含启动文件的文件夹，然后点击 `OK`。 +6. 勾选所需的文件夹并启动文件。 +7. 若想使用新的配置文件替代先前同名的配置，请选择`覆盖现有启动配置并忽略警告`。 +8. 点击`完成`。 # GDBStub 调试 -乐鑫 Eclipse 插件集成了 GDBStub 调试功能，允许用户在 Eclipse 界面中诊断处于 panic 模式下的芯片并进行问题调试。 +乐鑫 Eclipse 插件集成了 GDBStub 调试功能，能够在 Eclipse 界面中诊断处于 panic 模式下的芯片并进行问题调试。 使能 GDBStub 调试功能： -1. 前往 `sdkconfig` 打开配置编辑器。 +1. 双击项目根目录中的 `sdkconfig` 文件，启动配置编辑器。 + ![](docs_readme/images/GDBStubDebugging/sdkconfig_editor.png) -1. 展开 `Component Config` 部分，并选择 `ESP System Settings`；窗口右侧在 `Panic handler behaviour` 中选择 `GDBStub on Panic`。 +2. 展开`组件配置`部分并选择 `ESP 系统设置`。在设置菜单中`紧急处理程序行为`右侧的下拉选项里选择`紧急时使用 GDBStub`。 + ![](docs_readme/images/GDBStubDebugging/sdkconfig_editor_panic_behavior.png) -至此，实例一旦发生 panic，则串口监视器将自动进入 GDBStub 调试页面。 +至此，实例一旦触发紧急情况，串口监视器将自动进入 GDBStub 调试页面。 使用 GDBStub 调试功能： -1. 创建一个 `hello_world` 项目模版，并在 main c 文件中增加下方代码： +1. 创建一个 `hello_world` 项目模版，并在 main c 文件中添加下方代码： - ``` - This is a global variable
- COREDUMP_DRAM_ATTR uint8_t global_var; - ``` + ``` + This is a global variable
+ COREDUMP_DRAM_ATTR uint8_t global_var; + ``` -1. 接着，在 `esp_restart()` 功能之前插入下方代码： +2. 接着，在 `esp_restart()` 功能之前插入下方代码： - ``` - global_var = 25;
- assert(0);
- ``` + ``` + global_var = 25; + assert(0); + ``` 最终文件实例： + ![](docs_readme/images/GDBStubDebugging/code_example.png) -构建烧录项目，并启动串口监视器。我们在第 45 行发送一个失败信号，这会使芯片进入 panic 模式。之后会跳出调试模式界面，此时芯片将停止工作。 +构建并烧录项目，启动串口监视器。我们在第 45 行发送一个失败信号，这会使芯片进入 panic 模式。之后会跳出调试模式界面，此时芯片将停止工作。 -注意，芯片进入 panic 模式后无法再从断点继续执行，您必须停止运行并重新启动芯片（使用 idf 命令或重新启动串口监视器）。 +注意，芯片进入 panic 模式后无法再从断点继续执行，而必须使用 idf 命令来停止运行并重新启动芯片，或者也可以重新启动串口监视器。 ![](docs_readme/images/GDBStubDebugging/debug_panic_mode.png) -您可以在此界面查看寄存器堆栈踪迹，甚至堆栈框架中变量的值。 +此界面可以查看寄存器堆栈踪迹，甚至可以查看堆栈框架中变量的值。 -退出调试界面，请点击`停止`。 +点击`停止`按钮，退出调试界面。 # Core Dump 调试 -乐鑫 ESP-IDF Eclipse 插件允许用户调试芯片崩溃时的 core dump 信息，且无需进行额外配置。目前，仅支持 UART core dump 捕获与调试。 +乐鑫 ESP-IDF Eclipse 插件能够调试芯片崩溃时的 core dump 信息，且无需进行额外配置。目前，仅支持 UART core dump 捕获与调试。 + +参照下列步骤，在项目中打开 core dump 调试功能： -为你的项目打开 core dump 调试功能： +1. 双击项目根目录中的 `sdkconfig` 文件，启动配置编辑器。 -1. 在项目的根目录中打开 `sdkconfig` 文件。此时，你会看到配置编辑器窗口。 +2. 在左侧列表中选择 `Core Dump`，并将`数据接收端`配置为 `UART`。 -1. 在左侧列表中选择 `Core Dump`，并将 `Data Destination` 配置为 `UART`。 ![](docs_readme/images/CoreDumpDebugging/sdkconfig_editor.png) -至此，core dump 功能已经打开。此后，一旦项目发生任何崩溃，仅需打开串口监控器即可查看 core dump 信息，还可在 eclipse 中打开调试视图，方便用户的诊断。 +至此，core dump 功能已经打开。此后，一旦项目发生任何崩溃，仅需打开串口监视器即可查看 core dump 信息，还可在 eclipse 中打开调试视图，方便进行诊断。 -你还可以查看寄存器堆栈追踪，甚至查看堆栈帧中的变量值。 +此界面可以查看寄存器堆栈踪迹，甚至可以查看堆栈框架中变量的值。 -退出调试窗口：点击`停止`按钮。 +点击`停止`按钮，退出调试界面。 # 通过 USB 升级设备固件 (DFU) -设备固件升级 (DFU) 允许用户通过 USB 升级设备固件，但必须满足一些条件： +设备固件升级 (DFU) 是通过 USB 升级设备固件的一种机制，但必须满足下列条件： - DFU 支持仅限 ESP32-S2 和 ESP32-S3 系列。 -- 其次，您还需额外链接一些导线，具体见下表。此外，您还可以参考针对 ESP32-S2 开发板的[示例](https://blog.espressif.com/dfu-using-the-native-usb-on-esp32-s2-for-flashing-the-firmware-b2c4af3335f1)。 +- 需要额外连接一些导线，具体见下表。此外，也可以可以参考针对 ESP32-S2 开发板的[示例](https://blog.espressif.com/dfu-using-the-native-usb-on-esp32-s2-for-flashing-the-firmware-b2c4af3335f1)。 | GPIO | USB | | -----| ------------| @@ -651,107 +645,98 @@ ESP-IDF 项目构建中的大多数常见错误均可从提示数据库 (`tools/ | GND | GND（黑） | | +5V | +5V（红） | -确认上述条件满足后： +确认满足上述条件后： + +1. 按住 Boot 键的同时按一下 Reset 键进入 bootloader 模式。此时，芯片被被识别为 DFU 设备并进行烧录。 -1. 按住 Boot 键的同时按一下 Reset 键进入“固件下载”模式。芯片只有在“下载模式”中才可以被识别为 DFU 设备，并进行 USB 烧录。 -1. 通过 [Zadig 工具](https://zadig.akeo.ie/>) 安装 USB 驱动（仅支持 Windows）。这里需要注意几点： - - 注意必须首先使芯片进入“下载模式”且已被识别为 DFU 设备后，再运行 Zadig 工具安装 USB 驱动。 - - Zadig 工具可能识别到若干个 USB 接口，请仅为未安装驱动的接口（通常为接口 2）进行安装 WinUSB 驱动，不要为同一个接口重复安装驱动。 + +1. 通过 [Zadig 工具](https://zadig.akeo.ie/)安装 USB 驱动（仅支持 Windows）。这里需要注意几点： + - 必须首先使芯片进入“下载模式”且已被识别为 DFU 设备后，再运行 Zadig 工具安装 USB 驱动。 + - Zadig 工具可能会识别到若干个 USB 接口，请仅为未安装驱动的接口（通常为接口 2）进行安装 WinUSB 驱动，不要为同一个接口重复安装驱动。 - 不推荐手动安装 Windows 设备管理器中的驱动，这可能导致烧录失败。 -完成上述步骤后，可通过 DFU 构建烧固件，具体步骤如下： +完成上述步骤后，可通过 DFU 构建并烧录固件，具体步骤如下： 1. 编辑活跃启动配置。 -1. 前往主页面，选择 `Flash over DFU` 选项。 -1. 选择需要的 IDF 目标。 -1. 此时，使用 build 命令会生成一个新文件 (dfu.bin)，可用于后续的烧录。 +2. 前往主页面，选择`烧录 DFU` 选项。 +3. 选择需要的 IDF 目标。 +4. 此时，使用 build 命令会生成一个新文件 (dfu.bin)，可用于后续的烧录。 -![DFU actions](https://user-images.githubusercontent.com/24419842/226182180-286099d3-9c1c-4394-abb0-212d43054529.png) +![DFU 步骤](https://user-images.githubusercontent.com/24419842/226182180-286099d3-9c1c-4394-abb0-212d43054529.png) -更多信息（包括常见错误和已知问题），请见[指南](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32s3/api-guides/dfu.html#usb-drivers-windows-only)。 +包括常见错误和已知问题在内的更多信息，请参考[指南](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32s3/api-guides/dfu.html#usb-drivers-windows-only)。 # 应用层追踪 -ESP-IDF 的[应用层追踪](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/api-guides/app_trace.html) 功能可用于分析程序行为。ESP-IDF Eclipse 插件也特别提供了用户界面，允许通过命令开始/停止追踪，并进行数据处理。具体参考可见 [app_trace_to_host](https://github.com/espressif/esp-idf/tree/master/examples/system/app_trace_to_host) 项目，创建方式如下： +ESP-IDF 的[应用层追踪](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/api-guides/app_trace.html)功能可用于分析程序行为。ESP-IDF Eclipse 插件也特别提供了用户界面，允许通过命令开始和停止追踪，并进行数据处理。具体参考可见 [app_trace_to_host](https://github.com/espressif/esp-idf/tree/release/v5.0/examples/system/app_trace_to_host) 项目，如果使用 ESP-IDF 5.1 及更高版本，则可参考 [app_trace_basic](https://github.com/espressif/esp-idf/tree/release/v5.1/examples/system/app_trace_basic) 项目。这些项目可以直接在插件中创建。 ![](docs_readme/images/AppLvlTracing_1.png) -启动应用层追踪功能之前，请首先完成项目的调试配置，包括指定使用的开发板名称。否则无法正常启动 OpenOCD 服务器。 +启动应用层追踪功能之前，首先请完成项目的调试配置，包括指定使用的开发板名称。否则无法正常启动 OpenOCD 服务器。 ![](docs_readme/images/AppLvlTracing_3.png) -配置完成后，从 `项目浏览器` 中选择您的项目，并点击 `ESP-IDF:Application Level Tracing`： +配置完成后，在`项目资源管理器`中右键点击对应项目，并选择 `ESP-IDF` > `应用层追踪`： ![](docs_readme/images/AppLvlTracing_2.png) -注意，本功能需要调用 OpenOCD 服务器，因此启动需要一定时间，请耐心等待。另外，调用自动完成，无需从外部特别打开 OpenOCD 服务器。应用层追踪启动后会自动填充一些配置，您也可以根据个人需要修改。 +注意，本功能需要调用 OpenOCD 服务器，因此启动需要一定时间，请耐心等待。另外，调用自动完成，无需从外部打开 OpenOCD 服务器。应用层追踪启动后会自动填充一些配置，也可以根据个人需要进行修改。 开始命令： * 语法：`start [poll_period [trace_size [stop_tmo [wait4halt [skip_size]]]]` * 参数： - * `outfile`：文件路径（从任一 CPU），格式应满足 `file://path/to/file`。 - * `poll_period`：可用追踪数据的轮询周期（单位：毫秒）。如果大于 0，则命令以“非阻塞”模式运行。默认值 1（1 毫秒）。 - * `trace_size`：可追踪数据的最大长度限制（单位：字节）。注意，该参数使能后，追踪数据达到配置的长度后则自动停止。默认值 -1（不限制最大长度）。 - * `stop_tmo`：超时限制（单位：秒），即如特定期间中未收到数据则停止追踪。默认值 -1（不限制超时）。如需配置，注意应长于两条追踪命令之间的最大间隔。 - * `wait4halt`：配置为 0 立刻开始追踪，否则等待目标停止后开始追踪（复位后、出现断点等）。默认值 0（立刻开始追踪）。 - * `skip_size`：开始追踪后跳过若干个字节。默认值 0（跳过 0 个字节）。 + * `outfile`：用于指定文件路径，该文件可保存来自两个 CPU 的数据。此参数应采用以下格式 `file://path/to/file`。 + * `poll_period`：可用追踪数据的轮询周期（单位：毫秒）。如果大于 0，则命令以“非阻塞”模式运行。默认值为 1 毫秒。 + * `trace_size`：可追踪数据的最大长度限制（单位：字节）。当追踪数据达到配置的长度后就会自动停止。默认值 -1（不限制最大长度）。 + * `stop_tmo`：超时限制（单位：秒）。若特定期间内未收到数据则停止追踪。默认值 -1（不限制超时）。如需配置，注意该参数值应大于两条追踪命令之间的最大间隔。 + * `wait4halt`：配置为 0 则立刻开始追踪；否则，等待目标暂停（如复位后、遇到断点等），然后自动恢复并开始跟踪。默认值为 0。 + * `skip_size`：开始追踪后跳过若干个字节。默认值为 0。 -更多信息，请见[这里](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/api-guides/app_trace.html?)。 +更多信息，请参考[此处](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/api-guides/app_trace.html?)。 ![](docs_readme/images/AppLvlTracing_4.png) 另外两个参数 `Trace Processing Script` 和 `Start Parsing Command` 用于解析输出文件。 * `Trace Processing Script` 配置解析脚本的存储路径，默认为 ESP-IDF 中的 logtrace_proc.py -* `Start Parsing Command` 配置解析结果文件的存储路径，默认为 `$IDF_PATH/tools/esp_app_trace/logtrace_proc.py/path/to/trace/file/path/to/program/elf/file`。 +* `Start Parsing Command` 配置解析结果文件的存储路径，默认为 `$IDF_PATH/tools/esp_app_trace/logtrace_proc.py/path/to/trace/file/path/to/program/elf/file`，必要时可进行修改。 -注意，右侧的 `Start parse` 按钮默认将处于禁用状态。此时，可以点击窗口右下方的 `开始` 按钮，这将生成一个 dump 文件，并同时解禁 `Start parse` 按钮。 +注意，右侧的`开始解析`按钮默认处于禁用状态。可以点击窗口右下方的`开始`按钮，生成 dump 文件并同时解禁`开始解析`按钮。此时按钮会变为`停止`，以便停止跟踪。 -此后，点击 `Start parse` 按钮，从 Eclipse 控制台查看解析脚本的输出： +生成输出文件后，点击`开始解析`按钮，从 Eclipse 控制台查看解析脚本的输出情况： ![](docs_readme/images/AppLvlTracing_5.png) - -# ESP-IDF Master 更新 - -您如果在使用 ESP-IDF 的 master 分支，并希望进行升级：请打开 Eclipse 插件，前往 `乐鑫` > `ESP-IDF 工具管理器`，并点击 `更新 ESP-IDF master`。 - -![image](https://user-images.githubusercontent.com/24419842/182107159-16723759-65e0-4c34-9440-ebe2f536e62a.png) - -> **Note:**该选项仅适用于 ESP-IDF 的 master 分支。 - # ESP-IDF 分区表编辑器界面 -`ESP-IDF: 分区表编辑器`命令允许您以更便捷的方式编辑您的[分区表](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/partition-tables.html)。在此界面中，您可以查看所有支持的类型和子类型，并监控输入数据。 - -> **Note:**此命令仅支持 IDF-Eclipse 2.8.0 及更高版本中。 +分区表编辑器命令提供了一种方便快捷的方式来编辑[分区表](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/partition-tables.html)。在此界面中，可以查看所有支持的类型和子类型，并监控输入的数据。 具体操作步骤如下： 1. 前往`项目资源管理器`，打开需要自定义分区表的 ESP-IDF 项目。 -1. 在`项目资源管理器`中右键单击项目，并选择 `ESP-IDF: 分区表编辑器`命令： +2. 在`项目资源管理器`中右键单击项目，并选择 `ESP-IDF` > `分区表编辑器`命令： ![partition_table_editor_3](https://user-images.githubusercontent.com/24419842/216105408-ca2e73ce-5df3-4bdd-ac61-b7265deb9b44.png) - 当首次打开所选项目的分区表编辑器时，您将看到标准的可编辑内容。错误（如果有）将高亮显示。您可以将鼠标悬停错误之上以获得详细提示： + 首次打开所选项目的分区表编辑器时，能看到标准的可编辑内容。如果存在错误，将高亮显示。鼠标悬停在错误之上可以获得详细提示： ![partition_table_editor_4](https://user-images.githubusercontent.com/24419842/216106804-703b2eb4-b141-48de-8559-0599f072219f.png) -1. 单击`保存`或`保存并退出`，以保存您的更改。 +3. 单击`保存`或`保存并退出`，以保存更改。 -要使用自定义的分区表， +若想使用自定义的分区表，请参照以下步骤： 1. 前往 `sdkconfig` 并按照下图设置 `Custom partition table CSV`： - ![partition_table_editor](https://user-images.githubusercontent.com/24419842/216104107-2844068b-8412-468b-931f-b4778af4417c.png) + ![partition_table_editor](https://user-images.githubusercontent.com/24419842/216104107-2844068b-8412-468b-931f-b4778af4417c.png) # NVS 表编辑器 -`NVS 表编辑器`可以根据 CSV 文件中提供的键值对，生成二进制文件。生成的二进制文件与 [ESP-IDF 非易失性存储](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/storage/nvs_flash.html) 中定义的 NVS 架构兼容。CSV 文件应满足如下格式： +NVS 表编辑器可以根据 CSV 文件中提供的键值对，生成二进制文件。生成的二进制文件与 [ESP-IDF 非易失性存储库](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/storage/nvs_flash.html)中定义的 NVS 架构兼容。CSV 文件应满足如下格式： ``` key,type,encoding,value <-- column header (must be the first line) @@ -759,31 +744,43 @@ ESP-IDF 的[应用层追踪](https://docs.espressif.com/projects/esp-idf/zh_CN/l key1,data,u8,1 key2,file,string,/path/to/file ``` -> **Note:** 上述格式基于 ESP-IDF 的 [NVS 分区生成工具](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/storage/nvs_partition_gen.html)。 -具体操作步骤如下： +> **注意：** 上述格式基于 ESP-IDF 的 [NVS 分区生成程序](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/storage/nvs_partition_gen.html)。 -1. 在`项目资源管理器`中右键单击项目 -1. 选择 `ESP-IDF: NVS 表编辑器`命令： +具体操作步骤如下： - ![NVS Table Editor](https://user-images.githubusercontent.com/24419842/216114697-9f231211-f5dd-431b-9432-93ecc656cfec.png) +1. 在`项目资源管理器`中右键单击项目。 +2. 点击 `ESP-IDF` > `NVS 表编辑器`： - > **Note:**此命令仅支持 IDF-Eclipse 2.8.0 及更高版本中。 + ![NVS 表编辑器](https://user-images.githubusercontent.com/24419842/216114697-9f231211-f5dd-431b-9432-93ecc656cfec.png) -1. 根据需求，更改 CSV 数据 -1. 点击`保存`按钮保存更改。如果一切正常，您将在对话框顶部看到信息消息： +3. 根据需求，更改 CSV 数据 +4. 点击`保存`按钮保存更改。如果一切正常，对话框顶部将出现信息提示 ![NVS_TABLE_EDITOR_2png](https://user-images.githubusercontent.com/24419842/216115906-9bb4fe55-293b-4c6b-8d22-0aa3520581ab.png) -1. 生成分区二进制文件（如果需要加密二进制文件，请选择 `encrypt`；如果需要使用自己的密钥，请禁用 `generate key` 选项）。您可在对话框顶部，查看有关二进制文件的生成结果。如内容过长不能全部显示，您可以将鼠标悬停，以查看完整消息： +5. 生成分区二进制文件（如果需要加密二进制文件，请选择`加密`；如果需要使用自己的密钥，请禁用`生成密钥`选项）。对话框顶部将出现信息提示，可查看有关二进制文件的生成结果。如内容过长不能全部显示，可以将鼠标悬停以查看完整消息 ![NVS_Table_Editor_4](https://user-images.githubusercontent.com/24419842/216117261-9bee798a-3a9e-4be5-9466-fc9d3847834b.png) - > **Note:** 错误（如果有）将高亮显示。您可以将鼠标悬停错误之上以获得详细提示。此外，如 CSV 文件保存失败，您可在对话框顶部查看错误消息： + > **Note:** 若存在错误，则将高亮显示。鼠标悬停于错误之上可获取详细错误提示。此外，如果 CSV 文件保存失败，对话框顶部也将出现错误提示。 ![NVS_Table_editor_5](https://user-images.githubusercontent.com/24419842/216118486-69f819fa-7a95-49ae-805e-473cd2c424e8.png) -完成上述所有步骤后，您将在项目目录中看到 `nvs.csv` 和 `nvs.bin` 文件。 +完成上述所有步骤后，项目目录中将出现 `nvs.csv` 和 `nvs.bin` 文件。 + + +# 将二进制数据写入 flash 中 + +可以通过 `ESP-IDF` > `将二进制数据写入 flash 中` 命令将二进制数据写入 ESP flash 芯片，该命令可通过右键点击项目资源管理器中的项目访问： + +Screenshot 2023-10-16 at 10 51 52 + +点击此命令后，将打开 `将二进制数据写入 flash 中` 对话框。对话框中提供了可编辑的默认值，用于设置二进制路径和偏移量。可以通过 `ESP-IDF` > `分区表编辑器`命令查看分区表以检查正确的偏移量，或者通过手动打开 ``partitions.csv`` 文件进行检查。 + +Screenshot 2023-10-16 at 10 51 27 + +点击 `Flash` 按钮后，flash 命令的结果将显示在此对话框内。 # 如何进行本地构建 @@ -796,60 +793,62 @@ ESP-IDF 的[应用层追踪](https://docs.espressif.com/projects/esp-idf/zh_CN/l mvn clean verify -Djarsigner.skip=true ``` -以上命令将生成 p2 更新站点 artifact： +以上命令将生成 p2 更新站点相关文件： * 名称：`com.espressif.idf.update-*` * 存储路径：`releng/com.espressif.idf.update/target` -后续可按照 介绍 进行安装。 +后续可按照介绍进行安装。 # 如何获得最新的开发构建 1. 前往最新 master 分支，找到 最新 commit 。 -1. 点击最新 commit 处的 :white_check_mark:。 -1. 点击 `Details`。 -1. 点击左侧 `Summary`。 -1. 下滑至页面底部，找到 `Artifacts`。 -1. 下载 `com.espressif.idf.update`，并按照 介绍 进行安装。 +2. 点击最新 commit 处的 :white_check_mark: 按键。 +3. 点击 `Details`。 +4. 点击左侧 `Summary`。 +5. 下滑至页面底部，找到 `Artifacts`。 +6. 下载 `com.espressif.idf.update`，并按照介绍进行安装。 # 自定义 IDE 配置 ## 自定义构建目录 -IDE 支持配置自定义构架目录： +IDE 支持配置自定义构建目录： -1. 选择您的项目，从顶部工具栏打开配置 `Edit` 界面。 -2. 选择 `Build Settings` 选项卡。 -3. 在 `Additional CMake arguments` 选项框提供自定义目录，可以选择项目中的某个文件夹，也可以选择项目外的某个文件夹，格式为 `-B `，例 `-B /Users/myUser/esp/generated`。 +1. 选择一个项目，从顶部工具栏打开配置 `编辑` 界面。 +2. 选择 `构建设置` 选项卡。 +3. 在 `额外的 CMake 参数` 选项框提供自定义目录，可以选择项目中的某个文件夹，也可以选择项目外的某个文件夹，格式为 `-B `，例 `-B /Users/myUser/esp/generated`。 4. 点击 `OK` 开始构建项目。 -注意，此配置将改变所有项目构建 artifact 的保存路径。 +注意，此配置将改变所有项目构建文件的保存路径。 ![](docs_readme/images/custombuilddir.png) # Wokwi 模拟器 -1. 按照[此处](https://github.com/MabezDev/wokwi-server/)说明，安装 `wokwi-server`。 -2. 在 Eclipse CDT 的构建环境变量中配置 `WOKWI_SERVER_PATH` 为 `wokwi-server` 可执行文件的路径（`Preferences` > `C/C++` > `Build` > `Environment`）。 +1. 按照[此处](https://github.com/MabezDev/wokwi-server/)的说明，安装 `wokwi-server`。 +2. 在 Eclipse CDT 的构建环境变量中配置 `WOKWI_SERVER_PATH` 为 `wokwi-server` 可执行文件的路径 (`Preferences` > `C/C++` > `Build` > `Environment`)。 3. 创建一个新的`运行启动配置`，选择 `Wokwi 模拟器`。 -4. 选择一个项目，并添加 Wokwi 项目的`项目 ID`。该项目 ID 可在 URL 中找到。例如，ESP32 Rust Blinky 项目的 URL 为 [https://wokwi.com/projects/345932416223806035](https://wokwi.com/projects/345932416223806035)，项目 ID 则为 URL 中的 345932416223806035。 -5. 点击 `完成` 以保存更改。 -6. 前往 IDE 工具栏，点击 `启动` 按钮来启动 Wokwi 模拟器。 +4. 选择一个项目，并添加 Wokwi 项目的`项目 ID`。该项目 ID 可在 URL 中找到。例如，ESP32 Rust Blinky 项目的 URL 为 [https://wokwi.com/projects/345932416223806035](https://wokwi.com/projects/345932416223806035)，项目 ID 是 URL 中的 345932416223806035。 +5. 点击`完成`，保存更改。 +6. 前往 IDE 工具栏，点击`启动`按钮以启动 Wokwi 模拟器。 7. Wokwi 模拟器将在外部浏览器中启动。串行监视器的输出也会显示在 Eclipse CDT 构建控制台中。 -8. 要终止 Wokwi 模拟器，前往工具栏并点击 `停止` 按钮。 +8. 要终止 Wokwi 模拟器，前往工具栏并点击`停止`按钮。 # ESP-IDF Eclipse 插件兼容情况 - IEP | Eclipse | Java | 工具安装器 | 描述 | +| IEP | Eclipse | Java | 安装程序 | 描述 | | ------ | ------ | ------ |------ | ------ | -| IEP 2.10.0 | Eclipse 2022-09, 2022-12, 2023-03 |Java 17 及以上 | [espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/untagged-52aeb689780472c126c1/espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe)| -| IEP 2.9.1 | Eclipse 2022-09 和 Eclipse 2022-12 |Java 17 及以上 | [espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.9.0-esp-idf-5.0.1/espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe) | Windows 用户建议使用离线 Windows 安装器并升级至最新的 IEP v2.9.1 插件| -| IEP 2.9.0 | Eclipse 2022-09 |Java 17 及以上 | [espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.9.0-esp-idf-5.0.1/espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe) | Windows 用户建议使用离线 Windows 安装器| -| IEP 2.2.0 | Eclipse 2021-06, 2021-03, 2020-12 |Java 11 及以上 | ESP-IDF 工具 Windows 安装器 2.10| | -| IEP 2.3.0 | Eclipse 2021-09, 2021-06 |Java 11 及以上 | ESP-IDF 工具 Windows 安装器 2.11| ESP-IDF 工具 Windows 安装器 2.11 默认搭配 IEP 2.2.0，需手动升级为 2.3.0| +| IEP 2.12.1 | Eclipse 2023-03 至 Eclipse 2023-12 | Java 17 及以上 | [espressif-ide-setup-2.12.1-with-esp-idf-5.2.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.12.1-esp-idf-5.2/espressif-ide-setup-2.12.1-with-esp-idf-5.2.exe) | +| IEP 2.12.0 | Eclipse 2023-03、2023-06、2023-09 | Java 17 及以上 | [espressif-ide-setup-2.12.0-with-esp-idf-5.1.2](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.12.0-esp-idf-5.1.2/espressif-ide-setup-2.12.0-with-esp-idf-5.1.2.exe) | +| IEP 2.11.0 | Eclipse 2023-03、2023-06、2023-09 | Java 17 及以上 | [espressif-ide-setup-2.11.0-with-esp-idf-5.1.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.11.0-esp-idf-5.1.1/espressif-ide-setup-2.11.0-with-esp-idf-5.1.1.exe) | +| IEP 2.10.0 | Eclipse 2022-09、2022-12、2023-03 | Java 17 及以上 | [espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/untagged-52aeb689780472c126c1/espressif-ide-setup-2.10.0-with-esp-idf-5.0.1.exe) | +| IEP 2.9.1 | Eclipse 2022-09 和 Eclipse 2022-12 | Java 17 及以上 | [espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.9.0-esp-idf-5.0.1/espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe) | 对于 Windows 用户，推荐使用 Windows 离线安装程序并升级至最新的 IEP v2.9.1 插件 | +| IEP 2.9.0 | Eclipse 2022-09 | Java 17 及以上 | [espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe](https://github.com/espressif/idf-installer/releases/download/espressif-ide-2.9.0-esp-idf-5.0.1/espressif-ide-setup-2.9.0-with-esp-idf-5.0.1.exe) | 对于 Windows 用户，推荐使用 Windows 离线安装程序 | + # 如何提交 bug？ -请点击[此链接](https://github.com/espressif/idf-eclipse-plugin/issues)提交问题，并提供完整的环境详细信息和日志。 \ No newline at end of file +请点击[此链接](https://github.com/espressif/idf-eclipse-plugin/issues)提交问题，并提供完整的环境详细信息和日志。