星智 1.54 METAL 触摸交互完整指南一键烧录固件、分区解析触控、拆解电源状态机【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32开篇导读无名科技星智 1.54 METAL (wifi) 是一款以 ESP32-S3 为主控、CST816 触控替代物理按键的触摸交互开发板铝合金外壳下集成 1.54 寸 ST7789 屏与 ES8311 音频链路。以下按构建、交互、电源策略、源码结构四个维度展开先走通克隆到烧录的命令链再解析触控分区判定、浅睡与深睡机制最后落到初始化链路和可定制点。构建与烧录从零烧录固件的完整命令链本章将固件运行前置覆盖从环境准备到串口监视的每一步。前置条件是已安装并激活对应 ESP-IDF 版本的环境变量。执行以下命令克隆仓库git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32将芯片目标设置为 ESP32-S3idf.py set-target esp32s3打开 menuconfig 并选择板卡idf.py menuconfig # 菜单路径Xiaozhi Assistant → Board Type → 无名科技星智1.54 METAL(wifi)执行编译与烧录并打开串口监视器idf.py build flash monitor该板卡的构建元数据位于main/boards/nologo/xingzhi-metal-1.54-wifi/config.json字段含义如下字段取值含义manufacturernologo厂商目录名对应main/boards/下的无名科技typexingzhi-metal-1.54-wifi板卡唯一标识menuconfig 中按此匹配targetesp32s3编译目标芯片决定 SDK 与工具链sdkconfig_append空数组该板卡不追加额外 SDK 配置沿用 esp32s3 工程默认硬件规格速览一张表覆盖主控、显示、触摸、音频、通信、电源六个模块。模块芯片或型号关键参数源码位置主控ESP32-S3编译目标esp32s3config.json显示ST7789240×240、16bpp、RGB 序、80MHz、色彩反转开启xingzhi-metal-1.54-wifi.cc触摸CST816I2C 地址 0x15轮询周期 40mscst816x.cc音频ES8311输入/输出均 24000Hz 采样率输入开启参考PA 使能 GPIO21xingzhi-metal-1.54-wifi.cc通信Wi-Fi板卡类继承WifiBoard无蜂窝模块xingzhi-metal-1.54-wifi.cc电源内置PowerManager电量 ADC 在 GPIO7USB 插入检测 ADC 在 GPIO1power_manager.h与同系列上一代相比星智 1.54 METAL 将外壳升级为铝合金交互由物理按键改为三区触摸。开关机时序也有变化旧版长按电源键 1 秒即可开机本版调整为长按 3 秒旧版插入 USB 时不会自动关机本版在检测到 USB 插入时于软件层主动拒绝关机并输出对应日志。交互行为解析触摸芯片坐标分区原理全部交互可归纳为一张操作映射表触发区域均为屏幕下方的虚拟触摸区。操作触发区域系统行为源码入口开机电源键物理关机状态长按 3 秒自动开机power_manager.h关机电源键物理开机状态长按 5 秒自动关机power_manager.h唤醒 / 打断中间触摸区单击切换通话状态cst816x.cc重新配网中间触摸区开机启动阶段单击重启并进入配网cst816x.cc增加音量右侧触摸区单击 10长按连续递增cst816x.cc减小音量左侧触摸区单击 −10长按连续递减cst816x.cc浅睡眠唤醒中间触摸区单击恢复表情与背光亮度xingzhi-metal-1.54-wifi.cc从源码看分区判定基于一张阈值表。触摸坐标精确命中表中登记点时才启用对应阈值未命中则回退到默认配置。该表定义于 cst816x.h// TOUCH_THRESHOLD_TABLE{x, y, 单击最长时长, 双击窗口, 长按阈值}单位 us {20, 600, 200000, 240000, 2000000}, // 源码注释音量 {40, 600, 200000, 240000, 4000000}, // 源码注释boot 按键 {60, 600, 200000, 240000, 2000000} // 源码注释音量-三个区域 Y 坐标均为 600X 坐标分别为 20、40、60。单击最长时长 200ms双击判定窗口 240ms左右音量区长按阈值 2000ms中间区为 4000ms。需要留意源码注释标注 x20 为音量、x60 为音量−与板卡 README 表格的左右描述相反定制前以实际触摸坐标与代码行为为准。事件判定是一段显式状态机运行于touchpad_daemon任务每 40ms 轮询一次触摸寄存器。在 cst816x.cc 的状态转移中按下沿记录起始时间戳复位长按标记。持续按压当前时间超过长按阈值时发出LONG_PRESS_START并置位防止重复触发。松手沿若长按已触发则发出LONG_PRESS_END若按压时长不超过 200ms则单击计数加一。非触摸态距上次释放超过 240ms 的窗口期结束时计数为 1 发出SINGLE_CLICK计数为 2 发出DOUBLE_CLICK。事件分发还有三个特殊分支均在y600且 x 命中 20/40/60 时生效设备状态为kDeviceStateStarting开机启动阶段时中间区单击调用EnterWifiConfigMode()进入配网对应开机 1 秒内单击重新配网。浅睡眠期间单击中间区先调用SetPowerSaveLevel(PowerSaveLevel::PERFORMANCE)唤醒PowerSaveTimer随后切换通话状态。其余状态下单击中间区调用ToggleChatState()完成唤醒或打断。音量参数集中在守护任务尾部见 cst816x.cc单击步幅 ±10范围钳制在ES8311_VOL_MIN(0) 至ES8311_VOL_MAX(100)每次调整后弹出VOLUME xx屏幕通知。长按连续调节间隔 200msVOL_ADJ_INTERVAL_US步长 5VOL_ADJ_STEP。到达上限或下限后自动停止并记录日志。电源与休眠 浅睡深睡与充电联动的状态机行为休眠策略由PowerSaveTimer管理状态流转可用一条时间线概括。待机 ─── 60s ───▶ 浅睡眠亮度 1% ─── 累计 300s ───▶ 深睡眠自动关机 ▲ │ └──────────────── 触摸中间区 / 任何活跃唤醒 ◀──────────────────┘构造函数中的实例化见 xingzhi-metal-1.54-wifi.cc参数含义对应 power_save_timer.h 的声明power_save_timer_ new PowerSaveTimer(-1, 60, 300); // cpu_max_freq-1 表示不调整 CPU 频率60s 进入浅睡300s 请求关机浅睡眠触发条件为空闲满 60 秒且无活跃请求。OnEnterSleepMode回调清空屏幕聊天消息、将表情切换为sleepy、把背光降到 1%。唤醒由OnExitSleepMode回调恢复表情为neutral并调用RestoreBrightness()还原亮度触发来源是触摸事件与WakeUp()。深睡眠浅睡累计至 300 秒触发OnShutdownRequest回调调用power_manager_-shutdown()。在 power_manager.h 中shutdown()先关闭背光、拉低Power_ControlGPIO48切断主电源若硬件未随之断电则对电源键脚 GPIO47 输出 14 组 100ms 高低脉冲模拟长按最终仍未断电时调用esp_deep_sleep_start()兜底。USB 插入状态下直接跳过硬件断电仅打印无法关机的日志。充电联动OnChargingStatusChanged回调在充电时调用power_save_timer_-SetEnabled(false)非充电时恢复启用见 xingzhi-metal-1.54-wifi.cc。GetBatteryLevel中还有一层同步放电状态发生翻转时按放电与否重新设置定时器使能见 xingzhi-metal-1.54-wifi.cc。电池检测基于两个 ADC 通道POWER_USBIN_ADC_CHANNELGPIO1判定 USB 插入取值落在 (1500, 4000) 区间视为充电中POWER_BATTERY_ADC_CHANNELGPIO7读取电量。ADC 配置为ADC_UNIT_1、12 位、12dB 衰减。检测定时器周期 1 秒每累计 60 个 tick 采样一次取 3 次滑动均值后按标定点做线性插值ADC 均值197020622154224623382430电量百分比0%20%40%60%80%100%低于 20% 时触发低电量状态回调见 power_manager.h。底层实现拆解上电初始化链路与 GPIO 分配构造函数按固定顺序完成六个 bring-up 步骤全部位于 xingzhi-metal-1.54-wifi.cc。步骤做了什么关键参数源码位置1初始化电源管理电源键脚 GPIO47、控制脚 GPIO48 拉高200ms 控制定时器与 1s 电池定时器power_manager.h2初始化休眠定时器60s 浅睡、300s 关机注册三个回调xingzhi-metal-1.54-wifi.cc3初始化 I2C 并探测芯片I2C_NUM_0SDA/SCL 为 GPIO41/42内拉扫描地址 1~1260x15 命中记为存在 CST816xingzhi-metal-1.54-wifi.cc4初始化 SPI 总线SPI3_HOSTMOSIGPIO10、SCKGPIO9DMA 缓冲按 240×240×16bpp 计算xingzhi-metal-1.54-wifi.cc5初始化 ST7789 面板80MHz、SPI mode 3、16bpp、RGB 序、invert_color(true)创建SpiLcdDisplayxingzhi-metal-1.54-wifi.cc6启动触摸守护任务仅当探测到 0x15 时创建Cst816x任务栈 2048优先级 1cst816x.cc触摸数据读取通过 I2C 拉取寄存器0x02起的 6 字节首字节低 4 位为触点数量后 4 字节按高 4 位 低 8 位解析出 (x, y)见 cst816x.cc。音频编解码使用Es8311AudioCodec与显示 I2C 共用I2C_NUM_0总线PA 使能脚为 GPIO21输入参考开启AUDIO_INPUT_REFERENCE见 config.h。全部 GPIO 汇总如下类别宏名GPIO用途音频AUDIO_I2S_GPIO_WS4I2S 时钟音频AUDIO_I2S_GPIO_MCLK5I2S 主时钟音频AUDIO_I2S_GPIO_BCLK6I2S 位时钟音频AUDIO_I2S_GPIO_DIN17I2S 输入麦克风音频AUDIO_I2S_GPIO_DOUT15I2S 输出扬声器音频AUDIO_CODEC_I2C_SDA_PIN41编解码 I2C SDA与触摸共用音频AUDIO_CODEC_I2C_SCL_PIN42编解码 I2C SCL与触摸共用音频AUDIO_CODEC_I2C_PA_EN21功放使能由 PCA9557 扩展控制屏幕DISPLAY_SDA10SPI MOSI屏幕DISPLAY_SCL9SPI SCK屏幕DISPLAY_DC8数据/命令选择屏幕DISPLAY_CS14片选屏幕DISPLAY_RES18面板复位屏幕DISPLAY_BACKLIGHT_PIN13PWM 背光电源POWER_USB_IN1USB 插入 ADC 检测电源Power_Control48电源控制输出电源Power_Dec47电源键检测与关机脉冲输出电源POWER_BATTERY_ADC_CHANNEL7电池电量 ADC按键BOOT_BUTTON_GPIO0BOOT 按键定制与扩展最小改动的三个定制路径面向想直接改参数、看效果的场景三个改动点均可在单文件内完成。调整休眠阈值修改 xingzhi-metal-1.54-wifi.cc 中PowerSaveTimer构造的 60 与 300 两个实参即改变浅睡与关机的触发时刻。改变浅睡亮度将OnEnterSleepMode回调中SetBrightness(1)的实参调整为 0~100 之间任意值屏幕在浅睡期间保持对应亮度。移动或收窄触控区修改 cst816x.h 的TOUCH_THRESHOLD_TABLE调整 (x, y) 命中点即可平移分区修改long_press_thresh_us可改变左右音量区 2s 的长按起调时刻。注意阈值表只做精确坐标匹配坐标偏移过大将回退到默认阈值建议同步验证触摸上报。可复用组件的继承关系值得先梳理避免重复实现PowerSaveTimer定义于main/boards/common/power_save_timer.h负责空闲计时、CPU 降频与三个回调的注册。Es8311AudioCodec继承自main/audio/audio_codec.h的AudioCodec封装 ESP-Codec-Dev 数据与寄存器控制接口。SpiLcdDisplay继承自main/display/display.h的Display屏蔽 SPI 帧缓冲刷新细节。板卡类XINGZHI_METAL_1_54_WIFI继承WifiBoard末尾由DECLARE_BOARD宏注册进工厂。参考入口内容路径板卡 READMEmain/boards/nologo/xingzhi-metal-1.54-wifi/README.md构建配置main/boards/nologo/xingzhi-metal-1.54-wifi/config.json板卡主实现xingzhi-metal-1.54-wifi.cc引脚定义config.h触摸驱动cst816x.cc、cst816x.h电源管理power_manager.h下一步可深入三个方向触摸驱动阈值表的精确坐标匹配为何如此设计PowerManager中 14 组 100ms 脉冲关机的硬件依据以及PowerSaveTimer内esp_pm与esp_timer的协作方式。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考