企业官网建设流程全解析

xiaozhi-esp32 适配 NULLLAB AI-VOX3 语音开发板：硬件特性、板级驱动源码解析与固件构建指南

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32

AI-VOX3 是 NULLLAB 推出的一款专为 AI 语音交互设计的高性能 ESP32-S3 嵌入式开发板，本仓库（xiaozhi-esp32）已将其作为官方支持板卡纳入构建矩阵。本文以 板卡官方说明 为骨架，结合仓库内真实板级驱动源码，全面梳理 AI-VOX3 的硬件规格、引脚分配、双网络与电源管理实现、音频回声消除原理，并给出基于 ESP-IDF 的完整固件构建与烧录方法，帮助开发者快速上手二次开发与 DIY 扩展。

一、板卡概述：面向 AI 语音交互的五合一开发板

AI-VOX3 是 AI VOX 的升级款，核心采用ESP32-S3-R8芯片，板载 16 MB Flash，集五合一功能于一体：AI 聊天、天气时钟、无线对讲机、MP3 音乐播放器、网络电台，同时支持本地语音唤醒、指令识别和语音合成，可广泛应用于智能家居、教育设备和物联网终端等领域。

硬件设计上，其 PCB 尺寸兼容乐高插销，可直接安装在积木 C 款上，便于 DIY 搭建；配套 AI-VOX3 扩展板与 MD40 电机驱动板，开发者可以基于板载资源快速构建原型，并通过丰富接口实现个性化功能扩展，大幅缩短开发周期。

在本项目中，该板卡以nulllab-ai-vox-v3目录形式存在于 main/boards/nulllab-ai-vox-v3 下，其板级实现类AIVOX3继承自双网络基类DualNetworkBoard，同时支持 Wi-Fi 与 ML307 Cat.1 4G 两种联网方式，是仓库内"Wi-Fi + 4G 双网切换"的代表性板卡之一。

二、功能特点与硬件规格

原版 README 列举的硬件规格完整继承如下，并补充软件层面对应能力：

• 主控：ESP32-S3R8 高性能 Xtensa 32 位 LX7 双核处理器，主频高达 240 MHz，内置 512 KB SRAM、384 KB ROM 以及 8 MB PSRAM，板载 16 MB Flash 存储芯片。
• 无线：支持 2.4 GHz Wi-Fi（802.11 b/g/n）与 Bluetooth 5（LE），板载天线。
• 供电与下载：Type-C 接口，支持程序下载、板载供电及锂电池充电，兼容主流开发环境，简化开发与电源管理流程。
• 电源按键：采用电源复位按键二合一设计，短按开机或系统复位，长按关机，详见下文"Power 按键说明"。
• 显示：可接 1.54 寸 240×240 分辨率 SPI 接口 LCD（ST7789），提供直观图形化交互界面；预留 LCD 排线和 OLED 插口，可选择 OLED 或 LCD 彩屏显示。
• 音频：板载 ES8311 音频编解码器与 3 W 音频放大器（NS4150B），支持高保真音频输入/输出，需外接喇叭。
• 麦克风：双麦克风设计，板载模拟麦克风，还可外挂模拟麦克风，支持单麦打断。
• 存储：板载 SD Card 接口，支持大容量存储扩展。
• 交互外设：板载 BOOT 按键、2 个按键（GPIO46/45）及 WS2812B RGB 灯，便于交互调试与状态指示。
• 扩展接口：
  • 引出一组 8 个 GPIO 排针接口（GPIO43/44/42/48/4/3/2/1），支持多种外设接入；
  • 预留一个 4 pin PH2.0 接口，可方便通过 PH2.0 供电，也可与其他主控通讯；
  • 配套外接 AI-VOX3 扩展板，可通过其排针接口扩展更多功能；
  • 配套外接 MD40 电机驱动板，可运行多个电机。
• 电源管理：板载充电升压 5V 2.4A 输出一体电路，支持外接锂电池供电，并通过 IO18 ADC 实时检测电量（源码实现见下文第四节）。
• 开发环境：支持 ESP-IDF、Arduino IDE、AilyBlockly。

在软件侧，该板卡具备以下与本项目强相关的特性：

• 联网方式可于 Wi-Fi 与 ML307 4G 之间运行时切换（DualNetworkBoard支持）；
• ES8311 编解码器支持全双工音频，且可通过播放缓存软参考实现回声消除（AEC）；
• 板载 240×240 ST7789 LCD 可显示表情、通知与中文/多语言文本；
• 内置 RGB LED 作为状态指示灯，音量按键支持步进调节与静音/最大音量快捷操作。

三、Power 按键说明

AI-VOX3 取消了传统的 Reset 复位按键，改为使用Power 按键统一操作：

