esp-idf/docs/zh_CN/get-started/establish-serial-connection.rst

385 lines
15 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

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.

与 {IDF_TARGET_NAME} 创建串口连接
==============================================
:link_to_translation:`en:[English]`
.. only:: not SOC_USB_OTG_SUPPORTED and not SOC_USB_SERIAL_JTAG_SUPPORTED
可以使用 USB 至 UART 桥,与 {IDF_TARGET_NAME} 创建串口连接。
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
可以使用 USB 至 UART 桥或 {IDF_TARGET_NAME} 支持的 USB 外设,与 {IDF_TARGET_NAME} 创建串口连接。
部分开发板中已经安装有 USB 至 UART 桥。如未安装,可使用外部桥。
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
支持的 USB 外设
------------------------
{IDF_TARGET_NAME} 支持 USB 外设。无需 USB 至 UART 桥,便可直接烧录设备。
.. blockdiag::
:scale: 70%
:caption: 支持 USB 的 SoC
:align: center
blockdiag usb_capable_esp {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\n Computer"];
CHIP [label="{IDF_TARGET_NAME}", width=120];
DUMMY [shape=none, width=1]
# node connections
PC <- DUMMY [label = "USB", fontsize=14];
DUMMY -> CHIP [fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Development Board\n\n\n";
CHIP; DUMMY;
}
}
部分支持 USB 外设的开发板同时也包含 USB 至 UART 桥。
安装有 USB 至 UART 桥的开发板
---------------------------------------
在安装有 USB 至 UART 桥的开发板中PC 和桥之间通过 USB 连接,桥和 {IDF_TARGET_NAME} 之间通过 UART 连接。
.. blockdiag::
:caption: 安装有 USB 至 UART 桥的开发板
:align: center
blockdiag esp_dev_board_with_usb_to_uart_bridge {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\nComputer"];
BRIDGE [label="USB-to-UART\n Bridge"];
CHIP [label="{IDF_TARGET_NAME}", width=120];
# node connections
PC <-> BRIDGE [label = "USB", fontsize=14];
BRIDGE <-> CHIP [label = "UART", fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Developmment Board\n\n\n";
BRIDGE; CHIP;
}
}
外部 USB 至 UART 桥
---------------------------
部分开发板使用外部 USB 至 UART 桥。这种情况通常出现在需要控制空间和成本的产品中,例如一些小型开发板或成品。
.. blockdiag::
:caption: 外部 USB 至 UART 桥
:align: center
blockdiag external_usb_to_uart_bridge_to_esp {
node_height = 80;
span_width = 160;
span_height = 140;
default_fontsize = 16
# labels of diagram nodes
PC [label="Personal\n Computer"];
BRIDGE [label="USB-to-UART\n Bridge", width=180];
CHIP [label="{IDF_TARGET_NAME}", width=120];
DUMMY [shape=none, width=1]
# node connections
PC <-> BRIDGE [label = "USB", fontsize=14];
BRIDGE <- DUMMY [label = "UART", fontsize=14];
DUMMY -> CHIP [fontsize=14];
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Programmmer Board\n\n\n";
BRIDGE
}
group {
shape = line;
style = dotted;
color = "#FF0000";
label = "Development Board\n\n\n";
CHIP; DUMMY;
}
}
.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
使用 USB 进行烧录
------------------
{IDF_TARGET_NAME} 支持 USB 外设,无需外部 USB 至 UART 桥,即可烧录二进制文件。
{IDF_TARGET_USB_PIN_DM:default="尚未更新!", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19", esp32c6="GPIO12", esp32h2="GPIO26", esp32p4="GPIO24/26"}
{IDF_TARGET_USB_PIN_DP:default="尚未更新!", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20", esp32c6="GPIO13", esp32h2="GPIO27", esp32p4="GPIO24/26"}
{IDF_TARGET_NAME} 上的 USB 使用 **{IDF_TARGET_USB_PIN_DP}** 作为 **D+** **{IDF_TARGET_USB_PIN_DM}** 作为 **D-**
.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED and not esp32s3 and not esp32p4
.. note:: {IDF_TARGET_NAME} 仅支持 *USB CDC and JTAG*
首次烧录需要手动设置 {IDF_TARGET_NAME} 进入下载模式。请按住 ``BOOT`` 按钮,同时按一下 ``RESET`` 按钮。之后,松开 ``BOOT`` 按钮。
.. only:: esp32s3
首次烧录需要手动设置 {IDF_TARGET_NAME} 进入下载模式。请按住 ``BOOT`` 按钮,同时按一下 ``RESET`` 按钮。之后,松开 ``BOOT`` 按钮。
.. only:: esp32s2
二进制文件烧录完成后,需要手动进行复位。
使用 UART 进行烧录
---------------------
本节描述如何使用 USB 至 UART 桥在 {IDF_TARGET_NAME} 和 PC 之间建立串行连接。板上桥与外部桥均适用。
连接 {IDF_TARGET_NAME} 和 PC
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
用 USB 线将 {IDF_TARGET_NAME} 开发板连接到 PC。如果设备驱动程序没有自动安装请先确认 {IDF_TARGET_NAME} 开发板上的 USB 至 UART 桥(或外部转 UART 适配器)型号,然后在网上搜索驱动程序,并进行手动安装。
以下是乐鑫 {IDF_TARGET_NAME} 开发板驱动程序的链接:
* CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 <https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers>`_
* FTDI: `FTDI 虚拟 COM 端口驱动程序 <https://ftdichip.com/drivers/vcp-drivers/>`_
以上驱动仅供参考,请查看开发板用户指南,了解开发板具体使用的 USB 至 UART 桥芯片。一般情况下,当 {IDF_TARGET_NAME} 开发板与 PC 连接时,对应驱动程序应该已经被打包在操作系统中,并已经自动安装。
对于使用 USB 至 UART 桥下载的设备,可以运行以下命令,包括定义波特率的可选参数。
.. code-block:: bash
idf.py -p PORT [-b BAUD] flash
``PORT`` 替换为 {IDF_TARGET_NAME} 开发板的串口名称。``-b`` 为可选参数,默认的波特率为 ``460800``。如需改变烧录器的波特率,请用需要的波特率代替 ``BAUD``
要查看串口名称Windows 用户请参考 `check-port-on-windows`_Linux 与 macOS 用户请参考 `check-port-on-linux-and-macos`_。
例如Windows 平台上串口名称为 ``COM3``,所需波特率为 ``115200``,可使用如下命令烧录开发板:
.. code-block:: bash
idf.py -p COM3 -b 115200 flash
Linux 平台上串口名称为 ``/dev/ttyUSB0``,所需波特率为 ``115200``,可使用如下命令烧录开发板:
.. code-block:: bash
idf.py -p /dev/ttyUSB0 -b 115200 flash
macOS 平台上串口名称为 ``/dev/cu.usbserial-1401``,所需波特率为 ``115200``,可使用如下命令烧录开发板:
.. code-block:: bash
idf.py -p /dev/cu.usbserial-1401 -b 115200 flash
.. note::
如果设备不支持自动下载模式,则需要手动进入下载模式。请按住 ``BOOT`` 按钮,同时按一下 ``RESET`` 按钮。之后,松开 ``BOOT`` 按钮。
.. _check-port-on-windows:
在 Windows 上查看端口
---------------------
检查 Windows 设备管理器中的 COM 端口列表。断开 {IDF_TARGET_NAME} 与 PC 的连接,然后重新连接,查看哪个端口从列表中消失后又再次出现。
以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口:
.. figure:: ../../_static/esp32-devkitc-in-device-manager.png
:align: center
:alt: 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥
:figclass: align-center
设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥
.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png
:align: center
:alt: Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
:figclass: align-center
Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
.. _check-port-on-linux-and-macos:
在 Linux 和 macOS 上查看端口
-----------------------------
查看 {IDF_TARGET_NAME} 开发板(或外部转串口适配器)的串口设备名称,请将以下命令运行两次。首先,断开开发板或适配器,首次运行以下命令;然后,连接开发板或适配器,再次运行以下命令。其中,第二次运行命令后出现的端口即是 {IDF_TARGET_NAME} 对应的串口:
Linux::
ls /dev/tty*
macOS::
ls /dev/cu.*
.. 注解::
对于 macOS 用户:若没有看到串口,请检查是否安装 USB/串口驱动程序。具体应使用的驱动程序,见章节 `连接 {IDF_TARGET_NAME} 和 PC`_。对于 macOS High Sierra (10.13) 的用户,你可能还需要手动允许驱动程序的加载,具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``,检查是否有信息显示:“来自开发人员的系统软件...”,其中开发人员的名称为 Silicon Labs 或 FTDI。
.. _linux-dialout-group:
在 Linux 中添加用户到 ``dialout````uucp``
--------------------------------------------------
当前登录用户应当可以通过 USB 对串口进行读写操作。在多数 Linux 版本中,都可以通过以下命令,将用户添加到 ``dialout`` 组,从而获许读写权限::
sudo usermod -a -G dialout $USER
在 Arch Linux 中,需要通过以下命令将用户添加到 ``uucp`` 组中::
sudo usermod -a -G uucp $USER
请重新登录,确保串口读写权限生效。
确认串口连接
------------------------
现在,请使用串口终端程序,查看重置 {IDF_TARGET_NAME} 后终端上是否有输出,从而验证串口连接是否可用。
.. only:: esp32c2
使用 40 MHz 的 XTAL 时ESP32-C2 的控制台波特率默认为 115200使用 26 MHz 的 XTAL 时,其波特率默认为 74880。
.. only:: not esp32c2
{IDF_TARGET_NAME} 的控制台波特率默认为 115200。
Windows 和 Linux 操作系统
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
在本示例中,我们将使用 `PuTTY SSH Client <https://www.putty.org/>`_`PuTTY SSH Client <https://www.putty.org/>`_ 既可用于 Windows 也可用于 Linux。也可以使用其他串口程序并设置如下的通信参数。
运行终端,配置在上述步骤中确认的串口:波特率 = 115200如有需要请更改为使用芯片的默认波特率数据位 = 8停止位 = 1奇偶校验 = N。以下截屏分别展示了如何在 Windows 和 Linux 中配置串口和上述通信参数(如 115200-8-1-N。注意这里一定要选择在上述步骤中确认的串口进行配置。
.. figure:: ../../_static/putty-settings-windows.png
:align: center
:alt: 在 Windows 操作系统中使用 PuTTY 设置串口通信参数
:figclass: align-center
在 Windows 操作系统中使用 PuTTY 设置串口通信参数
.. figure:: ../../_static/putty-settings-linux.png
:align: center
:alt: 在 Linux 操作系统中使用 PuTTY 设置串口通信参数
:figclass: align-center
在 Linux 操作系统中使用 PuTTY 设置串口通信参数
然后,请检查 {IDF_TARGET_NAME} 是否有打印日志。如有,请在终端打开串口进行查看。这里的日志内容取决于加载到 {IDF_TARGET_NAME} 的应用程序,请参考 `输出示例`_。如果没有看到输出日志,请参考 `故障排除`_
.. 注解::
请在验证完串口通信正常后,关闭串口终端。如果终端一直保持打开的状态,之后上传固件时将无法访问串口。
macOS 操作系统
^^^^^^^^^^^^^^^^^
macOS 提供了 **屏幕** 命令,因此无需安装串口终端程序。
- 参考 `在 Linux 和 macOS 上查看端口`_,运行以下命令::
ls /dev/cu.*
- 会看到类似如下输出::
/dev/cu.Bluetooth-Incoming-Port /dev/cu.SLAB_USBtoUART /dev/cu.SLAB_USBtoUART7
- 根据连接到电脑上的开发板类型和数量输出结果会有所不同。请选择开发板的设备名称并运行以下命令如有需要请将“115200”更改为使用芯片的默认波特率::
screen /dev/cu.device_name 115200
``device_name`` 替换为运行 ``ls /dev/cu.*`` 后出现的设备串口号。
- **屏幕** 显示的日志即为所需内容。日志内容取决于加载到 {IDF_TARGET_NAME} 的应用程序,请参考 `输出示例`_。如果没有看到输出日志,请参考 `故障排除`_。请使用 ``Ctrl-A + K`` 键退出当前 **屏幕** 会话。
.. 注解::
请在验证完串口通信正常后,关闭 **当前屏幕会话**。如果直接关闭终端窗口而没有关闭 **屏幕**,之后上传固件时将无法访问串口。
故障排除
^^^^^^^^^^^^^^^
如果没有日志输出,请检查以下原因:
- {IDF_TARGET_NAME} 的供电是否正常
- 启动终端程序后,是否重置开发板
- 使用 `在 Windows 上查看端口`_`在 Linux 和 macOS 上查看端口`_ 中描述的方法,检查所选串口是否正确
- 其他程序是否正在使用该串口
- 串口终端程序中的串口设置是否适用于该应用程序
- 应用程序是否会输出日志。具体来说,如果在 ``Component config`` > ``Log`` > ``Log Level`` > ``Default log verbosity (Info)`` 中设置为 ``No output``,则不会打印出任何日志。你可以在 ``menuconfig`` 中更改该设置。
- 是否禁用了日志输出(使用 :example:`hello world 示例 <get-started/hello_world>` 进行测试)
输出示例
^^^^^^^^^^^
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9", esp32c6="GPIO9", esp32h2="GPIO9", esp32p4="GPIO35"}
以下是一个日志示例。如果没看到任何输出,请尝试重置开发板。
.. 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
...
如果打印出的日志是可读的(而不是乱码),则表示串口连接正常。此时,可以继续进行安装,并最终将应用程序上载到 {IDF_TARGET_NAME}。
.. 注解::
在某些串口接线方式下,在 {IDF_TARGET_NAME} 启动并开始打印串口日志前,需要在终端程序中禁用串口 RTS DTR 管脚。该问题仅存在于将 RTS DTR 管脚直接连接到 EN {IDF_TARGET_STRAP_GPIO} 管脚上的情况,绝大多数开发板(包括乐鑫所有的开发板)都没有这个问题。更多详细信息,请参考 `esptool 文档`_
如在安装 {IDF_TARGET_NAME} 硬件开发的软件环境时,从 :ref:`get-started-connect` 跳转到了这里,请从 :ref:`get-started-configure` 继续阅读。
.. _esptool 文档: https://docs.espressif.com/projects/esptool/en/latest/advanced-topics/boot-mode-selection.html#automatic-bootloader