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

# 开始使用 Espressif 和 ESP32-DevKitC ESP-WROVER-KIT
<a name="getting_started_espressif"></a>

**重要**  <a name="deprecation-message"></a>
此参考集成托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时，我们建议[从此处开始](freertos-getting-started-modular.md)。如果您已经有一个基于现已 Amazon-FreeRTOS 弃用的存储库的 FreeRTOS 项目，请参阅。[Amazon-FreeRTOS Github 存储库迁移](github-repo-migration.md)

**注意**  
[要探索如何将 FreeRTOS 模块化库和演示集成到您自己的 Espressif IDF 项目中，请参阅我们精选的平台参考集成。 ESP32-C3 ](https://www.freertos.org/featured-freertos-iot-integration-targeting-an-espressif-esp32-c3-risc-v-mcu/)

按照本教程开始使用 Espressif ESP32-DevKitC 配备 ESP32-WROOM-32 ESP32-SOLO-1、或 ESP-WROVER 模块以及。 ESP-WROVER-KIT-VB要在合作伙伴设备目录中向我们的 AWS 合作伙伴购买一台，请使用以下链接：
+ [ESP32-WROOM-32 DevKitC](https://devices.amazonaws.com/detail/a3G0L00000AANtjUAH/ESP32-DevKitC)
+ [ESP32-SOLO-1](https://devices.amazonaws.com/detail/a3G0h0000076lSMEAY)
+ [ ESP32-WROVER-KIT](https://devices.amazonaws.com/detail/a3G0L00000AANtlUAH/ESP-WROVER-KIT)

这些版本的开发主板在 FreeRTOS 上均受支持。

有关这些主板最新版本的更多信息，请参阅 Espressif 网站的 [ ESP32-DevKitC ESP-WROVER-KIT V4](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/modules-and-boards.html#esp32-devkitc-v4) [或 v4.1](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/modules-and-boards.html#esp-wrover-kit-v4-1)。

**注意**  
目前，特别是 C 的 FreeRTOS 端口 ESP32-WROVER-KIT 不支持对称多处理 (SM DevKit P) 功能。

## 概述
<a name="getting_started_espressif-overview"></a>

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

1. 将主板连接到主机。

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

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

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

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

## 先决条件
<a name="setup-espressif-prereqs"></a>

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

### 注册获取 AWS 账户
<a name="sign-up-for-aws"></a>

要开始使用 AWS，你需要一个 AWS 账户。有关创建的信息 AWS 账户，请参阅《*AWS 账户管理 参考指南》 AWS 账户中的[入门](https://docs.aws.amazon.com//accounts/latest/reference/getting-started.html)指南*。

要提供访问权限，请为您的用户、组或角色添加权限：
+ 中的用户和群组 AWS IAM Identity Center：

  创建权限集合。按照《AWS IAM Identity Center 用户指南》**中[创建权限集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)的说明进行操作。
+ 通过身份提供者在 IAM 中托管的用户：

  创建适用于身份联合验证的角色。按照《IAM 用户指南》**中[针对第三方身份提供者创建角色（联合身份验证）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)的说明进行操作。
+ IAM 用户：
  + 创建您的用户可以担任的角色。按照《IAM 用户指南》**中[为 IAM 用户创建角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)的说明进行操作。
  + （不推荐使用）将策略直接附加到用户或将用户添加到用户组。按照《IAM 用户指南》**中[向用户添加权限（控制台）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)中的说明进行操作。

## 开始使用
<a name="setup-espressif-idf42"></a>

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

1. **设置 Espressif 硬件。**
   + 有关设置 ESP32-DevKitC 开发板硬件的信息，请参阅《[ ESP32-DevKitC V4 入门指南》](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/esp32/get-started-devkitc.html)。
   + 有关设置 ESP-WROVER-KIT 开发板硬件的信息，请参阅《[ ESP-WROVER-KIT V4.1 入门指南》](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/esp32/get-started-wrover-kit.html)。
**重要**  
当您阅读到 Espressif 手册的**入门** 部分时，请暂停并返回到此页面上的说明部分。

1. 从以下网址下载亚马逊 FreeRTOS。[GitHub](https://github.com/aws/amazon-freertos)（有关说明，请参阅[README.md](https://github.com/aws/amazon-freertos/blob/main/README.md)文件。）

1. **设置开发环境**。

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

   **Windows**

   1. 下载适用于 Windows ESP-IDF 的[通用在线安装程序](https://dl.espressif.com/dl/esp-idf/?idf=4.2)。

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

   1. 进入 “**下载或使用**” 步骤后 ESP-IDF，选择 “**使用现有 ESP-IDF 目录**”，然后将 “**选择现有 ESP-IDF 目录”** 设置为`{{freertos}}/vendors/espressif/esp-idf`。

   1. 完成安装。

   **macOS**

   1. 按照 [macOS 标准设置工具链先决条件 (ESP-IDF v4.2)](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/macos-setup.html) 中的说明进行操作。
**重要**  
当您到达 “**后续步骤 ESP-IDF” 下**的 “获取” 说明时，请停下来，然后返回本页上的说明。

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

   1. 转到 FreeRTOS 下载目录，然后运行以下脚本来下载并安装适用于您平台的 espressif 工具链。

      ```
      vendors/espressif/esp-idf/install.sh
      ```

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

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

   **Linux**

   1. 按照适用于 Linux 的[标准设置工具链先决条件 (ESP-IDF v4.2) 中的说明进行](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/linux-setup.html)操作。
**重要**  
当您到达 “**后续步骤 ESP-IDF” 下**的 “获取” 说明时，请停下来，然后返回本页上的说明。

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

   1. 转到 FreeRTOS 下载目录，然后运行以下脚本来下载并安装适用于您平台的 Espressif 工具链。

      ```
      vendors/espressif/esp-idf/install.sh
      ```

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

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

1. **建立串行连接。**

   1. 要在主机与之间建立串行连接 ESP32-DevKitC，必须安装 CP210x USB 转 UART Bridge VCP 驱动程序。您可以从 [Silicon Labs](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) 下载这些驱动程序。

      要在主机与之间建立串行连接 ESP32-WROVER-KIT，必须安装 FTDI 虚拟 COM 端口驱动程序。您可以从 [FTDI](https://www.ftdichip.com/Drivers/VCP.htm) 下载该驱动程序。

   1. 按照[建立与 ESP32 的串行连接](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/establish-serial-connection.html)中的步骤操作。

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

### 配置 FreeRTOS 演示应用程序
<a name="configure-demos-espressif-idf42"></a>

在本教程中，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`。） 

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

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

   ```
   python --version
   ```

   此时显示已安装的版本。如果您未安装 Python 3.0.1 或更高版本，可以从 [Python](https://www.python.org/downloads/) 网站进行安装。

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

   如果你运行的是 macOS 或 Linux，请参阅[安装 CLI AWS](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)。

1. 运行

   ```
   aws configure
   ```

   并使用您的 AWS 访问密钥 ID、私有访问密钥和默认 AWS 区域配置 AWS CLI。有关更多信息，请参阅[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。

1. 使用以下命令安装适用于 Python 的 AWS 开发工具包 (boto3)：
   + 在 Windows 上，在 “命令” 或 “ESP-IDF 4.x CMD” 应用程序中运行

     ```
     pip install boto3 --user
     ```
**注意**  
有关详细信息，请参阅 [Boto3 文档](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html)。
   + 在 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. 运行配置脚本。

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

   1. 导航到 `{{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` 标头文件
**注意**  
该证书是硬编码的，仅用于演示目的。 Production-level 应用程序应将这些文件存储在安全的位置。

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

### 在云上监控 MQTT 消息
<a name="gsg-espressif-monitor-mqtt"></a>

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

**要通过订阅 MQTT 主题 AWS IoT MQTT 客户端**

1. 导航至 [AWS IoT 控制台](https://console.aws.amazon.com/iotv2/)。

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

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

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

### 使用 idf.py 脚本构建、刷写和运行 FreeRTOS 演示项目
<a name="build-and-run-example-espressif-idf42"></a>

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

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

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

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

1. 转到 FreeRTOS 下载目录的根目录。

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

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

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

   ```
   idf.py erase_flash
   ```

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

   ```
   idf.py flash
   ```

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

   ```
   idf.py monitor
   ```
**注意**  
您可以合并这些命令，如以下示例所示。  

   ```
   idf.py erase_flash flash monitor
   ```

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

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

### 使用 CMake 构建和刷写 FreeRTOS
<a name="flash-espressif-cmake-idf42"></a>

除了 IDF 开发工具包提供的用于构建和运行代码的 `idf.py` 脚本外，您还可以使用 CMake 构建项目。目前，它支持 Unix Makefile 和 Ninja 构建系统。

**构建和刷写项目**

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

1. 运行以下脚本将 ESP-IDF 工具添加到 shell 的 PATH 中。  
**Windows**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Linux / macOS**  

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

1. 使用以下命令来生成构建文件。  
**对于 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
   ```

1. 构建项目。  
**对于 Unix Makefiles**  

   ```
   make -C ./YOUR_BUILD_DIRECTORY -j8 
   ```  
**对于 Ninja**  

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY -j8
   ```

1. 擦除闪存，然后刷写主板。  
**对于 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
   ```

## 运行低功耗蓝牙演示
<a name="espressif-run-ble"></a>

FreeRTOS 支持[低功耗蓝牙库](freertos-ble-library.md)连接。

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

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

1. 按照 [适用于 FreeRTOS 蓝牙设备的移动开发工具包](freertos-ble-mobile.md) 中的说明，在您的主机上下载并安装适用于移动平台的开发工具包。

1. 按照 [FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序](ble-demo.md#ble-sdk-app) 中的说明，在您的移动设备上设置演示移动应用程序。

有关如何在主板上运行低功耗蓝牙 MQTT 演示的说明，请参阅[低功耗蓝牙 MQTT](ble-demo.md#ble-demo-mqtt)。

有关如何在主板上运行 Wi-Fi 配置演示的说明，请参阅[Wi-Fi 资源调配](ble-demo.md#ble-demo-wifi)。

## 在您适用于 ESP32 的 CMake 项目中使用 FreeRTOS
<a name="getting_started_espressif_cmake_project"></a>

如果要在您自己的 CMake 项目中使用 FreeRTOS，可以将它设置为子目录并与应用程序一起构建。首先，从那里获取 FreeRTOS 的副本。[GitHub](https://github.com/aws/amazon-freertos)您也可以使用以下命令将它设置为 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
```

下面是在 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 中的组件
<a name="getting_started_espressif_cmake_project_components"></a>

在运行 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
<a name="getting_started_espressif_cmake_project_espidf"></a>

您可以在使用时添加更多组件 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 的配置
<a name="getting_started_espressif_cmake_project_override"></a>

目前，未提供明确定义的方法来重新定义 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)
```

### 提供你自己的 sdkconfig ESP-IDF
<a name="getting_started_espressif_providing_sdkconfig"></a>

如果要提供您自己的 `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 参考*中的[项目配置](https://docs.espressif.com/projects/esp-idf/en/v4.2-beta1/esp32s2/api-reference/kconfig.html)；如果您在成功编译后遇到问题，请参阅该页面上关于[已弃用选项及其替换](https://docs.espressif.com/projects/esp-idf/en/v4.2-beta1/esp32s2/api-reference/kconfig.html#deprecated-options-and-their-replacements)的部分。

### Summary
<a name="getting_started_espressif_cmake_project_summary"></a>

如果您的项目具有一个名为 `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)
```

## 问题排查
<a name="getting_started_espressif_troubleshooting"></a>
+ 如果你运行的是 macOS，但操作系统无法识别你的 ESP-WROVER-KIT，请确保你没有安装 D2XX 驱动程序。要卸载它们，请按照[适用于 macOS X 的 FTDI 驱动程序安装指南](http://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf)中的说明操作。
+ 由 ESP-IDF （并使用 make monitor 调用）提供的监视器实用程序可帮助您解码地址。因此，在应用程序停止工作时，它可以帮助您获取一些有意义的回溯跟踪信息。有关更多信息，请参阅 Espressif 网站上的[自动解码地址](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/api-guides/tools/idf-monitor.html#automatic-address-decoding)。
+ 还可以启用 GDBstub 来通过 gdb 通信，无需任何特殊 JTAG 硬件。有关更多信息，请参阅 Espressif 网站上的[通过 GDBStub 启动 GDB](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/api-guides/tools/idf-monitor.html#launching-gdb-with-gdbstub)。
+ 有关在需要基于 JTAG 硬件的调试时设置 OpenOCD-based 环境的信息，请参阅 Espressif 网站上的 [JTAG 调试](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html)。
+ 如果无法使用 `pip` 在 macOS 上安装 `pyserial`，请从 [pyserial 网站](https://pypi.org/simple/pyserial)下载。
+ 如果主板连续重置，请尝试通过在终端上输入以下命令来擦除闪存：

  ```
  make erase_flash
  ```
+ 如果您在运行 `idf_monitor.py` 时看到错误，请使用 Python 2.7。
+ FreeRTOS 中包含所需的库，因此无需从 ESP-IDF 外部下载它们。如果已设置 `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](#getting_started_espressif_cmake_project)中的步骤，并且您看到来自链接器的未定义的引用错误，则通常是由于缺少关联的库或演示所致。要添加它们，请使用标准 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
  ```

有关问故障排除的更多信息，请参阅[问题排查入门](gsg-troubleshooting.md)。

## 调试
<a name="getting_started_espressif_debugging"></a>

### 在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT (v4.2) 上调试代码 ESP-IDF
<a name="debugging-espressif-idf42"></a>

本节介绍如何使用 v4.2 调试乐鑫硬件。 ESP-IDF 您需要 JTAG 到 USB 电缆。我们使用 USB 转 MPSSE 电缆（例如 [FTDI C232HM-DDHSL-0](http://www.ftdichip.com/Products/Cables/USBMPSSE.htm)）。

**ESP-DevKitC 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 电缆，这些是与 FTDI 电缆的 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 数据](https://www.ftdichip.com/Support/Documents/DataSheets/Cables/DS_C232HM_MPSSE_CABLE.pdf)表开发的。有关更多信息，请参阅数据表中的“C232HM MPSSE 电缆连接和机械详细信息”。  
要在上启用 JTAG，请将跳线放在 TMS ESP-WROVER-KIT、TDO、TDI、TCK 和 S\_TDI 引脚上，如下所示。  

![跳线置放](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/JP8-jumpers.png)


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

**在 Windows 上设置调试**

1. 如中所述，将 FTDI 的 USB 端 C232HM-DDHSL-0 连接到您的计算机，另一端连接。[在 Espressif ESP32-DevKitC 和 ESP-WROVER-KIT (v4.2) 上调试代码 ESP-IDF](#debugging-espressif-idf42)FTDI C232HM-DDHSL-0 设备应出现在**通用串行总线控制**器下的 “设备管理**器**” 中。

1. 在通用串行总线设备列表下，右键单击该**C232HM-DDHSL-0**设备，然后选择 “**属性**”。
**注意**  
该设备可能被列为 **USB Serial Port (USB 串行端口)**。

   要查看设备的属性，请在属性窗口中选择**详细信息**选项卡。如果未列出该设备，请安装适用[于 FTDI C232HM-DDHSL-0 的 Windows 驱动程序](http://www.ftdichip.com/Drivers/D2XX.htm)。

1. 在 **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
   ```

1. 下载 [OpenOCD for Windows](https://github.com/espressif/openocd-esp32/releases)。

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

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

   1. 下载 [zadig.exe](https://zadig.akeo.ie)。

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

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

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

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

1. 打开命令提示符，转到 FreeRTOS 下载目录的根目录，然后运行以下命令。

   ```
   idf.py openocd
   ```

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

1. 打开新的命令提示符，转到 FreeRTOS 下载目录的根目录，然后运行

   ```
   idf.py flash monitor
   ```

1. 打开另一个命令提示符，转到 FreeRTOS 下载目录的根目录，然后等待演示开始在您的主板上运行。开始演示时，请运行

   ```
   idf.py gdb
   ```

   程序应在 `main` 函数中停止。
**注意**  
ESP32 支持最多两个断点。

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

1. 下载[适用于 macOS 的 FTDI 驱动程序](http://www.ftdichip.com/Drivers/VCP.htm)。

1. 下载 [OpenOCD](https://github.com/espressif/openocd-esp32/releases)。

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

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

   ```
   brew install libusb
   ```

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

   ```
   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

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

   ```
   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

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

   ```
   sudo kextunload -b com.apple.driver.AppleUSBFTDI
   ```

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

   ```
   system_profiler SPUSBDataType
   ```

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

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

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

1. 打开终端窗口，转到 FreeRTOS 下载目录的根目录，然后使用以下命令运行 OpenOCD。

   ```
   idf.py openocd
   ```

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

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

   ```
   sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

1. 转到 FreeRTOS 下载目录的根目录，然后运行 

   ```
   idf.py flash monitor
   ```

1. 打开另一个新的终端，转到 FreeRTOS 下载目录的根目录，然后运行

   ```
   idf.py gdb
   ```

   程序应在 `main` 停止。

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

1. 下载 [OpenOCD](https://github.com/espressif/openocd-esp32/releases)。提取 tarball 并按照自述文件中的安装说明操作。

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

   ```
   sudo apt-get install libusb-1.0
   ```

1. 打开终端并输入 **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
   ```

1. 注销，然后登录并重新对主板加电，使更改生效。在终端提示符下，列出 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 的闪存。

1. 在终端窗口中，转到 FreeRTOS 下载目录的根目录，然后使用以下命令运行 OpenOCD。

   ```
   idf.py openocd 
   ```

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

   ```
   idf.py flash monitor 
   ```

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

   ```
   idf.py gdb
   ```

   程序应在 `main()` 中停止。