Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 入门 - FreeRTOS
OverviewPrerequisites开始使用 ESP-IDF v3.3开始使用 ESP-IDF 版本在云上监控 MQTT 消息运行低功耗蓝牙演示在 ESP32 的 CMake 项目中使用 FreeRTOSTroubleshootingDebugging

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 入门

按照本教程操作，开始使用带 ESP32-WROOM-32、ESP32-SOLO-1 或 ESP-WROVER 模块的乐透 ESP32-DevKitC 和 ESP-WROVER-KIT-VB。如需从我们的合作伙伴处购买AWS合作伙伴设备目录，请使用以下链接：

FreeRTOS 支持这些版本的开发主板。

有关这些主板的最新版本的更多信息，请参阅ESP32-DevKitC V4或者ESP-WROVER-KIT v4.1）。

注意

目前，ESP32-WROVER-KIT 和 ESP DevKitC 的 FreeRTOS 端口不支持对称多处理 (SMP) 功能。

Overview

该教程将指导您完成以下步骤：

  1. 将主板连接到主机

  2. 在主机上安装软件来开发和调试微控制器主板的嵌入式应用程序

  3. 将 FreeRTOS 演示应用程序交叉编译为二进制映像

  4. 将应用程序二进制映像加载到您的主板中，然后运行该应用程序

  5. 跨串行连接与主板上运行的应用程序进行交互，以便进行监控和调试。

Prerequisites

在 Espressif 主板上开始使用 FreeRTOS 之前，您必须设置您的AWS帐户和权限。

要创建账户，请参阅创建并激活AWS账户。

添加AWS Identity and Access Management(IAM) 用户添加到您的账户，请参阅IAM 用户指南。向您的 IAM 用户账户授予对AWS IoT和 FreeRTOS，请将以下 IAM 策略附加到您的 IAM 用户账户：

  • AmazonFreeRTOSFullAccess

    允许对 IAM 用户的所有 FreeRTOS 资源（FreeRTOS：*）进行完全访问。

  • AWSIoTFullAccess

    允许对 IAM 用户的所有AWS IoT资源（物联网：*）。

将 AmazonFreeRTOSFullAccess 策略附加到您的 IAM 用户

  1. 导航到IAM 控制台。

  2. 在导航窗格中，选择 Users (用户)。

  3. 在搜索文本框中输入您的用户名，然后从列表中选择该名称。

  4. 选择 Add permissions (添加权限)。

  5. 选择直接附加现有策略。

  6. 在搜索框中，输入AmazonFreeRTOSFullAccess，从列表中选择它，然后选择。后续：审核。

  7. 选择 Add permissions (添加权限)。

将 AWSIoTFullAccess 策略附加到您的 IAM 用户

  1. 导航到IAM 控制台。

  2. 在导航窗格中，选择 Users (用户)。

  3. 在搜索文本框中输入您的用户名，然后从列表中选择该名称。

  4. 选择 Add permissions (添加权限)。

  5. 选择直接附加现有策略。

  6. 在搜索框中，输入AWSIoTFullAccess，从列表中选择它，然后选择。后续：审核。

  7. 选择 Add permissions (添加权限)。

有关 IAM 和用户账户的更多信息，请参阅IAM 用户指南。

有关策略的更多信息，请参阅。IAM 中的权限和策略。

注意

FreeRTOS 投资者 202012.00 版本支持 ESP-IDF 版本。如果您使用的是更高版本的 FFreeRTOS，请按照 IDFv4.2 特定的说明进行操作，网址为开始使用 ESP-IDF 版本。

开始使用 ESP-IDF v3.3

本节说明如何在 Espressif 硬件上使用 ESP-IDF v3.3。若要使用 ESP-IDF v4.2，请参阅开始使用 ESP-IDF 版本。

设置 Espressif 硬件

有关设置 ESP32-DevKitC 开发主板硬件的更多信息，请参阅。ESP32 开发基础 V4 入门指南。

有关设置 ESP-WROVER-KIT 开发主板硬件的信息。请参阅ESP-WROVER-KIT V4.1 入门指南。

重要

当您到达开始使用部分，停止，然后执行以下步骤。

设置开发环境

要与您的主板进行通信，您必须下载并安装工具链。

设置工具链

注意

ESP-IDF v3.3 不支持最新版本的 ESP32 编译器。如果您已经安装了最新版本的 ESP32 编译器，则应将其卸载并使用工具链安装中包含的兼容版本的编译器。请参阅本节中的链接。要检查编译器版本，请运行以下命令。

xtensa-esp32-elf-gcc --version

要设置工具链，请按照适用于您的主机操作系统的以下说明操作：

重要

当您到达后续步骤，停止，然后返回此页面上的说明。

如果您已按照后续步骤，就在现在或之前的场合，您应该清除IDF_PATH环境变量，然后再继续操作。如果您已按照 “Get ESP-IDF” 说明执行操作，则会自动设置此环境变量。

安装 CMake

需要 CMake 生成系统来为此设备生成 FreeRTOS 演示和测试应用程序。FreeRTOS 支持版本 3.13 及更高版本。

您可以从 CMake.org 下载最新版本的 CMake。同时提供源代码和二进制分发。

有关将 CMake 与 FreeRTOS 结合使用的详细信息，请参阅将 CMake 与 FreeRTOS 结合使用。

建立串行连接

要在您的主机和 ESP32-DevKitC 之间建立串行连接，必须安装 CP210x USB to UART Bridge VCP 驱动程序。您可以从 Silicon Labs 下载这些驱动程序。

要在您的主机和 ESP32-WROVER-KIT 之间建立串行连接，必须安装一些 FTDI 虚拟 COM 端口驱动程序。您可以从 FTDI 下载这些驱动程序。

有关更多信息，请参阅使用 ESP32 建立串行连接。建立串行连接后，记下主板连接的串行端口。在构建演示时需要用到它。

下载并配置 FreeRTOS

设置环境后，您可以从下载 FreeRTOSGitHub，或来自FreeRTOS 控制台。有关说明，请参阅自述文件文 GitHub。

