无名科技星智 1.54 METAL (wifi) 实战速通：触摸交互、休眠电源管理与 ESP32-S3 编译烧录完整指南

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

xiaozhi-esp32 项目中的无名科技星智 1.54 METAL (wifi)，是一块用 CST816 触摸交互替代物理按键的 ESP32-S3 语音助手板卡。本文先带你完成 ESP32-S3 编译烧录，再讲清开关机、唤醒、配网三件事与休眠电源管理的底层原理。

一、先跑起来：把固件烧进这块板子

如果你刚拿到手，第一件事就是点亮它。整个过程不需要改动任何源码，一条命令链走完克隆、配置、编译、烧录：

git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32 idf.py set-target esp32s3 idf.py menuconfig # Xiaozhi Assistant → Board Type → 选中 "Nologo Xingzhi Metal 1.54-inch Wi-Fi (无名科技星智)" idf.py build idf.py build flash monitor

其中menuconfig是唯一的交互步骤：沿Xiaozhi Assistant→Board Type找到「Nologo Xingzhi Metal 1.54-inch Wi-Fi (无名科技星智)」一项打勾，最后build flash monitor一步完成下载固件并打开串口终端。

这块板卡在仓库中的构建声明位于 config.json：manufacturer为nologo、type为xingzhi-metal-1.54-wifi、target为esp32s3，sdkconfig_append是空数组——意味着它不额外追加 SDK 配置，直接沿用工程默认的 esp32s3 配置。

二、上手三件事：开关机、唤醒对话、重新配网

这块板子用「一块物理电源键 + 三个触摸区」承担全部操作。最常用的三个场景如下表，关键阈值都标出来了：

💡 配网窗口只有开机后的 1 秒，是最容易错过的操作——错过就长按电源键重启再来一次即可，不用进菜单。

三、音量到底怎么调：单击 vs 长按

音量由左、右两个触摸区分担，中间区是「boot 键」（唤醒 / 打断 / 配网入口），三者分工如下：

两种调节方式的差异在于节奏：

• 单击：每次固定 ±10，音量被钳制在 0~100（ES8311_VOL_MIN/ES8311_VOL_MAX）之间，同时屏幕弹出VOLUME xx通知提示当前值；
• 长按：先按住 2 秒触发连续调节，之后每 200ms 按步长 5 递增或递减一次，顶到上限/下限后自动停止，松手（LONG_PRESS_END）也会立刻停止。

原理上很简单：CST816x 芯片通过 I2C 上报触点坐标，板端守护任务按坐标分区 + 按压时长把原始触摸翻译成「单击 / 双击 / 长按开始 / 长按结束」四类事件，再分发到对应动作——所以长按不是“按得久一点”，而是有明确 2 秒阈值的独立事件。

四、它是怎么"自己省电"的：休眠与电源联动

对使用者的价值可以直接总结成三条：

1. 待命 60 秒→ 进入浅睡眠：屏幕亮度降到 1%、表情切换为sleepy、聊天记录清空，但设备仍可被唤醒；
2. 待命累计 300 秒（浅睡眠后继续计时）→ 深睡眠，也就是直接自动关机；
3. 插在 USB 充电时不休眠，拔掉充电线才重新计时；浅睡眠状态下单击中间触摸键即可唤醒，屏幕亮度恢复。

源码入口只有一行值得先看：板卡构造函数里用PowerSaveTimer(-1, 60, 300)创建休眠定时器，后两个参数就是 60 秒浅睡眠、300 秒关机；三个回调OnEnterSleepMode/OnExitSleepMode/OnShutdownRequest分别负责降亮度、恢复亮度、调用power_manager_->shutdown()。充电联动则由PowerManager的OnChargingStatusChanged回调驱动SetEnabled(false/true)，实现「充电时休眠定时器整体停用」。细节见 power_save_timer.h 与 xingzhi-metal-1.54-wifi.cc。

五、想改源码，从这几个入口看

全部文件都在 main/boards/nologo/xingzhi-metal-1.54-wifi/ 下，按「先入口、后细节」的顺序导航：

