cosmo/terminal/firmware
mula.liu 3ad329460c 优化了火箭模拟发射台 2026-10-21 14:52:28 +08:00
..
cosmo_terminal 优化了火箭模拟发射台 2026-10-21 14:52:28 +08:00
README.md 增加了对waveshare-3p49设备支持 2026-10-16 14:18:49 +08:00

README.md

COSMO 轨道终端固件(ESP32-S3)

正点原子 ATK-DNESP32S3 + 2.4 寸 TFTLCD(ST7789V,横屏 320x240)上运行的终端固件。 联网后显示 6 位绑定码,网页端输入完成绑定,之后开机直接用长期 token 鉴权。 绑定完先落模式选择页:天体(该用户关注的天体 + 位置/速度/事件)或 火箭 (平台启用的运载火箭型号 + 参数 + 关联发射任务)。这一页永远是登录后的第一屏: 上次选的那一个会从高亮处记住(NVS 键 mode),但要再按一次 KEY2 才真正进去—— 换环境时先看清网络/后端地址再进去,比直接掉进一个空列表有用。同一页 KEY3 进设置页。

硬件

项目 说明
主控 ESP32-S3(8MB OPI PSRAM / 16MB flash)
屏幕 2.4" ST7789V 模块,4 线 SPI:SCK=12 / MOSI=11 / MISO=13 / DC=40 / CS=21
LCD 复位·供电·背光 板上 XL9555 IO 扩展器(I2C:SDA=41 / SCL=42,地址 0x20)
按键 KEY0..KEY3 走 XL9555(P1_4..P1_7),BOOT=GPIO0
触摸 无。这块 2.4 寸屏只有 ST7789V,没有触摸层
串口 S3 原生 USB 口(USB-Serial/JTAG)→ /dev/cu.usbmodem2101,115200;CH340 UART 口 → /dev/cu.usbserial-210,取决于固件编译时的 USB Mode,见「构建 / 烧录」

WIRE_DC / LCD_DC 跳线帽必须短接(SPI 模式),引脚集中在 src/board_config.h。

第二块板:Waveshare ESP32-S3-Touch-LCD-3.49(长条屏 + 触摸)

同一份源码用 -DCOSMO_BOARD=3 编出的第二个目标,引脚全部集中在 src/board_config.h:

项目 说明
主控 ESP32-S3(8MB OPI PSRAM / 16MB flash)
屏幕 3.49" 长条屏 640x172,AXS15231B,QSPI:CS=9 / SCK=10 / D0..D3=11,12,13,14(无 DC 线、无 GPIO 复位脚)
面板朝向 面板原生是 172x640 竖排,横屏由 disp_flush() 软件转置,UI 只认逻辑画布 640x172
触摸 AXS15231B 自带电容触摸,第二条 I2C:SDA=17 / SCL=18,地址 0x3B(与屏共用一片硅,总线独立)
供电·复位·背光 TCA9554 @0x20(系统 I2C:SDA=47 / SCL=48):SYS_EN=bit6、LCD_RST=bit5、BL_EN=bit1;背光 PWM GPIO42,低电平亮
按键 只有 BOOT(GPIO0)。侧面 PWR 是电源锁存、RESET 是 EN,都不能当按键用
电池 18650 座 + ETA6098C1 充电。电压经板上 3:1 分压(R3 200K / R15 100K)进 BAT_ADC=GPIO4=ADC1_CH3,所以脚上 mV x3 = VBAT
充电状态 没有状态脚:ETA6098 的 STAT 只接指示灯,TCA9554 八个脚也全被占用(bit0 触摸中断 / bit1 背光 / bit2,3 IMU / bit4 RTC / bit5 屏复位 / bit6 SYS_EN / bit7 NS_MODE),所以是否充电只能按 USB 在位近似
串口 S3 原生 USB → /dev/cu.usbmodem2101(FQBN 用 USBMode=hwcdc,CDCOnBoot=cdc)

坑:TCA9554 的 bit6(SYS_EN)绝不能拉低。 它和板 1 的 XL9555 同址(0x20)但只有 8 位、 寄存器编号也不同,照板 1 的初始化写法写进去就是整板断电——现象是"烧完没反应,像变砖"。 SYS_EN 是电源锁(PWR 键只是临时接通):上电第一件事就是把它拉高,见下面「电池与开机」。 复位和背光分别走 bit5 / bit1。 V1 版板上没有 TCA9554,探测不到 0x20 时退回直连:RST=GPIO21、背光=GPIO8。

输入方式:只有按键,没有触摸

设计稿里的底部按钮不能点——这块屏不带触摸层。两条证据:

  1. 屏模块的 8 pin 插座只有 PWR GND / CS 3V3 / WR SCK / RST SDA,没有 TOUCH_PEN/TOUCH_CS;
  2. 串口 i2cscan 在 I2C 上只扫到 0x10 / 0x12 / 0x1E / 0x20(XL9555) / 0x50(EEPROM), 没有 GT911(0x5D/0x14)、FT6x36(0x38)、CST0xx(0x28) 之类的触摸控制芯片。

所以交互全部走板子右侧丝印的实体键(KEY0..KEY3)+ BOOT:

键 位置 列表页 详情页 配对页
KEY0 右侧最上 上移 上移 —
KEY1 右侧第二 下移 下移 —
KEY2 右侧第三 进详情 返回列表 查看配对码说明
KEY3 右侧最下 立即刷新 右栏翻页 EVENTS/INFO 重新要一个码
BOOT 板上 GPIO0 等同 KEY2 等同 KEY2 等同 KEY2

屏幕底部那一排方框(设计稿里 [ORBIT][COMM][SYS] 那个造型)就是这几颗键的图例: 金色描边金字,按下时整块变金底暗金字 250ms 作为反馈,键名直接印在框里(KEY2 OK / KEY3 TAB…)。 串口 key 0xNNNN 注入的按键走同一条路径,反馈一样。

排查按键(键没反应时先看这两条):

# xlreg 打印 XL9555 四个寄存器;空闲时 input 应为 0xFFxx(P1_4..7 全高)
# 依次按 KEY0..KEY3 / BOOT,每颗停一秒,日志里 [key] changed=0x.... 会直接指出是哪一位
~/esp-tools/pio_env/bin/python terminal/tools/key_watch.py 240 /tmp/keywatch.log

坑:XL9555 读寄存器必须先写地址指针。 Wire.requestFrom() 之前不写 pointer, 读到的是上一次写之后自增到的位置(output/config),按键永远读不到,屏幕对实体键毫无反应。 read_reg() 里那句 endTransmission(false) + requestFrom() 就是修这个的。 空闲 input=0xFFFD:低字节 P0_0 是 ALS 光敏(悬空为低),所以按键只取高字节,避免幽灵按键。

电池与开机(18650)

src/power.cpp,只在 BOARD_HAS_BATTERY=1(板 3)编译。

事 做法
电源锁 setup() 第一件事(在 NVS / 屏 / 触摸之前)调 pwr_hold_early():读回 TCA9554 的 OUTPUT/CONFIG,先把输出锁存 bit6 写 1、再把方向改成输出(反过来会瞬间把 SYS_EN 拉低 = 电池供电时直接关机),日志 [pwr] SYS_EN=1
电压 analogSetPinAttenuation(4, ADC_11db) + analogReadMilliVolts()(core 自带曲线校准),8 次去最高最低取平均再 x3
电量 单节锂电曲线中间平两头陡,只能按表插值:3300mV=0% 3680=20% 3750=40% 3930=70% 4100=92% 4200=100%
充电 Serial.isPlugged()(= usb_serial_jtag_is_connected())—— USB 在位就当在充
显示 状态栏网络状态后面画一颗通行样子的电池(ui.cpp 的 bat_label()):外壳 + 右端铜帽,壳内按电量比例填一段,充电时在壳内叠一道白色闪电。颜色:充电绿 / ≤15% 红 / ≤30% 橙 / 其余青 / 没装电池只留灰壳。总宽 28,比原来那句 CHG 97% 还窄
采样 loop() 里 bat_poll() 每 2s 一次,显示值变了才置 g_dirty 重绘

按 PWR 不亮是这台板子的常态坑,不是坏了。 PWR(GPIO16, 原理图 SYS_OUT) 只是把电源临时接通, 松开就得靠固件拉高 SYS_EN 维持;老固件要等 disp_init() 才写这一位,中间隔着 delay(400)

  • 挂载 NVS + 屏初始化,短按(<0.5s)必然掉电,现象就是"按了不亮"。现在锁电排在 setup() 第一行(写完寄存器约 0.3s)。 判断电池到底装没装,不能靠 batt 的电压:座子空着、只插 USB 时那颗充电 IC 的电池端会空载浮到 ~4.2V,屏幕照样给你 CHG 97%(见下面「没有电池也显示 CHG 97%」)。硬判据只有一个:开机后直接拔 USB, 屏幕继续亮 = 电池通路和电源锁都成立;立刻黑 = 电池根本没接通。batt 打出来的 SYS_EN=1 (held) 只证明锁存寄存器写进去了,证明不了电池真在供电——判据始终是拔 USB。

