+++ /dev/null
-:orphan:
-
-.. Remove this file when the Chinese translation of getting started guide is updated
+++ /dev/null
-在用户配置文件中添加 IDF_PATH 和 idf.py PATH
-==========================================================================================================
-
-:link_to_translation:`en:[英文]`
-
-使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量：
-
-- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径
-- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录
-
-为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。
-
-.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。
-
-.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。
-
-.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。
-
-.. _add-paths-to-profile-windows:
-
-Windows 操作系统
------------------------------------
-
-在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。
-
-在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。
-
-你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。
-
-- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。
-- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。
-
-如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。
-
-
-.. _add-idf_path-to-profile-linux-macos:
-
-Linux 和 MacOS 操作系统
-------------------------------------
-
-要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中::
-
- export IDF_PATH=~/esp/esp-idf
- export PATH="$IDF_PATH/tools:$PATH"
-
-.. note::
-
- ``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。
-
-请退出，并重新登录使更改生效。
-
-.. note::
-
- 并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。
-
-运行以下命令来检查 ``IDF_PATH`` 设置是否正确::
-
- printenv IDF_PATH
-
-此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。
-
-为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令::
-
- which idf.py
-
-这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。
-
-如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入::
-
- export IDF_PATH=~/esp/esp-idf
- export PATH="$IDF_PATH/tools:$PATH"
-
-如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。
:link_to_translation:`en:[English]`
-有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。
+ESP-IDF V4.0 将默认采用基于 CMake 的编译系统。
-.. _eclipse.org: https://www.eclipse.org/
+对此，我们还推出了针对 CMake 编译系统的新 ESP-IDF Eclipse 插件。具体操作，请见 `ESP-IDF Eclipse 插件 <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`。
+
+如您仍需要对传统 GNU Make 编译系统的 Eclipse 支持，请前往 :doc:`传统 GNU Make 编译系统入门指南 </get-started-legacy/index>`，查看 :doc:`使用 Eclipse IDE 进行编译与烧录 </get-started-legacy/eclipse-setup>` 章节。
\ No newline at end of file
-*******************
-快速入门（CMake）
-*******************
+***********
+快速入门
+***********
:link_to_translation:`en:[English]`
-本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，
-
-通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。
+本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。
.. include:: /_build/inc/version-note.inc
概述
-====
+============
ESP32 SoC 芯片支持以下功能：
* 2.4 GHz Wi-Fi
-* 蓝牙 4.2 标准
+* 蓝牙 4.2
* 高性能双核
* 超低功耗协处理器
* 多种外设
乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。
准备工作
-========
+=============
硬件：
* 一款 **ESP32** 开发板
-* **USB 数据线** （USB A/Micro USB B）
+* **USB 数据线** (A 转 Micro-B)
* PC（Windows、Linux 或 Mac OS）
软件：
* 设置 **工具链**，用于编译 ESP32 代码；
-* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**；
+* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**；
* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本；
* 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse <https://www.eclipse.org/>`_。
开发板简介
-==========
+===========================
请点击下方连接，了解有关具体开发板的详细信息。
.. _get-started-step-by-step:
详细安装步骤
-==============
+=========================
请根据下方详细步骤，完成安装过程。
设置开发环境
-~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* :ref:`get-started-setup-toolchain`
+* :ref:`get-started-get-prerequisites` （:doc:`Windows <windows-setup>` 、:doc:`Linux <linux-setup>` 和 :doc:`macOS <macos-setup>`）
* :ref:`get-started-get-esp-idf`
-* :ref:`get-started-setup-path`
-* :ref:`get-started-get-packages`
+* :ref:`get-started-set-up-tools`
+* :ref:`get-started-set-up-env`
创建您的第一个工程
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-build-monitor`
-.. _get-started-setup-toolchain:
+.. _get-started-get-prerequisites:
-第一步：设置工具链
-====================
+第一步：安装准备
+=============================
-工具链指一套用于编译代码和应用程序的程序。
-
-为了加快开发进度，您可以直接使用乐鑫提供的预制工具链。请根据您的操作系统，点击下方对应的链接，并按照链接中的指导进行安装。
+在正式开始创建工程前，请先完成工具的安装，具体步骤见下：
.. toctree::
:hidden:
.. _Linux: ../get-started/linux-setup.html
.. _Mac OS: ../get-started/macos-setup.html
-.. note::
-
- 在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。
-
-此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置<get-started-customized-setup>` 章节获取更多信息。
-
-
.. _get-started-get-esp-idf:
-.. _get-started-set-up-tools:
+
第二步：获取 ESP-IDF
-===========================
+=================================
+
+在围绕 ESP32 构建应用程序之前，请先获取乐鑫提供的软件库文件 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
-除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
+获取 ESP-IDF 的本地副本：打开终端，切换到您要保存 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。
-请将 ESP-IDF 下载到您的本地。
+.. note::
-获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。
+ 在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。
Linux 和 MacOS 操作系统
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
打开终端，后运行以下命令：
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
Windows 操作系统
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. note::
+除了安装必要工具外，第一步中介绍的 :ref:`get-started-windows-tools-installer` 也能同时下载 ESP-IDF 本地副本。
+
+请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
- 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
+除了使用 ESP-IDF 工具安装器，您也可以参考 :ref:`指南 <get-esp-idf-windows-command-line>` 手动下载 ESP-IDF。
-请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
+.. _get-started-set-up-tools:
-打开命令提示符，后运行以下命令：
+第三步：设置工具
+=================================
-.. include:: /_build/inc/git-clone-windows.inc
+除了 ESP-IDF 本身，您还需要安装 ESP-IDF 使用的各种工具，比如编译器、调试器、Python 包等。
-ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
+Windows 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
+请根据第一步中对 Windows (:ref:`get-started-windows-tools-installer`) 的介绍，安装所有必需工具。
-.. include:: /_build/inc/git-clone-notes.inc
+除了使用 ESP-IDF 工具安装器，您也可以通过 **命令提示符** 窗口手动安装这些工具。具体步骤见下：
-.. note::
+.. code-block:: batch
+
+ cd %userprofile%\esp\esp-idf
+ install.bat
+
+或使用 Windows PowerShell
+
+.. code-block:: powershell
+
+ cd ~/esp/esp-idf
+ ./install.ps1
+
+Linux 和 MacOS 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块： ::
+.. code-block:: bash
+
+ cd ~/esp/esp-idf
+ ./install.sh
+
+自定义工具安装路径
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户根文件夹中，即 Linux 和 MacOS 系统中的 ``$HOME/.espressif`` 和 Windows 系统的 ``%USERPROFILE%\.espressif``。此外，您可以可以将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 ``IDF_TOOLS_PATH``。注意，请确保您的用户已经具备了读写该路径的权限。
- cd esp-idf
- git submodule update --init
+如果修改了 ``IDF_TOOLS_PATH`` 变量，请确保该变量在每次执行“安装脚本” (``install.bat``、``install.ps1`` 或 ``install.sh``) 和导出脚本 (``export.bat``、``export.ps1`` 或 ``export.sh``) 均保持一致。
-.. _get-started-setup-path:
.. _get-started-set-up-env:
-第三步：设置环境变量
-===========================
+第四步：设置环境变量
+=======================================
-请在您的 PC 上设置以下环境变量，否则无法编译工程。
+此时，您刚刚安装的工具尚未添加至 PATH 环境变量，无法通过“命令窗口”使用这些工具。因此，必须设置一些环境变量，这可以通过 ESP-IDF 提供的另一个脚本完成。
-- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
-- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
+Windows 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-paths-to-profile-windows>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos>` 操作系统的具体设置方式。
+Windows 安装器（:ref:`get-started-windows-tools-installer` ）可在“开始”菜单创建一个 "ESP-IDF Command Prompt" 快捷方式。该快捷方式可以打开命令提示符窗口，并设置所有环境变量。您可以点击该快捷方式，然后继续下一步。
+此外，如果您希望在当下命令提示符窗口使用 ESP-IDF，请使用下方代码：
-.. _get-started-get-packages:
+.. code-block:: batch
-第四步：安装 Python 软件包
-=================================
+ %userprofile%\esp\esp-idf\export.bat
-ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
+或使用 Windows PowerShell
- python -m pip install --user -r $IDF_PATH/requirements.txt
+.. code-block:: powershell
-.. note::
+ .$HOME/esp/esp-idf/export.ps1
+
+Linux 和 MacOS 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+请在您需要运行 ESP-IDF 的“命令提示符”窗口运行以下命令：
- 请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如：
+.. code-block:: bash
+
+ . $HOME/esp/esp-idf/export.sh
- ``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt``
+注意，命令开始的 "." 与路径之间应有一个空格！
+
+此外，您也可以将这行代码增加至您的 ``.profile`` 或 ``.bash_profile`` 脚本中，这样您就可以在任何命令窗口使用 ESP-IDF 工具了。
.. _get-started-start-project:
第五步：开始创建工程
-=======================
+========================================
现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。
将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下：
Linux 和 MacOS 操作系统
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
cp -r $IDF_PATH/examples/get-started/hello_world .
Windows 操作系统
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
.. _get-started-connect:
第六步：连接设备
-======================
+==========================================
现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。
.. _get-started-configure:
第七步：配置
-=================
+=========================
请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。
Linux 和 MacOS 操作系统
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/hello_world
idf.py menuconfig
-如果您的默认 Python 版本为 3.0 以上，可能需要运行 ``python2 idf.py`` 。
+如果您的默认 Python 版本为 3.0 及以上，可能需要运行 ``python2 $(which idf.py) menuconfig``。
Windows 操作系统
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\hello_world
idf.py menuconfig
-Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。
-
-.. note::
-
- 如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf`。
-
如果之前的步骤都正确，则会显示下面的菜单：
.. figure:: ../../_static/project-configuration.png
:alt: 工程配置 — 主窗口
:figclass: align-center
- 工程配置 — 主窗口
+工程配置 — 主窗口
``menuconfig`` 工具的常见操作见下。
-* ``上下箭头``：移动
+* 上下箭头：移动
* ``回车``：进入子菜单
* ``ESC 键``：返回上级菜单或退出
* ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。
-* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项
-* ``英文问号``：调出有关高亮选项的帮助菜单
-* ``/ 键``：寻找配置项目
+* ``空格``或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项
+* ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单
+* ``/ 键``：寻找配置工程
.. attention::
.. _get-started-build:
第八步：编译工程
-==================
+=========================
请使用以下命令，编译烧录工程：::
.. code-block:: none
- $ idf.py build
- Running cmake in directory /path/to/hello_world/build
- Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
- Warn about uninitialized values.
- -- Found Git: /usr/bin/git (found version "2.17.0")
- -- Building empty aws_iot component due to configuration
- -- Component names: ...
- -- Component paths: ...
-
- ... (more lines of build system output)
-
- [527/527] Generating hello-world.bin
- esptool.py v2.3.1
-
- Project build complete. To flash, run this command:
- ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
- or run 'idf.py -p PORT flash'
+ $ idf.py build
+ Running cmake in directory /path/to/hello_world/build
+ Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
+ Warn about uninitialized values.
+ -- Found Git:/usr/bin/git (found version "2.17.0")
+ -- Building empty aws_iot component due to configuration
+ -- Component names: ...
+ -- Component paths: ...
+
+ ... (more lines of build system output)
+
+ [527/527] Generating hello-world.bin
+ esptool.py v2.3.1
+
+ Project build complete. To flash, run this command:
+ ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
+ or run 'idf.py -p PORT flash'
如果一切正常，编译完成后将生成 .bin 文件。
.. _get-started-flash:
第九步：烧录到设备
-====================
+=============================
-请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： ::
+请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板：
- idf.py -p PORT [-b BAUD] flash
+ ``idf.py -p PORT [-b BAUD] flash``
请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect`。
-您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
+您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。
.. _get-started-build-monitor:
第十步：监视器
-==================
+======================
您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。
-运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： ::
+运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动：::
$ idf.py -p /dev/ttyUSB0 monitor
Running idf_monitor in directory [...]/esp/hello_world/build
您可使用快捷键 ``Ctrl+]``，退出 IDF 监视器。
-å¦\82æ\9e\9c IDF ç\9b\91è§\86å\99¨å\9c¨ç\83§å½\95å\90\8eå¾\88å¿«å\8f\91ç\94\9fé\94\99误ï¼\8cæ\88\96æ\89\93å\8d°ä¿¡æ\81¯å\85¨æ\98¯ä¹±ç \81ï¼\88è§\81ä¸\8bï¼\89ï¼\8cå¾\88æ\9c\89å\8f¯è\83½æ\98¯å\9b 为æ\82¨ç\9a\84å¼\80å\8f\91æ\9d¿é\80\89用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。
+å¦\82æ\9e\9c IDF ç\9b\91è§\86å\99¨å\9c¨ç\83§å½\95å\90\8eå¾\88å¿«å\8f\91ç\94\9fé\94\99误ï¼\8cæ\88\96æ\89\93å\8d°ä¿¡æ\81¯å\85¨æ\98¯ä¹±ç \81ï¼\88è§\81ä¸\8bï¼\89ï¼\8cå¾\88æ\9c\89å\8f¯è\83½æ\98¯å\9b 为æ\82¨ç\9a\84å¼\80å\8f\91æ\9d¿é\87\87用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。
.. figure:: ../../_static/get-started-garbled-output.png
:align: center
:alt: 乱码输出
:figclass: align-center
-此时，请您：
+此时，您可以：
1. 退出监视器。
-2. 打开 :ref:`menuconfig <get-started-configure>`，
+2. 打开 :ref:`menuconfig <get-started-configure>`。
3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。
4. 然后，请重新 :ref:`编译和烧录 <get-started-flash>` 应用程序。
您也可以运行以下命令，一次性执行构建、烧录和监视过程：
- ``idf.py -p PORT flash monitor``
+ ``idf.py -p PORT flash monitor``
此外，
现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。
更新 ESP-IDF
-=================
+================
乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。
-如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH <add-idf_path-to-profile>`。否则，工具链将无法找到 ESP-IDF。
-
此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 <updating>` 章节查看。
+注意，更新完成后，请执行 ``install.sh`` （Windows 系统中为 ``install.bat``）脚本，避免新版 ESP-IDF 所需的工具也有所更新。具体请参考 :ref:`get-started-set-up-tools`。
+
+一旦重新安装好工具，请使用“导出脚本”更新环境，具体请参考 :ref:`get-started-set-up-env`。
+
相关文档
-===========
+=================
.. toctree::
:maxdepth: 1
- add-idf_path-to-profile
establish-serial-connection
eclipse-setup
../api-guides/tools/idf-monitor
:link_to_translation:`en:[English]`
-除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
+除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
安装准备
=====================
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
-
.. note::
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
从源代码编译工具链
=================================
-- 安装依赖：
+安装依赖项：
- - CentOS 7::
+- CentOS 7::
- sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
+ sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
- - Ubuntu pre-16.04::
+- Ubuntu pre-16.04::
- sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
+ sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
- - Ubuntu 16.04 及以上::
+- Ubuntu 16.04 或以上 ::
- sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+ sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- - Debian 9::
+- Debian 9::
- sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+ sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- - Arch::
+- Arch::
- TODO
+ TODO
创建工作目录，并进入该目录::
- mkdir -p ~/esp
- cd ~/esp
+ mkdir -p ~/esp
+ cd ~/esp
下载并编译 ``crosstool-NG`` ：
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
-编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path>` 的介绍，将工具链添加到 ``PATH``。
+编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path-legacy>` 的介绍，将工具链添加到 ``PATH``。
后续步骤
-*******************************************************************
+*********************************************
Linux 平台工具链的标准设置
-*******************************************************************
+*********************************************
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
-å®\89è£\85å\89\8dæ\8f\90
+å®\89è£\85å\87\86å¤\87
=====================
编译 ESP-IDF 需要以下软件包：
- Ubuntu 和 Debian::
- sudo apt-get install git wget libncurses-dev flex bison gperf python python-click python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
+ sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
- sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
+ sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
-工具链的设置
-=========================
-
-.. include:: /_build/inc/download-links.inc
-
-Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
-
-- 64 位 Linux：
-
- |download_link_linux64|
-
-- 32 位 Linux：
-
- |download_link_linux32|
-
-1. 下载完成后，将它解压到 ``~/esp`` 目录：
-
- - for 64-bit Linux:
-
- .. include:: /_build/inc/unpack-code-linux64.inc
-
- - for 32-bit Linux:
-
- .. include:: /_build/inc/unpack-code-linux32.inc
-
-.. _setup-linux-toolchain-add-it-to-path:
-
-2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
-
- 要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：::
-
- export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
-
- 或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可::
-
- alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
-
- 然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
-
- .. note::
-
- 如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。
-
-3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确::
-
- printenv PATH
-
- 检查字符串的开头是否包含类似的工具链路径::
-
- $ printenv PATH
- /home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
-
- 除了 ``/home/user-name``，应该有具体的安装的主路径。
-
+其他提示
+===============
权限问题 /dev/ttyUSB0
-----------------------------------------------
+------------------------------------------------------------
+
+使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group>`。
-使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group>`
+ncurses 5 依赖项
+--------------------
-Arch Linux 用户
---------------------------------
+在 Linux 上运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但一些较新版本默认只提供 ncurses 6。
-在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。
+请查看对应版本信息，确认是否存在可用的 ncurses 5。此外，您也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
-`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置：
+Arch Linux 用户可在 AUR_ 中获得 native 和 lib32 配置的 ncurses 5 库：
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
-在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。
-
-或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
-
+在安装这些软件包之前，您可能需要将作者的公钥添加到您的密钥环中，具体参考上方的“注释”部分。
后续步骤
-================
+==========
-后续开发环境设置，请参考 :ref:`get-started-get-esp-idf` 一节。
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
相关文档
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
+
-*********************************************************************
-从零开始设置 Mac OS 环境下的工具链
-*********************************************************************
+***********************************************
+从零开始设置 MacOS 环境下的工具链
+***********************************************
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
软件包管理器
-======================
+===============
-从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
+从零开始设置工具链，您需要安装 MacPorts_ 或 homebrew_ 软件包管理器。或者，您也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
-MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。
+MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命令行工具即可。
- .. _homebrew: https://brew.sh/
- .. _MacPorts: https://www.macports.org/install.php
+.. _homebrew: https://brew.sh/
+.. _MacPorts: https://www.macports.org/install.php
-请å\8f\82è\80\83 :ref:`å·¥å\85·é\93¾è\87ªå®\9aä¹\89设置 <get-started-customized-setup>` ç« è\8a\82ï¼\8cæ\9f¥ç\9c\8bå\9c¨å\93ªäº\9bæ\83\85æ\99¯ä¸\8bé\9c\80è¦\81ä»\8e头å¼\80å§\8b设置工å\85·é\93¾。
+请å\8f\82è\80\83 :ref:`å·¥å\85·é\93¾è\87ªå®\9aä¹\89设置 <get-started-customized-setup>` ç« è\8a\82ï¼\8cæ\9f¥ç\9c\8bå\8f¯è\83½é\9c\80è¦\81ä»\8e头å¼\80å§\8b设置工å\85·é\93¾ç\9a\84æ\83\85å\86µ。
-å\87\86å¤\87å·¥ä½\9c
-============================
+å®\89è£\85å\87\86å¤\87
+=====================
- 安装 pip::
- sudo easy_install pip
+ sudo easy_install pip
- 安装 pyserial::
- pip install --user pyserial
+ pip install --user pyserial
- 安装 CMake 和 Ninja 编译工具：
- - 若使用 HomeBrew，你可以运行::
+ - 若有 HomeBrew，您可以运行::
- brew install cmake ninja
+ brew install cmake ninja
- - 若使用 MacPorts，你可以运行::
+ - 若有 MacPorts，您可以运行::
- sudo port install cmake ninja
+ sudo port install cmake ninja
从源代码编译工具链
-========================================
+=================================
-- 相关安装：
+安装依赖项：
- - 对于 MacPorts::
+- 对于 MacPorts::
- sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
+ sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
- - 对于 homebrew::
+- 对于 homebrew::
- brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
+ brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
创建一个文件系统镜像（区分大小写）::
- hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
+ hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
挂载::
- hdiutil mount ~/esp/crosstool.dmg
+ hdiutil mount ~/esp/crosstool.dmg
-创建指向你工作目录的符号链接::
+创建指向您工作目录的符号链接::
- mkdir -p ~/esp
- ln -s /Volumes/ctng ~/esp/ctng-volume
+ mkdir -p ~/esp
+ ln -s /Volumes/ctng ~/esp/ctng-volume
-前往新创建的目录：::
+前往新创建的目录 ::
- cd ~/esp/ctng-volume
+ cd ~/esp/ctng-volume
-下载 ``crosstool-NG``，并开始编译：
+下载并编译 ``crosstool-NG``
.. include:: /_build/inc/scratch-build-code.inc
-编译工具链：::
+编译工具链::
- ./ct-ng xtensa-esp32-elf
- ./ct-ng build
- chmod -R u+w builds/xtensa-esp32-elf
+ ./ct-ng xtensa-esp32-elf
+ ./ct-ng build
+ chmod -R u+w builds/xtensa-esp32-elf
-ç¼\96è¯\91å\90\8eç\9a\84å·¥å\85·é\93¾å°\86ä¿\9då\98å\9c¨ ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``ã\80\82æ ¹æ\8d® :ref:`Mac OS ä¸\8b设置ç\8e¯å¢\83å\8f\98é\87\8fç\9a\84æ \87å\87\86æ\96¹æ³\95 <setup-macos-toolchain-add-it-to-path>` ä¸ç\9a\84ä»\8bç»\8dï¼\8cå°\86å·¥å\85·é\93¾æ·»å\8a å\88° ``PATH`` ä¸。
+ç¼\96è¯\91å¾\97å\88°ç\9a\84å·¥å\85·é\93¾ä¼\9a被ä¿\9då\98å\88° ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``ã\80\82使ç\94¨å·¥å\85·é\93¾å\89\8dï¼\8c请å°\86 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` æ·»å\8a è\87³ ``PATH`` ç\8e¯å¢\83å\8f\98é\87\8f。
后续步骤
-=================
+==========
+
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
-继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf>` 章节。
-******************************************************************
-在 Mac OS 上安装 ESP32 工具链
-******************************************************************
+**********************************************
+MacOS 平台工具链的标准设置
+**********************************************
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
安装准备
=====================
- 安装 CMake 和 Ninja 编译工具：
- - 若有 HomeBrew_，你可以运行::
+ - 若有 HomeBrew_，您可以运行::
- brew install cmake ninja
+ brew install cmake ninja
- - 若有 MacPorts_，你可以运行::
+ - 若有 MacPorts_，您可以运行::
- sudo port install cmake ninja
+ sudo port install cmake ninja
- - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。
+ - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。
-- 强ç\83\88建议å\90\8cæ\97¶å®\89è£\85 ccache_ 以达å\88°更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
+- 强ç\83\88建议å\90\8cæ\97¶å®\89è£\85 ccache_ 以è\8e·å¾\97更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
.. note::
+
+ 如您在上述任何步骤中遇到以下错误::
- 如在任一步骤中出现以下报错信息::
-
- ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun``
-
- 你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。
-
-安装工具链
-======================
-
-.. include:: /_build/inc/download-links.inc
-
-下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网：
-
-|download_link_osx|
-
-完成下载后，请在 ``~/esp`` 目录下进行解压：
-
-.. include:: /_build/inc/unpack-code-osx.inc
-
-.. _setup-macos-toolchain-add-it-to-path:
-
-此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。
-
-为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：::
-
- export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
-
-此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令::
-
- alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
-
-此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。
-
-注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。
-
-此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确::
-
- printenv PATH
+ ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at:/Library/Developer/CommandLineTools/usr/bin/xcrun``
+ 则必须安装 XCode 命令行工具，具体可运行 ``xcode-select --install``。
后续步骤
-=================
+==========
-前往 :ref:`get-started-get-esp-idf`，完成接下来的开发环境配置。
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
相关文档
=================
.. _ccache: https://ccache.samba.org/
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
+
.. _get-started-customized-setup:
-*********************************************************
-工具链自定义设置
-*********************************************************
+*************************************
+工具链的自定义设置
+*************************************
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
-除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain`）下载二进制工具链外，你还可以自行编译工具链。
+除了从乐鑫官网（请见 :ref:`get-started-set-up-tools`）下载二进制工具链外，您还可以自行编译工具链。
-å¦\82æ\9e\9c没æ\9c\89ç\89¹å\88«é\9c\80æ±\82ï¼\8c建议ç\9b´æ\8e¥ä½¿ç\94¨æ\88\91们æ\8f\90ä¾\9bç\9a\84é¢\84ç¼\96è¯\91äº\8cè¿\9bå\88¶å·¥å\85·é\93¾ã\80\82ä¸\8dè¿\87ï¼\8cä½ ä¹\9få\8f¯è\83½ä¹\9fä¼\9aç\94±äº\8e以ä¸\8bå\8e\9få\9b ï¼\8cç¼\96è¯\91ä½ è\87ªå·±ç\9a\84工具链：
+å¦\82æ\97 ç\89¹æ®\8aé\9c\80æ±\82ï¼\8c建议ç\9b´æ\8e¥ä½¿ç\94¨æ\88\91们æ\8f\90ä¾\9bç\9a\84é¢\84ç¼\96è¯\91äº\8cè¿\9bå\88¶å·¥å\85·é\93¾ã\80\82ä¸\8dè¿\87ï¼\8cæ\82¨å\8f¯ä»¥å\9c¨ä»¥ä¸\8bæ\83\85å\86µè\80\83è\99\91è\87ªè¡\8cç¼\96è¯\91工具链：
- 需要定制工具链编译配置
-- 使用其他 GCC 版本（如 4.8.5）
+- 需要使用其他 GCC 版本（如 4.8.5）
- 需要破解 gcc、newlib 或 libstdc++
- 有相关兴趣或时间充裕
- 不信任从网站下载的 bin 文件
如需自行编译工具链，请查看以下文档：
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
+
+ windows-setup-scratch
+ linux-setup-scratch
+ macos-setup-scratch
- windows-setup-scratch
- linux-setup-scratch
- macos-setup-scratch
-******************************************************************
+********************************************
从零开始设置 Windows 环境下的工具链
-******************************************************************
+********************************************
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
-本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 <windows-setup>` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。
+除了使用 :doc:`ESP-IDF 工具安装器 <windows-setup>`，用户也可以手动设置 Windows 环境下的工具链，这也是本文的主要内容。手动安装工具可以更好地控制安装流程，同时也方便高阶用户进行自定义安装。
使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。
+.. note::
+ 基于 GNU Make 的构建系统要求 Windows 兼容 MSYS2_ Unix，基于 CMake 的构建系统则无此要求。
+
+.. _get-esp-idf-windows-command-line:
+
+获取 ESP-IDF
+=================
.. note::
- 基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。
+
+ 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
+
+ 请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
+
+打开命令提示符，运行以下命令：
+
+.. include:: /_build/inc/git-clone-windows.inc
+
+ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
+
+请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
+
+.. include:: /_build/inc/git-clone-notes.inc
+
+.. note::
+
+ 在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块 ::
+
+ cd esp-idf
+ git submodule update --init
+
工具
=====
-cmake
-^^^^^
+cmake 工具
+^^^^^^^^^^
下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。
-当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
+当安装器询问“安装选项”时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
Ninja 编译工具
-^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
- Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。
+ 目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具在 32 位 Windows 版本中使用 CMake 和 ``idf.py`` ，比如 mingw-make。但是目前暂无关于此工具的说明文档。
-从（`下载页面 <ninja-dl>`_）下载最新发布的 Windows 平台稳定版 `ninja`_。
+从（`下载页面 <ninja-dl_>`_）下载最新发布的 Windows 平台稳定版 ninja_。
-适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 <add-directory-windows-path>`_ （或者选择你的路径中已有的目录）。
+适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到您的路径 <add-directory-windows-path>` （或者选择您路径中的已有目录）。
Python 2.x
^^^^^^^^^^
-下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。
+下载并运行适用于 Windows 安装器的最新版 Python_ 2.7。
-Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。
+Python 安装器的“自定义”菜单可为您提供一系列选项，最后一项为 "Add python.exe to Path"（添加 python.exe 到路径中）。请将该选项更改到 "Will be installed"（将会安装）。
-Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令::
+Python 安装完成后，从 Windows 开始菜单中打开“命令提示符”窗口，并运行以下命令::
- pip install --user pyserial
+ pip install --user pyserial
适用于 IDF 的 MConf
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
-从 `kconfig-frontends 发布页面 <mconf-idf>`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。
+从 `kconfig-frontends releases page`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行少量自定义操作。
-你需将此工具解压到目录，然后 `添加到你的路径 <add-directory-windows-path>`_。
+请将此工具解压到目录，并 :ref:`添加到您的路径 <add-directory-windows-path>`。
工具链设置
===============
.. include:: /_build/inc/download-links.inc
-ä¸\8bè½½é¢\84ç¼\96è¯\91ç\9a\84 Windows å¹³å\8f°å·¥å\85·é\93¾ï¼\9a
+下载预编译的 Windows 工具链：
|download_link_win32|
-解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。
+解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-esp32-elf`` 目录。
-然后，须将该目录下的子目录 ``bin`` `添加到你的路径 <add-directory-windows-path>`_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
+然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到您的路径 <add-directory-windows-path>`。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
.. note::
-
- 如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
+ 如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
.. _add-directory-windows-path:
添加目录到路径
========================
-添加任何新目录到你的 Windows Path 环境变量：
+在 Windows 环境下，向 Path 环境变量增加任何新目录，请：
-打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。
+打开系统“控制面板”，找到环境变量对话框（Windows 10 用户请前往“高级系统设置”）。
-双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
+双击 ``Path`` 变量（选择“用户”或“系统路径”，具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
后续步骤
-================
+==========
-要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
+.. _cmake: https://cmake.org/download/
.. _ninja: https://ninja-build.org/
+.. _ninja-dl: https://github.com/ninja-build/ninja/releases
.. _Python: https://www.python.org/downloads/windows/
.. _MSYS2: https://msys2.github.io/
+.. _kconfig-frontends releases page: https://github.com/espressif/kconfig-frontends/releases
+.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
+
-:orphan:
+*************************************************
+在 Windows 环境下更新 ESP-IDF 工具
+*************************************************
+
+.. _get-started-install_bat-windows:
+
+使用脚本安装 ESP-IDF 工具
+====================================
+
+请从 Windows “命令提示符”窗口，切换至 ESP-IDF 的安装目录。然后运行::
+
+ install.bat
+
+对于 Powershell，请切换至 ESP-IDF 的安装目录。然后运行::
+
+ install.ps1
+
+该命令可下载安装 ESP-IDF 所需的工具。如您已经安装了某个版本的工具，则该命令将无效。
+该工具的下载安装位置由 ESP-IDF 工具安装器的设置决定，默认情况下为： ``C:\Users\username\.espressif``。
+
+.. _get-started-export_bat-windows:
+
+使用“导出脚本”将 ESP-IDF 工具添加至 PATH
+=================================================================================
+
+ESP-IDF 工具安装器将在“开始菜单”为 “ESP-IDF 命令提示符” 创建快捷方式。点击该快捷方式可打开 Windows 命令提示符窗口，您可在该窗口使用所有已安装的工具。
+
+有些情况下，您正在使用的 ESP-IDF 版本可能并未创建命令提示符快捷方式，此时您可以根据下方步骤将 ESP-IDF 工具添加至 PATH。
+
+首先，请打开需要使用 ESP-IDF 的命令提示符窗口，切换至 ESP-IDF 的安装路径，然后执行 ``export.bat``::
+
+ cd %userprofile%\esp\esp-idf
+ export.bat
+
+对于 Powershell 用户，请同样切换至 ESP-IDF 的安装路径，然后执行 ``export.ps1``::
+
+ cd ~/esp/esp-idf
+ export.ps1
+
+运行完成后，您就可以通过命令提示符使用 ESP-IDF 工具了。
-.. Remove this file when the Chinese translation of getting started guide is updated
-**********************************************************
+***********************************************
Windows 平台工具链的标准设置
-**********************************************************
+***********************************************
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
.. note::
- 基于 CMake 的构建系统仅支持 64 位版本 Windows。
+ 目前，基于 CMake 的构建系统仅支持 64 位 Windows 版本。32 位 Windows 版本的用户可根据 :doc:`传统 GNU Make 构建系统<../get-started-legacy/windows-setup>` 中的介绍进行操作。
-引言
+概述
============
-ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。
+ESP-IDF 需要安装一些必备工具，才能围绕 ESP32 构建固件，包括 Python、Git、交叉编译器、menuconfig 工具、CMake和 Ninja 编译工具等。
-å\9c¨æ¤å\85¥é\97¨æ\8c\87å\8d\97ä¸ï¼\8cæ\88\91们é\80\9aè¿\87å\91½ä»¤æ\8f\90示符è¿\9bè¡\8cæ\9c\89å\85³æ\93\8dä½\9cã\80\82ä¸\8dè¿\87ï¼\8cå®\89è£\85 ESP-IDF å\90\8eä½ è¿\98å\8f¯ä»¥ä½¿ç\94¨ :doc:`Eclipse <eclipse-setup>` æ\88\96æ\94¯æ\8c\81 CMake ç\9a\84å\9b¾å½¢å\8c\96å·¥å\85· IDEã\80\82
+å\9c¨æ\9c¬å\85¥é\97¨æ\8c\87å\8d\97ä¸ï¼\8cæ\88\91们é\80\9aè¿\87 **å\91½ä»¤æ\8f\90示符** è¿\9bè¡\8cæ\9c\89å\85³æ\93\8dä½\9cã\80\82ä¸\8dè¿\87ï¼\8cæ\82¨å\9c¨å®\89è£\85 ESP-IDF å\90\8eè¿\98å\8f¯ä»¥ä½¿ç\94¨ :doc:`Eclipse <eclipse-setup>` æ\88\96å\85¶ä»\96æ\94¯æ\8c\81 CMake ç\9a\84å\9b¾å½¢å\8c\96å·¥å\85· IDEã\80\82
-https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip
+.. note::
+ 较早 ESP-IDF 版本使用 :doc:`传统 GNU Make 编译系统<../get-started-legacy/windows-setup>` 和 MSYS2_ Unix 兼容环境。但如今已非必需，用户可直接通过 Windows 命令提示符使用 ESP-IDF。
+
+.. _get-started-windows-tools-installer:
ESP-IDF 工具安装器
=======================
-安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
-
-https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe
+要安装 ESP-IDF 必备工具，最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
-安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。
+https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe
-安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。
+本安装器可为您安装所需的交叉编译器、OpenOCD、cmake_ 和 Ninja_ 编译工具，以及一款 mconf-idf_ 配置工具。此外，本安装器还可在有需要时下载、运行 Python_ 3.7 和 `Git For Windows` 的安装器。
-请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。
+本安装器还可用于下载任意 ESP-IDF 发布版本。
-安装 Git
-==============
+使用命令提示符
+========================
-ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。
+在后续步骤中，我们将使用 Windows 的命令提示符进行操作。
-如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。
+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 路径。
-- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。
-- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。
-- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。
+2. 运行 ``cmd.exe``，并更新至您希望使用的 ESP-IDF 目录，然后运行 ``export.bat``。注意，这种方法要求 ``PATH`` 中存在 Python 和 Git。如果您在使用时遇到有关“找不到 Python 或 Git” 的错误信息，请使用第一种方法。
后续步骤
==========
-要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
+当 ESP-IDF 工具安装器安装完成后，则开发环境设置也到此结束。后续开发步骤，请前往 :ref:`get-started-start-project` 查看。
相关文档
=================
:maxdepth: 1
windows-setup-scratch
-
+ windows-setup-update
.. _MSYS2: https://msys2.github.io/
.. _cmake: https://cmake.org/download/
.. _Git for Windows: https://gitforwindows.org/
.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
.. _Github Desktop: https://desktop.github.com/
+
projects / esp-idf / commitdiff