mirror of
https://github.com/espressif/esp-idf.git
synced 2026-04-27 19:13:21 +00:00
docs: updated get started for EIM
This commit is contained in:
Wang Ning
Binary file not shown.
|
After Width: | Height: | Size: 96 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 230 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 430 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 97 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 114 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 232 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 229 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 148 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 227 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 237 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 200 KiB |
Vendored
BIN
Binary file not shown.
|
After Width: | Height: | Size: 208 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 144 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 175 KiB |
@@ -36,8 +36,35 @@ Please verify that the {IDF_TARGET_NAME} pins used for USB communication are not
|
||||
Configure USB Drivers
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
JTAG communication should work on all supported platforms. Windows users might get `LIBUSB_ERROR_NOT_FOUND` errors. Please use version 2.8 (or newer) of the :ref:`get-started-windows-tools-installer` and select the driver "Espressif - WinUSB support for JTAG (ESP32-C3/S3)" in order to resolve this issue. If you do not want to re-run the installer then the same can be achieved with `idf-env <https://github.com/espressif/idf-env>`_ by running the following command from PowerShell::
|
||||
JTAG communication should work on all supported platforms. Windows and Linux require extra steps as described below.
|
||||
|
||||
Invoke-WebRequest 'https://dl.espressif.com/dl/idf-env/idf-env.exe' -OutFile .\idf-env.exe; .\idf-env.exe driver install --espressif
|
||||
Windows
|
||||
"""""""
|
||||
|
||||
Windows users might get `LIBUSB_ERROR_NOT_FOUND` errors. To resolve this, install drivers using one of the following methods:
|
||||
|
||||
- In :doc:`Espressif Installation Manager (EIM) <../../get-started/windows-setup>` graphical user interface (GUI), click ``Open Dashboard`` under ``Manage Installations``, and then click ``Install Drivers``:
|
||||
|
||||
.. figure:: ../../../_static/jtag-debugging-install-usb-drivers-eim.png
|
||||
:align: center
|
||||
:alt: Install Drivers in EIM GUI
|
||||
:figclass: align-center
|
||||
|
||||
Install Drivers in EIM GUI
|
||||
|
||||
- Run the following command from PowerShell to install drivers with EIM command line interface:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim install-drivers
|
||||
|
||||
- Run the following command from PowerShell to install drivers with `idf-env <https://github.com/espressif/idf-env>`_:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Invoke-WebRequest 'https://dl.espressif.com/dl/idf-env/idf-env.exe' -OutFile .\idf-env.exe; .\idf-env.exe driver install --espressif
|
||||
|
||||
Linux
|
||||
"""""
|
||||
|
||||
On Linux adding OpenOCD udev rules is required and is done by placing the following `udev rules file <https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules>`_ in the ``/etc/udev/rules.d`` folder.
|
||||
|
||||
@@ -117,7 +117,7 @@ Setup of OpenOCD
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then OpenOCD is already installed. After :ref:`setting up the environment <get-started-set-up-env>` in your terminal, you should be able to run OpenOCD. Check this by executing the following command:
|
||||
If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then OpenOCD is already installed. After :ref:`setting up the environment for Windows <get-started-set-up-env>`, :ref:`Linux or macOS <get-started-set-up-env-linux-macos>` in your terminal, you should be able to run OpenOCD. Check this by executing the following command:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -136,7 +136,7 @@ The output should be as follows (although the version may be more recent than li
|
||||
|
||||
You may also verify that OpenOCD knows where its configuration scripts are located by printing the value of ``OPENOCD_SCRIPTS`` environment variable, by typing ``echo $OPENOCD_SCRIPTS`` (for Linux and macOS) or ``echo %OPENOCD_SCRIPTS%`` (for Windows). If a valid path is printed, then OpenOCD is set up correctly.
|
||||
|
||||
If any of these steps do not work, please go back to the :ref:`setting up the tools <get-started-set-up-tools>` section (for Linux and macOS) or :ref:`ESP-IDF Tools Installer <get-started-windows-tools-installer>` (for Windows) section of the Getting Started Guide.
|
||||
If any of these steps do not work, please go back to the :ref:`Installation <get-started-how-to-get-esp-idf>` section of the Getting Started Guide.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -178,7 +178,7 @@ Once target is configured and connected to computer, you are ready to launch Ope
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment <get-started-set-up-env>` section of the Getting Started Guide. To run OpenOCD for a specific board, you must pass the board-specific configuration. The default configuration for the built project can be found in the ``debug_arguments_openocd`` field of the ``build/project_description.json`` file. There is an example to run OpenOCD (this command works on Windows, Linux, and macOS):
|
||||
Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment for Windows <get-started-set-up-env>`, :ref:`Linux or macOS <get-started-set-up-env-linux-macos>` section of the Getting Started Guide. To run OpenOCD for a specific board, you must pass the board-specific configuration. The default configuration for the built project can be found in the ``debug_arguments_openocd`` field of the ``build/project_description.json`` file. There is an example to run OpenOCD (this command works on Windows, Linux, and macOS):
|
||||
|
||||
.. include:: {IDF_TARGET_PATH_NAME}.inc
|
||||
:start-after: run-openocd
|
||||
|
||||
@@ -63,7 +63,7 @@ ESP-IDF has some support options for OpenOCD debugging which can be set at compi
|
||||
|
||||
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
|
||||
|
||||
Please see the :ref:`project configuration menu <get-started-configure>` menu for more details on setting compile-time options.
|
||||
Please see the :ref:`project configuration menu for Windows <get-started-configure>`, :ref:`Linux, or macOS <get-started-configure-linux-macos>` menu for more details on setting compile-time options.
|
||||
|
||||
.. _jtag-debugging-tip-freertos-support:
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ The ``idf.py`` command-line tool provides a front-end for easily managing your p
|
||||
- Ninja_, which builds the project.
|
||||
- `esptool`_, which flashes the target.
|
||||
|
||||
The :ref:`Step 5. First Steps on ESP-IDF <get-started-configure>` contains a brief introduction on how to set up ``idf.py`` to configure, build, and flash projects.
|
||||
:ref:`Configure Your Project for Windows, <get-started-configure>` :ref:`Linux, or macOS <get-started-configure-linux-macos>` contains a brief introduction on how to set up ``idf.py`` to configure, build, and flash projects.
|
||||
|
||||
.. important::
|
||||
|
||||
@@ -176,7 +176,7 @@ For commands that are not known to ``idf.py``, an attempt to execute them as a b
|
||||
|
||||
The command ``idf.py`` supports `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ for bash, zsh and fish shells.
|
||||
|
||||
To enable autocompletion for ``idf.py``, use the ``export`` command (:ref:`Step 4. Set up the environment variables <get-started-set-up-env>`). Autocompletion is initiated by pressing the TAB key. Type ``idf.py -`` and press the TAB key to autocomplete options.
|
||||
To enable autocompletion for ``idf.py``, use the ``export`` command (:ref:`setting up the environment for Windows <get-started-set-up-env>`, :ref:`Linux or macOS <get-started-set-up-env-linux-macos>`). Autocompletion is initiated by pressing the TAB key. Type ``idf.py -`` and press the TAB key to autocomplete options.
|
||||
|
||||
The autocomplete support for PowerShell is planned in the future.
|
||||
|
||||
|
||||
@@ -167,7 +167,7 @@ These scripts accept optionally a comma-separated list of chip targets and ``--e
|
||||
|
||||
To install tools for all chip targets, run the scripts without any optional arguments using ``idf_tools.py install --targets=all``. Similarly, to install Python packages for core ESP-IDF functionality, run ``idf_tools.py install-python-env --features=core``.
|
||||
|
||||
It is also possible to install tools for specific chip targets. For example, ``install.sh esp32`` installs tools only for ESP32. See :ref:`Step 3. Set up the Tools <get-started-set-up-tools>` for more examples.
|
||||
It is also possible to install tools for specific chip targets. For example, ``install.sh esp32`` installs tools only for ESP32. See :ref:`Step 3. Set up the Tools <get-started-set-up-tools-legacy>` for more examples.
|
||||
|
||||
``install.sh --enable-XY`` enables feature ``XY`` (by running ``idf_tools.py install-python-env --features=core,XY``).
|
||||
|
||||
@@ -208,7 +208,7 @@ Other Installation Methods
|
||||
|
||||
Depending on the environment, more user-friendly wrappers for ``idf_tools.py`` are provided:
|
||||
|
||||
* :ref:`ESP-IDF Tools Installer <get-started-windows-tools-installer>` can download and install the tools. Internally the installer uses ``idf_tools.py``.
|
||||
* :ref:`ESP-IDF Installation Manager <get-started-how-to-get-esp-idf>` can download and install the tools. Internally the installer uses ``idf_tools.py``.
|
||||
* `ESP-IDF Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ includes a menu item to set up the tools. Internally the plugin calls ``idf_tools.py``.
|
||||
* `VSCode ESP-IDF Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_ includes an onboarding flow. This flow helps set up the tools. Although the extension does not rely on ``idf_tools.py``, the same installation method is used.
|
||||
|
||||
@@ -226,7 +226,7 @@ Uninstall ESP-IDF
|
||||
|
||||
Uninstalling ESP-IDF requires removing both the tools and the environment variables that have been configured during the installation.
|
||||
|
||||
* Windows users using the :ref:`Windows ESP-IDF Tools Installer <get-started-windows-tools-installer>` can simply run the uninstall wizard to remove ESP-IDF.
|
||||
* Users using the :ref:`ESP-IDF Installation Manager <get-started-how-to-get-esp-idf>` can remove ESP-IDF in the graphical user interface (GUI) or command line interface (CLI).
|
||||
* To remove an installation performed by running the supported :ref:`install scripts <idf-tools-install>`, simply delete the :ref:`tools installation directory <idf-tools-path>` including the downloaded and installed tools. Any environment variables set by the :ref:`export scripts <idf-tools-export>` are not permanent and will not be present after opening a new environment.
|
||||
* When dealing with a custom installation, in addition to deleting the tools as mentioned above, you may also need to manually revert any changes to environment variables or system paths that were made to accommodate the ESP-IDF tools (e.g., ``IDF_PYTHON_ENV_PATH`` or ``IDF_TOOLS_PATH``). If you manually copied any tools, you would need to track and delete those files manually.
|
||||
* If you installed any plugins like the `ESP-IDF Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ or `VSCode ESP-IDF Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_, you should follow the specific uninstallation instructions described in the documentation of those components.
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
IDF Windows Installer
|
||||
=========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Command-Line Parameters
|
||||
-----------------------
|
||||
|
||||
Windows Installer ``esp-idf-tools-setup`` provides the following command-line parameters:
|
||||
|
||||
* ``/CONFIG=[PATH]`` - Path to ``ini`` configuration file to override default configuration of the installer. Default: ``config.ini``.
|
||||
* ``/GITCLEAN=[yes|no]`` - Perform ``git clean`` and remove untracked directories in offline-mode installation. Default: ``yes``.
|
||||
* ``/GITRECURSIVE=[yes|no]`` - Clone recursively all Git repository submodules. Default: yes.
|
||||
* ``/GITREPO=[URL|PATH]`` - URL of repository to clone ESP-IDF. Default: ``https://github.com/espressif/esp-idf.git``.
|
||||
* ``/GITRESET=[yes|no]`` - Enable/Disable ``git reset`` of repository during installation. Default: ``yes``.
|
||||
* ``/HELP`` - Display command line options provided by Inno Setup installer.
|
||||
* ``/IDFDIR=[PATH]`` - Path to directory where it is installed. Default: ``{userdesktop}\esp-idf}``.
|
||||
* ``/IDFVERSION=[v4.3|v4.1|master]`` - Use specific ESP-IDF version. E.g., v4.1, v4.2, master. Default: ``empty``, pick the first version in the list.
|
||||
* ``/IDFVERSIONSURL=[URL]`` - Use URL to download list of ESP-IDF versions. Default: ``https://dl.espressif.com/dl/esp-idf/idf_versions.txt``.
|
||||
* ``/LOG=[PATH]`` - Store installation log file in specific directory. Default: ``empty``.
|
||||
* ``/OFFLINE=[yes|no]`` - Execute installation of Python packages by ``pip`` in offline mode. The same result can be achieved by setting the environment variable ``PIP_NO_INDEX``. Default: ``no``.
|
||||
* ``/USEEMBEDDEDPYTHON=[yes|no]`` - Use Embedded Python version for the installation. Set to ``no`` to allow the Python selection screen in the installer. Default: ``yes``.
|
||||
* ``/PYTHONNOUSERSITE=[yes|no]`` - Set ``PYTHONNOUSERSITE`` variable before launching any Python command to avoid loading Python packages from AppData\Roaming. Default: ``yes``.
|
||||
* ``/PYTHONWHEELSURL=[URL]`` - Specify URLs to PyPi repositories for resolving binary Python Wheel dependencies. The same result can be achieved by setting the environment variable ``PIP_EXTRA_INDEX_URL``. Default: ``https://dl.espressif.com/pypi``.
|
||||
* ``/SKIPSYSTEMCHECK=[yes|no]`` - Skip System Check page. Default: ``no``.
|
||||
* ``/VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL`` - Perform silent installation.
|
||||
|
||||
Unattended Installation
|
||||
-----------------------
|
||||
|
||||
The unattended installation of ESP-IDF can be achieved by following command-line parameters:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
|
||||
|
||||
When running the installer from the command line, it detaches its process from the command line and starts a separate process in the background to perform the installation without blocking the use of the command line. The following PowerShell script allows you to wait for the installer to complete:
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
|
||||
$InstallerProcess = Get-Process esp-idf-tools-setup
|
||||
Wait-Process -Id $InstallerProcess.id
|
||||
|
||||
Custom Python and Custom Location of Python Wheels
|
||||
--------------------------------------------------
|
||||
|
||||
The IDF installer is using by default embedded Python with reference to the Python Wheel mirror.
|
||||
|
||||
The following parameters allow to select custom Python and custom location of Python wheels:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /USEEMBEDDEDPYTHON=no /PYTHONWHEELSURL=https://pypi.org/simple/
|
||||
@@ -7,7 +7,6 @@ Tools
|
||||
idf-py
|
||||
idf-monitor
|
||||
idf-docker-image
|
||||
idf-windows-installer
|
||||
idf-component-manager
|
||||
idf-clang-tidy
|
||||
idf-tools
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
Open the ESP-IDF Installation Manager application ``eim``.
|
||||
|
||||
Under ``Manage Installations``, click ``Open Dashboard``.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui.png
|
||||
:align: center
|
||||
:alt: EIM Manage Installations
|
||||
|
||||
EIM Manage Installations
|
||||
|
||||
In the dashboard, you will see all the installed ESP-IDF versions. Select the version you want to use, and click ``Open IDF Terminal`` to launch a terminal session with activated ESP-IDF environment.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-open-terminal.png
|
||||
:align: center
|
||||
:alt: EIM Open IDF Terminal
|
||||
|
||||
EIM Open IDF Terminal
|
||||
@@ -0,0 +1,135 @@
|
||||
You can install ESP-IDF and the required tools using one of the following methods, depending on your preference:
|
||||
|
||||
- `Online Installation Using EIM GUI`_
|
||||
|
||||
Recommended for most users. Installs ESP-IDF and tools via a graphical interface with internet access.
|
||||
- `Online Installation Using EIM CLI`_
|
||||
|
||||
Installs ESP-IDF and tools from the command line with internet access.
|
||||
- `Online Installation Using a Loaded Configuration`_
|
||||
|
||||
Installs ESP-IDF and tools using a pre-saved configuration file copied from another PC. This method works with both the GUI and CLI, but requires internet access.
|
||||
- `Offline Installation`_
|
||||
|
||||
Installs ESP-IDF and tools from a local package, without internet access.
|
||||
|
||||
|
||||
Online Installation Using EIM GUI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Open the ESP-IDF Installation Manager application `eim`.
|
||||
|
||||
Under ``New Installation`` click ``Start Installation``.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui.png
|
||||
:align: center
|
||||
:alt: EIM Start Installation
|
||||
|
||||
EIM Start Installation
|
||||
|
||||
.. note::
|
||||
|
||||
If you have never installed ESP-IDF before, you will not see ``Manage Installations``. In this case, ``New Installation`` will be the only available option.
|
||||
|
||||
Under ``Easy Installation``, click ``Start Easy Installation`` to install the latest stable version of ESP-IDF with default settings.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-install.png
|
||||
:align: center
|
||||
:alt: EIM Easy Installation
|
||||
|
||||
EIM Easy Installation
|
||||
|
||||
If all prerequisites and path checks pass, you will see the ``Ready to Install`` page. Click ``Start Installation`` to begin the installation.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-ready-install.png
|
||||
:align: center
|
||||
:alt: EIM Ready to Install
|
||||
|
||||
EIM Ready to Install
|
||||
|
||||
During the installation, you can monitor the progress directly in the interface.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-installing.png
|
||||
:align: center
|
||||
:alt: EIM Installing
|
||||
|
||||
EIM Installing
|
||||
|
||||
Once finished, the ``Installation Complete`` page will appear.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-install-complete.png
|
||||
:align: center
|
||||
:alt: EIM Installation Complete
|
||||
|
||||
EIM Installation Complete
|
||||
|
||||
If the installation fails, you can:
|
||||
|
||||
- Click ``Logs`` at the bottom of the interface to view error details. Resolve the issues and click ``Try Again`` to restart the installation.
|
||||
- Alternatively, use `Custom Installation <https://docs.espressif.com/projects/idf-im-ui/en/latest/expert_installation.html>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
- To select an ESP-IDF version or customize the installation path, use ``Custom Installation`` instead. See more instructions in `EIM documentation > Expert Installations <https://docs.espressif.com/projects/idf-im-ui/en/latest/expert_installation.html>`__.
|
||||
- To manage existing installations, refer to `EIM documentation > Version Management <https://docs.espressif.com/projects/idf-im-ui/en/latest/version_management.html>`__.
|
||||
|
||||
|
||||
Online Installation Using EIM CLI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Run the following command to install the latest stable version of ESP-IDF with default settings in non-interactive mode:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim install
|
||||
|
||||
If you encounter issues running the above command, or if you want to customize the installation path, select ESP-IDF versions, or modify other options, launch the interactive installation wizard and follow the on-screen prompts:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim wizard
|
||||
|
||||
If the ESP-IDF version you want to install is not available in the interactive wizard, run the following command to install any available `versions <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/versions.html#releases>`__. For example, to install ESP-IDF v5.4.2, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim install -i v5.4.2
|
||||
|
||||
Once the installation is complete, you will see the following message in the terminal:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
2025-11-03T15:54:12.537993300+08:00 - INFO - Wizard result: %{r}
|
||||
2025-11-03T15:54:12.544174+08:00 - INFO - Successfully installed IDF
|
||||
2025-11-03T15:54:12.545913900+08:00 - INFO - Now you can start using IDF tools
|
||||
|
||||
.. note::
|
||||
|
||||
- To see all available options, run:
|
||||
.. code-block:: bash
|
||||
|
||||
eim --help
|
||||
- For more information about CLI usage, refer to
|
||||
|
||||
* `EIM documentation > CLI Configuration <https://docs.espressif.com/projects/idf-im-ui/en/latest/cli_configuration.html>`__
|
||||
* `EIM documentation > CLI Commands <https://docs.espressif.com/projects/idf-im-ui/en/latest/cli_commands.html>`__
|
||||
|
||||
|
||||
Online Installation Using a Loaded Configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When you install ESP-IDF, the installer automatically saves your setup to a configuration file named ``eim_config.toml`` in the installation directory. This configuration file can be reused on other computers to reproduce the same installation setup.
|
||||
|
||||
To install ESP-IDF using an existing ``eim_config.toml`` file, refer to the `EIM documentation > Configuration Files <https://docs.espressif.com/projects/idf-im-ui/en/latest/gui_configuration.html#configuration-files>`__.
|
||||
|
||||
|
||||
Offline Installation
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Both the GUI and CLI installers support offline installation. For instructions, refer to `EIM documentation > Offline Installation <https://docs.espressif.com/projects/idf-im-ui/en/latest/offline_installation.html>`__.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
You are now ready to start developing with ESP-IDF. To begin building and running your first application, continue with the :ref:`get-started-build` section.
|
||||
@@ -381,6 +381,6 @@ If you can see readable log output, it means serial connection is working and yo
|
||||
|
||||
For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the {IDF_TARGET_NAME} booting and producing serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & {IDF_TARGET_STRAP_GPIO} pins. See the `esptool documentation`_ for more details.
|
||||
|
||||
If you got here from :ref:`get-started-connect` when installing s/w for {IDF_TARGET_NAME} development, then you can continue with :ref:`get-started-configure`.
|
||||
If you got here from :ref:`Connect Your Device for Windows <get-started-connect>`, :ref:`Linux, or macOS <get-started-connect-linux-macos>` when installing s/w for {IDF_TARGET_NAME} development, then you can continue with :ref:`Configure Your Project for Windows <get-started-configure>`, :ref:`Linux, or macOS <get-started-configure-linux-macos>`.
|
||||
|
||||
.. _esptool documentation: https://docs.espressif.com/projects/esptool/en/latest/advanced-topics/boot-mode-selection.html#automatic-bootloader
|
||||
|
||||
@@ -127,21 +127,18 @@ If you have one of {IDF_TARGET_NAME} official development boards listed below, y
|
||||
|
||||
ESP32-DevKitC <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-devkitc/index.html>
|
||||
ESP32-DevKitM-1 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-devkitm-1/index.html>
|
||||
ESP-WROVER-KIT <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp-wrover-kit/index.html>
|
||||
ESP32-PICO-KIT <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-pico-kit/index.html>
|
||||
ESP32-Ethernet-Kit <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-ethernet-kit/index.html>
|
||||
ESP32-PICO-KIT-1 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-pico-kit-1/index.html>
|
||||
ESP32-PICO-DevKitM-2 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-pico-devkitm-2/index.html>
|
||||
ESP32-LCDKit <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-lcdkit/index.html>
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ESP32-S2-Saola-1 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-saola-1/index.html>
|
||||
ESP32-S2-DevKitM-1 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-devkitm-1/index.html>
|
||||
ESP32-S2-DevKitC-1 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-devkitc-1/index.html>
|
||||
ESP32-S2-Kaluga-Kit <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-kaluga-1/index.html>
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
@@ -150,7 +147,7 @@ If you have one of {IDF_TARGET_NAME} official development boards listed below, y
|
||||
|
||||
ESP32-C3-DevKitM-1 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32c3/esp32-c3-devkitm-1/index.html>
|
||||
ESP32-C3-DevKitC-02 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32c3/esp32-c3-devkitc-02/index.html>
|
||||
|
||||
ESP32-C3-LCDkit <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c3/esp32-c3-lcdkit/index.html>
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
@@ -159,6 +156,10 @@ If you have one of {IDF_TARGET_NAME} official development boards listed below, y
|
||||
|
||||
ESP32-S3-DevKitC-1 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-devkitc-1/index.html>
|
||||
ESP32-S3-DevKitM-1 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-devkitm-1/index.html>
|
||||
ESP32-S3-USB-OTG <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-usb-otg/index.html>
|
||||
ESP32-S3-LCD-EV-Board <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-lcd-ev-board/index.html>
|
||||
EchoEar <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/echoear/index.html>
|
||||
ESP-DualKey <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp-dualkey/index.html>
|
||||
|
||||
.. only:: esp32c2
|
||||
|
||||
@@ -166,6 +167,7 @@ If you have one of {IDF_TARGET_NAME} official development boards listed below, y
|
||||
:maxdepth: 1
|
||||
|
||||
ESP8684-DevKitM-1 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp8684/esp8684-devkitm-1/index.html>
|
||||
ESP8684-DevKitC-02 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c2/esp8684-devkitc-02/index.html>
|
||||
|
||||
.. only:: esp32c5
|
||||
|
||||
@@ -195,7 +197,7 @@ If you have one of {IDF_TARGET_NAME} official development boards listed below, y
|
||||
Software
|
||||
~~~~~~~~
|
||||
|
||||
To start using ESP-IDF on **{IDF_TARGET_NAME}**, install the following software:
|
||||
To start using ESP-IDF on **{IDF_TARGET_NAME}**, you need the following software:
|
||||
|
||||
* **Toolchain** to compile code for {IDF_TARGET_NAME}
|
||||
* **Build tools** - CMake and Ninja to build a full **Application** for {IDF_TARGET_NAME}
|
||||
@@ -208,39 +210,113 @@ To start using ESP-IDF on **{IDF_TARGET_NAME}**, install the following software:
|
||||
|
||||
.. _get-started-step-by-step:
|
||||
.. _get-started-how-to-get-esp-idf:
|
||||
.. _get-started-set-up-tools:
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
To install all the required software, we offer some different ways to facilitate this task. Choose from one of the available options.
|
||||
To install ESP-IDF, build tools, and the toolchain, use the ESP-IDF Installation Manager (EIM) available for multiple operating systems.
|
||||
|
||||
IDE
|
||||
~~~
|
||||
The EIM provides two installation options:
|
||||
|
||||
.. note:: We highly recommend installing the ESP-IDF through your favorite IDE.
|
||||
|
||||
* `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_
|
||||
* `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/README.md>`_
|
||||
|
||||
Manual Installation
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For the manual procedure, please select according to your operating system.
|
||||
- **Graphical User Interface (GUI)**: Offers a user-friendly interface, ideal for most users.
|
||||
- **Command Line Interface (CLI)**: Suitable for CI/CD pipelines and automated installations.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Windows Installer <windows-setup>
|
||||
Linux and macOS <linux-macos-setup>
|
||||
windows-setup
|
||||
linux-setup
|
||||
macos-setup
|
||||
|
||||
.. _get-started-build:
|
||||
|
||||
Build Your First Project
|
||||
========================
|
||||
|
||||
If you already have the ESP-IDF installed and are not using an IDE, you can build your first project from the command line following the :ref:`Start a Project on Windows <get-started-windows-first-steps>` or :ref:`Start a Project on Linux and macOS <get-started-linux-macos-first-steps>`.
|
||||
Once you have the ESP-IDF installed, you can build your first project either using an IDE or from the command line.
|
||||
|
||||
|
||||
Build in IDE
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The ESP-IDF versions installed through EIM can be used in the following IDEs, providing a graphical development experience:
|
||||
|
||||
- `Espressif-IDE <https://docs.espressif.com/projects/espressif-ide/en/latest/>`_ based on Eclipse CDT
|
||||
|
||||
It includes IDF Eclipse plugins, essential Eclipse CDT plugins, and other third-party plugins from the Eclipse platform to support building ESP-IDF applications.
|
||||
- Visual Studio Code integrated with the `ESP-IDF Extension for VS Code <https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/index.html>`_
|
||||
|
||||
It allows you to develop, build, flash, and monitor ESP-IDF applications directly within the Visual Studio Code.
|
||||
|
||||
For instructions on how to set up and use these IDEs with ESP-IDF, please refer to their respective documentation linked above.
|
||||
|
||||
|
||||
Build from Command Line
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To start a new project, build it, flash to {IDF_TARGET_NAME}, and monitor the device output from the command line, follow instructions for your operating system:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
windows-start-project
|
||||
linux-macos-start-project
|
||||
|
||||
.. note::
|
||||
|
||||
If you have not yet installed ESP-IDF, please go to :ref:`get-started-step-by-step` and follow the instructions there to install all required software before proceeding.
|
||||
|
||||
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
|
||||
|
||||
Uninstall ESP-IDF
|
||||
=================
|
||||
|
||||
If you want to remove ESP-IDF, please follow :ref:`idf-tools-uninstall`.
|
||||
To uninstall ESP-IDF and related tools installed via EIM, you can use either the graphical user interface (GUI) or the command line interface (CLI).
|
||||
|
||||
Uninstall Using EIM GUI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Launch the ESP-IDF Installation Manager. Under ``Manage Installations``, click ``Open Dashboard``.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui.png
|
||||
:align: center
|
||||
:alt: Open Dashboard in EIM GUI
|
||||
:figclass: align-center
|
||||
|
||||
Open Dashboard in EIM GUI
|
||||
|
||||
To remove a specific ESP-IDF version, click the ``Remove`` button under the version you want to remove.
|
||||
|
||||
To remove all ESP-IDF versions, click ``Purge All`` button at the bottom of the page.
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-uninstall.png
|
||||
:align: center
|
||||
:alt: Uninstall ESP-IDF in EIM GUI
|
||||
:figclass: align-center
|
||||
|
||||
Uninstall ESP-IDF in EIM GUI
|
||||
|
||||
Uninstall Using EIM CLI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To remove a specific ESP-IDF version, for example v5.4.2, run the following command in your terminal:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim uninstall v5.4.2
|
||||
|
||||
To remove all ESP-IDF versions, run the following command in your terminal:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim purge
|
||||
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
* `ESP-IDF Installation Manager (EIM) documentation <https://docs.espressif.com/projects/idf-im-ui/en/latest/>`_
|
||||
* `Espressif-IDE (ESP-IDF Eclipse Plugin) GitHub repository <https://github.com/espressif/idf-eclipse-plugin/tree/master>`_
|
||||
* `ESP-IDF Extension for VS Code GitHub repository <https://github.com/espressif/vscode-esp-idf-extension/tree/master>`_
|
||||
|
||||
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
|
||||
|
||||
+19
-41
@@ -1,9 +1,13 @@
|
||||
********************************************
|
||||
Standard Toolchain Setup for Linux and macOS
|
||||
********************************************
|
||||
*********************************************************
|
||||
Standard Toolchain Setup for Linux and macOS (Legacy)
|
||||
*********************************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. warning::
|
||||
|
||||
This document describes the legacy installation method of ESP-IDF on Linux and macOS, which was the default before v6.0.
|
||||
|
||||
Installation Step by Step
|
||||
=========================
|
||||
|
||||
@@ -14,13 +18,12 @@ Setting up Development Environment
|
||||
|
||||
These are the steps for setting up the ESP-IDF for your {IDF_TARGET_NAME}.
|
||||
|
||||
* :ref:`get-started-prerequisites`
|
||||
* :ref:`get-started-get-esp-idf`
|
||||
* :ref:`get-started-set-up-tools`
|
||||
* :ref:`get-started-set-up-env`
|
||||
* :ref:`get-started-start-a-project`
|
||||
* :ref:`get-started-prerequisites-legacy`
|
||||
* :ref:`get-started-get-esp-idf-legacy`
|
||||
* :ref:`get-started-set-up-tools-legacy`
|
||||
* :ref:`get-started-set-up-env-legacy`
|
||||
|
||||
.. _get-started-prerequisites:
|
||||
.. _get-started-prerequisites-legacy:
|
||||
|
||||
Step 1. Install Prerequisites
|
||||
=============================
|
||||
@@ -116,7 +119,7 @@ To install supported Python 3 on macOS:
|
||||
|
||||
During installation, the install script will check for supported Python versions on your system and select the oldest version that meets the minimum requirement.
|
||||
|
||||
.. _get-started-get-esp-idf:
|
||||
.. _get-started-get-esp-idf-legacy:
|
||||
|
||||
Step 2. Get ESP-IDF
|
||||
===================
|
||||
@@ -133,7 +136,7 @@ ESP-IDF is downloaded into ``~/esp/esp-idf``.
|
||||
|
||||
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
|
||||
|
||||
.. _get-started-set-up-tools:
|
||||
.. _get-started-set-up-tools-legacy:
|
||||
|
||||
Step 3. Set up the Tools
|
||||
========================
|
||||
@@ -228,7 +231,7 @@ If changing the ``IDF_TOOLS_PATH``, make sure it is exported in the environment
|
||||
.. note::
|
||||
Using ``IDF_TOOLS_PATH`` in variable assignment, e.g., ``IDF_TOOLS_PATH="$HOME/required_idf_tools_path" ./install.sh``, without prior exporting, will not work in most shells because the variable assignment will not affect the current execution environment, even if it's exported/changed in the sourced script.
|
||||
|
||||
.. _get-started-set-up-env:
|
||||
.. _get-started-set-up-env-legacy:
|
||||
|
||||
Step 4. Set up the Environment Variables
|
||||
========================================
|
||||
@@ -263,32 +266,21 @@ Now you can run ``get_idf`` to set up or refresh the esp-idf environment in any
|
||||
|
||||
Technically, you can add ``export.sh`` to your shell's profile directly; however, it is not recommended. Doing so activates IDF virtual environment in every terminal session (including those where IDF is not needed), defeating the purpose of the virtual environment and likely affecting other software.
|
||||
|
||||
.. _get-started-start-a-project:
|
||||
.. _get-started-build:
|
||||
.. _get-started-configure:
|
||||
.. _get-started-connect:
|
||||
.. _get-started-linux-macos-first-steps:
|
||||
|
||||
Step 5. First Steps on ESP-IDF
|
||||
==============================
|
||||
|
||||
.. include:: linux-macos-start-project.rst
|
||||
.. include:: start-project.rst
|
||||
|
||||
.. _get-started-update-esp-idf:
|
||||
.. _get-started-update-esp-idf-legacy:
|
||||
|
||||
Updating ESP-IDF and Python Packages in the ESP-IDF Environment
|
||||
===============================================================
|
||||
|
||||
It is recommended to update ESP-IDF from time to time, as newer versions fix bugs and/or provide new features. Please note that each ESP-IDF major and minor release version has an associated support period, and when one release branch is approaching end of life (EOL), all users are encouraged to upgrade their projects to more recent ESP-IDF releases, to find out more about support periods, see :doc:`ESP-IDF Versions <../versions>`.
|
||||
|
||||
The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`.
|
||||
The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf-legacy`.
|
||||
|
||||
Another solution is to update only what has changed. For specific instructions, please visit :ref:`Updating ESP-IDF <updating-master>` page.
|
||||
|
||||
After updating ESP-IDF, execute the install script again (``./install.sh`` in your ``$IDF_PATH``), in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools`.
|
||||
After updating ESP-IDF, execute the install script again (``./install.sh`` in your ``$IDF_PATH``), in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools-legacy`.
|
||||
|
||||
Once all the new tools are installed, enter the ESP-IDF environment using the export script as described in :ref:`get-started-set-up-env`.
|
||||
Once all the new tools are installed, enter the ESP-IDF environment using the export script as described in :ref:`get-started-set-up-env-legacy`.
|
||||
|
||||
Updating Python Packages in the ESP-IDF Environment Without Updating ESP-IDF
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -299,20 +291,6 @@ Some features in ESP-IDF are not included directly in the ESP-IDF repository. In
|
||||
|
||||
If you are an advanced user and want more control over the update process, you can also check :ref:`idf-tools-py` and its ``install-python-env`` command, which is used by the install script and handles the creation or update of the ESP-IDF environment.
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
* :doc:`establish-serial-connection`
|
||||
* `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_
|
||||
* `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_
|
||||
* :doc:`../api-guides/tools/idf-monitor`
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
establish-serial-connection
|
||||
flashing-troubleshooting
|
||||
|
||||
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
|
||||
.. _First Steps on ESP-IDF: ../get-started/first-steps.html
|
||||
@@ -1,10 +1,53 @@
|
||||
Now since all requirements are met, the next topic will guide you on how to start your first project.
|
||||
****************************************************
|
||||
Start a Project on Linux and macOS from Command Line
|
||||
****************************************************
|
||||
|
||||
This guide helps you on the first steps using ESP-IDF. Follow this guide to start a new project on the {IDF_TARGET_NAME} and build, flash, and monitor the device output.
|
||||
This guide helps you to start a new project on the {IDF_TARGET_NAME} and build, flash, and monitor the device output on Linux and macOS.
|
||||
|
||||
|
||||
.. _get-started-set-up-env-linux-macos:
|
||||
|
||||
Activate the Environment
|
||||
========================
|
||||
|
||||
.. note::
|
||||
|
||||
If you have not yet installed ESP-IDF, please go to :ref:`get-started-step-by-step` and follow the instruction in order to get all the software needed to use this guide.
|
||||
This section describes the default and recommended procedures to activate the environment from ESP-IDF v6.0. If you use the :doc:`legacy installation method on Linux and macOS <linux-macos-setup-legacy>`, skip this section.
|
||||
|
||||
Before using ESP-IDF tools in the terminal, you must activate the ESP-IDF environment. You can do this either via the GUI or CLI.
|
||||
|
||||
- `Activate Using EIM GUI`_
|
||||
- `Activate Using EIM CLI`_
|
||||
|
||||
Activate Using EIM GUI
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: eim-gui-activate-env.rst
|
||||
|
||||
Activate Using EIM CLI
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Upon successful installation of ESP-IDF, the EIM CLI prints a command to activate the ESP-IDF environment. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
:emphasize-lines: 6
|
||||
|
||||
You have successfully installed ESP-IDF
|
||||
for using the ESP-IDF tools inside the terminal, you will find activation scripts inside the base install folder
|
||||
sourcing the activation script will setup environment in the current terminal session
|
||||
============================================
|
||||
to activate the environment, run the following command in your terminal:
|
||||
source "/Users/username/.espressif/tools/activate_idf_v5.4.2.sh"
|
||||
============================================
|
||||
|
||||
Run the highlighted command in your terminal:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
source "/Users/username/.espressif/tools/activate_idf_v5.4.2.sh"
|
||||
|
||||
Once done, you have successfully activated the ESP-IDF environment in your terminal. All subsequent ESP-IDF commands should be run in this activated terminal.
|
||||
|
||||
|
||||
Start a Project
|
||||
===================
|
||||
@@ -24,6 +67,8 @@ Copy the project :example:`get-started/hello_world` to ``~/esp`` directory:
|
||||
|
||||
.. note:: There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. It is also possible to build examples in-place without copying them first.
|
||||
|
||||
.. _get-started-connect-linux-macos:
|
||||
|
||||
Connect Your Device
|
||||
===================
|
||||
|
||||
@@ -40,6 +85,8 @@ If you are not sure how to check the serial port name, please refer to :doc:`est
|
||||
|
||||
Keep the port name handy as it is needed in the next steps.
|
||||
|
||||
.. _get-started-configure-linux-macos:
|
||||
|
||||
Configure Your Project
|
||||
======================
|
||||
|
||||
@@ -93,3 +140,5 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
|
||||
``USB CDC``
|
||||
|
||||
3. Save the new configuration and exit the ``menuconfig`` screen.
|
||||
|
||||
.. include:: start-project.rst
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
************************************************
|
||||
Installation of ESP-IDF and Tools on Linux
|
||||
************************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This section describes how to install ESP-IDF and its required tools on Linux distributions (e.g., Ubuntu) using the ESP-IDF Installation Manager (EIM).
|
||||
|
||||
.. note::
|
||||
|
||||
This document describes the default and recommended way to install ESP-IDF v6.0 and newer versions. ESP-IDF also supports the :doc:`legacy installation method on Linux <linux-macos-setup-legacy>`, which was the default before ESP-IDF v6.0.
|
||||
|
||||
|
||||
Step 1: Install the Prerequisites (Optional)
|
||||
============================================
|
||||
|
||||
Skip this step if you plan to install EIM using :ref:`APT <install-eim-linux-apt>`.
|
||||
|
||||
For other installation methods, install the `required prerequisites <https://docs.espressif.com/projects/idf-im-ui/en/latest/prerequisites.html#linux>`_. These prerequisites may vary depending on your Linux distribution.
|
||||
|
||||
.. note::
|
||||
|
||||
Python 3.10 is the minimum supported version for ESP-IDF.
|
||||
|
||||
However, for `Offline Installation`_, EIM requires **Python 3.11 or versions later**.
|
||||
|
||||
|
||||
Step 2: Install the EIM
|
||||
=======================
|
||||
|
||||
You can install the EIM using one of the following methods:
|
||||
|
||||
- `Debian-Based Linux Installation via APT`_
|
||||
- `RPM-Based Linux Installation via DNF`_
|
||||
- `Download the EIM Installer`_
|
||||
|
||||
Installing via APT or DNF allows you to easily keep EIM up to date.
|
||||
|
||||
|
||||
.. _install-eim-linux-apt:
|
||||
|
||||
Debian-Based Linux Installation via APT
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Add the EIM repository to your APT sources list to make it available for installation:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
echo "deb [trusted=yes] https://dl.espressif.com/dl/eim/apt/ stable main" | sudo tee /etc/apt/sources.list.d/espressif.list
|
||||
|
||||
sudo apt update
|
||||
|
||||
Then, install the EIM Command Line Interface (CLI) alone, or together with Graphical User Interface (GUI) via APT:
|
||||
|
||||
- GUI and CLI:
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt install eim
|
||||
|
||||
- CLI only:
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt install eim-cli
|
||||
|
||||
|
||||
RPM-Based Linux Installation via DNF
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Add the EIM repository to your DNF sources list to make it available for installation:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo tee /etc/yum.repos.d/espressif-eim.repo << 'EOF'
|
||||
[eim]
|
||||
name=ESP-IDF Installation Manager
|
||||
baseurl=https://dl.espressif.com/dl/eim/rpm/$basearch
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
EOF
|
||||
|
||||
Then, install the EIM Command Line Interface (CLI) alone, or together with Graphical User Interface (GUI) via DNF:
|
||||
|
||||
- GUI and CLI:
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dnf install eim
|
||||
|
||||
- CLI only:
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dnf install eim-cli
|
||||
|
||||
|
||||
Download the EIM Installer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Alternatively, download the EIM installer for Linux from the `Espressif Download Page <https://dl.espressif.com/dl/eim/>`__, which provides both online and offline installers available in both CLI and GUI versions.
|
||||
|
||||
|
||||
Step 3: Install ESP-IDF Using EIM
|
||||
=================================
|
||||
|
||||
.. include:: eim-install-idf.rst
|
||||
@@ -0,0 +1,68 @@
|
||||
************************************************
|
||||
Installation of ESP-IDF and Tools on macOS
|
||||
************************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This section describes how to install ESP-IDF and its required tools on macOS using the Espressif Installation Manager (EIM).
|
||||
|
||||
.. note::
|
||||
|
||||
This document describes the default and recommended way to install ESP-IDF v6.0 and newer versions. ESP-IDF also supports the :doc:`legacy installation method on macOS <linux-macos-setup-legacy>`, which was the default before ESP-IDF v6.0.
|
||||
|
||||
|
||||
Step 1: Install the Prerequisites
|
||||
=================================
|
||||
|
||||
Install the required prerequisites via `Homebrew <https://brew.sh/>`_:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
brew install libgcrypt glib pixman sdl2 libslirp dfu-util cmake python
|
||||
|
||||
.. note::
|
||||
|
||||
Python 3.10 is the minimum supported version for ESP-IDF.
|
||||
|
||||
However, for `Offline Installation`_, EIM requires **Python 3.11 or versions later**.
|
||||
|
||||
|
||||
Step 2: Install the EIM
|
||||
=======================
|
||||
|
||||
Add the EIM repository to the Homebrew to make it available for installation:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
brew tap espressif/eim
|
||||
|
||||
Then, install the EIM Graphical User Interface (GUI) or Command Line Interface (CLI) via Homebrew:
|
||||
|
||||
- GUI:
|
||||
.. code-block:: bash
|
||||
|
||||
brew install --cask eim-gui
|
||||
|
||||
- CLI:
|
||||
.. code-block:: bash
|
||||
|
||||
brew install eim
|
||||
|
||||
.. note::
|
||||
|
||||
Installing via Homebrew makes it easier to keep EIM up to date.
|
||||
|
||||
Alternatively, download the EIM installer for macOS from the `Espressif Download Page <https://dl.espressif.com/dl/eim/>`__, which provides both online and offline installers available in both CLI and GUI versions.
|
||||
|
||||
|
||||
Step 3: Install ESP-IDF Using EIM
|
||||
=================================
|
||||
|
||||
.. include:: eim-install-idf.rst
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
:caption: Legacy Installation
|
||||
|
||||
linux-macos-setup-legacy
|
||||
@@ -222,3 +222,17 @@ For erasing the OTA data, if present, you can run this command:
|
||||
idf.py -p PORT erase-otadata
|
||||
|
||||
The flash erase command can take a while to be done. Do not disconnect your device while the flash erasing is in progress.
|
||||
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
* :doc:`establish-serial-connection`
|
||||
* :doc:`../api-guides/tools/idf-monitor`
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
establish-serial-connection
|
||||
flashing-troubleshooting
|
||||
|
||||
+7
-3
@@ -1,9 +1,13 @@
|
||||
*********************************
|
||||
Updating ESP-IDF Tools on Windows
|
||||
*********************************
|
||||
*******************************************
|
||||
Updating ESP-IDF Tools on Windows (Legacy)
|
||||
*******************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. warning::
|
||||
|
||||
This document describes the legacy method for updating ESP-IDF tools, which was the default before v6.0.
|
||||
|
||||
.. _get-started-install_bat-windows:
|
||||
|
||||
Install ESP-IDF Tools Using a Script
|
||||
@@ -1,142 +1,46 @@
|
||||
***********************************************
|
||||
Standard Setup of Toolchain for Windows
|
||||
***********************************************
|
||||
************************************************
|
||||
Installation of ESP-IDF and Tools on Windows
|
||||
************************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
ESP-IDF requires some prerequisite tools to be installed so you can build firmware for supported chips. The prerequisite tools include Python, Git, cross-compilers, CMake and Ninja build tools.
|
||||
|
||||
For this Getting Started we are going to use the Command Prompt, but after ESP-IDF is installed you can use `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ or another graphical IDE with CMake support instead.
|
||||
This section describes how to install ESP-IDF and its required tools on Windows using the Espressif Installation Manager (EIM).
|
||||
|
||||
.. note::
|
||||
|
||||
Limitations:
|
||||
This document describes the default and recommended way to install ESP-IDF v6.0 and newer versions. ESP-IDF also supports the :doc:`legacy method for updating ESP-IDF tools on Windows <windows-setup-update-legacy>`.
|
||||
|
||||
- The installation path of ESP-IDF and ESP-IDF Tools must not be longer than 90 characters. Too long installation paths might result in a failed build.
|
||||
- The installation path of Python or ESP-IDF must not contain white spaces or parentheses.
|
||||
- The installation path of Python or ESP-IDF should not contain special characters (non-ASCII) unless the operating system is configured with "Unicode UTF-8" support.
|
||||
|
||||
System Administrator can enable the support via ``Control Panel`` > Change ``date``, ``time``, or ``number`` formats > ``Administrative tab`` > Change ``system locale`` > check the option ``Beta: Use Unicode UTF-8 for worldwide language support`` > ``Ok`` > reboot the computer.
|
||||
|
||||
.. _get-started-windows-tools-installer:
|
||||
|
||||
ESP-IDF Tools Installer
|
||||
Step 1: Install the EIM
|
||||
=======================
|
||||
|
||||
The easiest way to install ESP-IDF's prerequisites is to download one of ESP-IDF Tools Installers.
|
||||
Install the EIM Graphical User Interface (GUI) or Command Line Interface (CLI) via `WinGet <https://learn.microsoft.com/en-us/windows/package-manager/winget/>`__:
|
||||
|
||||
+-------------------+--------------------------------+
|
||||
| |download-logo| | `Windows Installer Download`_ |
|
||||
+-------------------+--------------------------------+
|
||||
- GUI:
|
||||
.. code-block:: bash
|
||||
|
||||
.. |download-logo| image:: ../../_static/logo_windows_install.png
|
||||
:target: https://dl.espressif.com/dl/esp-idf/?idf=4.4
|
||||
winget install Espressif.EIM
|
||||
|
||||
.. _Windows Installer Download: https://dl.espressif.com/dl/esp-idf/?idf=4.4
|
||||
- CLI:
|
||||
.. code-block:: bash
|
||||
|
||||
winget install Espressif.EIM-CLI
|
||||
|
||||
.. note::
|
||||
|
||||
Installing via WinGet makes it easier to keep EIM up to date.
|
||||
|
||||
Alternatively, download the EIM installer for Windows from the `Espressif Download Page <https://dl.espressif.com/dl/eim/>`__, which provides both online and offline installers available in both CLI and GUI versions.
|
||||
|
||||
|
||||
What Is the Usecase for Online and Offline Installer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Step 2: Install ESP-IDF Using EIM
|
||||
=================================
|
||||
|
||||
Online Installer is very small and allows the installation of all available releases of ESP-IDF. The installer downloads only necessary dependencies including `Git For Windows`_ during the installation process. The installer stores downloaded files in the cache directory ``%userprofile%\.espressif``
|
||||
|
||||
Offline Installer does not require any network connection. The installer contains all required dependencies including `Git For Windows`_.
|
||||
|
||||
Components of the Installation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The installer deploys the following components:
|
||||
|
||||
- Embedded Python
|
||||
- Cross-compilers
|
||||
- OpenOCD
|
||||
- CMake_ and Ninja_ build tools
|
||||
- ESP-IDF
|
||||
|
||||
The installer also allows reusing the existing directory with ESP-IDF. The recommended directory is ``%userprofile%\Desktop\esp-idf`` where ``%userprofile%`` is your home directory.
|
||||
|
||||
Launching ESP-IDF Environment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
At the end of the installation process you can check out option ``Run ESP-IDF PowerShell Environment`` or ``Run ESP-IDF Command Prompt (cmd.exe)``. The installer launches ESP-IDF environment in selected prompt.
|
||||
|
||||
``Run ESP-IDF PowerShell Environment``:
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-screenshot-powershell.png
|
||||
:align: center
|
||||
:alt: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment
|
||||
:figclass: align-center
|
||||
|
||||
Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-powershell.png
|
||||
:align: center
|
||||
:alt: ESP-IDF PowerShell
|
||||
:figclass: align-center
|
||||
|
||||
ESP-IDF PowerShell
|
||||
|
||||
``Run ESP-IDF Command Prompt (cmd.exe)``:
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-screenshot.png
|
||||
:align: center
|
||||
:alt: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF Command Prompt (cmd.exe)
|
||||
:figclass: align-center
|
||||
|
||||
Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF Command Prompt (cmd.exe)
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-command-prompt.png
|
||||
:align: center
|
||||
:alt: ESP-IDF Command Prompt
|
||||
:figclass: align-center
|
||||
|
||||
ESP-IDF Command Prompt
|
||||
|
||||
Using the Command Prompt
|
||||
========================
|
||||
|
||||
For the remaining Getting Started steps, we are going to use the Windows Command Prompt.
|
||||
|
||||
ESP-IDF Tools Installer also creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This shortcut launches the Command Prompt (cmd.exe) and runs ``export.bat`` script to set up the environment variables (``PATH``, ``IDF_PATH`` and others). Inside this command prompt, all the installed tools are available.
|
||||
|
||||
Note that this shortcut is specific to the ESP-IDF directory selected in the ESP-IDF Tools Installer. If you have multiple ESP-IDF directories on the computer (for example, to work with different versions of ESP-IDF), you have two options to use them:
|
||||
|
||||
1. Create a copy of the shortcut created by the ESP-IDF Tools Installer, and change the working directory of the new shortcut to the ESP-IDF directory you wish to use.
|
||||
|
||||
2. Alternatively, run ``cmd.exe``, then change to the ESP-IDF directory you wish to use, and run ``export.bat``. Note that unlike the previous option, this way requires Python and Git to be present in ``PATH``. If you get errors related to Python or Git not being found, use the first option.
|
||||
|
||||
First Steps on ESP-IDF
|
||||
======================
|
||||
|
||||
.. _get-started-windows-first-steps:
|
||||
|
||||
.. include:: windows-start-project.rst
|
||||
.. include:: start-project.rst
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
For advanced users who want to customize the install process:
|
||||
|
||||
* :doc:`windows-setup-update`
|
||||
* :doc:`establish-serial-connection`
|
||||
* `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_
|
||||
* `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_
|
||||
* :doc:`../api-guides/tools/idf-monitor`
|
||||
.. include:: eim-install-idf.rst
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
:caption: Legacy Installation
|
||||
|
||||
windows-setup-update
|
||||
establish-serial-connection
|
||||
flashing-troubleshooting
|
||||
|
||||
.. _CMake: https://cmake.org/download/
|
||||
.. _Ninja: https://ninja-build.org/
|
||||
.. _Python: https://www.python.org/downloads/windows/
|
||||
.. _Git for Windows: https://gitforwindows.org/
|
||||
.. _Github Desktop: https://desktop.github.com/
|
||||
windows-setup-update-legacy
|
||||
|
||||
@@ -1,10 +1,38 @@
|
||||
Now since all requirements are met, the next topic guides you on how to start your first project.
|
||||
********************************************
|
||||
Start a Project on Windows from Command Line
|
||||
********************************************
|
||||
|
||||
This guide helps you on the first steps using ESP-IDF. Follow this guide to start a new project on the {IDF_TARGET_NAME} and build, flash, and monitor the device output.
|
||||
This guide helps you to start a new project on the {IDF_TARGET_NAME} and build, flash, and monitor the device output on Windows.
|
||||
|
||||
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
Activate the Environment
|
||||
========================
|
||||
|
||||
.. note::
|
||||
|
||||
If you have not yet installed ESP-IDF, please go to :ref:`get-started-step-by-step` and follow the instruction in order to get all the software needed to use this guide.
|
||||
This section describes the default and recommended procedures to activate the environment from ESP-IDF v6.0. If you use the :doc:`legacy method for updating ESP-IDF tools <windows-setup-update-legacy>`, skip this section.
|
||||
|
||||
Before using ESP-IDF tools in the terminal, you must activate the ESP-IDF environment. You can do this either via the GUI or CLI.
|
||||
|
||||
- `Activate Using EIM GUI`_
|
||||
- `Activate Using EIM CLI`_
|
||||
|
||||
Activate Using EIM GUI
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: eim-gui-activate-env.rst
|
||||
|
||||
Activate Using EIM CLI
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Upon successful installation of ESP-IDF, the EIM places **shortcuts** on your desktop to launch a terminal with activated ESP-IDF environment.
|
||||
|
||||
For example, click the ``IDF_v5.4.2_Powershell`` shortcut to open a PowerShell session with the environment set up.
|
||||
|
||||
Once done, you have successfully activated the ESP-IDF environment in your terminal. All subsequent ESP-IDF commands should be run in this activated terminal.
|
||||
|
||||
|
||||
Start a Project
|
||||
===================
|
||||
@@ -24,6 +52,8 @@ Copy the project :example:`get-started/hello_world` to ``~/esp`` directory:
|
||||
|
||||
.. note:: There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. It is also possible to build examples in-place without copying them first.
|
||||
|
||||
.. _get-started-connect:
|
||||
|
||||
Connect Your Device
|
||||
===================
|
||||
|
||||
@@ -37,6 +67,8 @@ If you are not sure how to check the serial port name, please refer to :doc:`est
|
||||
|
||||
Keep the port name handy as it is needed in the next steps.
|
||||
|
||||
.. _get-started-configure:
|
||||
|
||||
Configure Your Project
|
||||
======================
|
||||
|
||||
@@ -90,3 +122,5 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
|
||||
``USB CDC``
|
||||
|
||||
3. Save the new configuration and exit the ``menuconfig`` screen.
|
||||
|
||||
.. include:: start-project.rst
|
||||
|
||||
@@ -51,4 +51,4 @@ The ``CONFIG_ESPTOOLPY_FLASHSIZE_DETECT`` option has been renamed to :ref:`CONFI
|
||||
Windows Environment
|
||||
--------------------
|
||||
|
||||
The Msys/Mingw-based Windows environment support got deprecated in ESP-IDF v4.0 and was entirely removed in v5.0. Please use :ref:`get-started-windows-tools-installer` to set up a compatible environment. The options include Windows Command Line, Power Shell and the graphical user interface based on Eclipse IDE. In addition, a VS Code-based environment can be set up with the supported plugin: https://github.com/espressif/vscode-esp-idf-extension.
|
||||
The Msys/Mingw-based Windows environment support got deprecated in ESP-IDF v4.0 and was entirely removed in v5.0. Please use the Windows Tools Installer (deprecated in ESP-IDF v6.0) to set up a compatible environment. The options include Windows Command Line, Power Shell and the graphical user interface based on Eclipse IDE. In addition, a VS Code-based environment can be set up with the supported plugin: https://github.com/espressif/vscode-esp-idf-extension.
|
||||
|
||||
@@ -107,14 +107,14 @@ hw-reference/esp32s2/usermacos-setup_mesh api-reference/network/esp-wifi-m
|
||||
hw-reference/chip-series-comparison "https://products.espressif.com/#/product-comparison"
|
||||
|
||||
# Getting Started
|
||||
get-started/macos-setup get-started/linux-macos-setup
|
||||
get-started/linux-setup get-started/linux-macos-setup
|
||||
get-started/linux-macos-setup get-started/index
|
||||
get-started/windows-setup-scratch get-started/windows-setup
|
||||
get-started/linux-setup-scratch get-started/linux-macos-setup
|
||||
get-started/macos-setup-scratch get-started/linux-macos-setup
|
||||
get-started/linux-setup-scratch get-started/linux-setup
|
||||
get-started/macos-setup-scratch get-started/macos-setup
|
||||
get-started/toolchain-setup-scratch get-started/index
|
||||
get-started/eclipse-setup get-started/index
|
||||
get-started/vscode-setup get-started/index
|
||||
get-started/windows-setup-update get-started/windows-setup
|
||||
|
||||
# Kconfig documentation got pretty serious file structure changes
|
||||
api-reference/kconfig api-reference/kconfig-reference
|
||||
|
||||
@@ -36,8 +36,35 @@
|
||||
配置 USB 驱动程序
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
JTAG 通信在所有支持的平台上都可工作。Windows 用户可能会遇到 `LIBUSB_ERROR_NOT_FOUND` 错误。请使用 2.8 版本（或更新版本）的 :ref:`get-started-windows-tools-installer`，并选择驱动程序 “Espressif - WinUSB 支持 JTAG (ESP32-C3/S3)” 以解决此问题。如果您不想重新运行安装程序，则可以通过 `idf-env <https://github.com/espressif/idf-env>`_ 实现相同的效果。请在 PowerShell 运行以下命令::
|
||||
JTAG 通信在所有支持的平台上都可工作。Windows 和 Linux 需要额外步骤，具体请参考以下说明。
|
||||
|
||||
Invoke-WebRequest 'https://dl.espressif.com/dl/idf-env/idf-env.exe' -OutFile .\idf-env.exe; .\idf-env.exe driver install --espressif
|
||||
Windows
|
||||
"""""""
|
||||
|
||||
Windows 用户可能会遇到 `LIBUSB_ERROR_NOT_FOUND` 错误，可使用以下任意方法安装驱动程序以解决此问题：
|
||||
|
||||
- 在 :doc:`ESP-IDF 安装管理器 (EIM) <../../get-started/windows-setup>` 图形用户界面 (GUI) ，点击 ``管理安装`` 下方的 ``打开管理面板``，之后点击 ``安装驱动程序``：
|
||||
|
||||
.. figure:: ../../../_static/jtag-debugging-install-usb-drivers-eim-zh.png
|
||||
:align: center
|
||||
:alt: 在 EIM GUI 中安装驱动程序
|
||||
:figclass: align-center
|
||||
|
||||
在 EIM GUI 中安装驱动程序
|
||||
|
||||
- 在 PowerShell 运行以下命令，通过 EIM 命令行安装驱动程序：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim install-drivers
|
||||
|
||||
- 在 PowerShell 运行以下命令，通过 `idf-env <https://github.com/espressif/idf-env>`_ 安装驱动程序：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Invoke-WebRequest 'https://dl.espressif.com/dl/idf-env/idf-env.exe' -OutFile .\idf-env.exe; .\idf-env.exe driver install --espressif
|
||||
|
||||
Linux
|
||||
"""""
|
||||
|
||||
在 Linux 上，需要添加 OpenOCD udev 规则。方法是将以下 `udev 规则文件 <https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules>`_ 放置在 ``/etc/udev/rules.d`` 文件夹中。
|
||||
|
||||
@@ -117,7 +117,7 @@ JTAG 调试
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
如果已经按照 :doc:`快速入门 <../../get-started/index>` 完成了 ESP-IDF 及其 CMake 构建系统的安装，那么 OpenOCD 已经被默认安装到了你的开发系统中。在 :ref:`设置开发环境 <get-started-set-up-env>` 结束后，应该能够在终端中运行如下 OpenOCD 命令：
|
||||
如果已经按照 :doc:`快速入门 <../../get-started/index>` 完成了 ESP-IDF 及其 CMake 构建系统的安装，那么 OpenOCD 已经被默认安装到了你的开发系统中。在 :ref:`Windows <get-started-set-up-env>`、:ref:`Linux 或 macOS 设置开发环境<get-started-set-up-env-linux-macos>` 结束后，应该能够在终端中运行如下 OpenOCD 命令：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -136,7 +136,7 @@ JTAG 调试
|
||||
|
||||
你还可以检查 ``OPENOCD_SCRIPTS`` 环境变量的值，以确认 OpenOCD 配置文件的路径，Linux 和 macOS 用户可以在终端输入 ``echo $OPENOCD_SCRIPTS``，Windows 用户需要输入 ``echo %OPENOCD_SCRIPTS%``。如果终端输出了有效路径，则表明已经正确安装 OpenOCD。
|
||||
|
||||
如果无法执行上述步骤，请再次阅读快速入门手册，Linux 和 macOS 用户请参考 :ref:`设置安装工具 <get-started-set-up-tools>` 章节，Windows 用户请参考 :ref:`ESP-IDF 工具安装器 <get-started-windows-tools-installer>`。
|
||||
如果无法执行上述步骤，请再次阅读快速入门的 :ref:`安装 <get-started-how-to-get-esp-idf>` 章节。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -178,7 +178,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
打开终端，按照《快速入门指南》中的 :ref:`设置开发环境 <get-started-set-up-env>` 章节进行操作。运行 OpenOCD 时，需要提供与目标开发板相关的配置文件。构建项目后，ESP-IDF 会生成 ``build/project_description.json`` 文件，其中 ``debug_arguments_openocd`` 字段保存了默认的 OpenOCD 配置信息。请运行如下命令，以启动 OpenOCD（该命令适用于 Windows、Linux 和 macOS）：
|
||||
打开终端，按照快速入门中:ref:`Windows <get-started-set-up-env>`、:ref:`Linux 或 macOS 设置开发环境 <get-started-set-up-env-linux-macos>` 章节进行操作。运行 OpenOCD 时，需要提供与目标开发板相关的配置文件。构建项目后，ESP-IDF 会生成 ``build/project_description.json`` 文件，其中 ``debug_arguments_openocd`` 字段保存了默认的 OpenOCD 配置信息。请运行如下命令，以启动 OpenOCD（该命令适用于 Windows、Linux 和 macOS）：
|
||||
|
||||
.. include:: {IDF_TARGET_PATH_NAME}.inc
|
||||
:start-after: run-openocd
|
||||
|
||||
@@ -63,7 +63,7 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设
|
||||
|
||||
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 默认没有使能。在所有任务堆栈的末尾设置观察点，从 1 号开始索引。这是调试任务堆栈溢出的最准确的方式。
|
||||
|
||||
更多有关设置编译时的选项的信息，请参阅 :ref:`项目配置菜单 <get-started-configure>`。
|
||||
更多有关设置编译时的选项的信息，请参阅 :ref:`Windows <get-started-configure>`、:ref:`Linux 或 macOS 项目配置菜单<get-started-configure-linux-macos>`。
|
||||
|
||||
.. _jtag-debugging-tip-freertos-support:
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ IDF 前端工具 - ``idf.py``
|
||||
- Ninja_ 用于构建工程。
|
||||
- `esptool`_ 用于烧录目标芯片。
|
||||
|
||||
:ref:`第五步：开始使用 ESP-IDF 吧 <get-started-configure>` 简要介绍了设置 ``idf.py`` 以配置、构建及烧录工程的操作流程。
|
||||
:ref:`Windows <get-started-configure>`、 :ref:`Linux 或 macOS 配置项目 <get-started-configure-linux-macos>` 中简要介绍了设置 ``idf.py`` 以配置、构建及烧录工程的操作流程。
|
||||
|
||||
.. important::
|
||||
|
||||
@@ -176,7 +176,7 @@ uf2 二进制文件也可以通过 :ref:`idf.py uf2 <generate-uf2-binary>` 生
|
||||
|
||||
命令 ``idf.py`` 支持 bash、zsh 和 fish shell 的 `shell 自动补全 <https://click.palletsprojects.com/shell-completion/>`_。
|
||||
|
||||
调用命令 ``export`` 为 ``idf.py`` 启用自动补全（:ref:`第四步：设置环境变量 <get-started-set-up-env>`），按 TAB 键启动自动补全。输入 ``idf.py -`` 并按 TAB 键以自动补全选项。
|
||||
调用命令 ``export`` 为 ``idf.py`` 启用自动补全（:ref:`Windows <get-started-set-up-env>`、:ref:`Linux 或 macOS 设置环境<get-started-set-up-env-linux-macos>`），按 TAB 键启动自动补全。输入 ``idf.py -`` 并按 TAB 键以自动补全选项。
|
||||
|
||||
预计未来版本将支持 PowerShell 自动补全。
|
||||
|
||||
|
||||
@@ -167,7 +167,7 @@ ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本，包
|
||||
|
||||
要为所有芯片目标安装工具，请在不使用任何可选参数的情况下，运行 ``idf_tools.py install --targets=all``。要安装具备 ESP-IDF 核心功能的 Python 软件包，请运行 ``idf_tools.py install-python-env --features=core``。
|
||||
|
||||
也可为特定芯片安装工具，例如，运行 ``install.sh esp32`` 可以只为 ESP32 安装工具。更多相关示例，请参阅 :ref:`第三步：设置工具 <get-started-set-up-tools>`。
|
||||
也可为特定芯片安装工具，例如，运行 ``install.sh esp32`` 可以只为 ESP32 安装工具。更多相关示例，请参阅 :ref:`第三步：设置工具 <get-started-set-up-tools-legacy>`。
|
||||
|
||||
运行 ``idf_tools.py install-python-env --features=core,XY``，``install.sh --enable-XY`` 可以启用 ``XY`` 功能。
|
||||
|
||||
@@ -208,7 +208,7 @@ activate.py
|
||||
|
||||
为适用于不同环境，ESP-IDF 提供了更多用户友好的 ``idf_tools.py`` 包装工具：
|
||||
|
||||
* :ref:`ESP-IDF 工具安装器 <get-started-windows-tools-installer>` 支持下载和安装工具，其内部使用 ``idf_tools.py`` 实现功能。
|
||||
* :ref:`ESP-IDF 安装管理器 <get-started-how-to-get-esp-idf>` 支持下载和安装工具，其内部使用 ``idf_tools.py`` 实现功能。
|
||||
* `ESP-IDF Eclipse 插件 <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ 包括了一个用于设置工具的菜单项，该插件内部调用 ``idf_tools.py``。
|
||||
* `VSCode ESP-IDF 扩展 <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_ 提供了设置工具的入门流程。尽管此扩展包不依赖 ``idf_tools.py``，但安装方法相同。
|
||||
|
||||
@@ -226,7 +226,7 @@ activate.py
|
||||
|
||||
卸载 ESP-IDF 需要删除安装过程中配置的工具和环境变量。
|
||||
|
||||
* 使用 :ref:`Windows ESP-IDF 工具安装器 <get-started-windows-tools-installer>` 的 Windows 用户可以直接运行卸载向导卸载 ESP-IDF。
|
||||
* 使用 :ref:`ESP-IDF 安装管理器 <get-started-how-to-get-esp-idf>` 的用户可以在图形用户界面 (GUI) 或命令行界面 (CLI) 中卸载 ESP-IDF。
|
||||
* :ref:`工具安装目录 <idf-tools-path>` 下包含了已下载及安装的工具，删除该目录即可删除此前通过运行 :ref:`安装脚本 <idf-tools-install>` 安装的内容。通过 :ref:`导出脚本 <idf-tools-export>` 设置的环境变量不具备永久性，新环境中不会存在此类环境变量。
|
||||
* 如在安装过程中进行了自定义设置，除删除上述工具外，可能还涉及手动恢复此前为适用 ESP-IDF 工具而修改的环境变量及系统路径，例如 ``IDF_PYTHON_ENV_PATH`` 或 ``IDF_TOOLS_PATH``。如存在通过手动复制安装的工具，则也需手动追踪并删除相关文件。
|
||||
* 如安装了 `ESP-IDF Eclipse <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ 或 `VSCode ESP-IDF 扩展程序 <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_ 等插件，则需按照对应插件文档中的特定卸载说明进行操作。
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
IDF Windows 安装程序
|
||||
===========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
命令行参数
|
||||
----------
|
||||
|
||||
IDF Windows 安装程序 ``esp-idf-tools-setup`` 提供以下命令行参数：
|
||||
|
||||
* ``/CONFIG=[PATH]`` - 指定 ``ini`` 配置文件的路径，覆盖安装程序的默认配置。默认值：``config.ini``。
|
||||
* ``/GITCLEAN=[yes|no]`` - 在以离线模式安装时，执行 ``git clean`` 命令，并删除未跟踪的目录。默认值：``yes``。
|
||||
* ``/GITRECURSIVE=[yes|no]`` - 递归克隆所有 Git 仓库子模块。默认值：``yes``。
|
||||
* ``/GITREPO=[URL|PATH]`` - 指定克隆 ESP-IDF 仓库的 URL。默认值：``https://github.com/espressif/esp-idf.git``。
|
||||
* ``/GITRESET=[yes|no]`` - 在安装过程中，启用或禁用对仓库的 ``git reset`` 操作。默认值：``yes``。
|
||||
* ``/HELP`` - 显示 Inno Setup 安装程序提供的命令行选项。
|
||||
* ``/IDFDIR=[PATH]`` - 指定安装目录的路径。默认值：``{userdesktop}\esp-idf}``。
|
||||
* ``/IDFVERSION=[v4.3|v4.1|master]`` - 使用指定的 ESP-IDF 版本，如 v4.1、v4.2、master。默认值：``empty``，选取列表中的第一个版本。
|
||||
* ``/IDFVERSIONSURL=[URL]`` - 使用 URL 下载 ESP-IDF 版本列表。默认值：``https://dl.espressif.com/dl/esp-idf/idf_versions.txt``。
|
||||
* ``/LOG=[PATH]`` - 在指定目录中存储安装日志文件。默认值：``empty``。
|
||||
* ``/OFFLINE=[yes|no]`` - 在离线模式下，使用 ``pip`` 执行。通过设置环境变量 ``PIP_NO_INDEX``，也可在离线模式下安装 Python 软件包。默认值：``no``。
|
||||
* ``/USEEMBEDDEDPYTHON=[yes|no]`` - 使用嵌入式 Python 版本完成安装。将此参数设置为 ``no``，可以在安装程序中选择 Python 版本。默认值：``yes``。
|
||||
* ``/PYTHONNOUSERSITE=[yes|no]`` - 在启动任意 Python 命令前，设置 ``PYTHONNOUSERSITE`` 变量，避免从 AppData\Roaming 加载 Python 软件包。默认值：``yes``。
|
||||
* ``/PYTHONWHEELSURL=[URL]`` - 指定 PyPi 存储库的 URL，以解析二进制 Python Wheel 依赖关系。设置环境变量 ``PIP_EXTRA_INDEX_URL`` 可以实现相同效果。默认值：``https://dl.espressif.com/pypi``。
|
||||
* ``/SKIPSYSTEMCHECK=[yes|no]`` - 跳过系统检查页面。默认值：``no``。
|
||||
* ``/VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL`` - 执行静默安装。
|
||||
|
||||
静默安装
|
||||
--------
|
||||
|
||||
通过设置以下命令行参数，可以静默安装 ESP-IDF：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
|
||||
|
||||
在命令行中运行安装程序时，它会在后台启动一个独立的进程执行安装操作，而不会阻塞命令行的使用。通过以下 PowerShell 脚本可以等待安装程序完成：
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
|
||||
$InstallerProcess = Get-Process esp-idf-tools-setup
|
||||
Wait-Process -Id $InstallerProcess.id
|
||||
|
||||
自定义 Python 版本及 Python Wheel 位置
|
||||
--------------------------------------------------
|
||||
|
||||
IDF 安装程序默认使用嵌入的 Python 版本，并参考预定义的 Python Wheel 镜像获取所需软件包。
|
||||
|
||||
以下参数支持自定义 Python 版本及 Python Wheel 位置：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /USEEMBEDDEDPYTHON=no /PYTHONWHEELSURL=https://pypi.org/simple/
|
||||
@@ -7,7 +7,6 @@
|
||||
idf-py
|
||||
idf-monitor
|
||||
idf-docker-image
|
||||
idf-windows-installer
|
||||
idf-component-manager
|
||||
idf-clang-tidy
|
||||
idf-tools
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
打开 ESP-IDF 安装管理器应用程序 `eim`。
|
||||
|
||||
在 ``管理安装`` 下，点击 ``打开仪表板``。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-zh.png
|
||||
:align: center
|
||||
:alt: EIM 管理安装
|
||||
|
||||
EIM 管理安装
|
||||
|
||||
在仪表板中，会看到所有已安装的 ESP-IDF 版本。选择要使用的版本，然后点击 ``打开 IDF 终端``，启动已激活 ESP-IDF 环境的终端。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-open-terminal-zh.png
|
||||
:align: center
|
||||
:alt: EIM 打开 IDF 终端
|
||||
|
||||
EIM 打开 IDF 终端
|
||||
@@ -0,0 +1,135 @@
|
||||
您可以使用以下任一方法安装 ESP-IDF 及其所需工具，具体取决于您的需求：
|
||||
|
||||
- `使用 EIM GUI 在线安装`_
|
||||
|
||||
适合大多数用户。通过图形用户界面安装 ESP-IDF 及其所需工具，需要网络连接。
|
||||
- `使用 EIM CLI 在线安装`_
|
||||
|
||||
通过命令行安装 ESP-IDF 及其所需工具，需要网络连接。
|
||||
- `使用已有配置文件在线安装`_
|
||||
|
||||
使用从其他电脑复制的配置文件安装 ESP-IDF 及其所需工具，适用于 GUI 和 CLI，但需要网络连接。
|
||||
- `离线安装`_
|
||||
|
||||
从本地包安装 ESP-IDF 及其所需工具，无需网络连接。
|
||||
|
||||
|
||||
使用 EIM GUI 在线安装
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
打开 ESP-IDF 安装管理器应用程序 `eim`。
|
||||
|
||||
之后，在 ``新安装`` 下点击 ``开始安装``。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-zh.png
|
||||
:align: center
|
||||
:alt: EIM 开始安装
|
||||
|
||||
EIM 开始安装
|
||||
|
||||
.. note::
|
||||
|
||||
如果之前未安装过 ESP-IDF，GUI 中不会显示 ``管理安装``，仅显示 ``新安装`` 选项。
|
||||
|
||||
在 ``简易安装`` 下，点击 ``开始简易安装``，使用默认设置安装最新稳定版本的 ESP-IDF。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-install-zh.png
|
||||
:align: center
|
||||
:alt: EIM 简易安装
|
||||
|
||||
EIM 简易安装
|
||||
|
||||
如果所有先决条件和路径检查都通过，将看到 ``准备安装`` 页面。点击 ``开始安装`` 以开始安装。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-ready-install-zh.png
|
||||
:align: center
|
||||
:alt: EIM 准备安装
|
||||
|
||||
EIM 准备安装
|
||||
|
||||
安装过程中，可以直接在界面中查看安装进度。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-installing-zh.png
|
||||
:align: center
|
||||
:alt: EIM 安装中
|
||||
|
||||
EIM 安装中
|
||||
|
||||
安装完成后，会出现 ``安装完成`` 页面。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-install-complete-zh.png
|
||||
:align: center
|
||||
:alt: EIM 安装完成
|
||||
|
||||
EIM 安装完成
|
||||
|
||||
如果安装失败，可以：
|
||||
|
||||
- 点击界面底部的 ``日志`` 查看错误详情。解决问题后，点击 ``重试`` 重新开始安装。
|
||||
- 或者，使用 `自定义安装 <https://docs.espressif.com/projects/idf-im-ui/en/latest/expert_installation.html>`_。
|
||||
|
||||
.. note::
|
||||
|
||||
- 如需选择 ESP-IDF 版本或自定义安装路径，请使用 ``自定义安装``。更多说明请参阅 `EIM 文档 > Expert Installations <https://docs.espressif.com/projects/idf-im-ui/en/latest/expert_installation.html>`__。
|
||||
- 如需管理现有安装，请参阅 `EIM 文档 > Version Management <https://docs.espressif.com/projects/idf-im-ui/en/latest/version_management.html>`__。
|
||||
|
||||
|
||||
使用 EIM CLI 在线安装
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
运行以下命令，在非交互模式下使用默认设置安装最新稳定版本的 ESP-IDF：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim install
|
||||
|
||||
如果运行上述命令时遇到问题，或者需要自定义安装路径、选择 ESP-IDF 版本或修改其他设置项，请启动交互式安装向导，并按照屏幕上的提示操作：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim wizard
|
||||
|
||||
如果安装向导中没有想要安装的 ESP-IDF 版本，请运行以下命令来安装任意可选 `版本 <https://docs.espressif.com/projects/esp-idf/zh_CN/stable/esp32/versions.html#releases>`__。例如，要安装 ESP-IDF v5.4.2，请运行：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim install -i v5.4.2
|
||||
|
||||
安装完成后，会在终端中看到以下消息：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
2025-11-03T15:54:12.537993300+08:00 - INFO - Wizard result: %{r}
|
||||
2025-11-03T15:54:12.544174+08:00 - INFO - Successfully installed IDF
|
||||
2025-11-03T15:54:12.545913900+08:00 - INFO - Now you can start using IDF tools
|
||||
|
||||
.. note::
|
||||
|
||||
- 要查看所有可用选项，请运行：
|
||||
.. code-block:: bash
|
||||
|
||||
eim --help
|
||||
- 有关 CLI 使用的更多信息，请参阅：
|
||||
|
||||
* `EIM 文档 > CLI Configuration <https://docs.espressif.com/projects/idf-im-ui/en/latest/cli_configuration.html>`__
|
||||
* `EIM 文档 > CLI Commands <https://docs.espressif.com/projects/idf-im-ui/en/latest/cli_commands.html>`__
|
||||
|
||||
|
||||
使用已有配置文件在线安装
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
安装 ESP-IDF 时，安装程序会自动将设置保存到安装目录下的 ``eim_config.toml`` 配置文件中。此配置文件可在其他电脑上重复使用，快速复现相同的安装环境。
|
||||
|
||||
如需使用现有 ``eim_config.toml`` 文件安装 ESP-IDF，请参阅 `EIM 文档 > Configuration Files <https://docs.espressif.com/projects/idf-im-ui/en/latest/gui_configuration.html#configuration-files>`__。
|
||||
|
||||
|
||||
离线安装
|
||||
~~~~~~~~
|
||||
|
||||
EIM 的图形用户界面和命令行界面均支持离线安装。具体操作请参阅 `EIM 文档 > Offline Installation <https://docs.espressif.com/projects/idf-im-ui/en/latest/offline_installation.html>`__。
|
||||
|
||||
|
||||
后续步骤
|
||||
==========
|
||||
|
||||
至此，您已准备就绪，可以使用 ESP-IDF 开发 ESP-IDF 应用程序了。接下来，请继续阅读 :ref:`get-started-build` 章节，学习如何构建和运行您的第一个应用程序。
|
||||
@@ -381,6 +381,6 @@ macOS 提供了 **屏幕** 命令，因此无需安装串口终端程序。
|
||||
|
||||
在某些串口接线方式下，在 {IDF_TARGET_NAME} 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 管脚。该问题仅存在于将 RTS ＆ DTR 管脚直接连接到 EN ＆ {IDF_TARGET_STRAP_GPIO} 管脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，请参考 `esptool 文档`_。
|
||||
|
||||
如在安装 {IDF_TARGET_NAME} 硬件开发的软件环境时，从 :ref:`get-started-connect` 跳转到了这里，请从 :ref:`get-started-configure` 继续阅读。
|
||||
如在安装 {IDF_TARGET_NAME} 硬件开发的软件环境时，从 :ref:`Windows <get-started-connect>`、:ref:`Linux 或 macOS 连接设备 <get-started-connect-linux-macos>` 跳转到了这里，请从 :ref:`Windows <get-started-configure>`、:ref:`Linux 或 macOS 配置项目 <get-started-configure-linux-macos>` 继续阅读。
|
||||
|
||||
.. _esptool 文档: https://docs.espressif.com/projects/esptool/en/latest/advanced-topics/boot-mode-selection.html#automatic-bootloader
|
||||
|
||||
@@ -127,21 +127,18 @@
|
||||
|
||||
ESP32-DevKitC <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-devkitc/index.html>
|
||||
ESP32-DevKitM-1 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-devkitm-1/index.html>
|
||||
ESP-WROVER-KIT <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp-wrover-kit/index.html>
|
||||
ESP32-PICO-KIT <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-pico-kit/index.html>
|
||||
ESP32-Ethernet-Kit <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-ethernet-kit/index.html>
|
||||
ESP32-PICO-KIT-1 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-pico-kit-1/index.html>
|
||||
ESP32-PICO-DevKitM-2 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-pico-devkitm-2/index.html>
|
||||
ESP32-LCDKit <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-lcdkit/index.html>
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ESP32-S2-Saola-1 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s2/esp32-s2-saola-1/index.html>
|
||||
ESP32-S2-DevKitM-1 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s2/esp32-s2-devkitm-1/index.html>
|
||||
ESP32-S2-DevKitC-1 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s2/esp32-s2-devkitc-1/index.html>
|
||||
ESP32-S2-Kaluga-Kit <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s2/esp32-s2-kaluga-1/index.html>
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
@@ -150,7 +147,7 @@
|
||||
|
||||
ESP32-C3-DevKitC-02 <https://docs.espressif.com/projects/espressif-esp-dev-kits/zh_CN/latest/esp32c3/esp32-c3-devkitc-02/index.html>
|
||||
ESP32-C3-DevKitM-1 <https://docs.espressif.com/projects/espressif-esp-dev-kits/zh_CN/latest/esp32c3/esp32-c3-devkitm-1/index.html>
|
||||
|
||||
ESP32-C3-LCDkit <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32c3/esp32-c3-lcdkit/index.html>
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
@@ -159,6 +156,10 @@
|
||||
|
||||
ESP32-S3-DevKitC-1 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s3/esp32-s3-devkitc-1/index.html>
|
||||
ESP32-S3-DevKitM-1 <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s3/esp32-s3-devkitm-1/index.html>
|
||||
ESP32-S3-USB-OTG <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s3/esp32-s3-usb-otg/index.html>
|
||||
ESP32-S3-LCD-EV-Board <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s3/esp32-s3-lcd-ev-board/index.html>
|
||||
EchoEar <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s3/echoear/index.html>
|
||||
ESP-DualKey <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s3/esp-dualkey/index.html>
|
||||
|
||||
.. only:: esp32c2
|
||||
|
||||
@@ -166,6 +167,7 @@
|
||||
:maxdepth: 1
|
||||
|
||||
ESP8684-DevKitM-1 <https://docs.espressif.com/projects/espressif-esp-dev-kits/zh_CN/latest/esp8684/esp8684-devkitm-1/index.html>
|
||||
ESP8684-DevKitC-02 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c2/esp8684-devkitc-02/index.html>
|
||||
|
||||
.. only:: esp32c5
|
||||
|
||||
@@ -208,39 +210,113 @@
|
||||
|
||||
.. _get-started-step-by-step:
|
||||
.. _get-started-how-to-get-esp-idf:
|
||||
.. _get-started-set-up-tools:
|
||||
|
||||
安装
|
||||
============
|
||||
====
|
||||
|
||||
为安装所需软件，乐鑫提供了以下方法，可根据需要选择其中之一。
|
||||
请使用 ESP-IDF 安装管理器 (EIM) 来安装 ESP-IDF、构建工具和相关工具链，该管理器支持多种操作系统。
|
||||
|
||||
IDE
|
||||
~~~~~~
|
||||
EIM 提供两种安装方式：
|
||||
|
||||
.. note:: 建议通过自己喜欢的集成开发环境 (IDE) 安装 ESP-IDF。
|
||||
|
||||
* `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_
|
||||
* `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/README_CN.md>`_
|
||||
|
||||
手动安装
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
请根据操作系统，选择对应的手动安装流程。
|
||||
- **图形用户界面 (GUI)**：用户友好，适合大多数用户。
|
||||
- **命令行界面 (CLI)**：适用于 CI/CD 流水线和自动化安装。
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Windows Installer <windows-setup>
|
||||
Linux and macOS <linux-macos-setup>
|
||||
windows-setup
|
||||
linux-setup
|
||||
macos-setup
|
||||
|
||||
编译第一个工程
|
||||
===================
|
||||
.. _get-started-build:
|
||||
|
||||
如果已经安装好 ESP-IDF，且没有使用集成开发环境 (IDE)，请在命令提示行中，按照 :ref:`在 Windows 中开始创建工程 <get-started-windows-first-steps>` 或 :ref:`在 Linux 和 macOS 中开始创建工程 <get-started-linux-macos-first-steps>` 编译第一个工程。
|
||||
构建首个项目
|
||||
============
|
||||
|
||||
安装 ESP-IDF 后，您可选择在集成开发环境 (IDE) 中或通过命令行来构建首个项目。
|
||||
|
||||
|
||||
在 IDE 中构建
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
通过 EIM 安装的 ESP-IDF 版本可搭配以下 IDE 使用，获得图形化开发体验：
|
||||
|
||||
- 基于 Eclipse CDT 的 `Espressif-IDE <https://docs.espressif.com/projects/espressif-ide/zh_CN/latest/>`_
|
||||
|
||||
该 IDE 已集成 IDF Eclipse 插件、必备 Eclipse CDT 插件和其他 Eclipse 平台插件，可支持 ESP-IDF 应用的开发和构建。
|
||||
- 安装 `ESP-IDF 拓展 <https://docs.espressif.com/projects/vscode-esp-idf-extension/zh_CN/latest/index.html>`_ 的 Visual Studio Code
|
||||
|
||||
通过安装拓展，您可直接在 Visual Studio Code 中开发、构建、烧录和监视 ESP-IDF 应用程序。
|
||||
|
||||
关于 IDE 的具体配置与使用方法，请参阅上述对应的文档。
|
||||
|
||||
|
||||
通过命令行构建
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
如果使用命令行构建项目、构建、烧录至 {IDF_TARGET_NAME}、监视设备输出，请根据您的操作系统参考以下说明：
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
windows-start-project
|
||||
linux-macos-start-project
|
||||
|
||||
.. note::
|
||||
|
||||
如果尚未安装 ESP-IDF，请跳转至 :ref:`get-started-step-by-step`，按照说明先安装所有必需的软件。
|
||||
|
||||
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
|
||||
|
||||
卸载 ESP-IDF
|
||||
=================
|
||||
============
|
||||
|
||||
如需卸载 ESP-IDF，请参考 :ref:`idf-tools-uninstall`。
|
||||
如需卸载通过 EIM 安装的 ESP-IDF 及相关工具，可使用图形用户界面 (GUI) 或命令行界面 (CLI) 两种方式。
|
||||
|
||||
使用 EIM GUI 卸载
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
启动 ESP-IDF 安装管理器。在 ``管理安装`` 下，点击 ``打开仪表板``。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-zh.png
|
||||
:align: center
|
||||
:alt: EIM 打开仪表板
|
||||
:figclass: align-center
|
||||
|
||||
EIM 打开仪表板
|
||||
|
||||
如需删除特定 ESP-IDF 版本，请在该版本下点击 ``移除`` 按键。
|
||||
|
||||
如果删除所有 ESP-IDF 版本，请点击页面底部的 ``清除所有`` 按键。
|
||||
|
||||
.. figure:: ../../_static/get-started-eim-gui-uninstall-zh.png
|
||||
:align: center
|
||||
:alt: EIM 卸载 ESP-IDF
|
||||
:figclass: align-center
|
||||
|
||||
EIM 卸载 ESP-IDF
|
||||
|
||||
使用 EIM CLI 卸载
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
如需删除特定 ESP-IDF 版本，例如 v5.4.2，请在终端中运行以下命令：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim uninstall v5.4.2
|
||||
|
||||
如需删除所有 ESP-IDF 版本，请在终端中运行以下命令：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
eim purge
|
||||
|
||||
|
||||
相关文档
|
||||
=========
|
||||
|
||||
* `ESP-IDF 安装管理器 (EIM) 文档 <https://docs.espressif.com/projects/idf-im-ui/en/latest/>`_
|
||||
* `Espressif-IDE (ESP-IDF Eclipse 插件) GitHub 仓库 <https://github.com/espressif/idf-eclipse-plugin/tree/master>`_
|
||||
* `VSCode ESP-IDF 扩展 GitHub 仓库 <https://github.com/espressif/vscode-esp-idf-extension/tree/master>`_
|
||||
|
||||
.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
|
||||
|
||||
+19
-41
@@ -1,9 +1,13 @@
|
||||
*********************************************
|
||||
Linux 和 macOS 平台工具链的标准设置
|
||||
*********************************************
|
||||
***********************************************
|
||||
Linux 和 macOS 平台工具链的标准设置（已过时）
|
||||
***********************************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. warning::
|
||||
|
||||
本章节描述了在 Linux 和 macOS 上安装 ESP-IDF v6.0 之前版本的默认方式。
|
||||
|
||||
详细安装步骤
|
||||
=========================
|
||||
|
||||
@@ -14,13 +18,12 @@ Linux 和 macOS 平台工具链的标准设置
|
||||
|
||||
以下是为 {IDF_TARGET_NAME} 设置 ESP-IDF 的具体步骤。
|
||||
|
||||
* :ref:`get-started-prerequisites`
|
||||
* :ref:`get-started-get-esp-idf`
|
||||
* :ref:`get-started-set-up-tools`
|
||||
* :ref:`get-started-set-up-env`
|
||||
* :ref:`get-started-start-a-project`
|
||||
* :ref:`get-started-prerequisites-legacy`
|
||||
* :ref:`get-started-get-esp-idf-legacy`
|
||||
* :ref:`get-started-set-up-tools-legacy`
|
||||
* :ref:`get-started-set-up-env-legacy`
|
||||
|
||||
.. _get-started-prerequisites:
|
||||
.. _get-started-prerequisites-legacy:
|
||||
|
||||
第一步：安装准备
|
||||
=============================
|
||||
@@ -116,7 +119,7 @@ Apple M1 用户
|
||||
|
||||
安装过程中，安装脚本 (install.sh) 会检查系统中已安装的 Python 版本，并在所有符合最低要求的版本中，选择最早的版本使用。
|
||||
|
||||
.. _get-started-get-esp-idf:
|
||||
.. _get-started-get-esp-idf-legacy:
|
||||
|
||||
第二步：获取 ESP-IDF
|
||||
=================================
|
||||
@@ -133,7 +136,7 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。
|
||||
|
||||
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
|
||||
|
||||
.. _get-started-set-up-tools:
|
||||
.. _get-started-set-up-tools-legacy:
|
||||
|
||||
第三步：设置工具
|
||||
=================================
|
||||
@@ -228,7 +231,7 @@ ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具，
|
||||
.. note::
|
||||
如未导出环境变量，大多数 shell 将不支持在变量赋值中使用 ``IDF_TOOLS_PATH``，例如 ``IDF_TOOLS_PATH="$HOME/required_idf_tools_path" ./install.sh``。因为即便在源脚本中导出或修改了该变量，当前的执行环境也不受变量赋值影响。
|
||||
|
||||
.. _get-started-set-up-env:
|
||||
.. _get-started-set-up-env-legacy:
|
||||
|
||||
第四步：设置环境变量
|
||||
=======================================
|
||||
@@ -263,32 +266,21 @@ ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具，
|
||||
|
||||
不建议直接将 ``export.sh`` 添加到 shell 的配置文件。这样做会导致在每个终端会话中都激活 IDF 虚拟环境（包括无需使用 ESP-IDF 的会话）。这违背了使用虚拟环境的目的，还可能影响其他软件的使用。
|
||||
|
||||
.. _get-started-start-a-project:
|
||||
.. _get-started-build:
|
||||
.. _get-started-configure:
|
||||
.. _get-started-connect:
|
||||
.. _get-started-linux-macos-first-steps:
|
||||
|
||||
第五步：开始使用 ESP-IDF 吧
|
||||
========================================
|
||||
|
||||
.. include:: linux-macos-start-project.rst
|
||||
.. include:: start-project.rst
|
||||
|
||||
.. _get-started-update-esp-idf:
|
||||
.. _get-started-update-esp-idf-legacy:
|
||||
|
||||
ESP-IDF 环境更新：升级 ESP-IDF 与 Python 软件包
|
||||
===================================================
|
||||
|
||||
乐鑫会不时推出新版本的 ESP-IDF，修复 bug 或提供新的功能。请注意，ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持期限满后，版本停止更新维护，用户可将项目升级到最新的 ESP-IDF 版本。更多关于支持期限的信息，请参考 :doc:`ESP-IDF 版本 <../versions>`。
|
||||
|
||||
因此，在使用时，也应注意更新本地版本。最简单的方法是：直接删除本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。
|
||||
因此，在使用时，也应注意更新本地版本。最简单的方法是：直接删除本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf-legacy` 中的指示，重新完成克隆。
|
||||
|
||||
另一种方法是仅更新变更的部分，具体方式请参阅 :ref:`更新 ESP-IDF <updating>` 章节。
|
||||
|
||||
为确保工具版本符合新 ESP-IDF 的要求，在更新 ESP-IDF 版本后，请在 ``$IDF_PATH`` 目录下重新运行 ``./install.sh`` 脚本。详细说明请参阅 :ref:`get-started-set-up-tools`。
|
||||
为确保工具版本符合新 ESP-IDF 的要求，在更新 ESP-IDF 版本后，请在 ``$IDF_PATH`` 目录下重新运行 ``./install.sh`` 脚本。详细说明请参阅 :ref:`get-started-set-up-tools-legacy`。
|
||||
|
||||
所有新工具安装完成后，请参考 :ref:`get-started-set-up-env`，运行导出脚本并进入 ESP-IDF 开发环境。
|
||||
所有新工具安装完成后，请参考 :ref:`get-started-set-up-env-legacy`，运行导出脚本并进入 ESP-IDF 开发环境。
|
||||
|
||||
ESP-IDF 环境更新：只升级 Python 软件包
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -299,20 +291,6 @@ ESP-IDF 的部分功能并非直接包含在主代码库中，而是由 ``esp-id
|
||||
|
||||
高级用户如需更灵活地控制更新流程，可参考 :ref:`idf-tools-py` 工具及 ``install-python-env`` 命令。此命令被安装脚本调用，专门用于创建或更新 ESP-IDF 环境。
|
||||
|
||||
相关文档
|
||||
=================
|
||||
|
||||
* :doc:`establish-serial-connection`
|
||||
* `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README_CN.md>`_
|
||||
* `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_
|
||||
* :doc:`../api-guides/tools/idf-monitor`
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
establish-serial-connection
|
||||
flashing-troubleshooting
|
||||
|
||||
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
|
||||
.. _First Steps on ESP-IDF: ../get-started/first-steps.html
|
||||
@@ -1,28 +1,73 @@
|
||||
现在你已经具备了使用 ESP-IDF 的所有条件，接下来将介绍如何开始第一个工程。
|
||||
*****************************************************
|
||||
在 Linux 或 macOS 上通过命令行构建项目
|
||||
*****************************************************
|
||||
|
||||
本指南将介绍如何初步上手 ESP-IDF，包括如何使用 {IDF_TARGET_NAME} 创建第一个工程，并构建、烧录和监控设备输出。
|
||||
本指南将介绍如何使用命令行在 {IDF_TARGET_NAME} 上创建新项目，构建、烧录和监控设备输出。
|
||||
|
||||
|
||||
.. _get-started-set-up-env-linux-macos:
|
||||
|
||||
激活环境
|
||||
========
|
||||
|
||||
.. note::
|
||||
|
||||
如果还未安装 ESP-IDF，请参照 :ref:`get-started-step-by-step` 中的步骤，获取使用本指南所需的所有软件。
|
||||
本章节描述了 ESP-IDF v6.0 及以上版本激活环境的默认和推荐步骤。如果您使用 :doc:`Linux 和 macOS 上的传统安装方法 <linux-macos-setup-legacy>`，请跳过本章节。
|
||||
|
||||
开始创建工程
|
||||
在使用 ESP-IDF 工具之前，需要先激活 ESP-IDF 开发环境。您可以通过图形用户界面 (GUI) 或命令行界面 (CLI) 两种方式来激活。
|
||||
|
||||
- `使用 EIM GUI 激活`_
|
||||
- `使用 EIM CLI 激活`_
|
||||
|
||||
使用 EIM GUI 激活
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: eim-gui-activate-env.rst
|
||||
|
||||
使用 EIM CLI 激活
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF 安装完成后，EIM 命令行界面会打印一条命令提示，该命令用于激活 ESP-IDF 环境，例如：
|
||||
|
||||
.. code-block:: bash
|
||||
:emphasize-lines: 6
|
||||
|
||||
You have successfully installed ESP-IDF
|
||||
for using the ESP-IDF tools inside the terminal, you will find activation scripts inside the base install folder
|
||||
sourcing the activation script will setup environment in the current terminal session
|
||||
============================================
|
||||
to activate the environment, run the following command in your terminal:
|
||||
source "/Users/username/.espressif/tools/activate_idf_v5.4.2.sh"
|
||||
============================================
|
||||
|
||||
在终端中运行上述高亮命令：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
source "/Users/username/.espressif/tools/activate_idf_v5.4.2.sh"
|
||||
|
||||
至此，您已成功在终端中激活 ESP-IDF 环境。后续所有 ESP-IDF 相关命令都需在已激活的终端中运行。
|
||||
|
||||
|
||||
开始创建项目
|
||||
================
|
||||
|
||||
现在，可以准备开发 {IDF_TARGET_NAME} 应用程序了。可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。
|
||||
现在，可以准备开发 {IDF_TARGET_NAME} 应用程序了。可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 项目开始。
|
||||
|
||||
.. important::
|
||||
|
||||
ESP-IDF 编译系统不支持 ESP-IDF 路径或其工程路径中带有空格。
|
||||
ESP-IDF 编译系统不支持 ESP-IDF 路径或其项目路径中带有空格。
|
||||
|
||||
将 :example:`get-started/hello_world` 工程复制至本地的 ``~/esp`` 目录下：
|
||||
将 :example:`get-started/hello_world` 项目复制至本地的 ``~/esp`` 目录下：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp
|
||||
cp -r $IDF_PATH/examples/get-started/hello_world .
|
||||
|
||||
.. note:: ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。
|
||||
.. note:: ESP-IDF 的 :idf:`examples` 目录下有一系列示例项目，可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。
|
||||
|
||||
.. _get-started-connect-linux-macos:
|
||||
|
||||
连接设备
|
||||
==============
|
||||
@@ -40,10 +85,12 @@
|
||||
|
||||
请记住串口名，以便后续使用。
|
||||
|
||||
配置工程
|
||||
.. _get-started-configure-linux-macos:
|
||||
|
||||
配置项目
|
||||
=============
|
||||
|
||||
请进入 ``hello_world`` 目录，设置 {IDF_TARGET_NAME} 为目标芯片，然后运行工程配置工具 ``menuconfig``。
|
||||
请进入 ``hello_world`` 目录，设置 {IDF_TARGET_NAME} 为目标芯片，然后运行项目配置工具 ``menuconfig``。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -51,15 +98,15 @@
|
||||
idf.py set-target {IDF_TARGET_PATH_NAME}
|
||||
idf.py menuconfig
|
||||
|
||||
打开一个新工程后，应首先使用 ``idf.py set-target {IDF_TARGET_PATH_NAME}`` 设置“目标”芯片。注意，此操作将清除并初始化项目之前的编译和配置（如有）。也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见 :ref:`selecting-idf-target`。
|
||||
打开一个新项目后，应首先使用 ``idf.py set-target {IDF_TARGET_PATH_NAME}`` 设置“目标”芯片。注意，此操作将清除并初始化项目之前的编译和配置（如有）。也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见 :ref:`selecting-idf-target`。
|
||||
|
||||
正确操作上述步骤后，系统将显示以下菜单：
|
||||
|
||||
.. figure:: ../../_static/project-configuration.png
|
||||
:align: center
|
||||
:alt: 工程配置 — 主窗口
|
||||
:alt: 项目配置 — 主窗口
|
||||
|
||||
工程配置 — 主窗口
|
||||
项目配置 — 主窗口
|
||||
|
||||
可以通过此菜单设置项目的具体变量，包括 Wi-Fi 网络名称、密码和处理器速度等。``hello_world`` 示例项目会以默认配置运行，因此在这一项目中，可以跳过使用 ``menuconfig`` 进行项目配置这一步骤。
|
||||
|
||||
@@ -93,3 +140,5 @@
|
||||
``USB CDC``
|
||||
|
||||
3. 保存设置，退出 ``menuconfig`` 界面。
|
||||
|
||||
.. include:: start-project.rst
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
************************************************
|
||||
在 Linux 上安装 ESP-IDF 及工具链
|
||||
************************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
本章节将介绍如何使用 ESP-IDF 安装管理器 (EIM) 在 Linux 发行版（例如 Ubuntu）上安装 ESP-IDF 及其所需工具。
|
||||
|
||||
.. note::
|
||||
|
||||
本章节描述了 ESP-IDF v6.0 及以上版本的默认和推荐安装方式。如使用 ESP-IDF v6.0 之前版本的默认安装方式，请参考 :doc:`Linux 上的传统安装方法 <linux-macos-setup-legacy>`。
|
||||
|
||||
|
||||
第一步：安装依赖包（可选）
|
||||
==========================
|
||||
|
||||
如计划通过 :ref:`APT <install-eim-linux-apt>` 安装 EIM，可跳过本步骤。
|
||||
|
||||
如使用其他方式安装 EIM，请根据 Linux 发行版安装相应的 `依赖包 <https://docs.espressif.com/projects/idf-im-ui/en/latest/prerequisites.html#linux>`_。
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-IDF 要求 Python 版本至少为 3.10。
|
||||
|
||||
但如需使用 EIM 进行 `离线安装 <https://docs.espressif.com/projects/idf-im-ui/en/latest/offline_installation.html>`_，则必须使用 **Python 3.11 或更高版本**。
|
||||
|
||||
|
||||
第二步：安装 EIM
|
||||
=================
|
||||
|
||||
您可以使用以下任一方法安装 EIM：
|
||||
|
||||
- `通过 APT 安装（Debian 发行版）`_
|
||||
- `通过 DNF 安装（RPM 发行版）`_
|
||||
- `下载 EIM 安装包`_
|
||||
|
||||
通过 APT 或 DNF 安装 EIM 便于后续升级更新。
|
||||
|
||||
|
||||
.. _install-eim-linux-apt:
|
||||
|
||||
通过 APT 安装（Debian 发行版）
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
将 EIM 仓库添加到 APT 源列表，以便后续使用 APT 安装 EIM：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
echo "deb [trusted=yes] https://dl.espressif.com/dl/eim/apt/ stable main" | sudo tee /etc/apt/sources.list.d/espressif.list
|
||||
|
||||
sudo apt update
|
||||
|
||||
然后，通过 APT 安装 EIM 的命令行界面 (CLI) 和图形用户界面 (GUI)，或仅安装命令行界面 (CLI)：
|
||||
|
||||
- GUI 和 CLI：
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt install eim
|
||||
|
||||
- 仅 CLI：
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt install eim-cli
|
||||
|
||||
|
||||
通过 DNF 安装（RPM 发行版）
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
将 EIM 仓库添加到 DNF 源列表，以便后续使用 DNF 安装 EIM：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo tee /etc/yum.repos.d/espressif-eim.repo << 'EOF'
|
||||
[eim]
|
||||
name=ESP-IDF Installation Manager
|
||||
baseurl=https://dl.espressif.com/dl/eim/rpm/$basearch
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
EOF
|
||||
|
||||
然后，通过 DNF 安装 EIM 的命令行界面 (CLI) 和图形用户界面 (GUI)，或仅安装命令行界面 (CLI)：
|
||||
|
||||
- GUI 和 CLI：
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dnf install eim
|
||||
|
||||
- 仅 CLI：
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dnf install eim-cli
|
||||
|
||||
|
||||
下载 EIM 安装包
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
您也可以从 `Espressif 下载页面 <https://dl.espressif.com/dl/eim/>`__ 下载适用于 Linux 的 EIM 安装包，该页面提供了 CLI 和 GUI 版本的在线和离线安装程序。
|
||||
|
||||
|
||||
第三步：使用 EIM 安装 ESP-IDF
|
||||
=================================
|
||||
|
||||
.. include:: eim-install-idf.rst
|
||||
@@ -0,0 +1,68 @@
|
||||
************************************************
|
||||
在 macOS 上安装 ESP-IDF 及工具链
|
||||
************************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
本章节将介绍如何使用 ESP-IDF 安装管理器 (EIM) 在 macOS 上安装 ESP-IDF 及其所需工具。
|
||||
|
||||
.. note::
|
||||
|
||||
本章节描述了 ESP-IDF v6.0 及以上版本的默认和推荐安装方式。如使用 ESP-IDF v6.0 之前版本的默认安装方式，请参考 :doc:`macOS 上的传统安装方法 <linux-macos-setup-legacy>`。
|
||||
|
||||
|
||||
第一步：安装依赖包
|
||||
====================
|
||||
|
||||
通过 `Homebrew <https://brew.sh/>`__ 安装所需的依赖包：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
brew install libgcrypt glib pixman sdl2 libslirp dfu-util cmake python
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-IDF 要求 Python 版本至少为 3.10。
|
||||
|
||||
但如需使用 EIM 进行 `离线安装 <https://docs.espressif.com/projects/idf-im-ui/en/latest/offline_installation.html>`_，则必须使用 **Python 3.11 或更高版本**。
|
||||
|
||||
|
||||
第二步：安装 EIM
|
||||
=======================
|
||||
|
||||
将 EIM 仓库添加到 Homebrew 中，以便后续使用 Homebrew 安装 EIM：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
brew tap espressif/eim
|
||||
|
||||
然后，通过 Homebrew 安装 EIM 的图形用户界面 (GUI) 或命令行界面 (CLI)：
|
||||
|
||||
- GUI：
|
||||
.. code-block:: bash
|
||||
|
||||
brew install --cask eim-gui
|
||||
|
||||
- CLI：
|
||||
.. code-block:: bash
|
||||
|
||||
brew install eim
|
||||
|
||||
.. note::
|
||||
|
||||
通过 Homebrew 安装 EIM 便于后续升级更新。
|
||||
|
||||
您也可以从 `Espressif 下载页面 <https://dl.espressif.com/dl/eim/>`__ 下载适用于 macOS 的 EIM 安装包，该页面提供了 CLI 和 GUI 版本的在线和离线安装程序。
|
||||
|
||||
|
||||
第三步：使用 EIM 安装 ESP-IDF
|
||||
==============================
|
||||
|
||||
.. include:: eim-install-idf.rst
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
:caption: Legacy Installation
|
||||
|
||||
linux-macos-setup-legacy
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
{IDF_TARGET_HEAP_SIZE:default="[NEEDS TO BE UPDATED]", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c2="203888", esp32c3="337332", esp32c6="473816", esp32h2="268256", esp32p4="618848", esp32c5="348724"}
|
||||
|
||||
编译工程
|
||||
编译项目
|
||||
=========================
|
||||
|
||||
请使用以下命令，编译烧录工程：
|
||||
请使用以下命令，编译烧录项目：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
@@ -54,7 +54,7 @@
|
||||
|
||||
.. note::
|
||||
|
||||
勾选 ``flash`` 选项将自动编译并烧录工程，因此无需再运行 ``idf.py build``。
|
||||
勾选 ``flash`` 选项将自动编译并烧录项目，因此无需再运行 ``idf.py build``。
|
||||
|
||||
若在烧录过程中遇到问题，请参考下文中的“其他提示”。也可以前往 :doc:`flashing-troubleshooting` 或 :doc:`establish-serial-connection` 获取更多详细信息。
|
||||
|
||||
@@ -73,7 +73,7 @@
|
||||
监视输出
|
||||
===============
|
||||
|
||||
可以使用 ``idf.py -p PORT monitor`` 命令，监视 “hello_world” 工程的运行情况。注意，不要忘记将 PORT 替换为自己的串口名称。
|
||||
可以使用 ``idf.py -p PORT monitor`` 命令，监视 “hello_world” 项目的运行情况。注意，不要忘记将 PORT 替换为自己的串口名称。
|
||||
|
||||
运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动。
|
||||
|
||||
@@ -222,3 +222,17 @@ ESP-IDF 支持擦除 flash。请运行以下命令，擦除整个 flash：
|
||||
idf.py -p PORT erase-otadata
|
||||
|
||||
擦除 flash 需要一段时间，在擦除过程中，请勿断开设备连接。
|
||||
|
||||
|
||||
相关文档
|
||||
========
|
||||
|
||||
* :doc:`establish-serial-connection`
|
||||
* :doc:`../api-guides/tools/idf-monitor`
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
establish-serial-connection
|
||||
flashing-troubleshooting
|
||||
|
||||
+5
-1
@@ -1,9 +1,13 @@
|
||||
*************************************************
|
||||
在 Windows 环境下更新 ESP-IDF 工具
|
||||
在 Windows 环境下更新 ESP-IDF 工具（已过时）
|
||||
*************************************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. warning::
|
||||
|
||||
本章节描述了 ESP-IDF v6.0 版本之前更新 ESP-IDF 工具的默认方式。
|
||||
|
||||
.. _get-started-install_bat-windows:
|
||||
|
||||
使用脚本安装 ESP-IDF 工具
|
||||
@@ -1,142 +1,46 @@
|
||||
***********************************************
|
||||
Windows 平台工具链的标准设置
|
||||
***********************************************
|
||||
************************************************
|
||||
在 Windows 上安装 ESP-IDF 及工具链
|
||||
************************************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
概述
|
||||
============
|
||||
|
||||
ESP-IDF 需要安装一些必备工具，才能围绕 {IDF_TARGET_NAME} 构建固件，包括 Python、Git、交叉编译器、CMake 和 Ninja 编译工具等。
|
||||
|
||||
本入门指南介绍了如何通过 **命令提示符** 进行有关操作。不过，安装 ESP-IDF 后，还可以使用 `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README_CN.md>`_ 或其他支持 CMake 的图形化工具 IDE。
|
||||
本章节将介绍如何使用 ESP-IDF 安装管理器 (EIM) 在 Windows 上安装 ESP-IDF 及其所需工具。
|
||||
|
||||
.. note::
|
||||
|
||||
限定条件：
|
||||
|
||||
- 请注意 ESP-IDF 和 ESP-IDF 工具的安装路径不能超过 90 个字符，安装路径过长可能会导致构建失败。
|
||||
- Python 或 ESP-IDF 的安装路径中一定不能包含空格或括号。
|
||||
- 除非操作系统配置为支持 Unicode UTF-8，否则 Python 或 ESP-IDF 的安装路径中也不能包括特殊字符（非 ASCII 码字符）
|
||||
|
||||
系统管理员可以通过如下方式将操作系统配置为支持 Unicode UTF-8：``Control Panel`` > 更改 ``date``、``time``、或 ``number`` 格式 > ``Administrative tab`` > 更改 ``system locale`` > 勾选选项 ``Beta: Use Unicode UTF-8 for worldwide language support`` > ``Ok`` > 重启电脑。
|
||||
|
||||
.. _get-started-windows-tools-installer:
|
||||
|
||||
ESP-IDF 工具安装器
|
||||
=======================
|
||||
|
||||
安装 ESP-IDF 必备工具最简易的方式是下载一个 ESP-IDF 工具安装器。
|
||||
|
||||
+-------------------+--------------------------------+
|
||||
| |download-logo| | `Windows Installer Download`_ |
|
||||
+-------------------+--------------------------------+
|
||||
|
||||
.. |download-logo| image:: ../../_static/logo_windows_install.png
|
||||
:target: https://dl.espressif.com/dl/esp-idf/?idf=4.4
|
||||
|
||||
.. _Windows Installer Download: https://dl.espressif.com/dl/esp-idf/?idf=4.4
|
||||
本章节描述了 ESP-IDF v6.0 及以上版本的默认和推荐安装方式。ESP-IDF 仍支持 :doc:`Windows 上更新 ESP-IDF 的传统方法 <windows-setup-update-legacy>`。
|
||||
|
||||
|
||||
在线安装与离线安装的区别
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
在线安装程序非常小，可以安装 ESP-IDF 的所有版本。在安装过程中，安装程序只下载必要的依赖文件，包括 `Git For Windows`_ 安装器。在线安装程序会将下载的文件存储在缓存目录 ``%userprofile%/espressif`` 中。
|
||||
|
||||
离线安装程序不需要任何网络连接。安装程序中包含了所有需要的依赖文件，包括 `Git For Windows`_ 安装器。
|
||||
|
||||
安装内容
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
安装程序会安装以下组件：
|
||||
|
||||
- 内置的 Python
|
||||
- 交叉编译器
|
||||
- OpenOCD
|
||||
- CMake_ 和 Ninja_ 编译工具
|
||||
- ESP-IDF
|
||||
|
||||
安装程序允许将程序下载到现有的 ESP-IDF 目录。推荐将 ESP-IDF 下载到 ``%userprofile%\Desktop\esp-idf`` 目录下，其中 ``%userprofile%`` 代表家目录。
|
||||
|
||||
启动 ESP-IDF 环境
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
安装结束时，如果勾选了 ``Run ESP-IDF PowerShell Environment`` 或 ``Run ESP-IDF Command Prompt (cmd.exe)``，安装程序会在选定的提示符窗口启动 ESP-IDF。
|
||||
|
||||
``Run ESP-IDF PowerShell Environment``:
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-screenshot-powershell.png
|
||||
:align: center
|
||||
:alt: 完成 ESP-IDF 工具安装向导时运行 Run ESP-IDF PowerShell Environment
|
||||
:figclass: align-center
|
||||
|
||||
完成 ESP-IDF 工具安装向导时运行 Run ESP-IDF PowerShell Environment
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-powershell.png
|
||||
:align: center
|
||||
:alt: ESP-IDF PowerShell
|
||||
:figclass: align-center
|
||||
|
||||
ESP-IDF PowerShell
|
||||
|
||||
``Run ESP-IDF Command Prompt (cmd.exe)``:
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-screenshot.png
|
||||
:align: center
|
||||
:alt: 完成 ESP-IDF 工具安装向导时运行 Run ESP-IDF Command Prompt (cmd.exe)
|
||||
:figclass: align-center
|
||||
|
||||
完成 ESP-IDF 工具安装向导时运行 Run ESP-IDF Command Prompt (cmd.exe)
|
||||
|
||||
.. figure:: ../../_static/esp-idf-installer-command-prompt.png
|
||||
:align: center
|
||||
:alt: ESP-IDF 命令提示符窗口
|
||||
:figclass: align-center
|
||||
|
||||
ESP-IDF 命令提示符窗口
|
||||
|
||||
使用命令提示符
|
||||
========================
|
||||
|
||||
在后续步骤中，将介绍如何使用 Windows 的命令提示符进行操作。
|
||||
|
||||
ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF 命令提示符窗口的快捷方式。本快捷方式可以打开 Windows 命令提示符（即 cmd.exe），并运行 ``export.bat`` 脚本以设置各环境变量（比如 ``PATH``，``IDF_PATH`` 等）。此外，还可以通过 Windows 命令提示符使用各种已经安装的工具。
|
||||
|
||||
注意，本快捷方式仅适用 ESP-IDF 工具安装器中指定的 ESP-IDF 路径。如果电脑上存在多个 ESP-IDF 路径（比如需要不同版本的 ESP-IDF），有以下两种解决方法：
|
||||
|
||||
1. 为 ESP-IDF 工具安装器创建的快捷方式创建一个副本，并将新快捷方式的 ESP-IDF 工作路径指定为希望使用的 ESP-IDF 路径。
|
||||
|
||||
2. 或者，可以运行 ``cmd.exe``，并切换至希望使用的 ESP-IDF 目录，然后运行 ``export.bat``。注意，这种方法要求 ``PATH`` 中存在 Python 和 Git。如果在使用时遇到有关“找不到 Python 或 Git”的错误信息，请使用第一种方法。
|
||||
|
||||
开始使用 ESP-IDF
|
||||
========================
|
||||
|
||||
.. _get-started-windows-first-steps:
|
||||
|
||||
.. include:: windows-start-project.rst
|
||||
.. include:: start-project.rst
|
||||
|
||||
相关文档
|
||||
第一步：安装 EIM
|
||||
=================
|
||||
|
||||
想要自定义安装流程的高阶用户可参照：
|
||||
通过 `WinGet <https://learn.microsoft.com/en-us/windows/package-manager/winget/>`__ 安装 EIM 的图形用户界面 (GUI) 或命令行界面 (CLI)：
|
||||
|
||||
* :doc:`windows-setup-update`
|
||||
* :doc:`establish-serial-connection`
|
||||
* `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README_CN.md>`_
|
||||
* `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_
|
||||
* :doc:`../api-guides/tools/idf-monitor`
|
||||
- GUI:
|
||||
.. code-block:: bash
|
||||
|
||||
winget install Espressif.EIM
|
||||
|
||||
- CLI:
|
||||
.. code-block:: bash
|
||||
|
||||
winget install Espressif.EIM-CLI
|
||||
|
||||
.. note::
|
||||
|
||||
通过 WinGet 安装 EIM 便于后续升级更新。
|
||||
|
||||
您也可以从 `Espressif 下载页面 <https://dl.espressif.com/dl/eim/>`__ 下载适用于 Windows 的 EIM 安装包，该页面提供了 CLI 和 GUI 版本的在线和离线安装程序。
|
||||
|
||||
|
||||
第二步：使用 EIM 安装 ESP-IDF
|
||||
==============================
|
||||
|
||||
.. include:: eim-install-idf.rst
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
:caption: Legacy Installation
|
||||
|
||||
windows-setup-update
|
||||
establish-serial-connection
|
||||
flashing-troubleshooting
|
||||
|
||||
.. _CMake: https://cmake.org/download/
|
||||
.. _Ninja: https://ninja-build.org/
|
||||
.. _Python: https://www.python.org/downloads/windows/
|
||||
.. _Git for Windows: https://gitforwindows.org/
|
||||
.. _Github Desktop: https://desktop.github.com/
|
||||
windows-setup-update-legacy
|
||||
|
||||
@@ -1,28 +1,58 @@
|
||||
现在你已经具备了使用 ESP-IDF 的所有条件，接下来将介绍如何开始第一个工程。
|
||||
********************************************
|
||||
在 Windows 上通过命令行构建项目
|
||||
********************************************
|
||||
|
||||
本指南将介绍如何初步上手 ESP-IDF，包括如何使用 {IDF_TARGET_NAME} 创建第一个工程，并构建、烧录和监控设备输出。
|
||||
本指南将介绍如何使用命令行在 Windows 上创建 {IDF_TARGET_NAME} 项目，构建、烧录和监控设备输出。
|
||||
|
||||
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
激活环境
|
||||
=========
|
||||
|
||||
.. note::
|
||||
|
||||
如果还未安装 ESP-IDF，请参照 :ref:`get-started-step-by-step` 中的步骤，获取使用本指南所需的所有软件。
|
||||
本章节描述了 ESP-IDF v6.0 及以上版本激活环境的默认和推荐步骤。如使用 :doc:`Windows 上更新 ESP-IDF 工具的传统方法 <windows-setup-update-legacy>`，可跳过本章节。
|
||||
|
||||
开始创建工程
|
||||
在使用 ESP-IDF 工具之前，需要先激活 ESP-IDF 开发环境。您可以通过图形用户界面 (GUI) 或命令行界面 (CLI) 两种方式来激活。
|
||||
|
||||
- `使用 EIM GUI 激活`_
|
||||
- `使用 EIM CLI 激活`_
|
||||
|
||||
使用 EIM GUI 激活
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: eim-gui-activate-env.rst
|
||||
|
||||
使用 EIM CLI 激活
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF 安装完成后，EIM 会在桌面上创建 **快捷方式**，用于启动已激活 ESP-IDF 环境的终端。
|
||||
|
||||
例如，点击 ``IDF_v5.4.2_Powershell`` 快捷方式，打开已设置好环境的 PowerShell 终端。
|
||||
|
||||
至此，您已成功在终端中激活 ESP-IDF 环境。后续所有 ESP-IDF 相关命令都需在已激活的终端中运行。
|
||||
|
||||
|
||||
开始创建项目
|
||||
================
|
||||
|
||||
现在，可以准备开发 {IDF_TARGET_NAME} 应用程序了。可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。
|
||||
现在，可以准备开发 {IDF_TARGET_NAME} 应用程序了。可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 项目开始。
|
||||
|
||||
.. important::
|
||||
|
||||
ESP-IDF 编译系统不支持 ESP-IDF 路径或其工程路径中带有空格。
|
||||
ESP-IDF 编译系统不支持 ESP-IDF 路径或其项目路径中带有空格。
|
||||
|
||||
将 :example:`get-started/hello_world` 工程复制至本地的 ``~/esp`` 目录下：
|
||||
将 :example:`get-started/hello_world` 项目复制至本地的 ``~/esp`` 目录下：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
cd %userprofile%\esp
|
||||
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
|
||||
|
||||
.. note:: ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。
|
||||
.. note:: ESP-IDF 的 :idf:`examples` 目录下有一系列示例项目，可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。
|
||||
|
||||
.. _get-started-connect:
|
||||
|
||||
连接设备
|
||||
==============
|
||||
@@ -37,10 +67,12 @@
|
||||
|
||||
请记住串口名，以便后续使用。
|
||||
|
||||
配置工程
|
||||
.. _get-started-configure:
|
||||
|
||||
配置项目
|
||||
=============
|
||||
|
||||
请进入 ``hello_world`` 目录，设置 {IDF_TARGET_NAME} 为目标芯片，然后运行工程配置工具 ``menuconfig``。
|
||||
请进入 ``hello_world`` 目录，设置 {IDF_TARGET_NAME} 为目标芯片，然后运行项目配置工具 ``menuconfig``。
|
||||
|
||||
Windows
|
||||
~~~~~~~
|
||||
@@ -51,15 +83,15 @@ Windows
|
||||
idf.py set-target {IDF_TARGET_PATH_NAME}
|
||||
idf.py menuconfig
|
||||
|
||||
打开一个新工程后，应首先使用 ``idf.py set-target {IDF_TARGET_PATH_NAME}`` 设置“目标”芯片。注意，此操作将清除并初始化项目之前的编译和配置（如有）。也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见 :ref:`selecting-idf-target`。
|
||||
打开一个新项目后，应首先使用 ``idf.py set-target {IDF_TARGET_PATH_NAME}`` 设置“目标”芯片。注意，此操作将清除并初始化项目之前的编译和配置（如有）。也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见 :ref:`selecting-idf-target`。
|
||||
|
||||
正确操作上述步骤后，系统将显示以下菜单：
|
||||
|
||||
.. figure:: ../../_static/project-configuration.png
|
||||
:align: center
|
||||
:alt: 工程配置 — 主窗口
|
||||
:alt: 项目配置 — 主窗口
|
||||
|
||||
工程配置 — 主窗口
|
||||
项目配置 — 主窗口
|
||||
|
||||
可以通过此菜单设置项目的具体变量，包括 Wi-Fi 网络名称、密码和处理器速度等。``hello_world`` 示例项目会以默认配置运行，因此在这一项目中，可以跳过使用 ``menuconfig`` 进行项目配置这一步骤。
|
||||
|
||||
@@ -90,3 +122,5 @@ Windows
|
||||
``USB CDC``
|
||||
|
||||
3. 保存设置，退出 ``menuconfig`` 界面。
|
||||
|
||||
.. include:: start-project.rst
|
||||
|
||||
@@ -51,4 +51,4 @@ Esptool
|
||||
Windows 环境
|
||||
-------------
|
||||
|
||||
基于 MSYS/MinGW 的 Windows 环境支持已在 ESP-IDF v4.0 中弃用，v5.0 则完全移除了该项服务。请使用 :ref:`get-started-windows-tools-installer` 设置 Windows 兼容环境。目前支持 Windows 命令行、Power Shell 和基于 Eclipse IDE 的图形用户界面等选项。此外，还可以使用 `支持的插件 <https://github.com/espressif/vscode-esp-idf-extension>`_，设置基于 VSCode 的环境。
|
||||
基于 MSYS/MinGW 的 Windows 环境支持已在 ESP-IDF v4.0 中弃用，v5.0 则完全移除了该项服务。请使用 ESP-IDF 工具安装器（ESP-IDF v6.0 已弃用）设置 Windows 兼容环境。目前支持 Windows 命令行、Power Shell 和基于 Eclipse IDE 的图形用户界面等选项。此外，还可以使用 `支持的插件 <https://github.com/espressif/vscode-esp-idf-extension>`_，设置基于 VSCode 的环境。
|
||||
|
||||
Reference in New Issue
Block a user