概览先决条件开始使用运行低功耗蓝牙演示在你自己的 ESP32 CMake 项目中使用 FreeRTOS 问题排查调试

开始使用 Espressif ESP32-DevKit C 和 ESP-WROVER-KIT

重要

此参考集成托管在 Amazon-FreeRTOS 存储库中，该存储库已过时。建议您在创建新项目时从这里开始。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目，请参阅亚马逊 freerTOS Github 存储库迁移指南。

注意

要了解如何将 FreeRTOS 模块化库和演示集成到您自己的 Espressif IDF 项目中，请参阅我们的 ESP32-C3 平台精选参考集成。

按照本教程开始使用配备 ESP32-WROOM-32、ESP32-SOLO-1 或 ESP-WROVER 模块的 Espressif ESP32-DevKit C 以及 ESP-WROVER-KIT-VB。要从我们的AWS合作伙伴设备目录中购买一台，请使用以下链接：

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

有关这些主板最新版本的更多信息，请参阅 Espressif 网站上的 ESP32-DevKit C V4 或 ESP-WROVER-KIT v4.1。

注意

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

概览

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

将主板连接到主机。
在主机上安装软件来开发和调试微控制器主板的嵌入式应用程序。
将 FreeRTOS 演示应用程序交叉编译为二进制图像。
将应用程序二进制映像加载到您的主板上，然后运行该应用程序。
跨串行连接与主板上运行的应用程序进行交互，以便进行监视和调试。

先决条件

在你开始在乐鑫开发板上使用 FreeRTOS 之前，你必须设置AWS账户和权限。

如果您还没有 AWS 账户，请完成以下步骤来创建一个。

注册 AWS 账户

打开 https://portal.aws.amazon.com/billing/signup。
按照屏幕上的说明进行操作。

在注册时，您将接到一通电话，要求您使用电话键盘输入一个验证码。

当您注册 AWS 账户时，系统将会创建一个 AWS 账户根用户。根用户有权访问该账户中的所有 AWS 服务和资源。作为安全最佳实践，请为管理用户分配管理访问权限，并且只使用根用户执行需要根用户访问权限的任务。

AWS注册过程完成后，会向您发送一封确认电子邮件。在任何时候，您都可以通过转至 https://aws.amazon.com/ 并选择 My Account (我的账户) 来查看当前的账户活动并管理您的账户。

创建管理用户

保护您的 AWS 账户根用户

选择 Root user（根用户）并输入您的 AWS 账户电子邮件地址，以账户拥有者身份登录 AWS Management Console。在下一页上，输入您的密码。

要获取使用根用户登录方面的帮助，请参阅《AWS 登录用户指南》中的以根用户身份登录。
对您的根用户启用多重身份验证 (MFA)。

有关说明，请参阅《IAM 用户指南》中的为 AWS 账户根用户启用虚拟 MFA 设备（控制台）。

创建管理用户

对于您的日常管理任务，请在 AWS IAM Identity Center 中为管理用户授予管理访问权限。

有关说明，请参阅《AWS IAM Identity Center 用户指南》中的入门。

作为管理用户登录

要使用您的 IAM Identity Center 用户身份登录，请使用您在创建 IAM Identity Center 用户时发送到您的电子邮件地址的登录 URL。

要获取使用 IAM Identity Center 用户登录方面的帮助，请参阅《AWS 登录用户指南》中的登录 AWS 访问门户。

要提供访问权限，请为您的用户、组或角色添加权限：

AWS IAM Identity Center 中的用户和组：

创建权限集合。按照《AWS IAM Identity Center 用户指南》中创建权限集的说明进行操作。
通过身份提供商在 IAM 中托管的用户：

创建适用于身份联合验证的角色。按照《IAM 用户指南》中为第三方身份提供商创建角色（联合身份验证）的说明进行操作。
IAM 用户：
- 创建您的用户可以担任的角色。按照《IAM 用户指南》中为 IAM 用户创建角色的说明进行操作。
- （不推荐使用）将策略直接附加到用户或将用户添加到用户组。按照《IAM 用户指南》中向用户添加权限（控制台）中的说明进行操作。

