diff --git a/.github/workflows/docs_build.yml b/.github/workflows/docs_build.yml index db21711e6..8e895e186 100644 --- a/.github/workflows/docs_build.yml +++ b/.github/workflows/docs_build.yml @@ -38,7 +38,7 @@ jobs: # Update the path to include them and run. cd ./docs PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary - PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en + PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs - name: Archive Docs uses: actions/upload-artifact@v4 with: diff --git a/.github/workflows/docs_production.yml b/.github/workflows/docs_production.yml index e838dea50..7960ef853 100644 --- a/.github/workflows/docs_production.yml +++ b/.github/workflows/docs_production.yml @@ -46,7 +46,7 @@ jobs: echo "PIP install requirements..." pip3 install --user -r ./docs/requirements.txt echo "Building the Docs..." - cd ./docs && build-docs -l en + cd ./docs && build-docs echo "Deploy the Docs..." export DOCS_BUILD_DIR=$GITHUB_WORKSPACE/docs/ cd $GITHUB_WORKSPACE/docs diff --git a/docs/en/installation.rst b/docs/en/installation.rst index 89eafcd3e..9ba292866 100644 --- a/docs/en/installation.rst +++ b/docs/en/installation.rst @@ -1,106 +1,107 @@ Installation -=============================== +============ -Configuring and installing the Espressif-IDE involves two main steps: +:link_to_translation:`zh_CN:[中文]` -1. :ref:`Downloading and Installing the Espressif-IDE ` -2. :ref:`Installing the ESP-IDF and related tools within the Espressif-IDE ` -3. :ref:`Migrating old workspace to new ` +Configuring and installing the Espressif-IDE involves three main steps: + +1. :ref:`Download and Installing the Espressif-IDE ` +2. :ref:`Install the ESP-IDF and related tools within the Espressif-IDE ` +3. :ref:`Migrate old workspace to new ` .. note:: - For Eclipse CDT users who prefer installing the ESP-IDF Eclipse Plugin via the `Update site `_, please refer to the :ref:`Update Site Installation Guide `. -Espressif-IDE Installation ----------------------------- + For Eclipse CDT users who prefer installing the ESP-IDF Eclipse Plugin via the `update site `_, please refer to the :ref:`Update Site Installation Guide `. + .. _esp-idf-installation: -To begin, navigate to the section corresponding to your operating system below and follow the provided instructions to install the Espressif-IDE. +Espressif-IDE Installation +-------------------------- -Please note that the Espressif-IDE requires that -you install ESP-IDF via Espressif Installation Manager (EIM) to manage the ESP-IDF versions and tools. -For detailed documentation on using the Espressif Installation Manager (EIM), -please refer to the official guide `here `_. +To begin, navigate to the section below corresponding to your operating system, and follow the provided instructions to install the Espressif-IDE. + +Please note that the Espressif-IDE requires that you install ESP-IDF via Espressif Installation Manager (EIM) to manage the ESP-IDF versions and tools. For detailed documentation on using the EIM, please refer to the `official guide `_. Windows ~~~~~~~~ + .. note:: - For Windows users, Espressif-IDE is available with ESP-IDF as an offline installer. - + + For Windows users, Espressif-IDE is available with ESP-IDF as an offline installer. + To download and install it, follow the instructions provided :ref:`here `. 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. macOS/Linux ~~~~~~~~~~~~ + Download the Espressif-IDE for your respective operating system from the :ref:`download section `. After downloading, launch the IDE and proceed to :ref:`install the necessary ESP-IDF and related tools `. Please ensure that Java, Python, and Git are installed as prerequisites and are available in the system path before launching the IDE. -ESP-IDF and Tools Installation (New Workspace) ----------------------------------------------- .. _esp-idf-tools-installation: -The Espressif-IDE provides a Tool Manager view that allows you to activate available ESP-IDF versions and manage related tools. To install the ESP-IDF and its tools, first download the Espressif Installation Manager (EIM) from the following `link `_. +ESP-IDF and Tools Installation (New Workspace) +---------------------------------------------- +The Espressif-IDE provides a tool manager view that allows you to activate available ESP-IDF versions and manage related tools. To install the ESP-IDF and its tools, first download the EIM from the following `link `__. -After downloading and launching EIM, follow the on-screen instructions to install the required ESP-IDF version and associated tools. Once the installation is complete, you can use the ESP-IDF Manager within the IDE to activate the installed ESP-IDF version in the workspace. -The Espressif-IDE allows you to download and launch the EIM directly from the IDE, making it easier to manage your ESP-IDF versions and tools. If you are coming trying to open the workspace from and older version of Espressif-IDE you will be prompted to convert the older configuration to use with EIM. +After downloading and launching EIM, follow the on-screen instructions to install the required ESP-IDF version and associated tools. Once the installation is complete, you can use the ESP-IDF Manager within the IDE to activate the installed ESP-IDF version in the workspace. The Espressif-IDE allows you to download and launch the EIM directly from the IDE, making it easier to manage your ESP-IDF versions and tools. When you open a workspace created with an old version of Espressif-IDE, the IDE will prompt you to convert its configuration to be compatible with EIM. Follow these steps inside the Espressif-IDE to install the ESP-IDF and related tools: -1. Go to ``Espressif > ESP-IDF Manager``. The following editor will open: +1. Go to ``Espressif`` > ``ESP-IDF Manager``. The following editor will open: - .. image:: ../../media/ToolsManager/ESP-IDF_Manager_Editor_Screen.png + .. image:: ../../media/ToolsManager/ESP-IDF_Manager_Editor_Screen.png -2. Click on the ``Launch EIM`` or ``Download & Launch EIM`` button if you have not already downloaded and installed EIM. +2. Click the ``Launch EIM`` or ``Download & Launch EIM`` button if you have not downloaded and installed EIM. - You will see the progress of download and installation in the console. Once the EIM is launched, you can use it to install the ESP-IDF and related tools. + You will see the progress of download and installation in the console. Once the EIM is launched, you can use it to install the ESP-IDF and related tools. -3. Once you close the EIM your ESP-IDF Manager editor will be updated with the latest information about the ESP-IDF versions and tools available. +3. Once you close the EIM, your ESP-IDF Manager editor will be updated with the latest information about the ESP-IDF versions and tools available. -.. note:: - Please note that the EIM will be the only tool going forward to manage the ESP-IDF versions and tools. The previous versions of the Espressif-IDE used to manage tools internally but now the only point of entry into the ESP-IDF will be through the EIM. + .. image:: ../../media/ToolsManager/Tool_installed_and_activated.png -After the EIM is closed the ESP-IDF Manager editor will be updated with the latest information about the ESP-IDF versions and tools available.: +.. note:: -.. image:: ../../media/ToolsManager/Tool_installed_and_activated.png + Please note that the EIM will be the only tool going forward to manage the ESP-IDF versions and tools. Previous versions of the Espressif-IDE managed tools internally, but now all access to ESP-IDF is handled through the EIM. You can add as many versions of ESP-IDF as you want via EIM, but only one version can be set as active, and that version will be used to compile and index projects in your workspace. This feature helps you switch between versions in the workspace easily. -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 the radio button next to it in the ``Active`` column. The refresh button in the last column for the active ESP-IDF version can be used to reload any changes in the ESP-IDF directory you made. .. note:: - Any manual changes made to the ESP-IDF directory will not be reflected in the IDE until you refresh the active ESP-IDF version using the refresh button but if you made any changes to the installation of ESP-IDF using the EIM, those changes will be detected and a popup message will be shown to you to update the ESP-IDF version in the IDE. -.. image:: ../../media/ToolsManager/ESP-IDF_Manager_Changed_Installation_Message.png + Any manual changes made to the ESP-IDF directory will not be reflected in the IDE until you refresh the active ESP-IDF version using the refresh button. However, if you made any changes to the installation of ESP-IDF using the EIM, those changes will be detected and a popup message will be shown to you to update the ESP-IDF version in the IDE. +.. image:: ../../media/ToolsManager/ESP-IDF_Manager_Changed_Installation_Message.png -Migrating Old Workspace to New -------------------------------- .. _esp-idf-tools-migration: -If you are migrating from an older version of the Espressif-IDE, you will need to convert your existing workspace to be -compatible with the new ESP-IDF Manager. -You will need to download and install the Espressif Installation Manager (EIM) from the following `link `_. -After installation of the EIM please follow the steps below: - -1. Copy the downloaded EIM executable to `.espressif/eim_gui/` in user home directory for Windows and Linux. - For example, on Windows, it would be `C:\Users\\.espressif\eim_gui\eim.exe`. - On Linux , it would be `~/.espressif/eim_gui/eim`. - For macOS, copy the downloaded `eim.app` to your `Applications`, for example, `/Applications/eim.app`. - -2. Open the Espressif-IDE if already running restart it. -3. After the IDE detects the EIM executable and a valid older workspace, it will prompt you to convert the old workspace to the new format.: - -.. image:: ../../media/ToolsManager/ESP-IDF_Manager_Conversion.png - -4. Click on the ``Yes`` button to convert the old configuration. -5. Now in Espressif-IDE, go to ``Espressif > ESP-IDF Manager``. - The ESP-IDF Manager editor will open, and you can proceed to select activate against the version you want. - +Old-to-New Workspace Migration +------------------------------ + +If you are migrating from an old version of the Espressif-IDE, you will need to convert your existing workspace to be compatible with the new ESP-IDF Manager. You will need to download and install the EIM from the following `link `__. After installation of the EIM, please follow the steps below: + +1. Place the downloaded EIM executable in the appropriate location according to your operating system: + + - **Windows**: `C:\Users\\.espressif\eim_gui\eim.exe` + - **Linux**: `~/.espressif/eim_gui/eim` + - **macOS**: Copy the ``eim.app`` bundle to your ``Applications`` folder, for example `/Applications/eim.app`. + +2. Open the Espressif-IDE. If it is already running, restart the IDE. +3. After the IDE detects the EIM executable and a valid old workspace, it will prompt you to convert the old workspace to the new format. + + .. image:: ../../media/ToolsManager/ESP-IDF_Manager_Conversion.png + +4. Click the ``Yes`` button to convert the old configuration. +5. Now in Espressif-IDE, go to ``Espressif`` > ``ESP-IDF Manager``. The ESP-IDF Manager editor will open, and you can proceed to select and activate the ESP-IDF version you want. + References ---------- + .. toctree:: :maxdepth: 1 - Update Site Installation Guide - Windows Offline Installer - Configure CDT Build Environment Variables \ No newline at end of file + Update Site Installation Guide + Windows Offline Installer + Configure CDT Build Environment Variables diff --git a/docs/en/prerequisites.rst b/docs/en/prerequisites.rst index 7fbfd7e54..e14204275 100644 --- a/docs/en/prerequisites.rst +++ b/docs/en/prerequisites.rst @@ -1,26 +1,31 @@ Prerequisites -=============================== +============= + +:link_to_translation:`zh_CN:[中文]` + This document outlines the necessary requirements for installing and running Espressif-IDE to build applications with ESP-IDF. -Hardware Prerequisites ------------------------ +Hardware +-------- + - A computer running Windows, Linux, or macOS - An ESP32 development board with a USB to serial interface and/or debug port - A USB cable (data + power) compatible with your development board .. Note:: - Currently, some of the development boards are using USB Type C connectors. Be sure you have the correct cable to connect your board! -Software Prerequisites ------------------------ -The minimum requirements for running the Espressif-IDE are listed below. + Currently, some development boards are using USB Type-C connectors. Be sure you have the correct cable to connect your board. -- `Java 21 `_ and above. -- `Python 3.12 `_ and above. -- `Git `_. -- `ESP-IDF Prerequisites `_ based on your Operating System. +Software +-------- -.. note:: - Ensure that Java, Python, and Git are correctly set up and available in the system's PATH environment variable. +The minimum requirements for running the Espressif-IDE are listed below: + +- `Java 21 `_ and above +- `Python 3.12 `_ and above +- `Git `_ +- `ESP-IDF Prerequisites `_ based on your operating system +.. note:: + Ensure that Java, Python, and Git are correctly set up and available in the system's PATH environment variable. diff --git a/docs/en/troubleshooting.rst b/docs/en/troubleshooting.rst index 1bd9027c9..fa297e283 100644 --- a/docs/en/troubleshooting.rst +++ b/docs/en/troubleshooting.rst @@ -3,6 +3,8 @@ Troubleshooting =============== +:link_to_translation:`zh_CN:[中文]` + - :ref:`suggestions_for_build_errors` - :ref:`error_log` - :ref:`console_view_log` @@ -11,54 +13,58 @@ Troubleshooting .. _suggestions_for_build_errors: -Suggestions for Build Errors using Hints Viewer ------------------------------------------------- -If you encounter a problem during a build, there may be a hint for this error in the ESP-IDF hint database, located at ``tools/idf_py_actions/hints.yml`` in ESP-IDF. The ESP-IDF Eclipse plugin provides a hint viewer where you can type an error message to find a hint for it. +Suggestions for Build Errors Using Hints View +--------------------------------------------- + +If you encounter a problem during a build, there may be a hint for this error in the ESP-IDF hint database, located at ``tools/idf_py_actions/hints.yml`` in ESP-IDF. The ESP-IDF Eclipse plugin provides a Hints View where you can type an error message to find a hint for it. **Prerequisites:** The ``hints.yml`` file is available from ESP-IDF v5.0 and higher. If you are using an older version, you can manually download the ``hints.yml`` file from `here `_ and save it to ``esp-idf/tools/idf_py_actions/``. To download the file, right-click the ``Raw`` button and select ``Save as...``. -To open the hints viewer: -1. Navigate to ``Windows`` -> ``Show View`` -> ``Other...`` -> ``Espressif`` -> ``Hints``. +To open the Hints View, go to ``Windows`` > ``Show View`` > ``Other...`` > ``Espressif`` > ``Hints``. .. image:: https://user-images.githubusercontent.com/24419842/189666994-78cc8b24-b934-426f-9df5-79af28c50c55.png - :alt: Hints Viewer + :alt: Hints View Now you can type or paste an error from the build log, such as: + ``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 - :alt: Example Error in Hints Viewer + :alt: Example Error in Hints View -Double-clicking on the row will display the hint message if it doesn't fully fit on your screen. +Double-clicking the row will display the hint message if it doesn't fully fit on your screen. .. image:: https://user-images.githubusercontent.com/24419842/189673174-8ce40cda-6933-4dc4-a555-5d2ca617256e.png - :alt: Hint Message + :alt: Hint Message .. _error_log: Error Log --------- -The Error Log view captures warnings and errors logged by plug-ins. The log file is stored in the ``.log`` file within the ``.metadata`` subdirectory of the workspace. -To open the Error Log view: -- Go to ``Window`` > ``Show View`` > ``Error Log``. +The Error Log View captures warnings and errors logged by plug-ins. The log file is stored in the ``.log`` file within the ``.metadata`` subdirectory of the workspace. + +To open the Error Log View, go to ``Window`` > ``Show View`` > ``Error Log``. To export the current log view content: -1. Press the ``Export Log`` toolbar button or select ``Export Log...`` from the context menu. -2. Enter a file name. -It's recommended to include an error log when reporting an issue. +1. Press the ``Export Log`` toolbar button or select ``Export Log...`` from the context menu. + + .. image:: ../../media/export_log.png + :alt: Export Log -.. image:: ../../media/export_log.png - :alt: Export Log +2. Enter a file name. + +It's recommended to include an error log when reporting an issue. .. _console_view_log: Console View Log ---------------- -The Console View shows warnings and errors related to the current running process or build. To access the Console View: -- From the menu bar, select ``Window`` > ``Show View`` > ``Console``. +The Console View shows warnings and errors related to the current running process or build. + +To access the Console View, go to ``Window`` > ``Show View`` > ``Console``. .. image:: ../../media/CDT_Build_Console.png :alt: Console View @@ -67,18 +73,19 @@ The Console View shows warnings and errors related to the current running proces CDT Global Build Log -------------------- -To enable global build logging: -- Go to ``Preferences`` > ``C/C++`` > ``Build`` > ``Logging``. + +To enable global build logging, go to ``Preferences`` > ``C/C++`` > ``Build`` > ``Logging``. .. _espressif_idf_tools_console: Espressif IDF Tools Console ---------------------------- -The Espressif IDF Tools Console is part of the Console view and opens during the installation of IDF tools from Eclipse. + +The Espressif IDF Tools Console is part of the Console View and opens during the installation of IDF tools from Eclipse. If you encounter any issues during installation of IDF tools via ``Espressif`` > ``ESP-IDF Tools Manager`` > ``Install tools``, check the Espressif IDF Tools Console for errors. -If this console is not active, switch to it by clicking on the ``Display Selected Console`` icon in the console view. +If this console is not active, switch to it by clicking the ``Display Selected Console`` icon in the Console View. .. image:: ../../media/IDF_tools_console.png :alt: Espressif IDF Tools Console diff --git a/docs/zh_CN/additionalfeatures.rst b/docs/zh_CN/additionalfeatures.rst new file mode 100644 index 000000000..2e2908ad5 --- /dev/null +++ b/docs/zh_CN/additionalfeatures.rst @@ -0,0 +1 @@ +.. include:: ../en/additionalfeatures.rst \ No newline at end of file diff --git a/docs/zh_CN/additionalfeatures/appleveltracing.rst b/docs/zh_CN/additionalfeatures/appleveltracing.rst new file mode 100644 index 000000000..29df0adcd --- /dev/null +++ b/docs/zh_CN/additionalfeatures/appleveltracing.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/appleveltracing.rst diff --git a/docs/zh_CN/additionalfeatures/application-size-analysis.rst b/docs/zh_CN/additionalfeatures/application-size-analysis.rst new file mode 100644 index 000000000..d476fbc5d --- /dev/null +++ b/docs/zh_CN/additionalfeatures/application-size-analysis.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/application-size-analysis.rst diff --git a/docs/zh_CN/additionalfeatures/clangd_cdt_support.rst b/docs/zh_CN/additionalfeatures/clangd_cdt_support.rst new file mode 100644 index 000000000..318ab6cc3 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/clangd_cdt_support.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/clangd_cdt_support.rst diff --git a/docs/zh_CN/additionalfeatures/clangtoolchain.rst b/docs/zh_CN/additionalfeatures/clangtoolchain.rst new file mode 100644 index 000000000..8ea8eb748 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/clangtoolchain.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/clangtoolchain.rst diff --git a/docs/zh_CN/additionalfeatures/cmakeeditor.rst b/docs/zh_CN/additionalfeatures/cmakeeditor.rst new file mode 100644 index 000000000..2e22230b2 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/cmakeeditor.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/cmakeeditor.rst diff --git a/docs/zh_CN/additionalfeatures/configureenvvariables.rst b/docs/zh_CN/additionalfeatures/configureenvvariables.rst new file mode 100644 index 000000000..71d9a9e1b --- /dev/null +++ b/docs/zh_CN/additionalfeatures/configureenvvariables.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/configureenvvariables.rst diff --git a/docs/zh_CN/additionalfeatures/configuretoolchain.rst b/docs/zh_CN/additionalfeatures/configuretoolchain.rst new file mode 100644 index 000000000..cc9113037 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/configuretoolchain.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/configuretoolchain.rst diff --git a/docs/zh_CN/additionalfeatures/coredumpdebugging.rst b/docs/zh_CN/additionalfeatures/coredumpdebugging.rst new file mode 100644 index 000000000..3d2de7495 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/coredumpdebugging.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/coredumpdebugging.rst diff --git a/docs/zh_CN/additionalfeatures/dfu.rst b/docs/zh_CN/additionalfeatures/dfu.rst new file mode 100644 index 000000000..1d85ea065 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/dfu.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/dfu.rst diff --git a/docs/zh_CN/additionalfeatures/esp-terminal.rst b/docs/zh_CN/additionalfeatures/esp-terminal.rst new file mode 100644 index 000000000..be413fb02 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/esp-terminal.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/esp-terminal.rst diff --git a/docs/zh_CN/additionalfeatures/gdbstubdebugging.rst b/docs/zh_CN/additionalfeatures/gdbstubdebugging.rst new file mode 100644 index 000000000..86a505154 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/gdbstubdebugging.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/gdbstubdebugging.rst diff --git a/docs/zh_CN/additionalfeatures/heaptracing.rst b/docs/zh_CN/additionalfeatures/heaptracing.rst new file mode 100644 index 000000000..915b31641 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/heaptracing.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/heaptracing.rst diff --git a/docs/zh_CN/additionalfeatures/install-esp-components.rst b/docs/zh_CN/additionalfeatures/install-esp-components.rst new file mode 100644 index 000000000..2573f3201 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/install-esp-components.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/install-esp-components.rst diff --git a/docs/zh_CN/additionalfeatures/lspeditor.rst b/docs/zh_CN/additionalfeatures/lspeditor.rst new file mode 100644 index 000000000..0a340c9f7 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/lspeditor.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/lspeditor.rst diff --git a/docs/zh_CN/additionalfeatures/nvspartitioneditor.rst b/docs/zh_CN/additionalfeatures/nvspartitioneditor.rst new file mode 100644 index 000000000..0134ba3fa --- /dev/null +++ b/docs/zh_CN/additionalfeatures/nvspartitioneditor.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/nvspartitioneditor.rst diff --git a/docs/zh_CN/additionalfeatures/partitiontableeditor.rst b/docs/zh_CN/additionalfeatures/partitiontableeditor.rst new file mode 100644 index 000000000..766dc5182 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/partitiontableeditor.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/partitiontableeditor.rst diff --git a/docs/zh_CN/additionalfeatures/switchlanguage.rst b/docs/zh_CN/additionalfeatures/switchlanguage.rst new file mode 100644 index 000000000..6d08ef83c --- /dev/null +++ b/docs/zh_CN/additionalfeatures/switchlanguage.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/switchlanguage.rst diff --git a/docs/zh_CN/additionalfeatures/wokwisimulator.rst b/docs/zh_CN/additionalfeatures/wokwisimulator.rst new file mode 100644 index 000000000..4216a061c --- /dev/null +++ b/docs/zh_CN/additionalfeatures/wokwisimulator.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/wokwisimulator.rst diff --git a/docs/zh_CN/additionalfeatures/writebinarytoflash.rst b/docs/zh_CN/additionalfeatures/writebinarytoflash.rst new file mode 100644 index 000000000..3c2c08824 --- /dev/null +++ b/docs/zh_CN/additionalfeatures/writebinarytoflash.rst @@ -0,0 +1 @@ +.. include:: ../../en/additionalfeatures/writebinarytoflash.rst diff --git a/docs/zh_CN/buildproject.rst b/docs/zh_CN/buildproject.rst new file mode 100644 index 000000000..ef1051cd6 --- /dev/null +++ b/docs/zh_CN/buildproject.rst @@ -0,0 +1 @@ +.. include:: ../en/buildproject.rst diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py new file mode 100644 index 000000000..933b8ef0e --- /dev/null +++ b/docs/zh_CN/conf.py @@ -0,0 +1,25 @@ +# -*- coding: utf-8 -*- +# +# English Language RTD & Sphinx config file +# +# Uses ../conf_common.py for most non-language-specific settings. + +# Importing conf_common adds all the non-language-specific +# parts to this conf module + +try: + from conf_common import * # noqa: F403,F401 +except ImportError: + import os + import sys + sys.path.insert(0, os.path.abspath('../')) + from conf_common import * # noqa: F403,F401 + +# General information about the project. +project = u'Espressif-IDE' +copyright = u'2016 - 2024, 乐鑫信息科技（上海）股份有限公司' +pdf_title = u'Espressif-IDE 指南' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'zh_CN' diff --git a/docs/zh_CN/configureproject.rst b/docs/zh_CN/configureproject.rst new file mode 100644 index 000000000..fc69f45cb --- /dev/null +++ b/docs/zh_CN/configureproject.rst @@ -0,0 +1 @@ +.. include:: ../en/configureproject.rst diff --git a/docs/zh_CN/connectdevice.rst b/docs/zh_CN/connectdevice.rst new file mode 100644 index 000000000..35eddd77b --- /dev/null +++ b/docs/zh_CN/connectdevice.rst @@ -0,0 +1 @@ +.. include:: ../en/connectdevice.rst diff --git a/docs/zh_CN/debugproject.rst b/docs/zh_CN/debugproject.rst new file mode 100644 index 000000000..144237842 --- /dev/null +++ b/docs/zh_CN/debugproject.rst @@ -0,0 +1 @@ +.. include:: ../en/debugproject.rst diff --git a/docs/zh_CN/downloads.rst b/docs/zh_CN/downloads.rst new file mode 100644 index 000000000..b42d3a078 --- /dev/null +++ b/docs/zh_CN/downloads.rst @@ -0,0 +1 @@ +.. include:: ../en/downloads.rst diff --git a/docs/zh_CN/faqs.rst b/docs/zh_CN/faqs.rst new file mode 100644 index 000000000..4cb537d7d --- /dev/null +++ b/docs/zh_CN/faqs.rst @@ -0,0 +1 @@ +.. include:: ../en/faqs.rst diff --git a/docs/zh_CN/flashdevice.rst b/docs/zh_CN/flashdevice.rst new file mode 100644 index 000000000..7bb5c3de5 --- /dev/null +++ b/docs/zh_CN/flashdevice.rst @@ -0,0 +1 @@ +.. include:: ../en/flashdevice.rst diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst new file mode 100644 index 000000000..58446d485 --- /dev/null +++ b/docs/zh_CN/index.rst @@ -0,0 +1 @@ +.. include:: ../en/index.rst \ No newline at end of file diff --git a/docs/zh_CN/installation.rst b/docs/zh_CN/installation.rst new file mode 100644 index 000000000..cfd33b1b0 --- /dev/null +++ b/docs/zh_CN/installation.rst @@ -0,0 +1,107 @@ +安装 +==== + +:link_to_translation:`en:[English]` + +配置和安装 Espressif-IDE 包括三个主要步骤： + +1. :ref:`下载并安装 Espressif-IDE ` +2. :ref:`在 Espressif-IDE 中安装 ESP-IDF 及相关工具 ` +3. :ref:`将旧工作区迁移到新工作区 ` + +.. note:: + + 对于喜欢通过 `更新站点 `_ 安装 ESP-IDF Eclipse 插件的 Eclipse CDT 用户，请参考 :ref:`更新站点安装指南 `。 + +.. _esp-idf-installation: + +安装 Espressif-IDE +------------------ + +首先，请根据你的操作系统查看下方对应的章节，并参照说明安装 Espressif-IDE。 + +请注意，Espressif-IDE 要求通过乐鑫安装管理器 (Espressif Installation Manager, EIM) 安装 ESP-IDF，从而管理 ESP-IDF 版本和所需工具。有关使用 EIM 的详细文档，请参考 `官方指南 `_。 + +Windows +~~~~~~~ + +.. note:: + + 对于 Windows 用户，Espressif-IDE 提供带有 ESP-IDF 的离线安装包。 + +请参阅 :ref:`此文 ` 下载并安装 Espressif-IDE。该指南将引导你完成 Java、Git、CMake、ESP-IDF、IDF 工具、设备驱动以及 Espressif-IDE 的安装流程，帮助你快速入门。 + +macOS/Linux +~~~~~~~~~~~ + +找到 :ref:`下载章节 ` 中适用于你操作系统的 Espressif-IDE。下载完成后，启动 IDE 并继续 :ref:`安装所需的 ESP-IDF 及相关工具 `。请确保在启动 IDE 之前已安装 Java、Python 和 Git，并且其在系统路径中可用。 + +.. _esp-idf-tools-installation: + +安装 ESP-IDF 及相关工具（新工作区） +----------------------------------- + +Espressif-IDE 提供了工具管理视图，可用来激活可用的 ESP-IDF 版本并管理相关工具。若要安装 ESP-IDF 及其工具，首先点击 `此链接 `__ 下载 EIM。 + +下载并启动 EIM 后，按照屏幕提示安装所需的 ESP-IDF 版本及相关工具。安装完成后，你可以在 IDE 内使用 ESP-IDF 管理器激活工作区中的 ESP-IDF 版本。你可以直接从 IDE 下载并启动 EIM，便于管理 ESP-IDF 版本和工具。如果你在旧版本的 Espressif-IDE 中打开工作区，系统会提示你将旧版本的配置转换为与 EIM 兼容的格式。 + +参照下列步骤，在 Espressif-IDE 中安装 ESP-IDF 及相关工具： + +1. 前往 ``Espressif`` > ``ESP-IDF Manager``，将打开如下编辑器： + + .. image:: ../../media/ToolsManager/ESP-IDF_Manager_Editor_Screen.png + +2. 如果尚未下载和安装 EIM，请点击 ``Launch EIM`` 或 ``Download & Launch EIM`` 按钮。 + + 你可以在控制台查看下载和安装进度。EIM 启动后，可以用来安装 ESP-IDF 及相关工具。 + +3. 关闭 EIM 后，ESP-IDF 管理器编辑器将更新可用的 ESP-IDF 版本及工具的最新信息。 + + .. image:: ../../media/ToolsManager/Tool_installed_and_activated.png + +.. note:: + + 注意，早期版本的 Espressif-IDE 在内部管理工具，但现在对 ESP-IDF 的所有访问都由 EIM 统一处理。 + +你可以通过 EIM 添加任意数量的 ESP-IDF 版本，但只能激活一个版本，并将其用于编译和索引工作区中的项目。使用此功能，你可以在工作区中轻松切换 IDF 版本。 + +只需点击 ``Active`` 列旁的单选按钮即可激活特定版本。 + +最后一列的刷新按钮可用于重新加载 ESP-IDF 目录中的更改。 + +.. note:: + + 对 ESP-IDF 目录所做的任何手动更改，只有点击刷新按钮后，IDE 才会更新激活版本并显示最新内容。但如果是通过 EIM 修改了 ESP-IDF 的安装，IDE 会自动检测到，并弹出提示要求更新 ESP-IDF 版本。 + +.. image:: ../../media/ToolsManager/ESP-IDF_Manager_Changed_Installation_Message.png + +.. _esp-idf-tools-migration: + +迁移旧工作区到新工作区 +---------------------- + +如果你从旧版本的 Espressif-IDE 进行迁移，需要转换现有工作区，使其兼容新的 ESP-IDF 管理器。点击 `此链接 `__，下载并安装 EIM。安装 EIM 后，请按照以下步骤操作： + +1. 将下载的 EIM 可执行文件放置到适合你操作系统的位置： + + - **Windows**: `C:\Users\\.espressif\eim_gui\eim.exe` + - **Linux**: `~/.espressif/eim_gui/eim` + - **macOS**: 将 ``eim.app`` 应用包复制到 ``Applications`` 文件夹，例如 `/Applications/eim.app`. + +2. 打开 Espressif-IDE。如果 IDE 已运行，请重启。 +3. IDE 检测到 EIM 可执行文件和有效的旧工作区后，会提示你将旧工作区转换为新格式： + + .. image:: ../../media/ToolsManager/ESP-IDF_Manager_Conversion.png + +4. 点击 ``Yes`` 按钮转换旧配置。 +5. 在 Espressif-IDE 中，前往 ``Espressif`` > ``ESP-IDF Manager``。在打开的 ESP-IDF 管理器编辑器中选择并激活所需版本。 + +参考文档 +-------- + +.. toctree:: + :maxdepth: 1 + + 更新站点安装指南 + Windows 离线安装程序 + 配置 CDT 构建环境变量 diff --git a/docs/zh_CN/marketplaceupdate.rst b/docs/zh_CN/marketplaceupdate.rst new file mode 100644 index 000000000..8fcc98f1c --- /dev/null +++ b/docs/zh_CN/marketplaceupdate.rst @@ -0,0 +1 @@ +.. include:: ../en/marketplaceupdate.rst diff --git a/docs/zh_CN/monitoroutput.rst b/docs/zh_CN/monitoroutput.rst new file mode 100644 index 000000000..f8f89bd09 --- /dev/null +++ b/docs/zh_CN/monitoroutput.rst @@ -0,0 +1 @@ +.. include:: ../en/monitoroutput.rst diff --git a/docs/zh_CN/openocddebugging.rst b/docs/zh_CN/openocddebugging.rst new file mode 100644 index 000000000..df59e4d64 --- /dev/null +++ b/docs/zh_CN/openocddebugging.rst @@ -0,0 +1 @@ +.. include:: ../en/openocddebugging.rst diff --git a/docs/zh_CN/prerequisites.rst b/docs/zh_CN/prerequisites.rst new file mode 100644 index 000000000..3f9d2fd68 --- /dev/null +++ b/docs/zh_CN/prerequisites.rst @@ -0,0 +1,31 @@ +准备工作 +======== + +:link_to_translation:`en:[English]` + +本文档概述了安装和运行 Espressif-IDE 所需的基本要求，从而实现使用 ESP-IDF 构建应用程序。 + +硬件 +---- + +- 一台使用 Windows、Linux 或 macOS 操作系统的计算机 +- 一块带有 USB 转串口接口/调试端口，或两者兼有的 ESP32 开发板 +- 一根与开发板兼容的 USB 线缆（数据与供电） + +.. Note:: + + 目前，部分开发板使用 USB Type-C 连接器。请确保准备的 USB 线可正确连接开发板。 + +软件 +---- + +运行 Espressif-IDE 的最低要求如下： + +- `Java 21 `_ 及以上 +- `Python 3.12 `_ 及以上 +- `Git `_ +- `ESP-IDF 依赖项 `_，取决于所使用的操作系统 + +.. note:: + + 请确保已正确安装并配置 Java、Python 和 Git，且已在系统的 PATH 环境变量中可用。 diff --git a/docs/zh_CN/startproject.rst b/docs/zh_CN/startproject.rst new file mode 100644 index 000000000..bb7477bb5 --- /dev/null +++ b/docs/zh_CN/startproject.rst @@ -0,0 +1 @@ +.. include:: ../en/startproject.rst diff --git a/docs/zh_CN/troubleshooting.rst b/docs/zh_CN/troubleshooting.rst new file mode 100644 index 000000000..5eee60b95 --- /dev/null +++ b/docs/zh_CN/troubleshooting.rst @@ -0,0 +1,91 @@ +.. _troubleshooting: + +故障排查 +========= + +:link_to_translation:`en:[English]` + +- :ref:`suggestions_for_build_errors` +- :ref:`error_log` +- :ref:`console_view_log` +- :ref:`cdt_global_build_log` +- :ref:`espressif_idf_tools_console` + +.. _suggestions_for_build_errors: + +使用提示查看器解决构建错误 +-------------------------- + +如果在构建过程中遇到问题，ESP-IDF 的提示数据库（位于 ESP-IDF 的 ``tools/idf_py_actions/hints.yml``）中可能存在该错误的提示。ESP-IDF Eclipse 插件提供了提示查看器，你可以在其中输入错误信息以查找对应提示。 + +**前提条件：** ESP-IDF v5.0 及以上版本提供 ``hints.yml`` 文件。如果你使用的是旧版本的 IDF，可以点击 `此链接 `_ 手动下载 ``hints.yml`` 文件，并保存到 ``esp-idf/tools/idf_py_actions/``。若需下载文件，请右键点击 ``Raw`` 按钮并选择 ``Save as...``。 + +要打开提示查看器，请依次前往 ``Windows`` > ``Show View`` > ``Other...`` > ``Espressif`` > ``Hints``。 + +.. image:: https://user-images.githubusercontent.com/24419842/189666994-78cc8b24-b934-426f-9df5-79af28c50c55.png + :alt: 提示查看器 + +现在你可以在查看器中输入或粘贴构建日志中的错误，例如： + +``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 + :alt: 提示查看器中的示例错误 + +如果提示信息未在屏幕上完整显示，可双击此行查看完整提示。 + +.. image:: https://user-images.githubusercontent.com/24419842/189673174-8ce40cda-6933-4dc4-a555-5d2ca617256e.png + :alt: 提示信息 + +.. _error_log: + +错误日志 +-------- + +错误日志视图记录插件发出的警告和错误提示。日志文件存储在工作区 ``.metadata`` 子目录下的 ``.log`` 文件中。 + +要打开错误日志视图，请依次前往 ``Window`` > ``Show View`` > ``Error Log``。 + +若想导出当前日志内容： + +1. 点击工具栏的 ``Export Log`` 按钮，或从右键菜单中选择 ``Export Log...``。 + + .. image:: ../../media/export_log.png + :alt: 导出日志 + +2. 输入文件名。 + +建议在报告问题时附上错误日志。 + +.. _console_view_log: + +控制台视图日志 +-------------- + +控制台视图能显示与当前运行进程或构建相关的警告和错误。 + +要访问控制台视图，前往 ``Window`` > ``Show View`` > ``Console``。 + +.. image:: ../../media/CDT_Build_Console.png + :alt: 控制台视图 + +.. _cdt_global_build_log: + +CDT 全局构建日志 +---------------- + +要启用全局构建日志，前往 ``Preferences`` > ``C/C++`` > ``Build`` > ``Logging``。 + +.. _espressif_idf_tools_console: + +乐鑫 IDF 工具控制台 +------------------- + +乐鑫 IDF 工具控制台是控制台视图的一部分，从 Eclipse 安装 IDF 工具时会自动打开。 + +如果在通过 ``Espressif`` > ``ESP-IDF Tools Manager`` > ``Install tools`` 安装 IDF 工具过程中遇到问题，请检查乐鑫 IDF 工具控制台中的错误信息。 + +如果该控制台未激活，可在控制台视图中点击 ``Display Selected Console`` 图标切换到该控制台。 + +.. image:: ../../media/IDF_tools_console.png + :alt: 乐鑫 IDF 工具控制台 diff --git a/docs/zh_CN/windowsofflineinstaller.rst b/docs/zh_CN/windowsofflineinstaller.rst new file mode 100644 index 000000000..85d3edf76 --- /dev/null +++ b/docs/zh_CN/windowsofflineinstaller.rst @@ -0,0 +1 @@ +.. include:: ../en/windowsofflineinstaller.rst