• 短按一次Power 按键：开机或系统复位；
• 长按Power 按键：关机。

该设计将系统复位与开关机集成到同一按键，简化了操作流程，也意味着开发阶段如需复位设备，直接短按 Power 键即可。若在使用中修改了配置或刷入新固件后需要重启，同样通过该按键完成。

四、板级驱动源码解析

4.1 板卡注册与构建入口

AI-VOX3 在项目中的接入点有三处：

1. Kconfig 菜单项：main/Kconfig.projbuild 中定义BOARD_TYPE_AI_VOX3，菜单显示名为 "NullLab AI Vox V3"，并depends on IDF_TARGET_ESP32S3，即仅支持 ESP32-S3 目标芯片。
2. CMake 板卡目录映射：main/CMakeLists.txt 中CONFIG_BOARD_TYPE_AI_VOX3对应BOARD_DIR "nulllab-ai-vox-v3"，并配置了默认中文字体（font_noto_sans_basic_20_4）、图标字体（font_material_symbols_20_4）与 emoji 集合（noto-color-emoji_64）。
3. 构建清单：config.json 声明type为nulllab-ai-vox-v3、target为esp32s3，并追加CONFIG_ESP_CONSOLE_NONE=y——即固件默认禁用 ESP 控制台输出。从引脚分配看，GPIO43/44 被复用为 ML307 4G 模块的串口（ML307_TX_PIN/ML307_RX_PIN），而这两个引脚恰是 ESP32-S3 默认 UART0 的 RX/TX，因此可以推断禁用控制台正是为了避免与 4G 模块串口通信冲突。

此外，docs/esp-idf-6-migration.md 记录该板卡已在 ESP-IDF 6.0.1 下通过完整构建验证，属于主分支 IDF 6.0.x 兼容板卡。

4.2 双网络架构：Wi-Fi 与 4G 的运行时切换

板卡实现类AIVOX3位于 ai_vox3_board.cc，构造函数中调用DualNetworkBoard(ML307_TX_PIN, ML307_RX_PIN, GPIO_NUM_NC, DEFAULT_4G_NETWORK)，其中DEFAULT_4G_NETWORK在 config.h 中定义为 0。

双网络机制定义在 main/boards/common/dual_network_board.h：DualNetworkBoard内部持有std::unique_ptr<Board> current_board_，根据NetworkType（WIFI或ML307）在WifiBoard与Ml307Board之间切换，网络类型会通过LoadNetworkTypeFromSettings/SaveNetworkTypeToSettings持久化到设置中。

在 ai_vox3_board.cc 中，BOOT 按键的长按事件被绑定为SwitchNetworkType()：当设备处于启动中或 Wi-Fi 配置状态时，长按 BOOT 键即可切换 Wi-Fi / 4G 网络类型；而 BOOT 键单击则在启动/配网阶段进入 Wi-Fi 配置模式，其余状态切换聊天会话状态（ToggleChatState）。这一设计让无 4G 模块的版本（DEFAULT_4G_NETWORK为 0）与带 ML307 模块的版本共用同一套固件逻辑。

4.3 音频通路：ES8311 全双工与软件回声消除

音频编解码器封装在 ai_vox3_audio_codec.h 的AIVOX3AudioCodec类中，继承自 main/audio/audio_codec.h 的AudioCodec抽象：

• I2S 全双工通道：CreateDuplexChannels使用I2S_NUM_0同时创建 TX/RX 通道，16 bit、立体声槽位、128 倍 MCLK，输入输出采样率均为 24 kHz（见 config.h 的AUDIO_INPUT_SAMPLE_RATE/AUDIO_OUTPUT_SAMPLE_RATE）。
• ES8311 配置：通过 I2C（SDA=GPIO13，SCL=GPIO12，地址ES8311_CODEC_DEFAULT_ADDR）控制，ESP_CODEC_DEV_WORK_MODE_BOTH双工模式，use_mclk=true。
• 回声消除（AEC）软参考：README 提到"支持单麦打断"，源码注释进一步说明——"板子不支持硬件回采，采用缓存播放缓存来实现回声消除"。当CONFIG_USE_DEVICE_AEC使能时（config.h 中AUDIO_INPUT_REFERENCE=true），Write()会将播放数据写入ref_buffer_环形参考缓存，Read()则将麦克风数据与参考数据交织成双通道送给 AEC 处理，实现全双工免提通话。BOOT 键双击还可在线切换 AEC 开关模式（ai_vox3_board.cc）。
• 输入增益与音量：EnableInput开启时将麦克风输入增益设为 37.5 dB；EnableOutput恢复上次音量；音量设置通过esp_codec_dev_set_out_vol写入 ES8311。

