ESP32-S3 小智 AI 开发环境搭建与固件编译烧录（MCP 控制 GPIO 点亮 LED 灯示例）
文章目录
- 小智 AI 官网
- 小智 AI 文档
- 小智 AI 源码
- 小智 AI 简介
- Web 烧录固件
- 小智 AI 控制台
- 开发环境
- 立创实战派ESP32-S3开发板资源标注图
- 立创实战派ESP32-S3开发板原理图
- MCP 控制 GPIO 点亮 LED
在 Mac 环境 下搭建 ESP-IDF 开发环境，编译并烧录 小智 AI 语音机器人（xiaozhi-esp32） 固件。
小智 AI 是一款基于 Qwen / DeepSeek 等大模型 的智能语音助手，通过 MCP 协议 实现多端控制，支持语音唤醒、OLED 显示、声纹识别、MQTT 通信、离线唤醒词、自定义表情等功能。
文章涵盖内容包括：
- ✅ 环境搭建（ESP-IDF v5.5 与工具链安装）
- 🧰 源码下载与目标芯片配置
- ⚙️ idf.py 常用命令讲解
- 🚀 项目编译与固件烧录
- 💡 基于 MCP 的 GPIO 控制示例（C++ 代码实现绿灯点亮）
小智 AI 官网
小智 AI 文档
小智 AI 源码
小智 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 烧录固件
注： 烧录完成后如果 出现黑屏 可以按下主板 复位键。
小智 AI 控制台
开发环境
- TRAE CN 或 VSCode
- 安装 ESP-IDF 插件，选择 SDK 版本 5.4 或以上
- 本项目使用 Google C++ 代码风格，提交代码时请确保符合规范
- ESP32 (基于 ESP-IDF) 应用开发相关 C++ 知识体系
下载 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 源码
git clone --branch v5.5 --depth 1 --recursive https://github.com/espressif/esp-idf.git cd 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 的日志库，用于打印日志#defineTAG_"绿灯事件："// 定义日志标签宏，方便日志输出时区分模块来源// ============================// 定义一个类：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 协议voidInitializeTools(){// 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 灯了。例：“小智帮我打开绿灯”