Merge branch 'docs/Update_CN_Getting_Started_With_Changes_in_EN' into 'master'
Add translation for getting started guide - batch 1 See merge request espressif/esp-idf!6147
This commit is contained in:
Krzysztof Budzynski
commit
74e39c9cff
12 changed files with 384 additions and 455 deletions
|
|
@ -1,3 +0,0 @@
|
|||
:orphan:
|
||||
|
||||
.. Remove this file when the Chinese translation of getting started guide is updated
|
||||
|
|
@ -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` 小节开始阅读。
|
||||
|
|
@ -4,6 +4,8 @@ Eclipse IDE 创建和烧录指南
|
|||
|
||||
: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>` 章节。
|
||||
|
|
@ -1,22 +1,20 @@
|
|||
*******************
|
||||
快速入门（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
|
||||
* 高性能双核
|
||||
* 超低功耗协处理器
|
||||
* 多种外设
|
||||
|
|
@ -26,12 +24,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
|||
乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。
|
||||
|
||||
准备工作
|
||||
========
|
||||
=============
|
||||
|
||||
硬件：
|
||||
|
||||
* 一款 **ESP32** 开发板
|
||||
* **USB 数据线** （USB A/Micro USB B）
|
||||
* **USB 数据线** (A 转 Micro-B)
|
||||
* PC（Windows、Linux 或 Mac OS）
|
||||
|
||||
软件：
|
||||
|
|
@ -51,7 +49,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
|||
|
||||
|
||||
开发板简介
|
||||
==========
|
||||
===========================
|
||||
|
||||
请点击下方连接，了解有关具体开发板的详细信息。
|
||||
|
||||
|
|
@ -67,17 +65,17 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
|||
.. _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`
|
||||
|
||||
创建您的第一个工程
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -90,14 +88,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
|||
* :ref:`get-started-build-monitor`
|
||||
|
||||
|
||||
.. _get-started-setup-toolchain:
|
||||
.. _get-started-get-prerequisites:
|
||||
|
||||
第一步：设置工具链
|
||||
====================
|
||||
第一步：安装准备
|
||||
=============================
|
||||
|
||||
工具链指一套用于编译代码和应用程序的程序。
|
||||
|
||||
为了加快开发进度，您可以直接使用乐鑫提供的预制工具链。请根据您的操作系统，点击下方对应的链接，并按照链接中的指导进行安装。
|
||||
在正式开始创建工程前，请先完成工具的安装，具体步骤见下：
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
|
@ -125,27 +121,22 @@ 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 仓库 <https://github.com/espressif/esp-idf>`_。
|
||||
|
||||
获取 ESP-IDF 的本地副本：打开终端，切换到您要保存 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。
|
||||
|
||||
.. 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 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
|
||||
|
||||
请将 ESP-IDF 下载到您的本地。
|
||||
|
||||
获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
打开终端，后运行以下命令：
|
||||
|
||||
|
|
@ -156,71 +147,103 @@ 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:`指南 <get-esp-idf-windows-command-line>` 手动下载 ESP-IDF。
|
||||
|
||||
.. note::
|
||||
.. _get-started-set-up-tools:
|
||||
|
||||
在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块： ::
|
||||
|
||||
cd esp-idf
|
||||
git submodule update --init
|
||||
|
||||
.. _get-started-setup-path:
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
第三步：设置环境变量
|
||||
===========================
|
||||
|
||||
请在您的 PC 上设置以下环境变量，否则无法编译工程。
|
||||
|
||||
- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
|
||||
- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
|
||||
|
||||
您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-paths-to-profile-windows>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos>` 操作系统的具体设置方式。
|
||||
|
||||
|
||||
.. _get-started-get-packages:
|
||||
|
||||
第四步：安装 Python 软件包
|
||||
第三步：设置工具
|
||||
=================================
|
||||
|
||||
ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
|
||||
除了 ESP-IDF 本身，您还需要安装 ESP-IDF 使用的各种工具，比如编译器、调试器、Python 包等。
|
||||
|
||||
python -m pip install --user -r $IDF_PATH/requirements.txt
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
请根据第一步中对 Windows (:ref:`get-started-windows-tools-installer`) 的介绍，安装所有必需工具。
|
||||
|
||||
请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如：
|
||||
除了使用 ESP-IDF 工具安装器，您也可以通过 **命令提示符** 窗口手动安装这些工具。具体步骤见下：
|
||||
|
||||
``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt``
|
||||
.. code-block:: batch
|
||||
|
||||
cd %userprofile%\esp\esp-idf
|
||||
install.bat
|
||||
|
||||
或使用 Windows PowerShell
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
cd ~/esp/esp-idf
|
||||
./install.ps1
|
||||
|
||||
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.ps1`` 或 ``install.sh``) 和导出脚本 (``export.bat``、``export.ps1`` 或 ``export.sh``) 均保持一致。
|
||||
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
第四步：设置环境变量
|
||||
=======================================
|
||||
|
||||
此时，您刚刚安装的工具尚未添加至 PATH 环境变量，无法通过“命令窗口”使用这些工具。因此，必须设置一些环境变量，这可以通过 ESP-IDF 提供的另一个脚本完成。
|
||||
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Windows 安装器（:ref:`get-started-windows-tools-installer` ）可在“开始”菜单创建一个 "ESP-IDF Command Prompt" 快捷方式。该快捷方式可以打开命令提示符窗口，并设置所有环境变量。您可以点击该快捷方式，然后继续下一步。
|
||||
|
||||
此外，如果您希望在当下命令提示符窗口使用 ESP-IDF，请使用下方代码：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
%userprofile%\esp\esp-idf\export.bat
|
||||
|
||||
或使用 Windows PowerShell
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
.$HOME/esp/esp-idf/export.ps1
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
请在您需要运行 ESP-IDF 的“命令提示符”窗口运行以下命令：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. $HOME/esp/esp-idf/export.sh
|
||||
|
||||
注意，命令开始的 "." 与路径之间应有一个空格！
|
||||
|
||||
此外，您也可以将这行代码增加至您的 ``.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
|
||||
|
||||
|
|
@ -228,7 +251,7 @@ Linux 和 MacOS 操作系统
|
|||
cp -r $IDF_PATH/examples/get-started/hello_world .
|
||||
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
|
|
@ -244,7 +267,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
|
|||
.. _get-started-connect:
|
||||
|
||||
第六步：连接设备
|
||||
======================
|
||||
==========================================
|
||||
|
||||
现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。
|
||||
|
||||
|
|
@ -264,34 +287,28 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
|
|||
.. _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
|
||||
|
|
@ -303,13 +320,13 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
|||
|
||||
``menuconfig`` 工具的常见操作见下。
|
||||
|
||||
* ``上下箭头``：移动
|
||||
* 上下箭头：移动
|
||||
* ``回车``：进入子菜单
|
||||
* ``ESC 键``：返回上级菜单或退出
|
||||
* ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。
|
||||
* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项
|
||||
* ``英文问号``：调出有关高亮选项的帮助菜单
|
||||
* ``/ 键``：寻找配置项目
|
||||
* ``空格``或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项
|
||||
* ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单
|
||||
* ``/ 键``：寻找配置工程
|
||||
|
||||
.. attention::
|
||||
|
||||
|
|
@ -318,7 +335,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
|||
.. _get-started-build:
|
||||
|
||||
第八步：编译工程
|
||||
==================
|
||||
=========================
|
||||
|
||||
请使用以下命令，编译烧录工程：::
|
||||
|
||||
|
|
@ -352,11 +369,11 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
|||
.. _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`。
|
||||
|
||||
|
|
@ -409,7 +426,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
|||
.. _get-started-build-monitor:
|
||||
|
||||
第十步：监视器
|
||||
==================
|
||||
======================
|
||||
|
||||
您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。
|
||||
|
||||
|
|
@ -440,17 +457,17 @@ 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
|
||||
: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>` 应用程序。
|
||||
|
||||
|
|
@ -470,21 +487,22 @@ 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 <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
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
|
||||
除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
|
||||
|
||||
安装准备
|
||||
=====================
|
||||
|
|
@ -23,14 +23,13 @@
|
|||
|
||||
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::
|
||||
|
||||
|
|
@ -40,7 +39,7 @@
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -67,7 +66,7 @@
|
|||
./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``。
|
||||
|
||||
|
||||
后续步骤
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
*******************************************************************
|
||||
*********************************************
|
||||
Linux 平台工具链的标准设置
|
||||
*******************************************************************
|
||||
*********************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装前提
|
||||
安装准备
|
||||
=====================
|
||||
|
||||
编译 ESP-IDF 需要以下软件包：
|
||||
|
|
@ -15,94 +15,41 @@ Linux 平台工具链的标准设置
|
|||
|
||||
- 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>`。
|
||||
|
||||
Arch Linux 用户
|
||||
--------------------------------
|
||||
ncurses 5 依赖项
|
||||
--------------------
|
||||
|
||||
在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。
|
||||
在 Linux 上运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但一些较新版本默认只提供 ncurses 6。
|
||||
|
||||
`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置：
|
||||
请查看对应版本信息，确认是否存在可用的 ncurses 5。此外，您也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
|
||||
|
||||
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` 章节。
|
||||
|
||||
|
||||
相关文档
|
||||
|
|
@ -115,3 +62,4 @@ Arch Linux 用户
|
|||
|
||||
|
||||
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
|
||||
|
||||
|
|
|
|||
|
|
@ -1,23 +1,23 @@
|
|||
*********************************************************************
|
||||
***********************************************
|
||||
从零开始设置 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
|
||||
|
||||
请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看在哪些情景下需要从头开始设置工具链。
|
||||
请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看可能需要从头开始设置工具链的情况。
|
||||
|
||||
准备工作
|
||||
============================
|
||||
安装准备
|
||||
=====================
|
||||
|
||||
- 安装 pip::
|
||||
|
||||
|
|
@ -29,18 +29,18 @@ MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCo
|
|||
|
||||
- 安装 CMake 和 Ninja 编译工具：
|
||||
|
||||
- 若使用 HomeBrew，你可以运行::
|
||||
- 若有 HomeBrew，您可以运行::
|
||||
|
||||
brew install cmake ninja
|
||||
|
||||
- 若使用 MacPorts，你可以运行::
|
||||
- 若有 MacPorts，您可以运行::
|
||||
|
||||
sudo port install cmake ninja
|
||||
|
||||
从源代码编译工具链
|
||||
========================================
|
||||
=================================
|
||||
|
||||
- 相关安装：
|
||||
安装依赖项：
|
||||
|
||||
- 对于 MacPorts::
|
||||
|
||||
|
|
@ -58,29 +58,30 @@ 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 下设置环境变量的标准方法 <setup-macos-toolchain-add-it-to-path>` 中的介绍，将工具链添加到 ``PATH`` 中。
|
||||
编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` 添加至 ``PATH`` 环境变量。
|
||||
|
||||
|
||||
后续步骤
|
||||
=================
|
||||
==========
|
||||
|
||||
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
|
||||
|
||||
继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf>` 章节。
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
******************************************************************
|
||||
在 Mac OS 上安装 ESP32 工具链
|
||||
******************************************************************
|
||||
**********************************************
|
||||
MacOS 平台工具链的标准设置
|
||||
**********************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装准备
|
||||
=====================
|
||||
|
|
@ -19,64 +19,30 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
|
|||
|
||||
- 安装 CMake 和 Ninja 编译工具：
|
||||
|
||||
- 若有 HomeBrew_，你可以运行::
|
||||
- 若有 HomeBrew_，您可以运行::
|
||||
|
||||
brew install cmake ninja
|
||||
|
||||
- 若有 MacPorts_，你可以运行::
|
||||
- 若有 MacPorts_，您可以运行::
|
||||
|
||||
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
|
||||
|
||||
则必须安装 XCode 命令行工具，具体可运行 ``xcode-select --install``。
|
||||
|
||||
后续步骤
|
||||
=================
|
||||
==========
|
||||
|
||||
前往 :ref:`get-started-get-esp-idf`，完成接下来的开发环境配置。
|
||||
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
|
||||
|
||||
相关文档
|
||||
=================
|
||||
|
|
@ -91,3 +57,4 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
|
|||
.. _ccache: https://ccache.samba.org/
|
||||
.. _homebrew: https://brew.sh/
|
||||
.. _MacPorts: https://www.macports.org/install.php
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,72 +1,99 @@
|
|||
******************************************************************
|
||||
********************************************
|
||||
从零开始设置 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
|
||||
|
||||
适用于 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
|
||||
|
||||
下载预编译的 Windows 平台工具链：
|
||||
下载预编译的 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:
|
||||
|
|
@ -74,19 +101,24 @@ Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并
|
|||
添加目录到路径
|
||||
========================
|
||||
|
||||
添加任何新目录到你的 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/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,41 @@
|
|||
: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
|
||||
|
|
|
|||
|
|
@ -1,54 +1,52 @@
|
|||
**********************************************************
|
||||
***********************************************
|
||||
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 <eclipse-setup>` 或支持 CMake 的图形化工具 IDE。
|
||||
在本入门指南中，我们通过 **命令提示符** 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 :doc:`Eclipse <eclipse-setup>` 或其他支持 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.0.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/
|
||||
|
|
@ -68,3 +66,4 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你
|
|||
.. _Git for Windows: https://gitforwindows.org/
|
||||
.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
|
||||
.. _Github Desktop: https://desktop.github.com/
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue