Skip to content

自适应灯光:使用与注意 ​

HomeKit 自适应灯光会按一天中的时间曲线自动调节灯泡色温(偏暖 / 偏冷)。Olink 支持在已映射色温的灯具上启用该能力;控制台还可查看运行中的自适应任务与调节日志。

使用说明 ​

前置条件 ​

  1. 灯已接到 HomeKit(桥接器配件即可)。
  2. 配件上要有色温相关特征(多数可调色温灯映射后已有)。
  3. 在配件 输出配置 中打开自适应灯光能力(注入过渡控制特征),否则「家庭」里可能看不到或打不开自适应开关。

第一步:输出配置开启能力 ​

控制台 → HomeKit → 桥接器 → 配件 → 输出配置,对灯泡服务写入例如:

toml
[services.Lightbulb]
adaptive_lighting = true

服务名以配件详情里实际 HAP 服务为准(常见为 Lightbulb)。保存后会刷新该配件映射。

在配件详情里应能看到与过渡 / 自适应相关的特征(保存核对方式同 配件输出配置)。

第二步:在「家庭」App 里打开自适应灯光 ​

  1. 打开该灯泡配件详情。
  2. 打开 自适应灯光(名称以当前 iOS「家庭」界面为准)。
  3. Home 会下发过渡曲线;Olink 按曲线定时写色温。

控制台里能做什么 ​

HomeKit 页有 自适应灯光 入口,可查看当前运行中的任务、曲线参数,以及手动停止某路任务;也可查看调节日志(已应用 / 跳过关灯 / 色温未变等)。

日常开关仍以「家庭」App 为准;控制台偏运维与排查。

运行原理 ​

整体在干什么 ​

自适应灯光不是 Olink 自己算「现在该冷光还是暖光」。算法与时间曲线由苹果「家庭」/ Home hub 侧给出;Olink 负责:

  1. 让配件具备 HomeKit 规定的过渡控制能力(三条特殊特征);
  2. 接收 Home 下发的色温曲线 + 调度参数;
  3. 按间隔算出当前目标色温(单位 mired),写到灯的色温属性(经状态机 → 米家等设备);
  4. 在合适时机把色温变化通知回 Home。

可以记成:Home 出曲线,Olink 按表写色温。

text
「家庭」打开自适应灯光
        │
        ▼
写入 TransitionControl(TLV:曲线、起算时间、更新间隔…)
        │
        ▼
Olink 保存任务 → 启动周期调度
        │
        ▼
每个 tick:按已过时间在曲线上插值 → 得到目标色温
        │
        ├─ 灯已关 / 亮度为 0 → 跳过写入(防误亮)
        ├─ 色温与当前相同 → 跳过
        └─ 否则 write 色温属性 → 米家灯执行
        │
        ▼
按通知间隔把色温变化推回 Home(可选)

能力从哪来(输出配置) ​

adaptive_lighting = true 时,Olink 会在对应灯泡服务上注入三条无设备属性绑定的 HAP 特征(幂等,重复保存不会叠多套):

特征(概念)作用
Supported…TransitionConfiguration只读:告诉 Home「本灯支持哪些过渡」(如色温 IID)
CharacteristicValueTransitionControl可读可写,且需 写响应(wr):Home 用它下发 / 编排曲线
CharacteristicValueActiveTransitionCount只读 + 事件:当前是否有活跃过渡(0 / 1)

没有这三条(或 TransitionControl 缺写响应权限),Home 打开自适应灯光可能直接失败(例如 HMErrorDomain)。因此必须先走输出配置再开家庭开关。

桥接器启动或配件热挂载时,若配件已具备上述能力,会为该灯创建自适应控制器;若库里还有上次未结束的曲线,会恢复任务并继续调度。

Home 打开之后发生什么 ​

  1. Home 向 TransitionControl 写入一段 base64 TLV。
  2. Olink 解析出:过渡 ID、曲线起点时间、色温控制点序列、亮度调节范围、更新间隔(缺省约 60s)、通知间隔阈值(缺省约 10 分钟)等。
  3. 若 TLV 表示「关闭 / 无效模式」,则清除任务、ActiveTransitionCount → 0。
  4. 若为有效开启:落盘当前任务 → ActiveTransitionCount → 1 → 启动(或重启)后台循环。
  5. 循环每隔 update_interval 执行一次 tick(见下)。

控制台「自适应灯光任务」看到的,就是这些内存 + 持久化里的活跃任务快照。

每个 tick 怎么算色温、怎么写灯 ​

  1. 用单调时钟算「自曲线生效起过了多久」(不依赖墙钟微调,避免休眠后乱跳)。
  2. 在曲线控制点之间定位当前落在哪一段;曲线走完则自动结束自适应。
  3. 读当前亮度;在亮度调节范围内,按段内进度对色温做插值,并加上与亮度相关的微调,得到目标 mired(再夹到合理区间,如 100–500)。
  4. 写前检查灯是否该动:
    • 有开关映射时:关着就不写色温;
    • 否则:亮度视为 0 也不写。
      这样日常关灯后,周期任务一般不会把灯「写色温暖醒」。
  5. 目标色温与当前状态机值相同 → 记日志「未变」,不写设备。
  6. 不同 → 经状态机同步写色温属性 → 映射到米家等真实设备。
  7. 距上次通知超过阈值且色温有变 → 向 Home 推送色温特征变化事件。

调节日志里常见结果大致对应:applied(已写入)、skipped_off(关灯跳过)、unchanged(值未变)。

为什么「第一次开启」仍可能自动开灯 ​

周期 tick 已尽量在关灯时不写色温。但「家庭」刚打开自适应灯光时,除了下发曲线,往往还会立刻按当前曲线点去设色温(协议侧第一次生效)。

米家多数灯具的实现是:收到色温写入 ≈ 亮灯并调到该色温。于是:

  • 首次开启 → 一次色温写入 → 灯被打开(见上方红色注意);
  • 已经开着自适应、后来你关灯 → 后续 tick 多半跳过写入 → 一般不会反复误亮。

这是设备侧「写色温带开灯」的行为,不是 Olink 单独发了「开灯」指令。

和「只拧色温」的区别 ​

手动拧色温自适应灯光
谁决定数值你在 Home 里拖Home 曲线 + Olink 按时间插值
是否持续一次写入按间隔持续 tick,直到关闭或曲线结束
关灯后—周期写入会被跳过(见上)

手动改色温 / 颜色是否会立刻关掉自适应,取决于当前 Home / 版本策略;Olink 侧以 TransitionControl 的开启与关闭 TLV 为准。

注意事项 ​

第一次开启会自动开灯

开启自适应灯光时,系统会立刻按曲线设置色温。

米家大部分灯具在「写色温」时会顺带亮灯。因此:第一次在「家庭」里打开自适应灯光,灯往往会自动打开。

请在不介意灯亮起的时段操作(例如白天、人或房间允许亮灯时);夜间、卧室已关灯时慎开,避免突然亮灯。

其它注意:

点说明
本质是写色温自适应运行中会周期性调节色温;不是单独的「场景模式」开关
关灯后的周期调节Olink 在灯已关(或亮度为 0)时,周期 tick 会跳过写色温,减轻误亮;但首次开启仍可能因 Home 下发色温而亮灯(见上方红字)
手动改色温 / 颜色在「家庭」里手动拧色温或颜色,可能与自适应曲线冲突;表现以当前系统与版本为准
未开输出配置未设 adaptive_lighting = true 时,Home 侧可能无法正常启用
不适用无色温特征的开关灯、仅开关的继电器等

相关文档 ​