开始使用
- 让电脑或手机与 StackChan 处于同一局域网。
- 使用 Chrome 或 Edge 打开 Hi Chan，设备地址可直接用
stackchan.local:8032。 - 连接成功后即可控制应用、舵机、摄像头和设置；语音与点歌需要先进入 AI Agent。
进入 Agent 后直接说唤醒词，再说“播放周杰伦的歌”“放点安静的音乐”或其他指令。
怎么找到设备地址
固件会广播 mDNS，主机名就是 stackchan.local，所以设备地址栏直接填 stackchan.local:8032 通常就能连上，换 Wi-Fi、换 IP 都不用改。个别代理软件会劫持 .local 域名，这时改填路由器里看到的设备 IP，端口仍是 8032。设备屏幕上直接访问 http://设备IP:8032/ 也会自动跳到 Hi Chan 并带上地址。
Hi Chan 是 HTTPS 页面，要去调你局域网里的 HTTP 设备，这依赖 Chromium 的“本地网络访问”预检机制。Firefox 和 Safari 会按混合内容直接拦截，表现为怎么点都连不上。
浏览器是直接连设备的，状态数据和固件文件都不经过云端。设备 API 没有鉴权，只为局域网使用——不要把 StackChan 的 8032 端口映射到公网。
屏保行情
停留在 Launcher 且约 30 秒没有操作时，会进入行情跑马灯屏保。设备只在屏保显示期间拉取数据，退出后停止请求。
修改显示内容
- 在 Hi Chan 连接设备，打开“设置 → 屏保行情”。
- 选择资产类型并填写代码，最多 8 项。股票、ETF 与指数选“股票”；BTC、ETH 等选“加密货币”；黄金选“大宗商品”并填
GOLD。 - 点击“保存行情”。选择“恢复默认”会重新显示 BTC、SPACEX、MU 和 GOLD。
不同市场可能存在同名代码，显式选择可以避免把股票和加密货币查混。
设备约每 60 秒拉取一次，服务端缓存约 30 秒；行情变化最晚约 90 秒出现。
小智音乐播放服务
说“播放告白气球”会搜索并播放这一首，也支持故事、评书、相声、播客和有声书。
说“播放周杰伦的歌”“放点轻音乐”或“播放某个歌单”，会一首接一首播放，默认随机，直到通过屏幕或控制台停止。
首次播放未缓存的内容需要搜索、下载和转码，开始时间可能比已缓存歌曲长一些。播放过程中会流式传输，不必等整首下载完成。
音乐联动
在“设置 → 声音与特效”中可以分别开关：
- 麦克风造型：唱歌时显示陶醉表情和麦克风动画。
- 张嘴：嘴型跟随播放节奏变化。
- LED 灯带：12 颗灯显示滚动律动。
- 摇头：在点头、摇头和探头动作之间随节奏变化。
- 放歌暂停唤醒：默认开启，可显著降低 CPU 占用；关闭后播放时仍可用唤醒词。
服务地址
“网络歌曲播放服务”留空时会使用内置默认地址，但该服务器需要申请加入白名单后才能使用。目前服务器没有多账号隔离功能，所有人的播放记录会显示在一起，因此暂时不对外分享。建议优先部署自己的兼容音乐服务，并在设置中填写地址后保存。
如需使用，请联系 @tankxu 购买。
默认配置下，音乐播放时会暂停语音监听，因此不能通过“停止播放”口令结束。请点击控制台“停止播放”，或在放歌时双击屏幕停止并回到待机。放歌时单击屏幕不会中断音乐。
触摸、音量与状态灯
头顶最后一块触摸板调音量
使用头顶触摸条最靠后、远离脸部的最后一块：
- 短按后松开：音量 +10
- 长按：音量 −10，继续按住会连续降低
- 每次调整会在屏幕上显示新的音量，范围为 0–100，并保存到设备。
前面的触摸区域仍用于摸头互动；滑动会被识别为摸头动作，不会误调音量。也可以在 Hi Chan 的“控制”页拖动音量条精确调整。
屏幕和唤醒
- Agent 中可说默认唤醒词“你好小智”开始对话。
- 放歌时双击屏幕停止播放并回到待机。
- 非播放状态点击屏幕可进入或切换对话状态。
灯带状态
主动互动与问候
StackChan 不只是被动等唤醒。在“设置 → 主动互动”里打开主动搭话后，它会在你安静太久时自己开口关心一句，也可以在固定时刻问候。关掉这个开关就完全不再自主开口，但摸头、唤醒这些由你触发的回应仍然照常。
| 设置项 | 默认 | 说明 |
|---|---|---|
| 空闲后主动关心 | 90 分钟 | 多久没人理它就开口一次。没人应答会自动拉长间隔（最多拉到 16 倍），不会一直骚扰你。 |
| 最小互动间隔 | 30 分钟 | 两次主动开口之间至少隔这么久，防止连着说。 |
| 夜间静音 | 22 时 – 8 时 | 这段时间内不主动开口。起止填成同一个数就是全天不静音。 |
| 定时问候 | 08:30,12:30,21:00 | 逗号分隔，最多 8 个时刻，每个有 1 小时的触发窗口。留空就不定时问候。 |
8:30 这种缺前导零的形式。主动搭话需要设备处于 AI Agent 且已联网——它本质上还是走一次正常对话。
屏幕、待机与省电
屏幕背光
“设置 → 屏幕与待机”里拖动即可，范围 1–100，改完立即生效并记住。
0 会直接关掉屏幕电源让屏幕全黑，而且没法在设备上点回来。控制台已经把范围限制在 1 以上。另外，调暗几乎不能降温：实测从 75 调到 10 只降约 1°C，它的用途是夜里不刺眼，不是散热。
待机自主动作
没人理它的时候，脑袋会自己慢慢转。吵不吵取决于转速而不是幅度——慢慢转过去幅度再大也基本无声，快速动一下哪怕几度也会“咔”一声。所以动作分成两种：绝大部分时间是 3–4.5 秒完成的慢慢左顾右盼，偶尔来一次 1 秒左右的大幅度扭头，像突然被什么吸引。正因为后者稀少，它才像“注意到了什么”而不是噪音。
| 档位 | 小动间隔 | 大动间隔 | 感觉 |
|---|---|---|---|
| 关闭 | — | — | 完全静止 |
| 低 | 100–200 秒 | 10–20 分钟 | 几乎察觉不到它在动 |
| 中（默认） | 45–90 秒 | 5–10 分钟 | 安静地打量四周，偶尔被什么吸引 |
| 高 | 20–45 秒 | 2–4 分钟 | 明显活泼，适合有人在旁边互动时 |
这套动作是进入 Agent 时创建的，不会热更新。改了档位觉得没变化，退出 Agent 再进一次即可。放歌时这套逻辑整体让位给音乐律动，两边都在驱动同一对舵机。
空闲自动关机
同一块面板里可以设置空闲多少分钟自动关机，填 0 就永不自动关机。
需要注意省电策略只看设备是不是在用电池放电：插着 USB 时通常不会熄屏也不会自动关机；一旦拔掉电源转为电池供电，熄屏、降频和自动关机才会开始计时。所以“它怎么自己黑屏了/关机了”先看供电方式，诊断页的“电源”一栏会直接告诉你当前是充电中、外接供电还是电池供电。
Wi-Fi 与联网
预存多个网络，换地方免配网
“设置 → Wi-Fi 管理”可以存最多 10 个网络。设备开机扫描后会在已存列表里按信号强度挑一个连，所以把家里、公司、常去的地方都提前存好，搬到哪儿都能自己连上。同名网络再存一次就是更新密码。密码永远不会回显，列表里只看得到网络名。
没有已知网络时怎么配网
设备连不上任何已存网络时会自己开一个热点，手机连上去后在弹出的网页里填 Wi-Fi 即可。Launcher 下开机联网试 25 秒放弃，进入 Agent 后会重新独立地再试一轮，最多 60 秒才弹配网提示——所以在陌生环境下别急着断定它坏了。设置菜单里没有配网入口，配网统一走这条路。
设备记住了上次连接的信道和 IP，开机只扫那一个信道、直接复用上次地址。换了路由器或换了地方也不会卡住，扫不到会立刻回落到全信道重扫。
觉得连服务端很慢
别猜，用“诊断 → 网络诊断”量一下：它把一次完整连接拆成 DNS 解析 / TCP 建连 / TLS 握手三段分别计时。健康值是 DNS 低于 150 毫秒、TCP 低于 100 毫秒、TLS 0.6–1 秒。TLS 慢是正常的，这颗芯片没有加密硬件加速，软算就是这个量级。
如果 DNS 那一段动辄好几秒，那是 DNS 服务器的问题——运营商下发的主 DNS 不响应时，设备要等它超时才会换备用的。固件因此默认不使用路由器下发的 DNS，而是固定用两家公共 DNS，实测把进入 Agent 的等待从 8 秒压到 1.1 秒。
头部动作
“控制 → 头部舵机”可以直接把脑袋转到指定角度：左右 −128°–128°，上下 −90°–90°，还能选转动速度。刷新按钮读的是当前实际位置，刚下完指令舵机还在转，想确认到位就隔一两秒再读一次。语音说“往左看”走的也是同一条链路。
待机时大约四分之三的时间扭矩是松开的、可以轻轻扭动，但正在做动作的时候是掰不动的，硬来会损伤舵机。指令失效多半是舵机进了堵转保护，重启设备即可解除。
设备自带堵转保护：检测到转不动会退避并临时收窄可动范围，过一会儿自动恢复，不需要你干预。
ESP-NOW 遥控
兼容的 ESP-NOW 遥控器可以直接发送左右、俯仰和移动速度，临时接管 StackChan 的头部舵机；停止发送一段时间后，设备会回正并恢复表情与音乐律动控制。
- 先让 StackChan 的 Wi-Fi 初始化完成，并进入 AI Agent。
- 让遥控器使用相同无线信道；最简单的方式是让两边连接同一个 Wi-Fi。
- 遥控器 ID 为 0 时使用广播控制；其他 ID 用于区分目标设备。
常驻接收目前依赖 Agent 中运行的更新任务，Launcher 页面下可能没有反应；遇到这种情况先进入 Agent。遥控停止后约 10 秒释放接管。
Bilibili App
Bilibili App 可以在 StackChan 上浏览热门视频、分区内容、封面与详情，并播放完整画面和声音。播放页点击画面可显示暂停、进度和返回控制。
B 站视频使用的 H.264 格式无法由 ESP32-S3 直接解码。电脑端服务会实时拉取视频，并转换成 StackChan 可以播放的 320×240 画面和音频；播放期间电脑必须保持开机，且不能让服务休眠退出。
连接电脑服务
- 让电脑和 StackChan 连接同一个局域网，并确认电脑已安装 Python、aiohttp 和 ffmpeg。
- 在配套服务目录运行
PORT=2233 python3 app/bili_srv.py。 - 在 Hi Chan 打开“设置 → 服务地址”，把“B 站转码服务”填写为
http://电脑IP:2233并保存。 - 从 Launcher 打开 Bilibili App。若无法连接，请检查电脑防火墙是否允许局域网访问 2233 端口。
扫码登录自己的账号
配套服务支持生成 B 站登录二维码。使用自己的哔哩哔哩手机客户端扫码并确认后，即可使用自己的账号登录；热门和普通分区不登录也能浏览，账号相关内容需要登录。
账号 Cookie 由配套服务保存在运行它的电脑上，不会写入 StackChan。请只在自己信任的电脑上运行服务，不要把服务端口暴露到公网。
小宇宙播客
Launcher 里的 Podcast 应用可以浏览推荐、最新和订阅，点开频道看单集列表，并在播放页控制播放。三个标签页的内容形态不同：推荐给的是单集（横条列表），最新和订阅给的是频道（方形卡片），点进频道才是它的单集列表。
在 Hi Chan 打开“设置 → 服务地址”，把“小宇宙播客服务”填成配套服务的设备反代口
http://电脑IP:23021。注意不是 23020 那个 API 网关端口，填错了设备取不到音频。设备上没法从命令行模拟触摸，控制台“控制 → 播客遥控”提供了等价操作：切标签页、点开列表第 N 条、进入频道、返回。它只在小宇宙应用已经处于设备前台时有效，不在前台时指令不产生任何效果。
红外遥控（界面原型）
Launcher 里的 REMOTE 应用现在是界面原型：点按钮、或在 Agent 里说“把灯打开”“风扇开三档”，改动的只是设备内部记着的那份状态，屏幕上的开关和档位会跟着变——但机器上没有接红外发射头，不会真的发出遥控码，电视和灯不会有任何反应。
之所以先把这一层做出来，是因为难的部分不在发码，而在两个入口共用一份状态：触屏界面只活在 Launcher，而语音走的 MCP 工具只在 Agent 模式下存在，那时应用本身已经被销毁了。所以状态和执行逻辑放在两种模式都在的底层，界面只是它的一个视图——按钮调用它、渲染读取它。
接上红外发射头之后，只需在底层那一处补上发码，触屏和语音两条路会同时获得真实发射能力，界面和语音都不用改。当前可以用它预览交互和界面，也可以验证语音能不能正确理解“开灯”“调到三档”这类指令。
小鸡下蛋
Launcher 里的 HAPPY CHICKEN 是个不用动脑的小玩意儿：点屏幕任意位置，母鸡就在那儿下一个蛋，右上角的云朵里累计计数 +1。
- 一批最多 8 个蛋。停手约 1 秒后开始孵化，蛋一个接一个裂开，小鸡陆续钻出来。
- 小鸡出生后自己到处溜达，约 12 秒长大，长大后就朝画面外走掉，给后面的腾位置。同屏最多 8 只。
- 累计孵出 10 只以后，偶尔会蹦出一只彩色的小鸡（大约十分之一的概率，五种颜色）。
- 计数是本次累计的下蛋数，退出应用就清零，不存档也不排行。
它调的是小智那套音频服务，而这套服务只在进入 AI Agent 时才初始化；这个游戏只在 Launcher 里跑，而从 Agent 退回 Launcher 又会重启设备，于是音频服务在玩它的时候始终没就绪。代码每秒重试一次等它就绪，所以不会报错也不会卡，只是一直静音。
沙漏倒计时
Launcher 里的 HOURGLASS 是个计时器。进去先看到三个大小不同的沙漏，由小到大分别是 5 / 15 / 30 分钟，点哪个就按哪个开始，会响一声短音作为确认。
- 计时页里沙子按剩余比例往下流，底部是
分:秒的读数。 - 时间到：三组「滴滴滴」，一组比一组高，最后落一个长音收尾。数字变成金色停在 00:00 不自动返回，这样你离开一会儿回来也知道它已经响过了。
- 计时途中点一下屏幕，背景压暗并浮出返回按钮；3 秒不点它自己收回去，免得挡着看沙漏。
它不走小智的音频服务，而是直接驱动扬声器发音，所以不需要进 Agent。
截图与通知
屏幕截图
“控制 → 屏幕截图”把设备当前画面抓回浏览器，可以按 0.5 / 1 / 2 FPS 做实时预览，也可以点“截图”抓一张单独保存或复制。截图包含顶层图层，所以通知横幅和调试 HUD 都能看到。
默认勾选的“抓图前先唤醒屏幕”会先把屏保赶走再抓，代价是每张多约 0.4 秒。想看屏保长什么样，把它取消勾选即可。
推送通知
“控制 → 推送通知”把外部状态推到设备屏幕上，四个等级依次加码：
- toast：顶部横幅，到点自动消失，不打断当前操作。
- alert：横幅加提示音，需要留意的事情用它。
- speak：横幅、提示音，再让小智开口说一句。
- dialog：全屏卡片加按钮，等人在设备上拍板；控制台会轮询结果并显示按了哪个。
| 等级 | 在 Launcher | 在 AI Agent |
|---|---|---|
| toast | 横幅 | 横幅 |
| alert | 横幅，无声 | 横幅 + 提示音 |
| speak | 横幅，无声、不说话 | 横幅 + 提示音 + 小智开口 |
| dialog | 全屏卡片 + 触摸交互 | 同左 + 提示音 |
音频服务是进入 Agent 时才启动的，所以在 Launcher 下通知不会整条丢失，只是降级成没有声音。要声音就先让设备进 Agent。
设备本地没有语音合成，唯一能让它说任意内容的办法是把文本当作“你说的话”发给服务端，再由模型回应——所以措辞由模型决定，实际效果形如你发“会话已完成”，它说“好的，收到通知。”。这条通道对长度卡得很死，文本会被裁到约 12 个汉字，而且需要联网并处于 Agent。设备正在说话或聆听时通知会排队，等它空下来再念。
填上按钮名（比如“批准,拒绝”），发送后控制台会每秒轮询一次结果，谁在设备上按了哪个按钮会直接显示出来。不填按钮会自动补一个“OK”，否则卡片没法关掉。发出去又不需要了，点“撤销”即可收回。
诊断页怎么看
设备信息
这是芯片内部温度不是外壳温度，桌面待机就是 59–61°C，上限 125°C，余量充足。它和 CPU 忙不忙关系不大，功耗大头是双核常开、Wi-Fi 常连和内存持续刷新这些底噪。读数按 1°C 台阶跳，看着“纹丝不动”是正常的。
显示电量以及当前是充电中、外接供电还是电池供电。省电策略只看是否在放电，排查自动熄屏、降频、自动关机先看这一栏。
版本号固定是 9.9.9，判断固件有没有真的更新要看构建时间和 SHA，不要只看版本号。
跨重启保留的复位原因序列，新的在前。欠压和硬看门狗这两种崩溃不会留下崩溃转储，这串数字是唯一能查的线索。
资源文件与崩溃记录
“对账”查某个图标 / 字体文件在设备里的大小和哈希，用来核对推上去的资源和本地文件是否一致（文件名不能超过 32 个字符，超长的永远查不到）。“渲染探针”让设备真的把这张图渲染一遍，新增图片资源建议逐个过一遍这关——畸形的 PNG 会让翻页时死机。
崩溃转储不会随刷新固件一起清掉，一份旧崩溃能在里面躺很久。查完了或者确认它是旧固件留下的，就点“清除 coredump”，再复现拿到的才是当前固件的现场。
音频直通
不经过任何应用，直接让设备去放一条音频流，用来把“设备能不能解码出声”和“界面写得对不对”分开验证。它只适合临时试放一个地址。
这个通道用一条长连接把音频拉到底，播放中设备只要再收到一条网络请求就会丢字节、把解码器搞崩。控制台在这块面板操作时会自动停掉总览轮询、摄像头和屏幕预览，但你自己也别同时去点其他按钮。正常听播客不受这个限制，播客走的是另一套分段方式。
自己推送 OTA 固件
在 Hi Chan 中更新
- 先停止音乐和对话，让设备保持空闲。音频流量会拖慢上传，可能造成看似成功但实际校验失败。
- 打开“OTA”，App 固件选择
stack-chan.bin；图标、字体、唤醒词模型选择generated_assets.bin。 - 上传后等待设备自动重启并重新连接，在诊断页确认构建时间和 SHA 已变化。
修改代码通常只推 App；修改唤醒词、图标或字体必须另外推 Assets。Assets 传输中断时分区可能暂时不完整，重新上传即可恢复。
命令行推荐方式
在已经编译好的 firmware 目录执行：
./push_ota.sh 192.168.x.x
脚本会上传 build/stack-chan.bin，等待设备重启，并把设备返回的 ELF SHA 与本地产物做硬校验，可识别回滚或旧分区造成的“假成功”。
只推 Assets 时用配套脚本，别自己 curl 整个文件上去：
./push_assets.sh 192.168.x.x
4MB 一次性传上去会在中途被设备掐断——擦写闪存期间设备顾不上回应网络，连接就断了。脚本和 Hi Chan 的“资源 OTA”都按 256KB 分片发送并自动校验。传输失败会让资源分区处于半新半旧的状态（表现为图标、背景图全丢），重传一次即可修复。
- 首次安装定制固件必须先通过 USB 烧录一次，旧固件本身没有这套 OTA 服务。
- 定制固件不会跟随官方自动更新；后续请使用 Hi Chan 或上述脚本升级。
- USB 分区烧录不要整片从
0x0写入，否则会擦掉 NVS 中的 Wi-Fi、音量等设置。
常见问题
代理软件可能劫持 .local。改填路由器里看到的设备 IP，并保留 8032 端口。
HTTPS 页面访问内网 HTTP 依赖浏览器许可，优先使用 Chrome 或 Edge，并允许本地网络访问。
这是电池供电时的省电机制，不是行情故障。插 USB 通常不会触发。自动关机的时长可以在“设置 → 屏幕与待机”里改，填 0 就永不自动关机。
固件在编译期就关掉了蓝牙（省出约 50K 内存、固件小 330K）。手机 App 配对和 BLE 配网依赖闭源握手，开源版本来也走不通；“摇一摇”遥控走的是 ESP-NOW，与蓝牙无关，不受影响。配网请用小智那套：设备连不上已存网络时会自动开热点。
先让头部归中；仍无效就重启设备解除保护，切勿用手硬掰。
确认已进入 Agent；首次搜索和转码可能需要十几秒，已缓存内容会更快。
以诊断页构建时间和 SHA 为准，不要只看 9.9.9；重新空闲推送并核对 SHA。
提示音要设备处于 AI Agent 才有——音频服务是进 Agent 时才启动的。Launcher 下通知只有画面，这是降级不是丢失。
这条通道对长度卡得很死，超过约 12 个汉字就会被服务端拒收，整句播报就没了。把文案写短、写固定，别让长度随运行时数据（尤其是数字）浮动。
勾上“抓图前先唤醒屏幕”。控制台调 API 不算设备上的“操作”，不唤醒的话超过 30 秒无人触碰就一直截到屏保。
“待机自主动作”要退出 Agent 再进一次才生效；“小智服务端地址”要重启设备才生效。其余设置都是保存即刻生效并断电不丢。
先确认电脑端配套服务在跑、防火墙放行。播客要填的是设备反代口 23021，不是 23020；两个服务都要求电脑与设备在同一局域网且电脑不休眠。
芯片稳态就是 60°C 左右，属正常，上限 125°C。调暗背光实测只降 1°C，不解决问题也不需要解决。
每帧都要设备现拍现编码，约 0.4 秒一张，并且和放歌、对话抢资源。忙的时候把帧率降到 0.5 FPS 或直接暂停。