323 lines
11 KiB
Markdown
323 lines
11 KiB
Markdown
# kindle-dash
|
||
|
||
一个面向 Kindle Voyage 的低功耗电子墨水仪表盘项目。
|
||
当前仓库把整条链路都放在一起：
|
||
|
||
- `calendar/`：在电脑上生成背景图、主题包和前端预览
|
||
- `dash/`：运行在 Kindle 上，负责拉图、渲染时钟、休眠唤醒、主题切换
|
||
- `scripts/`：同步、抓图、SSH 恢复等运维脚本
|
||
- `bootstrap-new-kindle.sh`：新机预置与 SSH 打通后的自动化入口
|
||
- `snapshot.sh`：同步主题、切换主题、抓取 Kindle 实机画面的统一入口
|
||
|
||
## 当前状态
|
||
|
||
- `simple` / `default` 等主题已经接入当前运行链路
|
||
- Kindle 侧采用“低频背景 + 本机时钟重绘”的分层渲染方案
|
||
- 通过 `scripts/sync-layered-clock-to-kindle.sh` 同步主题时，天气背景会优先按 Kindle 当前网络出口位置导出
|
||
- 新机 bootstrap 方案已实现
|
||
- 新机 bootstrap 当前仍是“方案已实现，真机恢复出厂闭环未验证”
|
||
- `launch-from-kual.sh` 与 `setsid` 脱离方案已经落地到代码
|
||
- 主题入口当前只保留在 `KUAL`；运行态双翻页键菜单与右下角长按默认关闭
|
||
- 但 `KUAL -> Dashboard` 与 `Dashboard -> 原生 UI/KUAL` 的边界切换在 `Kindle Voyage 5.13.6` 上仍不稳定
|
||
|
||
## 项目目标
|
||
|
||
这个仓库不是单纯做一个网页，而是把下面几件事收成一套：
|
||
|
||
1. 在电脑上生成适合 Kindle 分辨率的背景图和主题资源
|
||
2. 把这些资源同步到已越狱的 Kindle
|
||
3. 让 Kindle 在低功耗模式下周期性刷新背景
|
||
4. 在设备本机按分钟重绘时钟，不依赖网络
|
||
5. 提供主题切换、实机截图、SSH 恢复和新机 bootstrap 工具
|
||
|
||
## 架构概览
|
||
|
||
### 1. 前端层 `calendar/`
|
||
|
||
作用：
|
||
|
||
- 使用 Vue 生成 Kindle 仪表盘布局
|
||
- 导出 `kindlebg.png`
|
||
- 导出多主题背景包和 `themes.json`
|
||
- 预览不同主题与方向
|
||
- Web 预览页里的天气位置仍优先走浏览器定位；Kindle 实机同步时则优先读取 Kindle 侧 GeoIP 缓存
|
||
|
||
关键文件：
|
||
|
||
- [App.vue](/Users/gavin/kindle-dash/calendar/src/App.vue)
|
||
- [SimpleDashboard.vue](/Users/gavin/kindle-dash/calendar/src/components/SimpleDashboard.vue)
|
||
- [themes.json](/Users/gavin/kindle-dash/calendar/config/themes.json)
|
||
|
||
### 2. 设备运行层 `dash/`
|
||
|
||
作用：
|
||
|
||
- 在 Kindle 上拉取或读取背景图
|
||
- 根据调度决定刷新还是休眠
|
||
- 在本机用 Lua + FBInk 渲染时钟
|
||
- 切换主题、维护运行时主题状态
|
||
- 在需要时拉起主题菜单服务
|
||
|
||
运行规则：
|
||
|
||
- 时钟刷新原则：无论 `debug on` 还是 `debug off`，设备侧时钟都按分钟调度刷新一次
|
||
- `debug on`：设备不进入真 suspend，保持常亮，并持续按分钟刷新
|
||
- `debug off`：设备仍按分钟刷新时钟；普通分钟刷新只更新后台缓存，不主动把时钟刷到可视屏幕，刷新后立即回到低功耗调度
|
||
- `debug off` 下短按 `power`：设备进入一个 5 分钟的可视窗口；窗口内时钟仍按分钟刷新，窗口结束后恢复到普通低功耗调度
|
||
- 通过 `KUAL` 启动 dashboard 或切换主题后回到 calendar：同样进入一个 5 分钟的可视窗口，避免用户回来时看到静止时钟
|
||
- 背景图与主题资源保持低频更新；分钟级高频更新只发生在本机时钟区域，不依赖网络
|
||
|
||
关键文件：
|
||
|
||
- [dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh)
|
||
- [switch-theme.sh](/Users/gavin/kindle-dash/dash/src/switch-theme.sh)
|
||
- [render-clock.lua](/Users/gavin/kindle-dash/dash/src/local/render-clock.lua)
|
||
- [theme-sync.sh](/Users/gavin/kindle-dash/dash/src/local/theme-sync.sh)
|
||
|
||
### 3. 运维层 `scripts/`
|
||
|
||
作用：
|
||
|
||
- 把当前 runtime 和主题包同步到 Kindle
|
||
- 抓取 Kindle 实机屏幕
|
||
- 恢复 Kindle 侧 SSH
|
||
- 协助 USBNetwork 调试
|
||
|
||
关键入口：
|
||
|
||
- [sync-layered-clock-to-kindle.sh](/Users/gavin/kindle-dash/scripts/sync-layered-clock-to-kindle.sh)
|
||
- [capture-kindle-screen.sh](/Users/gavin/kindle-dash/scripts/capture-kindle-screen.sh)
|
||
- [ssh-force-dropbear-22.sh](/Users/gavin/kindle-dash/scripts/kindle/ssh-force-dropbear-22.sh)
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
kindle-dash/
|
||
├── assets/ 前端静态资源
|
||
├── bootstrap-new-kindle.sh 新机预置/后半段自动化入口
|
||
├── snapshot.sh 同步 + 切主题 + 抓图统一入口
|
||
├── calendar/ Vue 前端与背景导出
|
||
├── dash/ Kindle 侧 runtime、KUAL、文档与 staging
|
||
├── scripts/ 同步、抓图、SSH 与网络辅助脚本
|
||
└── tmp/ 本地实机截图和临时产物
|
||
```
|
||
|
||
## 部署模型
|
||
|
||
### 已越狱 Kindle
|
||
|
||
这条路径适合设备已经有 `KUAL`、`USBNetwork`、SSH：
|
||
|
||
1. 在电脑上构建前端：
|
||
|
||
```sh
|
||
cd calendar
|
||
npm install
|
||
npm run typecheck
|
||
npm run build
|
||
```
|
||
|
||
2. 同步到 Kindle：
|
||
|
||
```sh
|
||
cd /Users/gavin/kindle-dash
|
||
sh scripts/sync-layered-clock-to-kindle.sh kindle
|
||
```
|
||
|
||
3. 切主题并立即出图：
|
||
|
||
```sh
|
||
ssh kindle '/mnt/us/dashboard/switch-theme.sh simple portrait'
|
||
```
|
||
|
||
4. 如需启动 dashboard 主循环：
|
||
|
||
```sh
|
||
ssh kindle 'cd /mnt/us/dashboard && ./start.sh'
|
||
```
|
||
|
||
调试或排障时，当前更推荐：
|
||
|
||
```sh
|
||
ssh kindle 'cd /mnt/us/dashboard && DEBUG=true ./start.sh'
|
||
```
|
||
|
||
原因：
|
||
|
||
- 这条路径已实机验证可用
|
||
- 不依赖 `KUAL` 的 UI 切换链路
|
||
- 出问题时可以直接看前台日志
|
||
|
||
### 新机 / 恢复出厂后 Kindle
|
||
|
||
这条路径适合 `Kindle Voyage 5.13.6`：
|
||
|
||
1. USB 挂载后执行预置：
|
||
|
||
```sh
|
||
sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version latest
|
||
```
|
||
|
||
2. 在 Kindle 上完成：
|
||
|
||
- `WatchThis`
|
||
- `;log mrpi`
|
||
- `Rename OTA Binaries -> Rename`
|
||
- 接回 Wi‑Fi
|
||
- `KTerm` 中执行 `sh /mnt/us/ssh-force-dropbear-22.sh`
|
||
|
||
3. 回到 Mac，执行后半段：
|
||
|
||
```sh
|
||
sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait
|
||
```
|
||
|
||
说明：
|
||
|
||
- `post-ssh` 当前会同步 `dashboard` shell 脚本、`KUAL` 菜单和主题包
|
||
- 它不会回补 `prepare-storage` 阶段预置的原生二进制，例如 `next-wakeup`、`xh`
|
||
- 所以这条路径默认前提仍然是：先跑过 `prepare-storage`
|
||
|
||
注意：这条新机 bootstrap 方案当前仍未做“真机恢复出厂闭环验证”。
|
||
|
||
## 常用命令
|
||
|
||
### 前端开发
|
||
|
||
```sh
|
||
cd calendar
|
||
npm install
|
||
npm run dev
|
||
npm run typecheck
|
||
npm run build
|
||
npm run export:themes
|
||
```
|
||
|
||
### Web 端定时生成与发布
|
||
|
||
如果 Web 服务器需要每小时自动生成最新背景图，并把结果放到固定静态目录，使用：
|
||
|
||
```sh
|
||
sh scripts/publish-calendar-dist.sh --output-dir /path/to/web-root --once
|
||
```
|
||
|
||
这条命令会：
|
||
|
||
- 调用 `npm run export:themes` 生成最新 `kindlebg.png`、`themes/<theme>/<orientation>/kindlebg.png`
|
||
- 同步 `calendar/dist/` 整个目录到你指定的 Web 根目录
|
||
|
||
如果希望常驻运行、每 60 分钟自动重跑一次，去掉 `--once`：
|
||
|
||
```sh
|
||
sh scripts/publish-calendar-dist.sh --output-dir /path/to/web-root
|
||
```
|
||
|
||
说明：
|
||
|
||
- 当前导图依赖 `calendar/scripts/export-kindle-background.swift`，因此这条自动发布链路需要运行在 macOS 上
|
||
- 如果你的线上静态服务器是 Linux，只适合把“发布目录”指到该 Linux 机器挂载出来的目录，或者先在 macOS 上生成后再额外同步
|
||
- Web 服务器应该直接服务这个发布目录，而不是只服务 `vite build` 产出的 HTML；否则 `.png` 路径可能回落成 `index.html`
|
||
|
||
### 主题与截图
|
||
|
||
```sh
|
||
sh snapshot.sh --list
|
||
sh snapshot.sh -t simple
|
||
sh snapshot.sh -t simple -o portrait
|
||
sh snapshot.sh --capture-only -b current-screen
|
||
sh snapshot.sh --date
|
||
```
|
||
|
||
### 新机 bootstrap
|
||
|
||
```sh
|
||
sh bootstrap-new-kindle.sh -h
|
||
sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version latest
|
||
sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait
|
||
```
|
||
|
||
补充：
|
||
|
||
- 如果还要执行 `--start-dashboard`，默认同样要求设备上已经有 `prepare-storage` 预置的完整 dashboard 基础运行时
|
||
|
||
### SSH 恢复
|
||
|
||
如果 Kindle 上已经有 `KTerm`，但外部 SSH 不通：
|
||
|
||
```sh
|
||
sh /mnt/us/ssh-force-dropbear-22.sh
|
||
```
|
||
|
||
然后在 Mac 上：
|
||
|
||
```sh
|
||
ssh kindle
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
### 日常使用
|
||
|
||
- Kindle 正常联网时，背景和主题配置可以更新
|
||
- 本机时钟按分钟重绘，不依赖网络
|
||
- 即使远端刷新失败，只要本地还有缓存背景，设备通常还能继续显示旧背景和本机时钟
|
||
|
||
### 换 Wi‑Fi 后
|
||
|
||
- 不影响 USB 预置
|
||
- 可能影响 `ssh kindle`
|
||
- 可能影响主题强制同步和远端背景刷新
|
||
- 如果新网络能正常出外网，日常显示通常不受影响
|
||
|
||
## 验证与验收
|
||
|
||
当前仓库里可直接运行的校验主要是：
|
||
|
||
```sh
|
||
cd calendar
|
||
npm run typecheck
|
||
npm run build
|
||
```
|
||
|
||
以及脚本级别语法检查，例如：
|
||
|
||
```sh
|
||
sh -n bootstrap-new-kindle.sh
|
||
sh -n snapshot.sh
|
||
```
|
||
|
||
说明：
|
||
|
||
- 当前仓库没有可用的 `lint` 脚本
|
||
- 当前仓库没有可用的 `test` 脚本
|
||
|
||
## 文档索引
|
||
|
||
推荐按下面顺序看：
|
||
|
||
1. 根仓库说明：
|
||
[README.md](/Users/gavin/kindle-dash/README.md)
|
||
2. Kindle runtime 英文原始说明：
|
||
[dash/README.md](/Users/gavin/kindle-dash/dash/README.md)
|
||
3. Voyage 5.13.6 越狱路径：
|
||
[kindle-voyage-5.13.6-watchthis-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-watchthis-zh.md)
|
||
4. SSH / KTerm 兜底：
|
||
[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)
|
||
5. Bootstrap 总说明：
|
||
[kindle-voyage-5.13.6-bootstrap-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-bootstrap-zh.md)
|
||
6. Bootstrap 闭环验证清单：
|
||
[kindle-voyage-5.13.6-bootstrap-validation-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-bootstrap-validation-zh.md)
|
||
7. 白屏/KUAL/SSH 交接：
|
||
[kindle-voyage-5.13.6-white-screen-handoff-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-white-screen-handoff-zh.md)
|
||
|
||
## 已知限制
|
||
|
||
1. `WatchThis` / demo / `;log mrpi` 仍然不能完全自动化
|
||
2. `bootstrap-new-kindle.sh` 当前还没有做一次真机恢复出厂闭环验收
|
||
3. `ssh kindle` 依赖当前网络和 IP；换 Wi‑Fi 后可能要重新确认地址或 SSH 配置
|
||
4. `KUAL -> Dashboard` 与 `Dashboard -> 原生 UI/KUAL` 的边界切换在 `Kindle Voyage 5.13.6` 上仍不稳定
|
||
5. `stop.sh` 当前必须走保守恢复路径，实验性的“快速切换”方案已在 `2026-03-17` 撤回
|
||
6. Voyage 右上角系统状态栏当前仍可能短暂闪现，顶部遮罩还没有做到完全压住
|
||
7. 天气预报的位置当前使用 Kindle 侧 GeoIP 做“市级近似定位”，结果不保证精确到真实街道或精确城区
|
||
8. 当前架构下，分钟级时钟刷新需要设备被唤醒；而设备一旦被唤醒，屏幕/灯光会一起进入可视态，因此暂时做不到“不亮灯唤醒并肉眼可见更新时钟”
|