Timeframe 设备配对指南:TRMNL、reTerminal、Boox Mira 墨水屏 3 步接入全流程
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),步骤自动按设备类型裁剪:
- Device(创建设备):给显示设备起名(如 "Kitchen Display"),并从下拉框选择你手中的型号
- Pair(配对):输入设备屏幕上显示的 6 位配对码(Visionect 例外,它按序列号自动确认,无需配对码)
- Layout(布局):仅当设备提供多种布局时出现,可预览每种版式后点选
配对成功后,设备就会像上图这样显示你的日历日程、天气与智能家居状态。
📦 第一步:在 Home Assistant 中安装 Timeframe 插件
- 打开 Home Assistant,进入 Settings → Add-ons → Add-on Store
- 点击右上角三点菜单(⋮)→ Repositories,添加本项目的仓库地址(详见仓库 README.md 的 Installation 一节)
- 在商店中找到 Timeframe,点击 Install → Start
- 浏览器访问
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 仪表盘,你有两个入口:
- 新手向导:首次打开会自动进入 app/views/onboarding/show.html.erb 的向导,按提示填名称 → 选型号 → 填配对码
- Add Device 卡片:后续新增设备时,在仪表盘直接打开"Add Device"表单,选择型号后会自动出现 Pairing Code 输入框(仅接受 6 位数字,输入合法后按钮才可点击),见 engine/app/views/dashboard/_add_device_forms.html.erb
点击 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 这类小屏
以上图为 2-Day 布局在事件较多时的紧凑排布效果。布局随时可在设备设置页的 Layout 区域切换,切换即时保存并刷新预览(设置页逻辑见 engine/app/views/devices/settings.html.erb)。
reTerminal E1003 横屏安装时可切到 Landscape 版式,时间轴横向铺满大屏。
小屏设备推荐使用 1-Day 布局,日程行自动缩放以适配窄屏。
🔁 换屏或恢复出厂后如何重新配对
如果更换了屏幕或给设备做了工厂重置,原账号下会留一个"待配对"状态,无需从头再来:
- 打开该设备的设置页,底部有 Pair or replace display 区块(表单见 engine/app/views/devices/_reconnect_form.html.erb)
- 让新屏幕重新走一遍上面的取码流程:TRMNL / reTerminal E1001 把 API Server 指向仪表盘地址;其他设备访问
/pair - 把新配对码填入并点击 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 分钟——剩下的时间,就交给你的墨水屏家庭仪表盘吧。



