# knob_os · 设备固件 跑在 JC3636K518 旋钮屏(ESP32-S3R8 / 1.85" 360×360 圆屏 / TF 卡)上的自研固件。 固件占 **app0 / app1 两个对等 7.5MB 槽**,OTA 在两者之间来回写、互为回滚;原厂固件不再占槽(整片备份在 `00-固件库/设备原机备份/`)。 | 想看什么 | 去哪 | |---|---| | 结构:分层、模块、导航、与平台联动 | [`ARCHITECTURE.md`](ARCHITECTURE.md) | | 怎么改:代码/UI/交互/字体/串口/发版/坑 | [`doc/开发规范.md`](doc/开发规范.md) | | 升级(双槽 / 回滚 / 服务端契约 / 发版) | [`doc/固件更新.md`](doc/固件更新.md) | | 扫码登录(设备出码 → 手机免密进网页) | [`doc/扫码登录.md`](doc/扫码登录.md) | | 界面截图索引 | [`doc/界面一览.md`](doc/界面一览.md) | | 硬件引脚与整机备份 | [`../README.md`](../README.md) | --- ## 能做什么 | 应用 | 内容 | |---|---| | 时钟(默认桌面) | 大号时间 + 秒进度环;旋钮设定番茄钟分钟数,点击开始/暂停,长按归零;工作/短休/长休自动接力 | | 相册 | 读 TF 卡 `/pic/*.jpg`,旋钮或左右滑切换,定时轮播,圆形裁切 + 页码胶囊 | | 音乐 | 本地唱片机:扫 `/music`,解析 ID3 标题/歌手/封面,中央黑胶旋转;旋钮切歌、点击盘心播放/暂停;发声走副控(主控无 DAC) | | 星盘 | 太阳/月亮星座 + 本月运势(平台 `/astro`),旋钮翻页,运势页可滚 | | 我的 | 昵称/太阳星座/常住地/生日与时区(只读);**转旋钮 = 拉一次资料**,**长按屏幕 = 开/关管理二维码** | | 天气 | 平台 `/weather`(服务端聚合和风 + 缓存);温度/体感/湿度/风力,环按湿度填充 | | 设置 | 网络 / 固件 / 系统 / 账号 / 关于;全屏中心聚焦轮盘 | 交互:上划进一级菜单(7 个扇区,只放图标,中心盘显示应用名与 `序号/总数`)→ 旋钮切换、点击进入 → 应用内下滑打开该应用的设置层 → 长按回桌面。旋钮是主要输入,触摸只做点按与滑动。 **绑定**:相册/音乐/天气进入时未绑定会自动升起绑定页,6 位码上屏,网页输码即可;绑定后换长期 token 存 NVS。 **配网**:未配网时开热点 `nex_buddy` / `12345678`,屏幕给出热点名、密码与网址,手机连上会自动弹配置页(captive portal)。 **扫码登录**:「我的」页长按屏幕出二维码(底部 1/3 遮罩层写着这行提示),手机扫码免密进个人页(票据 5 分钟、一码一用)。 --- ## 编译与烧录 ```bash cd 01-开发工作区/新项目/knob_os bash build.sh # → build/knob_os.ino.bin bash ../../工具脚本/flash_app.sh build/knob_os.ino.bin /dev/cu.usbmodemXXXX app0 python3 ../../工具脚本/bootctl.py set app1 # 手动切槽(一般由 OTA 自己切) ``` `flash_app.sh` 把 **分区表 + 目标槽 + otadata** 一起写,槽偏移从 `partitions.csv` 现读,`nvs` 不动 (烧完不用重新配网/绑定);写入前校验体积(7.5MB/槽)与镜像头 `0xE9`。 发版(编译 → 上传 → 发布)用 `工具脚本/release.sh`,详见 [`doc/固件更新.md`](doc/固件更新.md) §6。 改了中文文案要重新生成字体子集,否则新字是方框: ```bash bash tools/gen_font.sh ``` `build.sh` 会先跑 `tools/collect_chars.py --check` 把这件事拦在编译前。 --- ## 串口调试 115200,固件内置命令通道(截屏、切应用、注入旋钮、下发 WiFi/服务端地址、OTA 联调…)。 完整命令表见 [`doc/开发规范.md`](doc/开发规范.md) §9,最常用的几个: | 键 | 作用 | |---|---| | `s` | 截一帧发回主机(存 PNG) | | `1`–`7` | 直接切到第 N 个应用 | | `u` / `d` / `c` | 开一级菜单 / 开设置层 / 全关 | | `+` / `-` | 凭空拧一格旋钮 | | `N` / `V` / `?` | 网络状态 / 槽位与升级状态 / 当前应用与剩余堆 | --- ## 环境 ``` arduino-cli 1.5.1 · esp32:esp32@3.0.7 lvgl 8.4.0 · ESP32_Display_Panel 0.2.2 · ESP32_IO_Expander 0.1.0 esp-lib-utils 0.2.2 · JPEGDEC 1.8.5 · ArduinoJson 7.4.3 ``` FQBN: ``` esp32:esp32:esp32s3:FlashSize=16M,PSRAM=opi,CDCOnBoot=cdc,USBMode=hwcdc,PartitionScheme=app3M_fat9M_16MB,UploadSpeed=921600 ``` > 分区表用根目录 `partitions.csv` 覆盖(不是 FQBN 里那个官方 `app3M_fat9M_16MB`); > `build.sh` 还会把 `upload.maximum_size` 覆盖成 7864320,否则 arduino-cli 按 3MB 校验会误报超限。 > 库版本别随手升级:Display_Panel 0.2.2 是下划线类名,且必须配 IO_Expander 0.1.0。