Timeframe实时更新架构:如何用WebSocket+ActionCable让Boox Mira实现2秒级仪表盘刷新

原创2026-10-24 12:40:031,962 阅读

Timeframe实时更新架构:如何用WebSocket+ActionCable让Boox Mira实现2秒级仪表盘刷新

Timeframe 是一款运行在 Home Assistant 上的墨水屏日历、天气与智能家居家庭仪表盘。对于 Boox Mira 系列墨水屏设备,它基于 WebSocket + ActionCable 构建了一套实时推送链路:后端每 2 秒拉取一次 Home Assistant 状态,内容变化时即时推送到设备端,让 25.3 英寸的 Boox Mira Pro 像一块"活"的家庭中枢,而不是每 15 分钟才动一次的静态屏。

Timeframe墨水屏仪表盘实时刷新效果:日历事件、天气与智能家居状态一览

两种更新模式:为什么 Boox Mira 走 WebSocket?

Timeframe 支持的硬件分成两类(见 device.rb 中的 SUPPORTED_MODELS 定义):

模式 代表设备 更新方式
截图轮询 TRMNL、reTerminal 等 服务端定时截图,设备定期拉取(默认 15 分钟)
实时推送 Boox Mira / Mira Pro(realtime: true) WebSocket 长连接 + 服务端主动推送

墨水屏的刷新很"贵"——每次全刷都会闪烁并消耗电量,所以 Timeframe 的实时架构核心矛盾是:既要秒级响应,又不能让屏幕乱闪。整套设计都围绕这两点展开。

实时推送三步走:从 HA 状态到墨水屏画面

第一步:每 2 秒轮询 Home Assistant 状态

调度逻辑非常直白,入口在 config/scheduler.rb:

# Fetch states every 2 seconds for near-real-time updates
scheduler.every "2s" do
  HomeAssistantApi.new.fetch_states
  DeviceBroadcaster.broadcast_all_mira_devices
end

除了 2 秒级的状态轮询,还有分层节奏:日历每分钟同步一次、天气每分钟刷新、配置每 5 分钟更新。这种"高频小数据 + 低频大数据"的组合,是 2 秒级体验的来源。

第二步:MD5 去重,只广播"真的变了"的内容

DeviceBroadcaster 是广播的守门员(device_broadcaster.rb)。每次它都会把设备当前要渲染的完整数据序列化成 JSON,做 MD5 哈希,与上次结果比对:

  • 哈希相同 → 什么都不做,屏幕保持原样;
  • 哈希不同 → 通过 DeviceChannel 向该设备的所有 WebSocket 连接广播一条 refresh 消息。

这里有个精妙细节:去重哈希故意排除了 current_time 字段。因为时钟是设备端 JS 每秒本地渲染的,如果每分钟把"时间变了"当成内容变更广播,屏幕就会每分钟全屏闪一次——这在墨水屏上是灾难。

第三步:ActionCable 通道,一屏一条长连接

推送通道定义在 device_channel.rb:设备端订阅时携带 device_id,服务端校验权限后执行 stream_for device,把这条 WebSocket 连接挂到该设备的广播流上。

Timeframe两日视图实时刷新高密度事件日历,日程变更秒级同步

生产环境 config/cable.yml 使用 PostgreSQL 适配器——利用 HA 附加插件自带的数据库做广播中转,无需额外部署 Redis 等消息中间件,单机 Docker 容器即可跑通整条链路,部署成本极低。

收到刷新消息后:DOM morph 让墨水屏"局部更新、不闪烁"

设备端的页面(如 mira_component.html.erb)通过 ActionCable.createConsumer() 建立订阅,收到 refresh 消息后重新拉取最新 HTML,但不是粗暴地替换整个页面:

布局模板 device.html.erb 内置了一个自研的 tfMorph 函数,逐节点比对新旧 DOM,只修补真正变化的文字和属性。它刻意做到三点:

  1. 不碰 <script> 节点——WebSocket 订阅和时钟计时器始终存活,刷新不中断;
  2. 保留 data-morph-keep 标记的节点——由 JS 驱动的大时钟、日期、整点闪烁提示不会被动;
  3. 逐节点原地替换——让 Boox 墨水屏走局部刷新(partial refresh),画面不闪、几乎无残影。

另外,消息里还带着 deploy_time 版本号:一旦服务端发布了新版本,设备端检测到版本不一致就整页 reload 一次,保证发版后每台设备恰好完整刷新一次。网络中断时也不会白屏——拉取失败会保留最后的好画面,并按 5 秒起步、最长 30 秒的退避策略持续重试。

TRMNL风格Timeframe仪表盘演示:状态栏、天气与时间轴事件实时呈现

进阶了解:Visionect 设备的另一条实时通路

除了 WebSocket,Timeframe 还为 Visionect Place & Play 13 复刻了厂商私有协议。server.rb 实现了一个监听 11114 端口的 TCP 服务,能解码 20 字节小端包头 + CRC32 校验的设备报文,并用 双缓冲区(旧帧 + 新帧)投递图像,让 EPD 芯片正确计算刷新波形。项目还附带了 proxy.rb 透明代理,用于抓包逆向——这条私有协议链路是"2 秒级"之外更硬核的另一面。

核心文件速查

模块 路径 职责
2 秒调度器 config/scheduler.rb 轮询 HA 状态并触发广播
去重广播器 engine/app/lib/device_broadcaster.rb MD5 对比,变化才推送
WebSocket 通道 engine/app/channels/device_channel.rb 按设备订阅/广播
Cable 配置 config/cable.yml PostgreSQL 适配器
Mira 客户端 engine/app/components/devices/mira_component.html.erb 订阅、morph、断线重试
DOM 补丁 engine/app/views/layouts/device.html.erb tfMorph 局部无闪烁更新

总结

Timeframe 的 2 秒级实时架构并不复杂,但每个环节都在为墨水屏"省刷新":分层轮询控制数据源频率,MD5 去重拦截无效推送,PostgreSQL 适配器零成本落地 WebSocket,DOM morph 把全屏闪烁变成局部更新。四段组合下来,Boox Mira 既做到了"秒级响应",又守住了墨水屏的功耗底线——这套思路对任何想做墨水屏实时仪表盘的团队都很有参考价值。

登录后查看全文
ha-addon