209 lines
12 KiB
Markdown
209 lines
12 KiB
Markdown
# 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 或切"传输中"界面 |
|
||
| 天气设置 | 天气应用没有设置项(城市/单位由账号与接口决定) | — |
|