长按 PWR 关机(已实现):pwr_key_poll() 每帧读 IO16(按下=低),按住 ≥3 秒后松手 就把 SYS_EN 写 0,松手瞬间 Q2 关断、整板断电;官方例程同理,文案是「长按 PWR 按键, 等待屏幕显示 OFF…松开按键即可」。两条前提写在 power.cpp 的注释里,都是必须的: ① 开机那一次长按作废(必须先见到一次松手,否则每次开机都被自己关掉); ② USB 插着时直接忽略并打印提示 —— VBUS 经 D1 还在供 VSYS,写 0 不会断电, 只会变成"按了没反应"。所以这条只能拔了 USB 试;重新开机是纯硬件的,长按 PWR 即可。

先说清楚:电池在哪、哪根线是什么

这块板上电芯只有一个去处:压在板子中间的黑色 18650 座里。 丝印 BAT 旁边那两个孔是 没有贴塑壳座的 MX1.25-2P 焊盘(BOM 备注 NC/插座 直针拔插式 MX1.25-2P = 可选不贴), 不能拿"BAT 座空着"当"电池没装"的依据。丝印 SPK 上那根红黑双绞线是外壳盖子里小喇叭的喇叭线 (另一端接 NS4150 功放输出),和电源通路无关,别拔也别往别处插。

没有电池也显示 CHG 97%(这是硬件信息缺失,不是显示 bug)

batt 读的是 BAT_ADC 分压后的 VBAT 母线,不是电芯本身;而 ETA6098C1 的 STAT 只接了 指示灯 LED1(串 R10 27K),没有任何电池在位/充满状态脚进 MCU,TCA9554 八个脚也全占满了。 所以取下电芯、只插 USB 时,充电 IC 的电池端空载浮到 ~4.2V,屏幕上就必然是 CHG 97%。

电芯在不在,只能靠"装与不装的电压差"证明(同一块板实测):

状态 batt 说明
电芯压在座里 3750~3800mV 电芯把母线钳住了 → 电芯确实接在 VBAT 网络上,充电/采样通路是好的
取下电芯 4162mV 空载浮压

推论:不要用 batt 的电压判断电池在不在,也不要拿它当"电芯坏了"的依据。 硬判据只有一个:开机后直接拔 USB,屏幕继续亮 = 电池通路 + 电源锁都成立。

真因(已修复):TCA9554 方向寄存器地址写错,0x02 应为 0x03

先认错:这一节之前写的是"电源锁硬件断、P6→R43→T1 虚焊、建议走售后/飞线",那是错的, 而且是我自己造的错。板子没问题,是我们固件的寄存器编号写错了。

真机验证通过:烧录修复版之后长按 PWR 开机、拔掉 USB,屏幕保持常亮;排查期临时命令 读回的 in=0xE2(bit1/5/6 读回 1)是"引脚真的在输出高"的旁证,不是自己刚写进去的那个字节。 (pwr / hold / holdio / sysout 这几条排查命令已经删掉,结论只留这一节。)

TCA9554 只有 4 个寄存器,方向不在 0x02:

地址 寄存器 上电默认
0x00 Input Port(只读) —
0x01 Output Port(输出锁存) 0xFF
0x02 Polarity Inversion(输入极性反转) 0x00
0x03 Configuration(方向,1=输入) 0xFF

三处独立出处:TI 手册 Table 3(ti.com/lit/ds/symlink/tca9554.pdf);官方 V2 仓库 Arduino/examples/08_Audio_Test/src/codec_board/drv/tca9554.c 的 TCA9554_CONFIGURATION_PORT 0x03;Arduino/examples/07_BATT_PWR_Test/src/tca9554/esp_io_expander_tca9554.c 的 DIRECTION_REG_ADDR 0x03。

我们 board_config.h 写的是 TCA_REG_CONFIG 0x02。来源很好解释:另一块板上的 16 位扩展器 XL9555(TCA9535 兼容)里 0x02 确实是 P0 方向,而这里 TCA_REG_INPUT/OUTPUT 又用的是 8 位 TCA9554 的编号,两张表混抄就错位了一格。后果:

  • 方向寄存器从头到尾没被写过 → 上电默认 0xFF → 八个 EXIO 全是高阻输入;
  • 写 OUTPUT 只改芯片内部锁存,引脚不驱动 → SYS_EN 从未真正拉高过 → 拔 USB / 松手必掉电;
  • 最阴的一点:排查命令读回的就是我们刚写进 0x02 的那个字节,cfg=0x9D 看着严丝合缝, 是自证式假证据;把八个位全拉高同样无效,因为无效的原因根本不在位映射上。 由此得出的"这颗片方向=输出时不更新 input register""P6 拉不高"两条推论一并作废。
  • 附带副作用:0x9D 被当成极性反转写进去了,bit1/5/6 的输入读数会取反(只影响读,不影响功能)。 正常上电复位后是 0x00,不用额外清。

为什么"按住 PWR 能开机、能进系统"和这个 bug 完全不矛盾:按键支路是把 Q2 gate 直接短到 GND 的 纯硬件通路,和 SYS_EN 驱动的是同一个 gate。它能亮只证明功率级(电芯/Q2/R42/VSYS/3V3)是好的, 一点也证明不了固件写对了寄存器 —— 我当时正是把这条当成了"固件已经生效"的证据。

为什么 EXIO1(EXIO5) 浮空时屏也正常:背光使能和复位这两条网络板上本就有偏置,屏还另有驱动自带 的复位兜底,所以"屏能用"从来没验证过扩展器真的在输出。修好方向之后我们走的正是官方 lvgl_port.c 那套:example_lcd_exio_init() 把 BL_EN|LCD_RST 设输出、BL_EN=1 点亮, example_lcd_reset() 高 30ms → 低 250ms → 高 30ms(我们 panel_power_on() 同序)。

如果修好方向之后仍然"拔 USB 就黑",再动硬件:运行时量 TCA9554 第 11 脚(P6)≈3.3V、 R43 右端(T1 base)≈0.7V、Q2 gate≈0.6V。P6=3.3V 而 base≈0V = R43/T1 那侧断; P6 本身 0V 而寄存器确实是输出+高 = 片子侧问题。这三个读数是售后判据,0402+SOT-23 不建议自己补焊。

网传"SYS_EN=GPIO48(V2)/GPIO47(V1) 硬锁"是假的:官方引脚表直接否掉

官方手册 V1、V2 两张接口表(docs.waveshare.net/ESP32-S3-Touch-LCD-3.49 的「接口介绍」)里:

脚 官方标注
IO47 IMU SDA / RTC SDA / Audio SDA
IO48 IMU SCL / RTC SCL / Audio SCL
IO16 SYS OUT
IO4 BAT ADC
EXIO6 SYS EN(TCA9554 一列,全表只出现这一次)

47/48 在 V1、V2 两版上都明确是 I2C(我们固件也把它们当 SDA/SCL 用,四颗从机全部正常应答), 根本不可能同时是电源锁;"V1=47、V2=48"是编的,官方 V1↔V2 差异清单只有四条(新增 TP_INT、 锂电充电电流、LCD_TE↔LCD_RESET 互换、LCD_BL↔EXIO_INT 互换),与 47/48 无关。 照抄那段代码只会把 I2C 时钟脚按住,锁不到电。

官方 07_BATT_PWR_Test 的说明原文也印证机制只有一套:tca9554_init()「初始化锂电池控制 IO 端口」 (set_dir(SYS_EN, OUTPUT) + set_level(SYS_EN, 1))、「断开 USB 供电,接入锂电池,通过长按 PWR 按键进行开机」「等待屏幕显示 ON…松开按键即可」—— 和我们的做法一致,和 GPIO 硬锁无关。

⚠️ 顺带留档:SYS_OUT(GPIO16) 不是第二条保持路,只是感知脚。它的网络是 3V3 → R9 10K → IO16 → D3 → Key1 节点,IO16 输出低只会让 D3 反偏、灌不进电流,锁不住; 反过来 latch 断开时该节点被拉到 ~3.5V 使 D3 反偏、IO16 读到高,按下 PWR 才把 IO16 拖低 —— 所以官方例程里 gpio_get_level(16)==0 表示"按键按下"。实测把 GPIO16 拉低也断不开电源, 与这个网络分析一致。

输入方式(长条屏):全触摸,没有按钮区

172 高只有 22mm,底部按键条要吃掉半行内容,右缘抽屉也要来回开合,都别扭。所以长条屏 不画任何按键条(KEY_H 0),内容区 CONT_W 就是整幅 640,页面级动作只留状态栏右上角 1~2 颗上下文按钮(header_actions() / header_buttons()):需要什么就出现什么, 不需要时那一行只有标题。

页面 右起第一颗 第二颗
模式页 ⚙ SETUP
天体列表 / 火箭列表 ‹ BACK
天体详情 / 火箭详情 ‹ BACK(画在页头那一行)
连接中 ≡ CONFIG
配网页 ‹ BACK
设置页 ‹ BACK ≡ CONFIG
配对页 ◎ CODE ≡ CONFIG
故障页 ◎ RETRY ≡ CONFIG
升级页 ‹ BACK(下载中整行不画) ⤓ INSTALL / ◎ RETRY

