diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 6597e1ef44..fe66e45a58 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -142,8 +142,8 @@ IDE .. toctree:: :maxdepth: 1 - Eclipse Plugin <../get-started/eclipse-setup> - VSCode Extension <../get-started/vscode-setup> + Eclipse Plugin + VSCode Extension Manual Installation ~~~~~~~~~~~~~~~~~~~ @@ -153,18 +153,12 @@ For the manual procedure, please select according to your operating system. .. toctree:: :maxdepth: 1 - Windows Installer <../get-started/windows-setup> - Linux and macOS <../get-started/linux-macos-setup> + Windows Installer + Linux and macOS Build Your First Project ======================== -If you already have the ESP-IDF installed and not using IDE, you can build your first project from the command line following :ref:`get-started-first-steps`. - -.. toctree:: - :hidden: - - Windows - Manual +If you already have the ESP-IDF installed and not using IDE, you can build your first project from the command line following the :ref:`Start a Project on Windows ` or :ref:`Start a Project on Linux and macOS`. .. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ diff --git a/docs/en/get-started/linux-macos-setup.rst b/docs/en/get-started/linux-macos-setup.rst index 9f4ee39f9d..814cb4c2c3 100644 --- a/docs/en/get-started/linux-macos-setup.rst +++ b/docs/en/get-started/linux-macos-setup.rst @@ -229,11 +229,12 @@ Technically, you can add ``export.sh`` to your shell's profile directly; however .. _get-started-build: .. _get-started-configure: .. _get-started-connect: -.. _get-started-first-steps: +.. _get-started-linux-macos-first-steps: Step 5. First Steps on ESP-IDF ============================== +.. include:: linux-macos-start-project.rst .. include:: start-project.rst Tip: Updating ESP-IDF diff --git a/docs/en/get-started/linux-macos-start-project.rst b/docs/en/get-started/linux-macos-start-project.rst new file mode 100644 index 0000000000..874aae6972 --- /dev/null +++ b/docs/en/get-started/linux-macos-start-project.rst @@ -0,0 +1,74 @@ +Now since all requirements are met, the next topic will guide you on how to start your first project. + +This guide will help you on the first steps using ESP-IDF. Follow this guide to start a new project on the {IDF_TARGET_NAME} and build, flash, and monitor the device output. + +.. note:: + + If you have not yet installed ESP-IDF, please go to :ref:`get-started-step-by-step` and follow the instruction in order to get all the software needed to use this guide. + +Start a Project +=================== + +Now you are ready to prepare your application for {IDF_TARGET_NAME}. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in ESP-IDF. + +.. important:: + + The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. + +Copy the project :example:`get-started/hello_world` to ``~/esp`` directory: + +.. code-block:: bash + + cd ~/esp + cp -r $IDF_PATH/examples/get-started/hello_world . + +.. note:: There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. It is also possible to build examples in-place without copying them first. + +Connect Your Device +=================== + +Now connect your {IDF_TARGET_NAME} board to the computer and check under which serial port the board is visible. + +Serial ports have the following naming patterns: + +- **Linux**: starting with ``/dev/tty`` +- **macOS**: starting with ``/dev/cu.`` + +If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details. + +.. note:: + + Keep the port name handy as you will need it in the next steps. + +Configure Your Project +====================== + +Navigate to your ``hello_world`` directory, set {IDF_TARGET_NAME} as the target, and run the project configuration utility ``menuconfig``. + +.. code-block:: bash + + cd ~/esp/hello_world + idf.py set-target {IDF_TARGET_PATH_NAME} + idf.py menuconfig + +After opening a new project, you should first set the target with ``idf.py set-target {IDF_TARGET_PATH_NAME}``. Note that existing builds and configurations in the project, if any, will be cleared and initialized in this process. The target may be saved in the environment variable to skip this step at all. See :ref:`selecting-idf-target` for additional information. + +If the previous steps have been done correctly, the following menu appears: + +.. figure:: ../../_static/project-configuration.png + :align: center + :alt: Project configuration - Home window + + Project configuration - Home window + +You are using this menu to set up project specific variables, e.g., Wi-Fi network name and password, the processor speed, etc. Setting up the project with menuconfig may be skipped for "hello_word", since this example runs with default configuration. + +.. only:: esp32 + + .. attention:: + + If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, or ESP32-DevKitM-1 board with the **ESP32-MIN1-1(1U)** module, please enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. + +.. note:: + + The colors of the menu could be different in your terminal. You can change the appearance with the option ``--style``. Please run ``idf.py menuconfig --help`` for further information. \ No newline at end of file diff --git a/docs/en/get-started/start-project.rst b/docs/en/get-started/start-project.rst index 5f3f62ff92..452ba35234 100644 --- a/docs/en/get-started/start-project.rst +++ b/docs/en/get-started/start-project.rst @@ -4,106 +4,6 @@ {IDF_TARGET_HEAP_SIZE:default="298968", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c3="337332"} -Now you have all requirements met, the next topic will guide you on how to start your first project. - -This guide will help you on the first steps using ESP-IDF. Follow this guide to start a new project on the {IDF_TARGET_NAME} and build, flash, and monitor the device output. - -.. note:: - - If you haven't yet installed the ESP-IDF, please go to :ref:`get-started-step-by-step` and follow the instruction in oder to get all the software needed to use this guide. - -Start a Project -=================== - -Now you are ready to prepare your application for {IDF_TARGET_NAME}. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. - -.. important:: - - The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. - -Copy the project :example:`get-started/hello_world` to ``~/esp`` directory: - -Windows -~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp - xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world - -Linux/macOS -~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp - cp -r $IDF_PATH/examples/get-started/hello_world . - -.. note:: There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. It is also possible to build examples in-place, without copying them first. - -Connect Your Device -=================== - -Now connect your {IDF_TARGET_NAME} board to the computer and check under what serial port the board is visible. - -Serial ports have the following patterns in their names: - -- **Windows**: names like ``COM1`` -- **Linux**: starting with ``/dev/tty`` -- **macOS**: starting with ``/dev/cu.`` - -If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details. - -.. note:: - - Keep the port name handy as you will need it in the next steps. - -Configure your Project -====================== - -Navigate to your ``hello_world`` directory, set {IDF_TARGET_NAME} chip as the target and run the project configuration utility ``menuconfig``. - -Windows -~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp\hello_world - idf.py set-target {IDF_TARGET_PATH_NAME} - idf.py menuconfig - -Linux/macOS -~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp/hello_world - idf.py set-target {IDF_TARGET_PATH_NAME} - idf.py menuconfig - -Setting the target with ``idf.py set-target {IDF_TARGET_PATH_NAME}`` should be done once after opening a new project. If the project contains some existing builds and configurations, they will be cleared and initialized. The target may be saved in the environment variable to skip this step at all. See :ref:`selecting-idf-target` for additional information. - -If the previous steps have been done correctly, the following menu appears: - -.. figure:: ../../_static/project-configuration.png - :align: center - :alt: Project configuration - Home window - :figclass: align-center - - Project configuration - Home window - -You are using this menu to set up project specific variables, e.g. Wi-Fi network name and password, the processor speed, etc. Setting up the project with menuconfig may be skipped for "hello_word". This example will run with default configuration. - -.. only:: esp32 - - .. attention:: - - If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, or ESP32-DevKitM-1 board with the **ESP32-MIN1-1(1U)** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. - -.. note:: - - The colors of the menu could be different in your terminal. You can change the appearance with the option ``--style``. Please run ``idf.py menuconfig --help`` for further information. - Build the Project ================= diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index 5168b91380..958959394b 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -109,6 +109,9 @@ Note that this shortcut is specific to the ESP-IDF directory selected in the ESP First Steps on ESP-IDF ====================== +.. _get-started-windows-first-steps: + +.. include:: windows-start-project.rst .. include:: start-project.rst Related Documents diff --git a/docs/en/get-started/windows-start-project.rst b/docs/en/get-started/windows-start-project.rst new file mode 100644 index 0000000000..a78fa06276 --- /dev/null +++ b/docs/en/get-started/windows-start-project.rst @@ -0,0 +1,74 @@ +Now since all requirements are met, the next topic will guide you on how to start your first project. + +This guide will help you on the first steps using ESP-IDF. Follow this guide to start a new project on the {IDF_TARGET_NAME} and build, flash, and monitor the device output. + +.. note:: + + If you have not yet installed ESP-IDF, please go to :ref:`get-started-step-by-step` and follow the instruction in order to get all the software needed to use this guide. + +Start a Project +=================== + +Now you are ready to prepare your application for {IDF_TARGET_NAME}. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in ESP-IDF. + +.. important:: + + The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. + +Copy the project :example:`get-started/hello_world` to ``~/esp`` directory: + +.. code-block:: batch + + cd %userprofile%\esp + xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world + +.. note:: There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. It is also possible to build examples in-place without copying them first. + +Connect Your Device +=================== + +Now connect your {IDF_TARGET_NAME} board to the computer and check under which serial port the board is visible. + +Serial port names start with ``COM`` in Windows. + +If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details. + +.. note:: + + Keep the port name handy as you will need it in the next steps. + +Configure Your Project +====================== + +Navigate to your ``hello_world`` directory, set {IDF_TARGET_NAME} as the target, and run the project configuration utility ``menuconfig``. + +Windows +~~~~~~~ + +.. code-block:: batch + + cd %userprofile%\esp\hello_world + idf.py set-target {IDF_TARGET_PATH_NAME} + idf.py menuconfig + +After opening a new project, you should first set the target with ``idf.py set-target {IDF_TARGET_PATH_NAME}``. Note that existing builds and configurations in the project, if any, will be cleared and initialized in this process. The target may be saved in the environment variable to skip this step at all. See :ref:`selecting-idf-target` for additional information. + +If the previous steps have been done correctly, the following menu appears: + +.. figure:: ../../_static/project-configuration.png + :align: center + :alt: Project configuration - Home window + + Project configuration - Home window + +You are using this menu to set up project specific variables, e.g., Wi-Fi network name and password, the processor speed, etc. Setting up the project with menuconfig may be skipped for "hello_word", since this example runs with default configuration. + +.. only:: esp32 + + .. attention:: + + If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, or ESP32-DevKitM-1 board with the **ESP32-MIN1-1(1U)** module, please enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. + +.. note:: + + The colors of the menu could be different in your terminal. You can change the appearance with the option ``--style``. Please run ``idf.py menuconfig --help`` for further information. \ No newline at end of file diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index f61c0b41d8..43cc97f273 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -142,8 +142,8 @@ IDE .. toctree:: :maxdepth: 1 - Eclipse Plugin <../get-started/eclipse-setup> - VSCode Extension <../get-started/vscode-setup> + Eclipse Plugin + VSCode Extension 手动安装 ~~~~~~~~~~~~~~~~~~~ @@ -153,18 +153,14 @@ IDE .. toctree:: :maxdepth: 1 - Windows Installer <../get-started/windows-setup> - Linux and macOS <../get-started/linux-macos-setup> + Windows Installer + Linux and macOS 编译第一个工程 =================== +.. + Please translate -如果您已经安装好 ESP-IDF 且没有使用集成开发环境 (IDE)，请在命令提示行中按照 :ref:`get-started-first-steps` 编译第一个工程。 - -.. toctree:: - :hidden: - - Windows - Manual +If you already have the ESP-IDF installed and not using IDE, you can build your first project from the command line following the :ref:`Start a Project on Windows ` or :ref:`Start a Project on Linux and macOS`. .. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ diff --git a/docs/zh_CN/get-started/linux-macos-setup.rst b/docs/zh_CN/get-started/linux-macos-setup.rst index cfc8a6c98e..7f4512416b 100644 --- a/docs/zh_CN/get-started/linux-macos-setup.rst +++ b/docs/zh_CN/get-started/linux-macos-setup.rst @@ -229,11 +229,12 @@ ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具， .. _get-started-build: .. _get-started-configure: .. _get-started-connect: -.. _get-started-first-steps: +.. _get-started-linux-macos-first-steps: 第五步：开始使用 ESP-IDF 吧 ======================================== +.. include:: linux-macos-start-project.rst .. include:: start-project.rst 建议：更新 ESP-IDF diff --git a/docs/zh_CN/get-started/linux-macos-start-project.rst b/docs/zh_CN/get-started/linux-macos-start-project.rst new file mode 100644 index 0000000000..e5db125094 --- /dev/null +++ b/docs/zh_CN/get-started/linux-macos-start-project.rst @@ -0,0 +1,74 @@ +现在您已经具备了使用 ESP-IDF 的所有条件，接下来将介绍如何开始您的第一个工程。 + +本指南将帮助您完成使用 ESP-IDF 的第一步。按照本指南，您将使用 {IDF_TARGET_NAME} 创建第一个工程，并构建、烧录和监控设备输出。 + +.. note:: + + 如果您还未安装 ESP-IDF，请参照 :ref:`get-started-step-by-step` 中的步骤，获取使用本指南所需的所有软件。 + +开始创建工程 +================ + +现在，您可以准备开发 {IDF_TARGET_NAME} 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 + +.. important:: + + ESP-IDF 编译系统不支持 ESP-IDF 路径或其工程路径中带有空格。 + +将 :example:`get-started/hello_world` 工程复制至您本地的 ``~/esp`` 目录下： + +.. code-block:: bash + + cd ~/esp + cp -r $IDF_PATH/examples/get-started/hello_world . + +.. note:: ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，您可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。 + +连接设备 +============== + +现在，请将您的 {IDF_TARGET_NAME} 开发板连接到 PC，并查看开发板使用的串口。 + +通常，串口在不同操作系统下显示的名称有所不同： + +- **Linux 操作系统：** 以 ``/dev/tty`` 开头 +- **macOS 操作系统：** 以 ``/dev/cu.`` 开头 + +有关如何查看串口名称的详细信息，请见 :doc:`establish-serial-connection`。 + +.. note:: + + 请记住串口名，您会在后续步骤中使用。 + +配置工程 +============= + +请进入 ``hello_world`` 目录，设置 {IDF_TARGET_NAME} 为目标芯片，然后运行工程配置工具 ``menuconfig``。 + +.. code-block:: bash + + cd ~/esp/hello_world + idf.py set-target {IDF_TARGET_PATH_NAME} + idf.py menuconfig + +打开一个新工程后，应首先使用 ``idf.py set-target {IDF_TARGET_PATH_NAME}`` 设置“目标”芯片。注意，此操作将清除并初始化项目之前的编译和配置（如有）。您也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见 :ref:`selecting-idf-target`。 + +正确操作上述步骤后，系统将显示以下菜单： + +.. figure:: ../../_static/project-configuration.png + :align: center + :alt: 工程配置 — 主窗口 + + 工程配置 — 主窗口 + +您可以通过此菜单设置项目的具体变量，包括 Wi-Fi 网络名称、密码和处理器速度等。``hello_world`` 示例项目会以默认配置运行，因此在这一项目中，可以跳过使用 ``menuconfig`` 进行项目配置这一步骤。 + +.. only:: esp32 + + .. attention:: + + 如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组）或 ESP32-DevKitM-1（板载 ESP32-MINI-1(1U) 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。 + +.. note:: + + 您终端窗口中显示出的菜单颜色可能会与上图不同。您可以通过选项 ``--style`` 来改变外观。请运行 ``idf.py menuconfig --help`` 命令，获取更多信息。 \ No newline at end of file diff --git a/docs/zh_CN/get-started/start-project.rst b/docs/zh_CN/get-started/start-project.rst index 62774b2d5d..b5eef81131 100644 --- a/docs/zh_CN/get-started/start-project.rst +++ b/docs/zh_CN/get-started/start-project.rst @@ -4,106 +4,6 @@ {IDF_TARGET_HEAP_SIZE:default="298968", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c3="337332"} -现在您已经具备了使用 ESP-IDF 的所有条件，接下来将介绍如何开始您的第一个工程。 - -本指南将帮助您完成使用 ESP-IDF 的第一步。按照本指南，您将能使用 {IDF_TARGET_NAME} 开始创建第一个工程，并构建、烧录和监控设备输出。 - -.. note:: - - 如果您还没有安装 ESP-IDF，请前往 :ref:`get-started-step-by-step` 并按照说明操作，以获得使用本指南所需的所有软件。 - -开始创建工程 -================ - -现在，您可以开始准备开发 {IDF_TARGET_NAME} 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 - -.. important:: - - ESP-IDF 编译系统不支持 ESP-IDF 路径或其工程路径中带有空格。 - -将 :example:`get-started/hello_world` 工程复制至您本地的 ``~/esp`` 目录下： - -Windows 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp - xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world - -Linux 和 macOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp - cp -r $IDF_PATH/examples/get-started/hello_world . - -.. note:: ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，您可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。 - -连接设备 -============== - -现在，请将您的 {IDF_TARGET_NAME} 开发板连接到 PC，并查看开发板使用的串口。 - -通常，串口在不同操作系统下显示的名称有所不同： - -- **Windows 操作系统：** ``COM1`` 等 -- **Linux 操作系统：** 以 ``/dev/tty`` 开始 -- **macOS 操作系统：** 以 ``/dev/cu.`` 开始 - -有关如何查看串口名称的详细信息，请见 :doc:`establish-serial-connection`。 - -.. note:: - - 请记住串口名，您会在后续步骤中使用。 - -配置工程 -============= - -请进入 ``hello_world`` 目录，设置 {IDF_TARGET_NAME} 为目标芯片，然后运行工程配置工具 ``menuconfig``。 - -Windows 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp\hello_world - idf.py set-target {IDF_TARGET_PATH_NAME} - idf.py menuconfig - -Linux 和 macOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp/hello_world - idf.py set-target {IDF_TARGET_PATH_NAME} - idf.py menuconfig - -打开一个新工程后，应首先使用 ``idf.py set-target {IDF_TARGET_PATH_NAME}`` 设置“目标”芯片。注意，此操作将清除并初始化项目之前的编译和配置（如有）。 您也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见 :ref:`selecting-idf-target`。 - -如果之前的步骤都正确，则会显示下面的菜单： - -.. figure:: ../../_static/project-configuration.png - :align: center - :alt: 工程配置 — 主窗口 - :figclass: align-center - - 工程配置 — 主窗口 - -您可以通过此菜单设置项目的具体变量，包括 Wi-Fi 网络名称、密码和处理器速度等。``hello_world`` 示例项目会以默认配置运行，因此可以跳过使用 ``menuconfig`` 进行项目配置这一步骤。 - -.. only:: esp32 - - .. attention:: - - 如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组）或 ESP32-DevKitM-1（板载 ESP32-MINI-1(1U) 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。 - -.. note:: - - 您终端窗口中显示出的菜单颜色可能会与上图不同。您可以通过选项 ``--style`` 来改变外观。请运行 ``idf.py menuconfig --help`` 命令，获取更多信息。 - 编译工程 ========================= diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index 9962acdd1b..dafe5e0287 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -109,6 +109,9 @@ ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF 开始使用 ESP-IDF ======================== +.. _get-started-windows-first-steps: + +.. include:: windows-start-project.rst .. include:: start-project.rst 相关文档 diff --git a/docs/zh_CN/get-started/windows-start-project.rst b/docs/zh_CN/get-started/windows-start-project.rst new file mode 100644 index 0000000000..e6c846c0ed --- /dev/null +++ b/docs/zh_CN/get-started/windows-start-project.rst @@ -0,0 +1,71 @@ +现在您已经具备了使用 ESP-IDF 的所有条件，接下来将介绍如何开始您的第一个工程。 + +本指南将帮助您完成使用 ESP-IDF 的第一步。按照本指南，您将使用 {IDF_TARGET_NAME} 创建第一个工程，并构建、烧录和监控设备输出。 + +.. note:: + + 如果您还未安装 ESP-IDF，请参照 :ref:`get-started-step-by-step` 中的步骤，获取使用本指南所需的所有软件。 + +开始创建工程 +================ + +现在，您可以准备开发 {IDF_TARGET_NAME} 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 + +.. important:: + + ESP-IDF 编译系统不支持 ESP-IDF 路径或其工程路径中带有空格。 + +将 :example:`get-started/hello_world` 工程复制至您本地的 ``~/esp`` 目录下： + +.. code-block:: batch + + cd %userprofile%\esp + xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world + +.. note:: ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，您可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。 + +连接设备 +============== + +现在，请将您的 {IDF_TARGET_NAME} 开发板连接到 PC，并查看开发板使用的串口。 + +在 Windows 操作系统中，串口名称通常以 ``COM`` 开头。 + +有关如何查看串口名称的详细信息，请见 :doc:`establish-serial-connection`。 + +.. note:: + + 请记住串口名，您会在后续步骤中使用。 + +配置工程 +============= + +请进入 ``hello_world`` 目录，设置 {IDF_TARGET_NAME} 为目标芯片，然后运行工程配置工具 ``menuconfig``。 + +.. code-block:: batch + + cd %userprofile%\esp\hello_world + idf.py set-target {IDF_TARGET_PATH_NAME} + idf.py menuconfig + +打开一个新工程后，应首先使用 ``idf.py set-target {IDF_TARGET_PATH_NAME}`` 设置“目标”芯片。注意，此操作将清除并初始化项目之前的编译和配置（如有）。您也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见 :ref:`selecting-idf-target`。 + +正确操作上述步骤后，系统将显示以下菜单： + +.. figure:: ../../_static/project-configuration.png + :align: center + :alt: 工程配置 — 主窗口 + + 工程配置 — 主窗口 + +您可以通过此菜单设置项目的具体变量，包括 Wi-Fi 网络名称、密码和处理器速度等。``hello_world`` 示例项目会以默认配置运行，因此在这一项目中，可以跳过使用 ``menuconfig`` 进行项目配置这一步骤。 + +.. only:: esp32 + + .. attention:: + + 如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组）或 ESP32-DevKitM-1（板载 ESP32-MINI-1(1U) 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。 + +.. note:: + + 您终端窗口中显示出的菜单颜色可能会与上图不同。您可以通过选项 ``--style`` 来改变外观。请运行 ``idf.py menuconfig --help`` 命令，获取更多信息。 \ No newline at end of file