xiaozhi_esp32s3_lis

GitHub ↗

ESP32-S3 小智 AI 语音聊天机器人固件，支持离线唤醒、流式对话、多语言识别与 50+ 款硬件平台

Stars

Forks

Issues

Watchers

技术栈

C++ 80.2%C 14.7%Python 4.2%CMake 0.9%Shell 0%

小智 AI 聊天机器人固件（XiaoZhi AI Chatbot）

基于 ESP32-S3 的开源 AI 语音对话机器人固件，支持离线语音唤醒、流式语音对话、多语言识别与多硬件平台适配。

（中文 | English | 日本語）

📺 相关视频

✨ 功能特性

网络连接：支持 Wi-Fi 与 ML307 Cat.1 4G 双模
唤醒方式：BOOT 键点击/长按唤醒与打断；离线语音唤醒（基于 ESP-SR）
流式语音对话：支持 WebSocket 与 MQTT+UDP 两种通信协议
多语言识别：国语、粤语、英语、日语、韩语 5 种语言（基于 SenseVoice）
声纹识别：识别是谁在喊 AI 的名字（基于 3D-Speaker）
语音合成（TTS）：支持火山引擎与 CosyVoice
大语言模型（LLM）：支持 Qwen、DeepSeek、豆包等
自定义角色：可配置提示词与音色，打造个性化 AI 角色
短期记忆：每轮对话后自我总结，维持上下文连贯
显示屏支持：OLED / LCD 显示屏，显示信号强弱与对话内容；LCD 支持显示图片表情
多语言界面：中文简体、中文繁体、英语、日语
OTA 升级：支持固件在线升级
IoT 物模型：内置电池、屏幕、扬声器、台灯等设备物模型

🛠 技术栈

类别	技术
主控芯片	ESP32-S3 / ESP32-C3
开发框架	ESP-IDF >= 5.3
语言	C++17
GUI 框架	LVGL 9.2.2 + esp_lvgl_port
语音唤醒	ESP-SR 2.x
音频编解码	Opus（esp-opus-encoder）
音频处理	AFE 降噪 / 增益（仅 ESP32-S3 + PSRAM）
音频 Codec	ES8311 / ES8388 / Box Codec 等
网络协议	WebSocket / MQTT + UDP
4G 模组	ML307（esp-ml307）
配网	esp-wifi-connect
字体	xiaozhi-fonts
LED 驱动	led_strip
构建系统	CMake + idf.py

📁 项目结构

xiaozhi_esp32s3_lis/
├── CMakeLists.txt              # 顶层 CMake，项目版本 v1.5.1
├── sdkconfig.defaults          # 默认 SDK 配置（ESP32-S3）
├── sdkconfig.defaults.esp32c3  # ESP32-C3 专用配置
├── partitions.csv              # 分区表（默认）
├── partitions_4M.csv           # 4MB Flash 分区表
├── partitions_8M.csv           # 8MB Flash 分区表
├── partitions_32M_sensecap.csv # SenseCAP 32MB 分区表
├── main/
│   ├── CMakeLists.txt          # 主组件构建配置
│   ├── Kconfig.projbuild       # 菜单配置项（开发板/语言/协议/屏幕等）
│   ├── idf_component.yml       # 依赖组件清单
│   ├── main.cc                 # 程序入口，初始化 NVS 与事件循环
│   ├── application.h / .cc     # 核心应用单例，状态机与主循环
│   ├── settings.h / .cc        # 设备设置管理
│   ├── system_info.h / .cc     # 系统信息
│   ├── ota.h / .cc             # OTA 固件升级
│   ├── background_task.h / .cc  # 后台音频编解码任务
│   ├── boards/                 # 各开发板适配层（50+ 款硬件）
│   │   ├── common/             # 通用板级基类（WiFi/ML307/电源/按键/I2C）
│   │   ├── lichuang-dev/       # 立创·实战派 ESP32-S3
│   │   ├── esp-box-3/          # 乐鑫 ESP32-S3-BOX3
│   │   ├── m5stack-core-s3/    # M5Stack CoreS3
│   │   ├── atoms3r-echo-base/  # AtomS3R + Echo Base
│   │   └── ...                  # 更多开发板
│   ├── audio_codecs/           # 音频 Codec 驱动（ES8311/ES8388/Box等）
│   ├── audio_processing/       # 音频处理（降噪/唤醒词检测）
│   ├── display/                # 显示驱动（LCD/OLED）
│   ├── led/                    # LED 驱动（GPIO/单灯/环形灯条）
│   ├── protocols/              # 通信协议（WebSocket/MQTT）
│   ├── iot/                    # IoT 物模型（电池/屏幕/扬声器/台灯）
│   └── assets/                 # 多语言语音提示资源（zh-CN/en-US/ja-JP/zh-TW）
├── docs/
│   ├── websocket.md            # WebSocket 通信协议文档
│   ├── wiring.jpg / wiring2.jpg # 面包板接线图
│   └── *.jpg                   # 各开发板实物图
├── scripts/
│   ├── flash.sh                # 烧录脚本
│   ├── release.py              # 发布脚本
│   ├── gen_lang.py             # 多语言资源生成
│   └── p3_tools/               # p3 音频格式转换工具
└── LICENSE                     # MIT 许可证

