From 4131b51c166ddf64d8c511b7b5ab1be3ec049682 Mon Sep 17 00:00:00 2001 From: liying Date: Tue, 24 Mar 2020 16:09:15 +0800 Subject: [PATCH] Backport changes made in 6147 to release/4.0 --- docs/en/contribute/documenting-code.rst | 65 ++++-- .../get-started/add-idf_path-to-profile.rst | 3 - .../get-started/add-idf_path-to-profile.rst | 73 ------ docs/zh_CN/get-started/eclipse-setup.rst | 12 +- .../establish-serial-connection.rst | 76 +++---- docs/zh_CN/get-started/index.rst | 215 +++++++++--------- .../zh_CN/get-started/linux-setup-scratch.rst | 38 ++-- docs/zh_CN/get-started/linux-setup.rst | 115 ++++------ .../zh_CN/get-started/macos-setup-scratch.rst | 58 +++-- docs/zh_CN/get-started/macos-setup.rst | 78 ++----- .../get-started/toolchain-setup-scratch.rst | 15 +- .../get-started/windows-setup-scratch.rst | 86 ++++--- .../get-started/windows-setup-update.rst | 33 ++- docs/zh_CN/get-started/windows-setup.rst | 56 +++-- 14 files changed, 433 insertions(+), 490 deletions(-) delete mode 100644 docs/en/get-started/add-idf_path-to-profile.rst delete mode 100644 docs/zh_CN/get-started/add-idf_path-to-profile.rst diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index fb83f73e1..2e2df3172 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -1,7 +1,7 @@ Documenting Code ================ -The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation. +The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation. Introduction @@ -20,14 +20,14 @@ Typical comment block, that contains documentation of a function, looks like bel .. image:: ../../_static/doc-code-documentation-inline.png :align: center :alt: Sample inline code documentation - -Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data reach and very well organized `Doxygen Manual `_. + +Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data rich and very well organized `Doxygen Manual `_. Why we need it? --------------- -The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx `_ and `Breathe `_ to aid preparation and automatic updates of API documentation when the code changes. +The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx `_ and `Breathe `_ to aid preparation and automatic updates of API documentation when the code changes. With these tools the above piece of code renders like below: @@ -56,7 +56,7 @@ When writing code for this repository, please follow guidelines below. .. image:: ../../_static/doc-code-void-function.png :align: center :alt: Sample void function documented inline and after rendering - + 5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member. .. image:: ../../_static/doc-code-member.png @@ -73,7 +73,7 @@ When writing code for this repository, please follow guidelines below. * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist * - other error codes from the underlying storage driver * - + 7. Overview of functionality of documented header file, or group of files that make a library, should be placed in the same directory in a separate ``README.rst`` file. If directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``. @@ -116,7 +116,7 @@ There is couple of tips, how you can make your documentation even better and mor */ void first_similar_function (void); void second_similar_function (void); - /**@}*/ + /**@}*/ For practical example see :component_file:`nvs_flash/include/nvs.h`. @@ -132,14 +132,14 @@ There is couple of tips, how you can make your documentation even better and mor Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects. -6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory. +6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory. .. _link-custom-roles: Linking Examples ---------------- -When linking to examples on GitHub do not use absolute / hadcoded URLs. Instead, use docutils custom roles that will generate links for you. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links do not get broken when files in master branch are moved around or deleted. +When linking to examples on GitHub do not use absolute / hardcoded URLs. Instead, use docutils custom roles that will generate links for you. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links do not get broken when files in master branch are moved around or deleted. The following roles are provided: @@ -197,9 +197,9 @@ The following types of diagrams are supported: * `Activity diagram `_ * `Logical network diagram `_ -With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents. +With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents. -For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image. +For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image. Below are couple of diagram examples: @@ -215,6 +215,34 @@ Try them out by modifying the source code and see the diagram instantly renderin There may be slight differences in rendering of font used by the `interactive shell`_ compared to the font used in the esp-idf documentation. +Add Notes +--------- + +Working on a document, you might need to: + +- Place some suggestions on what should be added or modified in future. +- Leave a reminder for yourself or somebody else to follow up. + +In this case, add a todo note to your reST file using the directive ``.. todo::``. For example: + +.. code-block:: none + + .. todo:: + + Add a package diagram. + +If you add ``.. todolist::`` to a reST file, the directive will be replaced by a list of all todo notes from the whole documentation. + +By default, the directives ``.. todo::`` and ``.. todolist::`` are ignored by documentation builders. If you want the notes and the list of notes to be visible in your locally built documentation, do the following: + +1. Open your local ``conf_common.py`` file. +2. Find the parameter ``todo_include_todos``. +3. Change its value from ``False`` to ``True``. + +Before pushing your changes to origin, please set the value of ``todo_include_todos`` back to ``False``. + +For more details about the extension, see `sphinx.ext.todo `_ documentation. + Put it all together ------------------- @@ -231,10 +259,10 @@ OK, but I am new to Sphinx! 3. You will likely want to see how documentation builds and looks like before posting it on the GitHub. There are two options to do so: * Install `Sphinx `_, `Breathe `_, `Blockdiag `_ and `Doxygen `_ to build it locally, see chapter below. - + * Set up an account on `Read the Docs `_ and build documentation in the cloud. Read the Docs provides document building and hosting for free and their service works really quick and great. -4. To preview documentation before building, use `Sublime Text `_ editor together with `OmniMarkupPreviewer `_ plugin. +4. To preview documentation before building, use `Sublime Text `_ editor together with `OmniMarkupPreviewer `_ plugin. .. _setup-for-building-documentation: @@ -242,6 +270,9 @@ OK, but I am new to Sphinx! Setup for building documentation locally ---------------------------------------- +Install Dependencies +"""""""""""""""""""" + You can setup environment to build documentation locally on your PC by installing: 1. Doxygen - https://www.stack.nl/~dimitri/doxygen/ @@ -254,6 +285,7 @@ You can setup environment to build documentation locally on your PC by installin The package "sphinx_rtd_theme" is added to have the same "look and feel" of `ESP32 Programming Guide `_ documentation like on the "Read the Docs" hosting site. + Do not worry about being confronted with several packages to install. Besides Doxygen, all remaining packages are written in Python. Therefore installation of all of them is combined into one simple step. Installation of Doxygen is OS dependent: @@ -278,7 +310,7 @@ Installation of Doxygen is OS dependent: .. note:: - If you are installing on Windows system (Linux and MacOS users should skip this note), **before** going further, execute two extra steps below. These steps are required to install dependencies of "blockdiag" discussed under :ref:`add-illustrations`. + If you are installing on Windows MSYS2 system (Linux and MacOS users should skip this note, Windows users who don't use MSYS2 will need to find other alternatives), **before** going further, execute two extra steps below. These steps are required to install dependencies of "blockdiag" discussed under :ref:`add-illustrations`. 1. Update all the system packages: @@ -317,13 +349,12 @@ Now you should be ready to build documentation by invoking:: make html -This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser. - +This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser. Wrap up ------- -We love good code that is doing cool things. +We love good code that is doing cool things. We love it even better, if it is well documented, so we can quickly make it run and also do the cool things. Go ahead, contribute your code and documentation! diff --git a/docs/en/get-started/add-idf_path-to-profile.rst b/docs/en/get-started/add-idf_path-to-profile.rst deleted file mode 100644 index 9d4fa4ff4..000000000 --- a/docs/en/get-started/add-idf_path-to-profile.rst +++ /dev/null @@ -1,3 +0,0 @@ -:orphan: - -.. Remove this file when the Chinese translation of getting started guide is updated diff --git a/docs/zh_CN/get-started/add-idf_path-to-profile.rst b/docs/zh_CN/get-started/add-idf_path-to-profile.rst deleted file mode 100644 index 5c051fe53..000000000 --- a/docs/zh_CN/get-started/add-idf_path-to-profile.rst +++ /dev/null @@ -1,73 +0,0 @@ -在用户配置文件中添加 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` 小节开始阅读。 diff --git a/docs/zh_CN/get-started/eclipse-setup.rst b/docs/zh_CN/get-started/eclipse-setup.rst index 066544708..368d0240e 100644 --- a/docs/zh_CN/get-started/eclipse-setup.rst +++ b/docs/zh_CN/get-started/eclipse-setup.rst @@ -1,9 +1,11 @@ -**************************************** +******************************** Eclipse IDE 创建和烧录指南 -**************************************** - +******************************** :link_to_translation:`en:[English]` -有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。 +ESP-IDF V4.0 将默认采用基于 CMake 的编译系统。 + +对此，我们还推出了针对 CMake 编译系统的新 ESP-IDF Eclipse 插件。具体操作，请见 https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md。 + +如果您需要 Eclipse IDE 支持传统的 ESP_IDF Make 构建系统，请见 :doc:`传统 GNU Make 构建系统入门指南 ` 中的 :doc:`Eclipse IDE 创建和烧录指南 `。 -.. _eclipse.org: https://www.eclipse.org/ diff --git a/docs/zh_CN/get-started/establish-serial-connection.rst b/docs/zh_CN/get-started/establish-serial-connection.rst index 0219250dd..2952820a9 100644 --- a/docs/zh_CN/get-started/establish-serial-connection.rst +++ b/docs/zh_CN/get-started/establish-serial-connection.rst @@ -1,15 +1,14 @@ -与 ESP32 创建串口连接 -============================================== +与 ESP32 建立串口连接 +===================== :link_to_translation:`en:[English]` 本章节主要介绍如何创建 ESP32 和 PC 之间的串口连接。 - 连接 ESP32 和 PC --------------------- +----------------- -用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。 +用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。 以下是乐鑫 ESP32 开发板驱动程序的链接： @@ -22,87 +21,83 @@ `ESP32-LyraTD-MSC `_, `CP210x`_ :ref:`ESP32-PICO-KIT `, `CP210x`_ :ref:`ESP-WROVER-KIT `, `FTDI`_ - :ref:`ESP32 Demo 板 `, `FTDI`_ - `ESP-Prog`_, `FTDI`_, 编程板 (w/o ESP32) - `ESP32-MeshKit-Sense `_, n/a, 搭配 `ESP-Prog`_ 使用 - `ESP32-Sense Kit `_, n/a, 搭配 `ESP-Prog`_ 使用 + :ref:`ESP32 Demo Board `, `FTDI`_ + `ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32) + `ESP32-MeshKit-Sense `_, n/a, Use with `ESP-Prog`_ + `ESP32-Sense Kit `_, n/a, Use with `ESP-Prog`_ .. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers .. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm .. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board -* CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 `_ -* FTDI: `FTDI 虚拟 COM 端口驱动程序 `_ +* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ +* FTDI: `FTDI Virtual COM Port Drivers `_ -以上驱动仅用于参考。一般情况下，当上述任一 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。 +以上驱动仅用于参考。正常情况下，当上述任一 ESP32 开发板与 PC 连接时，打包在操作系统中的驱动程序将会开始自动安装。 -在 Windows 上查看端口 ---------------------- +查看端口（Windows 用户） +------------------------ -检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。 +检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重连。查看从列表中消失后再次出现的是哪个端口。 以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口： .. figure:: ../../_static/esp32-devkitc-in-device-manager.png :align: center - :alt: 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 + :alt: Windows 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 :figclass: align-center - - 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 + + Windows 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 .. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png :align: center - :alt: Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口 + :alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager :figclass: align-center Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口 - -在 Linux 和 MacOS 上查看端口 ------------------------------ +查看端口（Linux 和 MacOS 用户） +-------------------------------- 查看 ESP32 开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 ESP32 对应的串口： Linux :: - ls /dev/tty* MacOS :: - ls /dev/cu.* .. note:: + MacOS 用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开系统偏好设置-> 安全和隐私-> 通用，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。 - 对于 MacOS 用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。 .. _linux-dialout-group: -在 Linux 中添加用户到 ``dialout`` ------------------------------------ +将用户增加至 Linux 的 ``dialout`` 组 +------------------------------------ -当前登录用户应当可以通过 USB 对串口进行读写操作。在多数 Linux 版本中，你都可以通过以下命令，将用户添加到 ``dialout`` 组，来获许读写权限:: +当前登录用户应当拥有通过 USB 对串口进行读写的权限。在多数 Linux 版本中，您都可以通过以下命令，将用户添加到 ``dialout`` 组，来获取读写权限:: sudo usermod -a -G dialout $USER 在 Arch Linux 中，需要通过以下命令将用户添加到 ``uucp`` 组中:: - + sudo usermod -a -G uucp $USER 请重新登录，确保串口读写权限可以生效。 - 确认串口连接 ------------------------- +------------ -现在，请使用串口终端程序，验证串口连接是否可用。在本示例中，我们将使用 `PuTTY SSH Client `_， `PuTTY SSH Client `_ 既可用于 Windows 也可用于 Linux。你也可以使用其他串口程序并设置如下的通信参数。 +现在，请使用串口终端程序，验证串口连接是否可用。在本实例中，我们将使用 `PuTTY SSH Client `_ 进行验证。该工具同时适用于 Windows 和 Linux 操作系统。您也可以使用其他串口程序，设置通信参数如下。 -运行终端，配置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下截屏分别展示了在 Windows 和 Linux 中配置串口和上述通信参数（如 115200-8-1-N）。注意，这里一定要选择在上述步骤中确认的串口进行配置。 +运行终端，配置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。在 Windows 和 Linux 中配置串口和通信参数（如 115200-8-1-N）的截图如下。注意，这里一定要选择在上述步骤中确认的串口进行配置。 .. figure:: ../../_static/putty-settings-windows.png :align: center :alt: 在 Windows 操作系统中使用 PuTTY 设置串口通信参数 :figclass: align-center - + 在 Windows 操作系统中使用 PuTTY 设置串口通信参数 .. figure:: ../../_static/putty-settings-linux.png @@ -112,8 +107,7 @@ MacOS :: 在 Linux 操作系统中使用 PuTTY 设置串口通信参数 - -然后，请检查 ESP32 是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 ESP32 的应用程序，下图即为一个示例。 +然后，请在终端打开串口，查看 ESP32 是否有任何打印，具体打印内容取决于加载至 ESP32 的程序。ESP32 打印示例如下所示： .. highlight:: none @@ -138,18 +132,16 @@ MacOS :: ... -如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 ESP32。 +如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，您可以继续进行安装，并最终将应用程序下载到 ESP32。 .. note:: - 在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。 + 在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参加 `esptool 文档`_ 。 .. note:: - 请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。 - -如你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-connect` 跳转到了这里，请从 :ref:`get-started-configure` 继续阅读。 + 验证完成后，请关闭串口终端。我们将在后续步骤中向 ESP32 下载新的固件，如果未关闭终端，则该应用程序则无法访问串口。 +如果您是在安装 ESP32 软件的过程中从 :ref:`get-started-connect` 章节跳转至此，请返回 :ref:`get-started-configure` 章节。 .. _esptool 文档: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader - diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index e0b786d1f..09a71fc41 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -1,6 +1,6 @@ -******************* -快速入门（CMake） -******************* +*********** +快速入门 +*********** :link_to_translation:`en:[English]` @@ -16,7 +16,7 @@ ESP32 SoC 芯片支持以下功能： * 2.4 GHz Wi-Fi -* 蓝牙 4.2 标准 +* 蓝牙 4.2 * 高性能双核 * 超低功耗协处理器 * 多种外设 @@ -31,15 +31,15 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 硬件： * 一款 **ESP32** 开发板 -* **USB 数据线** （USB A/Micro USB B） +* **USB 数据线** (A 转 Micro-B) * PC（Windows、Linux 或 Mac OS） 软件： * 设置 **工具链**，用于编译 ESP32 代码； -* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**； -* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本； -* 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse `_。 +* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**； +* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本 +* 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse `_ .. figure:: ../../_static/what-you-need.png @@ -67,17 +67,17 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 .. _get-started-step-by-step: 详细安装步骤 -============== +============ 请根据下方详细步骤，完成安装过程。 设置开发环境 -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~ -* :ref:`get-started-setup-toolchain` +* :doc:`Windows `、:doc:`Linux ` 和 :doc:`macOS ` 的 :ref:`get-started-get-prerequisites`。 * :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` 创建您的第一个工程 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -90,21 +90,19 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 * :ref:`get-started-build-monitor` -.. _get-started-setup-toolchain: +.. _get-started-get-prerequisites: -第一步：设置工具链 -==================== +第一步：安装准备 +============================= -工具链指一套用于编译代码和应用程序的程序。 - -为了加快开发进度，您可以直接使用乐鑫提供的预制工具链。请根据您的操作系统，点击下方对应的链接，并按照链接中的指导进行安装。 +在正式开始创建工程前，请先完成工具的安装，具体步骤见下： .. toctree:: :hidden: Windows Linux - MacOS + macOS +-------------------+-------------------+-------------------+ | |windows-logo| | |linux-logo| | |macos-logo| | @@ -125,27 +123,21 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 .. _Linux: ../get-started/linux-setup.html .. _Mac OS: ../get-started/macos-setup.html +.. _get-started-get-esp-idf: + +第二步：获取 ESP-IDF +========================== + +在围绕 ESP32 构建应用程序之前，请先获取乐鑫提供的软件库文件 `ESP-IDF 仓库 `_。 + +获取 ESP-IDF 的本地副本：打开终端，切换到您要保存 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。 + .. note:: 在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。 -此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置` 章节获取更多信息。 - - -.. _get-started-get-esp-idf: -.. _get-started-set-up-tools: - -第二步：获取 ESP-IDF -=========================== - -除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 `_。 - -请将 ESP-IDF 下载到您的本地。 - -获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。 - Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ 打开终端，后运行以下命令： @@ -156,59 +148,78 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 Windows 操作系统 -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ -.. note:: - - 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。 - -请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。 - -打开命令提示符，后运行以下命令： - -.. include:: /_build/inc/git-clone-windows.inc - -ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 +除了安装必要工具外，第一步中介绍的 :ref:`get-started-windows-tools-installer` 也能同时下载 ESP-IDF 本地副本。 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 -.. include:: /_build/inc/git-clone-notes.inc +除了使用 ESP-IDF 工具安装器，您也可以参考 :ref:`指南 ` 手动下载 ESP-IDF。 -.. note:: +.. _get-started-set-up-tools: - 在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块： :: +第三步：设置工具 +======================== - cd esp-idf - git submodule update --init +除了 ESP-IDF 本身，您还需要安装 ESP-IDF 使用的各种工具，比如编译器、调试器、Python 包等。 + +Windows 操作系统 +~~~~~~~~~~~~~~~~~ + +请根据第一步中对 Windows (:ref:`get-started-windows-tools-installer`) 的介绍，安装所有必需工具。 + +除了使用 ESP-IDF 工具安装器，您也可以通过**命令提示符**窗口手动安装这些工具。具体步骤见下： + +.. code-block:: batch + + cd %userprofile%\esp\esp-idf + install.bat + +Linux 和 MacOS 操作系统 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + cd ~/esp/esp-idf + ./install.sh + +自定义工具安装路径 +~~~~~~~~~~~~~~~~~~~~ + +本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户根文件夹中，Linux 和 MacOS 系统为 ``$HOME/.espressif``，Windows 系统为 ``%USERPROFILE%\.espressif``。此外，您可以可以将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 ``IDF_TOOLS_PATH``。注意，请确保您的用户已经具备了读写该路径的权限。 + +如果修改了 ``IDF_TOOLS_PATH`` 变量，请确保该变量在每次执行 ``install.bat``/``install.sh`` 和 ``export.bat``/``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 ` 、:ref:`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`` 中。您可以运行以下命令进行安装： :: +Linux 和 MacOS 操作系统 +~~~~~~~~~~~~~~~~~~~~~~~~~~ - python -m pip install --user -r $IDF_PATH/requirements.txt +请在您需要运行 ESP-IDF 的“命令提示符”窗口运行以下命令： -.. note:: +.. code-block:: bash - 请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： + . $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: @@ -220,7 +231,7 @@ ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您 将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下： Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -228,14 +239,16 @@ Linux 和 MacOS 操作系统 cp -r $IDF_PATH/examples/get-started/hello_world . Windows 操作系统 -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ .. code-block:: batch cd %userprofile%\esp xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world -ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照上面的方法进行创建。您可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。 +ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照上面的方法进行创建。您可以按照上述方法复制并运行其中的任何示例， + +也可以直接编译示例，无需进行复制。 .. important:: @@ -244,7 +257,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 .. _get-started-connect: 第六步：连接设备 -====================== +=========================== 现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。 @@ -264,12 +277,12 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 .. _get-started-configure: 第七步：配置 -================= +============== 请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。 Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -277,19 +290,13 @@ Linux 和 MacOS 操作系统 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 @@ -301,13 +308,13 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 ``menuconfig`` 工具的常见操作见下。 -* ``上下箭头``：移动 +* 上下箭头：移动 * ``回车``：进入子菜单 * ``ESC 键``：返回上级菜单或退出 * ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。 -* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项 -* ``英文问号``：调出有关高亮选项的帮助菜单 -* ``/ 键``：寻找配置项目 +* ``空格`` 或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项 +* ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单 +* ``/ 键``：寻找配置工程 .. attention:: @@ -316,9 +323,9 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 .. _get-started-build: 第八步：编译工程 -================== +========================= -请使用以下命令，编译烧录工程：:: +请使用以下命令，编译烧录工程:: idf.py build @@ -350,7 +357,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 .. _get-started-flash: 第九步：烧录到设备 -==================== +================== 请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： :: @@ -393,25 +400,23 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 Compressed 136672 bytes to 67544... Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... Hash of data verified. - + Leaving... Hard resetting via RTS pin... 如果一切顺利，烧录完成后，开发板将会复位，应用程序 "hello_world" 开始运行。 -.. note:: - - （目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse 指南 `。 +.. （目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse guide `。 .. _get-started-build-monitor: 第十步：监视器 -================== +================ -您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。 +您可以使用 ``idf.py -p PORT 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 @@ -424,6 +429,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 ets Jun 8 2016 00:22:57 ... + 此时，您就可以在启动日志和诊断日志之后，看到打印的 “Hello world!” 了。 .. code-block:: none @@ -438,7 +444,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 您可使用快捷键 ``Ctrl+]``，退出 IDF 监视器。 -如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板选用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。 +如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板采用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。 .. figure:: ../../_static/get-started-garbled-output.png :align: center @@ -454,9 +460,9 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 .. note:: - 您也可以运行以下命令，一次性执行构建、烧录和监视过程： + 您也可以运行以下命令，一次性执行构建、烧录和监视过程:: - ``idf.py -p PORT flash monitor`` + idf.py -p PORT flash monitor 此外， @@ -468,26 +474,27 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。 更新 ESP-IDF -================= +================ 乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 -如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH `。否则，工具链将无法找到 ESP-IDF。 - 此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 ` 章节查看。 +注意，更新完成后，请执行 ``install.sh``（Windows 系统中为 ``install.bat``）脚本，避免新版 ESP-IDF 所需的工具也所更新。具体请参考 :ref:`get-started-set-up-tools`。 + +一旦重新安装好工具，请使用 ``export.sh``（Windows 系统中为 ``export.bat``）脚本更新环境，具体请参考 :ref:`get-started-set-up-env`。 + 相关文档 -=========== +======== .. toctree:: :maxdepth: 1 - add-idf_path-to-profile establish-serial-connection eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch ../get-started-legacy/index -.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ +.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ .. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/zh_CN/get-started/linux-setup-scratch.rst b/docs/zh_CN/get-started/linux-setup-scratch.rst index cf4cce448..52f6e064c 100644 --- a/docs/zh_CN/get-started/linux-setup-scratch.rst +++ b/docs/zh_CN/get-started/linux-setup-scratch.rst @@ -4,10 +4,10 @@ :link_to_translation:`en:[English]` -除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。 +除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。 安装准备 -===================== +======== 编译 ESP-IDF 需要以下软件包： @@ -15,7 +15,7 @@ sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache -- Ubuntu 和 Debian:: +- Ubuntu and Debian:: 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 libffi-dev libssl-dev @@ -23,39 +23,39 @@ sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial python-click python-cryptography python-future python-pyparsing python-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`` ： @@ -67,11 +67,11 @@ ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 +编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 `标准设置指南 `_ 的介绍，将工具链添加到 ``PATH``。 后续步骤 -========== +======== 继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst index c2cd1ef9a..3c9494003 100644 --- a/docs/zh_CN/get-started/linux-setup.rst +++ b/docs/zh_CN/get-started/linux-setup.rst @@ -1,117 +1,80 @@ -******************************************************************* +********************************************* Linux 平台工具链的标准设置 -******************************************************************* +********************************************* -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` -安装前提 -===================== +安装准备 +======== 编译 ESP-IDF 需要以下软件包： - CentOS 7:: - sudo yum install git wget ncurses-devel flex bison gperf python cmake ninja-build ccache + sudo yum install git wget ncurses-devel flex bison gperf python cmake ninja-build ccache -- Ubuntu 和 Debian:: +- Ubuntu and Debian:: - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools cmake ninja-build ccache libffi-dev libssl-dev + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools cmake ninja-build ccache libffi-dev libssl-dev - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pip cmake ninja ccache + sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pip 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``，应该有具体的安装的主路径。 + + 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 +其他提示 +======== 权限问题 /dev/ttyUSB0 ----------------------------------------------- +---------------------- -使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 ` +使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 `。 Arch Linux 用户 --------------------------------- +---------------- -在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。 +在 Arch Linux 中运行预编译 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但 Arch 会使用 ncurses 6。 -`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置： +不过，AUR_ 中有针对原生和 lib32 配置的向下兼容库： - https://aur.archlinux.org/packages/ncurses5-compat-libs/ - https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ -在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。 +在安装这些软件包之前，您可能需要将作者的公钥添加到您的密钥环中，具体参考上方的“注释”部分。 -或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。 +此外，您也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。 +设置 Ubuntu 和 Debian 默认使用 Python 3 +------------------------------------------------ + +目前，Ubuntu 和 Debian 仍使用 Python 2.7 为默认编译器。Python3 可通过以下方式安装:: + + sudo apt-get install python3 python3-pip python3-setuptools + +运行以下指令，设置 Python 3 为默认编译器:: + + sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10 + +.. note:: + + 此改动将影响系统中的所有应用。 后续步骤 -================ +======== -后续开发环境设置，请参考 :ref:`get-started-get-esp-idf` 一节。 +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 相关文档 -================= +======== .. toctree:: - :maxdepth: 1 + :maxdepth: 1 - linux-setup-scratch + linux-setup-scratch .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst index a5003ca94..67eb0d3e3 100644 --- a/docs/zh_CN/get-started/macos-setup-scratch.rst +++ b/docs/zh_CN/get-started/macos-setup-scratch.rst @@ -1,52 +1,51 @@ -********************************************************************* -从零开始设置 Mac OS 环境下的工具链 -********************************************************************* +*********************************************** +从零开始设置 MacOS 环境下的工具链 +*********************************************** -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` 软件包管理器 -====================== +============ -从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 `。 +从零开始设置工具链，您需要安装 MacPorts_ 或 homebrew_ 软件包管理器。或者，您也可以直接 :doc:`下载预编译的工具链 `。 -MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。 +MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命令行工具即可。 .. _homebrew: https://brew.sh/ .. _MacPorts: https://www.macports.org/install.php -请参考 :ref:`工具链自定义设置 ` 章节，查看在哪些情景下需要从头开始设置工具链。 +请参考 :ref:`工具链自定义设置 ` 章节，查看可能需要从头开始设置工具链的情况。 -准备工作 -============================ +安装准备 +======== - 安装 pip:: - + sudo easy_install pip - 安装 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 - - - 对于 homebrew:: + + - 对于 homebrew:: brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make @@ -58,29 +57,28 @@ MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCo hdiutil mount ~/esp/crosstool.dmg -创建指向你工作目录的符号链接:: +创建指向您工作目录的符号链接:: mkdir -p ~/esp ln -s /Volumes/ctng ~/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 -编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 - +编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` 添加至 ``PATH`` 环境变量。 后续步骤 -================= +======== -继续设置开发环境，请前往 :ref:`获取 ESP-IDF ` 章节。 +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf`。 diff --git a/docs/zh_CN/get-started/macos-setup.rst b/docs/zh_CN/get-started/macos-setup.rst index 43d8a6684..183fd7766 100644 --- a/docs/zh_CN/get-started/macos-setup.rst +++ b/docs/zh_CN/get-started/macos-setup.rst @@ -1,11 +1,11 @@ -****************************************************************** -在 Mac OS 上安装 ESP32 工具链 -****************************************************************** +************************** +MacOS 平台工具链的标准设置 +************************** -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` 安装准备 -===================== +======== ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 @@ -19,71 +19,37 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 - 安装 CMake 和 Ninja 编译工具： - - 若有 HomeBrew_，你可以运行:: + - 如果有安装 HomeBrew_，则可通过运行以下指令完成安装:: - brew install cmake ninja + brew install cmake ninja + + - 如果有安装 MacPorts_，则可通过运行以下指令完成安装:: - - 若有 MacPorts_，你可以运行:: + sudo port install cmake ninja + + - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 - sudo port install cmake ninja - - - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 - -- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。 +- 强烈建议同时安装 ccache_ 以获得更快的编译速度。如有 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。 相关文档 -================= +======== .. toctree:: :maxdepth: 1 - + macos-setup-scratch .. _cmake: https://cmake.org/ diff --git a/docs/zh_CN/get-started/toolchain-setup-scratch.rst b/docs/zh_CN/get-started/toolchain-setup-scratch.rst index 435fe177b..f34dada90 100644 --- a/docs/zh_CN/get-started/toolchain-setup-scratch.rst +++ b/docs/zh_CN/get-started/toolchain-setup-scratch.rst @@ -1,17 +1,17 @@ .. _get-started-customized-setup: -********************************************************* -工具链自定义设置 -********************************************************* +************************************* +工具链的自定义设置 +************************************* -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` -除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain`）下载二进制工具链外，你还可以自行编译工具链。 +除了从乐鑫官网（请见 :ref:`get-started-set-up-tools`）下载二进制工具链外，您还可以自行编译工具链。 -如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链： +如无特殊需求，建议直接使用我们提供的预编译二进制工具链。不过，您可以在以下情况考虑自行编译工具链： - 需要定制工具链编译配置 -- 使用其他 GCC 版本（如 4.8.5） +- 需要使用其他 GCC 版本（如 4.8.5） - 需要破解 gcc、newlib 或 libstdc++ - 有相关兴趣或时间充裕 - 不信任从网站下载的 bin 文件 @@ -25,3 +25,4 @@ linux-setup-scratch macos-setup-scratch + diff --git a/docs/zh_CN/get-started/windows-setup-scratch.rst b/docs/zh_CN/get-started/windows-setup-scratch.rst index 48b291a14..d92632b2f 100644 --- a/docs/zh_CN/get-started/windows-setup-scratch.rst +++ b/docs/zh_CN/get-started/windows-setup-scratch.rst @@ -1,71 +1,101 @@ -****************************************************************** +******************************************** 从零开始设置 Windows 环境下的工具链 -****************************************************************** +******************************************** -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` -本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 ` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。 +除了使用 :doc:`ESP-IDF 工具安装器 `，用户也可以手动设置 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 ^^^^^ 下载最新发布的 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。但是目前暂无关于此工具的说明文档。 -从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 `ninja`_。 +从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 ninja_。 -适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 `_ （或者选择你的路径中已有的目录）。 +适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到您的路径 ` （或者选择您路径中的已有目录）。 Python ^^^^^^ +下载并运行适用于 Windows 安装器的最新版 Python_。 -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`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。 +从 `kconfig-frontends releases page `_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行少量自定义操作。 -你需将此工具解压到目录，然后 `添加到你的路径 `_。 +请将此工具解压到目录，并 `添加到您的路径 `_。 工具链设置 =============== .. include:: /_build/inc/download-links.inc -下载预编译的 Windows 平台工具链： +下载预编译的 Windows 工具链： |download_link_win32| -解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。 +解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-esp32-elf`` 目录。 -然后，须将该目录下的子目录 ``bin`` `添加到你的路径 `_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。 +然后，请将该目录下的 ``bin`` 子目录 `添加到您的路径 `_。例如，``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: @@ -73,19 +103,21 @@ Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并 添加目录到路径 ======================== -添加任何新目录到你的 Windows Path 环境变量： +在 Windows 环境下，向 Path 环境变量增加任何新目录，请： -打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。 +打开系统“控制面板”，找到环境变量对话框（Windows 10 用户请前往“高级系统设置”）。 -双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;``。 +双击 ``Path`` 变量（选择“用户”或“系统路径”，具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;``。 后续步骤 -================ +======== -要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。 +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 .. _ninja: https://ninja-build.org/ .. _Python: https://www.python.org/downloads/windows/ .. _MSYS2: https://msys2.github.io/ +.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ + diff --git a/docs/zh_CN/get-started/windows-setup-update.rst b/docs/zh_CN/get-started/windows-setup-update.rst index 9d4fa4ff4..df28e39fb 100644 --- a/docs/zh_CN/get-started/windows-setup-update.rst +++ b/docs/zh_CN/get-started/windows-setup-update.rst @@ -1,3 +1,32 @@ -:orphan: +************************************* +在 Windows 环境下更新 ESP-IDF 工具 +************************************* + +.. _get-started-install_bat-windows: + +运行 ``install.bat`` 安装 EPS-IDF 工具 +=========================================== + +请从 Windows “命令提示符”窗口，切换至 ESP-IDF 的安装目录。然后运行:: + + install.bat + +该命令可下载安装 ESP-IDF 所需的工具。如您已经安装了某个版本的工具，则该命令将无效。 +该工具的下载安装位置由 ESP-IDF 工具安装器的设置决定，默认情况下为： ``C:\Users\username\.espressif``。 + +.. _get-started-export_bat-windows: + +运行 ``export.bat`` 将 ESP-IDF 工具添加至路径 +============================================== + +ESP-IDF 工具安装器将在“开始菜单”为 “ESP-IDF 命令提示符” 创建快捷方式。点击该快捷方式可打开 Windows 命令提示符窗口，您可在该窗口使用所有已安装的工具。 + +有些情况下，您正在使用的 ESP-IDF 版本可能并未创建命令提示符快捷方式，此时您可以根据下方步骤将 ESP-IDF 工具添加至 PATH。 + +首先，请打开需要使用 ESP-IDF 的命令提示符窗口，切换至 ESP-IDF 的安装路径，然后执行 ``export.bat``:: + + cd %userprofile%\esp\esp-idf + export.bat + +运行完成后，您就可以通过命令提示符使用 ESP-IDF 工具了。 -.. Remove this file when the Chinese translation of getting started guide is updated diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index 1bbb806fd..51a537cc7 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -1,57 +1,55 @@ -********************************************************** +*********************************************** 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 编译工具等。 -在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse ` 或支持 CMake 的图形化工具 IDE。 +在本入门指南中，我们通过 **命令提示符** 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 :doc:`Eclipse ` 或其他支持 CMake 的图形化工具 IDE。 -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 工具安装器，地址如下： +要安装 ESP-IDF 必备工具，最简易的方式是下载 ESP-IDF 工具安装器，地址如下： -https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe +https://dl.espressif.com/dl/esp-idf-tools-setup-2.3.exe -安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。 +本安装器可为您安装所需的交叉编译器、OpenOCD、cmake_ 和 Ninja_ 编译工具，以及一款 mconf-idf_ 配置工具。此外，本安装器还可在有需要时下载、运行 Python_ 3.7 和 `Git For Windows` 的安装器。 -安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。 +本安装器还可用于下载任意 ESP-IDF 发布版本。 -请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。 +使用命令提示符 +=============== -安装 Git -============== +在后续步骤中，我们将使用 Windows 的命令提示符进行操作。 -ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。 +ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF 命令提示符窗口的快捷方式。本快捷方式可以打开 Windows 命令提示符（即 cmd.exe），并运行 ``export.bat`` 脚本以设置各环境变量（比如 ``PATH``，``IDF_PATH`` 等）。此外，您可还以通过 Windows 命令提示符使用各种已经安装的工具。 -如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。 +注意，本快捷方式仅适用 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` 查看。 相关文档 -================= +======== 想要自定义安装流程的高阶用户可参照： @@ -59,7 +57,7 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你 :maxdepth: 1 windows-setup-scratch - + windows-setup-update .. _MSYS2: https://msys2.github.io/ .. _cmake: https://cmake.org/download/