配置 FreeRTOS 演示应用程序

  1. 如果您运行的是 macOS 或 Linux，请打开终端提示符。如果运行的是 Windows，请打开mingw32.exe。MinGW 文是一个适用于本机 Microsoft Windows 应用程序的简约开发环境。

  2. 要验证您已安装 Python 2.7.10 或更高版本，请运行 

    python --version

    此时显示已安装的版本。如果未安装 Python 2.7.10 或更高版本，则可以从Python网站。

  3. 您需要AWS Command Line Interface(AWS CLI）运行AWS IoT命令。如果运行的是 Windows，请使用easy_install awscli安装AWS CLI）。

    如果您运行的是 macOS 或 Linux，请参阅安装AWS CLI。

  4. 运行aws configure配置AWS CLI与您的AWS访问密钥 ID、秘密访问密钥和AWS区域。有关更多信息，请参阅配置 AWS CLI。

  5. 使用以下命令安装AWS适用于 Python (boto3) 的开发工具包：

    • 在 Windows 上的 mingw32 环境中，运行 

      easy_install boto3

    • 在 macOS 或 Linux 上，运行 

      pip install tornado nose --user

      然后运行 

      pip install boto3 --user

FreeRTOS 包括SetupAWS.py脚本，可以更轻松地设置您的 Espressif 主板以连接到AWS IoT。要配置此脚本，请打开 freertos/tools/aws_config_quick_start/configure.json 并设置以下属性：

afr_source_dir

完整路径FreeRTOS目录。确保您使用正斜杠来指定此路径。

thing_name

要分配给代表您的主板的 AWS IoT 事物的名称。

wifi_ssid

Wi-Fi 网络的 SSID。

wifi_password

Wi-Fi 网络的密码。

wifi_security

Wi-Fi 网络的安全类型。

有效安全类型有：

  • eWiFiSecurityOpen（开放，不安全）

  • eWiFiSecurityWEP（WEP 安全性）

  • eWiFiSecurityWPA（WPA 安全性）

  • eWiFiSecurityWPA2（WPA2 安全性）

运行配置脚本

  1. 如果您运行的是 macOS 或 Linux，请打开终端提示符。如果您运行的是 Windows，请打开mingw32.exe。

  2. 导航到freertos/tools/aws_config_quick_start目录并运行 

    python SetupAWS.py setup

该脚本执行以下操作：

  • 创建一个 IoT 事物、证书和策略

  • 将 IoT 策略附加到证书，将证书附加到 AWS IoT 事物

  • 使用您的 AWS IoT 终端节点、Wi-Fi SSID 和凭证填充 aws_clientcredential.h 文件

  • 设置您的证书和私有密钥格式，然后将其写入 aws_clientcredential_keys.h 标头文件

    注意

    仅出于演示目的对证书进行了硬编码。生产级应用程序应将这些文件存储在安全位置。

有关 的更多信息SetupAWS.py，请参阅README.md中的freertos/tools/aws_config_quick_start目录。

构建、刷写和运行 FreeRTOS 演示项目

您可以使用 CMake 生成构建文件，使用 Make 构建应用程序二进制文件，使用 Espressif 的 IDF 实用程序刷写主板。

在 Linux 和 MacOS 统上构建免费服务（ESP-IDF v3.3）

如果您使用的是 Windows，请参阅在窗口上构建 FreeRTOS（ESP-IDF v3.3）。

使用 CMake 生成构建文件，然后使用 Make 构建应用程序。

使用 CMake 生成演示应用程序的构建文件

  1. 将目录更改为 FreeRTOS 下载目录的根目录。

  2. 使用以下命令可生成构建文件。

    cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B your-build-directory
    注意

    如果您想要构建应用程序以进行调试，请将 -DCMAKE_BUILD_TYPE=Debug 标志添加到此命令。

    如果您想要生成测试应用程序构建文件，请添加 -DAFR_ENABLE_TESTS=1 标志。

    Espressif 提供的代码使用轻型 IP (lwIP) 堆栈作为默认网络堆栈。要改用 FreeRTOS +TCP 网络堆栈，请添加–DAFR_ESP_FREERTOS_TCP标志添加到 CMake 命令。

    要为非供应商提供的代码添加 lwIP 依赖项，请将以下行添加到 CMake 依赖性文件中，CMakeLists.txt，用于您的自定义 Wi-Fi 组件。 

    # Add a dependency on the bluetooth espressif component to the common component
set(COMPONENT_REQUIRES lwip)

使用 Make 构建应用程序

  1. 将目录更改为 build 目录。

  2. 使用以下命令，通过 Make 构建应用程序。

    make all -j4
    注意

    每当您在 aws_demos 项目和 aws_tests 项目之间切换时，都必须使用 cmake 命令构建生成文件。

在窗口上构建 FreeRTOS（ESP-IDF v3.3）

在 Windows 上，必须为 CMake 指定构建生成器。否则，CMake 默认为 Visual Studio。Espressif 正式推荐使用 Ninja 构建系统，因为它适用于 Windows、Linux 和 MacOS。您必须在本机 Windows 环境（如 cmd 或 PowerShell）中运行 CMake 命令。不支持在虚拟 Linux 环境（如 MSYS2 或 WSL）中运行 CMake 命令。

使用 CMake 生成构建文件，然后使用 Make 构建应用程序。

使用 CMake 生成演示应用程序的构建文件

  1. 将目录更改为 FreeRTOS 下载目录的根目录。

  2. 使用以下命令可生成构建文件。

    cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -GNinja -S . -B build-directory
    注意

    如果您想要构建应用程序以进行调试，请将 -DCMAKE_BUILD_TYPE=Debug 标志添加到此命令。

    如果您想要生成测试应用程序构建文件，请添加 -DAFR_ENABLE_TESTS=1 标志。

    Espressif 提供的代码使用轻型 IP (lwIP) 堆栈作为默认网络堆栈。要改用 FreeRTOS +TCP 网络堆栈，请添加–DAFR_ESP_FREERTOS_TCP标志添加到 CMake 命令。

    要为非供应商提供的代码添加 lwIP 依赖项，请将以下行添加到 CMake 依赖性文件中，CMakeLists.txt，用于您的自定义 Wi-Fi 组件。 

    # Add a dependency on the bluetooth espressif component to the common component
set(COMPONENT_REQUIRES lwip)

构建应用程序

  1. 将目录更改为 build 目录。

  2. 调用 Ninja 以构建应用程序。

    ninja

    或者，使用通用 CMake 接口来构建应用程序。

    cmake --build build-directory
    注意

    每当您在 aws_demos 项目和 aws_tests 项目之间切换时，都必须使用 cmake 命令构建生成文件。

闪存并运行 FreeRTOS 转换器（ESP-IDF v3.3）

本节说明如何在 Espressif 硬件上使用 ESP-IDF v3.3。若要使用 ESP-IDF v4.2，请参阅开始使用 ESP-IDF 版本。

使用 Espressif 的 IDF 实用程序 (freertos/vendors/espressif/esp-idf/tools/idf.py) 刷写您的主板、运行应用程序并查看日志。

要擦除主板的闪存，请转到freertos目录中，然后使用以下命令。 

./vendors/espressif/esp-idf/tools/idf.py erase_flash -B build-directory

要将应用程序二进制文件刷入您的主板，请使用make

make flash

您也可以使用 IDF 脚本以刷写主板：

./vendors/espressif/esp-idf/tools/idf.py flash -B build-directory

如需监控，请使用以下命令：

./vendors/espressif/esp-idf/tools/idf.py monitor -p /dev/ttyUSB1 -B build-directory
注意

您可以组合使用这些命令。例如：

./vendors/espressif/esp-idf/tools/idf.py erase_flash flash monitor -p /dev/ttyUSB1 -B build-directory

开始使用 ESP-IDF 版本

本节说明如何在 Espressif 硬件上使用 ESP-IDF v4.2。若要使用 ESP-IDF v3.3，请参阅开始使用 ESP-IDF v3.3。

注意

本教程中的 Linux 命令需要您使用 Bash shell。

设置 Espressif 硬件

有关设置 ESP32-DevKitC 开发主板硬件的信息，请参阅ESP32 开发基础 V4 入门指南。

有关设置 ESP-WROVER-KIT 开发主板硬件的信息，请参阅ESP-WROVER-KIT V4.1 入门指南。

重要

当您到达开始使用部分，停止，然后返回到此页面上的说明。

设置开发环境

要与您的主板进行通信，您必须下载并安装工具链。

设置工具链

要设置工具链，请按照适用于您的主机操作系统的以下说明操作：

重要

当您到达后续步骤，停止，然后返回此页面上的说明。

完成安装（Linux/MacOS）

ESP-IDF Windows 安装程序安装所有必要的工具。Linux 和 MacOS 平台需要额外的步骤才能完成安装。

  1. 打开命令行窗口

  2. 导航到 FreeRTOS 下载目录，然后运行以下脚本，下载并安装适用于您平台的乐鑫工具链。

    vendors/espressif/esp-idf/install.sh

  3. 使用以下命令将 ESP-IDF 工具链工具添加到终端路径中。

    source vendors/espressif/esp-idf/export.sh

建立串行连接

要在您的主机和 ESP32-DevKitC 之间建立串行连接，必须安装 CP210x USB to UART Bridge VCP 驱动程序。您可以从 Silicon Labs 下载这些驱动程序。

要在您的主机和 ESP32-WROVER-KIT 之间建立串行连接，必须安装 FTDI 虚拟 COM 端口驱动程序。您可以从FTDI。

有关更多信息，请参阅使用 ESP32 建立串行连接。建立串行连接后，记下主板连接的串行端口。在构建演示时需要用到它。

下载并配置 FreeRTOS

设置环境后，您可以从下载 FreeRTOSGitHub，或来自FreeRTOS 控制台。有关说明，请参阅自述文件文 GitHub。

配置 FreeRTOS 演示应用程序

  1. 如果您运行的是 macOS 或 Linux，请打开终端提示符。如果您运行的是 Windows，请打开mingw32.exe。(MinGW 文是一个适用于本机 Microsoft Windows 应用程序的简约开发环境。）

  2. 要验证您已安装 Python3，请运行 

    python --version

    此时显示已安装的版本。如果未安装 Python 3.0.1 或更高版本，则可以从Python网站。

  3. 您需要AWS Command Line Interface(AWS CLI）运行AWS IoT命令。如果运行的是 Windows，请使用easy_install awscli安装AWS CLI）。

    如果您运行的是 macOS 或 Linux，请参阅安装AWS CLI。

  4. Run 

    aws configure

    配置AWS CLI与您的AWS访问密钥 ID、私有访问密钥和默认值AWS区域。有关更多信息，请参阅配置 AWS CLI。

  5. 使用以下命令安装AWS适用于 Python (boto3) 的开发工具包：

    • 在 Windows 上的 mingw32 环境中，运行 

      easy_install boto3

    • 在 macOS 或 Linux 上，运行 

      pip install tornado nose --user

      然后运行 

      pip install boto3 --user

FreeRTOS 包括SetupAWS.py脚本，可以更轻松地设置您的 Espressif 主板以连接到AWS IoT。要配置此脚本，请打开 freertos/tools/aws_config_quick_start/configure.json 并设置以下属性：

afr_source_dir

完整路径FreeRTOS目录。确保您使用正斜杠来指定此路径。

thing_name

要分配给代表您的主板的 AWS IoT 事物的名称。

wifi_ssid

Wi-Fi 网络的 SSID。

wifi_password

Wi-Fi 网络的密码。

wifi_security

Wi-Fi 网络的安全类型。

有效安全类型有：

  • eWiFiSecurityOpen（开放，不安全）

  • eWiFiSecurityWEP（WEP 安全性）

  • eWiFiSecurityWPA（WPA 安全性）

  • eWiFiSecurityWPA2（WPA2 安全性）

运行配置脚本

  1. 如果您运行的是 macOS 或 Linux，请打开终端提示符。如果运行的是 Windows，请打开mingw32.exe文件。

  2. 导航到freertos/tools/aws_config_quick_start目录并运行 

    python SetupAWS.py setup

该脚本执行以下操作：

  • 创建一个 IoT 事物、证书和策略

  • 将 IoT 策略附加到证书，将证书附加到 AWS IoT 事物

  • 使用您的 AWS IoT 终端节点、Wi-Fi SSID 和凭证填充 aws_clientcredential.h 文件

  • 设置您的证书和私有密钥格式，然后将其写入 aws_clientcredential_keys.h 标头文件

    注意

    仅出于演示目的对证书进行了硬编码。生产级应用程序应将这些文件存储在安全位置。

有关 的更多信息SetupAWS.py，请参阅README.md中的freertos/tools/aws_config_quick_start目录。

使用 idy.py 脚本构建、刷写和运行 FreeRTOS 演示项目

您可以使用乐鑫的 IDF 实用程序生成构建文件，生成应用程序二进制文件，然后刷写主板。

在 Windows、Linux 和 MacOS 上构建并刷写 FreeRTOS（ESP-IDF 4.2 版）

使用idf.py脚本来构建项目并将二进制文件闪存到您的设备上。

注意

某些设置可能要求您使用端口选项"-p port-name"替换为idf.py指定正确的端口，如下例中所示。 

idf.py -p /dev/cu.usbserial-00101301B flash

生成并刷写项目

  1. 导航到 FreeRTOS 下载目录的根目录。

  2. 在命令行窗口中，输入以下命令以将 ESP-IDF 工具添加到终端的 PATH 中。

    Windows

    vendors\espressif\esp-idf\export.bat

    Linux /MacOS

    source vendors/espressif/esp-idf/export.sh

  3. 在build目录并使用以下命令构建固件映像。 

    idf.py -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 build

    将会看到类似下面的输出。

    Running cmake in directory /path/to/hello_world/build
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
Warn about uninitialized values.
-- Found Git: /usr/bin/git (found version "2.17.0")
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...

... (more lines of build system output)

[527/527] Generating hello-world.bin
esptool.py v2.3.1

Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
or run 'idf.py -p PORT flash'

    如果没有错误，构建将生成固件二进制 .bin 文件。

  4. 使用以下命令擦除开发板的闪存。

    idf.py erase_flash

  5. 使用idf.py脚本将应用程序二进制文件刷写到您的主板。 

    idf.py flash

  6. 使用以下命令监控主板串行端口的输出。

    idf.py monitor
注意

您可以合并这些命令，如以下示例所示。

idf.py erase_flash flash monitor
注意

对于某些主机设置，您必须在闪烁主板时指定端口，如以下示例所示。

idf.py erase_flash flash monitor -p /dev/ttyUSB1

使用 CMake 构建和闪存 FreeRTOS

除了idf.py脚本来构建和运行代码，您也可以使用 CMake 构建项目。目前，它支持 Unix 生成文件或忍者构建系统。

生成并刷写项目

  1. 在命令行窗口中，导航到 FreeRTOS 下载目录的根。

  2. 运行以下脚本，将 ESP-IDF 工具添加到外壳的 PATH 中。

    Windows

    vendors\espressif\esp-idf\export.bat

    Linux /MacOS

    source vendors/espressif/esp-idf/export.sh

  3. 输入以下命令以生成构建文件。

    使用 Unix 生成文件

    cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0

    与忍者

    cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja

  4. 擦除闪光灯，然后闪烁电路板。

    使用 Unix 生成文件

    make -C ./YOUR_BUILD_DIRECTORY erase_flash
    make -C ./YOUR_BUILD_DIRECTORY flash

    与忍者

    ninja -C ./YOUR_BUILD_DIRECTORY erase_flash
    ninja -C ./YOUR_BUILD_DIRECTORY flash

在云上监控 MQTT 消息

您可以使用 AWS IoT 控制台中的 MQTT 客户端监控您的设备发送到 AWS 云的消息。

使用 AWS IoT MQTT 客户端订阅 MQTT 主题

  1. 导航到 AWS IoT 控制台。

  2. 在导航窗格中，选择测试以打开 MQTT 客户端。

  3. 在 Subscription topic (订阅主题)中，输入 your-thing-name/example/topic，然后选择 Subscribe to topic (订阅主题)。

运行低功耗蓝牙演示

FreeRTOS 支持低功耗蓝牙连接性。

要跨低功耗蓝牙运行 FreeRTOS 演示项目，您必须在 iOS 或 Android 移动设备上运行 FreerTOS 低功耗蓝牙移动开发工具包演示应用程序。

设置 FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序

  1. 按照中的说明进行操作适用于 FreeRTOS 蓝牙设备的移动开发工具包，在您的主机上下载并安装适用于移动平台的开发工具包。

  2. 按照中的说明进行操作FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序在您的移动设备上设置演示移动应用程序。

有关如何在主板上运行低功耗蓝牙 MQTT 演示的说明，请参阅低功耗蓝牙 MQTT 演示应用程序。

有关如何在主板上运行 Wi-Fi 预置演示的说明，请参阅 Wi-Fi 预置演示应用程序。

在 ESP32 的 CMake 项目中使用 FreeRTOS

如果要在您自己的 CMake 项目中使用 FreeRTOS，您可以将它设置为子目录并与应用程序一起构建。首先，获取 FreeRTOS 的副本，无论是从GitHub或来自的FreeRTOS 控制台。如果您使用的是 Git，您也可以使用以下命令将它设置为 Git 子模块，以便将来更轻松地更新。 

git submodule add -b release https://github.com/aws/amazon-freertos.git freertos

如果已发布更高版本，则可使用这些命令更新本地副本。

# Pull the latest changes from the remote tracking branch.
git submodule update --remote -- freertos
# Commit the submodule change because it is pointing to a different revision now.
git add freertos
git commit -m "Update FreeRTOS to a new release"

如果您的项目具有以下目录结构：

- freertos (the copy that you obtained from GitHub or the AWS IoT console)
- src
  - main.c (your application code)
- CMakeLists.txt

然后下面是顶级CMakeLists.txt文件，可以用于构建您的应用程序与 FreeRTOS 一起使用。

ESP-IDF v3.3
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

add_executable(my_app src/main.c)

# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)

# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::mqtt)
ESP-IDF v4.2
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

# Pull in ESP-IDF defined CMake build infrastructure logic to configure the project, discover all the components, etc
set(esp_idf_dir "${CMAKE_CURRENT_LIST_DIR}/freertos/vendors/espressif/esp-idf")
include(${esp_idf_dir}/tools/cmake/idf.cmake)

# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)
get_filename_component(
    IDF_EXECUTABLE_SRCS
    "src/main.c" ABSOLUTE
    )

要构建项目，请运行以下 CMake 命令。确保 ESP32 编译器位于 PATH 环境变量中。

cmake -S . -B build-directory -DCMAKE_TOOLCHAIN_FILE=freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja
cmake --build build

要将应用程序刷写到您的主板，请运行以下命令。

cmake --build build-directory --target flash

使用 FreeRTOS 中的组件

在运行 CMake 后，您可以在摘要输出中找到所有可用的组件。它应与以下示例类似。

====================Configuration for FreeRTOS====================
  Version:                 201910.00
  Git version:             201910.00-388-gcb3612cb7

Target microcontroller:
  vendor:                  Espressif
  board:                   ESP32-DevKitC
  description:             Development board produced by Espressif that comes in two
                           variants either with ESP-WROOM-32 or ESP32-WROVER module
  family:                  ESP32
  data ram size:           520KB
  program memory size:     4MB

Host platform:
  OS:                      Linux-4.15.0-66-generic
  Toolchain:               xtensa-esp32
  Toolchain path:          /opt/xtensa-esp32-elf
  CMake generator:         Ninja

FreeRTOS modules:
  Modules to build:        ble, ble_hal, ble_wifi_provisioning, common, crypto, defender,
                           dev_mode_key_provisioning, freertos_plus_tcp, greengrass,
                           https, kernel, mqtt, ota, pkcs11, pkcs11_implementation,
                           platform, secure_sockets, serializer, shadow, tls, wifi
  Enabled by user:         ble, ble_hal, ble_wifi_provisioning, defender, greengrass,
                           https, mqtt, ota, pkcs11, pkcs11_implementation, platform,
                           secure_sockets, shadow, wifi
  Enabled by dependency:   common, crypto, demo_base, dev_mode_key_provisioning,
                           freertos, freertos_plus_tcp, kernel, pkcs11_mbedtls,
                           secure_sockets_freertos_plus_tcp, serializer, tls, utils
  3rdparty dependencies:   http_parser, jsmn, mbedtls, pkcs11, tinycbor
  Available demos:         demo_ble, demo_ble_numeric_comparison, demo_defender,
                           demo_greengrass_connectivity, demo_https, demo_mqtt, demo_ota,
                           demo_shadow, demo_tcp, demo_wifi_provisioning
  Available tests:
=========================================================================

您可以引用Modules to build列表。要将它们链接到您的应用程序，请将AFR::命名空间，例如AFR::mqtt、AFR::ota等等。

将自定义组件添加到 ESP-IDF

可以向 ESP-IDF 构建环境添加更多组件。例如，假定您想添加一个名为example_component，你的项目看起来像这样 

- freertos
- components
  - example_component
    - include
      - example_component.h
    - src
      - example_component.c
    - CMakeLists.txt
- src
  - main.c
- CMakeLists.txt

，那么以下是CMakeLists.txt文件。

ESP-IDF v3.3
# include paths of this components.
set(COMPONENT_ADD_INCLUDEDIRS include)

# source files of this components.
set(COMPONENT_SRCDIRS src)
# Alternatively, use COMPONENT_SRCS to specify source files explicitly
# set(COMPONENT_SRCS src/example_component.c)

# add this components, this will define a CMake library target.
register_component()
ESP-IDF v4.2
# Use idf_component_register to add this component, this will define a CMake library target.
# Specify component sources in SRCS.
# Specify component include directories in INCLUDE_DIRS.
idf_component_register(SRCS "src/foo.c"
                       INCLUDE_DIRS "include")
# Standard CMake function can be used to specify dependencies. ${COMPONENT_TARGET} is defined
# from esp-idf when you call register_component, by default it's idf_component_<folder_name>.
target_link_libraries(${COMPONENT_TARGET} PRIVATE AFR::mqtt)

您还可以使用标准 CMake 函数 target_link_libraries 指定依赖关系。请注意，组件的目标名称存储在由 ESP-IDF 定义的变量 COMPONENT_TARGET 中。

ESP-IDF v3.3
# add this component, this will define a CMake library target.
register_component()

# standard CMake function can be used to specify dependencies. ${COMPONENT_TARGET} is defined
# from esp-idf when you call register_component, by default it's idf_component_<folder_name>.
target_link_libraries(${COMPONENT_TARGET} PRIVATE AFR::mqtt)
ESP-IDF v4.2
# add this component, this will define a CMake library target.
idf_component_register(SRCS "src/foo.c"
                       INCLUDE_DIRS "include")

# standard CMake function can be used to specify dependencies. ${COMPONENT_TARGET} is defined
# from esp-idf when you call register_component, by default it's idf_component_<folder_name>.
target_link_libraries(${COMPONENT_TARGET} PRIVATE AFR::mqtt)

对于 ESP 组件，可通过设置两个变量来做到这一点。COMPONENT_REQUIRES和COMPONENT_PRIV_REQUIRES。请参阅构建系统（CMake）中的ESP-IDF 编程指南第 4.2 版。

ESP-IDF v3.3
# If the dependencies are from ESP-IDF, use these 2 variables. Note these need to be
# set before calling register_component().
set(COMPONENT_REQUIRES log)
set(COMPONENT_PRIV_REQUIRES lwip)
ESP-IDF v4.2
# If the dependencies are from ESP-IDF, use these 2 variables (REQUIRES, PRIV_REQUIRES) 
#   in the idf_component_register call: (Refer here for information on the 
#   idf_component_register function: https://docs.espressif.com/projects/esp-idf/en/v4.2/esp32/api-guides/build-system.html#cmake-component-register)
idf_component_register(SRCS "src/foo.c"
                       INCLUDE_DIRS "include"
                       REQUIRES log
                       PRIV_REQUIRES lwip)

然后，在顶级 CMakeLists.txt 文件中，告知 ESP-IDF 从何处查找这些组件。在之前的任何位置添加以下行add_subdirectory(freertos)。

ESP-IDF v3.3
# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is a variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/example_component" ABSOLUTE
)
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})
ESP-IDF v4.2
# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is a variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/example_component" ABSOLUTE
)
idf_build_component(${EXTRA_COMPONENT_DIRS})

