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

# 乐鑫-WROOM-32SE ESP32 入门
<a name="getting_started_esp32wroom-32se"></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 项目中，请参阅我们精选的-C3 平台参考集成。 ESP32](https://www.freertos.org/featured-freertos-iot-integration-targeting-an-espressif-esp32-c3-risc-v-mcu/)
目前，-WROOM-32SE 的 FreeRTOS 端口不支持 ESP32对称多处理 (SMP) 功能。

本教程向您展示了如何开始使用乐鑫-WROOM-32SE ESP32。要在合作伙伴设备目录中向我们的合作伙伴购买一台，请参阅 [ESP32-WROOM-32SE。 AWS](https://devices.amazonaws.com/detail/a3G0h0000077nRtEAI/ESP32-WROOM-32SE)

## 概述
<a name="getting_started_esp32wroom-32se-overview"></a>

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

1. 将主板连接到主机。

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

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

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

1. 使用串行连接监控和调试正在运行的应用程序。

## 先决条件
<a name="setup-esp32wroom-32se-prereqs"></a>

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

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

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

**报名参加 AWS 账户**

1. 打开[https://portal.aws.amazon.com/billing/注册。](https://portal.aws.amazon.com/billing/signup)

1. 按照屏幕上的说明操作。

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

   当您注册时 AWS 账户，就会创建*AWS 账户根用户*一个。根用户有权访问该账户中的所有 AWS 服务 和资源。作为最佳安全实践，请为用户分配管理访问权限，并且只使用根用户来执行[需要根用户访问权限的任务](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。

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

### 创建具有管理访问权限的用户
<a name="create-an-admin"></a>

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

**保护你的 AWS 账户根用户**

1.  选择 **Root 用户**并输入您的 AWS 账户 电子邮件地址，以账户所有者的身份登录。[AWS 管理控制台](https://console.aws.amazon.com/)在下一页上，输入您的密码。

   要获取使用根用户登录方面的帮助，请参阅《AWS 登录 用户指南》**中的 [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial)。

1. 为您的根用户启用多重身份验证（MFA）。

   有关说明，请参阅 I [A *M* 用户指南中的为 AWS 账户 根用户启用虚拟 MFA 设备（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html)。

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

1. 启用 IAM Identity Center。

   有关说明，请参阅**《AWS IAM Identity Center 用户指南》中的[启用 AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html)。

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

   有关使用 IAM Identity Center 目录 作为身份源的教程，请参阅《[用户*指南》 IAM Identity Center 目录中的使用默认设置配置AWS IAM Identity Center 用户*访问权限](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html)。

**以具有管理访问权限的用户身份登录**
+ 要使用您的 IAM Identity Center 用户身份登录，请使用您在创建 IAM Identity Center 用户时发送到您的电子邮件地址的登录 URL。

  有关使用 IAM Identity Center 用户[登录的帮助，请参阅*AWS 登录 用户指南*中的登录 AWS 访问门户](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html)。

**将访问权限分配给其他用户**

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

   有关说明，请参阅《AWS IAM Identity Center 用户指南》**中的 [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html)。

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

   有关说明，请参阅《AWS IAM Identity Center 用户指南》**中的 [Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.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-esp32wroom-32s-idf42"></a>

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

1. **设置 Espressif 硬件。**

   有关设置 ESP32-WROOM-32SE 开发板硬件的信息，请参阅 [ ESP32-DevKit C](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/index.html#installation-step-by-step) V4 入门指南。
**重要**  
在该指南的**分步安装**部分，请按照步骤进行操作，直到完成步骤 4（设置环境变量）。完成步骤 4 后，请暂停，然后按照此处的其余步骤进行操作。

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

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

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

   **Windows**

   1. 下载 ESP-IDF 的 Windows 版[通用在线安装程序](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-WROOM-32SE 之间建立串行连接，请安装 CP210x USB 到 UART Bridge VCP 驱动程序。您可以从 [Silicon Labs](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) 下载这些驱动程序。

   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-esp32wroom-32s-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`。） 

**重要**  
 ATECC608A 设备具有一次性初始化，在第一次运行项目时（在调用期间`C_InitToken`），该初始化会锁定在设备上。但是，FreeRTOS 演示项目和测试项目的配置不同。如果设备在演示项目配置期间被锁定，则并非测试项目中的所有测试都会成功。

1. 按照[配置 FreeRTOS 演示](freertos-prereqs.md#freertos-configure)中的步骤配置 FreeRTOS 演示项目。进入最后一步后，**要格式化 AWS IoT 凭据，请**停止并执行以下步骤。

1. Microchip 提供了多种脚本工具来帮助设置 ATECC608 A 部分。导航到 `freertos/vendors/microchip/example_trust_chain_tool` 目录并打开 `README.md` 文件。

1. 请按照 `README.md` 文件中的说明预置您的设备。相应步骤包括：

   1. 创建并注册证书颁发机构 AWS。

   1. 在 ATECC608 A 上生成密钥并导出公钥和设备序列号。

   1. 为设备生成证书并向注册该证书 AWS。

1. 按照 [开发人员模式密钥预置](dev-mode-key-provisioning.md) 的说明，将 CA 证书和设备证书加载到设备上。

### 监控云端上的 MQTT 消息 AWS
<a name="gsg-esp32wroom-32se-monitor-mqtt"></a>

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

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

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

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

1. 在**订阅主题**中，输入 `your-thing-name/example/topic`，然后选择**订阅主题**。

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

您可以使用 Espressif 的 IDF (`idf.py`) 生成构建文件，构建应用程序二进制文件，将二进制文件刷写到设备。

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

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

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

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

### 使用构建和刷新 FreeRTOS CMake
<a name="flash-esp32wroom-32se-cmake-idf42"></a>

除了使用 IDF SDK 提供的`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_plus_ecc608a_devkitc -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0
   ```  
**对于 Ninja**  

   ```
   cmake -DVENDOR=espressif -DBOARD=esp32_plus_ecc608a_devkitc -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 erase_flash
   ```

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

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY erase_flash
   ```

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY flash
   ```

## 附加信息
<a name="getting_started_esp32wroom-32se-additional"></a>

有关使用 Espressif ESP32 主板和对其进行故障排除的更多信息，请参阅以下主题：
+ [在你自己的项目中使用 FreeRTOS CMake ESP32](getting_started_espressif.md#getting_started_espressif_cmake_project)
+ [问题排查](getting_started_espressif.md#getting_started_espressif_troubleshooting)
+ [调试](getting_started_espressif.md#getting_started_espressif_debugging)