update at 2026-03-16 09:00:35
This commit is contained in:
douboer@gmail.com
@@ -85,12 +85,10 @@ ssh kindle
|
||||
调试 dashboard 时，先在 KUAL 中执行：
|
||||
|
||||
1. `Dashboard Debug On`
|
||||
2. `Kindle Dashboard`
|
||||
|
||||
调试结束后再执行：
|
||||
|
||||
1. `Dashboard Debug Off`
|
||||
2. `Kindle Dashboard`
|
||||
|
||||
相关脚本：
|
||||
|
||||
@@ -207,8 +205,7 @@ bin/dropbearmulti dropbear -F -E -p 22 -P /mnt/us/usbnet/run/dropbear-force-22.p
|
||||
### B. Dashboard 调试
|
||||
|
||||
1. KUAL -> `Dashboard Debug On`
|
||||
2. KUAL -> `Kindle Dashboard`
|
||||
3. 调试完成后再 `Dashboard Debug Off`
|
||||
2. 调试完成后再 `Dashboard Debug Off`
|
||||
|
||||
### C. SSH 启动的最短稳定路线
|
||||
|
||||
|
||||
317
dash/docs/kindle-voyage-5.13.6-white-screen-handoff-zh.md
Normal file
317
dash/docs/kindle-voyage-5.13.6-white-screen-handoff-zh.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# Kindle Voyage 5.13.6 白屏/KUAL/SSH 交接文档
|
||||
|
||||
本文记录 2026-03-15 这轮 dashboard 调试在后半段进入的异常状态，目标是给下一次接手排障的人一个明确起点，避免继续沿着已经证伪或高风险的路径重复试错。
|
||||
|
||||
## 当前交接状态
|
||||
|
||||
截至本次更新时，设备不再处于“完全卡死且无法 SSH”的状态，而是进入了一个更窄的失败场景：
|
||||
|
||||
- Kindle 已能回到主页
|
||||
- `ssh kindle` 已恢复可用
|
||||
- 从 `KUAL -> Kindle Dashboard` 进入 dashboard 时，仍会复现白屏
|
||||
- 白屏出现时，dashboard 本身往往没有真正接管成功，更像是 `framework/KUAL` 启动链在中途被打断
|
||||
- 当前最稳定的恢复路径，仍然是通过 SSH 执行 `./stop.sh`
|
||||
|
||||
这份文档只记录当前交接结论，不再继续尝试修复。
|
||||
|
||||
## 已确认的事实
|
||||
|
||||
### 1. `Dashboard Debug On` 已能阻止自动挂起
|
||||
|
||||
这部分在设备可连 SSH 时已经实机验证通过：
|
||||
|
||||
- [dash/src/debug-on.sh](/Users/gavin/kindle-dash/dash/src/debug-on.sh) 现在会：
|
||||
- 把 `DISABLE_SYSTEM_SUSPEND=true` 写入 `local/env.sh`
|
||||
- 自动重启 dashboard
|
||||
- 日志里已经出现过：
|
||||
|
||||
```text
|
||||
Skipping system suspend, sleeping for 40s instead
|
||||
```
|
||||
|
||||
所以“点 `Dashboard Debug On` 之后 3 秒就休眠”这个问题，本轮已经修住。
|
||||
|
||||
### 2. `dashboard` 模式不是可交互界面
|
||||
|
||||
当前实现里，dashboard 启动后会主动停掉 Kindle 的前台 UI：
|
||||
|
||||
- [dash/src/dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh#L50) 调用 `stop_framework`
|
||||
- [dash/src/dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh#L51) 停掉 `webreader`
|
||||
|
||||
这意味着：
|
||||
|
||||
- 进入 dashboard 之后，不应再期望当前屏幕仍然像普通 Kindle 页面那样可点击
|
||||
- 也不应再期待“从 dashboard 直接返回刚才那个 KUAL 页面”
|
||||
|
||||
### 3. 顶栏遮罩不处理触摸
|
||||
|
||||
右上角状态栏遮罩逻辑在：
|
||||
|
||||
- [dash/src/dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh#L121)
|
||||
|
||||
它只是调用 `fbink` 在帧缓冲上画白色矩形，不负责输入，也不会接管触摸事件。因此：
|
||||
|
||||
- “点不到 KUAL” 不是顶栏遮罩造成的
|
||||
- 真正相关的是 `framework/webreader` 被停掉
|
||||
|
||||
### 4. `stop.sh` 现在只负责恢复 UI 栈，不负责直接打开 KUAL
|
||||
|
||||
当前 [dash/src/stop.sh](/Users/gavin/kindle-dash/dash/src/stop.sh) 已改成：
|
||||
|
||||
- 停掉 `dash.sh`
|
||||
- 清掉 `preventScreenSaver`
|
||||
- 启动 `framework`
|
||||
- 启动 `webreader`
|
||||
|
||||
也就是说它的职责是：
|
||||
|
||||
- 让 Kindle 回到“应该可以恢复正常 UI”的状态
|
||||
|
||||
不是：
|
||||
|
||||
- 直接把 KUAL booklet 弹出来
|
||||
|
||||
补充一点：在白屏恢复过程中，`stop.sh` 已经比旧版稳定很多，但仍存在一种残留状态：
|
||||
|
||||
- `framework` 和 `cvm` 已回来了
|
||||
- `webreader` 可能还停在 `stop/waiting`
|
||||
|
||||
这时手工再执行一次 `start webreader`，主页通常就能回来。
|
||||
|
||||
### 5. 直接 `booklet run` 的试探命令不安全
|
||||
|
||||
本轮为了验证能否从 shell 里直接拉起主页或 KUAL，试过两类命令：
|
||||
|
||||
```sh
|
||||
lipc-set-prop com.lab126.booklet run "app://com.lab126.booklet.home"
|
||||
lipc-set-prop com.lab126.booklet run "com.mobileread.ixtab.kindlelauncher.KualBooklet"
|
||||
```
|
||||
|
||||
这条路不稳定，已经触发过 `cvm` 崩溃打包。设备上看到过：
|
||||
|
||||
- `/mnt/us/documents/cvm_2886_..._crash_Mar_15_14.14.19_2026.tgz`
|
||||
- `/mnt/us/documents/cvm_5551_..._crash_Mar_15_14.18.54_2026.tgz`
|
||||
|
||||
因此下次接手时，不要再直接复用这两条命令。
|
||||
|
||||
### 6. dashboard 本身可以工作，失败更像发生在 KUAL 启动路径
|
||||
|
||||
本轮已经验证过：
|
||||
|
||||
- 通过 SSH 直接前台运行 `DEBUG=true ./start.sh`，dashboard 可以正常渲染
|
||||
- 时钟、背景图、顶栏遮罩都能按预期执行
|
||||
- 前台日志里可以看到正常的刷新过程
|
||||
|
||||
这说明：
|
||||
|
||||
- dashboard 渲染逻辑本身不是当前白屏问题的主因
|
||||
- 真正未解的是 `KUAL -> start.sh -> dash.sh` 这条非调试、后台化启动路径
|
||||
|
||||
### 7. 白屏时，帧缓冲本身就是白的，不是单纯 e-ink 残影
|
||||
|
||||
本轮抓过多次 `fbgrab`：
|
||||
|
||||
- `tmp/current-ui.png`
|
||||
- `tmp/ui-restart-screen.png`
|
||||
- `tmp/ui-after-power-cycle.png`
|
||||
|
||||
这些截图都是真正的纯白图，不是“系统其实起来了，只是屏幕没刷新”。因此：
|
||||
|
||||
- 白屏发生时，不能只从物理屏幕角度判断
|
||||
- 需要继续围绕 `framework / cvm / webreader / dash.sh` 的实际进程状态排查
|
||||
|
||||
### 8. 日志证据表明：KUAL 切到 dashboard 的过程中，framework 主进程被 TERM
|
||||
|
||||
这轮从 `/var/log/messages` 里已经看到关键序列：
|
||||
|
||||
- KUAL booklet 被启动
|
||||
- home booklet 被恢复
|
||||
- 随后 `framework main process (...) killed by TERM signal`
|
||||
|
||||
这说明当前最可疑的点是：
|
||||
|
||||
- KUAL 页面触发 dashboard 启动时，父 UI 进程在切换链路中被自己或系统杀掉
|
||||
- dashboard 又没有在这之前稳定脱离 KUAL 会话
|
||||
- 结果就是前台白屏，而不是正常切入 dashboard
|
||||
|
||||
## 本轮过程中已验证过的有效路径
|
||||
|
||||
在问题进一步收敛前，以下链路是验证过可工作的：
|
||||
|
||||
### 1. 背景图链路
|
||||
|
||||
- 网页导出 `1072x1448` 的 `8-bit grayscale PNG`
|
||||
- Kindle 直接显示这张背景图时，所见即所得
|
||||
|
||||
关键文件：
|
||||
|
||||
- [calendar/dist/kindlebg.png](/Users/gavin/kindle-dash/calendar/dist/kindlebg.png)
|
||||
- [dash/src/local/fetch-dashboard.sh](/Users/gavin/kindle-dash/dash/src/local/fetch-dashboard.sh)
|
||||
|
||||
### 2. 本机时钟链路
|
||||
|
||||
黑块问题已经从“透明 PNG patch”切到“Lua 本机绘制”：
|
||||
|
||||
- [dash/src/local/render-clock.lua](/Users/gavin/kindle-dash/dash/src/local/render-clock.lua)
|
||||
- [dash/src/local/render-clock.sh](/Users/gavin/kindle-dash/dash/src/local/render-clock.sh)
|
||||
|
||||
当设备 SSH 正常时，这条链路已经实机验证过：
|
||||
|
||||
- 背景正常
|
||||
- 时钟可叠加
|
||||
- 不再出现整块黑色 patch
|
||||
|
||||
### 3. Wi-Fi SSH 链路
|
||||
|
||||
目前仍可用的稳定入口是：
|
||||
|
||||
```sh
|
||||
ssh kindle
|
||||
```
|
||||
|
||||
它依赖本机 `~/.ssh/config` 中的：
|
||||
|
||||
- `HostName 192.168.72.3`
|
||||
- `IdentityFile ~/.ssh/id_ed25519_git`
|
||||
|
||||
这一条在本次文档更新时已经恢复。
|
||||
|
||||
### 4. 直接从 SSH 前台启动 dashboard
|
||||
|
||||
当前唯一明确验证成功的 dashboard 启动方式是：
|
||||
|
||||
```sh
|
||||
ssh kindle 'cd /mnt/us/dashboard && DEBUG=true ./start.sh'
|
||||
```
|
||||
|
||||
这条路径的特点是：
|
||||
|
||||
- `dash.sh` 以前台方式运行
|
||||
- 不依赖 KUAL 页面还活着
|
||||
- 能直接看到 shell trace 和实时日志
|
||||
|
||||
相对地：
|
||||
|
||||
- 直接点 `KUAL -> Kindle Dashboard`
|
||||
- 或通过普通 `./start.sh` 后台起进程
|
||||
|
||||
这两条路径目前都没有被证明稳定。
|
||||
|
||||
## 当前不要再做的事情
|
||||
|
||||
以下路径本轮已经证明风险高或收益低，下次接手前不要重复：
|
||||
|
||||
1. 不要再尝试“双击电源键 / 同时按翻页条”呼出 KUAL
|
||||
|
||||
- 当前仓库没有任何这类按键绑定实现
|
||||
- 这条路没有现成机制可用
|
||||
|
||||
2. 不要再尝试 `booklet run` 直接拉起主页或 KUAL
|
||||
|
||||
- 已触发 `cvm` 崩溃
|
||||
- 风险高于收益
|
||||
|
||||
3. 不要继续走“KUAL -> Dashboard -> 再返回 KUAL”的交互路径
|
||||
|
||||
- dashboard 启动后会停掉 `framework/webreader`
|
||||
- 从逻辑上这就不是一个受支持的返回路径
|
||||
|
||||
4. 不要把 `KUAL -> Kindle Dashboard` 当成当前可用入口
|
||||
|
||||
- 这正是现在仍会复现白屏的路径
|
||||
- 问题还没有修住
|
||||
|
||||
## 下一次接手的安全起点
|
||||
|
||||
下一次恢复排障时，请按这个顺序来：
|
||||
|
||||
### A. 先把设备恢复到正常 UI
|
||||
|
||||
1. 长按电源键约 40 秒重启
|
||||
2. 先不要启动 dashboard
|
||||
3. 先确认能正常回到 Kindle 首页
|
||||
4. 再确认能正常打开 KUAL
|
||||
|
||||
### B. 再确认网络
|
||||
|
||||
只有在设备已经稳定回到正常 UI 后，才做这一步：
|
||||
|
||||
```sh
|
||||
ssh kindle
|
||||
```
|
||||
|
||||
如果仍然不通，再查：
|
||||
|
||||
- Kindle 是否连回同一个主 Wi-Fi
|
||||
- IP 是否还是 `192.168.72.3`
|
||||
- DropBear 是否还在监听 `22`
|
||||
|
||||
### C. 重新进入 dashboard 时的推荐方式
|
||||
|
||||
恢复后如果还要继续调 dashboard，当前建议只走这条路径：
|
||||
|
||||
```sh
|
||||
ssh kindle 'cd /mnt/us/dashboard && DEBUG=true ./start.sh'
|
||||
```
|
||||
|
||||
原因：
|
||||
|
||||
- 这条路径已经验证成功
|
||||
- 可以直接看到日志
|
||||
- 不依赖 KUAL 的 UI 切换链路
|
||||
|
||||
退出 dashboard 时：
|
||||
|
||||
```sh
|
||||
ssh kindle 'cd /mnt/us/dashboard && ./stop.sh'
|
||||
```
|
||||
|
||||
等几秒，让 UI 栈恢复，再从 Kindle 首页重新打开 KUAL。
|
||||
|
||||
如果执行完 `./stop.sh` 后主页仍然没有回来，再补：
|
||||
|
||||
```sh
|
||||
ssh kindle 'start webreader'
|
||||
```
|
||||
|
||||
不要从 dashboard 页面直接尝试回 KUAL。
|
||||
|
||||
### D. 当前真正待修的点
|
||||
|
||||
下次接手时，排障目标应该收敛到这一条：
|
||||
|
||||
- 为什么 `KUAL -> Kindle Dashboard` 会白屏，而 `ssh kindle 'DEBUG=true ./start.sh'` 却能正常显示
|
||||
|
||||
也就是说，重点应该放在：
|
||||
|
||||
- KUAL 菜单动作
|
||||
- `start.sh` 的后台脱离方式
|
||||
- `framework` 被 TERM 的时机
|
||||
|
||||
而不是继续怀疑背景图、时钟绘制或顶栏遮罩。
|
||||
|
||||
## 这轮涉及的关键文件
|
||||
|
||||
- [dash/src/dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh)
|
||||
- [dash/src/start.sh](/Users/gavin/kindle-dash/dash/src/start.sh)
|
||||
- [dash/src/stop.sh](/Users/gavin/kindle-dash/dash/src/stop.sh)
|
||||
- [dash/src/debug-on.sh](/Users/gavin/kindle-dash/dash/src/debug-on.sh)
|
||||
- [dash/src/debug-off.sh](/Users/gavin/kindle-dash/dash/src/debug-off.sh)
|
||||
- [dash/src/local/env.sh](/Users/gavin/kindle-dash/dash/src/local/env.sh)
|
||||
- [dash/src/local/render-clock.sh](/Users/gavin/kindle-dash/dash/src/local/render-clock.sh)
|
||||
- [dash/src/local/render-clock.lua](/Users/gavin/kindle-dash/dash/src/local/render-clock.lua)
|
||||
- [dash/docs/kindle-voyage-5.13.6-dual-ssh-playbook-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-dual-ssh-playbook-zh.md)
|
||||
|
||||
## 最后结论
|
||||
|
||||
本轮后半段的主要问题已经不是 dashboard 页面本身，而是：
|
||||
|
||||
- dashboard 与 Kindle 原生 `framework/KUAL` 的边界切换不稳定
|
||||
- `KUAL -> Kindle Dashboard` 这条启动链仍会白屏
|
||||
- 直接用 shell 强拉 booklet 会触发前台 Java 崩溃
|
||||
|
||||
因此，当前最重要的不是继续调页面，而是：
|
||||
|
||||
1. 保留当前已经可用的 SSH 启动/停止路径
|
||||
2. 修住 `KUAL -> Kindle Dashboard` 白屏
|
||||
3. 在不再触发 `cvm` 崩溃的前提下，把“进入 dashboard”和“退出 dashboard”都收敛成稳定流程
|
||||
@@ -53,6 +53,35 @@
|
||||
- 降低全屏刷新频率
|
||||
- 减少墨水屏闪烁与残影
|
||||
|
||||
### 2.1 当前导出基线
|
||||
|
||||
基于 Kindle Voyage 系统自带屏保 `bg_default.png` 的实机验证，当前背景导出链路应遵守这几个固定约束：
|
||||
|
||||
- 网页成品页尺寸直接使用 `1072 x 1448`
|
||||
- Kindle 主背景图直接导出为同尺寸，不再做额外旋转、补边或缩放
|
||||
- 导出格式固定为 `8-bit grayscale PNG`
|
||||
- 页面视觉尽量保持纯白底、纯黑文字与图标，避免大面积灰阶装饰
|
||||
|
||||
这部分不是临时调试参数，而是后续继续微调版式时的默认基准。
|
||||
|
||||
当前设备端时钟实现也已经切换为：
|
||||
|
||||
- Kindle 本机 `lua` 生成时钟区位图
|
||||
- 通过 `fbink` 刷新指定矩形
|
||||
|
||||
在 Kindle Voyage 5.13.6 的当前环境里，还需要额外注意一点：
|
||||
|
||||
- `fbink` 叠加图片时必须带 `-V` / `--noviewport`
|
||||
- 否则会因为 viewport 修正导致时钟区域纵向偏移
|
||||
- 并且会在同一帧缓冲里出现两个重叠时钟
|
||||
|
||||
也就是说，Voyage 上本地时钟叠加的稳定命令形态应当是：
|
||||
|
||||
```sh
|
||||
fbink -q -V -g "file=/mnt/us/dashboard/local/state/clock-render.pgm,x=$CLOCK_REGION_X,y=$CLOCK_REGION_Y"
|
||||
```
|
||||
- 不再依赖 `eips + 透明 PNG patch` 叠图
|
||||
|
||||
## 3. 分层边界
|
||||
|
||||
### 3.1 全屏背景层
|
||||
@@ -465,8 +494,22 @@ export CLOCK_REGION_Y=0
|
||||
export CLOCK_REGION_WIDTH=220
|
||||
export CLOCK_REGION_HEIGHT=220
|
||||
export CLOCK_FULL_REFRESH_INTERVAL_MINUTES=15
|
||||
export PRE_SLEEP_GRACE_SECONDS=10
|
||||
```
|
||||
|
||||
补充两条运行期约束：
|
||||
|
||||
- `clock-index.sh` 取当前时间时必须沿用 `TIMEZONE`，不能直接读系统默认时区
|
||||
- `PRE_SLEEP_GRACE_SECONDS` 这类“进入休眠前的可中断窗口”必须从实际休眠时长里扣掉，否则分钟刷新会长期落后一个节拍
|
||||
|
||||
当前实现里，时钟区域的适配已经分成两层：
|
||||
|
||||
- `CLOCK_REGION_X/Y/WIDTH/HEIGHT` 负责位置与尺寸
|
||||
- `CLOCK_*` 外观参数负责指针长度、粗细、刻度长度和圆心点大小
|
||||
|
||||
因此，页面板式变化导致时钟区域变大变小时，一般不需要重画任何静态素材，也不需要改 Lua 代码；
|
||||
只要重新导出网页拿到新的 `clock-region.json`，同步到 Kindle 后，本机时钟就会按新尺寸重画。
|
||||
|
||||
## 10. 实施顺序
|
||||
|
||||
建议按下面顺序落地，避免一次改太多导致链路难排查。
|
||||
|
||||
Reference in New Issue
Block a user