小智 ESP32-C6-LCD-1.69 开发板接入指南：编译配置、板级适配与按键交互全解析

小智 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 可以看到该板卡的关键构建属性：manufacturer为waveshare，type为esp32-c6-lcd-1.69，目标芯片为esp32c6；同时在 SDK 配置中追加了CONFIG_USE_ESP_WAKE_WORD=y，即默认启用 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. 配置编译目标为 ESP32C6

idf.py set-target esp32c6

此命令将工程目标芯片切换为 ESP32-C6，同时会依据 sdkconfig.defaults.esp32c6 自动生成对应 sdkconfig。

2. 打开 menuconfig

idf.py menuconfig

3. 选择板卡

在 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 build

5. 烧录并打开串口终端

idf.py build flash monitor

monitor会打开串口监视器，设备启动日志与交互调试信息都会输出到终端。首次使用建议同时完成编译与烧录，一步到位验证固件是否正常运行。

menuconfig 关键选项补充说明

选择板卡后，Xiaozhi Assistant菜单中还有几个与 C6 板卡强相关的配置项值得关注：

• Wake Word Implementation Type（唤醒词实现类型）：在 main/Kconfig.projbuild 中，USE_ESP_WAKE_WORD（Wakenet 模型、无 AFE）明确支持 ESP32C3、ESP32C5 与 ESP32C6 目标，这也是本板卡通过config.json默认追加CONFIG_USE_ESP_WAKE_WORD=y的原因。可在此处改为Disabled关闭唤醒词，或保持默认启用。
• WiFi Configuration Method（配网方式）：默认使用 Hotspot（WiFi 热点配网）方式，也可切换为 ESP-BluFi（BLE 配网）。
• Flash Assets 与 Default Language：可控制是否烧录语音资源包（assets）以及设备显示语言，默认中文。

四、板级源码解析：硬件如何被驱动

选择板卡后，构建系统会把 esp32-c6-lcd-1.69.cc 中的CustomBoard作为板级实现编译进固件。它继承自WifiBoard（见 main/boards/common/wifi_board.cc），并重写音频、显示、背光、电池等核心接口。通过阅读源码可以完整还原板卡硬件拓扑。

1. 音频通路：ES8311 + I2S

GetAudioCodec()返回Es8311AudioCodec实例，音频采样率输入输出均为24000 Hz。音频相关引脚在 config.h 中定义：

InitializeI2c()中以 I2C_NUM_0 创建主总线并开启内部上拉，随后InitializePowerManager()完成电池采样引脚初始化，GetAudioCodec()在首次调用时把 I2C 总线句柄传入 ES8311 驱动，完成编解码器注册。

2. 显示通路：ST7789 1.69 英寸 LCD

显示屏使用 ST7789 驱动芯片，分辨率为240×280，通过 SPI 总线驱动：

InitializeSpi()中 SPI 时钟主机为 SPI2_HOST，InitializeLcdDisplay()设置像素时钟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_PIN（GPIO_NUM_15）作为电池供电使能脚，BATTERY_ADC_PIN（GPIO_NUM_0）作为 ADC 采样脚。GetBatteryLevel()将 ADC 采样电压按阈值映射为电量百分比：

同时通过充电引脚电平判断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.h：BOOT_BUTTON_GPIO（GPIO_NUM_9）与PWR_BUTTON_GPIO（GPIO_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.cc），Button类提供OnClick、OnDoubleClick、OnLongPress、OnPressUp等回调注册能力，长按判定时间由组件默认参数决定。

六、烧录后首次使用与常见问题

1. 配网：首次开机（未连接服务器）单击 BOOT 按键进入配网模式，使用手机连接设备热点完成 WiFi 配置，之后设备自动连接服务器。
2. 唤醒词：固件默认内置"你好小智"唤醒词模型（见 sdkconfig.defaults.esp32c6 中的CONFIG_SR_WN_WN9S_NIHAOXIAOZHI=y），连接服务器后说出唤醒词即可开始对话；单击 BOOT 键同样可唤醒或打断。
3. 菜单路径差异：官方文档写的是Xiaozhi Assistant -> Board Type -> Waveshare ESP32-C6-LCD-1.69，而 main/Kconfig.projbuild 中该菜单的 prompt 实际为Target Board，不同 IDF 版本界面显示可能略有差异，认准 "Waveshare ESP32-C6-LCD-1.69" 条目即可。
4. 分区与 Flash 模式：ESP32-C6 使用 partitions/v2/16m_c3.csv 分区表与 QIO 模式，若手头板卡 Flash 容量或引脚配置不同，需对应调整 sdkconfig 中分区表与 Flash 模式设置。
5. 编译报错排查：若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