默认情况下，此组件现在将自动链接到您的应用程序代码。您应能够包含其标头文件并调用它定义的函数。

覆盖 FreeRTOS 的配置

目前，在 FreeRTOS 源树外部，还没有明确定义的方法来重新定义配置。默认情况下，CMake 将在 freertos/vendors/espressif/boards/esp32/aws_demos/config_files/ 和 freertos/demos/include/ 目录中进行查找。但是，可以使用解决方法来告知编译器首先搜索其他目录。例如，您可以为 FreeRTOS 配置添加其他文件夹。 

- freertos
- freertos-configs
  - aws_clientcredential.h
  - aws_clientcredential_keys.h
  - iot_mqtt_agent_config.h
  - iot_config.h
- components
- src
- CMakeLists.txt

freertos-configs 下的文件是从 freertos/vendors/espressif/boards/esp32/aws_demos/config_files/ 和 freertos/demos/include/ 目录复制的。然后，在你的顶级CMakeLists.txt文件，请在add_subdirectory(freertos)以便编译器首先搜索此目录。 

include_directories(BEFORE freertos-configs)

为 ESP-IDF 提供您自己的 sdkconfig

如果要提供您自己的 sdkconfig.default，您可以从命令行设置 CMake 变量 IDF_SDKCONFIG_DEFAULTS： 

