
本文来源:http://www.lpqz.cn/news/106486
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
1. 从一次“翻车”说起,为什么换块板子就跑不起来了。前段时间有个做智能语音硬件的朋友找我说,他把一套跑得好好的小智源码从一块ESP32-S3开发板挪到另一块ESP32-S3开发板上,结果编译能过、烧录也成功,但一上电就卡在启动阶段,串口日志刷到一半就重启,偶尔还会出现音频完全没声音、屏幕花屏、按键全乱的情况。他反复确认过芯片型号一样、Flash大小一样、甚至开发板外观都长得差不多,但就是跑不起来。他问我的第一句话是“同一套源码换块板子为什么还要重新适配”,这个问题其实特别典型。很多刚接触ESP32语音交互项目的朋友会下意识地把“芯片型号相同”等同于“硬件完全兼容”,把“源码能编译”等同于“固件能跑通”。但真实情况是小智源码这类项目对硬件外设的依赖非常深,它不是一个纯软件逻辑的程序,而是一个把芯片、音频编解码器、麦克风阵列、功放、屏幕、按键、存储、电源管理全部串起来的嵌入式系统。换一块开发板,哪怕主控芯片一模一样,只要外围器件的型号、连接引脚、供电时序、总线地址有任何一处不同,整套系统就可能从“能跑”变成“跑不起来”。我打算把这件事彻底讲清楚。这篇文章会从小智源码的架构特点出发,拆解“换板子要重新适配”背后的真实原因,然后给出可复现的适配流程、参数计算方法、常见问题排查表以及我自己踩过的坑。适合正在玩ESP32语音项目、准备换板子、或者打算自己画板子的朋友参考。哪怕你只是刚拿到一块ESP32-S3开发板还没跑通第一个语音demo,这里面的思路也能帮你少走很多弯路。
2. 小智源码到底依赖了哪些硬件细节。2.1 它不是“一个程序”而是一整套硬件抽象层。很多人第一次看小智源码的目录结构会觉得它就是一个普通的ESP-IDF工程,有main、有components、有CMakeLists.txt。但真正跑起来之后你会发现它内部其实分了好几层:最上面是语音交互逻辑,中间是音频处理和服务通信,最底下是板级支持包也就是常说的Board层。这个Board层才是决定“换板子要不要改代码”的关键。Board层做的事情说白了就是把“芯片的通用引脚”翻译成“这块板子上真实的外设”。比如芯片的GPIO编号是固定的,但哪一根GPIO接了麦克风的时钟线、哪一根接了功放的数据线、哪一根控制屏幕背光,这些完全由开发板厂商决定。小智源码在编译时会根据一个板级配置把这些映射关系写死到固件里。你换一块板子,如果这个映射关系变了,固件就会去操作错误的引脚,轻则没声音,重则短路或者反复重启。我见过最离谱的一个案例是有人把一块板子的功放使能引脚配置成了另一块板子的屏幕复位引脚,结果一上电屏幕就一直处于复位状态,而功放被反复拉高拉低,喇叭里发出“哒哒哒”的噪声。这种问题从代码逻辑上根本看不出来,只有对着原理图一根线一根线核对才能发现。
2.2 音频链路是最容易出问题的地方。小智源码的核心功能是语音交互,所以音频链路是重中之重。一条完整的音频链路通常包括麦克风、音频编解码芯片、主控芯片、功放、扬声器,这里面每一个环节都可能有差异。先说麦克风,有的开发板用的是模拟麦克风直接接到ESP32的ADC引脚,有的用的是数字麦克风走I2S接口,这两种方案在源码里的初始化方式完全不同。模拟麦克风需要配置ADC的采样率和增益,数字麦克风需要配置I2S的时钟和通道。如果你拿到的板子用的是数字麦克风但源码里配置的是模拟麦克风,那录出来的就是一片噪声。再说音频编解码芯片,小智源码常见的搭配是ES8311、ES7210这类芯片,它们负责把麦克风的模拟信号转成数字信号或者把数字信号转成模拟信号送给功放,这些芯片通常通过I2C总线配置寄存器、通过I2S总线传输音频数据。不同芯片的寄存器地址、初始化序列、采样率支持范围都不一样,哪怕都是ES8311,如果I2C地址被硬件设计成了不同的值,源码里也得跟着改。功放部分也一样,有的板子用的是NS4150这类模拟功放只需要一个使能引脚,有的用的是I2S数字功放比如MAX98357那就需要额外的I2S通道,功放的使能引脚如果是低电平有效还是高电平有效也会影响源码里的控制逻辑。
2.3 屏幕、按键、存储的差异同样致命。除了音频,屏幕也是换板子时的高频问题点。小智源码支持多种屏幕,有SPI接口的、有RGB接口的、有QSPI接口的,不同接口的初始化代码完全不同,分辨率、颜色格式、偏移量、镜像方向这些参数只要有一个不对,屏幕就会花屏、白屏或者显示错位。按键看起来简单,但按键的引脚编号、按下时的电平状态、有没有外部上拉电阻,这些都会影响源码里的按键扫描逻辑。我遇到过一块板子按键按下时是低电平但源码里默认配置成了高电平触发,结果按键一直被认为是按下的状态,设备一开机就进入配网模式。存储方面,ESP32通常外挂一块Flash或者PSRAM,Flash的大小和分区表直接相关,如果源码里配置的分区表是针对8MB Flash的而你板子上只有4MB,那烧录的时候就会报错或者烧进去之后运行到一半发现空间不够。PSRAM的型号和时序也会影响内存分配,如果源码里启用了PSRAM但板子上没有,启动阶段就会直接失败。
3. 换板子适配的完整流程,从原理图到能跑。3.1 第一步,拿到原理图核对每一个外设。换板子之后第一件事不是改代码而是找原理图,没有原理图后面所有工作都是盲猜。原理图里要重点看几个东西:主控芯片的型号和封装、音频编解码芯片的型号和I2C地址、麦克风的类型和接口、功放的型号和使能方式、屏幕的接口和分辨率、按键的引脚和电平、Flash和PSRAM的型号和容量。我一般会把这些信息整理成一张表方便和源码里的配置逐项对比。这张表做完之后你基本就能判断出适配的工作量有多大:如果只是功放使能引脚变了,那改一个宏定义就行;如果音频编解码芯片换了,那可能要重写整个音频初始化流程。
3.2 第二步,找到源码里的板级配置文件。小智源码通常会把板级相关的配置放在一个单独的文件或者目录里,比如board_config.h、bsp.c、config.h之类的。你要做的就是找到这个文件然后对照上面的表格逐项修改。常见的配置项包括引脚定义(AUDIO_I2S_GPIO_BCLK、AUDIO_I2S_GPIO_WS、AUDIO_I2S_GPIO_DOUT、AUDIO_I2S_GPIO_DIN、AUDIO_CODEC_I2C_SDA、AUDIO_CODEC_I2C_SCL、PA_ENABLE_GPIO等)、芯片型号(AUDIO_CODEC_ES8311、AUDIO_CODEC_ES7210等)、采样率(AUDIO_SAMPLE_RATE等)、屏幕参数(DISPLAY_WIDTH、DISPLAY_HEIGHT、DISPLAY_OFFSET_X、DISPLAY_OFFSET_Y、DISPLAY_MIRROR_X、DISPLAY_MIRROR_Y等)、按键参数(BUTTON_GPIO、BUTTON_ACTIVE_LEVEL)、存储参数(FLASH_SIZE、PSRAM_ENABLE)。改这些配置的时候一定要改一项、编译一次、烧录一次、看一次日志,不要一次性全改完再烧,因为一旦出问题你很难判断是哪一项改错了。我自己的习惯是先把引脚定义改完确认能启动,再改音频芯片配置确认能录音放音,最后改屏幕和按键确认交互正常。
3.3 第三步,处理音频编解码芯片的差异。如果新板子用的音频编解码芯片和原板子不一样,那工作量会大很多。你需要做几件事:第一确认芯片的I2C地址,ES8311的默认地址通常是0x18,ES7210通常是0x40,但有些板子会因为硬件设计不同而改变地址,地址不对I2C通信就会失败芯片根本初始化不了。第二确认芯片的初始化序列,不同芯片的寄存器配置完全不同,你需要找到新芯片的数据手册按照它的要求配置采样率、增益、输入输出通道、电源管理这些参数,有些芯片还需要额外的复位引脚或者时钟引脚这些也要在源码里加上。第三确认I2S的时钟配置,不同芯片对MCLK、BCLK、WS的频率要求可能不同,比如ES8311通常需要MCLK是采样率的256倍而有些芯片可能只需要128倍,如果时钟配置不对音频会变调或者完全没声音。第四确认数据格式,I2S的数据格式有标准I2S、左对齐、右对齐、DSP模式等,不同芯片支持的模式不同,如果源码里配置的是标准I2S但芯片只支持左对齐,那录出来的声音就是乱的。
3.4 第四步,处理屏幕和按键的差异。屏幕适配的核心是找到正确的初始化序列和参数,SPI屏幕通常需要配置时钟频率、颜色格式、偏移量、镜像方向,RGB屏幕还需要配置时序参数比如前后沿、同步脉冲宽度,这些参数如果不对屏幕就会花屏或者偏移。我一般会先用屏幕厂商提供的示例代码确认屏幕能正常显示,然后再把参数移植到小智源码里,这样可以把屏幕本身的问题和源码的问题分开避免同时排查两个方向。按键适配相对简单但也要注意几个细节:按键引脚有没有内部上拉、按下时是低电平还是高电平、有没有硬件消抖电路,如果源码里配置的触发电平和实际相反,按键就会一直处于“按下”状态,如果硬件没有消抖电路源码里就需要加软件消抖否则按键会误触发。
3.5 第五步,处理存储和分区表的差异。Flash容量变了分区表就要跟着改。小智源码通常会在partitions.csv文件里定义分区包括nvs、phy_init、factory、ota_0、ota_1等。如果Flash从8MB变成4MB,你可能需要缩小factory分区或者去掉ota_1分区。PSRAM的差异也要注意,如果原板子有PSRAM而新板子没有,源码里启用PSRAM的配置就要关掉否则启动时会报错;如果新板子有PSRAM但原板子没有,你可以启用PSRAM来获得更多内存但要注意PSRAM的型号和时序配置。
4. 实操现场,一次完整的换板适配记录。4.1 硬件准备和初步检查。我手上有一块原板子主控是ESP32-S3,音频芯片是ES8311,屏幕是1.28寸SPI圆屏,Flash是8MB带PSRAM。新板子也是ESP32-S3,但音频芯片换成了ES7210加ES8311的组合,屏幕换成了1.69寸QSPI方屏,Flash是4MB没有PSRAM。先做硬件检查,用万用表确认新板子的供电正常,用示波器看晶振有没有起振,用I2C扫描工具确认音频芯片的地址。这一步很重要,因为如果硬件本身有问题后面改代码都是白费功夫。I2C扫描我一般用一段代码烧进去之后看串口输出,扫描结果发现0x18和0x40都有设备,说明ES8311和ES7210都在线,这一步确认之后心里就有底了。
4.2 修改板级配置。接下来找到源码里的板级配置文件我的是board_config.h,对照原理图把引脚定义全部改掉。这里要注意ES7210是四通道麦克风采集芯片,它需要额外的I2S通道来传输麦克风数据,所以I2S的配置要比原来复杂。原来的配置是BCLK接GPIO5、WS接GPIO6、DOUT接GPIO7、DIN接GPIO8、I2C的SDA接GPIO1、SCL接GPIO2、功放使能接GPIO10。新板子的配置改成BCLK接GPIO14、WS接GPIO15、DOUT接GPIO16、DIN接GPIO17、I2C保持不变、功放使能改成GPIO12,同时把音频芯片的宏定义从AUDIO_CODEC_ES8311改成AUDIO_CODEC_ES7210_ES8311表示同时使用两颗芯片。
4.3 处理ES7210的初始化。ES7210的初始化比ES8311复杂因为它有四个麦克风通道需要配置每个通道的增益和使能状态。我参考了芯片数据手册和厂商提供的示例代码写了一个初始化函数,流程是:先复位芯片(写0x00寄存器为0xFF延时10ms再写0x41延时10ms),然后配置时钟(0x01写0x3F、0x02写0x00),再配置麦克风通道(0x03到0x06都写0x00),再配置增益(0x07到0x0A都写0x20),最后使能芯片(0x00写0x41)。这里面的寄存器值是根据数据手册和实际测试调出来的,不同批次的芯片可能需要微调,我一般会先用默认值跑一遍,如果录音声音太小或者有噪声再调整增益寄存器。
4.4 修改分区表和PSRAM配置。Flash从8MB变成4MB分区表必须改。原来的分区表包含nvs、phy_init、factory(0x300000大小)、ota_0(0x300000)、ota_1(0x300000),新的分区表去掉ota_1并把factory和ota_0都缩小到0x1C0000。PSRAM配置也要关掉,在sdkconfig里找到CONFIG_SPIRAM把它设为n。如果源码里有代码依赖PSRAM分配内存比如heap_caps_malloc(size, MALLOC_CAP_SPIRAM),那就要改成malloc(size)否则运行时会返回空指针。
4.5 屏幕适配和按键调整。新屏幕是QSPI接口的1.69寸方屏分辨率240x280,原来的SPI屏幕驱动完全不能用需要换成QSPI驱动。我找到了屏幕厂商提供的QSPI示例代码把初始化序列和参数移植过来,关键参数包括DISPLAY_WIDTH 240、DISPLAY_HEIGHT 280、DISPLAY_OFFSET_X 0、DISPLAY_OFFSET_Y 20、DISPLAY_MIRROR_X false、DISPLAY_MIRROR_Y false、DISPLAY_SWAP_XY false。DISPLAY_OFFSET_Y这个参数特别重要,因为方屏的可见区域和显存区域可能不一致,偏移量不对就会显示错位。我一开始没设偏移量结果屏幕上方有20像素的白边下面少了20像素的内容,后来查了屏幕数据手册发现显存是240x320可见区域是240x280所以Y偏移要设成20。按键方面新板子的按键是低电平触发而且没有外部上拉,所以源码里要启用内部上拉并把触发电平改成低电平,BUTTON_GPIO设GPIO_NUM_0、BUTTON_ACTIVE_LEVEL设0、gpio_set_pull_mode设为GPIO_PULLUP_ONLY。
4.6 编译、烧录、看日志。所有配置改完之后编译烧录。第一次烧录后串口日志显示I2C通信正常,ES7210和ES8311都初始化成功但录音没有声音,看日志发现I2S读取超时说明麦克风数据没有进来。排查过程先用示波器看I2S的BCLK和WS有没有波形,发现波形正常,再看DIN引脚发现没有数据,怀疑是ES7210的通道配置不对,检查寄存器发现通道使能位没打开,把0x03到0x06寄存器改成0x01之后录音正常了。第二次测试发现放音有声音但音量很小,检查功放使能引脚发现GPIO12被配置成了低电平有效但实际功放是高电平使能,把PA_ENABLE_GPIO的控制逻辑反过来之后音量正常了。第三次测试发现屏幕显示正常但按键没反应,用万用表量按键引脚发现按下时电压从3.3V变成0V说明是低电平触发,但源码里配置的是高电平触发,改成低电平之后按键正常。整个适配过程花了大概两天时间,其中大部分时间是在排查音频和屏幕的问题,如果一开始就有完整的原理图和芯片数据手册时间可以缩短到半天。
5. 常见问题速查表和避坑经验。5.1 启动阶段就失败怎么办。启动失败通常有几个原因:Flash分区表不匹配、PSRAM配置错误、晶振频率不对、电源供电不足。排查顺序是先看串口日志,如果日志停在boot阶段多半是Flash或PSRAM的问题,如果日志能走到app_main但马上重启多半是外设初始化失败导致的看门狗复位。我整理了一个速查表:串口无输出是晶振未起振或供电不足,用示波器看晶振、万用表量电压;日志停在boot是Flash分区表错误,检查partitions.csv和Flash容量;日志停在PSRAM是PSRAM配置错误,关闭PSRAM或检查型号时序;反复重启是外设初始化失败看门狗,逐项注释外设初始化;I2C扫描不到设备是引脚错误或上拉缺失,检查引脚定义加外部上拉。
5.2 音频没声音怎么排查。音频问题是最常见的,排查思路是先确认I2C能通信再确认I2S有时钟再确认数据引脚有波形最后确认功放使能正确。具体步骤:用I2C扫描工具确认音频芯片地址在线;用示波器看I2S的BCLK和WS是否有波形、频率是否和采样率匹配;用示波器看DIN或DOUT是否有数据波形;检查功放使能引脚的电平是否正确;检查音频芯片的寄存器配置特别是通道使能和增益。我遇到过最隐蔽的一个问题是ES8311的MCLK配置成了采样率的128倍但芯片要求256倍结果音频变调,后来把MCLK倍数改成256之后正常了。
5.3 屏幕花屏或偏移怎么处理。屏幕问题通常是参数不对,先确认分辨率、颜色格式、偏移量、镜像方向这四个参数。如果屏幕能亮但花屏多半是颜色格式不对比如RGB565和RGB888搞混了;如果屏幕显示内容偏移多半是偏移量没设对;如果屏幕内容镜像了改镜像参数就行。QSPI屏幕还要注意命令格式和地址位数,不同厂商的QSPI屏幕初始化序列可能不同。我一般会先用厂商的示例代码确认屏幕能正常显示再把参数移植到小智源码里。
5.4 按键误触发或没反应。按键问题通常是电平配置反了或者没有消抖,先确认按下时的电平状态再确认源码里的触发电平,如果没有外部消抖电路源码里要加20ms左右的软件消抖。还有一个容易忽略的点是有些板子的按键和启动模式引脚复用,比如GPIO0既是按键又是下载模式选择,如果按键按下时正好在上电阶段芯片可能进入下载模式而不是正常运行,这种情况需要在硬件上避免或者源码里加延时判断。
5.5 我踩过的几个坑。第一个坑是忽略电源时序,有些音频芯片和功放对供电时序有要求比如先给编解码芯片供电再给功放供电,如果时序不对芯片可能初始化失败或者有噪声,我后来在源码里加了延时确保供电稳定后再初始化外设。第二个坑是I2C地址冲突,新板子上ES8311和ES7210的地址分别是0x18和0x40但源码里默认只初始化了一个地址,后来我把两个芯片的初始化分开分别用不同的I2C地址问题解决。第三个坑是Flash分区表没对齐,分区表的偏移量必须是0x1000的整数倍否则烧录会报错,我一开始没注意改完之后编译能过但烧录失败后来把偏移量对齐之后正常。第四个坑是PSRAM和Flash共用引脚,有些ESP32-S3开发板的PSRAM和Flash共用SPI引脚,如果PSRAM配置不对Flash也会受影响,这种情况要仔细看原理图确认引脚复用关系。
6. 自己画板子时怎么提前避免适配问题。如果你打算自己画一块跑小智源码的板子,那适配工作其实可以在设计阶段就避免。我的建议是尽量参考官方推荐的硬件设计尤其是音频链路和电源部分。音频芯片的选型尽量和源码默认支持的一致比如ES8311加ES7210的组合,这样源码里已经有现成的驱动不需要自己写。引脚分配要提前规划好,把I2S、I2C、SPI、QSPI这些总线的引脚固定下来避免和Strapping引脚、USB引脚冲突,ESP32-S3的Strapping引脚在上电时有特殊功能如果被外设拉高或拉低可能导致芯片启动模式错误。电源部分要给音频芯片和功放留足够的余量,尤其是功放在大音量时的瞬时电流可能很大,如果电源设计不好会导致芯片复位或者音频失真,我一般会在功放电源引脚旁边放一个大电容比如1000uF来吸收瞬时电流。最后画完板子之后一定要先做一块样板把所有外设都测试一遍确认硬件没问题之后再批量生产,我见过太多人直接批量生产结果发现音频芯片地址错了或者屏幕接口不对整批板子都报废。
7. 适配工作的价值,从“换板子”到“理解系统”。回到最开始那个问题,同一套小智源码换块ESP32开发板为什么还要重新适配?因为小智源码不是一个纯软件程序,它是一个软硬件深度耦合的嵌入式系统,芯片型号相同只是最基础的条件,真正决定能不能跑起来的是外围器件的型号、引脚、总线地址、供电时序、初始化序列这些细节。适配的过程其实是一次很好的学习机会,你会被迫去看原理图、查数据手册、用示波器量波形、读芯片寄存器,这些技能在纯软件开发里是学不到的但恰恰是嵌入式开发的核心能力。我自己的经验是每适配一块新板子,对音频链路、I2S协议、I2C通信、电源管理的理解都会加深一层。如果你正在做类似的项目,我的建议是不要怕改代码但一定要有方法:先核对原理图再改板级配置,然后逐项测试,最后整理成文档。这样下次再换板子的时候你就有了一套可复用的流程而不是每次都从零开始猜。

