xiaozhi-esp32 板卡适配实战WDMomo ESP32-CGC 开发板的编译配置与硬件引脚解析【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本指南围绕开源仓库 xiaozhi-esp32 中 WDMomo ESP32-CGC 开发板适配目录 展开完整梳理从idf.py set-target到烧录编译的完整流程并深入 config.h、config.json 与 esp32_cgc_board.cc 源码逐引脚讲解音频、屏幕、按键与 MCP 灯控设备的底层实现。读完本文你将掌握如何为 ESP32 基础款小智 AI 开发板完成目标芯片切换、menuconfig 选型、屏幕驱动配置以及硬件资源裁剪的全过程。一、板卡背景与仓库支持情况ESP32-CGC 是开发者 wdmomo 设计的一款面向小智 AIXiaozhi Assistant的开源硬件开发板基于乐鑫 ESP32经典款非 S3/C3 等衍生型号设计。作者以开源方式发布了 V1、V2 两个版本的 PCB 工程并配套提供详细的硬件设计说明文档方便 DIY 玩家复刻与二次开发。在 xiaozhi-esp32 仓库中该板卡由以下四个文件构成完整的适配单元文件作用README.md编译配置步骤与作者资料入口config.h引脚定义、音频 I2S 模式、屏幕参数宏config.json构建系统识别的板卡元数据与默认 sdkconfigesp32_cgc_board.cc板级初始化SPI/LCD、按键、音频编解码器、MCP 灯控工具其中config.json声明了该板卡的厂家wdmomo、类型esp32-cgc、编译目标芯片target: esp32并在构建时自动追加CONFIG_LCD_ST7735_128X128y即默认启用 128×128 分辨率的 ST7735 屏幕配置。这一默认配置与 README 中选择屏幕类型为 ST7735 128*128的步骤相互印证说明该板卡的标准出货屏幕就是 1.8 英寸左右的 ST7735 小屏。二、编译配置完整流程以下命令与 menuconfig 路径均继承自板卡官方 README并补充了必要说明。1. 配置编译目标为 ESP32idf.py set-target esp32ESP32-CGC 使用经典 ESP32 芯片因此必须将编译目标切换为esp32。该命令会重新生成sdkconfig并限定后续可选的板卡范围——只有depends on IDF_TARGET_ESP32的板卡才会出现在 Target Board 列表中见 main/Kconfig.projbuild 中BOARD_TYPE_WDMOMO_CGC的声明。2. 打开 menuconfig 图形配置界面idf.py menuconfigmenuconfig 是 ESP-IDF 的 Kconfig 图形化配置工具xiaozhi-esp32 的所有板卡、外设、唤醒词、显示样式等选项都聚合在Xiaozhi Assistant菜单下定义于 main/Kconfig.projbuild。3. 选择目标板卡在 menuconfig 中依次进入Xiaozhi Assistant - Target Board - WDMomo ESP32-CGC对应 Kconfig 中的BOARD_TYPE_WDMOMO_CGCbool 项depends on IDF_TARGET_ESP32。从源码结构看同属 wdmomo 系列还有一款 ESP32-CGC-144对应BOARD_TYPE_WDMOMO_CGC_144选板时注意区分标准版与 144 版本。4. 选择屏幕类型Xiaozhi Assistant - LCD Type - ST7735, 分辨率128*128LCD Type子菜单由DISPLAY_LCD_TYPEchoice 定义可选项非常丰富。对于 ESP32-CGCconfig.h 中已经为每一种屏幕宏预置了完整的显示参数宽高、镜像、XY 交换、颜色反转、偏移量、SPI 模式选择后编译系统会通过宏开关自动套用对应参数。Kconfig 选项分辨率驱动芯片适用说明LCD_ST7735_128X128128×128ST7735ESP32-CGC 默认屏幕OFFSET_X2, OFFSET_Y3LCD_ST7735_128X160128×160ST7735竖屏小屏LCD_ST7789_240X320240×320ST7789IPS 大屏LCD_ST7789_240X240240×240ST7789方块屏LCD_ST7789_240X135240×135ST7789长条屏自动 XY 交换LCD_ST7796_320X480320×480ST7796IPS 大屏LCD_ILI9341_240X320240×320ILI9341经典大屏LCD_GC9A01_240X240240×240GC9A01圆形屏LCD_CUSTOM自定义自定义手动指定分辨率等参数5. 编译固件idf.py build编译完成后即可使用idf.py flash monitor烧录并查看串口日志。若替换了不同屏幕只需重新进入 menuconfig 切换LCD Type再编译无需改动任何源码。三、硬件资源与引脚分配源码解读1. 音频通路Simplex I2S 与 NoAudioCodecESP32-CGC 的音频采样率定义为输入 16 kHz、输出 24 kHzconfig.h这是小智协议的标准采样率。默认启用AUDIO_I2S_METHOD_SIMPLEX单工模式即麦克风与扬声器各自使用独立的 I2S 总线信号GPIOMIC WSGPIO_NUM_25MIC SCKGPIO_NUM_26MIC DINGPIO_NUM_32SPK DOUTGPIO_NUM_33SPK BCLKGPIO_NUM_14SPK LRCKGPIO_NUM_27若硬件设计需要改为 Duplex I2S 双工模式可注释掉 config.h 中的AUDIO_I2S_METHOD_SIMPLEX宏此时将改用AUDIO_I2S_GPIO_WS/BCLK/DIN/DOUTGPIO 4/5/6/7单总线方案。对应代码在 esp32_cgc_board.cc 的GetAudioCodec()中通过条件编译创建NoAudioCodecSimplex或NoAudioCodecDuplex实例——也就是说该板卡本身不携带硬件音频编解码芯片Codec音频以裸 I2S 数字信号输出由外部功放/咪头电路完成模拟转换。2. LCD 显示SPI 总线与三系列驱动芯片esp32_cgc_board.cc 的InitializeSpi()使用 SPI3 主机MOSI/SCLK 对应DISPLAY_MOSI_PIN(23)/DISPLAY_SCLK_PIN(18)最大传输尺寸按屏幕分辨率动态计算宽 × 高 × 2 字节 RGB565。屏幕控制引脚见 config.h信号GPIO背光GPIO_NUM_4SCLKGPIO_NUM_18MOSIGPIO_NUM_23CSGPIO_NUM_5DCGPIO_NUM_2RESETGPIO_NUM_NC未连接SPI 时钟20 MHzInitializeLcdDisplay()根据 Kconfig 宏自动选择驱动芯片默认走 ST7789 驱动esp_lcd_new_panel_st7789选中LCD_ILI9341_240X320时使用 ILI9341 驱动选中LCD_GC9A01_240X240时不仅使用 GC9A01 驱动还会加载一组专为 GC9107GC9A01 兼容型号准备的初始化命令序列gc9107_lcd_init_cmds包含 20 余条寄存器配置随后统一执行esp_lcd_panel_reset/init/invert_color/swap_xy/mirror完成显示初始化。3. 按键Boot 键与 AI 键按键GPIO功能BOOT 键GPIO_NUM_0设备启动阶段点击进入 Wi-Fi 配网模式正常运行中点击切换对话开关ToggleChatStateASR 键GPIO_NUM_13点击直接触发唤醒词你好小智WakeWordInvoke这一交互逻辑在 esp32_cgc_board.cc 的InitializeButtons()中通过Button回调实现Boot 键在kDeviceStateStarting状态下调用EnterWifiConfigMode()进入配网其余状态切换聊天ASR 键则模拟唤醒词触发语音识别流程。4. MCP 灯控让 AI 看见并控制真实世界config.h 中预留了LAMP_GPIOGPIO_NUM_12并在注释中说明这是一个 MCP 测试控制一盏灯。InitializeTools()中实例化的 LampController 会在 MCP Server 中注册三个工具self.lamp.get_state返回灯的开关状态 JSONself.lamp.turn_on拉高 GPIO 点亮灯具self.lamp.turn_off拉低 GPIO 熄灭灯具。这意味着通过 MCP 协议云端大模型可以直接调用这三个工具来控制 ESP32-CGC 上的真实硬件是典型的AI Agent 控制 IoT 设备落地演示。若不需要该功能可将LAMP_GPIO改为GPIO_NUM_NCLampController构造时会自动跳过 GPIO 初始化与工具注册见 lamp_controller.h 中对GPIO_NUM_NC的提前返回处理。四、常见问题与排查建议menuconfig 中找不到 WDMomo ESP32-CGC确认已执行idf.py set-target esp32该板卡仅支持IDF_TARGET_ESP32目标芯片为 S3/C3 时选项不会出现。屏幕花屏或颜色异常检查LCD Type是否与实物屏幕一致重点核对 config.h 中对应宏的DISPLAY_INVERT_COLOR、DISPLAY_MIRROR_X/Y、DISPLAY_SWAP_XY与DISPLAY_OFFSET_X/Y是否与屏幕模组匹配。更换屏幕后显示区域偏移ST7735 系列小屏常需微调DISPLAY_OFFSET_X/Y例如 128×128 默认偏移为 (2, 3)换屏后按模组数据手册重新设置。音频无声确认板卡采用的是 Simplex 双总线接线MIC 与 SPK 分离若硬件为单 I2S 总线共线需切换为 Duplex 模式并核对 GPIO 4/5/6/7 接线。灯控工具不生效确认LAMP_GPIO未被占用、灯具驱动电路为低电平关断/高电平导通并保证固件已启用 MCP Server 相关配置。五、总结WDMomo ESP32-CGC 是 xiaozhi-esp32 生态中一款典型的经典 ESP32 低成本开源开发板其适配代码完整展示了板级接入的通用范式config.json声明板卡元数据与默认屏幕、config.h集中管理引脚与显示宏、esp32_cgc_board.cc按职责拆分 SPI/LCD、按键、音频与 MCP 工具初始化。无论你是复刻该板卡的 DIY 玩家还是准备为自己的 ESP32 硬件接入 xiaozhi-esp32都可以参考 custom-board.md 与上述源码结构快速完成从画板到跑通语音助手的全流程。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 xiaozhi-esp32 板卡适配实战：WDMomo ESP32-CGC 开发板的编译配置与硬件引脚解析
xiaozhi-esp32 板卡适配实战WDMomo ESP32-CGC 开发板的编译配置与硬件引脚解析【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本指南围绕开源仓库 xiaozhi-esp32 中 WDMomo ESP32-CGC 开发板适配目录 展开完整梳理从idf.py set-target到烧录编译的完整流程并深入 config.h、config.json 与 esp32_cgc_board.cc 源码逐引脚讲解音频、屏幕、按键与 MCP 灯控设备的底层实现。读完本文你将掌握如何为 ESP32 基础款小智 AI 开发板完成目标芯片切换、menuconfig 选型、屏幕驱动配置以及硬件资源裁剪的全过程。一、板卡背景与仓库支持情况ESP32-CGC 是开发者 wdmomo 设计的一款面向小智 AIXiaozhi Assistant的开源硬件开发板基于乐鑫 ESP32经典款非 S3/C3 等衍生型号设计。作者以开源方式发布了 V1、V2 两个版本的 PCB 工程并配套提供详细的硬件设计说明文档方便 DIY 玩家复刻与二次开发。在 xiaozhi-esp32 仓库中该板卡由以下四个文件构成完整的适配单元文件作用README.md编译配置步骤与作者资料入口config.h引脚定义、音频 I2S 模式、屏幕参数宏config.json构建系统识别的板卡元数据与默认 sdkconfigesp32_cgc_board.cc板级初始化SPI/LCD、按键、音频编解码器、MCP 灯控工具其中config.json声明了该板卡的厂家wdmomo、类型esp32-cgc、编译目标芯片target: esp32并在构建时自动追加CONFIG_LCD_ST7735_128X128y即默认启用 128×128 分辨率的 ST7735 屏幕配置。这一默认配置与 README 中选择屏幕类型为 ST7735 128*128的步骤相互印证说明该板卡的标准出货屏幕就是 1.8 英寸左右的 ST7735 小屏。二、编译配置完整流程以下命令与 menuconfig 路径均继承自板卡官方 README并补充了必要说明。1. 配置编译目标为 ESP32idf.py set-target esp32ESP32-CGC 使用经典 ESP32 芯片因此必须将编译目标切换为esp32。该命令会重新生成sdkconfig并限定后续可选的板卡范围——只有depends on IDF_TARGET_ESP32的板卡才会出现在 Target Board 列表中见 main/Kconfig.projbuild 中BOARD_TYPE_WDMOMO_CGC的声明。2. 打开 menuconfig 图形配置界面idf.py menuconfigmenuconfig 是 ESP-IDF 的 Kconfig 图形化配置工具xiaozhi-esp32 的所有板卡、外设、唤醒词、显示样式等选项都聚合在Xiaozhi Assistant菜单下定义于 main/Kconfig.projbuild。3. 选择目标板卡在 menuconfig 中依次进入Xiaozhi Assistant - Target Board - WDMomo ESP32-CGC对应 Kconfig 中的BOARD_TYPE_WDMOMO_CGCbool 项depends on IDF_TARGET_ESP32。从源码结构看同属 wdmomo 系列还有一款 ESP32-CGC-144对应BOARD_TYPE_WDMOMO_CGC_144选板时注意区分标准版与 144 版本。4. 选择屏幕类型Xiaozhi Assistant - LCD Type - ST7735, 分辨率128*128LCD Type子菜单由DISPLAY_LCD_TYPEchoice 定义可选项非常丰富。对于 ESP32-CGCconfig.h 中已经为每一种屏幕宏预置了完整的显示参数宽高、镜像、XY 交换、颜色反转、偏移量、SPI 模式选择后编译系统会通过宏开关自动套用对应参数。Kconfig 选项分辨率驱动芯片适用说明LCD_ST7735_128X128128×128ST7735ESP32-CGC 默认屏幕OFFSET_X2, OFFSET_Y3LCD_ST7735_128X160128×160ST7735竖屏小屏LCD_ST7789_240X320240×320ST7789IPS 大屏LCD_ST7789_240X240240×240ST7789方块屏LCD_ST7789_240X135240×135ST7789长条屏自动 XY 交换LCD_ST7796_320X480320×480ST7796IPS 大屏LCD_ILI9341_240X320240×320ILI9341经典大屏LCD_GC9A01_240X240240×240GC9A01圆形屏LCD_CUSTOM自定义自定义手动指定分辨率等参数5. 编译固件idf.py build编译完成后即可使用idf.py flash monitor烧录并查看串口日志。若替换了不同屏幕只需重新进入 menuconfig 切换LCD Type再编译无需改动任何源码。三、硬件资源与引脚分配源码解读1. 音频通路Simplex I2S 与 NoAudioCodecESP32-CGC 的音频采样率定义为输入 16 kHz、输出 24 kHzconfig.h这是小智协议的标准采样率。默认启用AUDIO_I2S_METHOD_SIMPLEX单工模式即麦克风与扬声器各自使用独立的 I2S 总线信号GPIOMIC WSGPIO_NUM_25MIC SCKGPIO_NUM_26MIC DINGPIO_NUM_32SPK DOUTGPIO_NUM_33SPK BCLKGPIO_NUM_14SPK LRCKGPIO_NUM_27若硬件设计需要改为 Duplex I2S 双工模式可注释掉 config.h 中的AUDIO_I2S_METHOD_SIMPLEX宏此时将改用AUDIO_I2S_GPIO_WS/BCLK/DIN/DOUTGPIO 4/5/6/7单总线方案。对应代码在 esp32_cgc_board.cc 的GetAudioCodec()中通过条件编译创建NoAudioCodecSimplex或NoAudioCodecDuplex实例——也就是说该板卡本身不携带硬件音频编解码芯片Codec音频以裸 I2S 数字信号输出由外部功放/咪头电路完成模拟转换。2. LCD 显示SPI 总线与三系列驱动芯片esp32_cgc_board.cc 的InitializeSpi()使用 SPI3 主机MOSI/SCLK 对应DISPLAY_MOSI_PIN(23)/DISPLAY_SCLK_PIN(18)最大传输尺寸按屏幕分辨率动态计算宽 × 高 × 2 字节 RGB565。屏幕控制引脚见 config.h信号GPIO背光GPIO_NUM_4SCLKGPIO_NUM_18MOSIGPIO_NUM_23CSGPIO_NUM_5DCGPIO_NUM_2RESETGPIO_NUM_NC未连接SPI 时钟20 MHzInitializeLcdDisplay()根据 Kconfig 宏自动选择驱动芯片默认走 ST7789 驱动esp_lcd_new_panel_st7789选中LCD_ILI9341_240X320时使用 ILI9341 驱动选中LCD_GC9A01_240X240时不仅使用 GC9A01 驱动还会加载一组专为 GC9107GC9A01 兼容型号准备的初始化命令序列gc9107_lcd_init_cmds包含 20 余条寄存器配置随后统一执行esp_lcd_panel_reset/init/invert_color/swap_xy/mirror完成显示初始化。3. 按键Boot 键与 AI 键按键GPIO功能BOOT 键GPIO_NUM_0设备启动阶段点击进入 Wi-Fi 配网模式正常运行中点击切换对话开关ToggleChatStateASR 键GPIO_NUM_13点击直接触发唤醒词你好小智WakeWordInvoke这一交互逻辑在 esp32_cgc_board.cc 的InitializeButtons()中通过Button回调实现Boot 键在kDeviceStateStarting状态下调用EnterWifiConfigMode()进入配网其余状态切换聊天ASR 键则模拟唤醒词触发语音识别流程。4. MCP 灯控让 AI 看见并控制真实世界config.h 中预留了LAMP_GPIOGPIO_NUM_12并在注释中说明这是一个 MCP 测试控制一盏灯。InitializeTools()中实例化的 LampController 会在 MCP Server 中注册三个工具self.lamp.get_state返回灯的开关状态 JSONself.lamp.turn_on拉高 GPIO 点亮灯具self.lamp.turn_off拉低 GPIO 熄灭灯具。这意味着通过 MCP 协议云端大模型可以直接调用这三个工具来控制 ESP32-CGC 上的真实硬件是典型的AI Agent 控制 IoT 设备落地演示。若不需要该功能可将LAMP_GPIO改为GPIO_NUM_NCLampController构造时会自动跳过 GPIO 初始化与工具注册见 lamp_controller.h 中对GPIO_NUM_NC的提前返回处理。四、常见问题与排查建议menuconfig 中找不到 WDMomo ESP32-CGC确认已执行idf.py set-target esp32该板卡仅支持IDF_TARGET_ESP32目标芯片为 S3/C3 时选项不会出现。屏幕花屏或颜色异常检查LCD Type是否与实物屏幕一致重点核对 config.h 中对应宏的DISPLAY_INVERT_COLOR、DISPLAY_MIRROR_X/Y、DISPLAY_SWAP_XY与DISPLAY_OFFSET_X/Y是否与屏幕模组匹配。更换屏幕后显示区域偏移ST7735 系列小屏常需微调DISPLAY_OFFSET_X/Y例如 128×128 默认偏移为 (2, 3)换屏后按模组数据手册重新设置。音频无声确认板卡采用的是 Simplex 双总线接线MIC 与 SPK 分离若硬件为单 I2S 总线共线需切换为 Duplex 模式并核对 GPIO 4/5/6/7 接线。灯控工具不生效确认LAMP_GPIO未被占用、灯具驱动电路为低电平关断/高电平导通并保证固件已启用 MCP Server 相关配置。五、总结WDMomo ESP32-CGC 是 xiaozhi-esp32 生态中一款典型的经典 ESP32 低成本开源开发板其适配代码完整展示了板级接入的通用范式config.json声明板卡元数据与默认屏幕、config.h集中管理引脚与显示宏、esp32_cgc_board.cc按职责拆分 SPI/LCD、按键、音频与 MCP 工具初始化。无论你是复刻该板卡的 DIY 玩家还是准备为自己的 ESP32 硬件接入 xiaozhi-esp32都可以参考 custom-board.md 与上述源码结构快速完成从画板到跑通语音助手的全流程。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考