mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-03 03:31:41 +03:00
docs: updated get started for EIM
This commit is contained in:
Wang Ning
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user