Timeframe 设备配对指南:TRMNL、reTerminal、Boox Mira 墨水屏 3 步接入全流程

原创2026-10-24 23:18:58452 阅读

Timeframe 设备配对指南:TRMNL、reTerminal、Boox Mira 墨水屏 3 步接入全流程

Timeframe 是运行在 Home Assistant 上的开源电子墨水屏(e-paper)日历、天气与智能家居家庭仪表盘,以官方 Add-on 形式提供。本指南带你走通 TRMNL、reTerminal、Boox Mira 等墨水屏设备的完整配对流程:开机获取配对码、在仪表盘输入 6 位数字码、选择显示布局,全程约 5 分钟。

🖥️ Timeframe 支持哪些墨水屏设备?

Timeframe 内置 8 款支持设备的完整定义(屏幕尺寸、可用布局、刷新方式),源码见 engine/app/models/device.rb 中的 SUPPORTED_MODELS:

设备 屏幕 更新方式 可选布局
Visionect Place & Play 13" 13" 竖屏 10 分钟级 固定
Boox Mira Pro 25.3" 25.3" 彩色 WebSocket 实时 固定
Boox Mira 13.3" 13.3" WebSocket 实时 固定
TRMNL (OG) 7.5" 黑白 截图轮询 Timeline / 3-Day / 2-Day / 1-Day
TRMNL (X) 10.3" 黑白 截图轮询 竖屏 / 横屏 / 2-Day 横屏
reTerminal E1001 7.5" 7.5" 黑白 截图轮询 Timeline / 3-Day / 2-Day / 1-Day
reTerminal Sticky 3.97" 3.97" 截图轮询 1-Day 竖屏
reTerminal E1003 10.3" 10.3" 灰度 截图轮询 竖屏 / 横屏 / 2-Day 横屏

💡 其中 Boox Mira 系列通过 WebSocket 实时刷新;其余设备采用截图轮询,白天约 15 分钟刷新一次,夜间(23:00–05:00)自动降为约每小时一次以省电。

⚡ 配对流程总览:3 步完成接入

Timeframe 为 Home Assistant 插件模式设计了一个引导向导(app/services/onboarding_flow.rb),步骤自动按设备类型裁剪:

  1. Device(创建设备):给显示设备起名(如 "Kitchen Display"),并从下拉框选择你手中的型号
  2. Pair(配对):输入设备屏幕上显示的 6 位配对码(Visionect 例外,它按序列号自动确认,无需配对码)
  3. Layout(布局):仅当设备提供多种布局时出现,可预览每种版式后点选

TRMNL 墨水屏设备配对成功后的 Timeframe 日程显示界面

配对成功后,设备就会像上图这样显示你的日历日程、天气与智能家居状态。

📦 第一步:在 Home Assistant 中安装 Timeframe 插件

  1. 打开 Home Assistant,进入 Settings → Add-ons → Add-on Store
  2. 点击右上角三点菜单(⋮)→ Repositories,添加本项目的仓库地址(详见仓库 README.md 的 Installation 一节)
  3. 在商店中找到 Timeframe,点击 Install → Start
  4. 浏览器访问 http://homeassistant.local:8099 打开 Timeframe 仪表盘

也可以脱离 HA 用 Docker 独立运行:仓库自带的 docker-compose.yml 只需填入 TIMEFRAME_HOME_ASSISTANT_URL 和 TIMEFRAME_HOME_ASSISTANT_TOKEN(HA 长期访问令牌)即可。

🔑 第二步:开机设备,获取 6 位配对码

不同硬件获取配对码的方式略有不同,但核心都是:设备联网后向 Timeframe 发起注册,Timeframe 回传一个 6 位数字配对码显示在屏幕上。

TRMNL / reTerminal 系列(固件配对)

