OVMS3-idf/docs/zh_CN/get-started/index.rst
Ivan Grokhotkov e1ac237169 Merge branch 'doc/fix_config_links' into 'master'
doc: Fix config links, add navigation lists to config items page

See merge request idf/esp-idf!3310
2018-09-25 18:23:24 +08:00

337 lines
12 KiB
ReStructuredText
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

***********
快速入门
***********
: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 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案,集成了高性能的 CPU 内核、超低功耗协处理器和丰富的外设。ESP32 采用 40 nm 工艺制成,具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性,适用于各种应用和不同功耗需求。
乐鑫为用户提供完整的软、硬件资源进行 ESP32 设备的开发。乐鑫所研发的软件开发环境 ESP-IDF 能够帮助用户快速开发物联网 (IoT) 应用,满足用户对于 Wi-Fi、蓝牙、低功耗等性能的需求。
准备工作
=========
开发 ESP32 应用程序需要准备:
* **电脑**:安装 Windows、Linux 或者 Mac 操作系统
* **工具链**:用于编译 ESP32 **应用程序**
* **ESP-IDF**:包含 ESP32 API 和用于操作 **工具链** 的脚本
* **文本编辑器**:编写 C 语言程序,例如 `Eclipse <http://www.eclipse.org/>`_
* **ESP32 开发板** 和将其连接到 **电脑****USB 线**
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
开发应用程序
开发环境的准备工作包括以下三部分:
1. 设置 **工具链**
2. 从 GitHub 上获取 **ESP-IDF**
3. 安装和配置 **Eclipse**
如果你偏好使用其它编辑器,可以跳过最后一步。
环境设置好后,就可以开始开发应用程序了。整个过程可以概括为如下四步:
1. 配置 **工程** 并编写代码
2. 编译 **工程** 并链接成一个 **应用程序**
3. 烧写 **应用程序****ESP32**
4. 监视/调试 **应用程序**
下文将全程指导你操作完成这些步骤。
开发板指南
==========
如果你有下列任一 ESP32 开发板,请点击对应的链接,对照指南进行操作就可以让你的板子跑起来。
.. toctree::
:maxdepth: 1
ESP32 DevKitC <../get-started/get-started-devkitc>
ESP-WROVER-KIT <../get-started/get-started-wrover-kit>
ESP32-PICO-KIT <../get-started/get-started-pico-kit>
如果你使用其它开发板,请查看下面的内容。
.. _get-started-setup-toolchain:
设置工具链
===============
用 ESP32 进行开发最快的方法是安装预编译的工具链。请根据你的操作系点击对应的链接,并按照链接中的指导进行安装。
.. toctree::
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: macos-setup.html
.. _Windows: windows-setup.html
.. _Linux: linux-setup.html
.. _Mac OS: macos-setup.html
.. note::
我们使用 ``~/esp`` 目录来安装预编译的工具链、ESP-IDF 和示例程序。你也可以使用其它目录,但是需要注意调整相应的指令。
你可以安装预编译的工具链或者自定义你的环境,这完全取决于个人经验和偏好。如果你要自定义环境,请参考 :ref:`get-started-customized-setup`
工具链设置完成后,就可以 :ref:`get-started-get-esp-idf` 了。
.. _get-started-get-esp-idf:
获取 ESP-IDF
=================
.. highlight:: bash
工具链(包括用于编译和构建应用程序的程序)安装完后,你还需要 ESP32 相关的 API/库。API/库在 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_ 中。
.. include:: /_build/inc/git-clone.inc
查看 :doc:/versions 以获取不同情况下选择要使用的分支的帮助。
.. note::
注意这里有个 ``--recursive`` 选项。如果你克隆 ESP-IDF 时没有带这个选项,你还需要运行额外的命令来获取子模块: ::
cd ~/esp/esp-idf
git submodule update --init
.. _get-started-setup-path:
设置 ESP-IDF 路径
=====================
工具链程序使用环境变量 ``IDF_PATH`` 来访问 ESP-IDF。这个变量应该设置在你的 PC 中,否则工程将不能编译。你可以在每次 PC 重启时手工设置,也可以通过在用户配置文件中定义 ``IDF_PATH`` 变量来永久性设置。要永久性设置,请参考 :doc:`add-idf_path-to-profile` 文档中 :ref:`Windows <add-idf_path-to-profile-windows>`:ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` 相关的指导进行操作。
.. _get-started-get-packages:
安装依赖的 Python 软件包
====================================
ESP-IDF 所依赖的 Python 软件包位于 ``$IDF_PATH/requirements.txt`` 文件中,您可以通过运行以下命令来安装它们:
.. code:: bash
python -m pip install --user -r $IDF_PATH/requirements.txt
.. note::
请调用 ESP-IDF 使用的相同版本的 Python 解释器,解释器的版本号可以通过运行命令 ``python --version`` 来获得,根据结果,您可能要使用 ``python2``, ``python2.7`` 或者类似的名字而不是 ``python``,例如::
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
.. _get-started-start-project:
创建一个工程
===============
现在可以开始创建 ESP32 应用程序了。为了快速开始,我们这里以 IDF 的 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程为例进行说明。
:example:`get-started/hello_world` 拷贝到 ``~/esp`` 目录: ::
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程,都可以按照上面的方法进行创建。
.. important::
esp-idf 构建系统不支持在路径中存在空格。
.. _get-started-connect:
连接
=======
还有几个步骤就完成了。在继续后续操作前,先将 ESP32 开发板连接到 PC然后检查串口号看看它能否正常通信。如果你不知道如何操作请查看 Establish Serial Connection with ESP32 中的相关指导。请注意一下端口号,我们在下一步中会用到。
.. _get-started-configure:
配置
=========
在终端窗口中,输入 ``cd ~/esp/hello_world`` 进入 ``hello_world`` 所在目录,然后启动工程配置工具 ``menuconfig`` ::
cd ~/esp/hello_world
make menuconfig
如果之前的步骤都正确,则会显示下面的菜单:
.. figure:: ../../_static/project-configuration.png
:align: center
:alt: Project configuration - Home window
:figclass: align-center
工程配置 - 主窗口
在菜单中,进入 ``Serial flasher config`` > ``Default serial port`` 配置串口(工程将会加载到该串口上)。输入回车确认选择,选择 ``< Save >`` 保存配置,然后选择 ``< Exit >`` 退出应用程序。
.. note::
在 Windows 系统中,端口号的名称类似 COM1在 MacOS 中以 ``/dev/cu.`` 开始,而在 Linux 系统中,以 ``/dev/tty`` 开始。
(详细内容可以参考章节 :doc:`establish-serial-connection`。)
下面是一些使用 ``menuconfig`` 的小技巧:
* 使用 up & down 组合键在菜单中上下移动
* 使用 Enter 键进入一个子菜单Escape 键退出子菜单或退出整个菜单
* 输入 ``?`` 查看帮助信息Enter 键退出帮助屏幕
* 使用空格键或 ``Y````N`` 键来使能 (Yes) 和禁止 (No) 带有复选框 "``[*]``" 的配置项
* 当光标在某个配置项上面高亮时,输入 ``?`` 可以直接查看该项的帮助信息
* 输入 ``/`` 搜索配置项
.. note::
如果你是 **Arch Linux** 用户,需要进入 ``SDK tool configuration````Python 2 interpreter````python`` 修改为 ``python2``
.. attention::
如果 ESP32-DevKitC 板载的是 ESP32-SOLO-1 模组,请务必在烧写示例程序之前在 menuconfig 中使能单核模式(:ref:CONFIG_FREERTOS_UNICORE
.. _get-started-build-flash:
编译和烧写
===============
现在可以编译和烧写应用程序了,执行指令: ::
make flash
这条命令会编译应用程序和所有的 ESP-IDF 组件,生成 bootloader、分区表和应用程序 bin 文件,并将这些 bin 文件烧写到 ESP32 板子上。
.. highlight:: none
::
esptool.py v2.0-beta2
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changed.
Attaching SPI flash...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0220
Compressed 11616 bytes to 6695...
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
Hash of data verified.
Compressed 408096 bytes to 171625...
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 82...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
如果没有任何问题,在编译过程结束后将能看到类似上面的消息。最后,板子将会复位,应用程序 "hello_world" 开始启动。
如果你想使用 Eclipse IDE 而不是运行 ``make``,请参考 :doc:`Eclipse guide <eclipse-setup>`
.. _get-started-build-monitor:
监视器
=======
如果要查看 "hello_world" 程序是否真的在运行,输入命令 ``make monitor``。这个命令会启动 IDF Monitor 程序: ::
$ make monitor
MONITOR
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun 8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun 8 2016 00:22:57
...
在启动消息和诊断消息后,你就能看到 "Hello world!" 程序所打印的消息: ::
...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
要退出监视器,请使用快捷键 ``Ctrl+]``
.. note::
如果串口打印的不是上面显示的消息而是类似下面的乱码: ::
e<><65><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
或者监视器程序启动失败,那么可能你的开发板用的是 26 MHz 晶振,而 ESP-IDF 默认的是 40 MHz 晶振。请退出监视器,回到 :ref:`配置 <get-started-configure>`,将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 改为 26 MHz然后再次 :ref:`编译和烧写 <get-started-build-flash>`。请在 ``make menuconfig`` 的 Component config --> ESP32-specific --> Main XTAL frequency 中配置。
要一次性执行 ``make flash````make monitor``,输入 ``make flash monitor``。参考文档 :doc:`IDF Monitor <idf-monitor>` 里的快捷键和更多内容。
你已完成 ESP32 的入门!
现在你可以尝试其他的示例工程 :idf:`examples`,或者直接开发自己的应用程序。
更新 ESP-IDF
=============
使用 ESP-IDF 一段时间后,你可能想要进行升级来获得新的性能或者对 bug 进行修复。最简单的更新方式是删除已有的 ``esp-idf`` 文件夹然后再克隆一个,即重复 :ref:`get-started-get-esp-idf` 里的操作。
然后 :doc:`add-idf_path-to-profile`,这样工具链脚本就能够知道这一版本的 ESP-IDF 的具体位置。
另外一种方法是只更新有改动的部分。:ref:`更新步骤取决于现在用的ESP-IDF版本 <updating>`
相关文档
=================
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
make-project
eclipse-setup
idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases