大飞的技术博客

·约 4 分钟·

设备算,浏览器看:一块墨水屏设备的网页伴侣

PocketOracle 是一块靠电池生活的墨水屏设备,深睡是它的静止态——但它偏偏有一个功能与此对立:网页服务。手机连上设备热点 PO-xxxx,浏览器打开 192.168.4.1/app,就能用完整的占卜引擎:求签、每日一言、奇门九宫、六爻装卦、六十四卦全文、黄历、八字,外加配网和 OTA。这是「不插网的 Web 服务」系列的第一篇,讲这个「网页伴侣」的会话模型和 API 设计。

约束先于设计

这个功能长成现在的样子,是被三条物理约束逼出来的:

电池。WiFi 常开是百毫安级功耗,和「深睡待机 12h 唤一次」的设计直接对立。所以它不能是常驻服务器,必须是一次有边界的会话:用户主动进入(设置 → 对时,或菜单「网络」卡片),5 分钟没有任何 HTTP 请求就自动关 radio 回深睡。每个 handler 入口都调 net_touch() 打点,服务循环轮询 net_idle_ms(),任何按键也能立刻退出。

网络方向。手机连的是设备热点,热点里没有外网——所以一切计算必须在设备端完成,网页只是个遥控器。反过来,AI 解卦的 GLM 请求只能由设备发起:API key 存在设备 NVS 里,永不下发到手机。方向决定了信任边界。

Flash。设备只有 4MB flash,不可能塞下一个正经的前端框架。网页是单文件 HTML,这个话题够写一篇,留给下一篇。

「引擎同源」:网页和屏幕永远一致

网页伴侣最核心的设计决策其实是一句废话级别的原则:设备屏幕上显示的结果和网页上显示的结果,必须来自同一份代码。

占卜引擎(签文池、奇门转盘、梅花起卦、六爻装卦、农历干支)是一层纯 C 逻辑,不碰 SPI、不碰屏幕。设备 UI 调它,web API 也调它——同一个 /api/draw,网页上出的签和墨水屏上的签,出自同一次随机数、同一份语料。不存在「网页版逻辑和固件版逻辑对不上」这类事故的生存空间。

这个原则还催生了一个可爱的功能:屏幕推送。网页上求签,/api/draw 的结果会同步到墨水屏上——实现是典型的 core/ui 解耦:web.c 只往一个 {签组, 签号} 信箱里塞消息(web_push_take,消费即清),不 include 任何 UI 头文件;设备侧的服务循环每秒轮询信箱,取到就用共享的紧凑版式上屏,并且 ui_hist_push 记入设备的历史记录。网页求的签,设备也认账——两边共享的不只是计算,还有账本。

一个通配符 handler 扛下全部 API

API 面最终长到了十几个端点:

路径干什么
/api/status电量/充电/RTC/倒数日
/api/sets、/api/draw、/api/daily签组目录、随机求签、每日一签
/api/qimen、/api/meihua、/api/liuyao奇门、梅花、六爻装卦
/api/hex六十四卦经传全文
/api/quote、/api/almanac、/api/bazi每日一言、黄历、四柱
/api/history求签历史
/api/ask触发 AI 解卦(POST)+ 轮询答案(GET)

但 esp_httpd 默认只给 CONFIG_HTTPD_MAX_URI_HANDLERS = 8 个 handler 槽位。逐个注册,第二个端点加进去就得改 menuconfig。解法是换掉匹配函数:

hc.uri_match_fn = httpd_uri_match_wildcard;
httpd_register_uri_handler(server,
    &(httpd_uri_t){ .uri = "/api/*", .method = HTTP_ANY, .handler = h_api });

// h_api 按前缀 + 方法分发:
if (!strncmp(u, "/api/draw", 9)  && req->method == HTTP_GET)  return h_draw(req);
if (!strncmp(u, "/api/ask", 8)   && req->method == HTTP_POST) return h_ask(req);

一个通配符注册,分发表就是一个 if 链。以后加端点是加一行,不是加一次「槽位还剩几个」的心算。

JSON 输出全部手写 snprintf 拼装——值域受控(签号、卦序、干支都是枚举),不需要 JSON 库;唯一出现用户自由文本的字段(所问何事)过一遍转义。缓冲区全是 static:httpd 就一个工作线程,不存在并发写。

会话的两条世界线

httpd 实际会起两种会话,共用同一套 handler 和同一个空闲计时:

  1. 配网 AP 会话:手机连热点,地址恒为 192.168.4.1。表单提交 WiFi 凭据、AI key、倒数日、生日——设备没有键盘,这个门户就是它的输入法,所有文字输入都从这张网页表单走。
  2. STA 局域网会话:对时成功后设备连上家里的 WiFi,net_sta_ip 拿到局域网地址直接显示在「服务中」屏幕上——手机切回家里的网,不用连热点也能用,体验好一截。

两种模式都跑在 APSTA 下,一个 httpd 实例服务两边。5 分钟空闲从最后一次 net_touch() 起算,不区分会话。

小结

这个功能的架构可以压成三句话:会话有界(5 分钟空闲关 radio,电池优先),引擎同源(网页和屏幕共享同一份 C 逻辑和同一本历史账),API 面走通配符(一个 handler,if 链分发)。下一篇讲它的反面——手机端那一小块:热点里没有 CDN,CSS 从哪来。