diff --git a/docs/zh_CN/get-started/add-idf_path-to-profile.rst b/docs/zh_CN/get-started/add-idf_path-to-profile.rst index 7ece4ab8f..1af406efd 100644 --- a/docs/zh_CN/get-started/add-idf_path-to-profile.rst +++ b/docs/zh_CN/get-started/add-idf_path-to-profile.rst @@ -1 +1,63 @@ -.. include:: ../../en/get-started/add-idf_path-to-profile.rst \ No newline at end of file +在用户配置文件中添加 IDF_PATH +============================== + +为了在系统多次重新启动时保留 “IDF_PATH” 环境变量的设置，请按照以下说明将其添加到用户配置文件中。 + +.. _add-idf_path-to-profile-windows: + + +Windows +------- + +用户配置文件脚本存放在 ``C:/msys32/etc/profile.d/`` 目录中。每次打开 MSYS2 窗口时，系统都执行这些脚本。 + + +#. 在 ``C:/msys32/etc/profile.d/`` 目录下创建一个新的脚本文件。将其命名为 ``export_idf_path.sh``。 + +#. 确定 ESP-IDF 目录的路径。路径与系统配置有关，例如 ``C:\msys32\home\user-name\esp\esp-idf``。 +#. 在脚本中加入 ``export`` 命令，e.g.:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + + 请将原始 Windows 路径中将反斜杠替换为正斜杠。 + +#. 保存脚本。 + +#. 关闭 MSYS2 窗口并再次打开。输入以下命令检查是否设置了 ``IDF_PATH``:: + + printenv IDF_PATH + +将此前在脚本文件中输入的路径打印出来。 + +如果您不想在用户配置文件中永久设置 ``IDF_PATH``，则应在打开 MSYS2 窗口时手动输入:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + +如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-setup-path` 小节跳转到了这里，请返回到 :ref:`get-started-start-project` 小节。 + +.. _add-idf_path-to-profile-linux-macos: + +Linux and MacOS +--------------- + +在 ``~/.profile`` 文件中加入以下指令，创建 ``IDF_PATH``： + + export IDF_PATH=~/esp/esp-idf + +注销并重新登录以使此更改生效。 + +.. note:: + + 如果将 ``/bin/bash`` 已设为登录 shell，并且 ``.bash_profile`` 和 ``.profile`` 同时存在，则更新 ``.bash_profile``。 + +运行以下命令以确保 ``IDF_PATH`` 已经设置好:: + + printenv IDF_PATH + +此前在 ``~/.profile`` 文件中输入（或者手动设置）的路径应该被打印出来。 + +如果不想永久设置 ``IDF_PATH``，每次重启或者注销时在终端窗口中手动输入:: + + export IDF_PATH=~/esp/esp-idf + +如果您从 :ref:`get-started-setup-path` 小节跳转到了这里，在安装用于 ESP32 开发的软件时，返回到 :ref:`get-started-start-project` 小节。 \ No newline at end of file diff --git a/docs/zh_CN/get-started/establish-serial-connection.rst b/docs/zh_CN/get-started/establish-serial-connection.rst index 4cae221a5..38c05344c 100644 --- a/docs/zh_CN/get-started/establish-serial-connection.rst +++ b/docs/zh_CN/get-started/establish-serial-connection.rst @@ -1 +1,125 @@ -.. include:: ../../en/get-started/establish-serial-connection.rst \ No newline at end of file +与 ESP32 创建串口连接 +========================= + +本章节介绍如何在 ESP32 和 PC 之间建立串口连接。 + +连接 ESP32 和 PC +-------------------- + +用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，确认 ESP32 开发板上的 USB 转串口芯片（或外部串口适配器）型号，在网上搜索驱动程序并进行安装。 + +以下是乐鑫 ESP32 开发板驱动程序的链接： + +* ESP32-PICO-KIT 和 ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers `_ + +* ESP32-WROVER-KIT 和 ESP32 Demo Board - `FTDI Virtual COM Port Drivers `_ + +以上驱动仅用于参考。当您将上述 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中并自动安装。 + +在 Windows 上查看端口 +--------------------- + +检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次显示。 + +以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口： + +.. figure:: ../../_static/esp32-devkitc-in-device-manager.png + :align: center + :alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager + :figclass: align-center + + 设备管理器中 ESP32-DevKitC 的 USB 串口转换器 + +.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png + :align: center + :alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager + :figclass: align-center + + Windows 设备管理器中的两个 USB-WROVER-KIT 串行端口 + +在 Linux 和 MacOS 上检查串口 +----------------------------- + +要查看 ESP32 开发板（或外部串口适配器）的串口设备名称，运行以下命令两次，第一次先拔下开发板或适配器，第二次插入开发板或适配器之后再运行命令，第二次运行指令后出现的端口即是 ESP32 对应的串口： + +Linux :: + + ls /dev/tty* + +MacOS :: + + ls /dev/cu.* + + +.. _linux-dialout-group: + +在 Linux 添加用户到 ``dialout`` +----------------------------------- + +当前登录用户可以通过 USB 读写串口。在大多数 Linux 发行版中，这是通过以下命令将用户添加到 ``dialout`` 组来完成的:: + + sudo usermod -a -G dialout $USER + +重新登录以确保串行端口的读写权限被启用。 + + +确认串口连接 +------------------------ + +现在验证串口连接是可用的。您可以使用串口终端程序来执行此操作。在这个例子中，我们将使用 `PuTTY SSH Client `_ ，它有 Windows 和 Linux 等平台的版本。您也可以使用其他串口程序并设置如下的通信参数。 + +运行终端，设置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下是设置串口和在 Windows 和 Linux 上传输参数（如 115200-8-1-N）的一些截屏示例。注意选择上述步骤中确认的串口进行设置。 + +.. figure:: ../../_static/putty-settings-windows.png + :align: center + :alt: Setting Serial Communication in PuTTY on Windows + :figclass: align-center + + 在 Windows 上的 PuTTY 设置串口传输。 + +.. figure:: ../../_static/putty-settings-linux.png + :align: center + :alt: Setting Serial Communication in PuTTY on Linux + :figclass: align-center + + 在 Linux 上的 PuTTY 设置串口传输。 + +在终端打开串口，检查是否有任何打印出来的日志。日志内容取决于加载到 ESP32 的应用程序。下图为 ESP32 的一个示例日志。 + +.. highlight:: none + +:: + + ets Jun 8 2016 00:22:57 + + rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + + rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + configsip: 0, SPIWP:0x00 + clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 + mode:DIO, clock div:2 + load:0x3fff0008,len:8 + load:0x3fff0010,len:3464 + load:0x40078000,len:7828 + load:0x40080000,len:252 + entry 0x40080034 + I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader + I (45) boot: compile time 18:48:10 + + ... + +如果您看到一些清晰的日志，则表示串行连接正常，您可以继续安装，最后将应用程序上载到 ESP32。 + +.. note:: + + 对于某些串口接线配置，在 ESP32 启动并产生串行输出之前，需要在终端程序中禁用串行 RTS ＆ DTR 引脚。这取决于串口适配器硬件本身，大多数开发板（包括所有乐鑫开发板）没有这个问题。此问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况。更多详细信息，参见 `esptool documentation`_。 + +.. note:: + + 验证通讯正常后关闭串口终端。下一步，我们将使用另一个应用程序来上传 ESP32。此应用程序在终端打开时将无法访问串口。 + +如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-connect` 小节跳转到了这里，请返回到 :ref:`get-started-configure` 小节继续阅读。 + +.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader + diff --git a/docs/zh_CN/get-started/idf-monitor.rst b/docs/zh_CN/get-started/idf-monitor.rst index a3c3f4f17..5e19ff158 100644 --- a/docs/zh_CN/get-started/idf-monitor.rst +++ b/docs/zh_CN/get-started/idf-monitor.rst @@ -1 +1,124 @@ -.. include:: ../../en/get-started/idf-monitor.rst \ No newline at end of file +*********** +IDF Monitor +*********** + +IDF Monitor 工具是在 IDF 中调用 “make monitor” 目标时运行的 Python 程序。 + +它主要是一个串行终端程序，用于收发该端口的串行数据，IDF Monitor 同时兼具 IDF 的其他特性。 + +IDF Monitor 操作快捷键 +=========================== +- ``Ctrl-]`` 退出 monitor； +- ``Ctrl-T Ctrl-H`` 展示帮助页面和其他快捷键； +- 除了 ``Ctrl-]`` 和 ``Ctrl-T``，其他快捷键信号会通过串口发送到目标设备。 + +自动解码地址 +================= +当 esp-idf 以 “0x4 _______” 形式打印一个十六进制的代码地址时，IDF Monitor 将使用 addr2line_ 来查找源代码的位置和函数名称。 + +.. highlight:: none + +当某个 esp-idf 应用程序发生 crash 和 panic 事件之后，将产生如下的寄存器转储和回溯:: + + Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled. + Register dump: + PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00 + A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000 + A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0 + A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0 + A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000 + + Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90 + +IDF Monitor 为转储补充如下信息:: + + Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled. + Register dump: + PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00 + 0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57 + (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52 + A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000 + A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0 + A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0 + A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000 + + Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90 + 0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57 + (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52 + 0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47 + 0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42 + 0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33 + 0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254 + +在后台，IDF Monitor 运行以下命令解码各个地址:: + + xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS + + +配置 GDBStub 供 GDB 调试 +============================ + +默认情况下，如果 esp-idf 应用程序 crash, panic 处理函数打印上述的寄存器和堆栈转储，然后重启。 + +您可以选择配置 panic 处理函数，使其运行串行的 "gdb stub"。该程序可以与 gdb 调试器通信，提供内存，变量，栈帧读取的功能。虽然这不像 JTAG 调试那样通用，但您不需要使用特殊硬件。 + +要启用 gdbstub，运行 ``make menuconfig`` 并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 + +如果启用此选项并且 IDF Monitor 发现 gdbstub 已加载，它将自动暂停串口监控并使用正确的参数运行 GDB。GDB 退出后，电路板将通过 RTS 串行线路复位（如果已连接）。 + +IDF Monitor 在后台运行的命令是:: + + xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf + + +快速编译与烧录 +================= + +使用快捷键 ``Ctrl-T Ctrl-A`` 暂停 IDF Monitor，并运行 ``make flash`` 目标，然后 IDF Monitor 就会恢复正常。任何更改的源文件将在烧录之前重新编译。 + +使用快捷键 ``Ctrl-T Ctrl-A`` 暂停 IDF Monitor，并运行 ``make app-flash`` 目标，然后 IDF Monitor 就会恢复正常。这与 ``make flash`` 类似，但只有主应用程序被编译和重新烧录。 + +快速重置 +====================== +键盘快捷键 ``Ctrl-T Ctrl-R`` 将通过 RTS 线（如果已连接）重置开发板。 + + +暂停应用程序 +===================== + +通过快捷键 ``Ctrl-T Ctrl-P`` 重启进入 bootloader，开发板将不运行任何程序。等待其他设备启动时可以使用此操作。使用快捷键 ``Ctrl-T Ctrl-R`` 重新启动应用程序。 + +输出显示开关 +================ + +暂停屏幕上的输出，以查看之前日志，可以使用快捷键 ``Ctrl-T Ctrl-Y`` 切换显示（当显示关闭时丢弃所有的串行数据）。这样您可以停下来查看日志，不必关闭显示器就可以快速恢复打印。 + +Simple Monitor +======================= + +较早版本的 ESP-IDF 使用 pySerial_ 命令行程序 miniterm_ 作为串行控制台程序。 + +这个程序仍然可以通过 ``make simple_monitor`` 运行。 + +IDF Monitor 基于 miniterm 并使用相同的快捷键。 + +IDF Monitor 已知问题 +============================= + +Windows 环境下已知问题 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 如果您使用支持 idf_monitor 的 Windows 环境，却收到错误 "winpty: command not found”，请运行 ``pacman -S winpty`` 进行修复。 +- 由于 Windows 控制台的限制，gdb 中的箭头键和其他一些特殊键不起作用。 +- 偶尔当 “make” 退出时，可能会在 idf_monitor 恢复之前暂停 30 秒。 +- 偶尔当 "gdb" 运行时，它可能会暂停一段时间，然后才开始与 gdbstub 进行通信。 + + +.. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html +.. _gdb: https://sourceware.org/gdb/download/onlinedocs/ +.. _pySerial: https://github.com/pyserial/pyserial +.. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm + + diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 387e68ceb..e2eb3d2ea 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -71,9 +71,9 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了 .. toctree:: :hidden: - Windows <../get-started/windows-setup> - Linux <../get-started/linux-setup> - MacOS <../get-started/macos-setup> + Windows + Linux + MacOS +-------------------+-------------------+-------------------+ | |windows-logo| | |linux-logo| | |macos-logo| | @@ -82,17 +82,17 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了 +-------------------+-------------------+-------------------+ .. |windows-logo| image:: ../../_static/windows-logo.png - :target: ../get-started/windows-setup.html + :target: windows-setup.html .. |linux-logo| image:: ../../_static/linux-logo.png - :target: ../get-started/linux-setup.html + :target: linux-setup.html .. |macos-logo| image:: ../../_static/macos-logo.png - :target: ../get-started/macos-setup.html + :target: macos-setup.html -.. _Windows: ../get-started/windows-setup.html -.. _Linux: ../get-started/linux-setup.html -.. _Mac OS: ../get-started/macos-setup.html +.. _Windows: windows-setup.html +.. _Linux: linux-setup.html +.. _Mac OS: macos-setup.html .. note:: @@ -316,9 +316,9 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 .. toctree:: :maxdepth: 1 - ../get-started/add-idf_path-to-profile - ../get-started/establish-serial-connection - ../get-started/make-project - ../get-started/eclipse-setup - ../get-started/idf-monitor - ../get-started/toolchain-setup-scratch + add-idf_path-to-profile + establish-serial-connection + make-project + eclipse-setup + idf-monitor + toolchain-setup-scratch diff --git a/docs/zh_CN/get-started/macos-setup.rst b/docs/zh_CN/get-started/macos-setup.rst index a0edfdb16..ea5b6c60d 100644 --- a/docs/zh_CN/get-started/macos-setup.rst +++ b/docs/zh_CN/get-started/macos-setup.rst @@ -1 +1,58 @@ -.. include:: ../../en/get-started/macos-setup.rst \ No newline at end of file +************************************** +在 Mac OS 上安装 ESP32 工具链 +************************************** + +安装准备 +================ + +- 安装 pip:: + + sudo easy_install pip + +- 安装 pyserial:: + + sudo pip install pyserial + + +安装工具链 +=============== + +Mac OS 版本的 ESP32 工具链可以从以下地址下载： + +https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-75-gbaf03c2-5.2.0.tar.gz + +下载压缩文件之后，解压到 ``~/esp`` 目录中:: + + mkdir -p ~/esp + cd ~/esp + tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-75-gbaf03c2-5.2.0.tar.gz + +.. _setup-macos-toolchain-add-it-to-path: + +工具链将被解压到 ``~/esp/xtensa-esp32-elf/`` 路径下。 + +在 ``~/.profile`` 文件中更新 ``PATH`` 环境变量以使用工具链。为了使 ``xtensa-esp32-elf`` 在各种终端会话中都可用，在 ``~/.profile`` 文件中加上以下指令:: + + export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin + +或者，您可以为上述命令创建一个别名。这样只有执行以下指令时工具链才能被使用。将下面的指令添加到您的 ``〜/ .profile`` 文件中:: + + alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin" + +当需要使用工具链时，在命令行里输入 ``get_esp32``，就可以将工具链添加到 ``PATH`` 中。 + + +下一步 +========== + +前往 :ref:`get-started-get-esp-idf` 继续配置开发环境。 + + +相关文档 +================= + +.. toctree:: + :maxdepth: 1 + + macos-setup-scratch + diff --git a/docs/zh_CN/get-started/make-project.rst b/docs/zh_CN/get-started/make-project.rst index e2939c219..6c03bab97 100644 --- a/docs/zh_CN/get-started/make-project.rst +++ b/docs/zh_CN/get-started/make-project.rst @@ -1 +1,71 @@ -.. include:: ../../en/get-started/make-project.rst \ No newline at end of file +通过 make 指令创建和烧录项目 +============================= + + +寻找项目 +----------------- + +和 `esp-idf-template `_ 项目一样，ESP-IDF 在 Github 上的 :idf:`examples` 目录下也有示例项目。 + +找到需要的项目后，切换到其目录，然后可以对其进行配置和构建。 + + +配置项目 +------------------------ + +:: + + make menuconfig + + +编译项目 +---------------------- + +:: + + make all + +... 该命令将配置 app 和 bootloader 并根据配置生成分区表。 + + +烧录项目 +--------------------- + +当 ``make all`` 结束后，系统将打印一命令行提示您如何使用 esptool.py 烧录芯片。用户也可以通过以下指令进行烧录:: + + make flash + +这种方法将烧录整个项目（包括 app, bootloader 和分割表）到芯片中。通过命令 `make menuconfig` 可以配置串口。 + +运行 ``make flash`` 之前无需运行 ``make all``。运行 ``make flash`` 将自动重建烧录所需的一切。 + + +仅编译和烧录应用程序 +--------------------------------- + +在最初的烧录之后，用户可以仅创建烧录 app，不烧录 bootloader 和分区表: + +* ``make app`` - 仅创建应用程序。 +* ``make app-flash`` - 仅烧录应用程序。 + +需要时 ``make app-flash`` 指令将自动重建 app。 + +如果 bootloader 和分区表不变的话，对他们进行重新烧录并不会有负面影响。 + +分区表 +------------------- + +编译完项目后，"build" 目录将包含一个名为 "my_app.bin" 的二进制文件。这是一个可由 bootloader 加载的 ESP32 映像二进制文件。 + +一个 ESP32 flash 可以包含多个应用程序，以及多种数据（校准数据，文件系统，参数存储等）。因此，分区表烧录在 flash 偏移地址 0x8000 的地方。 + +分区表中的每个条目都有一个名称（标签），类型（app，数据或其他），子类型和闪存中分区表被存放的偏移量。 + +使用分区表最简单的方法是 `make menuconfig` 并选择一个简单的预定义分区表: + +* "Single factory app, no OTA" +* "Factory app, two OTA definitions" + +在这两种情况下，出厂应用程序的烧录偏移为 0x10000。运行 `make partition_table`，可以打印分区表摘要。 + +更多关于 :doc:`分区表 <../api-guides/partition-tables>` 的信息，以及如何创建自定义分区表，可以查看 :doc:`文档 <../api-guides/partition-tables>`。