这是什么
小智AI（xiaozhi-esp32）是虾哥发起的开源 ESP32 语音助手项目，用大模型（Qwen/DeepSeek等） 做语音理解，通过 MCP 协议控制设备。官方支持很多现成开发板，也支持面包板手工接线 这种最基础的形态——本资料记录的就是面包板版本：不需要焊接，四个模块加几根杜邦线插在 面包板上，刷官方固件、配网绑定账号后就能直接对话。
固件仓库里预置了很多开发板配置，面包板 + 纯 WiFi（不接 ML307R 4G 模块）对应的板型是
bread-compact-wifi，下载固件时认准这个名字，别下成带 ml307/
NT26 后缀的 4G 版。
用到的模块
一共四个模块，先认清楚长相，接线时才不会认错。
主控
ESP32-S3（N16R8）
整个项目的大脑，联网、语音识别、控制其它模块全靠它。16MB Flash + 8MB PSRAM。
麦克风
INMP441
I2S 数字麦克风，负责把说话声音采集进来交给主控识别。
功放
MAX98357A
I2S 功放，主控识别完、准备好回复之后，声音靠它推动喇叭放出来。
屏幕
0.91寸 OLED（128×32）
I2C 屏幕，显示联网中/待机/聆听中这些设备状态。
各模块引脚说明
INMP441 麦克风
- WS数据选择（左右声道时钟），接 ESP32 GPIO4。
- SCK数据时钟，接 ESP32 GPIO5。
- SD数据输出，接 ESP32 GPIO6。
- VDD接 ESP32 3V3。
- GND接地，同时短接模块上的 L/R 选择脚。
WS 和 SCK 顺序不能搞反——接反了现象是
设备能正常开机，但完全听不懂/收不到你说话的声音，不会报错提示，只能靠对照这张表核对。
MAX98357A 功放
- DIN音频数据输入，接 ESP32 GPIO7。
- BCLK位时钟，接 ESP32 GPIO15。
- LRC左右声道时钟，接 ESP32 GPIO16。
- VIN接 ESP32 3V3 或 5V（模块支持范围内）。
- GND接地；
SD/GAIN按模块丝印说明短接或悬空。
0.91寸 OLED（I2C）
- SDAI2C 数据线，接 ESP32 GPIO41。
- SCLI2C 时钟线，接 ESP32 GPIO42。
- VCC接 ESP32 3V3。
- GND接地。
音量按键
- VOL+音量加，接 ESP32 GPIO40。
- VOL-音量减，接 ESP32 GPIO39。
完整接线表
| ESP32-S3 引脚 | 接到哪个模块 | 模块引脚 | 说明 |
|---|---|---|---|
| GPIO4 | INMP441 | WS | 数据选择 |
| GPIO5 | INMP441 | SCK | 数据时钟，别和WS接反 |
| GPIO6 | INMP441 | SD | 数据输出 |
| GPIO7 | MAX98357A | DIN | 音频数据 |
| GPIO15 | MAX98357A | BCLK | 位时钟 |
| GPIO16 | MAX98357A | LRC | 左右声道时钟 |
| GPIO41 | 0.91寸OLED | SDA | I2C数据 |
| GPIO42 | 0.91寸OLED | SCL | I2C时钟 |
| GPIO40 | 按键 | VOL+ | 音量加 |
| GPIO39 | 按键 | VOL- | 音量减 |
| 3V3 / GND | 全部模块 | VDD/VCC / GND | 共电共地，麦克风L/R脚短接到GND |
每根线接完前按两端核对一遍：左边是 ESP32 的 GPIO 编号，右边是模块的 英文引脚名——不要凭面包板插孔位置的记忆去接，两端都读一遍名字最保险。
固件下载与选型
- 打开小智AI文档站
https://xiaozhi.me/docs，找到"固件下载"区，选最新版本 （本资料整理时是 v2.2.4）。 - 进入版本更新说明页，找到"1. 烧录教程"下方的"面包板系列"表格。
- 找到
Bread Compact WiFi（面包板）这一行，下载v2.2.4_bread-compact-wifi.zip——不要下成带 ml307/NT26 后缀的 4G 版，这块板子没接 4G 模块。 - 解压 zip，里面的
merged-binary.bin才是真正要用来烧录的固件文件。
如果浏览器没有自动下载，会弹出一个"另存为"保存框，选好保存位置点 "保存"就行，这一步经常被忽略导致以为下载失败。
固件源码关键段
不用改代码，接线跟固件里预先定义好的引脚对上就行。以下两段引脚定义来自固件仓库的
main/boards/bread-compact-wifi/config.h。
① 麦克风 + 功放引脚定义（第14-19行）
#define AUDIO_I2S_MIC_GPIO_WS GPIO_NUM_4
#define AUDIO_I2S_MIC_GPIO_SCK GPIO_NUM_5
#define AUDIO_I2S_MIC_GPIO_DIN GPIO_NUM_6
#define AUDIO_I2S_SPK_GPIO_DOUT GPIO_NUM_7
#define AUDIO_I2S_SPK_GPIO_BCLK GPIO_NUM_15
#define AUDIO_I2S_SPK_GPIO_LRCK GPIO_NUM_16② 按钮 + 屏幕引脚定义（第29-33、41-42行）
#define VOLUME_UP_BUTTON_GPIO GPIO_NUM_40
#define VOLUME_DOWN_BUTTON_GPIO GPIO_NUM_39
#define DISPLAY_SDA_PIN GPIO_NUM_41
#define DISPLAY_SCL_PIN GPIO_NUM_42
#error "OLED display type is not selected"最后这行 #error 是故意设计的——如果没有在编译配置里选定
具体的 OLED 型号（比如本项目用的 CONFIG_OLED_SSD1306_128X32，对应 0.91 寸屏），
编译直接失败拒绝继续，比烧录完再猜屏幕为什么不亮省事得多。
网页烧录流程
用乐鑫官方的 ESP Launchpad 网页烧录工具，浏览器直接烧录，不用装任何桌面软件（需要 Chrome/Edge 等支持 Web Serial 的浏览器）。
- 用数据线把 ESP32-S3 接上电脑，打开 ESP Launchpad 页面，切到
DIY标签。 - Flash Address 保持默认
0。 - 点"选择文件"，选中解压出来的
merged-binary.bin。 - 点顶部
Connect，在弹出的串口列表里选中开发板对应的串口，完成连接。 - 连接成功后，点右下角的
Program，开始烧录。 - 烧录完成后设备会自动重启，重启后就能进入配网流程。
本站也做了一个网页烧录工具，
同样是浏览器直连、不装软件，内核用的是乐鑫官方 esptool-js，本地离线运行、不上传任何数据。
但老实说，功能不如官方 ESP Launchpad 完善，属于备用工具：
- 不是通用工具——写入地址（
0x0）、Flash 大小（16MB）都是照这块板子这份固件写死的， 换别的板子或固件用不了；ESP Launchpad 的DIY模式可以自己填地址，适用范围更广。 - 没人长期维护——ESP Launchpad 是乐鑫官方产品，这个是个人写的，出问题不保证有人跟进修。
- 自动重启不一定成功——工具页面自己也提示了，烧录完更保险的做法是手动按一下开发板的
RST键，不要干等自动重启。
它比官方工具多一个地方：烧录完能在同一个页面直接看设备重启后的串口日志， 不用另开串口监视器。日常烧录还是建议先用 ESP Launchpad，这个工具留着备用，或者你想顺便看一眼启动日志时用。
配网与设备绑定
配网
- 设备第一次开机，会自己开一个 WiFi 热点等你配网。
- 手机 WiFi 列表里找到
Xiaozhi开头的热点，连上它。 - 手机通常会自动弹出配置页面；没弹出的话手动打开浏览器访问
192.168.4.1。 - 页面里填的是你家路由器的名字和密码，不是小智账号的密码。
- 填完点连接，等页面显示"正在连接"，成功后设备就接入你家网络了。
设备绑定
- 打开小智AI官网，登录控制台，点"添加设备"。
- 设备第一次开机或重启，会念出一个 6 位数验证码，把验证码填进去，点添加。
- 绑定成功后会让你确认设备接入协议，选开源版，免费接入核心功能就够用。
- 回到智能体列表，设备下面显示"设备(1)"就说明绑定完成，可以直接开口跟它对话了。
常见问题与避坑
| 现象 | 优先检查 |
|---|---|
| 能开机，但听不懂/收不到说话声音 | INMP441 的 WS/SCK 是否接反（GPIO4/GPIO5） |
| 屏幕不显示或花屏 | SDA/SCL 是否接反（GPIO41/GPIO42）；编译时是否选对了 128×32 屏型 |
| 编译报错 "OLED display type is not selected" | 正常提示，编译配置里需要显式选定屏幕型号 |
| 下载的固件烧录后一直重启找不到网络 | 确认下载的是 bread-compact-wifi 而不是带 4G 后缀的版本 |
| 点下载没反应 | 浏览器可能弹出了"另存为"保存框，需要手动点保存 |
| 网页烧录工具连不上串口 | 确认用的是支持 Web Serial 的浏览器，且没有其它程序占用该串口 |
下一步能做什么
这套接线和固件配置已经实机验证跑通，照第3-4节把线接好、第5-8节走完， 正常情况下不用改一行代码就能听到设备回你说话。