本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 乐鑫-S ESP32 2 入门 **重要** 该参考集成托管在已弃用的 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/) [本教程向您展示如何开始使用乐鑫 ESP32-S2 SoC 和-S2-Saola-1 开发板。ESP32](https://devices.amazonaws.com/detail/a3G0h00000AkFngEAF/ESP32-S2-Saola-1) ## 概述 该教程将指导您完成以下步骤： 1. 将主板连接到主机。 1. 在您的主机上安装软件，以开发和调试微控制器主板的嵌入式应用程序。 1. 将 FreeRTOS 演示应用程序交叉编译为二进制映像。 1. 将应用程序二进制映像加载到您的主板中，然后运行该应用程序。 1. 使用串行连接监控和调试正在运行的应用程序。 ## 先决条件 在开始在乐鑫看板上使用 FreeRTOS 之前，您必须设置账户和权限。 Amazon ### 注册获取 Amazon Web Services 账户 如果您没有 Amazon Web Services 账户，请完成以下步骤来创建一个。 **报名参加 Amazon Web Services 账户** 1. 打开[https://portal.aws.amazon.com/billing/注册。](https://portal.amazonaws.cn/billing/signup) 1. 按照屏幕上的说明操作。 在注册时，将接到电话或收到短信，要求使用电话键盘输入一个验证码。 当您注册时 Amazon Web Services 账户，就会创建*Amazon Web Services 账户根用户*一个。根用户有权访问该账户中的所有 Amazon Web Services 服务 和资源。作为最佳安全实践，请为用户分配管理访问权限，并且只使用根用户来执行[需要根用户访问权限的任务](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。 Amazon 注册过程完成后会向您发送一封确认电子邮件。您可以随时前往 [https://aws.amazon.com/](https://www.amazonaws.cn/)并选择 “**我的账户”，查看您当前的账户活动并管理您的账户**。 ### 保护 IAM 用户 注册后 Amazon Web Services 账户，开启多重身份验证 (MFA)，保护您的管理用户。有关说明，请参阅《IAM 用户指南》**中的 [为 IAM 用户启用虚拟 MFA 设备（控制台）](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-iam-user)。 要允许其他用户访问您的 Amazon Web Services 账户 资源，请创建 IAM 用户。为了保护您的 IAM 用户，请启用 MFA 并仅向 IAM 用户授予执行任务所需的权限。 有关创建和保护 IAM 用户的更多信息，请参阅《IAM 用户指南》中的以下主题：** + [在你的 IAM 用户中创建 Amazon Web Services 账户](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_create.html) + [适用于 Amazon 资源的访问权限管理](https://docs.amazonaws.cn/IAM/latest/UserGuide/access.html) + [基于 IAM 身份的策略示例](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_examples.html) 要提供访问权限，请为您的用户、组或角色添加权限： + 通过身份提供商在 IAM 中托管的用户： 创建适用于身份联合验证的角色。按照《IAM 用户指南》**中[针对第三方身份提供商创建角色（联合身份验证）](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-idp.html)的说明进行操作。 + IAM 用户： + 创建您的用户可以担任的角色。按照《IAM 用户指南》**中[为 IAM 用户创建角色](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-user.html)的说明进行操作。 + （不推荐使用）将策略直接附加到用户或将用户添加到用户组。按照《IAM 用户指南》**中[向用户添加权限（控制台）](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)中的说明进行操作。 ## 开始使用 **注意** 本教程中的 Linux 命令要求您使用 Bash Shell。 1. **设置 Espressif 硬件。** 有关设置 ESP32-S2 开发板硬件的信息，请参阅-S [ ESP322-Saola-](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html) 1 入门指南。 **重要** 当您阅读到 Espressif 手册的**入门** 部分时，请暂停并返回到此页面上的说明部分。 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/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-DevKit C 之间建立串行连接，请安装 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. 您需要 Amazon 命令行界面 (CLI) 才能运行 Amazon IoT 命令。如果你运行的是 Windows，请使用该`easy_install awscli` Amazon 命令在 “命令” 或 “ESP-IDF 4.x CMD” 应用程序中安装 CLI。 如果你运行的是 macOS 或 Linux，请参阅[安装 CLI Amazon](https://docs.amazonaws.cn/cli/latest/userguide/installing.html)。 1. 运行 ``` aws configure ``` 并使用您的 Amazon 访问密钥 ID、私有访问密钥和默认 Amazon 区域配置 Amazon CLI。有关更多信息，请参阅[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-getting-started.html)。 1. 使用以下命令安装适用于 Python 的 Amazon 开发工具包 (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 主板以连接到 Amazon IoT。 **运行配置脚本** 1. 要配置此脚本，请打开 `freertos/tools/aws_config_quick_start/configure.json` 并设置以下属性： **`afr_source_dir`** 计算机上的 `freertos` 目录的完整路径。确保您使用正斜杠来指定此路径。 **`thing_name`** 您要为代表您的看板 Amazon 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”或“命令”应用程序。 1. 导航到 `freertos/tools/aws_config_quick_start` 目录运行 ``` python SetupAWS.py setup ``` 脚本执行以下操作： + 创建 Amazon IoT 事物、证书和策略。 + 将 Amazon IoT 策略附加到证书，将证书附加到 Amazon IoT 事物。 + 使用您的 Amazon IoT 终端节点、Wi-Fi SSID 和凭证填充 `aws_clientcredential.h` 文件 + 设置您的证书和私有密钥格式，然后将其写入 `aws_clientcredential_keys.h` 标头文件 **注意** 出于演示目的，对该证书进行了硬编码。生产级应用程序应将这些文件存储在安全位置。 有关 `SetupAWS.py` 的更多信息，请参阅 `freertos/tools/aws_config_quick_start` 目录中的 `README.md` 文件。 ### 监控云端上的 MQTT 消息 Amazon 在运行 FreeRTOS 演示项目之前，您可以在控制台中 Amazon IoT 设置 MQTT 客户端，以监控您的设备发送到云端的消息。 Amazon **使用 MQTT 客户端订阅 M Amazon IoT QTT 主题** 1. 登录 [Amazon IoT 控制台](https://console.amazonaws.cn/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 (ESP-IDF v4.2) 使用 `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 ``` ### 使用构建和刷新 FreeRTOS CMake 除了使用 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=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 主板和对其进行故障排除的更多信息，请参阅以下主题： + [在你自己的项目中使用 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)