开始使用 Espressif ESP32-C 和 DevKit ESP-WROVER-KIT - 免费 RTOS
概述先决条件开始使用运行低功耗蓝牙演示RTOS在你自己的CMake项目中使用 Free ESP32问题排查调试

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

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

重要

此参考集成托管在 Amazon-Free RTOS 存储库中，该存储库已弃用。当您创建新项目时，我们建议从此处开始。如果您已经有一个基于现已弃用的 Amazon-Free RTOS 存储库的免费RTOS项目，请参阅。亚马逊免费版 RTOS Github 存储库迁移指南

注意

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

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

免费版支持这些版本的开发板RTOS。

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

注意

目前，ESP32WROVER-KIT 和 ESP DevKit C 的空闲RTOS端口不支持 Symmetric 多处理 (SMP) 功能。

概述

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

  1. 将主板连接到主机。

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

  3. 将免费RTOS演示应用程序交叉编译成二进制映像。

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

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

先决条件

在开始使用乐鑫看板RTOS上的免费版之前，您必须设置 AWS 账户和权限。

注册获取 AWS 账户

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

要注册 AWS 账户

  1. 打开https://portal.aws.amazon.com/billing/注册。

  2. 按照屏幕上的说明进行操作。

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

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

AWS 注册过程完成后会向您发送一封确认电子邮件。您可以随时前往 https://aws.amazon.com/并选择 “我的账户”，查看您当前的账户活动并管理您的账户。

创建具有管理访问权限的用户

注册后，请保护您的安全 AWS 账户 AWS 账户根用户 AWS IAM Identity Center，启用并创建管理用户，这样您就不会使用 root 用户执行日常任务。

保护你的 AWS 账户根用户

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

    要获取使用根用户登录方面的帮助，请参阅《AWS 登录 用户指南》中的以根用户身份登录。

  2. 为您的 root 用户开启多重身份验证 (MFA)。

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

创建具有管理访问权限的用户

  1. 启用IAM身份中心。

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

  2. 在 IAM Identity Center 中，向用户授予管理访问权限。

    有关使用 IAM Identity Center 目录 作为身份源的教程，请参阅《用户指南》 IAM Identity Center 目录中的使用默认设置配置AWS IAM Identity Center 用户访问权限。

以具有管理访问权限的用户身份登录
将访问权限分配给其他用户

  1. 在 IAM Identity Center 中，创建一个遵循应用最低权限权限的最佳实践的权限集。

    有关说明，请参阅《AWS IAM Identity Center 用户指南》中的创建权限集。

  2. 将用户分配到一个组，然后为该组分配单点登录访问权限。

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

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

  • 中的用户和群组 AWS IAM Identity Center：

    创建权限集合。按照《AWS IAM Identity Center 用户指南》中创建权限集的说明进行操作。

  • IAM通过身份提供商管理的用户：

    创建适用于身份联合验证的角色。按照《IAM用户指南》中为第三方身份提供商创建角色（联合）中的说明进行操作。

  • IAM用户：

    • 创建您的用户可以担任的角色。按照《用户指南》中为IAM用户创建角色中的IAM说明进行操作。

    • （不推荐使用）将策略直接附加到用户或将用户添加到用户组。按照《用户指南》中向用户（控制台）添加权限中的IAM说明进行操作。

开始使用

注意

本教程中的 Linux 命令要求您使用 Bash Shell。

  1. 设置 Espressif 硬件。

    重要

    当您阅读到 Espressif 手册的入门 部分时，请暂停并返回到此页面上的说明部分。

  2. RTOS从这里免费下载 Amazon GitHub。（有关说明，请参阅 README.md 文件。）

  3. 设置开发环境。

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

    Windows

    1. 下载 ESP-适用于 Windows IDF 的通用在线安装程序。

    2. 运行通用在线安装程序。

    3. 当你进入 “下载或使用 ESP-” 步骤时IDF，选择 “使用现有 ESP-IDF 目录”，然后将 “选择现有 ESP-IDF 目录” 设置为freertos/vendors/espressif/esp-idf。

    4. 完成安装。

    macOS

    1. 按照 macOS 标准设置工具链先决条件 (ESP-IDF v4.2) 中的说明进行操作。

      重要

      当您到达 “后续步骤” 下的 “获IDF取 ESP-” 说明时，请停下来，然后返回本页上的说明。

    2. 打开一个命令行窗口。

    3. 导航到免费RTOS下载目录，然后运行以下脚本下载并安装适用于您平台的 espressif 工具链。

      vendors/espressif/esp-idf/install.sh

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

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

    Linux

    1. 按照适用于 Linux 的标准设置工具链先决条件 (ESP-IDF v4.2) 中的说明进行操作。

      重要

      当您到达 “后续步骤” 下的 “获IDF取 ESP-” 说明时，请停下来，然后返回本页上的说明。

    2. 打开一个命令行窗口。

    3. 导航到免费RTOS下载目录，然后运行以下脚本下载并安装适用于您的平台的 Espressif 工具链。

      vendors/espressif/esp-idf/install.sh

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

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

  4. 建立串行连接。

    1. 要在主机和 ESP32-DevKit C 之间建立串行连接，必须安装 CP21 0x USB 到 UART Bridge VCP 驱动程序。您可以从 Silicon Labs 下载这些驱动程序。

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

    2. 按照步骤与建立串行连接ESP32。

    3. 建立串行连接后，记下主板连接的串行端口。您需要它来刷写演示。

