knob_os/ARCHITECTURE.md

209 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# knob_os 架构
自研固件,跑在 JC3636K518C_I_W(ESP32-S3R8 / 16MB Flash / 8MB PSRAM / 1.85" 360×360 圆屏 / TF 卡)。
Flash 布局是 **app0 / app1 两个对等的 7.5MB 槽**(`partitions.csv`),互为 OTA 回滚目标;原厂固件不再占槽,整片备份在 `00-固件库/设备原机备份/`。
> 怎么改代码(分层规则、UI/交互规范、字体图标、串口调试、发版与坑)见 [`doc/开发规范.md`](doc/开发规范.md);
> 升级流程见 [`doc/固件更新.md`](doc/固件更新.md);扫码登录见 [`doc/扫码登录.md`](doc/扫码登录.md)。
> 本文只写**结构**:有哪些层、有哪些模块、它们之间怎么连。
>
> 最后核对:2026-11-06(固件 0.1.5)
---
## 1. 分层
```
┌──────────────────────────────────────────────────────────┐
│ apps/ 业务应用(时钟/相册/音乐/星盘/我的/天气/设置) │ 只管"这个应用做什么"
├──────────────────────────────────────────────────────────┤
│ ui/ 主题、圆环控件、导航外壳、模态 │ 只管"长什么样、怎么进怎么出"
├──────────────────────────────────────────────────────────┤
│ core/ App 基类、注册表、表驱动设置 │ 只管"框架规则"
├──────────────────────────────────────────────────────────┤
│ hal/ 屏幕、触摸、编码器、SD、电池、触感 │ 只管"硬件怎么用"
├──────────────────────────────────────────────────────────┤
│ services/ WiFi、平台、天气、星盘、媒体同步、OTA、串口 │ 后台能力,不碰 UI
└──────────────────────────────────────────────────────────┘
```
依赖方向严格单向:`apps → ui → core → hal`;`services` 可被 apps/ui 调用,但**不反向依赖 ui**。
换屏幕只改 `hal`,换风格只改 `ui`,加应用不用碰框架。
主循环只有一个任务(20KB 栈,见 `knob_os.ino` 的 `knobTask`):`displayLoop → shell.loop → 各 service.loop`,
LVGL 非线程安全,所有 UI 操作都在这一个任务里。
---
## 2. 目录
```
knob_os/
├── knob_os.ino 入口:初始化 → 注册应用 → 主循环
├── lv_conf.h LVGL 配置(96KB 堆、字体、缓冲区 40 行)
├── partitions.csv 双槽分区表(nvs/otadata/app0/app1/coredump)
├── build.sh 一键编译(lv_conf 同步 → 字体检查 → 增量编译)
├── slave_audio/ 副控 sketch(UART 收码流 → minimp3 → I2S)
├── doc/ 界面索引 / 开发规范 / 固件更新 / 扫码登录
├── tools/ gen_font.sh · collect_chars.py · gen_icons.py · qr_dump/qr_verify · flash_slave.sh
└── src/
├── config/ BoardPins.h(引脚唯一真源)· AppConfig.h(品牌/版本/常量)
├── core/ App.h · AppManager · Settings(表驱动)· Log
├── hal/ Display · Encoder · Storage · Power · Haptic · bidi_switch_knob
├── ui/ Theme · Widgets · Launcher · Shell · Splash
│ BindScreen · NetWizard · ServerEditor · QrScreen/QrCode
│ OtaPanel · SyncPrompt
├── apps/ ClockApp · GalleryApp · MusicApp · AstroApp · UserApp · WeatherApp · SettingsApp
├── services/ NetService · PlatformService · WebPortal(+web_ui.h)
│ WeatherService · AstroService · MusicLibrary · MediaSync
│ OtaService · LinkService · AudioLink · RemoteDebug
└── assets/ lv_font_cjk_16/24 · lv_font_media_16/24 · lv_font_num_64 · lv_font_zodiac_26 · icons.c
```
`assets/` 里的字体与图标都是脚本生成的,不要手改。
---
## 3. 导航模型
```
┌──────────────┐
上划 │ 一级菜单 │ N 个应用沿圆周均分(当前 7 个)
┌──────────────► │ (Launcher) │ 旋钮选 · 点击进 · 下滑取消
│ └──────┬───────┘
│ │ 点击图标
┌──┴────────┐ ▼
│ 应用全屏 │ ◄────────────┘
│ (App) │ 内置模态:绑定页 / 二维码 / OTA 进度 / 同步进度
└──┬────────┘
│ 下滑
▼
┌──────────────┐
│ 应用设置层 │ 全屏升起,中心聚焦轮盘;只显示本应用的设置项
└──────────────┘
```
| 操作 | 结果 |
|---|---|
| 上划 | 打开一级菜单(当前应用高亮) |
| 一级菜单里旋钮 | 环形切换,中心盘显示应用名 + `序号/总数`(扇区里只有图标) |
| 点击图标 | 进入应用 |
| 一级菜单里下滑 | 取消,回原应用 |
| 应用内下滑 | 升起该应用的设置层(设置应用例外:整页就是设置) |
| 设置层旋钮 | 中心聚焦轮盘:旋到中心即选中;滑轨行只能手指拖值 |
| 任意位置长按 | 回桌面(`sys.boot` 指定的应用,默认时钟) |
| 未配网开机 | 进配网向导(热点名/密码/网址 + 重新配网按钮) |
| 未绑定进入需账号的功能 | 升起绑定页(6 位码上屏) |
Shell 用"容器 + 隐藏"而不是销毁重建:每个应用只 `build()` 一次,切走时 `HIDDEN`——番茄钟切到相册再回来,计时不会断。
---
## 4. 服务层
| 服务 | 职责 | 状态 |
|---|---|---|
| `NetService` | STA 优先、15s 超时回落 SoftAP、mDNS、SNTP、`requestAp/requestStopAp` 请求队列 | 完成 |
| `PlatformService` | 设备身份(chip_id + token)、配对状态机、资料同步、校时、带鉴权的 GET/POST | 完成 |
| `WeatherService` | 平台 `/weather`(服务端聚合和风 + Redis),未绑定不请求 | 完成 |
| `AstroService` | 平台 `/astro`:太阳/月亮星座 + 当月运势,NVS 兜底 | 完成 |
| `MediaSync` | 平台清单 diff、下载、CRC 校验、事务性写卡、同步回报 | 完成(真机端到端待测) |
| `MusicLibrary` | 后台扫卡、ID3v2.2/2.3/2.4 解析(标题/歌手/APIC 封面/时长估算) | 完成 |
| `OtaService` | 查/下/校验/切槽/上报 + 开机尝试计数回滚 | 完成 |
| `AudioLink` | TF 卡 MP3 码流封帧推给副控(UART1 921600 + 流控) | 完成,待真机联调 |
| `LinkService` | 与副控的控制指令通道 + 回包记录 | 通道完成,协议待对齐 |
| `WebPortal` | 内置配网页(单页 PROGMEM)+ 14 个 API | 完成 |
### 4.1 与平台(nex_buddy)的联动
设备只跟自己配的服务端说话,第三方 Key 一概不进固件。
| 用途 | 接口 | 说明 |
|---|---|---|
| 取配对码 | `POST /device/v1/pair/code` | 上报 chip_id/model/版本,拿 6 位码 + `server_time` |
| 查绑定状态 | `GET /device/v1/pair/status` | 只在绑定页内每 5s,不是全局轮询 |
| 换长期 token | `POST /device/v1/pair/claim` | token 存 NVS `pf.token` |
| 资料同步 | `GET /device/v1/profile` | 昵称、星座名;401 = 被吊销 → 回未绑定 |
| 天气 | `GET /device/v1/weather` | 服务端按常住地→出生地选城市;503 = 服务端没配和风 Host |
| 星盘 | `GET /device/v1/astro?lang=` | 太阳/月亮星座 + 当月运势 |
| 校时/心跳 | `GET /device/v1/ping` | 响应带带偏移的 `ts`,顺带刷新 `last_active_at` |
| 扫码取票 | `POST /device/v1/web-login/ticket` | 返回 10 位码 + 二维码 URL |
| 媒体探测 | `GET /device/v1/media/pending` | 有没有变化(seq/rev) |
| 媒体清单 | `GET /device/v1/media/manifest` | 全量清单 + crc32 + rev |
| 媒体下载 | `GET /device/v1/media/{id}/file` | 只放行绑定用户自己的库 |
| 同步回报 | `POST /device/v1/media/report` | synced/deleted + rev |
| 固件检查 | `GET /device/v1/firmware/check?current=` | 指定的目标版本优先,否则同通道更新版本 |
| 固件下载/上报 | `GET /firmware/{id}/download`、`POST /firmware/report` | 只写非运行槽;稳定 60s 后报 success |
实现要点:
- token 形如 `<device_id>:<secret>`,请求头 `Authorization: Bearer <token>` 原样带出去;
- 网络全在后台任务里跑,结果写静态结构由 `loop()` 合并;NVS 与 LVGL 一律主线程;
- 绑定页是模态的:进入相册/音乐/天气时未绑定就升起,点击换码、下滑收起,开着时旋钮与其它手势吞掉。
### 4.2 音频链路(为什么音乐要绕到副控)
主控 I2S 一根线都没接到 DAC;PCM5100 挂在副控的 `GPIO25(BCK)/26(DIN)/27(LRCK)`(`XSMT=GPIO32` 拉高才出声)。
所以"主控解码"这条路不成立:
```
TF 卡 MP3 ──SDMMC──> 主控 AudioLink ──UART1 921600──> 副控 slave_audio
├─ minimp3 软解
└─ I2S 25/26/27 ─> PCM5100
```
帧格式(两边严格一致,改一处必须改两处):
```
AA 55 | cmd | len_lo len_hi | payload | crc8 crc8: poly 0x07, init 0x00
主控→副控 01 START / 02 DATA(≤512B) / 03 END / 04 PAUSE / 05 VOL / 06 STOP
副控→主控 30 STATUS payload=[state, freeKbHi, freeKbLo, 0] 每 250ms 一次
```
流控:副控 64KB 环形缓冲,状态帧上报剩余空间;主控只在 ≥6KB 时继续塞。欠载时副控补静音帧拖住 I2S 时钟,避免"咔"声。
---
## 5. Web 门户 API(`http://nexbuddy.local` / 未配网 `192.168.4.1`)
| 接口 | 说明 |
|---|---|
| `GET /api/status` | 版本、模式、IP、RSSI、电量、TF、天气、分区、当前应用 |
| `GET /api/settings` / `POST /api/setting` | 全部设置项(类型/范围/单位/选项)/ 改一项 |
| `GET /api/files?path=` / `POST /api/cd` | 列目录 / 锁定上传目标目录 |
| `POST /api/upload` / `GET /api/download` / `POST /api/delete` | TF 卡文件读写删 |
| `GET /api/wifi/scan` / `POST /api/wifi` | 扫描热点 / 配网 |
| `POST /api/server/test` | 校验服务端地址并请求 `/healthz` |
| `POST /api/reset` / `POST /api/reboot` | 恢复默认 / 重启 |
| `POST /api/boot/rollback` | 切到另一个槽并重启(另一槽无镜像 → 409) |
---
## 6. 资源预算
| 项目 | 占用 | 上限 |
|---|---|---|
| Flash(app bin) | ≈2.6 MB | 7.5 MB(单槽) |
| 静态 RAM | ≈180 KB | 320 KB |
| LVGL 堆 | 96 KB | — |
| 图片解码缓冲 | 253 KB + 320 KB | 走 PSRAM(8 MB) |
| LVGL 绘制缓冲 | 360×40×2 ≈ 28 KB | 内部 RAM(`LV_BUF_ROWS 40`) |
中文字体是 Flash 大头(UI 子集 ×2 档 + 媒体字体 2500 字 ≈ 900 KB)。
`collect_chars.py` 只收字符串字面量、跳过注释与网页,所以体积可控。
---
## 7. 边界(刻意没做的)
| 项 | 现状 | 后续 |
|---|---|---|
| 音频发声 | 副控解码出声,副控需单独烧一次 | 真机联调:解出第一声后,进度换成副控回报的真实值 |
| 音频格式 | 只解析 MP3 帧头估时长;WAV/FLAC/M4A 能列出但无时长 | 按扩展名补解析 |
| 副控 OTA | 无远程升级通道(主控控制不了副控 EN/IO0) | 只 USB 烧(`tools/flash_slave.sh`) |
| 蓝牙音箱 | 主控只有 BLE,A2DP 需副控重写 | 单独立项(M6) |
| 主题色切换 | 立即生效但已有控件不重建,需重进应用 | accent 变化时重建当前应用 |
| 文本类设置 | 服务端地址/城市等在配网页改,设备端只读 | 设备端九宫格输入法(工作量大) |
| 上传时 UI | multipart 写卡期间 loop 被占,界面卡一下 | 分块让出 CPU 或切"传输中"界面 |
| 天气设置 | 天气应用没有设置项(城市/单位由账号与接口决定) | — |