cmake -S . -B build-directory -DIDF_SDKCONFIG_DEFAULTS=path_to_your_sdkconfig_defaults -DCMAKE_TOOLCHAIN_FILE=freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja

如果您不为自己的sdkconfig.default文件，FreeRTOS 将使用位于freertos/vendors/espressif/boards/esp32/aws_demos/sdkconfig.defaults。

Summary

如果您的项目具有一个名为 example_component 的组件，并且您要覆盖某些配置，以下是顶级 CMakeLists.txt 文件的完整示例。

ESP-IDF v3.3
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

add_executable(my_app src/main.c)

# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)

# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is a variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/example_component" ABSOLUTE
)
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})

# Override the configurations for FreeRTOS.
include_directories(BEFORE freertos-configs)

# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::mqtt)
ESP-IDF v4.2
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

# Pull in ESP-IDF defined CMake build infrastructure logic to configure the project, discover all the components, etc
set(esp_idf_dir "${CMAKE_CURRENT_LIST_DIR}/freertos/vendors/espressif/esp-idf")
include(${esp_idf_dir}/tools/cmake/idf.cmake)
# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)
get_filename_component(
    IDF_EXECUTABLE_SRCS
    "src/main.c" ABSOLUTE
    )
# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is an variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/foo" ABSOLUTE
)
idf_build_component(${EXTRA_COMPONENT_DIRS})