齿轮 ⚙ SETUP 进的是只读的设置页;滑杆 ≡ CONFIG 直接进配网门户(改 WiFi、改后端地址都在那里)。 同一页上两颗按钮不会撞事。

  • 每颗按钮点下去就是 on_key_press 早就认识的那颗实体键(右起第一颗 = KEY3,第二颗 = KEY2), 业务逻辑一行没为触摸改写。
  • 图标 + 英文:ui_glyph() 用线稿画 14x14 的图标(返回箭头 / 齿轮 / 滑杆 / 环形箭头 / 下载), 右边跟一个英文词。图标负责一眼认事,英文负责说清是哪件事——中文一个词 2~3 字要 34~51px, 英文 4~7 个字母只要 36~63px,两颗按钮加标题才不会把 640 宽挤满。
  • 按钮宽 = HDR_PADx2 + 图标 14 + HDR_IV(4) + 英文字宽,视觉 HDR_BTN_H 24px 高(文字上下各留 3px)、 热区 HDR_HIT_H 31px (整条 header 0..30 都算命中,这屏 1px≈0.13mm,只按字面那 24px≈3mm 太难点)。 状态栏右端的用户名 等文字用 s_info_r 按按钮总宽往左让位。
  • 详情页只有一层 header:天体 / 火箭详情不再画状态栏,0..19 那一行直接是页头(标题 + 历元 / NEXT 日期),内容区从 TOP_Y 起,省下的 16px 给图标格和信息栏,右栏事件行距也摊开。
  • 点内容:列表卡、火箭卡、模式卡都注册了 HIT(),点哪张就选哪张,模式页点卡片直接进对应终端。
  • 详情页分页标签也直接可点(UI_ACT_TAB + 页号)。
  • 滑动翻页:上下滑 = UP/DN(列表滚动),左右滑 = 第四键(刷新 / 右栏翻页 / 回模式页)。
  • 列表页右缘的上下键(nav_rail()):垂直居中两颗图标按钮,等价 KEY0/KEY1,和上下滑是同一 件事——滑这块屏容易误判成卡片点击,列表页给两颗实心的更跟手。它们占的 RAIL_W(30) 会从 CARD_W 里扣掉,卡片不会压在按钮下面;只在天体 / 火箭列表页出现,详情页不加。 列表空着或者总数不超过一页(cnt > LIST_ROWS 不成立)时整组禁用:按钮照画但边框降到 C_TRACE、箭头降到 C_CYAN_DIM,并且不登记热区——点了没反应的东西不能还长得像能点。
  • BOOT(GPIO0) 等同「确认」,触摸没校准时用它兜底退出。
  • UI_ACT_TAB 是热区里的页面内动作,由 tp_gesture_run() 自己消化,不进 on_key_press。
  • 命中区上限 UI_MAX_HITS 16(两颗按钮 + 一屏卡片 + 分页标签,远够用)。
  • 版面常量在 src/ui.cpp 顶部(STRIP / HDR_TY / HDR_LINE / TOP_Y / CONT_W / RAIL_W / CARD_W),按钮那组在 header_actions() 附近(GLYPH_SZ / HDR_PAD / HDR_IV / HDR_GAP / HDR_BTN_H / HDR_HIT_H)。

触摸状态机:宁可丢一下,不能点错

先量清楚假信号有多大,再定规矩。touch on 期间每次采样都进统计(src/touch.cpp 的 touch_stats_*),每秒打一行 [tp] poll=N true=N len1=.. len2=.. len3=.. len4+=.. max=N@(x,y) span=N:

场景 采样 有手指的帧
空闲 40s 3280 0
开机 + 3 次 reload(HTTP 阻塞 + 整屏重绘) ~4500 0

结论:AXS15231B 在没人碰的时候不冒假帧,"误点"不是控制器的问题,全部出在代码怎么 解读坐标上。所以 touch_tick() 定三条(TP_* 一组常量):

规矩 常量 治的是
按下要连续 2 帧才成立,落点只取确认帧的均值,抬手那一帧的坐标一律不用 TP_CONFIRM 2 / TP_RELEASE 2 指尖抬起瞬间会漂几十像素,拿末帧查热区就点到隔壁卡
滑动要连续 2 帧都压在 TP_SWIPE_PX(48) 之外才算,方向在确认那一刻锁死 TP_SWIPE_HOLD 2 首末两帧之差判滑动 = 一帧坐标毛刺就自己翻一页(列表页"不稳"的真相)
一次接触超过 3s 当作卡住的假信号丢掉 TP_CONTACT_MS 3000 手指压着不动 + 网络正忙时,别让手势一直举着

排查手法:touch on 之后按 [tp] (x,y) key=0xNNNN idx=N 对号,误点时先确认派发的坐标 是不是手指那一处;tap <x> <y> 用同一套结算路径注入一次点按,可以脱离手指验热区。 若还要调手感,动 TP_CONFIRM(加到 3 更稳但更钝),别动 TP_POLL_MS(12ms 对应 ~82 次/秒的实测采样率,再慢就会漏快点)。

触摸坐标→画布的映射必须和 disp_flush() 的软件转置严格互逆 (panel_x ← 逻辑 y、panel_y ← 逻辑 x,两轴各自可镜像)。出厂映射为 TP_SWAP_XY=1、 TP_INVERT_X=0、TP_INVERT_Y=1,等价于官方 LVGL 例程里的 point.x = rawY、point.y = 640 - rawX, 已在真机上用手指加串口 tap 逐页对过热区。若换了面板方向或出现「点左边却出在右边」,先 touch on 点四角读回报,再调 src/touch.h 里这三项。dump / screen_shot.py 抓的是转置 之前的逻辑帧缓冲,能验证版面但验证不了转置方向;正放 / 倒放由加速度计自动判(flip auto)。

构建 / 烧录

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy    # 本地代理端口是死的,会拖死下载
# 当前这块板子插的是 CH340 那根线 -> CDCOnBoot=default,控制台在 /dev/cu.usbserial-210
FQBN='esp32:esp32:esp32s3:PSRAM=opi,FlashSize=16M,FlashMode=dio,CDCOnBoot=default,PartitionScheme=app3M_fat9M_16MB,UploadSpeed=460800'
~/esp-tools/arduino-cli --config-file ~/esp-tools/arduino-cli.yaml compile --fqbn "$FQBN" terminal/firmware/cosmo_terminal
~/esp-tools/arduino-cli --config-file ~/esp-tools/arduino-cli.yaml upload  --fqbn "$FQBN" --port /dev/cu.usbserial-210 terminal/firmware/cosmo_terminal

长条屏(板 3)同一份源码多一个宏,先 --output-dir 再 --input-dir 烧,只重刷变化的扇区:

FQBN='esp32:esp32:esp32s3:PSRAM=opi,FlashSize=16M,FlashMode=dio,USBMode=hwcdc,CDCOnBoot=cdc,PartitionScheme=app3M_fat9M_16MB,UploadSpeed=460800'
~/esp-tools/arduino-cli --config-file ~/esp-tools/arduino-cli.yaml compile --fqbn "$FQBN" \
  --build-property "compiler.cpp.extra_flags=-DCOSMO_BOARD=3" \
  --output-dir /tmp/cosmo_fw3 terminal/firmware/cosmo_terminal
