Also clean up some changes in Chinese CMake guide which were not propagated from the English guide.
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
+.. include:: /_build/inc/version-note.inc
+
Introduction
============
Linux and MacOS
~~~~~~~~~~~~~~~
-.. code-block:: bash
+To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command:
- mkdir -p ~/esp
- cd ~/esp
- git clone --recursive https://github.com/espressif/esp-idf.git
+.. include:: /_build/inc/git-clone-bash.inc
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
+Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
-.. code-block:: batch
+.. include:: /_build/inc/git-clone-windows.inc
- mkdir %userprofile%\esp
- cd %userprofile%\esp
- git clone --recursive https://github.com/espressif/esp-idf.git
+ESP-IDF will be downloaded into ``esp\esp-idf`` in the user's profile directory.
+
+Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.
+
+.. include:: /_build/inc/git-clone-notes.inc
.. highlight:: bash
.. note::
Configure
=========
-Naviagate to the directory of the ``hello_world`` application copy, and run the ``menuconfig`` project configuration utility:
+Navigate to the directory of the ``hello_world`` application copy, and run the ``menuconfig`` project configuration utility:
Linux and MacOS
~~~~~~~~~~~~~~~
After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf-cmake`.
-Another solution is to update only what has changed. This method is useful if you have a slow connection to GitHub. To do the update run the following commands:
-
-Linux and MacOS
-~~~~~~~~~~~~~~~
-
-.. code-block:: bash
-
- cd ~/esp/esp-idf
- git pull
- git submodule update --init --recursive
-
-Windows Command Prompt
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: batch
-
- cd %userprofile%\esp\esp-idf
- git pull
- git submodule update --init --recursive
-
-The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
-
-.. highlight:: bash
-
-It is also possible to check out a specific release of ESP-IDF, e.g. `v2.1`.
-
-Linux and MacOS
-~~~~~~~~~~~~~~~
+If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts know where to find the ESP-IDF in its release specific location.
-.. code-block:: bash
-
- cd ~/esp
- git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
- cd esp-idf-v2.1/
- git checkout v2.1
- git submodule update --init --recursive
-
-
-Windows Command Prompt
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: batch
-
- cd %userprofile%\esp
- git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
- cd esp-idf-v2.1/
- git checkout v2.1
- git submodule update --init --recursive
-
-After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
-
-.. note::
-
- Different versions of ESP-IDF may have different setup or prerequisite requirements, or require different toolchain versions. If you experience any problems, carefully check the Getting Started documentation for the version you are switching to.
+Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
Related Documents
eclipse-setup
idf-monitor
toolchain-setup-scratch
+
+.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
+.. _Releases page: https://github.com/espressif/esp-idf/releases
\r
Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.\r
\r
-.. include:: /_build/inc/git-clone.inc\r
+To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command:\r
+\r
+.. include:: /_build/inc/git-clone-bash.inc\r
+\r
+ESP-IDF will be downloaded into ``~/esp/esp-idf``.\r
\r
Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.\r
\r
+.. include:: /_build/inc/git-clone-notes.inc\r
+\r
.. note::\r
\r
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::\r
\r
- cd ~/esp/esp-idf\r
+ cd esp-idf\r
git submodule update --init --recursive\r
\r
-\r
.. _get-started-setup-path:\r
\r
Setup Path to ESP-IDF\r
TEMPLATES = {
"en": {
- "git-clone": {
- "template": """
-To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command::
+ "git-clone-bash": """
+.. code-block:: bash
cd ~/esp
git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
+ """,
+
+ "git-clone-windows": """
+.. code-block:: batch
-ESP-IDF will be downloaded into ``~/esp/esp-idf``.
+ mkdir %%userprofile%%\\esp
+ cd %%userprofile%%\\esp
+ git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
+ """,
+ "git-clone-notes": {
+ "template": """
.. note::
%(extra_note)s
%(zipfile_note)s
""",
"master": 'This command will clone the master branch, which has the latest development ("bleeding edge") '
- 'version of ESP-IDF. It is fully functional and updated on weekly basis with the most recent features and bugfixes.',
- "branch": 'The ``git clone`` option ``-b %(clone_arg)s`` tells git to clone the %(ver_type)s in the ESP-IDF repository '
- 'corresponding to this version of the documentation.',
+ 'version of ESP-IDF. It is fully functional and updated on weekly basis with the most recent features and bugfixes.',
+ "branch": 'The ``git clone`` option ``-b %(clone_arg)s`` tells git to clone the %(ver_type)s in the ESP-IDF repository ``git clone`` '
+ 'corresponding to this version of the documentation.',
"zipfile": {
"stable": 'As a fallback, it is also possible to download a zip file of this stable release from the `Releases page`_. '
'Do not download the "Source code" zip file(s) generated automatically by GitHub, they do not work with ESP-IDF.',
"unstable": 'GitHub\'s "Download zip file" feature does not work with ESP-IDF, a ``git clone`` is required. As a fallback, '
'`Stable version`_ can be installed without Git.'
}, # zipfile
- }, # git-clone
+ }, # git-clone-notes
"version-note": {
"master": """
.. note::
}, # version-note
}, # en
"zh_CN": {
- "git-clone": {
- "template": """
-获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库::
+ "git-clone-bash": """
+.. code-block:: bash
cd ~/esp
git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
+ """,
+
+ "git-clone-windows": """
+.. code-block:: batch
-ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
+ mkdir %%userprofile%%\\esp
+ cd %%userprofile%%\\esp
+ git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
+ """,
+ "git-clone-notes": {
+ "template": """
.. note::
%(extra_note)s
version, ver_type, is_stable = get_version()
- write_git_clone_inc(template["git-clone"], out_dir, version, ver_type, is_stable)
+ write_git_clone_inc_files(template, out_dir, version, ver_type, is_stable)
write_version_note(template["version-note"], out_dir, version, ver_type, is_stable)
print("Done")
-def write_git_clone_inc(template, out_dir, version, ver_type, is_stable):
- zipfile = template["zipfile"]
+def write_git_clone_inc_files(templates, out_dir, version, ver_type, is_stable):
+ def out_file(basename):
+ p = os.path.join(out_dir, "%s.inc" % basename)
+ print("Writing %s..." % p)
+ return p
+
if version == "master":
- args = {
- "clone_args": "",
- "extra_note": template["master"],
- "zipfile_note": zipfile["unstable"]
- }
+ clone_args = ""
else:
- args = {
- "clone_args": "-b %s " % version,
- "extra_note": template["branch"] % {"clone_arg": version, "ver_type": ver_type},
- "zipfile_note": zipfile["stable"] if is_stable else zipfile["unstable"]
- }
- out_file = os.path.join(out_dir, "git-clone.inc")
- with open(out_file, "w", encoding='utf-8') as f:
- f.write(template["template"] % args)
- print("%s written" % out_file)
+ clone_args = "-b %s " % version
+
+ with open(out_file("git-clone-bash"), "w", encoding="utf-8") as f:
+ f.write(templates["git-clone-bash"] % locals())
+
+ with open(out_file("git-clone-windows"), "w", encoding="utf-8") as f:
+ f.write(templates["git-clone-windows"] % locals())
+
+ with open(out_file("git-clone-notes"), "w", encoding="utf-8") as f:
+ template = templates["git-clone-notes"]
+
+ zipfile = template["zipfile"]
+
+ if version == "master":
+ extra_note = template["master"],
+ zipfile_note = zipfile["unstable"]
+ else:
+ extra_note = template["branch"] % {"clone_arg": version, "ver_type": ver_type}
+ zipfile_note = zipfile["stable"] if is_stable else zipfile["unstable"]
+
+ f.write(template["template"] % locals())
+
+ print("Wrote git-clone-xxx.inc files")
def write_version_note(template, out_dir, version, ver_type, is_stable):
\r
本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子，说明 ESP-IDF (Espressif IoT Development Framework) 的使用方法，包括配置、编译、下载固件到开发板等步骤。\r
\r
+.. include:: /_build/inc/version-note.inc\r
+\r
概述\r
============\r
\r
Linux 和 MacOS\r
~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
\r
-.. code-block:: bash\r
+获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库:\r
\r
- mkdir -p ~/esp\r
- cd ~/esp\r
- git clone --recursive https://github.com/espressif/esp-idf.git\r
+.. include:: /_build/inc/git-clone-bash.inc\r
\r
ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。\r
\r
+有关在给定情况下使用哪个 ESP-IDF 版本的信息，请参阅 :doc:`/versions` 。\r
\r
Windows Command Prompt\r
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
\r
-.. code-block:: batch\r
+.. include:: /_build/inc/git-clone-windows.inc\r
\r
- mkdir %userprofile%\esp\r
- cd %userprofile%\esp\r
- git clone --recursive https://github.com/espressif/esp-idf.git\r
+ESP-IDF 将会被下载到用户的 ``esp\esp-idf`` 目录下。\r
+\r
+有关在给定情况下使用哪个 ESP-IDF 版本的信息，请参阅 :doc:`/versions` 。\r
+\r
+.. include:: /_build/inc/git-clone-notes.inc\r
\r
.. highlight:: bash\r
.. note::\r
cd esp-idf\r
git submodule update --init\r
\r
-.. note::\r
-\r
- 基于 CMake 的构建系统预览默认使用的 Git 分支是 ``feature/cmake``。如果你在克隆时没有带 ``--branch`` 选项，可通过以下命令行切换分支::\r
-\r
- cd esp-idf\r
- git checkout feature/cmake\r
-\r
.. _get-started-setup-path-cmake:\r
\r
设置环境变量\r
\r
你需在你的电脑中设置这两个变量，否则工程将不能编译。\r
\r
-你可以在每次 PC 重启时手动设置，你也可以在用户配置中进行永久设置，具体请参照 :doc:`add-idf_path-to-profile` 小节中的 :ref:`Windows <add-paths-to-profile-windows-cmake>`，:ref:`Linux 和 MacOS <add-idf_path-to-profile-linux-macos-cmake>` 相关指导进行操作。 \r
+你可以在每次 PC 重启时手动设置，你也可以在用户配置中进行永久设置，具体请参照 :doc:`add-idf_path-to-profile` 小节中的 :ref:`Windows <add-paths-to-profile-windows-cmake>`，:ref:`Linux 和 MacOS <add-idf_path-to-profile-linux-macos-cmake>` 相关指导进行操作。\r
\r
.. _get-started-start-project-cmake:\r
\r
* 当光标在某个配置项上面高亮时，输入 ``?`` 可以直接查看该项的帮助信息\r
* 输入 ``/`` 搜索配置项\r
\r
+.. attention::\r
+\r
+ 如果 ESP32-DevKitC 板载的是 ESP32-SOLO-1 模组，请务必在烧写示例程序之前在 menuconfig 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。\r
+\r
.. _get-started-build-cmake:\r
\r
创建一个工程\r
\r
\r
更新 ESP-IDF\r
-=========================\r
-\r
-ESP-IDF 使用一段时间后，你可能想要进行升级来获得新的性能或者对 bug 进行修复。最简单的更新方式是删除已有的 ``esp-idf`` 文件夹然后再克隆一个，即重复 :ref:`get-started-get-esp-idf-cmake` 小节中所述的初始安装即可。\r
-\r
-另外一种方法是只更新有改动的部分，此方法适合连接 GitHub 比较缓慢的情况。你只需运行如下指令： \r
-\r
-Linux 和 MacOS\r
-~~~~~~~~~~~~~~~~~~~~~~~~~\r
-\r
-.. code-block:: bash\r
-\r
- cd ~/esp/esp-idf\r
- git pull\r
- git submodule update --init --recursive\r
-\r
-Windows Command Prompt\r
-~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+=============\r
\r
-.. code-block:: batch\r
+使用 ESP-IDF 一段时间后，您可能想通过升级来获取新的功能或者修复 bug，最简单的升级方式就是删除已有的 ``esp-idf`` 文件夹然后重新克隆一个，即重复 :ref:`get-started-get-esp-idf` 里的操作。\r
\r
- cd %userprofile%\esp\esp-idf\r
- git pull\r
- git submodule update --init --recursive\r
-\r
-``git pull`` 命令将获取和合并 GitHub 上对 ESP-IDF 仓库所做的更改。``git submodule update --init --recursive`` 命令会更新现有子模块或拷贝更新的子模块。GitHub 上的子模块是指向其他仓库的链接，需要以下额外命令将其指向你的电脑。\r
-\r
-.. highlight:: bash\r
-\r
-你还可以查看具体发布的 ESP-IDF 版本，如 `v2.1`。\r
-\r
-Linux 和 MacOS\r
-~~~~~~~~~~~~~~~~~~~~\r
-\r
-.. code-block:: bash\r
-\r
- cd ~/esp\r
- git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1\r
- cd esp-idf-v2.1/\r
- git checkout v2.1\r
- git submodule update --init --recursive\r
-\r
-\r
-Windows Command Prompt\r
-~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
-\r
-.. code-block:: batch\r
-\r
- cd %userprofile%\esp\r
- git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1\r
- cd esp-idf-v2.1/\r
- git checkout v2.1\r
- git submodule update --init --recursive\r
-\r
-注意 :doc:`add-idf_path-to-profile`，这样工具链脚本就能够知道这一版本的 ESP-IDF 的具体位置。\r
-\r
-.. note::\r
-\r
- ESP-IDF 版本不同，其设置、必备要求或所需工具链版本也会有所不同。如果你有任何问题，请仔细对照快速入门文档查看你将使用版本的相应要求。\r
+然后 :doc:`添加 IDF 到工作路径 <add-idf_path-to-profile>`，这样工具链脚本就能够知道这一版本的 ESP-IDF 的具体位置。\r
\r
+另外一种方法是只更新有改动的部分。:ref:`更新步骤取决于现在用的ESP-IDF版本 <updating>`。\r
\r
相关文档\r
=================\r
eclipse-setup\r
idf-monitor\r
toolchain-setup-scratch\r
+\r
+.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/\r
+.. _Releases page: https://github.com/espressif/esp-idf/releases\r
***********
:link_to_translation:`en:[English]`
-.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
-
本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子来说明如何使用 ESP-IDF (Espressif IoT Development Framework)，包括配置、编译、下载固件到开发板等步骤。
.. include:: /_build/inc/version-note.inc
工具链（包括用于编译和构建应用程序的程序）安装完后，你还需要 ESP32 相关的 API/库。API/库在 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_ 中。
-.. include:: /_build/inc/git-clone.inc
+获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库:
+
+.. include:: /_build/inc/git-clone-bash.inc
+
+ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
-æ\9f¥ç\9c\8b :doc:/versions 以è\8e·å\8f\96ä¸\8då\90\8cæ\83\85å\86µä¸\8bé\80\89æ\8b©è¦\81使ç\94¨ç\9a\84å\88\86æ\94¯ç\9a\84帮å\8a©。
+æ\9c\89å\85³å\9c¨ç»\99å®\9aæ\83\85å\86µä¸\8b使ç\94¨å\93ªä¸ª ESP-IDF ç\89\88æ\9c¬ç\9a\84ä¿¡æ\81¯ï¼\8c请å\8f\82é\98\85 :doc:`/versions` 。
.. note::
注意这里有个 ``--recursive`` 选项。如果你克隆 ESP-IDF 时没有带这个选项，你还需要运行额外的命令来获取子模块： ::
- cd ~/esp/esp-idf
+ cd esp-idf
git submodule update --init
+.. include:: /_build/inc/git-clone-notes.inc
.. _get-started-setup-path:
* 当光标在某个配置项上面高亮时，输入 ``?`` 可以直接查看该项的帮助信息
* 输入 ``/`` 搜索配置项
-.. note::
-
- 如果你是 **Arch Linux** 用户，需要进入 ``SDK tool configuration`` 将 ``Python 2 interpreter`` 从 ``python`` 修改为 ``python2``。
-
.. attention::
- 如果 ESP32-DevKitC 板载的是 ESP32-SOLO-1 模组，请务必在烧写示例程序之前在 menuconfig 中使能单核模式（:ref:CONFIG_FREERTOS_UNICORE）。
+ 如果 ESP32-DevKitC 板载的是 ESP32-SOLO-1 模组，请务必在烧写示例程序之前在 menuconfig 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。
.. _get-started-build-flash:
projects / esp-idf / commitdiff