🚀 快速开始

方式一：免开发环境烧录（推荐新手）

无需搭建 ESP-IDF 开发环境，直接使用预编译固件烧录。固件默认接入 xiaozhi.me 官方服务器，个人用户注册后可免费使用 Qwen 实时模型。

👉 Flash 烧录固件（无 IDF 开发环境）

方式二：源码编译烧录

环境要求

操作系统：Linux（推荐，编译速度快、免驱动问题）或 Windows / macOS
编辑器：Cursor 或 VSCode
ESP-IDF：SDK 版本 >= 5.3（通过 VSCode ESP-IDF 插件安装）
Python 3

克隆与编译

git clone https://github.com/G-YOUNG01/xiaozhi_esp32s3_lis.git
cd xiaozhi_esp32s3_lis

# 设置目标芯片（默认 ESP32-S3）
idf.py set-target esp32s3

# 菜单配置（选择开发板型号、语言、通信协议等）
idf.py menuconfig
# 导航到 "Xiaozhi Assistant" 菜单进行配置

# 编译
idf.py build

# 烧录（替换 COMx 为实际串口号）
idf.py -p COMx flash

# 查看串口日志
idf.py -p COMx monitor

面包板手工制作

详见飞书文档教程：

👉 《小智 AI 聊天机器人百科全书》

面包板效果图

⚙️ 配置说明

通过 idf.py menuconfig → Xiaozhi Assistant 菜单配置以下选项：

开发板类型（Board Type）

支持 50+ 款开发板，常用包括：

开发板	配置项
面包板（WiFi）	`BOARD_TYPE_BREAD_COMPACT_WIFI`
面包板（WiFi + LCD）	`BOARD_TYPE_BREAD_COMPACT_WIFI_LCD`
面包板（ML307 4G）	`BOARD_TYPE_BREAD_COMPACT_ML307`
立创·实战派 ESP32-S3	`BOARD_TYPE_LICHUANG_DEV`
乐鑫 ESP32-S3-BOX3	`BOARD_TYPE_ESP_BOX_3`
M5Stack CoreS3	`BOARD_TYPE_M5STACK_CORE_S3`
AtomS3R + Echo Base	`BOARD_TYPE_ATOMS3R_ECHO_BASE`
神奇按钮 2.4 / 2.5	`BOARD_TYPE_MAGICLICK_2P4 / 2P5`
微雪 ESP32-S3-Touch-AMOLED-1.8	`BOARD_TYPE_ESP32S3_Touch_AMOLED_1_8`
LILYGO T-Circle-S3	`BOARD_TYPE_LILYGO_T_CIRCLE_S3`
SenseCAP Watcher	`BOARD_TYPE_SENSECAP_WATCHER`
虾哥 Mini C3	`BOARD_TYPE_XMINI_C3`

完整列表请查看 main/Kconfig.projbuild 中的 BOARD_TYPE 选项。

显示屏类型

OLED：SSD1306 128x32 / 128x64（面包板 WiFi/ML307/ESP32 可选）
LCD：ST7789（多种分辨率）、ST7735、ST7796、ILI9341、GC9A01 圆屏、自定义参数

语言选择

中文简体（LANGUAGE_ZH_CN，默认）
中文繁体（LANGUAGE_ZH_TW）
英语（LANGUAGE_EN_US）
日语（LANGUAGE_JA_JP）

通信协议

MQTT + UDP（默认）：低延迟语音传输
WebSocket：需配置 WEBSOCKET_URL 与 WEBSOCKET_ACCESS_TOKEN

功能开关

配置项	默认	说明
`USE_WAKE_WORD_DETECT`	开启	离线唤醒词检测（需 ESP32-S3 + PSRAM）
`USE_AUDIO_PROCESSOR`	开启	音频降噪与增益处理（需 ESP32-S3 + PSRAM）
`USE_WECHAT_MESSAGE_STYLE`	关闭	使用微信聊天界面风格

OTA 升级地址

OTA_VERSION_URL：固件版本检查 URL，默认为本地测试地址，部署时需修改为实际服务器地址。

🔌 已支持的开源硬件

📡 智能体配置

设备烧录后，可登录 xiaozhi.me 控制台进行 AI 智能体配置（模型选择、提示词、音色等）。

👉 后台操作视频教程（旧版界面）

📖 技术文档

WebSocket 通信协议文档
私有化部署服务器参考：xiaozhi-esp32-server（MIT 许可证）

🧪 代码风格

使用 Google C++ 代码风格，提交代码前请确保符合规范。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！学习交流 QQ 群：376893254。新增开发板适配请在 main/boards/ 下创建对应目录，包含 config.h、config.json 与板级实现文件。

📄 许可证

MIT License — 允许免费使用，包括商业用途。

👤 作者

GYOUNG - GitHub

本项目是虾哥的第一个硬件作品，希望帮助更多人入门 AI 硬件开发。

← 返回作品集