66 KiB
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。
输入方式:只有按键,没有触摸
设计稿里的底部按钮不能点——这块屏不带触摸层。两条证据:
- 屏模块的 8 pin 插座只有
PWR GND / CS 3V3 / WR SCK / RST SDA,没有 TOUCH_PEN/TOUCH_CS; - 串口
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_H24px 高(文字上下各留 3px)、 热区HDR_HIT_H31px (整条 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_tRGB565 值。 忘了转会整屏颜色字节互换,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_MS150ms 走 (一帧 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_MS150ms 走,回到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:
- 手机/电脑连这个热点(开放网络,无密码);
- 浏览器打开
http://192.168.4.1(多数系统会自动弹出强制门户); - 选 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=..¤t=.. 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、不可逆的事,量产前再定。