Timeframe TRMNL接入全解析:从MAC地址配对到屏幕渲染的完整API流程

原创2026-10-24 20:02:08378 阅读

Timeframe TRMNL接入全解析:从MAC地址配对到屏幕渲染的完整API流程

Timeframe(ha-addon)是一款运行在 Home Assistant 中的电子纸家庭仪表盘,可将日历、天气与智能家居状态渲染到 TRMNL、reTerminal 等墨水屏设备上。本文带你走一遍 TRMNL 接入的完整 API 流程:设备如何凭 MAC 地址注册、如何生成 6 位配对码完成配对,以及服务器端如何渲染屏幕截图并下发到墨水屏,帮助新手快速理解整套对接机制。

Timeframe TRMNL电子纸屏幕渲染示例:展示天气、日程事件与智能家居状态的家庭仪表盘

一、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)会做三件事:

  1. 按 MAC 查库:若该 MAC 已绑定设备,说明硬件被恢复出厂,会先调用 detach_hardware! 解除旧绑定,避免把旧凭证偷偷发回给一台"空白"设备;
  2. 创建待配对记录:在 PendingDevice 表中生成一条注册记录,包含一个 16 字节的随机 api_key 和一个 6 位数字配对码(pairing code),模型映射逻辑见 engine/app/models/pending_device.rb;
  3. 返回响应:
{
  "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 位数字:

Timeframe TRMNL 配对向导与屏幕渲染组件的日历布局示意

提交后调用 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 的做法是:先把仪表盘渲染成网页,再用无头浏览器截图,最后做灰度量化。

  1. 选模板渲染网页:TokenDevicesController 根据设备配置的模板(Timeline、3-Day、2-Day、1-Day)渲染对应的 ViewComponent,页面包含日历事件、天气、sensor.timeframe_top_right_* 等智能家居状态;

Timeframe TRMNL 两日模板渲染效果:密集日程事件的双栏日历布局

  1. 无头 Chromium 截图:ScreenshotService 以 480×800 竖屏视口启动 headless Chromium 截图,再旋转 90° 得到横屏效果,并内置了 20 秒硬超时防止浏览器卡死;
  2. 灰度化与抖动:截图转为灰度后,用 Floyd-Steinberg 抖动算法量化到 2 级(2-bit)灰阶——这正是墨水屏设备可显示的黑白灰层次;
  3. 缓存与内容指纹:每次生成会记录内容的 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 墨水屏变成了会自己更新的家庭日历仪表盘。理解这条链路后,无论是排查配对失败,还是想为自研墨水屏设备实现类似对接,都能找到清晰的参照。

登录后查看全文
ha-addon