在设备自带的设置向导里完成 Wi‑Fi 配置,并把 API Server 地址指向你的 Timeframe 仪表盘地址(如 http://homeassistant.local:8099)。设备固件随后请求 GET /api/setup(路由定义见 config/routes.rb),固件以 MAC 地址注册,屏幕即显示配对码。该接口由 engine/app/controllers/api/trmnl_controller.rb 实现,会自动识别固件上报的型号(如 trmnl_og、reterminal_e1003)。

Boox Mira 系列(浏览器配对)

Mira 是彩色墨水屏平板,无需改固件:直接在 Boox 设备的浏览器中访问仪表盘地址后的 /pair 路径(如 http://homeassistant.local:8099/pair),页面会大字显示配对码,并每 5 秒自动刷新,见 engine/app/views/setup/index.html.erb。

Visionect Place & Play 13"

免配对码:设备通过私有 TCP 协议(engine/app/lib/visionect_protocol/)按序列号连接,Timeframe 会自动确认并建立连接。

✍️ 第三步:在仪表盘输入配对码,完成配对

回到 Timeframe 仪表盘,你有两个入口:

点击 Add Device / Pair 后,PendingDevice 记录会被"认领":设备的真实 MAC 地址、API Key 与型号写入正式设备记录,屏幕随即开始显示内容(配对逻辑见 engine/app/models/pending_device.rb)。

⏳ 配对码有效期为 60 分钟。设备等待配对期间会持续轮询服务端来"续命",所以只要屏幕还亮着代码就有效;若超时过期,重启设备或重进 /pair 页面即可刷新出新码。

🎨 配对之后:为屏幕选择最合适的布局

多布局设备(TRMNL、reTerminal 7"/10.3"、TRMNL X)在向导最后一步可并排预览各种版式,每种布局还附带一句风格说明,例如:

  • Timeline(trmnl):信息量最全的 14 天滚动日程,适合"灵活、详尽的时间表"
  • 2-Day(two_day / two_day_landscape):今天 + 明天,密集日程也收得下
  • 1-Day(one_day / sticky_one_day):极简单日视图,适合 reTerminal Sticky 这类小屏

TRMNL 设备上的 Timeframe 2-Day 密集日程布局效果

以上图为 2-Day 布局在事件较多时的紧凑排布效果。布局随时可在设备设置页的 Layout 区域切换,切换即时保存并刷新预览(设置页逻辑见 engine/app/views/devices/settings.html.erb)。

reTerminal E1003 横屏模式下的 Timeframe 墨水屏显示布局

reTerminal E1003 横屏安装时可切到 Landscape 版式,时间轴横向铺满大屏。

reTerminal Sticky 小屏上的 Timeframe 1-Day 单日布局

小屏设备推荐使用 1-Day 布局,日程行自动缩放以适配窄屏。

🔁 换屏或恢复出厂后如何重新配对

如果更换了屏幕或给设备做了工厂重置,原账号下会留一个"待配对"状态,无需从头再来:

  1. 打开该设备的设置页,底部有 Pair or replace display 区块(表单见 engine/app/views/devices/_reconnect_form.html.erb)
  2. 让新屏幕重新走一遍上面的取码流程:TRMNL / reTerminal E1001 把 API Server 指向仪表盘地址;其他设备访问 /pair
  3. 把新配对码填入并点击 Pair display

重新配对会保留该设备的全部设置(名称、布局、日历选择)并迁移到新屏幕上。若重置后的硬件被配对到别的账号,旧记录会被自动清理,避免"僵尸设备"卡片残留。

❓ 常见配对问题排查

现象 原因与解决
提示 "Invalid or expired pairing code" 配对码已过期或输错。回到 /pair 或设备屏幕刷新出新码(6 位数字,注意 0 和 O)
输入框填不满、按钮点不了 配对码必须是 6 位纯数字,页面会做实时格式校验
设备一直停在配对码画面 确认设备与 Timeframe 在同一网络、API 地址端口正确(HA 插件默认 8099)
想先试试效果再接日历 在设备设置页开启 Demo mode,屏幕会显示演示数据
修改设置后屏幕没变 截图类设备等待下一轮刷新(白天 15 分钟),按设备上的绿色按钮可立即刷新

✅ 小结

Timeframe 的配对设计非常"无感":设备端只负责显示一个 6 位码,仪表盘端只负责输入这个码,型号识别、凭据绑定、布局推荐全部自动完成。从 HA 商店安装 Add-on 到屏幕亮起你的第一份日程,通常不超过 5 分钟——剩下的时间,就交给你的墨水屏家庭仪表盘吧。

登录后查看全文
ha-addon