Home Assistant 中 Harmony Hub 配置同步动作 harmony.sync 完整使用指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读harmony.sync是 Home Assistant 中用于强制同步 Logitech Harmony Hub 与 Harmony 云端配置的核心动作。当你在 Harmony App 中增删了活动Activity、设备Device或按键命令Command后Home Assistant 并不会实时感知这些变更此时即可调用本动作让 Hub 主动拉取最新配置从而刷新写入配置目录的harmony_UNIQUE_ID.conf文件。读完本文你将掌握harmony.sync在 UI 与 YAML 两种方式下的调用方法、Target 定位机制以及它与 Harmony 集成配置文件、remote.turn_on、remote.send_command等周边能力如何协同工作。1. 动作概述什么时候需要同步根据 harmony.sync 动作文档本动作的用途是强制在 Harmony Hub 与 Harmony 云端之间执行一次同步Synchronization。典型触发场景是你在 Harmony App手机端或桌面端里修改了活动、设备或命令之后希望 Home Assistant 立刻拾取pick up最新配置。这些修改包括但不限于新增或删除了某个活动如添加Watch TV、Play Games新增或删除了某个受控设备如添加一台接收机 Receiver修改了某个设备下可用的按键命令列表。注意虽然动作名称是sync但它的本质是让 Home Assistant 重新读取 Hub 上的最新配置并刷新本地缓存文件而不是把本地改动推送到云端。2. 使用前提Harmony 集成与 XMPPharmony.sync动作由 Logitech Harmony Hub 集成 提供该集成属于Local Push本地推送IoT 类别支持以下硬件型号Harmony HubHarmony CompanionHarmony ProHarmony EliteHarmony Pro 2400集成通过配置流ha_config_flow: true完成设置并同时提供remote与select两类平台实体。集成文档特别提醒视固件版本而定你可能需要为该集成启用 XMPP。从 Harmony App 进入MenuHarmony SetupAdd/Edit Devices ActivitiesRemote HubEnable XMPP。因此在排查harmony.sync不生效的问题时应首先确认 XMPP 已开启、Hub 处于在线状态。3. 从用户界面调用UI 方式如果你倾向于可视化构建自动化与脚本Harmony 集成会在 UI 中引导你逐步完成设置全程无需编写 YAML。动作文档给出了标准操作路径进入SettingsAutomations scenes打开一个现有的自动化或脚本或者选择Create automationCreate new automation如果是在创建新自动化需在When触发条件区域添加一个触发器脚本Scripts不需要触发器它们由其他自动化或手动调用时运行在Then do执行动作区域选择Add action选择要控制的对象。在By target目标定位详见下文第 5 节下选择你想要控制的 Harmony 遥控器实体从该目标可用的动作列表中选择Sync点击Save保存。UI 中的选项本动作在 UI 中没有额外的可配置选项——它不需要任何参数直接对目标实体执行同步即可。4. 在 YAML 中调用动作文档明确指出在 YAML 中本动作的调用名称为harmony.sync。下面是最基础的可复制示例action: harmony.sync target: entity_id: remote.tv_room该示例会同步remote.tv_room与 Harmony 云端的配置。这里的target是必填项——动作文档Targets 说明强调本动作必须有目标target。目标就是动作的对象你可以将动作指向单个实体、设备、区域Area、楼层Floor或标签LabelHome Assistant 会对该目标背后所有匹配的remote域实体执行此动作。Target 的五种定位方式目标类型说明示例实体Entity单个具体的remote实体remote.living_room设备Device属于某台设备的所有remote实体—区域Area某个房间或区域中的所有remote实体—楼层Floor某个楼层上的所有remote实体—标签Label共享某个标签的所有remote实体—你还可以在同一次动作中混合多种目标类型例如同时添加一个具体实体和一个区域作为目标让动作同时作用于两者。在自动化 / 脚本中的完整示例automation: - alias: Sync Harmony hub after activity changes triggers: - trigger: state entity_id: remote.tv_room actions: - action: harmony.sync target: entity_id: remote.tv_room5. 同步的实际效果配置文件被刷新动作文档的Good to know部分点明了本动作最关键的实战含义启动时包含可用活动、设备和命令的配置文件会被写入你的 Home Assistant 配置目录。当你在 Harmony App 中做出修改之后运行本动作即可让这些信息得到刷新。对应的文件位于 配置目录命名格式为harmony_UNIQUE_ID.conf每个 Hub 设备对应一个。根据 Harmony 集成文档该文件包含三部分关键信息所有已编程活动的名称与 ID 编号所有已编程设备的名称与 ID 编号每台已编程设备可用的全部按键命令。集成文档还说明该文件在 Harmony Hub 配置发生变更时会自动被覆盖无需重启 Home Assistant——而harmony.sync正是触发这一刷新的动作。配置文件内容示例活动列表Activity的典型结构如下{ Activities: { -1: PowerOff, 20995306: Watch TV, 20995307: Play Games, 20995308: Listen Music } }设备与命令列表的典型结构如下{ Devices: { TV: { commands: [ PowerOff, PowerOn ], id: 327297814 }, Receiver: { commands: [ PowerOff, PowerOn, VolumeUp, VolumeDown, Mute ], id: 428297615 } } }可以看到harmony.sync刷新的这份文件正是其他 Harmony 动作如remote.turn_on按活动名启动、remote.send_command按设备名发送命令读取的权威索引。因此每次在 Harmony App 中改动配置后先执行一次harmony.sync可以避免后续自动化因为引用了过时的活动 ID 或设备命令而失败。6. 与相关动作的协同动作文档将 harmony.change_channel 列为相关动作。此外结合 Harmony 集成文档与同步机制密切相关的动作还包括remote.turn_on—— 按活动启动启动一个活动。若未指定activity将启动配置中的默认活动指定的活动既可以是活动名称也可以是配置文件中的活动 ID。数据属性可选说明entity_id否目标实体 IDactivity是要启动的活动 ID 或活动名称例如读取harmony_UNIQUE_ID.conf后按活动名Watch TV启动actions: - action: remote.turn_on target: entity_id: remote.bed_room_hub data: activity: Watch TVremote.send_command—— 发送按键命令向某台设备发送单条或多条命令。设备 ID、命令名称均来自启动时写入、并被harmony.sync刷新的配置文件。可选参数包括重复次数num_repeats、命令间隔delay_secs以及按键按住时长hold_secs。action: remote.send_command target: entity_id: remote.tv_room data: command: - PowerOn - Mute device: Receiver delay_secs: 0.6其中device也可以直接用配置文件中的设备 ID 代替设备名如428297615。7. 动手验证在 Actions 工具中测试无需编写任何 YAML你可以直接在界面中验证本动作的效果进入SettingsToolsActions搜索harmony.sync选择目标实体并点击Perform action即可立刻观察 Hub 同步后配置文件是否被刷新以及remote实体的属性如current_activity是否随之更新。这也是排查活动/设备改动未生效问题的最快途径。8. 最佳实践小结改动即同步每次在 Harmony App 中新增/删除活动、设备或命令后第一时间执行harmony.sync与状态属性联动同步完成后可使用模板传感器展示current_activity属性或通过状态触发自动化详见 Harmony 集成示例实现基于活动的联动控制无需重启配置文件的刷新由 Hub 配置变更或harmony.sync触发不需要重启 Home Assistant检查前提条件若同步后配置仍为旧内容先确认 XMPP 已启用、Hub 在线再重试harmony.sync。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考