# Override the configurations for FreeRTOS.
include_directories(BEFORE freertos-configs)

# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::mqtt)

有关使用 CMake 构建系统的更多信息，请参阅生成系统在乐鑫 API 指南中

Troubleshooting

  • 如果您运行的是 macOS，而该操作系统不会识别您的 ESP-WROVER-KIT，请确保您未安装 D2XX 驱动程序。要卸载它们，请按照适用于 macOS X 的 FTDI 驱动程序安装指南中的说明操作。

  • ESP-IDF 提供的监控实用程序（使用 make monitor 调用）可帮助您解码地址。因此，在应用程序停止工作时，它可以帮助您获取一些有意义的回溯跟踪信息。有关更多信息，请参阅 。自动地址解码）。

  • 还可以启用 GDBstub 来通过 gdb 通信，无需任何特殊 JTAG 硬件。有关更多信息，请参阅 。使用 GDB存根启动 GDB）。

  • 有关设置基于 OpenOCD 的环境的信息（如果需要基于 JTAG 硬件的调试），请参阅。JTAG 调试）。

  • 如果pyserial不能使用pip下载，请从pyrun 网站。

  • 如果主板连续重置，请尝试通过在终端上输入以下命令来擦除闪存。

    make erase_flash

  • 如果您在运行 idf_monitor.py 时看到错误，请使用 Python 2.7。

  • ESP-IDF 中必需的库包括在 FreeRTOS 中，因此无需从外部下载它们。如果IDF_PATH环境变量，我们建议您在生成 FreeRTOS 之前清除它。

  • 在 Windows 上，生成项目可能需要 3-4 分钟。您可在 make 命令上使用 -j4 开关来缩短生成时间： 

    make flash monitor -j4

  • 如果您的设备无法连接到 AWS IoT，请打开 aws_clientcredential.h 文件并验证该文件中的配置变量已正确定义。clientcredentialMQTT_BROKER_ENDPOINT[] 应类似于 1234567890123-ats.iot.us-east-1.amazonaws.com。

  • 如果您遵循在 ESP32 的 CMake 项目中使用 FreeRTOS中的步骤，并且您看到来自链接器的未定义的引用错误，则通常是由于缺少关联的库或演示所致。要添加它们，请使用标准 CMake 函数 target_link_libraries 更新 CMakeLists.txt 文件（在根目录下） 。

  • ESP-IDF v4.2 支持使用xtensa-esp32-elf-gcc 8.2.0。工具链。如果您使用的是较早版本的 Xtensa 工具链，请下载所需版本。

  • 如果您看到类似以下内容的错误日志，有关 ESP-IDF v4.2 未满足的 python 依赖关系。

    The following Python requirements are not satisfied:
click>=5.0
pyserial>=3.0
future>=0.15.2
pyparsing>=2.0.3,<2.4.0
pyelftools>=0.22
gdbgui==0.13.2.0
pygdbmi<=0.9.0.2
reedsolo>=1.5.3,<=1.5.4
bitstring>=3.1.6
ecdsa>=0.16.0
Please follow the instructions found in the "Set up the tools" section of ESP-IDF Getting Started Guide

    使用以下 Python 命令在您的平台上安装 python 依赖关系：

    root/vendors/espressif/esp-idf/requirements.txt

有关更多故障排除信息，请参阅问题排查入门。

Debugging

在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 上调试代码

本节介绍如何使用 ESP-IDF v3.3 调试乐鑫硬件。若要使用 ESP-IDF v4.2 进行调试，请参阅在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 上调试代码。

您需要 JTAG 到 USB 电缆。我们使用 USB 到 MPSSE 电缆（例如，FTDI C232HM-DDHSL-0）。

ESP-DevKitC JTAG 设置

对于 FTDI C232HM-DDHSL-0 电缆，以下是与 ESP32 DevkitC 的连接。

C232HM-DDHSL-0 电线颜色 ESP32 GPIO 针脚 JTAG 信号名称

棕色（针脚 5）

IO14

TMS

黄色（针脚 3）

IO12

TDI

黑色（针脚 10）

GND

GND

橙色（针脚 2）

IO13

TCK

绿色（针脚 4）

IO15

TDO

ESP-WROVER-KIT JTAG 设置

对于 FTDI C232HM-DDHSL-0 电缆，以下是与 ESP32-WROVER-KIT 的连接。

C232HM-DDHSL-0 电线颜色 ESP32 GPIO 针脚 JTAG 信号名称

棕色（针脚 5）

IO14

TMS

黄色（针脚 3）

IO12

TDI

橙色（针脚 2）

IO13

TCK

绿色（针脚 4）

IO15

TDO

这些表源自 FTDI C232HM-DDHSL-0 数据表。有关更多信息，请参阅数据表中的 “C232HM MPSSE 电缆连接和机械详细信息” 部分。

要在 ESP-WROVER-KIT 上启用 JTAG，请将跳线放在 TMS、TDO、TDI、TCK 和 S_TDI 针脚上，如此处所示。

跳线位置

在窗口上进行调试（ESP-IDF v3.3）

在 Windows 上设置调试

  1. 将 FTDI C232HM-DDHSL-0 的 USB 一端连接到您的计算机，另一端的操作如在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 上调试代码中所述。FTDI C232HM-DDHSL-0 设备应显示在设备管理器下的通用串行总线控制器中。

  2. 在通用串行总线设备列表下，右键单击 C232HM-DDHSL-0 设备，然后选择 Properties (属性)。

    注意

    该设备可能被列为 USB Serial Port (USB 串行端口)。

    在属性窗口中，选择详细信息选项卡以查看设备的属性。如果设备未列出，请安装适用于 FTDI C232HM-DDHSL-0 的 Windows 驱动程序。

  3. 在 Details (详细信息) 选项卡上，选择 Property (属性)，然后选择 Hardware IDs (硬件 ID)。您应看到与以下类似的内容。值字段。 

    FTDIBUS\COMPORT&VID_0403&PID_6014

    在此示例中，供应商 ID 为 0403，产品 ID 为 6014。

    验证这些 ID与 projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg 中的 ID 匹配。ID 在以开头的行中指定ftdi_vid_pid后跟供应商 ID 和产品 ID。 

    ftdi_vid_pid 0x0403 0x6014

  4. 下载 OpenOCD for Windows。

  5. 将文件解压缩到 C:\ 并将 C:\openocd-esp32\bin 添加到系统路径。

  6. OpenOCD 需要 libusb，默认情况下未在 Windows 上安装。

    安装 libusb

    1. 下载 zadig.exe。

    2. 运行 zadig.exe。在 Options (选项) 菜单中，选择 List All Devices (列出所有设备)。

    3. 从下拉菜单中，选择 C232HM-DDHSL-0。

    4. 在绿色箭头右侧的目标驱动程序字段中，选择 WinUSB。

    5. 从目标驱动程序字段下方的下拉列表中，选择箭头，然后选择安装驱动程序。选择 Replace Driver (替换驱动程序)。

  7. 打开命令提示符窗口，导航到projects/espressif/esp32/make/aws_demos并运行以下命令。

    对于 ESP32-WROOM-32 和 ESP32-WROVER

    openocd.exe -f esp32_devkitj_v1.cfg -f esp-wroom-32.cfg

    对于 ESP32-SOLO-1

    openocd.exe -f esp32_devkitj_v1.cfg -f esp-solo-1.cfg

    保持此命令提示符窗口处于打开状态。

  8. 打开一个新的命令提示符窗口，导航到您的 msys32 目录，然后运行 mingw32.exe。

  9. 在 mingw32 终端内，导航到projects/espressif/esp32/make/aws_demos并运行 

    make flash monitor

  10. 打开另一个 mingw32 终端，导航到 projects/espressif/esp32/make/aws_demos，然后等到演示开始在您的主板上运行。开始演示时，请运行 xtensa-esp32-elf-gdb -x gdbinit build/aws_demos.elf。程序应在 main 函数中停止。