4.4 电源管理：ADC 实时电量检测

power_manager.h 实现了PowerManager，对应 README 中"通过 IO18 ADC 实时检测电量"的声明：

• 采样与滤波：InitializeAdc将BATTERY_LEVEL_PIN（GPIO18）配置为单次 ADC（oneshot），12 位位宽、12 dB 衰减；每 1 秒定时采样一次，维护 10 个样本的滑动窗口取平均值，抑制瞬时抖动。
• 电量换算：CalculateBatteryLevel将平均 ADC 值线性映射到百分比——ADC 值 ≤ 2048 记为 0%，≥ 2330 记为 100%，中间按比例换算（BATTERY_LEVEL_MIN/BATTERY_LEVEL_MAX定义于该类）。
• 充电检测：BATTERY_CHARGING_PIN（GPIO47）作为充电状态输入，带 5 次去抖；当电量已达 100% 时IsCharging()返回 false，不再显示"充电中"。

该电源信息通过AIVOX3::GetBatteryLevel（ai_vox3_board.cc）上报给上层应用，用于状态栏电量图标与低电量提示。

4.5 LCD 显示与背光

ai_vox3_board.cc 中：

• SPI 总线使用SPI3_HOST，最高 40 MHz 时钟，MOSI=GPIO21、CLK=GPIO17、CS=GPIO15、DC=GPIO14，复位脚GPIO_NUM_NC（由板载电路自动复位）。
• 面板为 ST7789 驱动、16 bit 像素、240×240 分辨率，DISPLAY_INVERT_COLOR=true、RGB 顺序、无镜像/无坐标交换（参数定义于 config.h）。
• 背光由PwmBacklight驱动（GPIO16，非反相输出），开机时RestoreBrightness()恢复上次亮度。

4.6 按键交互逻辑

板载 3 个按键（见 ai_vox3_board.cc）：

音量调节通过codec->output_volume() ± 10步进（上限 100、下限 0），并在 LCD 上弹出音量通知（Lang::Strings::VOLUME/MAX_VOLUME/MUTED多语言字符串），长按可一键最大音量或静音，方便免唤醒操作。

五、核心引脚速查表

以下引脚分配全部来自 config.h，供硬件接线与二次开发参考：

六、固件构建与烧录

AI-VOX3 属于 ESP32-S3 平台板卡，遵循仓库主分支推荐的 ESP-IDF 开发流程（项目 README 建议使用 ESP-IDF v6.0.2，该板卡已在 IDF 6.0.1 验证通过）。常规步骤如下：

1. 准备环境：安装 ESP-IDF v6.0.x（主分支推荐版本），建议使用 Linux 以获得更快编译速度与更少驱动问题。

2. 选择目标芯片并配置板卡：

   idf.py set-target esp32s3 idf.py menuconfig

   在 menuconfig 中选择 Board Type 为NullLab AI Vox V3（对应CONFIG_BOARD_TYPE_AI_VOX3，见 main/Kconfig.projbuild）。

3. 编译：

   idf.py build

   注意：该板卡的 config.json 会追加CONFIG_ESP_CONSOLE_NONE=y，因此固件默认不输出 ESP 日志到串口——如需查看日志，请通过 WebSocket/MQTT 调试通道或自行调整该配置项。

4. 烧录与监控：

   idf.py -p /dev/ttyUSB0 flash monitor

   设备通过 Type-C 口供电并下载程序。首次使用需通过手机热点/配网流程连接服务器，可注册 xiaozhi.me 账号免费体验 Qwen 实时语音模型；如需自建服务端，可参考仓库 README 中列出的 xiaozhi-esp32-server 系列开源项目。

七、总结与扩展建议

AI-VOX3 是一块"音频全双工 + 双网络 + 彩屏显示 + 电池供电"高度集成的 AI 语音开发板，在本仓库中的适配已覆盖构建配置、板级驱动、电源管理与交互逻辑全链路。对于开发者而言，可以在此基础上：

• 通过BOOT 键长按在 Wi-Fi 与 ML307 4G 间切换，评估两种联网方案的场景适用性；
• 借助8 个 GPIO 排针与 PH2.0 接口接入传感器、电机（MD40 驱动板）或扩展板，结合设备端 MCP 实现 AI 可见的 IoT 控制（参见 MCP 协议文档）；
• 在 main/boards/nulllab-ai-vox-v3 目录基础上修改 config.h 引脚映射，快速适配同型号衍生产品。

若你希望基于本项目自研板卡，可参考仓库的 自定义板卡指南 与 ESP-IDF 6.0 迁移指南，以 AI-VOX3 的板级实现为模板，在数小时内完成新板卡的接入与编译验证。

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32