尧图网站建设 
xiaozhi-esp32 中 M5Stack Cardputer Adv 板卡支持硬件引脚、TCA8418 键盘驱动与烧录实战指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文围绕 xiaozhi-esp32 固件中 M5Stack Cardputer Adv 板卡的完整支持实现展开覆盖硬件规格与引脚定义、板级配置文件、TCA8418 键盘驱动与键盘 WiFi 配网 UI、ES8311 音频链路的接线细节以及 8MB Flash 分区与 esptool 烧录命令。读完后你可以独立完成该板卡的固件构建、烧录与配网操作并理解其按键映射、电量监测等底层实现。一、硬件规格总览M5Stack Cardputer Adv 是一款基于 ESP32-S3FN8Stamp-S3A 核心板的卡片式电脑xiaozhi-esp32 通过 board 目录 为其提供了完整的板级支持。官方 README 给出的硬件规格如下组件规格MCUESP32-S3FN8 240MHzFlash8MB显示屏ST7789V2 1.14 240x135音频编解码ES8311功放NS4150B麦克风MEMS键盘56 键TCA8418IMUBMI270电池1750mAh带 ADC 电量监测从源码结构看这块板子的特点是全外设共用一条 I2C 总线 独立 SPI 显示屏 独立 ADC 电量通道一条 I2C 总线SDAGPIO8, SCLGPIO9同时挂载ES8311 音频编解码器、TCA8418 键盘扫描芯片和 BMI270 IMU显示屏走 SPI3四根数据线 背光 PWM电池电压经 100KΩ/100KΩ 分压后接入 ADC1_CH9GPIO10。板级实现入口是 m5stack_cardputer_adv.cc其中M5StackCardputerAdvBoard继承自WifiBoard通过DECLARE_BOARD宏注册到固件的板卡选择框架中。二、引脚定义与 config.h 的逐一对应README 中列出的三组引脚显示屏、音频、电池监测与 config.h 中的宏定义一一对应。这里把两者合并整理便于查表对照。2.1 显示屏ST7789V2SPI功能GPIOconfig.h 宏MOSIGPIO35DISPLAY_SPI_MOSI_PINSCLKGPIO36DISPLAY_SPI_SCLK_PINCSGPIO37DISPLAY_SPI_CS_PINDCGPIO34DISPLAY_DC_PINRSTGPIO33DISPLAY_RST_PINBL背光GPIO38DISPLAY_BACKLIGHT_PINconfig.h 还定义了该屏幕的显示参数DISPLAY_WIDTH 240/DISPLAY_HEIGHT 135物理分辨率DISPLAY_MIRROR_X true/DISPLAY_MIRROR_Y false/DISPLAY_SWAP_XY trueST7789V2 面板与像素缓冲的坐标变换关系DISPLAY_OFFSET_X 40/DISPLAY_OFFSET_Y 53面板逻辑偏移1.14 寸屏在 240x240 面板坐标系中的窗口位置DISPLAY_BACKLIGHT_OUTPUT_INVERT false背光输出电平不取反。在 m5stack_cardputer_adv.cc 的InitializeSt7789Display()中可以看到这些参数的实际使用SPI 初始化在SPI3_HOST上pclk_hz设为 40MHz并开启sio_mode 13 线 SPI 模式随后调用esp_lcd_panel_invert_color、esp_lcd_panel_swap_xy、esp_lcd_panel_mirror完成与 config.h 一致的显示变换。背光则使用 256Hz PWM注释说明该频率与 M5GFX 对该机型的背光设置保持一致并在板卡代码中定义了MIN_BRIGHTNESS 30防止亮度调得过暗。2.2 音频ES8311 NS4150B功能GPIOI2C SDAGPIO8I2C SCLGPIO9I2S BCLKGPIO41I2S LRCKGPIO43I2S DOUTGPIO46I2S DINGPIO42config.h 中对应的宏与方向注释以 config.h 为准#define AUDIO_I2S_GPIO_MCLK GPIO_NUM_NC // 无外部 MCLK #define AUDIO_I2S_GPIO_BCLK GPIO_NUM_41 // SCLK #define AUDIO_I2S_GPIO_WS GPIO_NUM_43 // LRCK #define AUDIO_I2S_GPIO_DOUT GPIO_NUM_42 // MCU - ES8311 #define AUDIO_I2S_GPIO_DIN GPIO_NUM_46 // ES8311 - MCU两个值得注意的配置采样率 24kHzAUDIO_INPUT_SAMPLE_RATE与AUDIO_OUTPUT_SAMPLE_RATE均定义为 24000功放常开AUDIO_CODEC_PA_PIN GPIO_NUM_NC注释说明 NS4150B 功放始终上电固件不做 PA 开关控制。在GetAudioCodec()中固件针对该板卡做了一个关键适配由于 Cardputer Adv 的 ES8311没有外接 MCLKuse_mclk false内部时钟代码派生了一个CardputerAdvEs8311子类在构造完成后立即i2s_channel_disable(tx_handle_)/i2s_channel_disable(rx_handle_)目的是让esp_codec_dev_open有足够窗口先行配置 ES8311 寄存器再启动 I2S 通道。2.3 电池监测ADC功能GPIO备注ADCGPIO10100KΩ / 100KΩ 分压config.h 中给出了从官方原理图Sch_M5CardputerAdv_v1.0核实的分压参数#define BATTERY_ADC_UNIT ADC_UNIT_1 #define BATTERY_ADC_CHANNEL ADC_CHANNEL_9 #define BATTERY_UPPER_RESISTOR 100000.0f // R9: BAT - GPIO10 #define BATTERY_LOWER_RESISTOR 100000.0f // R8: GPIO10 - GND #define BATTERY_CHARGING_PIN GPIO_NUM_NC分压比 1:1 意味着 ADC 读到的电压需乘以 2 才能还原电池电压。板卡通过 adc_battery_monitor.h 中的通用AdcBatteryMonitor组件实现电量百分比估算并在GetBatteryLevel()中向上层暴露充电/放电状态。2.4 键盘与 IMUREADME 未单列补充自 config.h除 README 已列引脚外config.h 还定义了两个 I2C 外设与按钮外设地址/引脚宏TCA8418 键盘 I2C 地址0x34KEYBOARD_TCA8418_ADDRTCA8418 中断脚GPIO11KEYBOARD_INT_PINBMI270 IMU I2C 地址0x68IMU_BMI270_ADDRBOOT 按钮GPIO0BOOT_BUTTON_GPIO三、板级配置 config.json 与构建参数config.json 是 xiaozhi-esp32 构建系统的板卡描述文件构建脚本 scripts/build.py 会读取其中的type与builds字段来配置编译变体{ manufacturer: m5stack, type: m5stack-cardputer-adv, target: esp32s3, builds: [ { name: m5stack-cardputer-adv, sdkconfig_append: [ CONFIG_SPIRAMn, CONFIG_ESPTOOLPY_FLASHSIZE_8MBy, CONFIG_PARTITION_TABLE_CUSTOM_FILENAME\partitions/v2/8m.csv\ ] } ] }三条sdkconfig_append的含义CONFIG_SPIRAMnStamp-S3AS3FN8只有内置 8MB Flash、无外部 PSRAM必须关闭 SPIRAM 以释放 GPIO 与内存CONFIG_ESPTOOLPY_FLASHSIZE_8MBy告知工具链 Flash 容量为 8MBCONFIG_PARTITION_TABLE_CUSTOM_FILENAMEpartitions/v2/8m.csv指定使用仓库中的 8MB 分区表。该分区表内容与烧录地址完全吻合# ESP-IDF Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, otadata, data, ota, 0xd000, 0x2000, phy_init, data, phy, 0xf000, 0x1000, ota_0, app, ota_0, 0x20000, 0x2f0000, ota_1, app, ota_1, , 0x2f0000, assets, data, spiffs, 0x600000, 2Mnvs0x9000存放 NVS 配置WiFi 凭据等otadata0xd000OTA 切换数据对应烧录表中的ota_data_initial.binota_0/ota_1自 0x20000 起各 0x2F0000双 OTA 应用槽assets0x6000002MB SPIFFS存放生成的语音/语言资产对应烧录表中的generated_assets.bin。四、固件实现解析4.1 板卡初始化流程M5StackCardputerAdvBoard构造函数按固定顺序完成硬件初始化InitializeI2c() // I2C_NUM_0, GPIO8/9, 内部上拉 I2cDetect() // 扫描并打印 128 个地址的探通表 InitializeSpi() // SPI3_HOST InitializeSt7789Display() // 3 线 SPI ST7789 面板驱动 InitializeButtons() // BOOT 按钮 (GPIO0) InitializeKeyboard() // TCA8418 (0x34, INTGPIO11) InitializeBatteryMonitor()// ADC1_CH9 GetBacklight()-RestoreBrightness() // 恢复上次亮度其中I2cDetect()会在串口打印完整的 I2C 地址探通表如0x34键盘、0x68IMU、ES8311 地址是排查 I2C 接线问题时的第一手日志。4.2 TCA8418 键盘驱动7x8 物理矩阵到 4x14 逻辑布局56 键键盘由 I2C 键盘扫描芯片 TCA8418 驱动实现在 tca8418_keyboard.cc。该驱动有几个关键设计点1物理矩阵与逻辑布局的映射。Cardputer Adv 硬件上把 TCA8418 接成 7x8 矩阵KP_GPIO1 0x7F对应 R0-R6KP_GPIO2 0xFF对应 C0-C7但物理键位排布与 Cardputer 的 4x14 布局一致。驱动通过RemapRawKeyToLogical()把原始 (row, col) 重映射为逻辑坐标uint8_t mapped_col (row * 2) ((col 3) ? 1 : 0); // 0..13 uint8_t mapped_row (col 4) % 4; // 0..3即每一原始行贡献两个逻辑列左右半区逻辑行由原始列号每 4 个环绕一次推出。2HID 键码与字符表。tca8418_keyboard.h 定义了完整的 HID 兼容KeyCode枚举KC_A0x04 …KC_ENTER0x28 … 修饰键KC_LCTRL/KC_LSHIFT/KC_LALT/KC_LOPTKEY_MAP[4][14]则给出每个键位的普通/Shift 两态字符如1/!、z/Z。3修饰键语义。字母键的大小写采用Shift 与 CapsLock 的 XOR 语义按住 Shift 时 CapsLock 效果反转符合标准键盘习惯数字与符号键仅受 Shift 影响。CapsLock为按下一次切换一次的锁存状态。4中断驱动 任务轮询的按键事件模型。GPIO11 中断脚配置为ANYEDGE触发注释说明 IRQ 低电平有效且事件未读完时可能持续拉低ISR 中仅置位标志并vTaskNotifyGiveFromISR唤醒keyboard_task4096 栈、优先级 5任务内循环读取 TCA8418 的KEY_EVENT_A0x04寄存器按键事件码解码为(key_code-1)/10与(key_code-1)%10得到原始行列并用 64 位key_state_mask_对重复的按下/释放事件去重防抖。最后统一回写INT_STAT0x02为 0x1F 清中断。5双回调接口。驱动同时提供KeyCallback旧式方向键/回车与KeyEventCallback携带 HID 键码 字符的完整事件前者供音量/亮度控制后者供 WiFi 配网 UI 做文本输入。4.3 按键功能映射旧式回调HandleLegacyKeyPress()把 5 个键映射为系统功能其中方向键复用键盘上的字符键注释与 M5Cardputer 布局一致逻辑功能物理键逻辑位置音量KEY_UP;行2列11音量-KEY_DOWN.行3列11亮度-KEY_LEFT,行3列10亮度KEY_RIGHT/行3列12开始/停止对话KEY_ENTEREnter行2列13音量与亮度都采用粗调/细调步进中间区间每次 ±10靠近两端≤20 或 ≥80亮度下限为MIN_BRIGHTNESS 20时每次 ±1亮度下限固定 30%。每次调节都会调用display_-ShowNotification()在屏幕上短暂提示当前值如Volume: 60%。BOOT 按钮GPIO0的OnClick逻辑开机启动阶段按下则进入 WiFi 配网模式EnterWifiConfigMode否则切换对话状态app.ToggleChatState()——Enter 键的语义与之完全对齐。4.4 键盘驱动的 WiFi 配网 UI由于 Cardputer Adv 没有实体音量键固件实现了一套纯键盘操作的 WiFi 配网界面wifi_config_ui.h / wifi_config_ui.cc状态机覆盖Scanning → SelectWifi → InputPassword、InputSsid → InputManualPwd、SavedList → Connecting → Success/Failed共 8 个状态进入方式二选一在 WiFi 配网扫描界面按W键进入完整键盘配网StartKeyboardWifiConfig先扫描再选网按S键直接进入已保存 WiFi 列表StartWithSavedList配网过程中的所有按键含字母、数字、方向、Enter、Esc、Backspace都被WifiConfigUI::HandleKeyEvent()优先消费不影响正常对话流程选定 SSID/密码后AttemptWifiConnection()会把凭据写入SsidManager持久化保存停止 AP 配网模式后切回 Station 连接并轮询最多 10 秒100 × 100ms等待结果最终在屏幕上显示连接成功/失败。这套机制让 Cardputer Adv 在没有手机热点依赖的情况下仅凭 56 键键盘就能完成首次配网与换网。4.5 显示屏与背光的展示层显示对象是SpiLcdDisplay继承自 lcd_display.h构造时传入分辨率、面板偏移与镜像/交换参数亮度对象为 256Hz PWM 的PwmBacklight。RestoreBrightness()在启动时恢复上次保存的亮度避免每次上电屏幕过亮。五、使用方法按下 BOOT 按钮进入配网模式连接 WiFi 后即可使用语音助手功能。结合 4.4 节的源码可知配网模式下的进一步操作为在扫描界面按W键使用键盘扫描/手动输入 WiFi 信息按S键从已保存的 WiFi 列表中选择日常使用中Enter 键与 BOOT 按钮一样用于开始/停止对话;.,/键分别调节音量与亮度。六、烧录参数与命令该板卡烧录参数芯片 ESP32-S3Flash 8MB模式 DIO频率 80MHz。Flash 地址布局地址文件0x0bootloader/bootloader.bin0x8000partition_table/partition-table.bin0xd000ota_data_initial.bin0x20000xiaozhi.bin0x600000generated_assets.bin其中 0xd000 对应分区表的otadata、0x20000 对应ota_0、0x600000 对应 2MB 的assetsSPIFFS 分区见 3 节分区表。构建时该板卡的 build 目录为build-cardputer-adv烧录命令如下python -m esptool --chip esp32s3 -b 460800 -p PORT \ --before default_reset --after hard_reset \ write_flash --flash_mode dio --flash_size 8MB --flash_freq 80m \ 0x0 build-cardputer-adv/bootloader/bootloader.bin \ 0x8000 build-cardputer-adv/partition_table/partition-table.bin \ 0xd000 build-cardputer-adv/ota_data_initial.bin \ 0x20000 build-cardputer-adv/xiaozhi.bin \ 0x600000 build-cardputer-adv/generated_assets.bin将PORT替换为实际串口设备路径如 macOS 下的/dev/cu.usbmodem21101Linux 下通常为/dev/ttyACM*或/dev/ttyUSB*。构建可通过仓库的构建脚本完成脚本会解析 config.json 中的板卡类型并生成对应的 sdkconfig关闭 SPIRAM、选择 8MB 分区表再调用 ESP-IDF 工具链产出上述五个烧录文件。七、小结与延伸阅读Cardputer Adv 在 xiaozhi-esp32 中的支持是一个小屏幕卡片机板卡的典型样本一条 I2C 总线复用三个外设、无 MCLK 的 ES8311 I2S 适配、7x8 物理矩阵到 4x14 逻辑键盘的坐标重映射、纯键盘操作的 WiFi 配网状态机以及 8MB 双 OTA 2MB SPIFFS 资产分区。相关实现文件汇总文件职责README.md硬件规格、引脚、烧录指南config.h引脚/显示/音频/电池/键盘宏定义config.json构建变体与 sdkconfig 追加项m5stack_cardputer_adv.cc板卡初始化、按键功能、音频适配tca8418_keyboard.cc / tca8418_keyboard.h键盘驱动与 HID 键码表wifi_config_ui.cc / wifi_config_ui.h键盘 WiFi 配网 UI 状态机partitions/v2/8m.csv8MB 分区表adc_battery_monitor.h通用 ADC 电量监测组件【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 xiaozhi-esp32 中 M5Stack Cardputer Adv 板卡支持：硬件引脚、TCA8418 键盘驱动与烧录实战指南
xiaozhi-esp32 中 M5Stack Cardputer Adv 板卡支持硬件引脚、TCA8418 键盘驱动与烧录实战指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文围绕 xiaozhi-esp32 固件中 M5Stack Cardputer Adv 板卡的完整支持实现展开覆盖硬件规格与引脚定义、板级配置文件、TCA8418 键盘驱动与键盘 WiFi 配网 UI、ES8311 音频链路的接线细节以及 8MB Flash 分区与 esptool 烧录命令。读完后你可以独立完成该板卡的固件构建、烧录与配网操作并理解其按键映射、电量监测等底层实现。一、硬件规格总览M5Stack Cardputer Adv 是一款基于 ESP32-S3FN8Stamp-S3A 核心板的卡片式电脑xiaozhi-esp32 通过 board 目录 为其提供了完整的板级支持。官方 README 给出的硬件规格如下组件规格MCUESP32-S3FN8 240MHzFlash8MB显示屏ST7789V2 1.14 240x135音频编解码ES8311功放NS4150B麦克风MEMS键盘56 键TCA8418IMUBMI270电池1750mAh带 ADC 电量监测从源码结构看这块板子的特点是全外设共用一条 I2C 总线 独立 SPI 显示屏 独立 ADC 电量通道一条 I2C 总线SDAGPIO8, SCLGPIO9同时挂载ES8311 音频编解码器、TCA8418 键盘扫描芯片和 BMI270 IMU显示屏走 SPI3四根数据线 背光 PWM电池电压经 100KΩ/100KΩ 分压后接入 ADC1_CH9GPIO10。板级实现入口是 m5stack_cardputer_adv.cc其中M5StackCardputerAdvBoard继承自WifiBoard通过DECLARE_BOARD宏注册到固件的板卡选择框架中。二、引脚定义与 config.h 的逐一对应README 中列出的三组引脚显示屏、音频、电池监测与 config.h 中的宏定义一一对应。这里把两者合并整理便于查表对照。2.1 显示屏ST7789V2SPI功能GPIOconfig.h 宏MOSIGPIO35DISPLAY_SPI_MOSI_PINSCLKGPIO36DISPLAY_SPI_SCLK_PINCSGPIO37DISPLAY_SPI_CS_PINDCGPIO34DISPLAY_DC_PINRSTGPIO33DISPLAY_RST_PINBL背光GPIO38DISPLAY_BACKLIGHT_PINconfig.h 还定义了该屏幕的显示参数DISPLAY_WIDTH 240/DISPLAY_HEIGHT 135物理分辨率DISPLAY_MIRROR_X true/DISPLAY_MIRROR_Y false/DISPLAY_SWAP_XY trueST7789V2 面板与像素缓冲的坐标变换关系DISPLAY_OFFSET_X 40/DISPLAY_OFFSET_Y 53面板逻辑偏移1.14 寸屏在 240x240 面板坐标系中的窗口位置DISPLAY_BACKLIGHT_OUTPUT_INVERT false背光输出电平不取反。在 m5stack_cardputer_adv.cc 的InitializeSt7789Display()中可以看到这些参数的实际使用SPI 初始化在SPI3_HOST上pclk_hz设为 40MHz并开启sio_mode 13 线 SPI 模式随后调用esp_lcd_panel_invert_color、esp_lcd_panel_swap_xy、esp_lcd_panel_mirror完成与 config.h 一致的显示变换。背光则使用 256Hz PWM注释说明该频率与 M5GFX 对该机型的背光设置保持一致并在板卡代码中定义了MIN_BRIGHTNESS 30防止亮度调得过暗。2.2 音频ES8311 NS4150B功能GPIOI2C SDAGPIO8I2C SCLGPIO9I2S BCLKGPIO41I2S LRCKGPIO43I2S DOUTGPIO46I2S DINGPIO42config.h 中对应的宏与方向注释以 config.h 为准#define AUDIO_I2S_GPIO_MCLK GPIO_NUM_NC // 无外部 MCLK #define AUDIO_I2S_GPIO_BCLK GPIO_NUM_41 // SCLK #define AUDIO_I2S_GPIO_WS GPIO_NUM_43 // LRCK #define AUDIO_I2S_GPIO_DOUT GPIO_NUM_42 // MCU - ES8311 #define AUDIO_I2S_GPIO_DIN GPIO_NUM_46 // ES8311 - MCU两个值得注意的配置采样率 24kHzAUDIO_INPUT_SAMPLE_RATE与AUDIO_OUTPUT_SAMPLE_RATE均定义为 24000功放常开AUDIO_CODEC_PA_PIN GPIO_NUM_NC注释说明 NS4150B 功放始终上电固件不做 PA 开关控制。在GetAudioCodec()中固件针对该板卡做了一个关键适配由于 Cardputer Adv 的 ES8311没有外接 MCLKuse_mclk false内部时钟代码派生了一个CardputerAdvEs8311子类在构造完成后立即i2s_channel_disable(tx_handle_)/i2s_channel_disable(rx_handle_)目的是让esp_codec_dev_open有足够窗口先行配置 ES8311 寄存器再启动 I2S 通道。2.3 电池监测ADC功能GPIO备注ADCGPIO10100KΩ / 100KΩ 分压config.h 中给出了从官方原理图Sch_M5CardputerAdv_v1.0核实的分压参数#define BATTERY_ADC_UNIT ADC_UNIT_1 #define BATTERY_ADC_CHANNEL ADC_CHANNEL_9 #define BATTERY_UPPER_RESISTOR 100000.0f // R9: BAT - GPIO10 #define BATTERY_LOWER_RESISTOR 100000.0f // R8: GPIO10 - GND #define BATTERY_CHARGING_PIN GPIO_NUM_NC分压比 1:1 意味着 ADC 读到的电压需乘以 2 才能还原电池电压。板卡通过 adc_battery_monitor.h 中的通用AdcBatteryMonitor组件实现电量百分比估算并在GetBatteryLevel()中向上层暴露充电/放电状态。2.4 键盘与 IMUREADME 未单列补充自 config.h除 README 已列引脚外config.h 还定义了两个 I2C 外设与按钮外设地址/引脚宏TCA8418 键盘 I2C 地址0x34KEYBOARD_TCA8418_ADDRTCA8418 中断脚GPIO11KEYBOARD_INT_PINBMI270 IMU I2C 地址0x68IMU_BMI270_ADDRBOOT 按钮GPIO0BOOT_BUTTON_GPIO三、板级配置 config.json 与构建参数config.json 是 xiaozhi-esp32 构建系统的板卡描述文件构建脚本 scripts/build.py 会读取其中的type与builds字段来配置编译变体{ manufacturer: m5stack, type: m5stack-cardputer-adv, target: esp32s3, builds: [ { name: m5stack-cardputer-adv, sdkconfig_append: [ CONFIG_SPIRAMn, CONFIG_ESPTOOLPY_FLASHSIZE_8MBy, CONFIG_PARTITION_TABLE_CUSTOM_FILENAME\partitions/v2/8m.csv\ ] } ] }三条sdkconfig_append的含义CONFIG_SPIRAMnStamp-S3AS3FN8只有内置 8MB Flash、无外部 PSRAM必须关闭 SPIRAM 以释放 GPIO 与内存CONFIG_ESPTOOLPY_FLASHSIZE_8MBy告知工具链 Flash 容量为 8MBCONFIG_PARTITION_TABLE_CUSTOM_FILENAMEpartitions/v2/8m.csv指定使用仓库中的 8MB 分区表。该分区表内容与烧录地址完全吻合# ESP-IDF Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, otadata, data, ota, 0xd000, 0x2000, phy_init, data, phy, 0xf000, 0x1000, ota_0, app, ota_0, 0x20000, 0x2f0000, ota_1, app, ota_1, , 0x2f0000, assets, data, spiffs, 0x600000, 2Mnvs0x9000存放 NVS 配置WiFi 凭据等otadata0xd000OTA 切换数据对应烧录表中的ota_data_initial.binota_0/ota_1自 0x20000 起各 0x2F0000双 OTA 应用槽assets0x6000002MB SPIFFS存放生成的语音/语言资产对应烧录表中的generated_assets.bin。四、固件实现解析4.1 板卡初始化流程M5StackCardputerAdvBoard构造函数按固定顺序完成硬件初始化InitializeI2c() // I2C_NUM_0, GPIO8/9, 内部上拉 I2cDetect() // 扫描并打印 128 个地址的探通表 InitializeSpi() // SPI3_HOST InitializeSt7789Display() // 3 线 SPI ST7789 面板驱动 InitializeButtons() // BOOT 按钮 (GPIO0) InitializeKeyboard() // TCA8418 (0x34, INTGPIO11) InitializeBatteryMonitor()// ADC1_CH9 GetBacklight()-RestoreBrightness() // 恢复上次亮度其中I2cDetect()会在串口打印完整的 I2C 地址探通表如0x34键盘、0x68IMU、ES8311 地址是排查 I2C 接线问题时的第一手日志。4.2 TCA8418 键盘驱动7x8 物理矩阵到 4x14 逻辑布局56 键键盘由 I2C 键盘扫描芯片 TCA8418 驱动实现在 tca8418_keyboard.cc。该驱动有几个关键设计点1物理矩阵与逻辑布局的映射。Cardputer Adv 硬件上把 TCA8418 接成 7x8 矩阵KP_GPIO1 0x7F对应 R0-R6KP_GPIO2 0xFF对应 C0-C7但物理键位排布与 Cardputer 的 4x14 布局一致。驱动通过RemapRawKeyToLogical()把原始 (row, col) 重映射为逻辑坐标uint8_t mapped_col (row * 2) ((col 3) ? 1 : 0); // 0..13 uint8_t mapped_row (col 4) % 4; // 0..3即每一原始行贡献两个逻辑列左右半区逻辑行由原始列号每 4 个环绕一次推出。2HID 键码与字符表。tca8418_keyboard.h 定义了完整的 HID 兼容KeyCode枚举KC_A0x04 …KC_ENTER0x28 … 修饰键KC_LCTRL/KC_LSHIFT/KC_LALT/KC_LOPTKEY_MAP[4][14]则给出每个键位的普通/Shift 两态字符如1/!、z/Z。3修饰键语义。字母键的大小写采用Shift 与 CapsLock 的 XOR 语义按住 Shift 时 CapsLock 效果反转符合标准键盘习惯数字与符号键仅受 Shift 影响。CapsLock为按下一次切换一次的锁存状态。4中断驱动 任务轮询的按键事件模型。GPIO11 中断脚配置为ANYEDGE触发注释说明 IRQ 低电平有效且事件未读完时可能持续拉低ISR 中仅置位标志并vTaskNotifyGiveFromISR唤醒keyboard_task4096 栈、优先级 5任务内循环读取 TCA8418 的KEY_EVENT_A0x04寄存器按键事件码解码为(key_code-1)/10与(key_code-1)%10得到原始行列并用 64 位key_state_mask_对重复的按下/释放事件去重防抖。最后统一回写INT_STAT0x02为 0x1F 清中断。5双回调接口。驱动同时提供KeyCallback旧式方向键/回车与KeyEventCallback携带 HID 键码 字符的完整事件前者供音量/亮度控制后者供 WiFi 配网 UI 做文本输入。4.3 按键功能映射旧式回调HandleLegacyKeyPress()把 5 个键映射为系统功能其中方向键复用键盘上的字符键注释与 M5Cardputer 布局一致逻辑功能物理键逻辑位置音量KEY_UP;行2列11音量-KEY_DOWN.行3列11亮度-KEY_LEFT,行3列10亮度KEY_RIGHT/行3列12开始/停止对话KEY_ENTEREnter行2列13音量与亮度都采用粗调/细调步进中间区间每次 ±10靠近两端≤20 或 ≥80亮度下限为MIN_BRIGHTNESS 20时每次 ±1亮度下限固定 30%。每次调节都会调用display_-ShowNotification()在屏幕上短暂提示当前值如Volume: 60%。BOOT 按钮GPIO0的OnClick逻辑开机启动阶段按下则进入 WiFi 配网模式EnterWifiConfigMode否则切换对话状态app.ToggleChatState()——Enter 键的语义与之完全对齐。4.4 键盘驱动的 WiFi 配网 UI由于 Cardputer Adv 没有实体音量键固件实现了一套纯键盘操作的 WiFi 配网界面wifi_config_ui.h / wifi_config_ui.cc状态机覆盖Scanning → SelectWifi → InputPassword、InputSsid → InputManualPwd、SavedList → Connecting → Success/Failed共 8 个状态进入方式二选一在 WiFi 配网扫描界面按W键进入完整键盘配网StartKeyboardWifiConfig先扫描再选网按S键直接进入已保存 WiFi 列表StartWithSavedList配网过程中的所有按键含字母、数字、方向、Enter、Esc、Backspace都被WifiConfigUI::HandleKeyEvent()优先消费不影响正常对话流程选定 SSID/密码后AttemptWifiConnection()会把凭据写入SsidManager持久化保存停止 AP 配网模式后切回 Station 连接并轮询最多 10 秒100 × 100ms等待结果最终在屏幕上显示连接成功/失败。这套机制让 Cardputer Adv 在没有手机热点依赖的情况下仅凭 56 键键盘就能完成首次配网与换网。4.5 显示屏与背光的展示层显示对象是SpiLcdDisplay继承自 lcd_display.h构造时传入分辨率、面板偏移与镜像/交换参数亮度对象为 256Hz PWM 的PwmBacklight。RestoreBrightness()在启动时恢复上次保存的亮度避免每次上电屏幕过亮。五、使用方法按下 BOOT 按钮进入配网模式连接 WiFi 后即可使用语音助手功能。结合 4.4 节的源码可知配网模式下的进一步操作为在扫描界面按W键使用键盘扫描/手动输入 WiFi 信息按S键从已保存的 WiFi 列表中选择日常使用中Enter 键与 BOOT 按钮一样用于开始/停止对话;.,/键分别调节音量与亮度。六、烧录参数与命令该板卡烧录参数芯片 ESP32-S3Flash 8MB模式 DIO频率 80MHz。Flash 地址布局地址文件0x0bootloader/bootloader.bin0x8000partition_table/partition-table.bin0xd000ota_data_initial.bin0x20000xiaozhi.bin0x600000generated_assets.bin其中 0xd000 对应分区表的otadata、0x20000 对应ota_0、0x600000 对应 2MB 的assetsSPIFFS 分区见 3 节分区表。构建时该板卡的 build 目录为build-cardputer-adv烧录命令如下python -m esptool --chip esp32s3 -b 460800 -p PORT \ --before default_reset --after hard_reset \ write_flash --flash_mode dio --flash_size 8MB --flash_freq 80m \ 0x0 build-cardputer-adv/bootloader/bootloader.bin \ 0x8000 build-cardputer-adv/partition_table/partition-table.bin \ 0xd000 build-cardputer-adv/ota_data_initial.bin \ 0x20000 build-cardputer-adv/xiaozhi.bin \ 0x600000 build-cardputer-adv/generated_assets.bin将PORT替换为实际串口设备路径如 macOS 下的/dev/cu.usbmodem21101Linux 下通常为/dev/ttyACM*或/dev/ttyUSB*。构建可通过仓库的构建脚本完成脚本会解析 config.json 中的板卡类型并生成对应的 sdkconfig关闭 SPIRAM、选择 8MB 分区表再调用 ESP-IDF 工具链产出上述五个烧录文件。七、小结与延伸阅读Cardputer Adv 在 xiaozhi-esp32 中的支持是一个小屏幕卡片机板卡的典型样本一条 I2C 总线复用三个外设、无 MCLK 的 ES8311 I2S 适配、7x8 物理矩阵到 4x14 逻辑键盘的坐标重映射、纯键盘操作的 WiFi 配网状态机以及 8MB 双 OTA 2MB SPIFFS 资产分区。相关实现文件汇总文件职责README.md硬件规格、引脚、烧录指南config.h引脚/显示/音频/电池/键盘宏定义config.json构建变体与 sdkconfig 追加项m5stack_cardputer_adv.cc板卡初始化、按键功能、音频适配tca8418_keyboard.cc / tca8418_keyboard.h键盘驱动与 HID 键码表wifi_config_ui.cc / wifi_config_ui.h键盘 WiFi 配网 UI 状态机partitions/v2/8m.csv8MB 分区表adc_battery_monitor.h通用 ADC 电量监测组件【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考