本文来源:http://www.lpqz.cn/news/106486
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
1. Starting with a 'crash'—why does swapping a board make it stop working? A while ago, a friend who works on smart voice hardware came to me and said that he had moved a perfectly working set of Xiaozhi source code from one ESP32-S3 development board to another ESP32-S3 development board. The compilation passed and the flashing succeeded, but as soon as he powered it on, it got stuck in the boot stage; the serial log would print halfway and then reboot, and occasionally there would be completely silent audio, a garbled screen, and all the buttons behaving erratically. He repeatedly confirmed that the chip model was the same, the Flash size was the same, and even the boards looked almost identical—but it just wouldn't run. The first thing he asked me was 'Why does the same set of source code need to be re-adapted when I swap boards?' This question is actually very typical. Many people who are new to ESP32 voice interaction projects subconsciously equate 'same chip model' with 'fully compatible hardware,' and 'the source code compiles' with 'the firmware runs.' But the reality is that projects like Xiaozhi source code have very deep dependencies on hardware peripherals. It's not a purely software-logic program; it's an embedded system that ties together the chip, audio codec, microphone array, power amplifier, screen, buttons, storage, and power management all in one. Swap one development board—even if the main chip is exactly the same—and as long as there is any difference in the model of the peripheral components, the connection pins, the power-on timing, or the bus addresses, the whole system can go from 'running' to 'not running.' I intend to explain this thoroughly. Starting from the architectural characteristics of Xiaozhi source code, this article will break down the real reasons behind 'why swapping boards requires re-adaptation,' and then provide a reproducible adaptation process, parameter calculation methods, a common-problem troubleshooting table, and pitfalls I've encountered myself. It's suitable as a reference for those working on ESP32 voice projects, planning to swap boards, or intending to design their own board. Even if you've just gotten an ESP32-S3 development board and haven't gotten the first voice demo running yet, the ideas here can help you avoid many detours.
2. What hardware details does Xiaozhi source code actually depend on? 2.1 It's not 'one program' but an entire hardware abstraction layer. Many people, the first time they look at the directory structure of Xiaozhi source code, think it's just an ordinary ESP-IDF project, with a main, components, and CMakeLists.txt. But once you actually run it, you'll find it's divided internally into several layers: at the top is the voice interaction logic, in the middle is audio processing and service communication, and at the bottom is the board support package, commonly called the Board layer. This Board layer is the key that determines 'whether swapping boards requires code changes.' What the Board layer does, plainly speaking, is translate the chip's 'generic pins' into the 'actual peripherals on this board.' For example, the chip's GPIO numbers are fixed, but which GPIO connects to the microphone's clock line, which connects to the amplifier's data line, and which controls the screen backlight are entirely decided by the board manufacturer. When compiling, Xiaozhi source code hard-codes these mapping relationships into the firmware based on a board-level configuration. If you swap a board and this mapping changes, the firmware will operate the wrong pins—at best no sound, at worst a short circuit or repeated reboots. The most outrageous case I've seen was someone configuring one board's amplifier enable pin as another board's screen reset pin, with the result that on power-up the screen stayed permanently in reset while the amplifier was repeatedly pulled high and low, producing a 'click-click-click' noise from the speaker. This kind of problem is completely invisible from the code logic; you can only find it by checking the schematic line by line.
2.2 The audio chain is the most problem-prone area. The core function of Xiaozhi source code is voice interaction, so the audio chain is of paramount importance. A complete audio chain typically includes the microphone, audio codec chip, main control chip, power amplifier, and speaker, and every link in it can have differences. Starting with the microphone: some boards use an analog microphone connected directly to the ESP32's ADC pin, while others use a digital microphone over the I2S interface; these two approaches are initialized completely differently in the source code. An analog microphone requires configuring the ADC's sample rate and gain, while a digital microphone requires configuring the I2S clock and channels. If your board uses a digital microphone but the source code is configured for an analog microphone, what you record will be nothing but noise. Moving on to the audio codec chip: common pairings in Xiaozhi source code are chips like the ES8311 and ES7210, which convert the microphone's analog signal to digital, or convert digital signals to analog for the amplifier. These chips are typically configured via registers over the I2C bus and transfer audio data over the I2S bus. Different chips have different register addresses, initialization sequences, and supported sample-rate ranges; even if they're both ES8311, if the I2C address has been designed to a different value in hardware, the source code must be changed accordingly. The same goes for the amplifier: some boards use an analog amplifier like the NS4150 that only needs a single enable pin, while others use an I2S digital amplifier such as the MAX98357, which requires an additional I2S channel. Whether the amplifier's enable pin is active-low or active-high also affects the control logic in the source code.
2.3 Differences in screens, buttons, and storage can be just as fatal. Besides audio, the screen is another frequent trouble spot when swapping boards. Xiaozhi source code supports multiple types of screens—SPI, RGB, and QSPI interfaces—and the initialization code for different interfaces is completely different. If even one of the parameters for resolution, color format, offset, or mirror direction is wrong, the screen will show a garbled image, a blank white screen, or a misaligned display. Buttons may look simple, but the button's pin number, the logic level when pressed, and whether there is an external pull-up resistor all affect the button-scanning logic in the source code. I once encountered a board where the button was active-low when pressed, but the source code was configured by default for active-high triggering; as a result, the button was perpetually considered pressed, and the device entered network-configuration mode the moment it powered on. On the storage side, the ESP32 typically has an external Flash or PSRAM. Flash size is directly related to the partition table—if the partition table configured in the source code is for 8MB Flash but your board only has 4MB, you'll get an error during flashing, or after flashing it will run halfway and then discover there's not enough space. The PSRAM model and timing also affect memory allocation; if the source code enables PSRAM but the board doesn't have any, the boot stage will fail outright.
3. The complete process of adapting to a new board, from schematic to running. 3.1 Step one: get the schematic and verify every peripheral. The first thing to do after swapping boards is not to change code—it's to find the schematic. Without a schematic, all subsequent work is guesswork. There are several key things to look at in the schematic: the main chip's model and package, the audio codec chip's model and I2C address, the microphone's type and interface, the amplifier's model and enable method, the screen's interface and resolution, the buttons' pins and levels, and the Flash and PSRAM models and capacities. I usually organize this information into a table to make it easy to compare item by item with the configuration in the source code. Once you've finished this table, you can basically gauge how much adaptation work is involved: if only the amplifier enable pin changed, you just change one macro definition; if the audio codec chip changed, you may have to rewrite the entire audio initialization flow.
3.2 Step two: locate the board-level configuration file in the source code. Xiaozhi source code usually places board-related configuration in a separate file or directory, such as board_config.h, bsp.c, config.h, or the like. What you need to do is find this file and modify it item by item against the table above. Common configuration items include pin definitions (AUDIO_I2S_GPIO_BCLK, AUDIO_I2S_GPIO_WS, AUDIO_I2S_GPIO_DOUT, AUDIO_I2S_GPIO_DIN, AUDIO_CODEC_I2C_SDA, AUDIO_CODEC_I2C_SCL, PA_ENABLE_GPIO, etc.), chip models (AUDIO_CODEC_ES8311, AUDIO_CODEC_ES7210, etc.), sample rate (AUDIO_SAMPLE_RATE, etc.), screen parameters (DISPLAY_WIDTH, DISPLAY_HEIGHT, DISPLAY_OFFSET_X, DISPLAY_OFFSET_Y, DISPLAY_MIRROR_X, DISPLAY_MIRROR_Y, etc.), button parameters (BUTTON_GPIO, BUTTON_ACTIVE_LEVEL), and storage parameters (FLASH_SIZE, PSRAM_ENABLE). When changing these configurations, you must change one item, compile once, flash once, and check the log once—don't change everything at once and then flash, because if something goes wrong, you'll have a hard time figuring out which item was wrong. My own habit is to first finish the pin definitions and confirm it boots, then change the audio chip configuration and confirm recording and playback work, and finally change the screen and buttons to confirm the interaction works properly.
3.3 Step three: handle differences in the audio codec chip. If the new board uses a different audio codec chip from the original, the workload increases significantly. You need to do several things: First, confirm the chip's I2C address. The default address of the ES8311 is usually 0x18, and the ES7210 is usually 0x40, but some boards change the address due to different hardware designs—if the address is wrong, I2C communication fails and the chip can't be initialized at all. Second, confirm the chip's initialization sequence. Different chips have completely different register configurations; you need to find the new chip's datasheet and configure parameters such as sample rate, gain, input/output channels, and power management according to its requirements. Some chips also need extra reset pins or clock pins, which must be added to the source code as well. Third, confirm the I2S clock configuration. Different chips may have different frequency requirements for MCLK, BCLK, and WS—for example, the ES8311 typically requires MCLK to be 256 times the sample rate, while some chips may only need 128 times. If the clock configuration is wrong, the audio will change pitch or be completely silent. Fourth, confirm the data format. I2S data formats include standard I2S, left-justified, right-justified, DSP mode, and so on; different chips support different modes. If the source code is configured for standard I2S but the chip only supports left-justified, the recorded sound will be garbled.
3.4 Step four: handle differences in the screen and buttons. The core of screen adaptation is finding the correct initialization sequence and parameters. SPI screens typically require configuring the clock frequency, color format, offset, and mirror direction; RGB screens additionally require timing parameters such as front and back porches and sync pulse width. If these parameters are wrong, the screen will show a garbled image or be misaligned. I generally first use the sample code provided by the screen manufacturer to confirm that the screen displays properly, and then port the parameters into Xiaozhi source code. This way you can separate problems with the screen itself from problems with the source code, avoiding having to troubleshoot two directions at once. Button adaptation is relatively simple, but a few details still matter: whether the button pin has an internal pull-up, whether it's active-low or active-high when pressed, and whether there's a hardware debounce circuit. If the trigger level configured in the source code is the opposite of the actual one, the button will stay perpetually in the 'pressed' state; if the hardware has no debounce circuit, you need to add software debouncing in the source code, or the button will trigger falsely.
3.5 Step five: handle differences in storage and the partition table. When the Flash capacity changes, the partition table must change with it. Xiaozhi source code usually defines partitions in the partitions.csv file, including nvs, phy_init, factory, ota_0, ota_1, and so on. If Flash changes from 8MB to 4MB, you may need to shrink the factory partition or remove the ota_1 partition. PSRAM differences also need attention: if the original board had PSRAM but the new one doesn't, you need to turn off the configuration that enables PSRAM in the source code, or you'll get an error at boot; if the new board has PSRAM but the original didn't, you can enable PSRAM to gain more memory, but pay attention to the PSRAM model and timing configuration.
4. Hands-on: a complete board-swap adaptation record. 4.1 Hardware preparation and initial checks. I have an original board at hand whose main chip is an ESP32-S3, audio chip is an ES8311, screen is a 1.28-inch SPI round display, and Flash is 8MB with PSRAM. The new board is also an ESP32-S3, but the audio chip has been swapped for an ES7210-plus-ES8311 combination, the screen for a 1.69-inch QSPI square display, and the Flash is 4MB with no PSRAM. First, do a hardware check: use a multimeter to confirm the new board's power supply is normal, use an oscilloscope to see whether the crystal oscillator is starting up, and use an I2C scanner tool to confirm the audio chips' addresses. This step is important, because if there's a problem with the hardware itself, all the code changes afterward are wasted effort. For the I2C scan I usually flash a piece of code and then look at the serial output. The scan showed devices at both 0x18 and 0x40, indicating that both the ES8311 and ES7210 were online. Once this step was confirmed, I felt confident.
4.2 Modifying the board-level configuration. Next, find the board-level configuration file in the source code—mine was board_config.h—and change all the pin definitions against the schematic. Note here that the ES7210 is a four-channel microphone capture chip; it needs an extra I2S channel to transfer microphone data, so the I2S configuration is more complex than before. The original configuration was BCLK on GPIO5, WS on GPIO6, DOUT on GPIO7, DIN on GPIO8, I2C SDA on GPIO1, SCL on GPIO2, and amplifier enable on GPIO10. The new board's configuration changes to BCLK on GPIO14, WS on GPIO15, DOUT on GPIO16, DIN on GPIO17, I2C unchanged, and amplifier enable changed to GPIO12. At the same time, change the audio chip macro definition from AUDIO_CODEC_ES8311 to AUDIO_CODEC_ES7210_ES8311 to indicate that both chips are used together.
4.3 Handling ES7210 initialization. The ES7210 is more complex to initialize than the ES8311 because it has four microphone channels, and you need to configure the gain and enable state of each channel. I wrote an initialization function referencing the chip datasheet and the sample code provided by the manufacturer. The flow is: first reset the chip (write 0xFF to register 0x00, delay 10ms, then write 0x41, delay 10ms), then configure the clock (write 0x3F to 0x01, write 0x00 to 0x02), then configure the microphone channels (write 0x00 to 0x03 through 0x06), then configure the gain (write 0x20 to 0x07 through 0x0A), and finally enable the chip (write 0x41 to 0x00). The register values here were worked out from the datasheet and actual testing; chips from different batches may need slight adjustments. I generally run once with the default values first, and if the recording is too quiet or has noise, then I adjust the gain registers.
4.4 Modifying the partition table and PSRAM configuration. With Flash changing from 8MB to 4MB, the partition table must be changed. The original partition table contained nvs, phy_init, factory (0x300000 in size), ota_0 (0x300000), and ota_1 (0x300000). The new partition table removes ota_1 and shrinks both factory and ota_0 to 0x1C0000. The PSRAM configuration must also be turned off: find CONFIG_SPIRAM in sdkconfig and set it to n. If the source code has code that allocates memory from PSRAM, such as heap_caps_malloc(size, MALLOC_CAP_SPIRAM), you need to change it to malloc(size), or it will return a null pointer at runtime.
4.5 Screen adaptation and button adjustment. The new screen is a 1.69-inch QSPI square display with a resolution of 240x280. The original SPI screen driver was completely unusable and had to be replaced with a QSPI driver. I found the QSPI sample code provided by the screen manufacturer and ported over the initialization sequence and parameters. The key parameters include DISPLAY_WIDTH 240, DISPLAY_HEIGHT 280, DISPLAY_OFFSET_X 0, DISPLAY_OFFSET_Y 20, DISPLAY_MIRROR_X false, DISPLAY_MIRROR_Y false, and DISPLAY_SWAP_XY false. The DISPLAY_OFFSET_Y parameter is especially important, because a square screen's visible area may not match its framebuffer area—if the offset is wrong, the display will be misaligned. At first I didn't set the offset, and the result was a 20-pixel white border at the top of the screen with 20 pixels of content missing at the bottom. Later I checked the screen datasheet and found that the framebuffer is 240x320 while the visible area is 240x280, so the Y offset had to be set to 20. As for the buttons, the new board's button is active-low and has no external pull-up, so I had to enable the internal pull-up in the source code and change the trigger level to low: set BUTTON_GPIO to GPIO_NUM_0, BUTTON_ACTIVE_LEVEL to 0, and gpio_set_pull_mode to GPIO_PULLUP_ONLY.
4.6 Compile, flash, and read the logs. After all configurations were changed, I compiled and flashed. After the first flash, the serial log showed I2C communication was normal and both the ES7210 and ES8311 initialized successfully, but there was no sound in the recording. The log showed an I2S read timeout, indicating that microphone data wasn't coming in. The troubleshooting process: first I used an oscilloscope to check whether the I2S BCLK and WS had waveforms—they were normal. Then I looked at the DIN pin and found no data. Suspecting the ES7210 channel configuration was wrong, I checked the registers and found the channel-enable bits weren't turned on; after changing registers 0x03 through 0x06 to 0x01, the recording worked. The second test showed playback had sound but the volume was very low. Checking the amplifier enable pin, I found GPIO12 was configured as active-low, but the amplifier was actually active-high; after reversing the PA_ENABLE_GPIO control logic, the volume was normal. The third test showed the screen displayed fine but the buttons didn't respond. Measuring the button pin with a multimeter, I found the voltage dropped from 3.3V to 0V when pressed, indicating active-low triggering, but the source code was configured for active-high; after changing it to active-low, the buttons worked. The whole adaptation took about two days, most of it spent troubleshooting the audio and screen issues. If I'd had the complete schematic and chip datasheets from the start, the time could have been cut to half a day.
5. Common-problem quick-reference table and pitfall-avoidance tips. 5.1 What to do if it fails at the boot stage. Boot failures usually have a few causes: a mismatched Flash partition table, incorrect PSRAM configuration, the wrong crystal frequency, or insufficient power supply. The troubleshooting order is to look at the serial log first. If the log stops at the boot stage, it's most likely a Flash or PSRAM problem; if the log reaches app_main but immediately reboots, it's most likely a watchdog reset caused by a peripheral initialization failure. I've put together a quick-reference table: no serial output means the crystal hasn't started oscillating or the power supply is insufficient—use an oscilloscope to check the crystal and a multimeter to measure the voltage; log stuck at boot means a Flash partition table error—check partitions.csv and the Flash capacity; log stuck at PSRAM means a PSRAM configuration error—disable PSRAM or check the model and timing; repeated reboots mean a peripheral initialization failure triggering the watchdog—comment out peripheral initializations one by one; no devices found in the I2C scan means wrong pins or a missing pull-up—check the pin definitions and add external pull-ups.
5.2 How to troubleshoot when there's no audio. Audio problems are the most common. The troubleshooting approach is: first confirm I2C communication works, then confirm I2S has a clock, then confirm the data pin has waveforms, and finally confirm the amplifier enable is correct. Specific steps: use an I2C scanner tool to confirm the audio chip's address is online; use an oscilloscope to check whether the I2S BCLK and WS have waveforms and whether their frequency matches the sample rate; use an oscilloscope to check whether DIN or DOUT has data waveforms; check whether the amplifier enable pin's level is correct; check the audio chip's register configuration, especially the channel enable and gain. The most subtle problem I ever encountered was an ES8311 whose MCLK was configured to 128 times the sample rate while the chip required 256 times, resulting in a pitch change; after changing the MCLK multiplier to 256, it was fine.
5.3 How to handle a garbled or misaligned screen. Screen problems are usually caused by wrong parameters. First confirm the four parameters: resolution, color format, offset, and mirror direction. If the screen lights up but is garbled, it's most likely the wrong color format—for example, mixing up RGB565 and RGB888. If the displayed content is offset, it's most likely that the offset wasn't set correctly. If the screen content is mirrored, just change the mirror parameter. QSPI screens also require attention to the command format and address bit width; different manufacturers' QSPI screens may have different initialization sequences. I generally first use the manufacturer's sample code to confirm the screen displays properly, and then port the parameters into Xiaozhi source code.
5.4 Buttons triggering falsely or not responding. Button problems are usually caused by a reversed level configuration or a lack of debouncing. First confirm the level state when pressed, then confirm the trigger level in the source code. If there's no external debounce circuit, add about 20ms of software debouncing in the source code. Another easily overlooked point is that on some boards the button shares a pin with the boot-mode selection—for example, GPIO0 serves as both a button and the download-mode selector. If the button happens to be pressed during the power-on phase, the chip may enter download mode instead of running normally. This needs to be avoided in hardware or handled in the source code by adding a delay check.
5.5 A few pitfalls I've fallen into. The first pitfall is ignoring power-on timing. Some audio chips and amplifiers have requirements for the power supply sequence—for example, power the codec chip first, then the amplifier. If the timing is wrong, the chip may fail to initialize or produce noise. I later added delays in the source code to ensure the power supply was stable before initializing peripherals. The second pitfall is an I2C address conflict. On the new board, the ES8311 and ES7210 had addresses of 0x18 and 0x40 respectively, but the source code by default initialized only one address. I later separated the initialization of the two chips, using different I2C addresses for each, which solved the problem. The third pitfall was a Flash partition table that wasn't aligned: the partition table offsets must be integer multiples of 0x1000, or flashing will report an error. I didn't notice this at first—after changing it, compilation passed but flashing failed; once I aligned the offsets, it was fine. The fourth pitfall was PSRAM and Flash sharing pins. On some ESP32-S3 development boards, PSRAM and Flash share SPI pins; if the PSRAM configuration is wrong, Flash is affected too. In this case, you need to study the schematic carefully to confirm the pin-multiplexing relationship.
6. How to avoid adaptation problems in advance when designing your own board. If you plan to design your own board to run Xiaozhi source code, the adaptation work can actually be avoided at the design stage. My advice is to follow the officially recommended hardware design as much as possible, especially for the audio chain and power supply sections. Choose an audio chip that matches what the source code supports by default—for example, the ES8311-plus-ES7210 combination—so the source code already has ready-made drivers and you don't have to write your own. Plan the pin assignment in advance: fix the pins for the I2S, I2C, SPI, and QSPI buses to avoid conflicts with the strapping pins and USB pins. The ESP32-S3's strapping pins have special functions at power-on, and if they're pulled high or low by a peripheral, the chip may boot into the wrong mode. For the power supply, leave enough headroom for the audio chip and amplifier. In particular, the amplifier's instantaneous current at high volume can be quite large; if the power supply is poorly designed, it can cause chip resets or audio distortion. I usually place a large capacitor, say 1000uF, next to the amplifier's power pin to absorb transient current. Finally, after finishing the board design, always build a prototype first and test all peripherals once to confirm the hardware is sound before going into mass production. I've seen too many people go straight to mass production only to discover the audio chip address was wrong or the screen interface was wrong, and the entire batch of boards was scrapped.
7. The value of adaptation work: from 'swapping boards' to 'understanding the system.' Returning to the original question—why does the same set of Xiaozhi source code need to be re-adapted when you swap to a different ESP32 development board? Because Xiaozhi source code isn't a pure software program; it's an embedded system where software and hardware are deeply coupled. Having the same chip model is only the most basic prerequisite; what truly determines whether it runs are the details—the models, pins, bus addresses, power-on timing, and initialization sequences of the peripheral components. The adaptation process is actually a great learning opportunity. You'll be forced to read schematics, consult datasheets, measure waveforms with an oscilloscope, and read chip registers—skills you can't learn in pure software development, yet they are precisely the core competencies of embedded development. In my own experience, every time I adapt a new board, my understanding of the audio chain, the I2S protocol, I2C communication, and power management deepens another level. If you're working on a similar project, my advice is: don't be afraid to change code, but be sure to have a method—first verify the schematic, then change the board-level configuration, then test item by item, and finally organize everything into documentation. That way, the next time you swap boards, you'll have a reusable process rather than starting from scratch and guessing every time.