开始使用

注意

本教程中的 Linux 命令要求你使用 Bash 外壳。

设置乐鑫硬件。
- 有关设置 ESP32-DevKit C 开发板硬件的信息，请参阅 ESP32-DevKit C V4 入门指南。
- 有关设置 ESP-WROVER-KIT 开发板硬件的信息，请参阅 ESP-WROVER-KIT V4.1 入门指南。
重要
当您到达 Espressif 指南的 “入门” 部分时，停下来，然后返回本页上的说明。
从以下地址下载Amazon FreeRTOS GitHub。（有关说明，请参阅 README.md 文件。）
设置您的开发环境。

要与您的开发板通信，您必须安装工具链。乐鑫提供 ESP-IDF 来为他们的开发板开发软件。由于 ESP-IDF 有自己的集成版本的 FreeRTOS 内核作为组件，Amazon FreeRTOS 包含删除了 FreeRTOS 内核的 ESP-IDF v4.2 的自定义版本。这修复了编译时出现的重复文件问题。要使用Amazon FreeRTOS 附带的 ESP-IDF v4.2 的自定义版本，请按照以下主机操作系统的说明进行操作。

Windows
1. 下载适用于 Windows 的 ESP-IDF 通用在线安装程序。
2. 运行通用在线安装程序。
3. 当你进入下载或使用 ESP-IDF 步骤时，选择使用现有 ESP-IDF 目录并将选择现有 ESP-IDF 目录设置为freertos/vendors/espressif/esp-idf。
4. 完成安装。
macOS
1. 按照 macOS 工具链先决条件标准设置（ESP-IDF v4.2）中的说明进行操作。
  
  重要
  当你看到 “后续步骤” 下的 “获取 ESP-IDF” 说明时，停下来，然后返回此页面上的说明。
2. 打开一个命令行窗口。
3. 导航到 FreeRTOS 下载目录，然后运行以下脚本下载并安装适用于您的平台的 espressif 工具链。
```
vendors/espressif/esp-idf/install.sh
```
4. 使用以下命令将 ESP-IDF 工具链工具添加到您的终端路径中。
```
source vendors/espressif/esp-idf/export.sh
```
Linux
1. 按照 Linux 工具链先决条件标准设置（ESP-IDF v4.2）中的说明进行操作。
  
  重要
  当你看到 “后续步骤” 下的 “获取 ESP-IDF” 说明时，停下来，然后返回此页面上的说明。
2. 打开一个命令行窗口。
3. 导航到 FreeRTOS 下载目录，然后运行以下脚本下载并安装适用于您的平台的 Espressif 工具链。
```
vendors/espressif/esp-idf/install.sh
```
4. 使用以下命令将 ESP-IDF 工具链工具添加到您的终端路径中。
```
source vendors/espressif/esp-idf/export.sh
```
建立串行连接。
1. 要在主机和 ESP32-DevKit C 之间建立串行连接，必须安装 CP210x USB 转 UART Bridge VCP 驱动程序。您可以从 Silicon Labs 下载这些驱动程序。
  
  要在主机和 ESP32-WROVER-KIT 之间建立串行连接，必须安装 FTDI 虚拟 COM 端口驱动程序。你可以从 FTDI 下载这个驱动程序。
2. 按照步骤与 ESP32 建立串行连接。
3. 建立串行连接后，记下主板连接的串行端口。你需要它来刷新演示。

配置 FreeRTOS 演示应用程序

在本教程中，FreeRTOS 配置文件位于freertos/vendors/espressif/boards/board-name/aws_demos/config_files/FreeRTOSConfig.h。（例如，如果选择AFR_BOARD espressif.esp32_devkitc了，则配置文件位于freertos/vendors/espressif/boards/esp32/aws_demos/config_files/FreeRTOSConfig.h。）

