Timeframe TRMNL接入全解析:从MAC地址配对到屏幕渲染的完整API流程
Timeframe TRMNL接入全解析:从MAC地址配对到屏幕渲染的完整API流程
Timeframe(ha-addon)是一款运行在 Home Assistant 中的电子纸家庭仪表盘,可将日历、天气与智能家居状态渲染到 TRMNL、reTerminal 等墨水屏设备上。本文带你走一遍 TRMNL 接入的完整 API 流程:设备如何凭 MAC 地址注册、如何生成 6 位配对码完成配对,以及服务器端如何渲染屏幕截图并下发到墨水屏,帮助新手快速理解整套对接机制。
一、Timeframe 与 TRMNL 的连接原理
TRMNL 是一块支持 Wi-Fi 的墨水屏设备,它的固件逻辑非常朴素:周期性地向用户配置的 API 地址发 HTTP 请求,拿到一张 PNG 图片的 URL,下载后刷到屏幕上。Timeframe 正是利用这一机制,为 TRMNL 实现了三个 API 端点(见 config/routes.rb):
| 端点 | 方法 | 作用 |
|---|---|---|
/api/setup |
GET | 设备首次上线时注册 MAC 地址,生成配对码 |
/api/display |
GET | 轮询刷新:返回屏幕截图 URL 与刷新间隔 |
/api/log |
POST | 回传设备本地日志 |
三个端点全部实现在 engine/app/controllers/api/trmnl_controller.rb 中。整个链路可以概括为一句话:MAC 地址换配对码 → 配对码换 API Key → API Key 换屏幕图片。
二、第一步:/api/setup 与 MAC 地址配对
当 TRMNL 完成配网、尚未拿到凭证时,固件会调用 GET /api/setup,并在请求头中携带自己的身份信息:
| 请求头 | 含义 |
|---|---|
ID |
设备 MAC 地址,是 Timeframe 识别设备的唯一依据 |
Model |
硬件型号,如 og、x,用于映射到 TRMNL (OG) / TRMNL (X) |
服务端收到请求后(trmnl_controller.rb L22-L60)会做三件事:
- 按 MAC 查库:若该 MAC 已绑定设备,说明硬件被恢复出厂,会先调用
detach_hardware!解除旧绑定,避免把旧凭证偷偷发回给一台"空白"设备; - 创建待配对记录:在
PendingDevice表中生成一条注册记录,包含一个 16 字节的随机api_key和一个 6 位数字配对码(pairing code),模型映射逻辑见 engine/app/models/pending_device.rb; - 返回响应:
{
"status": 200,
"api_key": "…",
"friendly_id": "048217",
"message": "Enter this code at timeframe.app"
}
TRMNL 固件会把 api_key 存下来,并把 friendly_id(即配对码)显示在屏幕上——这就是你在墨水屏上看到的 6 位数字。
💡 配对码默认 60 分钟过期;设备等待配对期间会持续轮询
/api/display,服务端通过keep_alive!不断续期,保证你慢慢输入也不至于失效。
三、第二步:输入配对码,完成设备认领
打开 Timeframe 的 Web 界面(Home Assistant 插件端口 8099),进入引导流程(app/services/onboarding_flow.rb 定义了 设备 → 配对 → 布局 三步向导),在配对页填入屏幕上显示的 6 位数字:
提交后调用 PendingDevice#claim!(pending_device.rb L90-L103),系统会把待配对记录"转正"为正式的 Device 设备记录:拷贝真实的 MAC 地址与 api_key,并标记 confirmed_at。从此之后,这台 TRMNL 与 Web 面板上的设备卡片就绑定在一起了。
配对页面表单见 app/views/onboarding/_step_pairing.html.erb。
四、第三步:/api/display 轮询与签名截图 URL
配对完成后,TRMNL 固件开始周期性调用 GET /api/display,请求头携带 ID(MAC)与 ACCESS_TOKEN(即配对时发放的 api_key)。服务端在 authenticate_device! 中同时校验两者,任一不符直接返回 401。
认证通过后,响应 JSON 包含 TRMNL 固件认识的全部字段:
{
"status": 0,
"filename": "display-2026-10-24T02:00:00Z.png",
"image_url": "…/signed_screenshot/<sgid>",
"refresh_rate": 900,
"special_function": "sleep"
}
几个值得注意的细节:
- 签名 URL:
image_url由 Device#signed_screenshot_url 生成,内含 1 分钟过期的签名凭证,固件下载后SignedScreenshotsController(engine/app/controllers/signed_screenshots_controller.rb)才会返回 PNG; - filename 去重:文件名基于截图时间戳。若内容没有变化,服务端复用旧截图、返回相同 filename,TRMNL 固件识别为"已刷过"便不再翻转屏幕,既省电又减少闪烁;
- 未知 MAC 的兜底:如果 MAC 查无设备(记录被删或待配对过期),服务端会自动重建一条待配对记录并返回
{status: 202},让设备继续显示配对码等待认领,而不是陷入永久 401; - 后台刷新:每次轮询后,RefreshDeviceScreenshotJob 会按
refresh_rate - 60秒调度下一次截图预生成,并自动合并重复任务。
五、屏幕渲染流水线:从 HTML 到 1-bit 墨水屏图像
这是整套流程中最巧妙的部分。TRMNL 屏幕分辨率为 800×480,Timeframe 的做法是:先把仪表盘渲染成网页,再用无头浏览器截图,最后做灰度量化。
- 选模板渲染网页:TokenDevicesController 根据设备配置的模板(Timeline、3-Day、2-Day、1-Day)渲染对应的 ViewComponent,页面包含日历事件、天气、
sensor.timeframe_top_right_*等智能家居状态;
- 无头 Chromium 截图:ScreenshotService 以 480×800 竖屏视口启动 headless Chromium 截图,再旋转 90° 得到横屏效果,并内置了 20 秒硬超时防止浏览器卡死;
- 灰度化与抖动:截图转为灰度后,用 Floyd-Steinberg 抖动算法量化到 2 级(2-bit)灰阶——这正是墨水屏设备可显示的黑白灰层次;
- 缓存与内容指纹:每次生成会记录内容的 CRC 指纹(Device#refresh_screenshot!),内容不变则直接跳过重新截图。
六、遥测上报:电池、固件与信号强度
/api/display 的每个请求头都会被服务端解析为设备遥测(update_device_from_headers):
| 请求头 | 用途 |
|---|---|
FW-Version / FW-Commit |
记录固件版本 |
Battery-Voltage |
按电压线性估算电量(TRMNL 类设备使用 3.0–4.2V 区间) |
Percent-Charged |
TRMNL-X 的电量计直读数,优先于电压估算 |
Battery-Charging / USB-Connected |
判断充电状态 |
RSSI |
Wi-Fi 信号强度 |
电量低于 25% 会触发低电量横幅,低于 10% 则整屏替换为充电提醒。设备还可以把本地日志通过 POST /api/log 回传(单次最多 50 条),落库为可审计的 device.log 事件。
七、刷新节奏:白天 15 分钟,夜间约 1 小时
为兼顾时效与续航,refresh_rate 由 Device#refresh_rate 按设备所在时区动态计算:
- 白天:固定 900 秒(15 分钟);
- 夜间 23:00–05:00:拉长到约 3540 秒(≈59 分钟),并在临近清晨时自动收敛,保证设备 5 点左右恢复正常节奏。
八、关键文件速查
| 模块 | 路径 |
|---|---|
| TRMNL API 控制器 | engine/app/controllers/api/trmnl_controller.rb |
| API 路由定义 | config/routes.rb |
| 待配对设备模型 | engine/app/models/pending_device.rb |
| 设备模型与截图逻辑 | engine/app/models/device.rb |
| 截图服务(浏览器+灰度处理) | engine/app/lib/screenshot_service.rb |
| 签名截图下发 | engine/app/controllers/signed_screenshots_controller.rb |
| 设备渲染控制器 | engine/app/controllers/token_devices_controller.rb |
| 引导配对流程 | app/services/onboarding_flow.rb |
| API 行为测试 | engine/test/controllers/api/trmnl_controller_test.rb |
小结
Timeframe 接入 TRMNL 的精髓在于一条清晰的凭证链:MAC 地址 → 配对码 → API Key → 签名图片 URL,再配合"内容指纹不变则不重刷屏"的优化,让一块普通的 Wi-Fi 墨水屏变成了会自己更新的家庭日历仪表盘。理解这条链路后,无论是排查配对失败,还是想为自研墨水屏设备实现类似对接,都能找到清晰的参照。