配置免费RTOS演示应用程序

在本教程中，免费RTOS配置文件位于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。）

  1. 如果您运行的是 macOS 或 Linux，请打开终端提示符。如果你运行的是 Windows，请打开 “ESP-IDF 4.xCMD” 应用程序（如果在安装 ESP-IDF 工具链时包含此选项），否则打开 “命令提示符” 应用程序。

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

    python --version

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

  3. 你需要 AWS 命令行界面 (CLI) 才能运行 AWS IoT 命令。如果你运行的是 Windows，请使用easy_install awscli命令 AWS CLI在 “命令” 或 “ESP-IDF 4.xCMD” 应用程序中安装。

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

  4. 运行

    aws configure

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

  5. 使用以下命令安装 AWS SDK适用于 Python 的 (boto3)：

    • 在 Windows 上，在 “命令” 或 “ESP-IDF 4.xCMD” 应用程序中，运行

      pip install boto3 --user
      注意

      有关详细信息，请参阅 Boto3 文档。

    • 在 macOS 或 Linux 上，运行

      pip install tornado nose --user

      然后运行

      pip install boto3 --user

    免费RTOS版包含SetupAWS.py脚本，可让您更轻松地设置乐鑫主板以进行连接。 AWS IoT要配置此脚本，请打开 freertos/tools/aws_config_quick_start/configure.json 并设置以下属性：

    afr_source_dir

    计算机上的 freertos 目录的完整路径。确保您使用正斜杠来指定此路径。

    thing_name

    您要为代表您的看板 AWS IoT 的事物分配的名称。

    wifi_ssid

    您SSID的 Wi-Fi 网络的。

    wifi_password

    Wi-Fi 网络的密码。

    wifi_security

    Wi-Fi 网络的安全类型。

    下面是有效的安全类型：

    • eWiFiSecurityOpen（开放，不安全）

    • eWiFiSecurityWEP（WEP安全）

    • eWiFiSecurityWPA（WPA安全）

    • eWiFiSecurityWPA2（WPA2安全）

  6. 运行配置脚本。

    1. 如果您运行的是 macOS 或 Linux，请打开终端提示符。如果你运行的是 Windows，请打开 “ESP-IDF 4.xCMD” 或 “命令” 应用程序。

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

      python SetupAWS.py setup

      脚本执行以下操作：

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

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

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

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

      注意

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

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

监控云端MQTT消息

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

向 AWS IoT MQTT客户订阅MQTT主题

  1. 导航到 AWS IoT 控制台。

  2. 在导航窗格中，选择测试，然后选择MQTT测试客户端。

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

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

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

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

注意

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

idf.py -p /dev/cu.usbserial-00101301B flash
RTOS在 Windows、Linux 和 macOS 上免费构建和刷新 (ESP-IDF v4.2)

  1. 导航到免费RTOS下载目录的根目录。

  2. 在命令行窗口中，输入以下命令将 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

  3. 在 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 文件。

  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

使用 Build 和 Flas RTOS h 免费 CMake

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

构建和刷写项目

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

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

    Windows
    vendors\espressif\esp-idf\export.bat
    Linux / macOS
    source vendors/espressif/esp-idf/export.sh

  3. 使用以下命令来生成构建文件。

    对于 Unix Makefiles
    cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0
    对于 Ninja
    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 Makefiles
    make -C ./YOUR_BUILD_DIRECTORY -j8
    对于 Ninja
    ninja -C ./YOUR_BUILD_DIRECTORY -j8

  5. 擦除闪存，然后刷写主板。

    对于 Unix Makefiles
    make -C ./YOUR_BUILD_DIRECTORY erase_flash
    make -C ./YOUR_BUILD_DIRECTORY flash
    对于 Ninja
    ninja -C ./YOUR_BUILD_DIRECTORY erase_flash
    ninja -C ./YOUR_BUILD_DIRECTORY flash

运行低功耗蓝牙演示