如果你运行的是 macOS 或 Linux，请打开终端提示符。如果你运行的是 Windows，请打开 “ESP-IDF 4.x CMD” 应用程序（如果你在安装 ESP-IDF 工具链时包含了这个选项），否则打开 “命令提示符” 应用程序。
要验证你是否安装了 Python3，请运行
```
python --version
```
此时显示已安装的版本。如果你没有安装 Python 3.0.1 或更高版本，你可以从 Python 网站进行安装。
您需要AWS命令行界面 (CLI) 才能运行AWS IoT命令。如果你运行的是 Windows，请使用easy_install awscliAWS命令在 “Command” 或 “ESP-IDF 4.x CMD” 应用程序中安装 CLI。

如果你运行的是 macOS 或 Linux，请参阅安装AWS CLI。
Run（运行）
```
aws configure
```
然后使用您的AWS访问密钥 ID、私有访问密钥和默认AWS区域。AWS有关更多信息，请参阅配置AWS CLI。
使用以下命令安装 PytythonAWS 开发置放 Python (boto3)：
- 在 Windows 上，在 “命令” 或 “ESP-IDF 4.x CMD” 应用程序中运行
```
pip install boto3 --user
```
  注意
  有关详细信息，请参见 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，请打开 “ESP-IDF 4.x CMD” 或 “Command” 应用程序。
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，请参阅freertos/tools/aws_config_quick_start目录README.md中的。

在云上监控 MQTT 消息

在运行 FreeRTOS 演示项目之前，可以在AWS IoT控制台中设置 MQTT 客户端以监控您的设备发送到AWS云端的消息。

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

导航到 AWS IoT 控制台。
在导航窗格中，选择 T es t，然后选择 MQTT 测试置放。
在 Subscription topic (订阅主题)中，输入 your-thing-name/example/topic，然后选择 Subscribe to topic (订阅主题)。

当演示项目在您的设备上成功运行时，您会看到 “Hello World！” 多次向您订阅的主题发送。

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

你可以使用 Espressif 的 IDF 实用程序 (idf.py) 来构建项目并将二进制文件烧录到你的设备上。

注意

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


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

在 Windows、Linux 和 macOS 上构建和刷新 FreeRTOS (ESP-IDF v4.2)

导航到 FreeRTOS 下载目录的根目录。
在命令行窗口中，输入以下命令将 ESP-IDF 工具添加到终端的 PATH 中。
Windows（“命令” 应用程序）
```
vendors\espressif\esp-idf\export.bat
```
Windows（“ESP-IDF 4.x CMD” 应用程序）

（当你打开应用程序时，这已经完成了。）

Linux/macOS
```
source vendors/espressif/esp-idf/export.sh
```

在build目录中配置 cmake 并使用以下命令构建固件映像。


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 文件。

使用以下命令，清除开发板的闪存。
```
idf.py erase_flash
```
使用该idf.py脚本将应用程序二进制文件刷新到您的开发板上。
```
idf.py flash
```
使用以下命令，监控主板串行端口的输出。
```
idf.py monitor
```
注意
您可以组合这些库，如以下示例所示。
```
idf.py erase_flash flash monitor
```
对于某些主机设置，在刷新主板时必须指定端口，如以下示例所示。
```
idf.py erase_flash flash monitor -p /dev/ttyUSB1
```

使用 cMake 构建和刷新 FreeRTOS

除了 IDF SDK 提供的用于生成和运行代码的idf.py脚本外，您还可以使用 CMake 构建项目。目前，它支持 Unix Makefile 或 Ninja 编译系统。

生成和刷新项目

在命令行窗口中，导航到 FreeRTOS 下载目录的根目录。
运行以下脚本将 ESP-IDF 工具添加到外壳的 PATH 中。
Windows
```
vendors\espressif\esp-idf\export.bat
```
Linux/macOS
```
source vendors/espressif/esp-idf/export.sh
```

要生成这些库，请输入以下命令以生成这些库。

使用 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

构建项目。

使用 Unix 生成文件


make -C ./YOUR_BUILD_DIRECTORY -j8

和忍者在一起


ninja -C ./YOUR_BUILD_DIRECTORY -j8

擦除闪光灯，然后刷新电路板。

使用 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

运行低功耗蓝牙演示

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

