本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
开始使用 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
注意
目前,ESP32-WROVER-KIT 和 ESP DevKit C 的 FreeRTOS 端口不支持对称多处理 (SMP) 功能。
概览
该教程将指导您完成以下步骤:
-
将主板连接到主机。
-
在主机上安装软件来开发和调试微控制器主板的嵌入式应用程序。
-
将 FreeRTOS 演示应用程序交叉编译为二进制图像。
-
将应用程序二进制映像加载到您的主板上,然后运行该应用程序。
-
跨串行连接与主板上运行的应用程序进行交互,以便进行监视和调试。
先决条件
在你开始在乐鑫开发板上使用 FreeRTOS 之前,你必须设置AWS账户和权限。
注册一个 AWS 账户
如果您还没有 AWS 账户,请完成以下步骤来创建一个。
注册 AWS 账户
按照屏幕上的说明进行操作。
在注册时,您将接到一通电话,要求您使用电话键盘输入一个验证码。
当您注册 AWS 账户 时,系统将会创建一个 AWS 账户根用户。根用户有权访问该账户中的所有 AWS 服务和资源。作为安全最佳实践,请 为管理用户分配管理访问权限,并且只使用根用户执行 需要根用户访问权限的任务。
AWS注册过程完成后,会向您发送一封确认电子邮件。在任何时候,您都可以通过转至 https://aws.amazon.com/
创建管理用户
注册 AWS 账户 后,创建一个管理用户,以避免使用根用户执行日常任务。
保护您的 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 指南的 “入门” 部分时,停下来,然后返回本页上的说明。
-
-
设置您的开发环境。
要与您的开发板通信,您必须安装工具链。乐鑫提供 ESP-IDF 来为他们的开发板开发软件。由于 ESP-IDF 有自己的集成版本的 FreeRTOS 内核作为组件,Amazon FreeRTOS 包含删除了 FreeRTOS 内核的 ESP-IDF v4.2 的自定义版本。这修复了编译时出现的重复文件问题。要使用Amazon FreeRTOS 附带的 ESP-IDF v4.2 的自定义版本,请按照以下主机操作系统的说明进行操作。
Windows
-
下载适用于 Windows 的 ESP-IDF 通用在线安装程序
。 -
运行通用在线安装程序。
-
当你进入下载或使用 ESP-IDF 步骤时,选择使用现有 ESP-IDF 目录并将选择现有 ESP-IDF 目录设置为
。freertos
/vendors/espressif/esp-idf -
完成安装。
macOS
-
按照 macOS 工具链先决条件标准设置(ESP-IDF v4.2)中的说明进行
操作。 重要
当你看到 “后续步骤” 下的 “获取 ESP-IDF” 说明时,停下来,然后返回此页面上的说明。
-
打开一个命令行窗口。
-
导航到 FreeRTOS 下载目录,然后运行以下脚本下载并安装适用于您的平台的 espressif 工具链。
vendors/espressif/esp-idf/install.sh
-
使用以下命令将 ESP-IDF 工具链工具添加到您的终端路径中。
source vendors/espressif/esp-idf/export.sh
Linux
-
按照 Linux 工具链先决条件标准设置(ESP-IDF v4.2)中的说明进行
操作。 重要
当你看到 “后续步骤” 下的 “获取 ESP-IDF” 说明时,停下来,然后返回此页面上的说明。
-
打开一个命令行窗口。
-
导航到 FreeRTOS 下载目录,然后运行以下脚本下载并安装适用于您的平台的 Espressif 工具链。
vendors/espressif/esp-idf/install.sh
-
使用以下命令将 ESP-IDF 工具链工具添加到您的终端路径中。
source vendors/espressif/esp-idf/export.sh
-
-
建立串行连接。
-
要在主机和 ESP32-DevKit C 之间建立串行连接,必须安装 CP210x USB 转 UART Bridge VCP 驱动程序。您可以从 Silicon Labs
下载这些驱动程序。 要在主机和 ESP32-WROVER-KIT 之间建立串行连接,必须安装 FTDI 虚拟 COM 端口驱动程序。你可以从 FTDI
下载这个驱动程序。 -
按照步骤与 ESP32 建立串行连接
。 -
建立串行连接后,记下主板连接的串行端口。你需要它来刷新演示。
-
配置 FreeRTOS 演示应用程序
在本教程中,FreeRTOS 配置文件位于
。(例如,如果选择freertos
/vendors/espressif/boards/board-name
/aws_demos/config_files/FreeRTOSConfig.hAFR_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 awscli
AWS命令在 “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.jsonafr_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 安全性)
-
-
-
运行配置脚本。
-
如果你运行的是 macOS 或 Linux,请打开终端提示符。如果你运行的是 Windows,请打开 “ESP-IDF 4.x CMD” 或 “Command” 应用程序。
-
导航到该
目录并运行freertos
/tools/aws_config_quick_startpython 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_startREADME.md
中的。 -
-
在云上监控 MQTT 消息
在运行 FreeRTOS 演示项目之前,可以在AWS IoT控制台中设置 MQTT 客户端以监控您的设备发送到AWS云端的消息。
使用 AWS IoT MQTT 客户端订阅 MQTT 主题
-
导航到 AWS IoT 控制台
。 -
在导航窗格中,选择 T es t,然后选择 MQTT 测试置放。
-
在 Subscription topic (订阅主题)中,输入
,然后选择 Subscribe to topic (订阅主题)。your-thing-name
/example/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 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_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
的文件示例。
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 配置添加另一个目录。freertos
/demos/include/
- 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
-
将文件解压缩到
C:\
并将C:\openocd-esp32\bin
添加到系统路径。 -
OpenOCD 需要 libusb,默认情况下未在 Windows 上安装。安装 libusb 的方法是:
-
下载 zadig.exe
。 -
运行
zadig.exe
。在 Options (选项) 菜单中,选择 List All Devices (列出所有设备)。 -
从下拉菜单中选择 C232HM-DDHSL-0。
-
在绿色箭头右侧的目标驱动程序字段中,选择 WinUSB。
-
在目标驱动程序字段下的列表中,选择箭头,然后选择 “安装驱动程序”。选择 Replace Driver (替换驱动程序)。
-
-
打开命令提示符,导航到 FreeRTOS 下载目录的根目录,然后运行以下命令。
idf.py openocd
保持此命令提示符窗口处于打开状态。
-
打开新的命令提示符,导航到 FreeRTOS 下载目录的根目录,然后运行
idf.py flash monitor
-
打开另一个命令提示符,导航到 FreeRTOS 下载目录的根目录,然后等到演示版开始在主板上运行。当它这样做时,运行
idf.py gdb
程序应在
main
函数中停止。注意
ESP32 支持最多两个断点。
-
- 在 macOS 上调试 (ESP-IDF v4.2)
-
-
下载 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()
中停止。
-