注意

ESP32 支持最多两个断点。

在 macOS 上进行调试（ESP-IDF 版本 3.3）

  1. 下载适用于 macOS 的 FTDI 驱动程序。

  2. 下载 OpenOCD。

  3. 提取下载的 .tar 文件，并将 .bash_profile 中的路径设置为 OCD_INSTALL_DIR/openocd-esp32/bin。

  4. 使用以下命令安装libusb在 macOS 上。 

    brew install libusb

  5. 使用以下命令卸载串行端口驱动程序。

    sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

  6. 如果您在高于 10.9 的 macOS 版本上运行，请使用以下命令卸载 Apple 的 FTDI 驱动程序。

    sudo kextunload -b com.apple.driver.AppleUSBFTDI

  7. 使用以下命令获取 FTDI 电缆的产品 ID 和供应商 ID。它会列出连接的 USB 设备。

    system_profiler SPUSBDataType

    来自的输出system_profiler应与以下内容类似。 

    DEVICE:
                            
Product ID: product-ID
Vendor ID: vendor-ID (Future Technology Devices International Limited)

  8. 打开 projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg 文件。设备的供应商 ID 和产品 ID 在以 ftdi_vid_pid 开头的行中指定。更改 ID 以匹配上一步骤 system_profiler 输出中的 ID。

  9. 打开终端窗口，导航到 projects/espressif/esp32/make/aws_demos，然后使用以下命令运行 OpenOCD：

    对于 ESP32-WROOM-32 和 ESP32-WROVER：

    openocd -f esp32_devkitj_v1.cfg -f esp-wroom-32.cfg

    对于 ESP32-SOLO-1：

    openocd -f esp32_devkitj_v1.cfg -f esp-solo-1.cfg

  10. 打开一个新的终端，使用以下命令来加载 FTDI 串行端口驱动程序。

    sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver

  11. 导航到 projects/espressif/esp32/make/aws_demos 并运行以下命令。 

    make flash monitor

  12. 打开另一个新终端，导航到projects/espressif/esp32/make/aws_demos，然后运行以下命令。 

    xtensa-esp32-elf-gdb -x gdbinit build/aws_demos.elf

    程序应在 main() 停止。

在 Linux 上进行调试（ESP-IDF v3.3）

  1. 下载 OpenOCD。提取 tarball 并按照自述文件中的安装说明操作。

  2. 使用以下命令在 Linux 上安装 libusb。

    sudo apt-get install libusb-1.0

  3. 打开终端并输入 ls -l /dev/ttyUSB* 来列出连接到您计算机的所有 USB 设备。这可以帮助您检查操作系统是否识别主板上的 USB 端口。将会看到类似下面的输出。 

    $ls -l /dev/ttyUSB*
crw-rw----    1    root    dialout    188,    0    Jul    10    19:04    /dev/ttyUSB0
crw-rw----    1    root    dialout    188,    1    Jul    10    19:04    /dev/ttyUSB1

  4. 注销，然后登录并重新对主板加电，使更改生效。在终端提示符下，列出 USB 设备。确保组所有者已从dialout到plugdev。 

    $ls -l /dev/ttyUSB*
crw-rw----    1    root    plugdev    188,    0    Jul    10    19:04    /dev/ttyUSB0
crw-rw----    1    root    plugdev    188,    1    Jul    10    19:04    /dev/ttyUSB1

    较小编号的 /dev/ttyUSBn 接口用于 JTAG 通信。其他接口路由到 ESP32 的串行端口 (UART)，用于将代码上传到 ESP32 的闪存。

  5. 在终端窗口中，导航到 projects/espressif/esp32/make/aws_demos，然后使用以下命令运行 OpenOCD。

    对于 ESP32-WROOM-32 和 ESP32-WROVER：

    openocd -f esp32_devkitj_v1.cfg -f esp-wroom-32.cfg

    对于 ESP32-SOLO-1：

    openocd -f esp32_devkitj_v1.cfg -f esp-solo-1.cfg

  6. 打开另一个终端，导航到projects/espressif/esp32/make/aws_demos，然后运行以下命令。 

    make flash monitor

  7. 打开另一个终端，导航到 projects/espressif/esp32/make/aws_demos 并运行以下命令： 

    xtensa-esp32-elf-gdb -x gdbinit build/aws_demos.elf

    程序应在 main() 中停止。

在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 上调试代码

本节介绍如何使用 ESP-IDF v4.2 调试乐鑫硬件。若要使用 ESP-IDF v3.3 进行调试，请参阅在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 上调试代码。

您需要 JTAG 到 USB 电缆。我们使用 USB 到 MPSSE 电缆（例如，FTDI C232HM-DDHSL-0）。

ESP-DevKitC JTAG 设置

对于 FTDI C232HM-DDHSL-0 电缆，以下是与 ESP32 DevkitC 的连接。

C232HM-DDHSL-0 电线颜色 ESP32 GPIO 针脚 JTAG 信号名称

棕色（针脚 5）

IO14

TMS

黄色（针脚 3）

IO12

TDI

黑色（针脚 10）

GND

GND

橙色（针脚 2）

IO13

TCK

绿色（针脚 4）

IO15

TDO

ESP-WROVER-KIT JTAG 设置

对于 FTDI C232HM-DDHSL-0 电缆，以下是与 ESP32-WROVER-KIT 的连接。

C232HM-DDHSL-0 电线颜色 ESP32 GPIO 针脚 JTAG 信号名称

棕色（针脚 5）

IO14

TMS