要通过低功耗蓝牙运行 FreeRTOS 演示项目，您必须在 iOS 或 Android 移动设备上运行 FreeRTOS 低功耗蓝牙移动 SDK 演示应用程序。

设置 FreeRTOS 低功耗蓝牙移动 SDK 演示应用程序

按照适用于 FreeRTOS 蓝牙设备的移动软件开发工具包中的说明，在您的主机上下载并安装适用于移动平台的开发工具包。
按照 FreeRTOS 低功耗蓝牙移动 SDK 演示应用程序中的说明，在您的移动设备上设置演示移动应用程序。

有关如何在您的主板上通过低功耗蓝牙运行 MQTT 演示的说明，请参阅低功耗蓝牙 MQTT。

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

在你自己的 ESP32 CMake 项目中使用 FreeRTOS

如果您想在自己的 CMake 项目中使用 FreeRTOS，可以将其设置为子目录并将其与应用程序一起构建。首先，从中获取 FreeRTOS 的副本GitHub。你也可以使用以下命令将其设置为 Git 子模块，这样future 更容易更新。


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

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


cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

# Tell IDF build to link against this target.
set(IDF_EXECUTABLE_SRCS "<complete_path>/src/main.c")
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::core_mqtt)

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


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


cmake --build build-directory

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


cmake --build build-directory --target flash

使用 FreeRTOS 中的组件

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


====================Configuration for FreeRTOS====================
  Version:                 202107.00
  Git version:             202107.00-g79ad6defb

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:        backoff_algorithm, common, common_io, core_http,
                           core_http_demo_dependencies, core_json, core_mqtt,
                           core_mqtt_agent, core_mqtt_agent_demo_dependencies,
                           core_mqtt_demo_dependencies, crypto, defender, dev_mode_key_
                           provisioning, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass,
                           http_demo_helpers, https, jobs, jobs_demo_dependencies,
                           kernel, logging, mqtt, mqtt_agent_interface, mqtt_demo_
                           helpers, mqtt_subscription_manager, ota, ota_demo_
                           dependencies, ota_demo_version, pkcs11, pkcs11_helpers,
                           pkcs11_implementation, pkcs11_utils, platform, secure_sockets,
                           serializer, shadow, tls, transport_interface_secure_sockets,
                           wifi
  Enabled by user:         common_io, core_http_demo_dependencies, core_json,
                           core_mqtt_agent_demo_dependencies, core_mqtt_demo_
                           dependencies, defender, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass, https,
                           jobs, jobs_demo_dependencies, logging, ota_demo_dependencies,
                           pkcs11, pkcs11_helpers, pkcs11_implementation, pkcs11_utils,
                           platform, secure_sockets, shadow, wifi
  Enabled by dependency:   backoff_algorithm, common, core_http, core_mqtt,
                           core_mqtt_agent, crypto, demo_base, dev_mode_key_provisioning,
                           freertos, http_demo_helpers, kernel, mqtt, mqtt_agent_
                           interface, mqtt_demo_helpers, mqtt_subscription_manager, ota,
                           ota_demo_version, pkcs11_mbedtls, serializer, tls,
                           transport_interface_secure_sockets, utils
  3rdparty dependencies:   jsmn, mbedtls, pkcs11, tinycbor
  Available demos:         demo_cli_uart, demo_core_http, demo_core_mqtt, demo_core_mqtt_
                           agent, demo_device_defender, demo_device_shadow,
                           demo_greengrass_connectivity, demo_jobs, demo_ota_core_http,
                           demo_ota_core_mqtt, demo_tcp
  Available tests:
=========================================================================

您可以引用Modules to build列表中的任何组件。要将它们链接到您的应用程序，请将AFR::命名空间放在名称的前面，例如AFR::core_mqttAFR::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的文件示例。



add_library(example_component src/example_component.c)
target_include_directories(example_component PUBLIC include)

然后，在顶级CMakeLists.txt文件中，通过在后面插入以下行来添加组件add_subdirectory(freertos)。


add_subdirectory(component/example_component)

然后，修改target_link_libraries以包含您的组件。


target_link_libraries(my_app PRIVATE AFR::core_mqtt PRIVATE example_component)

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

