企业官网建设流程全解析

小智 AI 助手 zhengchen-1.54tft-ml307 板卡全解析：双网络（WiFi + ML307 4G）架构、编译烧录与硬件适配

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

小智 AI 助手（xiaozhi-esp32）是一个基于 ESP32-S3 的开源 AI 语音对话机器人固件项目。本文聚焦其官方板卡zhengchen-1.54tft-ml307（正辰 1.54 英寸 TFT 屏 + ML307 4G 模组），结合 板卡 README 与仓库源码，完整讲解该板卡的编译配置命令、双网络切换原理、引脚定义、电源管理与高温告警机制，让读者既能在 5 分钟内完成固件编译烧录，也能深入理解其底层实现。

一、板卡概览：一块同时具备 WiFi 与 4G 双通道的语音交互板

zhengchen-1.54tft-ml307是 zhengchen（正辰）系列中带 ML307 4G 通信模组的版本，与同系列的zhengchen-1.54tft-wifi板卡共享显示与电源管理设计，核心差异在于网络接入方式：

• 默认通过ML307 4G Cat.1 模组联网，适合无 WiFi 覆盖的户外或移动场景；
• 同时保留WiFi 通道，可在两者之间运行时切换（长按 BOOT 键）。

板卡声明文件位于 main/boards/zhengchen/1.54tft-ml307/zhengchen-1.54tft-ml307.cc，类ZHENGCHEN_1_54TFT_ML307继承自DualNetworkBoard（双网络板基类），并通过DECLARE_BOARD宏注册进固件。其板卡类型在 config.json 中登记为zhengchen-1.54tft-ml307，编译目标为esp32s3。

二、编译配置与烧录命令（原文核心步骤）

依据 板卡 README，完整流程如下。

1. 设置编译目标

该板基于 ESP32-S3 芯片，首次配置需指定目标芯片：

idf.py set-target esp32s3

2. 打开 menuconfig 选择板卡

idf.py menuconfig

在图形化配置界面中依次进入：

Xiaozhi Assistant -> Board Type -> zhengchen-1.54tft-ml307

3. 编译固件

idf.py build

4. 烧录并监视串口日志

idf.py build flash monitor

执行后固件会烧录到开发板，并在当前终端实时显示设备日志（log 标签为ZHENGCHEN_1_54TFT_ML307，见 zhengchen-1.54tft-ml307.cc）。

5. 合并生成发布固件

如需生成可直接分发/量产烧录的完整合并固件：

idf.py merge-bin

说明：以上命令均依赖 ESP-IDF 环境。编译前请确保已按项目根目录 README.md 的说明完成 ESP-IDF 工具链（含 esp-adf 等组件）初始化，并已拉取 idf_component.yml 声明的依赖组件。

三、硬件资源与引脚配置（config.h 逐项解读）

板卡硬件映射全部集中在 main/boards/zhengchen/1.54tft-ml307/config.h：

音频方面，该板使用NoAudioCodecSimplex全双工直通编解码（见 zhengchen-1.54tft-ml307.cc）：输入 16 kHz、输出 24 kHz，I2S 麦克风与扬声器独立接线。

四、源码级深度解析：双网络（WiFi + ML307）如何协同工作

4.1 DualNetworkBoard 基类设计

main/boards/common/dual_network_board.h 定义了双网络板基类：

• 内部持有std::unique_ptr<Board> current_board_，根据NetworkType（WIFI/ML307）动态创建当前活动的网络板卡；
• 默认网络类型为ML307（枚举默认值），可通过Settings持久化保存与加载；
• SwitchNetworkType()负责运行时切换网络，GetNetworkType()返回当前类型，GetCurrentBoard()返回当前活动的板卡实例。

这就是"一块板卡同时承载 WiFi 与 4G"的底层机制：小智固件中的WifiBoard与Ml307Board在此被组合封装，应用层（对话、配网、状态上报）只面对统一的Board接口。

4.2 按键交互：从对话到网络切换

在 zhengchen-1.54tft-ml307.cc 中，按键逻辑非常清晰：