~/esp-tools/arduino-cli --config-file ~/esp-tools/arduino-cli.yaml upload --fqbn "$FQBN" \
  --port /dev/cu.usbmodem2101 --input-dir /tmp/cosmo_fw3 terminal/firmware/cosmo_terminal
  • PSRAM=opi 必须开:帧缓冲放在 PSRAM(板 1 是 320x240x2 = 150KB,板 3 长条屏 640x172x2 = 220KB,两块都放不下内部 RAM)。
  • COSMO_BOARD 只切硬件抽象,版面用 STRIP(LCD_HEIGHT < 200 自动为 1)自己适配,板 1/板 2 的版面常量不受板 3 影响。板 3 当前 Sketch uses 1524395 bytes (48%)。
  • USB 口选哪个决定串口在哪:USBMode=hwcdc,CDCOnBoot=cdc = Serial 走 S3 原生 USB(USB-Serial/JTAG,/dev/cu.usbmodem2101), 一根线同时能烧录和看日志/敲命令;换成 CDCOnBoot=default(=Disabled)则 Serial 落回 UART0/CH340, 要用 /dev/cu.usbserial-210。两种 FQBN 都能烧录(USB-Serial/JTAG 自带下载模式),但只有前一种能在原生口拿到日志—— 后面那种配 tools/*.py 得先把 PORT 改回 usbserial-210。
  • 烧录速率用 460800;921600 在这块 CH340 上会 Unable to verify flash chip connection。
  • 分区表 app3M_fat9M_16MB:app 3MB,当前 Sketch uses 1503518 bytes (47%) (内置兜底图标 + 模式页 96x96 大图 + 中文字库 125KB)。
  • 依赖:Arduino 核 esp32:esp32 3.3.12 + ArduinoJson 7.4.3,其余都是核心自带库。

界面:设计稿语言与离线资源

版面常量在 src/ui.cpp 顶部,全局统一:状态栏 y0..19(下沿一条 C_CYAN_DIM 分隔线)、 内容区 TOP_Y=22 .. BOT_Y=212、按键条 KEY_Y=216 高 20。列表页 3 张卡 y = 22 + n*65、h=60、cut=8,右缘 2px 滚动条。详情页:标题 y20、POS/VEL 两块 156x88(y40,左青右金)、下方左侧 88x81 天体图(雷达底纹 + 64x64 图标叠加)、 右侧 222x81 分页面板,[EVENTS] / [INFO] 由 KEY3 循环切换(INFO 页 = 中文名 + 中文简介, 12 字/行 x 2 行,第二行末尾留一个字位给截断标记 ..;面板高度放不下设计稿里的 3 行)。配色取自设计稿取色,见 src/display.h 的注释。

新增的两页沿用同一套常量:模式选择页 = 两张 150x146 面板(x = 8 + i*154、y=42、 cut=10,96x96 大图标 + 中文名 + 英文标签,选中的亮青边 + 左侧 3px 金条);火箭列表和 天体列表同为 3 张 314x60 卡,右列火箭是"还有几次发射"、天体留白(设计稿那个 ON/OFF 胶囊只是后端 is_active 的只读镜像:按不动,也改不了订阅,画成开关只会让人一直想按, 已去掉);火箭详情上半 156x88 两块(SPECS 青 / PERFORMANCE 金),下方左 88x81 立绘(雷达底纹 + 64x64 叠加)、右 222x81 三页面板 LAUNCH / STAGE / INFO。

面板统一用**切角(chamfer)**图元 disp_panel(x,y,w,h,cut,fill,border),需要辉光时先 disp_panel_glow() 在外侧描一圈低阶色。背景 disp_bg() = C_BG + 固定伪随机星点 + 角落电路走线,纯程序化,不占 flash。

内置图标和字库都是离线生成、提交进仓库的,编译时不需要 Pillow。 天体图标已经改成后台维护、运行时下载(见下一节),这套内置图标现在只当兜底:

/usr/bin/python3 terminal/tools/gen_assets.py     # 只读 资源文件/*.jpeg 和本机字体,无联网
  • src/icons.{h,cpp}:资源文件/*小.jpeg(320x320 纯黑底霓虹线稿)→ 亮度 bbox 裁切 → 补方 → LANCZOS 缩到 40x40(列表)/ 64x64(详情)→ 黑底门限 → RGB565。没有 alpha 通道, 运行时 disp_add_bitmap() 做加色混合(逐通道饱和相加),所以源图必须是纯黑底, 否则灰底会把整块面板糊白。icon_for(name, name_zh, type, detail) 先按名字小写子串匹配, 命不中再按后端 6 种 type 兜底,最后 planet。没有专属图的天体(水星/天王星/冥王星系) 就用 行星小.jpeg,不做假色相。后台没维护图标的天体走的就是这张表,见下一节。
  • 模式选择页两张 96x96 大图和火箭兜底图也是这个脚本出的:ic_mode_planet_96 / ic_mode_rocket_96 / ic_rocket_list / ic_rocket_detail。火箭那张不是画死的, 是脚本直接调后端的 app.services.rocket_art 用一组合成参数现画再降采样, 所以终端的兜底立绘和后端按登记参数画的立绘是同一套几何。
  • src/font_cjk.{h,cpp}:16x16 点阵,GB2312 一级字 3755 + 常用中文标点和 °×℃ = 3775 字(点阵 118KB + 索引 7.4KB)。STHeiti Medium 160pt 渲染 → 取 em 见方 158px 裁切 (字身中心下移 4px 找齐)→ BILINEAR 降到 16x16 → 阈值 130 二值化; 墨迹超过 55% 自动加严阈值防粘连,一点墨都没有则自动放宽。 按码位升序存 s_codepoints[] + s_glyphs[][32],运行时二分查找,缺字画空心方框 □。 disp_text() 按 UTF-8 逐字符分流:ASCII 走 font_asc2.h(推进 9px),中文走点阵(推进 17px); size=32 时中文按 2x2 块放大。截断一律走 disp_text_clipped() / clip_chars(), 保证不切断 UTF-8 序列。

双模式:天体 / 火箭

绑定完成 / 开机拿到 token -> SC_MODE 模式选择(KEY0/KEY1 选,KEY2 进,KEY3 -> SC_SETTINGS)
   天体 -> GET /api/terminal/follows          列表 -> 详情(EVENTS / INFO)
   火箭 -> GET /api/terminal/rockets          列表 -> 详情(LAUNCH / STAGE / INFO)
                        GET /api/terminal/rockets/{code}            参数 + 关联发射任务
                        GET /api/terminal/rockets/{code}/art?size=  按参数画的立面图点阵
  • 模式是持久化的:NVS 键 mode,值 0=天体 / 1=火箭,只用来决定模式页高亮哪一个 (不再"直达列表"——登录后一定先停在模式页)。串口 mode bodies|rockets|clear 可以免按键改, clear 把选择忘掉;reset 会连它一起清,只想重启用 reboot。
  • 设置页 SC_SETTINGS(模式页 KEY3):两块切角面板,只读地把"网"和"后端"摊开—— WiFi 在线/离线 + SSID + RSSI + 局域网 IP + 热点名,以及后端 URL + 绑定用户(BOUND/NOT BOUND)
    • 设备号 + 当前模式 + 日期时间(TIME,见下条)。要改东西按 KEY2 SETUP 进配网门户 (那里能同时改 WiFi 和后端地址),KEY3 BACK 回模式页。这两页都不发数据请求,所以不会被 5 分钟轮询踢走(loop() 只给 LIST/DETAIL/ROCKETS/ROCKET 调 run_tick),但每 60s 会被 auth_check() 拿一次 GET /api/terminal/follows 校验令牌,见「绑定与取数」。 串口 settings 直接跳这页。
  • 时钟只有一个来源:后端(src/clock.{h,cpp})。板子没有 RTC 电池,断电商 millis() 就归零, 所以每次 follows / rockets 回来都用响应里的 server_time(后端 datetime.utcnow(),UTC) 校准一次,两次校准之间按 millis() 走时;断网就照着手上的时间继续走,等下一轮刷新纠偏。 屏上显示的是 UTC + CLOCK_TZ_MIN(默认 +08:00:后端和库里都没有用户时区,换地区改这一个常数), 没同步过之前显示 --。只有设置页按秒重绘(loop() 里 SC_SETTINGS 那一支), 别处不会为了一颗时钟白刷整屏。日历换算是自己写的整数运算,不用 timegm (Arduino 的编译选项下 newlib 没暴露它的声明)也不用 mktime/gmtime(要吃本机 TZ), 好处是这套换算能直接在 PC 上 cc 出来对着 Python 逐日校。
  • 火箭立绘 = 后端按登记的火箭参数现画(backend/app/services/rocket_art.py),和 3D 模拟页共用 stageGeometry 那套几何:整流罩/级间段/助推器/栅格翼的尺寸全部来自平台里 登记的型号参数。参数哈希 art_ver 随列表下发,版本没变就一个字节都不重新下载, 列表只缺 40x40、进详情才拉 64x64(src/rocketstore.{h,cpp},PSRAM 里一个型号一个槽)。 拉不到(后端不通/型号没有)就退回固件内置那张线稿,版面不空。
  • LAUNCH 页那一行显示的是任务名,不是型号名:rocket_events.name 来自数据源,形如 Falcon 9 Block 5 | Starlink Group 15-25,型号已经是这页的标题了,前缀只会把真正的任务名 挤出面板边界,所以 build_rocket_detail() 下发的是 mission_name or name。 发射日期改成行尾右对齐成一列,"什么时候打什么"还是同一行读完。
  • 长任务名用中间省略,不用尾部省略(ui.cpp::text_elided):Starlink 这一类名字的区别 全在结尾的编号上,disp_text_clipped 那种掐尾巴会把 Starlink Group 15-25 打成 Starlink Group ..,等于三行都长成一样。所以先按整词把后缀收进右半边宽度, 剩下的宽度全部给开头,.. 夹在中间连成一串(Starlink G..15-25)——头和尾之间刻意 不留白,留白了 ..15-25 会被读成右边那一列发射日期;一个词都塞不下(超长词/中文) 才退到按字符收后缀。
  • 按键:列表页 KEY0/KEY1 光标、KEY2 进详情、KEY3 回模式选择页(天体列表原来 的"手动刷新"让给了模式页,刷新由进入时 + 5 分钟轮询覆盖);详情页 KEY0/KEY1 换上下 一个型号(火箭详情必须重新拉一次明细)、KEY2 回列表、KEY3 右栏翻页。 5 分钟轮询到人停留在详情页时不会把他踢回列表。

天体图标:后台维护,运行时动态拉取

设计稿里的天体图标不是编译死的:平台管理 -> 天体信息 -> 资源配置 -> 图标 里换一张图, 终端下一次数据刷新(5 分钟轮询或串口 reload)就跟着换。

后台 resources 表里 resource_type='icon' 的行(文件在 backend/upload/icon/*)
  -> 后端用 Pillow 现算成定长 RGB565 裸点阵(40x40=3200B / 64x64=8192B)
  -> GET /api/terminal/bodies/{id}/icon?size=40|64        (Bearer 终端 token)
  -> 固件直接喂 disp_add_bitmap() 加色混合,不解码 JPEG/PNG
  • 渲染:app/services/terminal_icon.py:render_rgb565(),流水线(亮度 bbox 裁切 → 补方 → LANCZOS → luma<=10 归零 → RGB565)和 terminal/tools/gen_assets.py 的 icon_pixels() 一致, 同一个源文件两边输出逐像素 0 差异,所以后台传的图和内置图是同一套视觉语言。 源图照旧要求纯黑底(没有 alpha,灰底会把整块面板糊白)。Pillow 本来就在 requirements.txt(10.1.0),没新增依赖。
  • 版本门控:/api/terminal/follows 每个天体多返回一个 icon_ver(= 图标资源行的 id, 也是图标端点的 ETag)。固件只在 icon_ver 变化时下载,稳态零流量。 一次 HTTPS 往返 ≈0.9~1.7s(大头是 TLS 握手,真机 RSSI -76~-82),比当年在局域网里 测的 ~130ms 慢一个数量级,所以图片一律不挡页面:见下面「补图与忙碌反馈」。
  • 换图是覆盖语义:同一个天体同一种资源类型只保留一行,重复上传时后端删掉旧行 并删掉旧文件(app/api/celestial_resource.py)。终端只在 icon_ver 变化时重下, 管理端预览/删除的 items[0] 和后端取的那一行从此指向同一张图。 (只有 icon 是覆盖;texture / model 是多值列表,追加语义保持不变。)
  • 固件缓存 src/iconstore.{h,cpp}:一个关注天体一个槽(上限 MAX_BODIES=6), 点阵 heap_caps_malloc(MALLOC_CAP_SPIRAM|MALLOC_CAP_8BIT) 惰性分配,每槽 3200+8192=11392B,最坏 6 槽约 68KB PSRAM;取消关注的槽在下次 sync 时释放(缓冲区留着复用)。 stat 会给每个槽打一行 icon : 599 v45 40 64(列出这个尺寸已经缓存了哪两张)。
  • 字节序:点阵按大端下发(和串口 dump 同一个约定),api_icon() 收完逐像素 __builtin_bswap16() 转回本机序——disp_add_bitmap() 吃的是普通 uint16_t RGB565 值。 忘了转会整屏颜色字节互换,fb_check.py --raw 实测最大逐像素误差 ~58000。
  • 兜底:后台没维护(404)/ 文件丢了(404)/ 解不开(502)/ 长度不符 / size 非法(400) → icon_store_get() 返回 NULL,UI 落回内置线稿,屏幕不会出现空洞。 Venus 后台没维护图标,正好当兜底的回归用例。

核对不用肉眼盯 960x720 的放大图,fb_check.py --raw 直接拿后端吐的裸点阵对屏幕:

curl --noproxy '*' -H "Authorization: Bearer $TOK" -o /tmp/ic_599_40.bin \
     'https://cosmo.unisspace.com/api/terminal/bodies/599/icon?size=40'
# 列表三张卡的图标左上角 = 13,32 / 13,97 / 13,162(40x40);详情 64x64 = 15,140
/usr/bin/python3 terminal/tools/fb_check.py /tmp/f_list --raw 13,32,40,/tmp/ic_599_40.bin

图标底下压着面板底色和雷达刻度,所以 --raw 是「在每个候选底色里取误差最小的再取 max」, 命中就是 0;拿土星图去核对木星详情位会得到 ~57000,说明这把尺子有效。

补图与忙碌反馈(触屏设备的响应速度)

HTTP 请求是同步阻塞的,loop() 停在里面时 touch_poll() 一次都跑不到——手指抬起时那一次 手势直接丢掉,这就是"点了没反应"。下面这几层一起治(cosmo_terminal.ino + src/api.cpp):

  • 页面先出来:load_rockets() 拿到 JSON 就翻到列表,不等图;缺图只登记一个 s_art_wait 标记。详情页同理,先用内置线稿开画,64x64 补上再换掉。
  • 没有加载页:以前首次取数要整屏切到 SC_LOADING(SYNCING DATA 那个窗),请求 一回来又整屏换回列表,两次全屏刷新加一次"内容凭空闪一下"。现在 load_data() / load_rockets() 只在手里还没数据时把对应的(空)列表页摆出来,取数过程全部交给 header 那条线表达;已经有数据时原地刷,不把人正在看的详情页踢回列表。空列表页在 st.busy 期间直接留白(draw_list() / draw_rockets() 开头 if (st.busy) return;), 否则首次进终端会先闪一屏 NO ACTIVE ROCKETS,看着像后端出问题。
  • 一轮只补一张:art_pump() 挂在 run_tick() 后面,每次 loop() 最多下载一张, 补完一张就 g_dirty 重绘——两张之间有整轮 loop 处理触摸,页面点得动。 详情页欠的那张优先(s_art_code),用户正盯着它。*_store_sync(..., max_fetch) 的返回值是"还缺几张",<0 表示刚失败,别再追着重试。
  • 连接复用(api.cpp 的 Session / http_open):WiFiClientSecure 和 HTTPClient 合成一个常驻 s_sess,setReuse(true),同一 host 的请求都走这条 TLS。一张 40x40 立绘从 0.8~1.7s(每次重新握手)掉到 30~270ms。代价是这条 TLS 连接连同 mbedTLS 的收发缓冲一直占着内部堆,所以空闲满 API_IDLE_CLOSE_MS(5s)由 loop() 调 api_close() 把它释放掉,下次请求再握手约 800ms。Session 里 tls 必须声明在 http 前面——成员按声明逆序析构, ~HTTPClient() 会无条件 _client->stop(),反了就是释放后用悬垂指针。
  • 手势排队(touch_tick()):抬手时如果 api_in_request() 为真,就把这一次手势 存进一格缓存(TpGesture,记着落点和当时那一页),等网络空下来第一时间的采样补发。 补发前要复核「没过期(TP_QUEUE_TTL_MS=1200) + 页面没换 +(点按的话)落点那块热区 还在原位且还是同一格」,对不上就整下丢掉——丢一下只是这一下没反应,补错一下是用户 没想点的跳转。判据用 api_in_request() 而不是 NetBusy 的深度:配对轮询那条路径没标 忙碌态,按深度判断会在 HTTP 里再发起一次 HTTP。
  • 请求期间也采样:api_set_wait_cb(ui_pulse) 每 25ms 回调一次(早先是 150ms, 一次轻点只压几十 ms,整下从两次回调之间漏掉 = 「点了没反应」),ui_pulse() 里 touch_pump() 每 25ms 采一次触摸、整屏重绘仍按 PULSE_DRAW_MS 150ms 走 (一帧 QSPI 要 30~80ms,刷太勤会把下载挤死)。排队/派发的推进因此不依赖回到 loop()。
  • 触摸一律不画按下态:以前按下要描一圈热区框、点亮那颗键,抬手再清。真机上这套 东西有两个毛病——① 那圈框看起来就是"选中区多了个外框";② 它只在回到 loop() 时才 过期,请求一卡就是 1~2s 不熄,人以为没点着会再补一下,误触就是这么来的。现在 key_flash 只由物理按键那条路点(key_flash_on(),给 320x240 那两块无触摸的板子做 键位图例反馈),触摸全程不置。点着的反馈是页面自己变(切页 / 换卡 / 换标签), 慢的那部分由下面那条忙碌指示(header 那条线)表示。
  • 忙碌指示 = header 那条线自己在流动:UiState.busy 为真时,ui_draw() 在 HDR_LINE 上跑一颗 88x2 的青色彗星(C_CYAN 身 72px + C_WHITE 头 16px)。跑马区间固定 是 header 线正中那 160px(x0=(CONT_W-160)/2,640 宽就是 240~400),跟页面无关,各页 看到的位置一致,也不会撞上状态栏左边的电量格(约到 x=217)和右边的用户名(约从 x=485 起); 彗星从区间左沿外整段进、右沿外整段出,周期约 2.0s。刻意只比那条线本身粗 1px(HDR_LINE+1 仍 < TOP_Y,压不到内容区),读起来 是分隔线在流,不是线上盖了根进度条;配色也换回青色——金色已经被 header 按钮和列表 选中卡占用,再拿来做忙碌指示就分不清"哪个能点"。相位取 millis(),不数重绘次数 (节拍一抖动画就一顿一顿)。重绘节拍两处喂:请求阻塞期由 ui_pulse 按 PULSE_DRAW_MS 150ms 走,回到 loop() 之后由那个 busy ? 120 : 250 的动画节拍接手 ——请求已经下来、只剩补图的那段没人喂 ui_pulse,不补这一拍线就停住不动了。 补图期间 net_begin() 不再重画整屏(was 判据),省掉每帧一次全屏刷新。

真机实测(公网后端 cosmo.unisspace.com,RSSI ≈ -78):

场景 改前 改后
单张 40x40 立绘 834~1698ms 30~268ms(多数 95~125ms)
详情页 64x64 立绘 ~1.3s 143ms
冷缓存进火箭列表页(JSON + 9 张图全齐) ~11s 2.07s
补图期间的按键响应 最长 1.6s 中位 57ms
冷握手后的第一个请求 — ~800ms(TLS 握手)

仍然治不了的:单次 TLS 握手 / 弱网重连(0.8~4s,实测偶见一张图 4.2s)这期间 loop() 整个停在里面,屏幕完全冻结,只能靠 header 那条在动的线告诉用户"在等"。要彻底不冻, 要么把 HTTP 挪进独立的 FreeRTOS 任务(得处理共享状态和显示锁),要么后端出一个 批量立绘接口——两条都比现在这套大得多,动之前先确认。

配网

NVS 里没有 SSID,或者存着的 WiFi 连着连不上,终端都会自己开热点 COSMO-SETUP-XXXX:

  1. 手机/电脑连这个热点(开放网络,无密码);
  2. 浏览器打开 http://192.168.4.1(多数系统会自动弹出强制门户);
  3. 选 SSID、填密码和后端地址(预填当前生效的地址),保存后自动重启。

下拉框第一项是**「不改 WiFi,只保存后端地址」**:换开发机/换服务器时不用重输密码。 选回当前网络时密码留空 = 沿用 NVS 里存的那份;三项都没动就回「没有需要保存的改动」,不重启。 密码框故意做成明文 type=text,配网失败一多半是密码打错。

下拉列表下面还有一个「手动输入 SSID」,填了就覆盖下拉框的选择:新环境里路由器只开 5GHz (ESP32-S3 只收 2.4GHz)或 SSID 被隐藏时,一个热点都扫不到,没有这个输入框配网就是死路; 这时下拉里还会把存过的 SSID放回来,至少不用手打原名。页面底部也标了「仅支持 2.4GHz WiFi」。

进了配网页不是只能重输:配网页 KEY3 RETRY = 关掉热点、拿 NVS 里的旧凭据再连一次。 从设置页进来时按的是 keep_sta=true:热点照开,但现有 WiFi 不断,门户同时挂在设备的局域网 IP 上 (和串口 portal lan 一样),改错了还能从局域网那一侧 curl 上去看。 串口 wifi / api / reload / pair 改了配置也顺手关热点——热点只属于配网页, 这件事统一收在 set_screen() 里(离开 SC_PROVISION 就 portal_stop())。

坑:portal_stop() 里的 close() 只关监听,路由是留着下次用的。 所以 portal_start() 里的 s_server.begin() 不能跟「注册路由」待在同一个 if (!s_routed) 里——否则第二次及以后 开的热点会变成「手机连得上、页面死活打不开」,而这恰好是换环境时最常撞的那一幕 (第一次自动进配网 → 密码敲错 → 又自动回到配网页)。 别拿「板子自己 GET 自己」当证据。 试过加一条串口命令让板子当客户端去连 http://192.168.4.1/,永远回 connection refused,看着像门户死了;实际是 lwIP 走 自身地址那条路径不可靠。同一时刻同网段的电脑 curl 拿到的是 200 / 4.5s。 要验证门户在服务就用下面这个真的外部客户端:串口 portal lan。

凭据、后端地址、token 都存在 NVS 命名空间 cosmo。

无网是怎么判出来的(换了环境不用接串口也能进配网)

wifi_tick() 给每一轮连接两类预算,用完就往下走,不会停在 CONNECTING 死等:

现象 WiFi.status() 屏上原因 一轮预算
扫不到这个 SSID WL_NO_SSID_AVAIL SSID NOT IN RANGE 6s(WIFI_GIVEUP,已定性不用等满)
密码/AP 拒绝接入 WL_CONNECT_FAILED LOGIN REJECTED (PASSWORD) 6s
关联上了但拿不到 IP 其它 NO IP ADDRESS 20s(WIFI_TIMEOUT)
用着用着掉线 非连接/配网页且掉线满 10s — net_watch() 回连接页重来

同一份凭据连着失败 WIFI_TRIES=2 轮就自动开热点。SSID 不在范围时现场实测 13~26s: 第二轮一定被判成 SSID NOT IN RANGE 只花 6s,但开机第一轮有时要到断开事件都收齐了才定性, 会吃满 20s(屏上原因显示 NO IP ADDRESS)。连接页同时显示原因和 TRY 1/2 HOTSPOT IN 7s 倒计时,配网页第一行显示失败原因;首次开机没存凭据则显示 NO SAVED WIFI CREDENTIALS。

不想等倒计时也能手动进配网:CONNECTING 页 KEY3、PAIR 页 KEY2、ERROR 页 KEY2。 PAIR 页那条是给「WiFi 连上了但后端不通」留的出口——换了网段、api 还指着上一套环境的内网 地址时,终端只会停在配对页反复报拿不到码,没有这个键就只能拆机接串口;按下时串口同时打印 dev/api/user/token 四个值,方便一眼看出是哪个填错了。反过来在配网页上想改回重试旧凭据, 按 KEY3 RETRY。

实测(MAC E8:06:90:9B:58:7C,Hammond-2015 已不在现场):复位后热点 COSMO-SETUP-587C 自动出现,Mac 连上拿到 192.168.4.2/网关 192.168.4.1,GET http://192.168.4.1/ 返回 200、下拉里 20 个热点、后端地址预填正式服务。配网页首响应约 4s,慢在 handle_root() 里那次同步 WiFi.scanNetworks()——用手机扫码进门户时别急着关页面。

搬到新场地之后怎么查

S3 只有 2.4GHz 射频,「我手机能连上」不算判据(大概率连的是 5G)。三步,都在串口上:

~/esp-tools/pio_env/bin/python terminal/tools/serial_term.py
#   scan                      板子眼里的 2.4G 网络全列表;目标 SSID 不在里面就是射频层的事
#   cfg                       把 NVS 里存的 ssid/pass/api 抄下来——搬家前先抄一次
#   wifi <ssid> <pass>        换凭据(测别的网络前,先把上面抄的原样填回去就行)
#   api <url>                 换后端地址,见下一节
#   settings                  跳到设置页(WiFi / 后端地址 / 绑定用户 / 当前模式)
#   portal lan                开热点但不断现有 WiFi:门户同时挂在设备局域网 IP 上,
#                             同一网段的电脑 curl http://<设备IP>/ 就能看到配网页

「无网」有两层,屏幕上分得出来:

情况 屏上表现 出路
WiFi 连不上 连接页写原因 + TRY 1/2 HOTSPOT IN 7s,用完预算自动开热点 配网页 / KEY3
WiFi 连着、后端不通 状态栏从 NET:ONLINE RSSI:-56 变橙色 NET:ONLINE API FAIL;连着 API_FAIL_LIMIT=3 次取不到数据自动翻故障页 故障页 KEY2 SETUP

第二层是换环境最常见的一种:连上了新 WiFi,api 还指着上一套环境的地址。 旧数据会继续显示(比空白有用),但状态栏必须先变脸,否则旧数据看着像在线; 故障页上写着 DATA FETCH FAILED (HTTP -1) FROM ...,那里才有配网出口。

后端地址(换服务器 / 上 https 只看这一节)

地址存 NVS 键 api,只有 NVS 里还没有这个键时才用编译期的默认值:

// cosmo_terminal.ino:26
#define DEFAULT_API    "https://cosmo.unisspace.com/api"   // 正式服务

换正式地址有三种改法,前两种不用重新烧录:

改法 怎么做 适用
串口 api https://your-domain.com/api(写 NVS,立刻重新取数) 设备在手边,最快
配网页 串口 portal 或首次开机 → http://192.168.4.1 → 后端地址 没有串口线
重烧 改 cosmo_terminal.ino:26 的 DEFAULT_API 再编译烧录;只有 NVS 里没有 api 键的设备才会读到它 批量出厂

重烧固件不清 NVS:已经配过网/敲过 api 的设备,改了 DEFAULT_API 也还是旧地址。 要么串口 api <新地址> 覆盖一次,要么串口 reset 清空整个 NVS(连 WiFi 凭据和 token 一起清,设备会回到配网+配对流程),让它重新回落到 DEFAULT_API。 配网页现在预填当前生效的地址(以前预填 DEFAULT_API,重开配网页直接点保存 会把地址刷回编译期那个局域网 IP)。

http:// 和 https:// 都支持:src/api.cpp:tls_make() 按前缀分流,https:// 走 WiFiClientSecure(setHandshakeTimeout(10)),其余走裸 HTTPClient。

  • 不校验证书链(setInsecure()):只要链路加密。代价是理论上可被中间人, 收益是换 CA / 证书续期都不用重烧固件。要严格校验就把 setInsecure() 换成 setCACert(root_ca),代价是根证书编进固件、换 CA 必须重烧。
  • TLS 握手瞬时要多占几十 KB 堆(WiFiClientSecure 的 mbedTLS 上下文)。这块板子是 OPI PSRAM、堆本来就宽,编译后 RAM 仍在 16% 左右,但这条只在编译层面验证过, 上正式 https 服务后建议串口 stat 看一眼剩余堆。
  • 别把服务器配成 HTTP→HTTPS 的 301:HTTPClient 不跟跳转,终端会直接拿不到数据。 要么地址直接填 https://,要么让 /api/ 继续留在 80 上。

绑定与取数

开机 -> 连 WiFi -> POST /api/terminal/pair/code  拿 6 位码,屏幕上大字显示
                 -> GET  /api/terminal/pair/status  每 2s 轮询
网页端 设备绑定入口输入 6 位码 -> POST /api/devices/bind
终端   轮询到 status=bound -> 立刻把 access_token 写入 NVS
       之后 GET /api/terminal/follows (Bearer token) 显示关注天体列表 / 详情

防抢绑靠后端,不靠终端:码只能由已登录用户在 /api/devices/bind 消费,同码并发只有 1 个成功;码 10 分钟过期,剩余不足 10s 时终端主动换新码;换绑会轮换 token,解绑后旧 token 立即 401,终端自动回到配对页。

设备行就是吊销表:终端多久发现一次

get_terminal_context() 每次请求都回查 terminal_devices——status != bound、user_id 对不上、 或 JWT 里的 bnd(绑定时刻)与 bound_at 不是同一轮,一律 401。后端不需要吊销列表, 网页端解绑/换绑即刻生效,剩下的问题只是终端什么时候会去问一次:

停在哪个页面 谁去问 发现解绑的延迟
列表 / 详情 / 火箭列表 / 火箭详情 run_tick() 的 5 分钟数据轮询 ≤5 分钟
模式页 / 设置页 auth_check() 每 60s(IDLE_CHECK_MS,独立钟 g_next_idle) ≤60s,且进这两页先复核一次
故障页 15s 重试 ≤15s

首屏改成模式页之后,这两页一度一个请求都不发:网页端解绑之后终端还挂着上一轮缓存在 NVS 里的用户名、设置页照旧写 BOUND,last_seen_at 也不再更新,网页端看它像掉线了。 auth_check() 只取结论不跳页(成功就刷新用户名/信号/快照并把 api_fail 抹掉, 后端不通只让状态栏变脸),60s 也落在 app/api/device.py 的 ONLINE_WINDOW_SECONDS = 360 之内,顺带把"设备在线"的那颗心跳补齐。

清 token 的动作四个取数入口共用 token_revoked():抹掉 K_TOKEN 和 K_USER (否则配对页顶上会挂着个早就解绑的账号)再 start_pairing() 要新码。

OTA 升级

分区表 app3M_fat9M_16MB 本来就是双 app 分区(ota_0 在 0x10000、ota_1 在 0x310000,各 3MB),做 OTA 不用改分区表。升级 = 把新镜像写进「另一个」分区, 收满且校验通过之后才把启动指针切过去:

开机 / 每 6h(update_tick) / 串口 update
  -> GET /api/terminal/firmware/check?board=..&current=..   Bearer token
  -> has_update=true -> 翻到 UPDATE 页:FROM 1.2.0 TO 1.2.1 + 更新说明
  -> 按 KEY2 才开始下载(KEY3 = 先回模式页)——不静默升级
  -> 512 字节分块边下边算 sha256,进度条画在本页(回调节流 500ms)
  -> 长度相符 + sha256 相符 + Update.end() 通过
     -> 先写 NVS 确认标记 -> esp_ota_set_boot_partition() -> ESP.restart()
  -> 新固件画出首屏 -> ota_mark_ok() 清掉标记

版本判定按「平台启用的版本」而不是「最新版本」:后端取该板型启用中版本号最高的 那条作为目标版本,终端上报的版本和它不一致就 has_update=true。往上是升级,往下是 回滚——把 1.2.2 停用、留 1.2.1 启用,跑着 1.2.2 的终端下次检查就会提示 FROM 1.2.2 TO 1.2.1。同一板型建议只启用一个版本,启用多个时以版本号最高的为准。

失败一律不切分区:断链 / 30s 收不到字节 / 写 flash 失败 / 摘要不符,都 Update.abort() 并停在 UPDATE FAILED,原分区照旧启动,可以重按 KEY2 重试。镜像大小是后端登记的 size,跟 HTTP Content-Length 双向核对,只信一边都不行。

弱网卡在的多半是那条 30s 空转判定:1.5MB 镜像在 rssi -70 的办公网上实测只有 ~40KB/s, 中间还会长时间卡在 TCP 窗口上(服务端 Send-Q 堆 130KB 不动),信号再差一点就整包失败 DOWNLOAD STALLED。真机验 OTA 请挑信号好的位置,或让设备指向公网那台服务器下载。

发一版就两步

# 1. 先改版本号(终端比的是这个字符串,不改等于没发)
$EDITOR terminal/firmware/cosmo_terminal/src/version.h
# 2. 编译 + 上传 + 登记(管理员账号,也可用 COSMO_ADMIN_USER / COSMO_ADMIN_PASSWORD)
/usr/bin/python3 terminal/tools/release_firmware.py --notes "详情页中文换行修正"

脚本只认 version.h,板型默认 atk-dnesp32s3,其余看 --help (--server 默认 http://127.0.0.1:8000/api;--skip-build --file x.bin 传现成镜像)。 --board 的三块板和 BOARDS 里的编译期开关一一对应,长条屏那块是 --board waveshare-3p49(-DCOSMO_BOARD=3)。两个坑记在这儿: ① FQBN 按板型走 FQBN_OVERRIDES——3.49 那块只有 ESP32-S3 原生 USB 一个口,必须 USBMode=hwcdc,CDCOnBoot=cdc,用默认那条(CDCOnBoot=default)OTA 完 /dev/cu.usbmodem* 就没了;② 板型开关只能加在 compiler.cpp.extra_flags 上,不能用 build.extra_flags: --build-property 是整体覆盖,而 esp32 core 的 platform.txt 把 -DARDUINO_USB_MODE / -DARDUINO_USB_CDC_ON_BOOT 塞在 build.extra_flags 里,覆盖掉之后原生 USB 那几块的 Serial 会退回 UART0(Serial.isPlugged() 直接编译不过),FQBN 里的 CDCOnBoot 也一起失效。 上传走 POST /api/admin/firmware(multipart),后端流式落盘到 backend/upload/firmware/, 当场算 sha256、校验镜像首字节是 0xE9。不想跑脚本就在管理后台「平台管理 → 固件管理」 (/admin/firmware,仅管理员)上传现成的 .bin、停用或删除镜像;两条路都是同一个接口, 版本号都得先改 version.h 再编译,同 (board, version) 后端一律拒收。

四条铁律

规矩 违反的后果
先改 version.h 再编译发布 终端只比版本号,同版本永远「已是最新」;后端也按 (board, version) 唯一约束拒收
镜像文件名不许覆盖(firmware/<board>-<version>.bin 天然带版本) nginx 对 /upload/ 设了 expires 1y,同名覆盖之后已经拿过旧包的终端永远拿不到新内容
--board 必须等于终端的 BOARD_NAME 后端按上报的板型发包,不匹配直接 409,终端停在原版本。出货板 atk-dnesp32s3,样机 xingzhi-cube-1.54tft / waveshare-3p49
第一版仍然得用串口烧 OTA 代码本身也在固件里,早于 1.2.0 的镜像没这段,只能用 arduino-cli upload 打进去

下载地址 = api_base 剥掉尾巴上的 /api 再拼 /upload/(ota_asset_url() 只干这一件事): https://cosmo.unisspace.com/api + firmware/atk-dnesp32s3-1.2.1.bin → https://cosmo.unisspace.com/upload/firmware/atk-dnesp32s3-1.2.1.bin。 所以镜像必须和 API 同一个站点;生产上这段走 nginx,本地是 app/main.py 挂的 StaticFiles, http://192.168.2.40:8000/upload/firmware/... 也能直取。

防变砖:同一版本三次起不来就自己退回去

切分区前先把新版本号写进 NVS(ota_pend),新固件画出首屏才清;起不来就没机会清, 下次开机 ota_boot_guard()(setup 里最早、store_begin() 之后立刻)给它计数 ota_try, 同一版本连着 3 次没确认就 esp_ota_set_boot_partition() 指回原分区再重启。 标记指向别的版本时按陈旧标记清掉——串口强刷了别的固件就是这种情况。

为什么不直接用 Update.attempt():arduino 预编译的 sdkconfig 没开 CONFIG_APP_ROLLBACK_ENABLE,esp_ota_get_state_partition() 只会返回 ESP_ERR_NOT_FOUND,bootloader 那套 UNKNOWN/VALID 状态机在这儿不可用,只能自己记。

坑:otadata 指向 ota_1 之后再串口重刷,看着像「烧了没生效」

OTA 之后启动指针在 0x310000,而 arduino-cli upload 默认只烧 0x10000(ota_0), 设备起来还是 ota_1 里那份老固件。把 otadata 擦掉,bootloader 会回到 ota_0:

~/Library/Arduino15/packages/esp32/tools/esptool_py/5.3.1/esptool \
    --chip esp32s3 -p /dev/cu.usbserial-210 -b 460800 erase-region 0xe000 0x2000

0xe000 / 0x2000 就是分区表里 otadata 那一行。arduino-cli 没封装擦除命令, 直接调它自带的那份 esptool(5.3.1 这个目录名随 esp32 core 升级会变,先 ls 确认)。

怎么确认升级成功

  • 串口 ota:当前 FW_VERSION + 板型、NVS 里有没有待确认标记、后端给的版本/大小/拼好的 URL。
  • 串口 update 只做一次检查;update now 是检查完直接开下(联调用,跳过人工按 KEY2)。
  • 网页端「我的设备」的固件列:v1.2.2 + 副行板型。版本号和板型是固件在每个终端请求 的头里自报的(X-FW-Version / X-Board,见 src/api.cpp),后端在终端鉴权那一层顺手 落库,所以配对完第一次拉数据就有值,不用等到真查升级;列里是 -- 说明这台跑的固件还 没有上报能力。设备端设置页的 DEVICE 卡同时显示版本、芯片ID、板型和当前运行分区 (app0/app1,OTA 之后会翻到另一个)。

串口命令(115200)

help / wifi <ssid> [pass] / cfg / api <url> / pair / reload / mode [bodies|rockets|clear] / rockets / portal [lan] / scan / stat / keys / xlreg / key 0xNN / i2cscan / selftest / dump / swap 0|1 / bgr 0|1 / inv 0|1 / mir 0|1 / rot [0..3] / imu / flip [0|1|auto] / touch [on|off] 与 tap <x> <y>(仅触摸板) / batt(仅带电池的板) / ota / update [now] / reboot / reset

reload 刷的是当前模式那份数据;rockets 打印内存里的火箭快照(code/参数/art_ver/待发射数), stat 末尾会把 rocket_store_dump() 的缓存表一起打出来(哪个型号缓存了 40 还是 40+64)。

换环境最常用的三条:scan(板子能看到哪些 2.4G 网络)、cfg(NVS 里存的 ssid/pass/api)、 portal lan(配网门户在不在服务,顺带能在同网段直接改后端地址,不用先连热点)。

key 0x8000|0x4000|0x2000|0x1000 注入一次按键(上/下/确认/刷新),不接按键也能翻页; dump 把当前 320x240 帧缓冲按 RGB565 大端从串口回传(约 14s),用来在电脑上看屏幕内容。 同一时刻只留一个串口读者:dump 抓到一半时再来第二个程序读同一个口,两个程序会分掉 这 15 万字节,抓屏停在半截、stat 也像没了回显(实测停在 94204/153600 字节)。

线要插对,CDCOnBoot 决定控制台在哪个口:cdc = Serial 走 S3 原生 USB (USB-Serial/JTAG,/dev/cu.usbmodemXXXX);default(=Disabled)= Serial 落回 UART0/CH340(/dev/cu.usbserial-210),此时原生口只剩 ESP-ROM.../entry 0x... 这些 ROM 打印,stat 敲下去一个字都不回。反过来插错线也是同一个症状:口在,但不是控制台。 当前这台机器上实测的是 CH340 那根线,所以固件按 CDCOnBoot=default 编、命令走 /dev/cu.usbserial-210。tools/*.py 挑口时 usbserial* 优先,换线用 COSMO_PORT= 指定。

点屏调色:颜色整体反了用 inv,红蓝互换用 bgr,明暗/花屏用 swap,左右反了用 mir。 selftest 画四条色带自检,任意按键或命令退出。

长条屏装反了两条命令对着修,都存 NVS(rot 键),重启还在:

# 画面镜像 / 上下颠倒 -> 试 rot 1 2 3(改的是 disp_flush 的转置方向,UI 不用动)
# 点的位置和反应对不上 -> touch on 逐点读 [tp] raw=... -> px=...,照回报改 touch.cpp 的开关
~/esp-tools/pio_env/bin/python terminal/tools/serial_term.py

stat 里 panel : 640x172 rot=0 是长条屏的当前朝向;touch on 期间画面暂停刷新,touch off 恢复。

# 一个终端:既能敲串口命令,又会在 dump 后自动出图
~/esp-tools/pio_env/bin/python terminal/tools/serial_term.py      # -> /tmp/fb.raw
ffmpeg -f rawvideo -pixel_format rgb565be -video_size 320x240 -i /tmp/fb.raw \
       -frames:v 1 -vf scale=960:720:flags=neighbor screen.png

注意:dump 读的是当前帧缓冲,切页后要等画面刷完再发,否则拿到的是上一页。 dump 内部按 128 字节分块写、写满前等 Serial.availableForWrite(),一次性灌会被 CH340 冲花。

抓屏脚本把「发命令 + 等画面 + dump + 出图」串成一行,状态机保证 [FB] 标记不被日志冲掉:

# 板 3 记得给尺寸,否则按 320x240 解析出来的图是花的
COSMO_FB=640x172 ~/esp-tools/pio_env/bin/python terminal/tools/screen_shot.py /tmp/log \
    "|2|-"                          # 先发空命令, drain 启动日志
    "key 0x2000|0.8|-"              # KEY2 确认 -> 进详情页
    "dump|0.2|/tmp/fb_detail"       # 抓详情页 -> /tmp/fb_detail.png

抓回来的裸数据用 fb_check.py 核对,不用肉眼在 960x720 的放大图里找茬:

# 列表页三张卡到底是哪张图(拿卡底色 + 内置图标做加色混合反算,残差 0 = 就是这张,兜底图一眼看穿)
# 后台维护过的图标会报「不属于任何内置图标」,那是正常的,改用 --raw 核对,见「天体图标」一节
/usr/bin/python3 terminal/tools/fb_check.py /tmp/r_list

# 中文字模逐像素核对(103,176 = 字模左上角,b77d = 前景色,后面是这一行该显示的字)
/usr/bin/python3 terminal/tools/fb_check.py /tmp/r_info --glyph 103,176,b77d,木星,太阳系中最大的行星

它直接读 src/icons.cpp / src/font_cjk.cpp 的点阵反推期望像素,所以「中文画成了空心方框」 「图标走错兜底」这类问题会直接报出来;选中卡前景是 C_WHITE、未选中是 C_TEXT,别填错。

每帧约 14s(板 3 走 S3 原生 USB-CDC,220KB 只要 ~2s);要抓按键反色,就在发键后 250ms 内 dump。 两个坑:① 每个 dump 必须单独占一步("key 0x2000|1.5|-" 之后另起一步 "dump|1.5|/tmp/x"), 写在同一步里抓到的是按键前的画面;② [FB] 标记后面的残留字节必须丢掉再写文件, 留着会让整幅图右移 2px 且末行丢 2px(脚本里 d=bytes(buf); buf=bytearray() 就是干这个的)。

已知限制

  • 板 1 没有触摸:设计稿里所有「点击」交互都改成按键,见上面「输入方式」。
  • 长条屏的软件转置方向只能靠眼睛确认:dump 读的是转置前的逻辑帧缓冲,画面镜像 / 倒置 要配合 rot 与 flip 看实物。触摸映射本身已按真机校好(TP_SWAP_XY=1、TP_INVERT_Y=1)。
  • 长条屏详情页右栏只有 249px(图标格 148 + 信息列 224 之外剩下的全部):三个标签 LAUNCH n / STAGE / INFO 靠 6px 栏距才排得下,发射任务名和日期之间只留 8px 栏距。 信息栏一格 112px,装不下带空格的单位,所以是 22700kN、2000KM 这种连着写的写法。 中文简介 desc 在长条屏是 4 行 30 字(板 1 是 2 行 23 字)。
  • 中文只有 16x16 点阵,覆盖 GB2312 一级字 + 常用标点;生僻字/二级字会画成 □, 同行英文不受影响。事件标题里的中文现在能显示,但仍然只截到 ev[28](约 9 个汉字)。
  • 后端只在首次绑定时下发 token。NVS 被清空但数据库仍是绑定状态时,屏幕会提示先在网页端解绑再重新要码。
  • HTTP 请求是阻塞的,卡住的那段时间 loop() 收不到触摸。现在靠四件事兜:页面先画 (JSON 一到就显示,不等图)、一次只补一张图、连接复用 + 手势排队(抬手时网络还忙 就等空下来补发,见「补图与忙碌反馈」)、按下立刻有反馈 + header 忙碌线。 剩下唯一还会整屏冻住的是单次 TLS 握手 / 弱网重连(0.8~4s),期间只有 header 那条线在动。
  • 动态图标要在后台维护过才有,没维护的天体用的是内置那 ~20 张线稿,水星/天王星/冥王星这类只能吃兜底图。
  • 事件列表按后端返回顺序显示,包含已过期的(is_upcoming=false 也在列)。
  • 火箭详情页右栏只有两行高度,中文简介 desc 截到 23 字(第二行末尾留一个字位给 ..), 比后端登记的完整简介短;换行遵守"中文标点不许顶行"(disp_text_wrap() 会把标点和它 前一个字一起挪到下一行)。
  • 火箭立绘是立面图,只画一对助推器(登记 4 个也用一对表示),长细比按真实高/宽比 做了一次 1.72 * a^0.45 的压缩并夹在 3.0~8.5:完全不缩在 40px 上就是一根针。 所以"瘦火箭显得比实际瘦"是刻意的,同屏内的相对粗细仍然可比。
  • 未做:频道消息页、设计稿里的 STATUS 数据格(表面温度、自转周期等后端没有数据源)。
  • OTA 只验 sha256、不验签名(setInsecure()):能挡住「下到半截的坏镜像」,挡不住「后端被人打穿之后发什么终端都装」。要防后者得上 Secure Boot v2 + flash 加密,那是烧 eFuse、不可逆的事,量产前再定。