update get-started/index.rst for release/v4.1

2025-07-29 18:27:20 +02:00 · 2020-12-11 11:38:37 +08:00
parent 6a9b351b67
commit 37d8033906
2 changed files with 61 additions and 47 deletions
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@ -109,7 +109,7 @@ Some tools need to be installed on the computer before proceeding to the next st
 +-------------------+-------------------+-------------------+
 | |windows-logo|    | |linux-logo|      | |macos-logo|      |
 +-------------------+-------------------+-------------------+
-| `Windows`_        | `Linux`_          | `Mac OS`_         |
+| `Windows`_        | `Linux`_          | `macOS`_          |
 +-------------------+-------------------+-------------------+

 .. |windows-logo| image:: ../../_static/windows-logo.png
@ -123,7 +123,7 @@ Some tools need to be installed on the computer before proceeding to the next st

 .. _Windows: ../get-started/windows-setup.html
 .. _Linux: ../get-started/linux-setup.html
-.. _Mac OS: ../get-started/macos-setup.html
+.. _macOS: ../get-started/macos-setup.html

 .. _get-started-get-esp-idf:

@ -343,9 +343,8 @@ To navigate and use ``menuconfig``, press the following keys:
 * Arrow keys for navigation
 * ``Enter`` to go into a submenu
 * ``Esc`` to go up one level or exit
-* ``?`` to see a help screen. Enter key exits the help screen
+* ``?`` to see a help screen for menu or configuration item. Enter key exits the help screen
 * ``Space``, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
-* ``?`` while highlighting a configuration item to display help about that item
 * ``/`` to find configuration items

 .. attention::
@ -385,7 +384,6 @@ This command will compile the application and all ESP-IDF components, then it wi

 If there are no errors, the build will finish by generating the firmware binary .bin file.

-
 .. _get-started-flash:

 Step 9. Flash onto the Device
@ -440,7 +438,6 @@ If there are no issues by the end of the flash process, the module will be reset

 .. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.

-
 .. _get-started-build-monitor:

 Step 10. Monitor
--- a/docs/zh_CN/get-started/index.rst
+++ b/docs/zh_CN/get-started/index.rst
@ -4,7 +4,11 @@

 :link_to_translation:`en:[English]`

-本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。
+.. Please keep README.md in sync with these instructions.
+
+本文档旨在指导用户搭建 ESP32 硬件开发的软件环境。
+
+通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。

 .. include:: /_build/inc/version-note.inc

@ -30,7 +34,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、

 * 一款 **ESP32** 开发板
 * **USB 数据线**  (A 转 Micro-B)
-* PC（Windows、Linux 或 Mac OS）
+* **电脑** （Windows、Linux 或 macOS）

 软件：

@ -105,7 +109,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
 +-------------------+-------------------+-------------------+
 | |windows-logo|    | |linux-logo|      | |macos-logo|      |
 +-------------------+-------------------+-------------------+
-| `Windows`_        | `Linux`_          | `Mac OS`_         |
+| `Windows`_        | `Linux`_          | `macOS`_          |
 +-------------------+-------------------+-------------------+

 .. |windows-logo| image:: ../../_static/windows-logo.png
@ -119,11 +123,10 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、

 .. _Windows: ../get-started/windows-setup.html
 .. _Linux: ../get-started/linux-setup.html
-.. _Mac OS: ../get-started/macos-setup.html
+.. _macOS: ../get-started/macos-setup.html

 .. _get-started-get-esp-idf:

-
 第二步：获取 ESP-IDF
 =================================

@ -133,9 +136,9 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、

 .. note::

-    在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。
+    在本文档中，Linux 和 macOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。

-Linux 和 MacOS 操作系统
+Linux 和 macOS 操作系统
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 打开终端，后运行以下命令：
@ -149,7 +152,7 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。
 Windows 操作系统
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-除了安装必要工具外，第一步中介绍的 :ref:`get-started-windows-tools-installer` 也能同时下载 ESP-IDF 本地副本。
+除了能安装必要工具外，第一步中介绍的 :ref:`get-started-windows-tools-installer` 也能同时下载 ESP-IDF 本地副本。

 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。

@ -181,7 +184,7 @@ Windows 操作系统
    cd ~/esp/esp-idf
    ./install.ps1

-Linux 和 MacOS 操作系统
+Linux 和 macOS 操作系统
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. code-block:: bash
@ -192,7 +195,7 @@ Linux 和 MacOS 操作系统
 自定义工具安装路径
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户根文件夹中，即 Linux 和 MacOS 系统中的 ``$HOME/.espressif`` 和 Windows 系统的 ``%USERPROFILE%\.espressif``。此外，您可以可以将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 ``IDF_TOOLS_PATH``。注意，请确保您的用户已经具备了读写该路径的权限。
+本步骤中介绍的脚本将 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``) 均保持一致。

@ -220,7 +223,7 @@ Windows 安装器（:ref:`get-started-windows-tools-installer` ）可在“开

    .$HOME/esp/esp-idf/export.ps1

-Linux 和 MacOS 操作系统
+Linux 和 macOS 操作系统
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 请在您需要运行 ESP-IDF 的“命令提示符”窗口运行以下命令：
@ -231,7 +234,19 @@ Linux 和 MacOS 操作系统

 注意，命令开始的 "." 与路径之间应有一个空格！

