ESP32-S3 小智 AI 开发环境搭建与固件编译烧录（MCP 控制 GPIO 点亮 LED 灯示例）
文章目录
- 小智 AI 官网
- 小智 AI 文档
- 小智 AI 源码
- 小智 AI 简介
- Web 烧录固件
- 小智 AI 控制台
- 开发环境
- 下载 xiaozhi-esp32 源码
- 搭建 IDF 开发环境
- 下载 esp-idf 源码
- 配置 IDF 环境变量
- IDF 常用命令
- 编译 xiaozhi-esp32 源码
- 选择目标芯片
- 项目配置
- 编译项目
- 烧录固件
- 监控串口
- 立创实战派ESP32-S3开发板资源标注图
- 立创实战派ESP32-S3开发板原理图
- MCP 控制 GPIO 点亮 LED
在 Mac 环境 下搭建 ESP-IDF 开发环境，编译并烧录 小智 AI 语音机器人（xiaozhi-esp32） 固件。
小智 AI 是一款基于 Qwen / DeepSeek 等大模型 的智能语音助手，通过 MCP 协议 实现多端控制，支持语音唤醒、OLED 显示、声纹识别、MQTT 通信、离线唤醒词、自定义表情等功能。
文章涵盖内容包括：
- ✅ 环境搭建（ESP-IDF v5.4 与工具链安装）
- 🧰 源码下载与目标芯片配置
- ⚙️ idf.py 常用命令讲解
- 🚀 项目编译与固件烧录
- 💡 基于 MCP 的 GPIO 控制示例（C++ 代码实现绿灯点亮）
小智 AI 官网
- https://www.gtai-tech.com/
小智 AI 文档
- https://docs.gtai-tech.com/welcome
小智 AI 源码
- https://github.com/78/xiaozhi-esp32
小智 AI 简介
小智 AI 聊天机器人作为一个语音交互入口，利用 Qwen / DeepSeek 等大模型的 AI 能力，通过 MCP 协议实现多端控制。
-
已实现的功能：
- Wi-Fi / ML307 Cat.1 4G
- 离线语音唤醒 ESP-SR
- 支持两种通信协议（Websocket 或 MQTT+UDP）
- 采用 OPUS 音频编解码
- 基于流式 ASR + LLM + TTS 架构的语音交互
- 声纹识别，识别当前说话人的身份 3D Speaker
- OLED / LCD 显示屏，支持表情显示
- 电量显示与电源管理
- 支持多语言（中文、英文、日文）
- 支持 ESP32-C3、ESP32-S3、ESP32-P4 芯片平台
- 通过设备端 MCP 实现设备控制（音量、灯光、电机、GPIO 等）
- 通过云端 MCP 扩展大模型能力（智能家居控制、PC桌面操作、知识搜索、邮件收发等）
- 自定义唤醒词、字体、表情与聊天背景，支持网页端在线修改 (自定义Assets生成器)
-
固件烧录
-
新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。
-
固件默认接入 xiaozhi.me 官方服务器，个人用户注册账号可以免费使用 Qwen 实时模型。
-
Web 烧录固件
- https://fw.gtai-tech.com/
注： 烧录完成后如果 出现黑屏 可以按下主板 复位键。
小智 AI 控制台
- https://xiaozhi.me/
开发环境
- TRAE CN 或 VSCode
- 安装 ESP-IDF 插件，选择 SDK 版本 5.4 或以上
- 本项目使用 Google C++ 代码风格，提交代码时请确保符合规范
下载 xiaozhi-esp32 源码
- https://github.com/78/xiaozhi-esp32
git clone --branch v2.0.3 --depth 1 https://github.com/78/xiaozhi-esp32.git
注： 下载最新稳定版本 v2.0.3，不推荐最新版编译可能会报错。
搭建 IDF 开发环境
注： 当前示例 xiaozhi-esp32 版本 2.0.3 对应的 ESP-IDF 最低版本要求 ≥ 5.4.0。
-
《ESP32-S3 ESP-IDF 编程指南》
-
Mac 环境安装开发所需工具
brew install cmake ninja dfu-util
- 查看源码对应的 IDF 版本号
下载 esp-idf 源码
- https://github.com/espressif/esp-idf
git clone --branch v5.5 --depth 1 --recursive https://github.com/espressif/esp-idf.gitcd esp-idf# 安装 ESP32-S3 开发所需的工具链、Python 包和依赖组件
./install.sh esp32s3
# 或为多个目标芯片安装所需工具
./install.sh esp32,esp32c3,esp32s3# 配置环境变量，让 ESP-IDF 的工具链和 Python 环境在当前终端会话中可用
. ./export.sh
配置 IDF 环境变量
echo '. $HOME/esp-idf/export.sh' >> ~/.zshrc
source ~/.zshrc
# 或
echo '. $HOME/esp-idf/export.sh' >> ~/.bash_profile
source ~/.bash_profile
注： 配置好环境变量后，每次打开新终端 IDF 工具链都会自动生效。
IDF 常用命令
idf.py --version
idf.py --help# 选择目标芯片
idf.py set-target esp32s3# 项目配置
idf.py menuconfig# 构建项目
idf.py build# 烧录固件
idf.py flash
idf.py flash -p /dev/cu.usbmodem14101# 监控串口，查看串口日志
idf.py monitor
编译 xiaozhi-esp32 源码
cd xiaozhi-esp32
选择目标芯片
idf.py set-target esp32s3
项目配置
idf.py menuconfig
- 按方向键选择 Xiaozhi Assistant 回车键进入子项
- 选择 Board Type 回车键进入子项选择 立创·实战派 ESP32-S3 开发板
注： 根据自己当前开发板来选择。
- 保存配置修改并退出（按 Q 键后会弹出保存提示再输入 Y ）
编译项目
idf.py build
注： 每次打开新的终端进行项目编译都必须重复以上操作步骤，从 idf.py set-target esp32s3 到 idf.py build 。
烧录固件
idf.py flash
# 或
idf.py flash -p /dev/cu.usbmodem14101
注： 烧录完成后如果 出现黑屏 可以按下主板 复位键。
监控串口
立创实战派ESP32-S3开发板资源标注图
立创实战派ESP32-S3开发板原理图
MCP 控制 GPIO 点亮 LED
- main/boards/lichuang-dev/lamp_G.h
#include "mcp_server.h" // 引入自定义头文件，定义了 McpServer 类等接口
#include <esp_log.h> // 引入 ESP-IDF 的日志库，用于打印日志#define TAG_ "绿灯事件：" // 定义日志标签宏，方便日志输出时区分模块来源// ============================
// 定义一个类：Green_Lamp（绿灯控制器）
// ============================
class Green_Lamp {// 私有成员区
private:bool power_ = false; // 成员变量，表示绿灯当前的开关状态（true=开，false=关）gpio_num_t gpio_num_; // 保存控制绿灯的 GPIO 引脚编号// 定义普通成员函数，用于返回绿灯状态std::string GetStatus(const PropertyList& props) {ESP_LOGW(TAG_, "获取到了绿灯的当前状态，当前状态为%s", power_ ? "开" : "关");return power_ ? "{\"灯光状态：\":绿灯是开着的！}" : "{\"灯光状态：\":绿灯是关着的！}";}// 公有成员区
public:// 构造函数：Green_Lamp(gpio_num)// 语法：explicit 构造函数，防止隐式类型转换// 作用：初始化 GPIO 并注册 MCP 工具explicit Green_Lamp (gpio_num_t gpio_num) : gpio_num_(gpio_num) {// 初始化 GPIO 配置结构体gpio_config_t cfg = {.pin_bit_mask = (1ULL << gpio_num_), // 指定使用的 GPIO 引脚.mode = GPIO_MODE_OUTPUT, // 设置为输出模式.pull_up_en = GPIO_PULLUP_DISABLE, // 禁用上拉.pull_down_en = GPIO_PULLDOWN_DISABLE, // 禁用下拉.intr_type = GPIO_INTR_DISABLE, // 禁用中断};// 调用 ESP-IDF API 配置 GPIOESP_ERROR_CHECK(gpio_config(&cfg));// 初始化为低电平（关闭状态）gpio_set_level(gpio_num_, 0);// ===========================// 注册 MCP 工具（绿灯相关控制接口）// ===========================// 获取单例模式的 MCP 服务器实例auto& server = McpServer::GetInstance();// 注册时，使用 std::bind 绑定成员函数using std::placeholders::_1; // 占位符，代表参数传入位置server.AddTool("绿灯.获取开关状态", // 工具名称"返回绿灯的开/关状态", // 工具描述PropertyList(), // 工具参数（此处为空）// 将类成员函数与当前对象绑定，返回一个可调用对象（行为与 Lambda 一致）// &Green_Lamp::GetStatus 指向成员函数的指针// _1 占位符，对应回调传入的第一个参数（即 const PropertyList&）std::bind(&Green_Lamp::GetStatus, this, _1));server.AddTool("绿灯.打开", "打开绿灯",PropertyList(), [this](const PropertyList&) {power_ = true;gpio_set_level(gpio_num_, 1); // 设置为高电平ESP_LOGW(TAG_, "已打开绿灯！"); // 日志记录return true; // 返回告诉小智执行成功！});server.AddTool("绿灯.关闭", "关闭绿灯",PropertyList(), [this](const PropertyList&) {power_ = false;gpio_set_level(gpio_num_, 0); // 设置为低电平ESP_LOGW(TAG_, "已关闭绿灯！"); // 日志记录return true; // 返回告诉小智执行成功！});}
};
- main/boards/lichuang-dev/lichuang_dev_board.cc
// ...#include "lamp_G.h"class LichuangDevBoard : public WifiBoard {
// 私有成员区
private:// ...// 物联网初始化，逐步迁移到 MCP 协议void InitializeTools() {// static LampController lamp(LAMP_GPIO);static Green_Lamp lamp_G(GPIO_NUM_11);}// 公有成员区
public:LichuangDevBoard() : boot_button_(BOOT_BUTTON_GPIO) {// ...// 初始化工具InitializeTools();GetBacklight()->RestoreBrightness();}
}
- 编译烧录固件
idf.py build
idf.py flash
- 监控串口
idf.py monitor
注： 主板网络连接成功后就可以通过语音控制 LED 灯了。例：“小智帮我打开绿灯”