diff --git a/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst b/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst index 06d563916..ad19c5465 100644 --- a/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst +++ b/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst @@ -29,10 +29,10 @@ Windows 操作系统 你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。 -- 点击 ``New...``（新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\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-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。 +如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。 .. _add-idf_path-to-profile-linux-macos-cmake: @@ -40,7 +40,7 @@ Windows 操作系统 Linux 和 MacOS 操作系统 ------------------------------------ -要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码增加至你的 ``~/.profile`` 文件中:: +要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中:: export IDF_PATH=~/esp/esp-idf export PATH="$IDF_PATH/tools:$PATH" @@ -53,7 +53,7 @@ Linux 和 MacOS 操作系统 .. note:: - 并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。 + 并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。 运行以下命令来检查 ``IDF_PATH`` 设置是否正确:: @@ -67,9 +67,9 @@ Linux 和 MacOS 操作系统 这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。 -如果你不想进行有关 ``IDF_PATH`` 或 ``PATH`` 的修改设置，你可以在每次重启或退出后在终端中手动输入:: +如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入:: export IDF_PATH=~/esp/esp-idf export PATH="$IDF_PATH/tools:$PATH" -如果你在安装 ESP32 开发的软件时，从 :ref:`get-started-setup-path-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。 +如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。 diff --git a/docs/zh_CN/get-started-cmake/establish-serial-connection.rst b/docs/zh_CN/get-started-cmake/establish-serial-connection.rst index f646db83e..278dfb6af 100644 --- a/docs/zh_CN/get-started-cmake/establish-serial-connection.rst +++ b/docs/zh_CN/get-started-cmake/establish-serial-connection.rst @@ -13,12 +13,28 @@ 以下是乐鑫 ESP32 开发板驱动程序的链接： -* ESP32-PICO-KIT 和 ESP32-DevKitC - `CP210x USB 至 UART 桥 VCP 驱动程序 `_ +.. csv-table:: + :header: 开发板, USB 驱动, 备注 + :widths: 40, 20, 40 -* ESP32-WROVER-KIT 和 ESP32 演示板 - `FTDI 虚拟 COM 端口驱动程序 `_ + :ref:`ESP32-DevKitC `, `CP210x`_ + `ESP32-LyraT `_, `CP210x`_ + `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`_ 使用 -以上驱动仅用于参考。当你将上述 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装了。 +.. _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 端口驱动程序 `_ + +以上驱动仅用于参考。一般情况下，当上述任一 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。 在 Windows 上查看端口 --------------------- @@ -32,7 +48,7 @@ :alt: 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 :figclass: align-center - 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 + 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 .. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png :align: center @@ -55,8 +71,9 @@ MacOS :: ls /dev/cu.* +.. note:: -.. note: 对于 MacOS 用户：若你没有看到串口，请检查你是否已按照入门指南安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。 + 对于 MacOS 用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。 .. _linux-dialout-group-cmake: @@ -125,13 +142,14 @@ MacOS :: .. note:: - 在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool documentation`_。 + 在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。 .. note:: 请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。 -如你在安装用于 ESP32 开发的软件时，从 :ref:`get-started-connect-cmake` 小节跳转到了这里，请返回到 :ref:`get-started-configure-cmake` 小节继续阅读。 +如你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-connect-cmake` 跳转到了这里，请从 :ref:`get-started-configure-cmake` 继续阅读。 -.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader +.. _esptool 文档: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader + diff --git a/docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst b/docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst index 83c4fb932..6b5cefdf1 100644 --- a/docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst +++ b/docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst @@ -55,7 +55,7 @@ ESP32-DevKitC V2 开发板 电源选项 -------- -开发板可任一选用以下三种供电方式： +开发板可从以下三种供电方式中任选其一： * Micro USB 供电（默认） * 5V / GND 管脚供电 diff --git a/docs/zh_CN/get-started-cmake/get-started-devkitc.rst b/docs/zh_CN/get-started-cmake/get-started-devkitc.rst index acee9febb..1305bbe30 100644 --- a/docs/zh_CN/get-started-cmake/get-started-devkitc.rst +++ b/docs/zh_CN/get-started-cmake/get-started-devkitc.rst @@ -86,7 +86,7 @@ ESP32-DevKitC V4（板载 ESP32-WROOM-32） 电源选项 -------- -开发板可任一选用以下三种供电方式： +开发板可从以下三种供电方式中任选其一： * Micro USB 供电（默认） * 5V / GND 管脚供电 @@ -121,7 +121,7 @@ C15（黄色）在 ESP32-DevKitC V4 开发板上的位置 ESP32-DevKitC V4 上电前，请首先确认开发板完好无损。 -之后，请前往 之后，请前往 :doc:`index` 的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +之后，请前往 :doc:`index` 的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 开发板尺寸 diff --git a/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst b/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst index 992708778..0ba33490c 100644 --- a/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst +++ b/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst @@ -15,15 +15,16 @@ - CentOS 7:: - sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache python-pyelftools + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - Ubuntu 和 Debian:: - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing cmake ninja-build ccache python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial 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-cryptography python2-future python2-pyparsing cmake ninja ccache python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache + .. note:: 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 @@ -41,7 +42,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 diff --git a/docs/zh_CN/get-started-cmake/linux-setup.rst b/docs/zh_CN/get-started-cmake/linux-setup.rst index 7e1afbcb5..6104d9f43 100644 --- a/docs/zh_CN/get-started-cmake/linux-setup.rst +++ b/docs/zh_CN/get-started-cmake/linux-setup.rst @@ -13,15 +13,15 @@ Linux 平台工具链的标准设置 (CMake) - CentOS 7:: - sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache python-pyelftools + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - Ubuntu 和 Debian:: - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing cmake ninja-build ccache python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial 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-cryptography python2-future python2-pyparsing cmake ninja ccache python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache .. note:: 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 @@ -69,7 +69,7 @@ Linux 版的 ESP32 工具链可以从 Espressif 的网站下载： 如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。 -3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确：:: +3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确:: printenv PATH diff --git a/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst b/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst index 26671984f..0080d8180 100644 --- a/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst +++ b/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst @@ -16,6 +16,8 @@ MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCo .. _homebrew: https://brew.sh/ .. _MacPorts: https://www.macports.org/install.php +请参考 :ref:`工具链自定义设置 ` 章节，查看在哪些情景下需要从头开始设置工具链。 + 准备工作 ============================ @@ -25,7 +27,7 @@ MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCo - 安装 pyserial:: - sudo pip install pyserial + pip install --user pyserial - 安装 CMake 和 Ninja 编译工具： diff --git a/docs/zh_CN/get-started-cmake/macos-setup.rst b/docs/zh_CN/get-started-cmake/macos-setup.rst index 83536dbe3..adb0b1241 100644 --- a/docs/zh_CN/get-started-cmake/macos-setup.rst +++ b/docs/zh_CN/get-started-cmake/macos-setup.rst @@ -17,7 +17,7 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 - 安装 pyserial:: - sudo pip install pyserial + pip install --user pyserial - 安装 CMake 和 Ninja 编译工具： @@ -29,9 +29,9 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 sudo port install cmake ninja - - 若以上均不适用，访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 + - 若以上均不适用，请访问 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:: @@ -62,7 +62,7 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH -此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令：:: +此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令:: alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" @@ -70,7 +70,7 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。 -此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确：:: +此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确:: printenv PATH diff --git a/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst b/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst index 93770381a..fc08a6f03 100644 --- a/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst +++ b/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst @@ -6,17 +6,17 @@ :link_to_translation:`en:[英文]` -除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain-cmake`）下载二进制工具链外，你还可以自行编制工具链。 +除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain-cmake`）下载二进制工具链外，你还可以自行编译工具链。 -如果没有特别需求，建议直接使用我们提供的预编制二进制工具链。不过，你也可能也会由于以下原因，编制你自己的工具链： +如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链： -- 需要定制工具链编制配置 +- 需要定制工具链编译配置 - 使用其他 GCC 版本（如 4.8.5） - 需要破解 gcc、newlib 或 libstdc++ - 有相关兴趣或时间充裕 - 不信任从网站下载的 bin 文件 -无论如何，如果你希望自行编制工具链，请查看以下文档： +如需自行编译工具链，请查看以下文档： .. toctree:: :maxdepth: 1 diff --git a/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst b/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst index a2669f234..325de61ef 100644 --- a/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst +++ b/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst @@ -44,7 +44,7 @@ Python 安装的“自定义”那一步提供了一份选项列表，最后一 Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令:: - pip install pyserial + pip install --user pyserial 适用于 IDF 的 MConf ^^^^^^^^^^^^^^^^^^^^^^ @@ -56,9 +56,11 @@ Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并 工具链设置 =============== -从 dl.espressif.com 下载预编译的 Windows 平台工具链： +.. include:: /_build/inc/download-links.inc -https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip +下载预编译的 Windows 平台工具链： + +|download_link_win32| 解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。 diff --git a/docs/zh_CN/get-started-cmake/windows-setup.rst b/docs/zh_CN/get-started-cmake/windows-setup.rst index 72211a423..e8d129033 100644 --- a/docs/zh_CN/get-started-cmake/windows-setup.rst +++ b/docs/zh_CN/get-started-cmake/windows-setup.rst @@ -24,7 +24,7 @@ ESP-IDF 工具安装器 安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下： -https://dl.espressif.com/dl/esp-idf-tools-setup-1.1.exe +https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe 安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。 @@ -37,16 +37,16 @@ https://dl.espressif.com/dl/esp-idf-tools-setup-1.1.exe ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。 -如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，并在快速入门中阐释相应 Git 命令，以使用你所选的 Git 客户端。 +如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。 使用终端 ================ -在快速入门指南接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符： +在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符： -- 比如，Windows 开始菜单下内置的 Command Prompt。本文档中的所有 Windows 命令行指示均为 Windows Command Prompt 中所使用的 "batch" 命令。 +- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。 - 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。 -- 如果你已安装 MSYS2_（通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。 +- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。 后续步骤 ==========