-此外，您也可以将这行代码增加至您的 ``.profile`` 或 ``.bash_profile`` 脚本中，这样您就可以在任何命令窗口使用 ESP-IDF 工具了。
+如果您需要经常运行 ESP-IDF，您可以为执行 ``export.sh`` 创建一个别名，具体步骤如下：
+
+1. 复制并粘贴以下命令到 shell 配置文件中（``.profile``， ``.bashrc``， ``.zprofile`` 等）
+    
+   .. code-block:: bash
+
+        alias get_idf='. $HOME/esp/esp-idf/export.sh'
+
+2. 通过重启终端窗口或运行 ``source [path to profile]``，如 ``source ~/.bashrc`` 来刷新配置文件。
+
+现在您可以在任何终端窗口中运行 ``get_idf`` 来设置或刷新 esp-idf 环境。
+
+这里不建议您直接将 ``export.sh`` 添加到 shell 的配置文件。因为这会导致在每个终端会话中都激活 IDF 虚拟环境（包括无需使用 IDF 的情况），从而破坏使用虚拟环境的目的，并可能影响其他软件的使用。

 .. _get-started-start-project:

@ -242,7 +257,7 @@ Linux 和 MacOS 操作系统

 将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下：

-Linux 和 MacOS 操作系统
+Linux 和 macOS 操作系统
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. code-block:: bash
@ -275,7 +290,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照

 - **Windows 操作系统：** ``COM1`` 等
 - **Linux 操作系统：** 以 ``/dev/tty`` 开始
- **MacOS 操作系统：** 以 ``/dev/cu.`` 开始
+- **macOS 操作系统：** 以 ``/dev/cu.`` 开始

 有关如何查看串口名称的详细信息，请见 :doc:`establish-serial-connection`。

@ -291,7 +306,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照

 请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。

-Linux 和 MacOS 操作系统
+Linux 和 macOS 操作系统
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. code-block:: bash
@ -316,14 +331,18 @@ Windows 操作系统

 工程配置 — 主窗口

+.. 注解::
+
+    您终端窗口中显示出的菜单颜色可能会与上图不同。您可以通过选项 ``--style`` 来改变外观。更多信息，请运行 ``idf.py menuconfig --help`` 命令。
+
+
 ``menuconfig`` 工具的常见操作见下。

 * 上下箭头：移动
 * ``回车``：进入子菜单
 * ``ESC 键``：返回上级菜单或退出
-* ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。
-* ``空格``或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项
-* ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单
+* ``英文问号``：调出菜单或选项的帮助菜单，按回车键可退出帮助菜单。
+* ``空格`` 或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项
 * ``/ 键``：寻找配置工程

 .. attention::
@ -343,23 +362,23 @@ Windows 操作系统

 .. code-block:: none

-    $ idf.py build
-    Running cmake in directory /path/to/hello_world/build
-    Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
-    Warn about uninitialized values.
-    -- Found Git:/usr/bin/git (found version "2.17.0")
-    -- Building empty aws_iot component due to configuration
-    -- Component names: ...
-    -- Component paths: ...
-
-    ... (more lines of build system output)
-
-    [527/527] Generating hello-world.bin
-    esptool.py v2.3.1
-
-    Project build complete. To flash, run this command:
-    ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
-    or run 'idf.py -p PORT flash'
+   $ idf.py build
+   Running cmake in directory /path/to/hello_world/build
+   Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
+   Warn about uninitialized values.
+   -- Found Git: /usr/bin/git (found version "2.17.0")
+   -- Building empty aws_iot component due to configuration
+   -- Component names: ...
+   -- Component paths: ...
+   
+   ... (more lines of build system output)
+   
+   [527/527] Generating hello-world.bin
+   esptool.py v2.3.1
+   
+   Project build complete. To flash, run this command:
+   ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
+   or run 'idf.py -p PORT flash'

 如果一切正常，编译完成后将生成 .bin 文件。

@ -416,10 +435,8 @@ Windows 操作系统

 如果一切顺利，烧录完成后，开发板将会复位，应用程序 "hello_world" 开始运行。

-.. note::
-
-    （目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse 指南 <eclipse-setup>`。

+.. （目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse 指南 <eclipse-setup>`。

 .. _get-started-build-monitor:

@ -489,11 +506,11 @@ Windows 操作系统

 乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 

-此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 <updating>` 章节查看。
+此外，您可以仅更新变更部分。具体方式取决于您使用的 ESP-IDF 版本，请前往 :ref:`更新 <updating>` 章节查看。

-注意，更新完成后，请执行 ``install.sh`` （Windows 系统中为 ``install.bat``）脚本，避免新版 ESP-IDF 所需的工具也有所更新。具体请参考 :ref:`get-started-set-up-tools`。
+注意，更新完成后，请再次运行安装脚本，以防新版 ESP-IDF 所需的工具也有所更新。具体请参考 :ref:`get-started-set-up-tools`。

-一旦重新安装好工具，请使用“导出脚本”更新环境，具体请参考 :ref:`get-started-set-up-env`。
+一旦重新安装好工具，请使用导出脚本更新环境，具体请参考 :ref:`get-started-set-up-env`。

 相关文档
 =================