企业官网建设流程全解析

Home Assistant Bond 集成实战：用 bond.set_light_power_tracked_state 校正灯光电源跟踪状态

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

Bond集成通过 Bond Bridge 用射频信号复刻物理遥控器，控制吊扇、灯、遮阳帘等设备。本指南聚焦于bond.set_light_power_tracked_state这一动作：它不向灯具发送任何信号，只更新 Home Assistant 认为灯具当前所处的是开还是关的"跟踪状态（tracked state）"，用于在单向射频通信下纠正状态漂移。读完本文，你将掌握该动作的完整 UI 操作步骤、YAML 参数写法、目标（Targets）选择方式，以及"遥控器操作后自动重同步"的实战自动化方案。

为什么需要"跟踪状态"：单向射频设备的现实约束

Bond Bridge 通过射频信号控制大量设备，但这些射频链路往往是单向的——控制器只发信号，设备无法把自身真实状态回传给 Home Assistant。因此 Home Assistant 只能"认为"设备处于什么状态，这个状态就是文档中反复提到的tracked state（跟踪状态）。

当用户直接用物理遥控器操作灯具时，Home Assistant 无从得知状态变化，其内部跟踪状态就会与灯具真实状态漂移失步（drift out of sync）。此时调用bond.set_light_power_tracked_state即可纠正偏差：告诉 Home Assistant 灯具实际上是开还是关，不向灯具发送任何信号，灯具本身保持原样不动。

这一点可以从文档目录结构得到印证：仓库source/_actions/下存在一组同族的"tracked state"动作文档，包括 bond.set_light_brightness_tracked_state（校正亮度）、bond.set_fan_speed_tracked_state（校正风扇转速）和 bond.set_switch_power_tracked_state（校正开关电源状态），它们共同解决了单向设备的状态同步问题。Bond 集成整体属于ha_iot_class: Local Push的 hub 类集成，支持 Bond Bridge v1（snowbird）、v2（zermatt）、Bond Bridge Pro（zermatt-pro）及 Smart By Bond Fans（breck）等已测试设备（详见 source/_integrations/bond.markdown）。

在 UI 中创建自动化或脚本调用该动作

在界面上为自动化或脚本添加此动作，操作步骤如下：

1. 进入设置（Settings）>自动化与场景（Automations & scenes）。
2. 打开一个已有的自动化或脚本；也可以选择创建自动化（Create automation）>创建新自动化（Create new automation）。
3. 如果是新建自动化，需要在When（何时）区域添加一个触发器。脚本（script）不需要触发器——它们在被其他内容调用时才运行。
4. 在Then do（然后执行）区域选择添加动作（Add action）。
5. 选择要控制的对象：在按目标（By target）下（参见下文 动作的目标）选择要控制的区域、楼层、设备、标签或实体。
6. 从该目标对应的动作列表中，选择设置灯光电源跟踪状态（Set light power tracked state）。
7. 将电源状态（Power state）设置为与灯具真实状态一致的开或关。
8. 选择保存（Save）。

UI 中的选项

在 YAML 中使用

如果需要直接在 YAML 中编写自动化，或想精确了解 Home Assistant 底层字段（字段名、类型、是否必填），可以参考本节的技术参考。YAML 中该动作的标识为bond.set_light_power_tracked_state，一个基本示例如下：

action: bond.set_light_power_tracked_state target: entity_id: light.living_room_lights data: power_state: true

这个例子告诉 Home Assistant：light.living_room_lights当前处于开启状态。

YAML 参数说明

注意power_state为必填参数，默认值为false；由于动作本身只更新跟踪状态而不下发信号，这个值应当严格对齐灯具的真实物理状态，而不是你想要的目标状态。

动作的目标（Targets）

该动作必须指定目标。目标就是动作的作用对象，可以指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的light域实体执行该动作：

• 实体（Entity）：某一个具体的 light 域实体，例如light.living_room。
• 设备（Device）：属于某台设备的所有 light 域实体。
• 区域（Area）：某个房间/区域内的所有 light 域实体。
• 楼层（Floor）：某一楼层上的所有 light 域实体。
• 标签（Label）：共享某个标签的所有 light 域实体。

同一个动作里还可以组合不同类型的目标，例如同时添加一个具体实体和一个区域，让动作一次性作用于两者（参见 source/_includes/actions/targets.md）。

注意事项（Good to know）

• 该动作只更新跟踪状态，不向灯具发送信号，因此灯具保持原状，不会被误触发开关。
• 如果同时需要纠正跟踪的亮度值，请搭配使用 Set light brightness tracked state 动作。亮度采用 0（关）到 255（最亮）的整数刻度，例如传brightness: 128表示半亮度。

动手试一试

准备好实测了吗？进入设置（Settings）>工具（Tools）>动作（Actions），搜索该动作，填写字段后选择执行动作（Perform action），无需编写任何 YAML 即可在实际实体上观察效果（参见 source/_includes/actions/try_it.md）。

自动化实战：遥控器操作后重新同步灯光状态

这是官方文档给出的典型场景：当物理遥控器向 Home Assistant 传达"灯已被打开"的信息时，用该自动化把跟踪状态校准到真实状态。

• 触发器（Trigger）：遥控器"开"按钮被按下
• 动作（Action）：设置灯光电源跟踪状态
  • 目标（Target）：客厅灯（Living room lights）
  • 电源状态（Power state）：开

完整 YAML 如下：

automation: - alias: "Resync the living room light state" triggers: - trigger: state entity_id: sensor.light_remote_button to: "on" actions: - action: bond.set_light_power_tracked_state target: entity_id: light.living_room_lights data: power_state: true

这里的思路是：物理遥控按钮被按下时，通常配套的传感器或事件会将按钮状态（如sensor.light_remote_button变为"on"）暴露给 Home Assistant；自动化以此为触发器，立即把light.living_room_lights的跟踪电源状态校准为true，从而让仪表盘、语音助手和后续自动化看到的都是真实状态。

关联动作一览

同族的"tracked state"动作形成一个完整的校准体系，可根据设备类型选用：

使用前提与边界

从 Bond 集成文档 可以确认以下适用前提：

• 该集成支持固件v2.10.x 及以上的 Bond Bridge；v2.9.x 及更低固件无法正常工作，添加集成前请先在 Bond App 中升级固件。
• 集成通过配置流（config flow）添加，需要 Bond hub 的主机地址与访问令牌（access token），令牌获取方式见 Bond Local API 文档的 Getting Started 章节。
• 集成覆盖 button、cover、fan、light、switch 等多种平台，本动作仅作用于 light 域实体，相关实体通常由 Bond 集成自动创建。

最后提醒：本动作的价值在于"校正认知"而非"控制设备"。它专用于修复单向射频链路带来的状态漂移，日常开关灯请使用常规的light.turn_on/light.turn_off，只有状态失步时才需要把它接入自动化进行重同步。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io