• xingzhi-metal-1.54-wifi.cc：板卡类XINGZHI_METAL_1_54_WIFI（继承WifiBoard）。构造函数初始化顺序是电源管理 → 休眠定时器 → I2C（扫描地址 1~126，命中0x15才认为触摸芯片在位）→ SPI → ST7789 屏幕 → 触摸任务；三个休眠回调和充电联动逻辑也都在这里。
• cst816x.h：TOUCH_THRESHOLD_TABLE定义三个触摸分区（x 坐标 20 / 40 / 60，y 均为 600）及单击 200ms、双击窗口 240ms、长按 2s（boot 区 4s）等阈值；VOL_ADJ_INTERVAL_US（200ms）、VOL_ADJ_STEP（5）控制长按连续调音量。
• cst816x.cc：touchpad_daemon主循环每 40ms 轮询一次，UpdateTouchPoint()从寄存器0x02读 6 字节解析触点；分区事件分发与音量调节逻辑都在这个循环里。
• power_manager.h：PowrSwitch()用 200ms 周期定时器轮询电源键完成开关机判定；CheckBatteryStatus()/ReadBatteryAdcData()负责充电判定（USB ADC 落在 1500~4000 区间视为充电）与电量换算（标定点1970→0%、2062→20%、2154→40%、2246→60%、2338→80%、2430→100%，低电量阈值 20%）；shutdown()在充电时拒绝关机、拉低电源控制脚失败后以esp_deep_sleep_start()兜底。
• config.h：所有引脚与显示/音频参数。

关键引脚一览（来自config.h）：

六、常见问题与排查

⚠️ 触摸完全无响应先看串口日志里有没有Device found at address 0x15。板卡启动时会扫描 I2C 总线 1~126 地址，只有探测到触摸芯片（0x15）才会创建触摸任务，否则整个触摸链路不会启动。若能看到Get CST816x chip ID日志说明芯片通信正常，此时检查触摸是否落进了TOUCH_THRESHOLD_TABLE的三个分区坐标——落在分区外的触摸本来就不会有动作。

进不去配网界面配网入口是「开机后 1 秒内单击中间触摸键」，且要求设备仍处在启动状态（kDeviceStateStarting）。窗口极短，最常见的失败原因就是点晚了。重启设备、在屏幕上刚亮起时立刻单击中间区即可；若仍无效，确认选中的是 Wi-Fi 版本（xingzhi-metal-1.54-wifi）固件。

插着 USB 关不掉机这是设计行为而非故障：shutdown()开头就检查充电状态，检测到插入 USB 时直接返回（日志会打印「检测到插入usb，无法关机」）。先拔掉 USB 线，再长按电源键 5 秒即可正常关机。

七、延伸：还能怎么定制

板卡把可定制点收敛得很干净，改哪个维度就看哪个文件：

• 触摸分区与事件阈值：想挪动分区位置、改长按判定时间或音量步长，全部在 cst816x.h 的TOUCH_THRESHOLD_TABLE、VOL_ADJ_INTERVAL_US、VOL_ADJ_STEP三个位置；
• 休眠与电源策略：60s/300s 的休眠节奏在 xingzhi-metal-1.54-wifi.cc 的PowerSaveTimer构造参数与三个回调里；电量标定点、充电判定区间、关机兜底逻辑在 power_manager.h；
• 交互能力扩展：xiaozhi-esp32 本身是基于 MCP 协议的项目，设备端控制与云端工具都能通过 MCP 继续扩展，思路可参考 docs/mcp-usage_zh.md 与 docs/mcp-protocol_zh.md；
• 移植到自己硬件：流程见 docs/custom-board_zh.md，把本文第五节的引脚表和初始化顺序当成模板即可。

到这里，这块板子「怎么烧、怎么用、怎么改」就都齐了：你可以直接复现第一节的命令链完成首次烧录，按第二、三节的表格完成日常操作，也能顺着第五节的入口把触摸分区、休眠时长、电量标定改成适合自己产品的参数。

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