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