小智 ESP32-C6-LCD-1.69 开发板接入指南编译配置、板级适配与按键交互全解析【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文以 xiaozhi-esp32 项目中微雪电子 Waveshare ESP32-C6-LCD-1.69 板卡的官方接入文档为核心结合仓库内该板卡的板级源码、引脚配置与编译系统系统讲解如何将该 1.69 英寸 LCD 带屏开发板编译为小智 AI 语音助手固件。读完本文你将掌握完整的固件编译与烧录流程、menuconfig 板卡选择方法以及 BOOT/PWR 两个实体按键在配网、唤醒、打断、息屏与开关机场景下的源码级实现原理。一、板卡与项目概况Waveshare ESP32-C6-LCD-1.69 是微雪电子推出的一款基于乐鑫 ESP32-C6 芯片的带屏开发板板载 1.69 英寸 240×280 分辨率的 ST7789 IPS 液晶屏、ES8311 音频编解码器Codec、麦克风与喇叭接口并配备 BOOT 与 PWR 两个实体按键。该板卡在 xiaozhi-esp32 仓库中拥有完整的板级支持相关文件位于 main/boards/waveshare/esp32-c6-lcd-1.69 目录文件作用config.json板卡构建元数据厂商、型号、目标芯片、SDK 配置追加项config.h板级硬件引脚映射与显示/音频参数宏定义esp32-c6-lcd-1.69.cc板级驱动实现CustomBoard类power_manager.h板载电池 ADC 采样与充电检测、开关机电源管理从 config.json 可以看到该板卡的关键构建属性manufacturer为wavesharetype为esp32-c6-lcd-1.69目标芯片为esp32c6同时在 SDK 配置中追加了CONFIG_USE_ESP_WAKE_WORDy即默认启用 ESP 官方唤醒词模型Wakenet编译出的固件开箱即可支持你好小智等唤醒词唤醒。二、环境要求与工程获取编译该板卡固件需要准备ESP-IDF 开发环境项目主线现已迁移到 ESP-IDF v6.0 及以上版本首选稳定版为 v6.0.2详见 docs/esp-idf-6-migration.md 与 README_zh.md。ESP32-C6 属于较新的 RISC-V 内核芯片建议使用较新版本的 IDF 以获得完整的 C6 支持。Python 依赖IDF 环境自带的 Python 虚拟环境即可满足构建需求。工程获取与进入项目目录git clone https://github.com/78/xiaozhi-esp32.git cd xiaozhi-esp32说明仓库根目录提供了多套 sdkconfig 默认配置其中 sdkconfig.defaults.esp32c6 指定了自定义分区表partitions/v2/16m_c3.csv、QIO 快速 Flash 模式和内置你好小智唤醒词模型选择 ESP32-C6 目标后构建系统会自动套用。三、编译配置命令完整流程按照官方板卡文档完整编译配置流程如下。1. 配置编译目标为 ESP32C6idf.py set-target esp32c6此命令将工程目标芯片切换为 ESP32-C6同时会依据 sdkconfig.defaults.esp32c6 自动生成对应 sdkconfig。2. 打开 menuconfigidf.py menuconfig3. 选择板卡在 menuconfig 图形界面中依次进入Xiaozhi Assistant - Board Type - Waveshare ESP32-C6-LCD-1.69该选项对应 main/Kconfig.projbuild 中的BOARD_TYPE_WAVESHARE_ESP32_C6_LCD_1_69其声明为bool Waveshare ESP32-C6-LCD-1.69且depends on IDF_TARGET_ESP32C6即只有在目标芯片为 ESP32-C6 时才会出现此选项。4. 编译idf.py build5. 烧录并打开串口终端idf.py build flash monitormonitor会打开串口监视器设备启动日志与交互调试信息都会输出到终端。首次使用建议同时完成编译与烧录一步到位验证固件是否正常运行。menuconfig 关键选项补充说明选择板卡后Xiaozhi Assistant菜单中还有几个与 C6 板卡强相关的配置项值得关注Wake Word Implementation Type唤醒词实现类型在 main/Kconfig.projbuild 中USE_ESP_WAKE_WORDWakenet 模型、无 AFE明确支持 ESP32C3、ESP32C5 与 ESP32C6 目标这也是本板卡通过config.json默认追加CONFIG_USE_ESP_WAKE_WORDy的原因。可在此处改为Disabled关闭唤醒词或保持默认启用。WiFi Configuration Method配网方式默认使用 HotspotWiFi 热点配网方式也可切换为 ESP-BluFiBLE 配网。Flash Assets 与 Default Language可控制是否烧录语音资源包assets以及设备显示语言默认中文。四、板级源码解析硬件如何被驱动选择板卡后构建系统会把 esp32-c6-lcd-1.69.cc 中的CustomBoard作为板级实现编译进固件。它继承自WifiBoard见 main/boards/common/wifi_board.cc并重写音频、显示、背光、电池等核心接口。通过阅读源码可以完整还原板卡硬件拓扑。1. 音频通路ES8311 I2SGetAudioCodec()返回Es8311AudioCodec实例音频采样率输入输出均为24000 Hz。音频相关引脚在 config.h 中定义宏引脚说明AUDIO_I2S_GPIO_MCLKGPIO_NUM_19I2S 主时钟 MCLKAUDIO_I2S_GPIO_WSGPIO_NUM_22字选择 WSLRCLKAUDIO_I2S_GPIO_BCLKGPIO_NUM_20位时钟 BCLKAUDIO_I2S_GPIO_DINGPIO_NUM_21麦克风数据输入AUDIO_I2S_GPIO_DOUTGPIO_NUM_23喇叭数据输出AUDIO_CODEC_I2C_SDA_PINGPIO_NUM_8编解码器 I2C 数据线AUDIO_CODEC_I2C_SCL_PINGPIO_NUM_7编解码器 I2C 时钟线AUDIO_CODEC_ES8311_ADDRES8311_CODEC_DEFAULT_ADDRES8311 器件地址InitializeI2c()中以 I2C_NUM_0 创建主总线并开启内部上拉随后InitializePowerManager()完成电池采样引脚初始化GetAudioCodec()在首次调用时把 I2C 总线句柄传入 ES8311 驱动完成编解码器注册。2. 显示通路ST7789 1.69 英寸 LCD显示屏使用 ST7789 驱动芯片分辨率为240×280通过 SPI 总线驱动宏引脚/值说明DISPLAY_CS_PINGPIO_NUM_5片选 CSDISPLAY_MOSI_PINGPIO_NUM_2数据线 MOSIDISPLAY_CLK_PINGPIO_NUM_1时钟 SCLKDISPLAY_DC_PINGPIO_NUM_3数据/命令选择 DCDISPLAY_RST_PINGPIO_NUM_4复位 RSTDISPLAY_BACKLIGHT_PINGPIO_NUM_6背光 PWM 引脚DISPLAY_SPI_MODE3SPI 模式DISPLAY_INVERT_COLORtrue颜色反转ST7789 常见要求DISPLAY_OFFSET_X / OFFSET_Y0 / 20显示偏移Y 方向偏移 20 像素适配面板InitializeSpi()中 SPI 时钟主机为 SPI2_HOSTInitializeLcdDisplay()设置像素时钟40 MHz通过esp_lcd_new_panel_st7789创建面板驱动并依据宏执行颜色反转、XY 交换与镜像设置。值得注意的细节是 esp32-c6-lcd-1.69.cc 中自定义了CustomLcdDisplay子类在SetupUI()中把状态栏左右内边距调整为屏幕宽度的 10%用于适配窄屏的 UI 布局。背光则通过PwmBacklight见 main/boards/common/backlight.h以 PWM 方式控制亮度并支持亮度掉电保存与恢复RestoreBrightness()。3. 电池管理ADC 电压分级板载电池检测由 power_manager.h 中的PowerManager实现BATTERY_EN_PINGPIO_NUM_15作为电池供电使能脚BATTERY_ADC_PINGPIO_NUM_0作为 ADC 采样脚。GetBatteryLevel()将 ADC 采样电压按阈值映射为电量百分比电压区间电量显示 3.52 V1%3.52 ~ 3.64 V20%3.64 ~ 3.76 V40%3.76 ~ 3.88 V60%3.88 ~ 4.00 V80%≥ 4.00 V100%同时通过充电引脚电平判断IsCharging()/IsDischarging()仅在放电状态下启用省电定时器。4. 省电与关机策略InitializePowerSaveTimer()创建PowerSaveTimer见 main/boards/common/power_save_timer.h参数为(-1, 60, 300)60 秒无操作进入休眠模式息屏300 秒后触发关机请求通过power_manager_-PowerOff()拉低电池使能引脚实现整机关机。休眠与唤醒回调分别调用GetDisplay()-SetPowerSaveMode(true/false)控制屏幕电源。五、按键操作功能与源码级实现板卡文档给出了两个实体按键的完整操作说明结合源码可以进一步看到每个操作背后的调用链。两个按键引脚定义于 config.hBOOT_BUTTON_GPIOGPIO_NUM_9与PWR_BUTTON_GPIOGPIO_NUM_18。BOOT 按键场景操作功能未连接服务器前单击进入配网模式连接服务器后单击唤醒、打断源码实现位于InitializeButtons()的boot_button_.OnClick(...)回调中当设备状态为kDeviceStateStarting即尚未连接服务器时调用EnterWifiConfigMode()进入 WiFi 配网模式否则调用app.ToggleChatState()切换对话状态——若当前处于待唤醒状态则唤醒开始对话若正在对话则打断/结束当前会话。PWR 按键操作功能双击息屏、亮屏长按开关机源码实现中PWR 按键在OnPressUp回调里嵌套注册了两个事件双击OnDoubleClick读取当前背光亮度backlight-brightness()若亮度为 0已息屏则恢复至亮度 50 或上次亮度值实现亮屏否则记录当前亮度并SetBrightness(0)息屏长按OnLongPress调用power_manager_-PowerOff()拉低电池使能脚GPIO_NUM_15实现关机。若板卡由 USB 供电重新上电即可开机。按键驱动统一基于 ESP-IDF 的iot_button组件封装见 main/boards/common/button.ccButton类提供OnClick、OnDoubleClick、OnLongPress、OnPressUp等回调注册能力长按判定时间由组件默认参数决定。六、烧录后首次使用与常见问题配网首次开机未连接服务器单击 BOOT 按键进入配网模式使用手机连接设备热点完成 WiFi 配置之后设备自动连接服务器。唤醒词固件默认内置你好小智唤醒词模型见 sdkconfig.defaults.esp32c6 中的CONFIG_SR_WN_WN9S_NIHAOXIAOZHIy连接服务器后说出唤醒词即可开始对话单击 BOOT 键同样可唤醒或打断。菜单路径差异官方文档写的是Xiaozhi Assistant - Board Type - Waveshare ESP32-C6-LCD-1.69而 main/Kconfig.projbuild 中该菜单的 prompt 实际为Target Board不同 IDF 版本界面显示可能略有差异认准 Waveshare ESP32-C6-LCD-1.69 条目即可。分区与 Flash 模式ESP32-C6 使用 partitions/v2/16m_c3.csv 分区表与 QIO 模式若手头板卡 Flash 容量或引脚配置不同需对应调整 sdkconfig 中分区表与 Flash 模式设置。编译报错排查若idf.py build失败优先确认idf.py set-target esp32c6已执行且 menuconfig 中板卡选项已正确选中C6 相关的组件如 ESP-SR 唤醒词库需随 IDF 版本正确下载可执行idf.py fullclean后重试。七、结语Waveshare ESP32-C6-LCD-1.69 以小体积带屏形态提供了完整的语音交互硬件基础而 xiaozhi-esp32 仓库在 main/boards/waveshare/esp32-c6-lcd-1.69 目录中为其提供了开箱即用的板级适配从set-target到menuconfig选择板卡再到build flash monitor一键烧录即可获得支持唤醒词、语音对话、屏幕显示与实体按键交互的完整 AI 助手固件。对于希望深入定制该板卡的开发者建议从 config.h 的引脚宏入手结合 esp32-c6-lcd-1.69.cc 的初始化顺序理解整块板卡的驱动骨架。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考