• BOOT 单击：先唤醒节能定时器；若当前处于 WiFi 网络且设备处于kDeviceStateStarting启动态，则进入 WiFi 配网模式（EnterWifiConfigMode）；否则切换对话状态（ToggleChatState）；
• BOOT 长按：调用SwitchNetworkType()在 WiFi 与 ML307 之间切换；
• 音量加/减单击：音量 ±10（0–100 范围），并在屏幕上弹出音量通知（ShowNotification）；
• 音量加/减长按：分别直达最大音量与静音。

4.3 电源管理与高温告警

板卡复用了同系列 1.54tft-wifi 的 PowerManager：

• 电池检测：通过 ADC 通道 7（12 位、衰减 12dB）采集电池电压，采用滑动平均（采样 3 次）与分段线性插值映射电量（ADC 2030→0%、2134→20%、2252→40%、2370→60%、2488→80%、2606→100%），每 60 个 tick 刷新一次；
• 低电量阈值：kLowBatteryLevel = 20，低于 20% 触发低电量回调；
• 温度监控：ESP32-S3 内置温度传感器，每 10 秒读取一次，温度变化超过 3.5°C 才触发回调（避免频繁刷新）；
• 高温弹窗：PowerManager将芯片温度通过OnTemperatureChanged回调传给显示层，zhengchen_lcd_display.h 中的UpdateHighTempWarning(chip_temp, threshold = 75.0f)在温度 ≥75°C 时弹出红色"温度过高"警告条（LV_PALETTE_RED背景、白色文字），低于阈值自动隐藏。

此外，InitializePowerSaveTimer使用 RTC GPIO2 保持外设供电，配合PowerSaveTimer(-1, 60, 300)实现 60 秒无操作进入低功耗、300 秒深度休眠的省电策略；充电状态下自动禁用节能定时器，拔电后恢复。

五、屏幕显示：ST7789 驱动的 240×240 LVGL 界面

显示初始化位于 zhengchen-1.54tft-ml307.cc：

• SPI3 总线，MOSI/SCLK 直连屏幕，最大传输240×240×2字节；
• 使用esp_lcd_new_panel_st7789创建驱动，SPI 模式 3、时钟 80 MHz、RGB 顺序、16 bpp；
• 启用颜色反转（esp_lcd_panel_invert_color(panel_, true)），并按DISPLAY_SWAP_XY / DISPLAY_MIRROR_X / DISPLAY_MIRROR_Y配置旋转镜像；
• 上层由ZHENGCHEN_LcdDisplay（继承SpiLcdDisplay）承载 LVGL 界面，负责表情、音量通知、高温告警等 UI 呈现。

六、与其他板卡的关系

zhengchen-1.54tft-ml307与 zhengchen-1.54tft-wifi 属于同系列姊妹板：两者共用相同的屏幕驱动ZHENGCHEN_LcdDisplay、相同的PowerManager电源管理、几乎一致的引脚分配（见两个目录下的 config.h），差异仅在于 ML307 版本额外引入 4G 模组引脚（GPIO11/GPIO12）并继承DualNetworkBoard。因此，从 WiFi 版迁移到 4G 版时，主要工作集中在网络层适配，显示与电源部分可直接复用。

七、常见问题与注意事项

1. 编译目标必须是 esp32s3：该板基于 ESP32-S3，若此前配置过其他目标，务必先执行idf.py set-target esp32s3；
2. 4G 联网需要实体 SIM 卡与天线：ML307 走运营商蜂窝网络，首次使用前确认 SIM 卡已激活、天线已连接，并在小智 App 中完成账号绑定；
3. 低电量保护：电量低于 20% 会触发低电量回调，建议及时充电；充电时节能定时器自动暂停；
4. 高温场景：长时间满负载运行时若屏幕弹出高温警告，说明芯片温度达到 75°C，请检查散热；
5. 合并固件：idf.py merge-bin生成的合并固件适合量产烧录，日常开发使用idf.py flash monitor即可。

结语

zhengchen-1.54tft-ml307以"WiFi + ML307 4G 双网络"为核心卖点，通过DualNetworkBoard抽象层实现了网络的无感切换，同时依托共享的PowerManager与 ST7789 显示驱动提供了完整的电量、温度监控与 LVGL 交互界面。借助本文的编译命令与源码剖析，开发者既可以快速把固件跑起来，也能在其基础上二次开发属于自己的双网络语音设备。相关可进一步阅读：板卡实现、双网络基类、电源管理。

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