黄色（针脚 3）

IO12

TDI

橙色（针脚 2）

IO13

TCK

绿色（针脚 4）

IO15

TDO

这些表源自 FTDI C232HM-DDHSL-0 数据表。有关更多信息，请参阅数据表中的 “C232HM MPSSE 电缆连接和机械详细信息” 部分。

要在 ESP-WROVER-KIT 上启用 JTAG，请将跳线放在 TMS、TDO、TDI、TCK 和 S_TDI 针脚上，如此处所示。

跳线位置

在窗口上进行调试（ESP-IDF v4.2）

在 Windows 上设置调试

  1. 将 FTDI C232HM-DDHSL-0 的 USB 一端连接到您的计算机，另一端的操作如在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 上调试代码中所述。FTDI C232HM-DDHSL-0 设备应显示在设备管理器下的通用串行总线控制器中。

  2. 在通用串行总线设备列表下，右键单击 C232HM-DDHSL-0 设备，然后选择 Properties (属性)。

    注意

    该设备可能被列为 USB Serial Port (USB 串行端口)。

    在属性窗口中，选择详细信息选项卡以查看设备的属性。如果设备未列出，请安装适用于 FTDI C232HM-DDHSL-0 的 Windows 驱动程序。

  3. 在 Details (详细信息) 选项卡上，选择 Property (属性)，然后选择 Hardware IDs (硬件 ID)。您应看到与以下类似的内容。值字段。 

    FTDIBUS\COMPORT&VID_0403&PID_6014

    在此示例中，供应商 ID 为 0403，产品 ID 为 6014。

    验证这些 ID与 projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg 中的 ID 匹配。ID 在以开头的行中指定ftdi_vid_pid后跟供应商 ID 和产品 ID。 

    ftdi_vid_pid 0x0403 0x6014

  4. 下载 OpenOCD for Windows。

  5. 将文件解压缩到 C:\ 并将 C:\openocd-esp32\bin 添加到系统路径。

  6. OpenOCD 需要 libusb，默认情况下未在 Windows 上安装。

    安装 libusb

    1. 下载 zadig.exe。

    2. 运行 zadig.exe。在 Options (选项) 菜单中，选择 List All Devices (列出所有设备)。

    3. 从下拉菜单中，选择 C232HM-DDHSL-0。

    4. 在绿色箭头右侧的目标驱动程序字段中，选择 WinUSB。

    5. 从目标驱动程序字段下方的下拉列表中，选择箭头，然后选择安装驱动程序。选择 Replace Driver (替换驱动程序)。

  7. 打开命令提示符窗口，导航到 FreeRTOS 下载目录的根目录，然后运行以下命令。

    idf.py openocd

    保持此命令提示符窗口处于打开状态。

  8. 打开一个新的命令提示符窗口，导航到您的 FreeRTOS 下载目录的根目录，然后运行 

    idf.py flash monitor

  9. 打开其他命令提示符，导航到 FreeRTOS 下载目录的根目录，然后等到演示开始在主板上运行。执行操作时，运行 

    idf.py gdb

    程序应在 main 函数中停止。

注意

ESP32 支持最多两个断点。

在 macOS 上进行调试（ESP-IDF 版本 4.2）

  1. 下载适用于 macOS 的 FTDI 驱动程序。

  2. 下载 OpenOCD。

  3. 提取下载的 .tar 文件，并将 .bash_profile 中的路径设置为 OCD_INSTALL_DIR/openocd-esp32/bin。

  4. 使用以下命令安装libusb在 macOS 上。 

    brew install libusb

  5. 使用以下命令卸载串行端口驱动程序。

    sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

  6. 如果您在高于 10.9 的 macOS 版本上运行，请使用以下命令卸载 Apple 的 FTDI 驱动程序。

    sudo kextunload -b com.apple.driver.AppleUSBFTDI

  7. 使用以下命令获取 FTDI 电缆的产品 ID 和供应商 ID。它会列出连接的 USB 设备。

    system_profiler SPUSBDataType

    来自的输出system_profiler应与以下内容类似。 

    DEVICE:
                            
Product ID: product-ID
Vendor ID: vendor-ID (Future Technology Devices International Limited)

  8. 打开 projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg 文件。设备的供应商 ID 和产品 ID 在以 ftdi_vid_pid 开头的行中指定。更改 ID 以匹配上一步骤 system_profiler 输出中的 ID。

  9. 打开终端窗口，导航到 FreeRTOS 下载目录的根目录，然后使用以下命令运行 OpenOCD：

    idf.py openocd

    保持终端窗口处于打开状态。

  10. 打开一个新的终端，使用以下命令来加载 FTDI 串行端口驱动程序。

    sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver

  11. 导航到 FreeRTOS 下载目录的根目录，并运行 

    idf.py flash monitor

  12. 打开另一个新终端，导航到您的 FreeRTOS 下载目录的根目录，然后运行 

    idf.py gdb

    程序应在 main 停止。

在 Linux 上进行调试（ESP-IDF 第 4.2 版）

  1. 下载 OpenOCD。提取 tarball 并按照自述文件中的安装说明操作。

  2. 使用以下命令在 Linux 上安装 libusb。

    sudo apt-get install libusb-1.0

  3. 打开终端并输入 ls -l /dev/ttyUSB* 来列出连接到您计算机的所有 USB 设备。这可以帮助您检查操作系统是否识别主板上的 USB 端口。将会看到类似下面的输出。 

    $ls -l /dev/ttyUSB*
crw-rw----    1    root    dialout    188,    0    Jul    10    19:04    /dev/ttyUSB0
crw-rw----    1    root    dialout    188,    1    Jul    10    19:04    /dev/ttyUSB1

  4. 注销，然后登录并重新对主板加电，使更改生效。在终端提示符下，列出 USB 设备。确保组所有者已从dialout到plugdev。 

    $ls -l /dev/ttyUSB*
crw-rw----    1    root    plugdev    188,    0    Jul    10    19:04    /dev/ttyUSB0
crw-rw----    1    root    plugdev    188,    1    Jul    10    19:04    /dev/ttyUSB1

    较小编号的 /dev/ttyUSBn 接口用于 JTAG 通信。其他接口路由到 ESP32 的串行端口 (UART)，用于将代码上传到 ESP32 的闪存。

  5. 在终端窗口中，导航到 FreeRTOS 下载目录的根目录，然后使用以下命令运行 OpenOCD：

    idf.py openocd

  6. 打开另一个终端，导航到您的 FreeRTOS 下载目录的根目录，然后运行以下命令。

    idf.py flash monitor

  7. 打开另一个终端，导航到您的 FreeRTOS 下载目录的根目录，然后运行以下命令：

    idf.py gdb

    程序应在 main() 中停止。