免费RTOS支持低功耗蓝牙库连接。

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

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

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

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

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

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

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

如果您想RTOS在自己的CMake项目中使用 Free，可以将其设置为子目录，然后将其与您的应用程序一起构建。首先，获取 Fre RTOS e from 的副本GitHub。您也可以使用以下命令将它设置为 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文件可用于与 Free 一起构建应用程序RTOS。

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

使用免费版中的组件 RTOS

运行后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)

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

免费改写配置 RTOS

目前没有明确的方法可以重新定义自由RTOS源代码树之外的配置。默认情况下，CMake将查找freertos/vendors/espressif/boards/esp32/aws_demos/config_files/和freertos/demos/include/目录。但是，可以使用解决方法来告知编译器首先搜索其他目录。例如，您可以为免费RTOS配置添加另一个文件夹。

- 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)

为-提供你自己的 sdkconfig ESP IDF

如果你想提供自己的变量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文件指定位置，Free 将RTOS使用位于的默认文件freertos/vendors/espressif/boards/esp32/aws_demos/sdkconfig.defaults。

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

Summary

如果您的项目具有一个名为 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硬件的调试时设置OCD基于开放的环境的信息，请参阅 Espressif 网站上的JTAG调试。

  • 如果无法使用 pip 在 macOS 上安装 pyserial，请从 pyserial 网站下载。

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

    make erase_flash

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

  • ESP-IDF 中必需的库包含在免费版中RTOS，因此无需从外部下载它们。如果设置了IDF_PATH环境变量，我们建议您在构建 Free 之前将其清除RTOS。

  • 在 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。

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

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

  • 如果你看到类似于以下内容的错误日志，那就是 IDF v4.2 中不满足的 python 依赖关系：ESP

    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 (-v4.2) ESP IDF

本节介绍如何使用 ESP-v4.2 调试乐鑫硬件。IDF你JTAG需要连接USB电缆。我们使用USB到MPSSE电缆（例如，FTDIC232HM-DDHSL -0）。

ESP-DevKit C JTAG 设置

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

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

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

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

跳线置放
在 Windows 上调试 (ESP-IDF v4.2)
在 Windows 上设置调试

  1. 如中所述，将 FTDI C232HM DDHSL -0 的一USB侧连接到计算机，另一侧连接。在 Espressif 上调试代码 ESP32-DevKit C 和 ESP-WROVER-KIT (-v4.2) ESP IDFFTDIC232HM DDHSL -0 设备应出现在设备管理器中的通用串行总线控制器下。

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

    注意

    该设备可能列为USB串行端口。

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

  3. 在 “详细信息” 选项卡上，选择 “属性”，然后选择 “硬件” IDs。您将在值字段中看到与以下类似的内容。

    FTDIBUS\COMPORT&VID_0403&PID_6014

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

    验证它们是否IDs与输入相IDs匹配projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg。在以IDs开头的行中指定，ftdi_vid_pid后面是供应商 ID 和产品 ID。

    ftdi_vid_pid 0x0403 0x6014

  4. 下载 O pen OCD for Windows。

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

  6. Open OCD 需要 libusb，Windows 上默认不安装该库。安装 libusb

    1. 下载 zadig.exe。

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

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

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

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

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

    idf.py openocd

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

  8. 打开新的命令提示符，导航到免费RTOS下载目录的根目录，然后运行

    idf.py flash monitor

  9. 打开另一个命令提示符，导航到免费RTOS下载目录的根目录，然后等到演示版开始在你的主板上运行。开始演示时，请运行

    idf.py gdb

    程序应在 main 函数中停止。

    注意

    最多ESP32支持两个断点。

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

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

  2. 下载打开OCD。

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

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

    brew install libusb

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

    sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

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

    sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

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

    sudo kextunload -b com.apple.driver.AppleUSBFTDI

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

    system_profiler SPUSBDataType

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

       DEVICE:

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

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

  10. 打开终端窗口，导航到免费RTOS下载目录的根目录，然后使用以下命令运行 Open OCD。

    idf.py openocd

    让该终端窗口保持打开状态。

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

    sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver

  12. 导航到免费RTOS下载目录的根目录，然后运行 

    idf.py flash monitor

  13. 打开另一个新终端，导航到免费RTOS下载目录的根目录，然后运行

    idf.py gdb

    程序应在 main 停止。

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

  1. 下载打开OCD。提取 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. 在终端窗口中，导航到免费RTOS下载目录的根目录，然后使用以下命令运行 Open OCD。

    idf.py openocd

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

    idf.py flash monitor

  7. 打开另一个终端，浏览免费RTOS下载目录的根目录，然后运行以下命令：

    idf.py gdb

    程序应在 main() 中停止。