小智接线和默认不一样：引脚定义改哪里、怎么改才不出事

只要你不是买的现成小智整机，而是拿一块通用开发板自己接了麦克风、功放和屏，那么你的接线和参考板一致的概率基本为零。

这时候固件烧进去，现象通常是：能开机、能连网、日志看着正常，但喊它没反应，或者它说话你听不见。你会怀疑麦克风坏了、功放坏了、板子有问题——其实只是固件在按别人的接线找你的硬件。

引脚定义在哪一层

在你那块板子目录下的 config.h 里。

按上游自定义开发板文档，一个板子目录包含 xxx_board.cc（板级初始化代码）、config.h（硬件配置）、config.json（板型与构建配置）和 README.md。硬件相关的参数和引脚，归 config.h 管。

这个分层是有意义的：上层的对话、唤醒、MCP 逻辑完全不关心你的喇叭接在哪个引脚——应用启动时拿到一个 board 对象，所有板级资源都从它取。所以改接线这件事，理论上只需要动这一层，不该去改协议或业务代码。如果你发现自己在改别的地方，多半是走偏了。

改之前，先确认你改的是"生效的那份"

这是最容易白忙半天的坑：改了 config.h，编译烧录，一点变化都没有。

原因几乎总是同一个：你改的板子目录，和你编译时选中的板型，不是同一个。

比如你复制了一份参考板目录改成自己的，改得很仔细，但编译时板型还选着原来那个——你改的那份文件根本没参与编译。

确认方法：看你编译时指定的板型名，和你改的目录名对不对得上。用脚本编译时这一点比较直观：

python scripts/build.py <board>

这里的 <board> 就是决定"用哪个目录"的东西。改文件前先确认这条对应关系，能省掉一整轮无效编译。

顺带一提，如果你是新建的板型目录，别忘了 Kconfig 和 CMakeLists 两处都要加——只加一处会出现"选不到"或"找不到目录"，详见小智自定义开发板怎么加。

ESP32-S3 上哪些引脚碰不得

改引脚最危险的不是接错，是用了不能用的引脚——因为症状往往不是"这个外设不工作"，而是整块板子起不来、反复重启、烧不进去，特别难往引脚上想。

在 ESP32-S3 上，下面这几类需要特别当心：

• Strapping 引脚（如 GPIO0、GPIO3、GPIO45、GPIO46）—— 芯片上电时靠它们决定启动模式。被外设拉住电平，可能直接导致启动不正常或进不去下载模式。
• USB 相关引脚（GPIO19、GPIO20）—— 占用后 USB 功能会受影响。
• 接 flash / PSRAM 的引脚（GPIO26–37 这一段）—— 这些是芯片内部存储用的，占用轻则不稳定，重则起不来。
• 不存在的引脚（GPIO22–25 在 S3 上没有）—— 写了也不会工作，但你会一直以为是别的原因。

最后一条尤其阴险：代码能编译过，运行不报错，就是没反应。见过不少人在这上面耗掉一整天，因为完全想不到"这个引脚根本不存在"。

具体哪些引脚可用、各有什么限制，以乐鑫官方该芯片的技术参考手册和 datasheet 为准。不同芯片（S3 / C3 / C6 / P4）差别很大，别把 S3 的经验直接套到 C 系列上。

站内工具里有个 ESP32-S3 GPIO 引脚查询 / 选脚检查，改引脚前过一遍能挡掉大部分低级错误。

按这个顺序验证

改完引脚，别一次全测，按这个顺序走，每一步失败都能指向一小段配置：

第一步：能不能开机。 串口有正常日志、不反复重启，说明你没有踩到 strapping 或 flash 引脚。这一步不过，别往下走——先把引脚从危险区挪开。

第二步：麦克风。 对着说话，看日志里有没有识别相关的反应。不行就查音频输入这组引脚和 codec 的 I2C 地址、采样率。

第三步：喇叭。 有没有声音、声音正不正常。破音、杂音往往不是引脚错，而是功放配置或采样率对不上。

第四步：屏幕。 亮不亮、显示正不正常。这一层还牵涉分辨率和字体配置。

倒过来测会很痛苦：屏幕不亮，你根本分不清是引脚错、参数错，还是板子压根没正常启动。

动手前先做一张对照表

改引脚最容易出的不是技术错误，是对不上号——你以为改的是麦克风的时钟线，其实改的是数据线。

所以强烈建议在改代码前，先花十分钟做一张三列表：

功能	参考板原来接在	我实际接在
麦克风 I2S 时钟	GPIOxx	GPIOyy
麦克风 I2S 数据	GPIOxx	GPIOyy
功放使能	GPIOxx	GPIOyy
…	…	…

这张表的价值有三个：

一是逼你把接线彻底搞清楚。 很多人其实说不全自己接了哪些线——填不出这张表，说明你还没准备好改代码，先回去看原理图。

二是改代码时照着抄，不容易串行。 一行一行对，比在脑子里记着改可靠得多。

三是出问题时能快速复查。 症状出来后，拿着表和实物、和代码各对一遍，比重新理解一遍快得多。

有个细节容易漏：功放使能、屏幕背光、电源控制这类"不传数据但必须对"的引脚，很多人只顾着填 I2S 和 I2C，把它们忘了。它们的特点是漏配之后日志完全正常，就是没反应——最难查的那一类。表里一定要留行给它们。

一个容易忽略的前提

改引脚前，先确认你的接线本身是对的。

我见过太多人反复改 config.h，其实是硬件那头虚焊、杜邦线松了、或者麦克风模块本身要求的电压不对。软件配置只能描述硬件，不能修复硬件。

一个简单的判断：如果你改了好几组不同的引脚组合都是同样的症状，那问题大概率在硬件或者更底层的配置上，别在引脚号上继续试。穷举引脚号是最没效率的排查方式，值得早点放弃。

还有一个几乎每个新手都会栽一次的坑：共地。用外部电源给功放或舵机单独供电时，那个电源的地必须和开发板的地接到一起，否则信号没有共同参考点——现象是时好时坏、抖动、乱动，看起来极像代码问题，其实少接一根地线。引脚号填得再对也救不了。

相关：小智自定义开发板怎么加讲完整的加板型流程，小智编译失败怎么查讲编译层面的问题，小智固件现在要 ESP-IDF 6.0 了提到新版本里 I2S 和 LCD 相关的改动——那正是自定义板最容易撞上的两处。