knob_os/ARCHITECTURE.md

12 KiB
Raw Permalink Blame History

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。 本文只写结构:有哪些层、有哪些模块、它们之间怎么连。

最后核对: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 或切"传输中"界面
天气设置 天气应用没有设置项(城市/单位由账号与接口决定) —