1. ESP32-S3 离线语音唤醒开发环境搭建

任务目标

在本地搭建 ESP-IDF 开发环境，编译一个最小工程并烧录到 ESP32-S3 开发板，通过板载 LED 闪烁验证工具链、编译、烧录全流程可用。本案例不涉及语音唤醒算法，仅完成环境验证，为后续离线语音唤醒实验铺路。

环境准备

• 操作系统：Windows 10/11 / Ubuntu 20.04+ / macOS
• 开发板：ESP32-S3-DevKitC-1（或兼容板），板载 RGB LED 连接 GPIO 48
• 依赖：Python 3.8+、Git
• ESP-IDF：v5.2 或更新版本（本案例以 v5.2 为例）

安装 ESP-IDF

Linux/macOS 执行以下命令（Windows 请使用 ESP-IDF PowerShell 安装器，或参考官方 Windows 安装指南）：

mkdir -p ~/esp
cd ~/esp
git clone --recursive -b v5.2 https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32s3
source ./export.sh

安装完成后，每次打开新终端需先执行 source ~/esp/esp-idf/export.sh 使环境变量生效。

工程代码

创建工程目录并编写主文件。以下代码实现板载 LED 以 500ms 间隔闪烁：

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#include "esp_log.h"

#define BLINK_GPIO 48  // ESP32-S3-DevKitC-1 板载 RGB LED 绿色通道

static const char *TAG = "blink";

void app_main(void)
{
    gpio_reset_pin(BLINK_GPIO);
    gpio_set_direction(BLINK_GPIO, GPIO_MODE_OUTPUT);

    ESP_LOGI(TAG, "LED blink started on GPIO %d", BLINK_GPIO);

    while (1) {
        gpio_set_level(BLINK_GPIO, 1);
        vTaskDelay(pdMS_TO_TICKS(500));
        gpio_set_level(BLINK_GPIO, 0);
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

编译与烧录

在工程目录下执行：

idf.py set-target esp32s3
idf.py menuconfig   # 无需修改任何配置，直接退出即可
idf.py build
idf.py -p /dev/ttyUSB0 flash   # Linux 示例，Windows 为 COM 口

烧录成功后，开发板会自动复位运行程序。若未自动复位，可手动按一下开发板上的 RST 键。

验证方法

• 观察板载 RGB LED 是否以约 1Hz 频率闪烁（亮 500ms、灭 500ms）。
• 若 LED 不亮，检查 GPIO 编号是否与你的开发板丝印一致（部分板载 LED 接 GPIO 2 或 38，需按实际硬件修改代码中的 BLINK_GPIO）。
• 在串口监视器（idf.py monitor）中应看到日志输出 LED blink started on GPIO 48，且无报错信息。

满足以上两点即说明 ESP-IDF 环境搭建成功，编译、烧录、运行链路完整可用。

常见问题

• 烧录失败提示无法打开端口：检查 USB 驱动是否安装（CP210x 或 CH340），确认端口号正确，Linux 下可能需要 sudo chmod 666 /dev/ttyUSB0 或加入 dialout 用户组。
• 编译报错找不到 esp_log.h：确认已执行 source export.sh，且工程目录下存在 CMakeLists.txt（由 idf.py create-project 生成或手动创建）。
• LED 不闪烁但程序运行正常：检查 GPIO 引脚定义是否与硬件匹配，部分开发板的板载 LED 为低电平点亮，需将代码中两个 gpio_set_level 参数互换。