Timeframe实时更新架构:如何用WebSocket+ActionCable让Boox Mira实现2秒级仪表盘刷新
Timeframe实时更新架构:如何用WebSocket+ActionCable让Boox Mira实现2秒级仪表盘刷新
Timeframe 是一款运行在 Home Assistant 上的墨水屏日历、天气与智能家居家庭仪表盘。对于 Boox Mira 系列墨水屏设备,它基于 WebSocket + ActionCable 构建了一套实时推送链路:后端每 2 秒拉取一次 Home Assistant 状态,内容变化时即时推送到设备端,让 25.3 英寸的 Boox Mira Pro 像一块"活"的家庭中枢,而不是每 15 分钟才动一次的静态屏。
两种更新模式:为什么 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 连接挂到该设备的广播流上。
生产环境 config/cable.yml 使用 PostgreSQL 适配器——利用 HA 附加插件自带的数据库做广播中转,无需额外部署 Redis 等消息中间件,单机 Docker 容器即可跑通整条链路,部署成本极低。
收到刷新消息后:DOM morph 让墨水屏"局部更新、不闪烁"
设备端的页面(如 mira_component.html.erb)通过 ActionCable.createConsumer() 建立订阅,收到 refresh 消息后重新拉取最新 HTML,但不是粗暴地替换整个页面:
布局模板 device.html.erb 内置了一个自研的 tfMorph 函数,逐节点比对新旧 DOM,只修补真正变化的文字和属性。它刻意做到三点:
- 不碰
<script>节点——WebSocket 订阅和时钟计时器始终存活,刷新不中断; - 保留
data-morph-keep标记的节点——由 JS 驱动的大时钟、日期、整点闪烁提示不会被动; - 逐节点原地替换——让 Boox 墨水屏走局部刷新(partial refresh),画面不闪、几乎无残影。
另外,消息里还带着 deploy_time 版本号:一旦服务端发布了新版本,设备端检测到版本不一致就整页 reload 一次,保证发版后每台设备恰好完整刷新一次。网络中断时也不会白屏——拉取失败会保留最后的好画面,并按 5 秒起步、最长 30 秒的退避策略持续重试。
进阶了解: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 既做到了"秒级响应",又守住了墨水屏的功耗底线——这套思路对任何想做墨水屏实时仪表盘的团队都很有参考价值。


