本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 乐鑫入门 ESP32-S2 **重要** 此参考集成托管在已弃用的 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/) 本教程将向您展示如何开始使用乐新 So ESP32-S2 C 和[ESP32-S2-Saola-1](https://devices.amazonaws.com/detail/a3G0h00000AkFngEAF/ESP32-S2-Saola-1)开发板。 ## 概述 该教程将指导您完成以下步骤： 1. 将主板连接到主机。 1. 在您的主机上安装软件，以开发和调试微控制器主板的嵌入式应用程序。 1. Cross-compile 二进制图像的 FreeRTOS 演示应用程序。 1. 将应用程序二进制映像加载到您的主板中，然后运行该应用程序。 1. 使用串行连接监控和调试正在运行的应用程序。 ## 先决条件 在开始在乐鑫看板上使用 FreeRTOS 之前，您必须设置账户和权限。 AWS ### 注册获取 AWS 账户 要开始使用 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)中的说明进行操作。 ## 开始使用 **注意** 本教程中的 Linux 命令要求您使用 Bash Shell。 1. **设置 Espressif 硬件。** 有关设置 ESP32-S2 开发板硬件的信息，请参阅《[ ESP32-S2-Saola-1 入门指南》](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.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/esp32s2/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/esp32s2/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) 下载这些驱动程序。 1. 按照[建立与 ESP32 的串行连接](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/establish-serial-connection.html)中的步骤操作。 1. 建立串行连接后，记下主板连接的串行端口。您需要它来刷写演示。 ### 配置 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`。） 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” 应用程序中运行 ``` easy_install boto3 ``` + 在 macOS 或 Linux 上，运行 ``` pip install tornado nose --user ``` 然后运行 ``` pip install boto3 --user ``` FreeRTOS 包含 `SetupAWS.py` 脚本，可以更轻松地设置您的 Espressif 主板以连接到 AWS IoT。 **运行配置脚本** 1. 要配置此脚本，请打开 `{{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” 应用程序。 1. 导航到 `{{freertos}}/tools/aws_config_quick_start` 目录运行 ``` python SetupAWS.py setup ``` 脚本执行以下操作： + 创建 AWS IoT 事物、证书和策略。 + 将 AWS 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 消息 AWS 云 在运行 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 演示项目 您可以使用 Espressif 的 IDF 实用工具生成构建文件，构建应用程序二进制文件和刷写主板。 #### 在 Windows、Linux 和 macOS 上构建和刷新 FreeRTOS (v4.2) ESP-IDF 使用 `idf.py` 脚本构建项目并将二进制文件刷写到设备上。 **注意** 某些设置可能需要您使用在 `idf.py` 中使用端口选项 `-p port-name` 来指定正确的端口，如以下示例所示。 ``` idf.py -p /dev/cu.usbserial-00101301B flash ``` **构建和刷写项目** 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=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 build ``` 您应该会看到以下示例的输出。 ``` Executing action: all (aliases: build) Running cmake in directory /path/to/hello_world/build Executing "cmake -G Ninja -DPYTHON_DEPS_CHECKED=1 -DESP_PLATFORM=1 -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -DCCACHE_ENABLE=0 /path/to/hello_world"... -- The C compiler identification is GNU 8.4.0 -- The CXX compiler identification is GNU 8.4.0 -- The ASM compiler identification is GNU ... (more lines of build system output) [1628/1628] Generating binary image from built executable esptool.py v3.0 Generated /path/to/hello_world/build/aws_demos.bin Project build complete. To flash, run this command: esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip esp32s2 write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x16000 build/ota_data_initial.bin 0x20000 build/aws_demos.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 除了使用 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=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -S . -B ./{{YOUR_BUILD_DIRECTORY}} -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 ``` + 对于 Ninja ``` cmake -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -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 ``` ## 附加信息 有关 Espressif ESP32 主板的更多信息，请参阅以下主题： + [在您适用于 ESP32 的 CMake 项目中使用 FreeRTOS](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)