覆盖 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。

有关更多信息，请参阅 Espressif API 参考中的项目配置，如果您在成功编译后遇到问题，请参阅该页面上关于已弃用选项及其替代品的部分。

摘要

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


cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

set(IDF_PROJECT_EXECUTABLE my_app)
set(IDF_EXECUTABLE_SRCS "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::core_mqtt)

问题排查

如果你正在运行 macOS 并且操作系统无法识别你的 ESP-WROVER-KIT，请确保你没有安装 D2XX 驱动程序。要卸载它们，请按照适用于 macOS X 的 FTDI 驱动程序安装指南中的说明操作。
ESP-IDF 提供的监控实用程序（使用 make monitor 调用）可帮助您解码地址。因此，它可以帮助您在应用程序停止运行时获得一些有意义的回溯信息。有关更多信息，请参阅 Espressif 网站上的自动地址解码。
也可以在不需要任何特殊的 JTAG 硬件的情况下启用 gdbStub 与 gdb 通信。有关更多信息，请参阅乐鑫网站上的 GdbStub 启动 GDB。
有关在需要基于 JTAG 硬件的调试时设置基于 OpenOCD 的环境的信息，请参阅 Espressif 网站上的 JTAG 调试。
如果pyserial无法pip在 macOS 上安装，请从 pyserial 网站下载。
如果主板持续重置，请尝试在终端上输入以下命令来擦除闪光灯。
```
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

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

调试

在 Espressif ESP32-DevKit C 和 ESP-WROVER-KIT（ESP-IDF v4.2）上调试代码

本节介绍如何使用 ESP-IDF v4.2 调试 Espressif 硬件。您需要 JTAG 到 USB 电缆。我们使用 USB 转 MPSSE 的电缆（例如 FTDI C232HM-DDHSL-0）。

ESP-DevKit C JTAG 设置

对于 FTDI C232HM-DDHSL-0 电缆，这些是与 ESP32 DevKitc 的连接。


| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Black (pin 10)           |  GND           |  GND             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             |

ESP-WROVER-KIT JTAG 设置

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


| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             |

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

要在 ESP-WROVER-KIT 上启用 JTAG，请在 TMS、TDO、TDI、TCK 和 S_TDI 引脚上放置跳线，如下所示。

在 Windows 上调试 (ESP-IDF v4.2)

在 Windows 上设置调试

将 FTDI C232HM-DDHSL-0 的 USB 一端连接到您的计算机，另一端的操作如在 Espressif ESP32-DevKit C 和 ESP-WROVER-KIT（ESP-IDF v4.2）上调试代码中所述。FTDI C232HM-DDHSL-0 设备应显示在设备管理器下的通用串行总线控制器中。
在通用串行总线设备列表下，右键单击 C232HM-DDHSL-0 设备，然后选择 “属性”。

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

要查看设备的属性，请在属性窗口中选择详细信息选项卡。如果未列出该设备，请安装适用于 FTDI C232HM-DDHSL-0 的 Windows 驱动程序。
在 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
```
下载 OpenOCD for Windows。
将文件解压缩到 C:\ 并将 C:\openocd-esp32\bin 添加到系统路径。
OpenOCD 需要 libusb，默认情况下未在 Windows 上安装。安装 libusb 的方法是：
1. 下载 zadig.exe。
2. 运行 zadig.exe。在 Options (选项) 菜单中，选择 List All Devices (列出所有设备)。
3. 从下拉菜单中选择 C232HM-DDHSL-0。
4. 在绿色箭头右侧的目标驱动程序字段中，选择 WinUSB。
5. 在目标驱动程序字段下的列表中，选择箭头，然后选择 “安装驱动程序”。选择 Replace Driver (替换驱动程序)。
打开命令提示符，导航到 FreeRTOS 下载目录的根目录，然后运行以下命令。
```
idf.py openocd
```
保持此命令提示符窗口处于打开状态。
打开新的命令提示符，导航到 FreeRTOS 下载目录的根目录，然后运行
```
idf.py flash monitor
```
打开另一个命令提示符，导航到 FreeRTOS 下载目录的根目录，然后等到演示版开始在主板上运行。当它这样做时，运行
```
idf.py gdb
```
程序应在 main 函数中停止。

注意
ESP32 支持最多两个断点。

在 macOS 上调试 (ESP-IDF v4.2)

下载适用于 macOS 的 FTDI 驱动程序。
下载 OpenOCD。
提取下载的 .tar 文件，并将 .bash_profile 中的路径设置为 OCD_INSTALL_DIR/openocd-esp32/bin。
使用以下命令libusb在 macOS 上安装。
```
brew install libusb
```

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


sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

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


sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

如果你运行的 macOS 版本低于 10.9，请使用以下命令卸载 Apple FTDI 驱动程序。
```
sudo kextunload -b com.apple.driver.AppleUSBFTDI
```
使用以下命令获取 FTDI 电缆的产品 ID 和供应商 ID。它列出了连接的 USB 设备。
```
system_profiler SPUSBDataType
```
的输出system_profiler应类似于以下内容。
```
   DEVICE:

   Product ID: product-ID
   Vendor ID: vendor-ID (Future Technology Devices International Limited) 
```
打开 projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg 文件。设备的供应商 ID 和产品 ID 在以 ftdi_vid_pid 开头的行中指定。更改 ID 以匹配上一步骤 system_profiler 输出中的 ID。
打开终端窗口，导航到 FreeRTOS 下载目录的根目录，然后使用以下命令运行 OpenOCD。
```
idf.py openocd
```
将此终端窗口保持打开状态。
打开一个新终端，然后使用以下命令加载 FTDI 串行端口驱动程序。
```
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
```
导航到 FreeRTOS 下载目录的根目录，然后运行
```
idf.py flash monitor
```
打开另一个新终端，导航到 FreeRTOS 下载目录的根目录，然后运行
```
idf.py gdb
```
程序应在 main 停止。

在 Linux 上进行调试 (ESP-IDF v4.2)

下载 OpenOCD。提取 tarball 并按照自述文件中的安装说明操作。
使用以下命令在 Linux 上安装 libusb。
```
sudo apt-get install libusb-1.0
```

打开终端并输入 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

注销，然后登录并重新对主板加电，使更改生效。在终端提示符下，列出 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 的闪存。
在终端窗口中，导航到 FreeRTOS 下载目录的根目录，然后使用以下命令运行 OpenOCD。
```
idf.py openocd 
```
打开另一个终端，导航到 FreeRTOS 下载目录的根目录，然后运行以下命令。
```
idf.py flash monitor 
```
打开另一个终端，导航 FreeRTOS 下载目录的根目录，然后运行以下命令：
```
idf.py gdb
```
程序应在 main() 中停止。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

Microchip ATECC608A 安全元件以及 Windows 模拟器

乐新 ESP32-WROOM-32SE 入门

开始使用 Espressif ESP32-DevKit C 和 ESP-WROVER-KIT

重要

注意

注意

概览

先决条件

注册一个 AWS 账户

注册 AWS 账户

创建管理用户

保护您的 AWS 账户根用户

创建管理用户

作为管理用户登录

开始使用

注意

重要

重要

重要

配置 FreeRTOS 演示应用程序

注意

注意

在云上监控 MQTT 消息

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

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

注意

在 Windows、Linux 和 macOS 上构建和刷新 FreeRTOS (ESP-IDF v4.2)

注意

使用 cMake 构建和刷新 FreeRTOS

生成和刷新项目

运行低功耗蓝牙演示

设置 FreeRTOS 低功耗蓝牙移动 SDK 演示应用程序

在你自己的 ESP32 CMake 项目中使用 FreeRTOS

使用 FreeRTOS 中的组件

使用 ESP-IDF 添加自定义组件

覆盖 FreeRTOS 的配置

为 ESP-IDF 提供您自己的 sdkconfig

摘要

问题排查

调试

在 Espressif ESP32-DevKit C 和 ESP-WROVER-KIT（ESP-IDF v4.2）上调试代码

在 Windows 上设置调试

注意

注意