Home Assistant UPB 集成实战upb.link_goto 动作快速将场景设置到目标亮度【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本篇技术指南围绕 Home Assistant 中 UPBUniversal Powerline Bus集成的upb.link_goto服务动作展开覆盖其在 UI 与 YAML 两种方式下的完整配置步骤、brightness/brightness_pct/rate三个参数的取值规则、UPB 系统对过渡时间的取整机制以及动作执行后可用于验证的upb.scene_changed事件。读完本文你可以在自动化或脚本中精确控制 UPB 场景link的亮度并正确设置平滑过渡时长。upb.link_goto 是什么upb.link_goto是 Home Assistant UPB 集成 提供的场景级动作用于将 UPB 场景scene/link直接设置到指定目标亮度。UPB 场景是一组可被联动控制的灯具链接upb.link_goto就是其中跳转到目标电平的命令。几个关键特性来自 动作参考文档 与 UPB 集成文档场景中不支持调光的灯会忽略亮度参数——它们只会被置为开/关状态不受brightness数值影响与upb.link_fade_start从当前亮度渐变到目标亮度不同link_goto是直达型命令适合需要立即到达目标电平的场合UPB 集成通过 UPB PIMPowerline Interface Module连接总线PIM 可接串口或走 TCP。集成的前提是从UPStart配置程序导出.upe文件并放入 Home Assistant 的 config 目录这一前置条件适用于本动作在内的所有 UPB 服务除了这类 UPB 专属动作UPB 灯光与场景实体同样支持 Home Assistant 标准的 Light / Scene 平台动作scene.turn_on、light.turn_on等。在用户界面中使用分步配置按 官方文档 给出的流程在 UI 中调用该动作共 7 步打开Settings Automations scenes打开一个已有的自动化或脚本或选择Create automationCreate new automation如果是新建自动化先在When部分添加触发条件脚本不需要触发器由其他实体调用时运行在Then do部分选择Add action在By target下选择要控制的 UPB 场景target 概念详见下文 动作的目标在针对该 target 展示的动作列表中选择Go to link填入目标亮度与过渡速率rate然后Save。UI 中暴露的三个选项选项说明是否必填Brightness目标亮度0表示关闭场景1为最小亮度255为最大亮度。与 Brightness percentage 二选一不能同时设置否Brightness percentage以百分比表示的目标亮度0关闭1最小100最大。与 Brightness 二选一否Rate场景过渡到新亮度所需时间秒。UPB 系统会将其取整到最近的支持值取值规则见下文 Rate 的取整机制-1表示使用设备默认速率否不改 YAML 快速验证在Settings Tools ActionsDeveloper Tools中搜索upb.link_goto填入场景实体与参数后点击Perform action即可直接观察真实实体上的效果无需编写任何 YAML该入口说明见 try_it 片段。在 YAML 中使用 upb.link_goto在 YAML 中该动作的名称为upb.link_goto。一个完整可运行的动作定义如下字段与 官方示例 一致采用当前推荐的列表式写法# 将 UPB 场景 scene.interior_lights 过渡到 50% 亮度历时 5 秒 - action: upb.link_goto target: entity_id: scene.interior_lights data: brightness_pct: 50 rate: 5参数完整参考参数类型必填默认值说明brightnessinteger否—目标亮度。0关闭场景1为最小亮度255为最大亮度。与brightness_pct二选一不能同时提供brightness_pctfloat否—以百分比表示的目标亮度。0关闭1最小100最大。与brightness二选一ratefloat否-1过渡到新亮度所需时间秒。UPB 系统取整到最近的支持值-1表示使用设备默认速率使用要点亮度参数互斥brightness0–255 绝对值与brightness_pct0–100 百分比表达同一语义只允许设置其中一个关闭场景的两种方式brightness: 0/brightness_pct: 0可以关闭场景如果只需要关闭这一语义更推荐使用专用的upb.link_deactivate动作它无任何附加参数见 相关动作rate: -1的默认语义不填rate时即等于-1由 UPB 设备固件决定过渡速率行为取决于硬件配置。Rate 的取整机制rate只是请求值。UPB 总线只提供离散的一组过渡时长系统会把请求值取整到最接近的支持值。完整的取整对照表来自 UPB 集成文档请求范围实际采用的过渡时间0 至 0.4 秒0 秒0.4 至 1.2 秒0.8 秒1.2 至 2.45 秒1.6 秒2.45 至 4.15 秒3.3 秒4.15 至 5.8 秒5 秒5.8 至 8.3 秒6.6 秒8.3 至 15 秒10 秒15 至 25 秒20 秒25 至 45 秒30 秒45 至 90 秒60 秒1.5 至 3.5 分钟2 分钟3.5 至 7.5 分钟5 分钟7.5 至 12.5 分钟10 分钟12.5 至 22.5 分钟15 分钟22.5 至 45 分钟30 分钟45 分钟及以上1 小时两点实践提示上表中 4.15–5.8 秒的区间会被取整为 5 秒因此示例中的rate: 5会精确落在支持值上而rate: 7实际生效的是 6.6 秒该取整规则只适用于亮度过渡时间不适用于 blink闪烁的速率。动作的目标Targetsupb.link_goto是必须指定 target的动作。target 可以是单一实体也可以是设备、区域、楼层或标签Home Assistant 会对匹配到的每个 scene 实体执行该动作规则定义见 targets 模板Entity单个场景实体如scene.interior_lightsDevice属于某个设备的全部场景实体Area某房间/区域内的全部场景实体Floor某楼层上的全部场景实体Label共享同一标签的全部场景实体。同一个动作还可以混合多种目标类型例如同时指定一个具体场景实体和一个区域一次调用即对两者生效- action: upb.link_goto target: entity_id: scene.interior_lights area_id: living_room data: brightness_pct: 80 rate: 10执行结果验证upb.scene_changed 事件从 集成文档 可以看到UPB link 发生任何变化时都会发出事件upb.scene_changedlink_goto执行成功后对应的就是其中的goto命令。事件数据event_data包含command变化类型取值为activated、blink、deactivated、fade_started、fade_stopped、goto之一address报告事件的 link 地址由 UPB 网络号与 Link 号组成格式如42_24网络 42、Link 24brightness_pct亮度百分比不适用时报告-1rate本次过渡采用的速率-1表示默认速率。利用该事件可以写一个场景跳转确认自动化写法参照集成文档中的事件示例条件改为goto- alias: UPB scene goto confirmed description: Trigger when UPB scene 9 on network 42 goes to a new level triggers: - trigger: event event_type: upb.scene_changed event_data: command: goto address: 42_9 actions: - action: persistent_notification.create data: title: Scene Goto message: Scene 9 on network 42 moved to {{ trigger.event.data.brightness_pct }}%相关动作upb.link_goto与以下 UPB 动作配合使用可覆盖场景亮度的直达 / 渐变 / 停止 / 关闭 / 闪烁全部语义各自的完整参数参见对应文档动作用途参考文档upb.link_goto将场景直接设置到目标亮度本文主题source/_actions/upb.link_goto.markdownupb.link_fade_start从当前亮度渐变到目标亮度参数brightness/brightness_pct/rate与link_goto相同source/_actions/upb.link_fade_start.markdownupb.link_fade_stop停止正在进行的场景渐变source/_actions/upb.link_fade_stop.markdownupb.link_deactivate关闭deactivate场景无附加参数source/_actions/upb.link_deactivate.markdownupb.link_blink让场景闪烁source/_actions/upb.link_blink.markdownupb.light_fade_start/upb.light_fade_stop/upb.light_blink面向单个灯光实体而非场景的同族动作source/_actions/upb.light_fade_start.markdown渐亮/渐暗场景下的典型写法见集成文档示例对light.kitchen调用upb.light_fade_startbrightness_pct: 75、rate: 10即 10 秒渐亮到 75%。注意事项与调试设备状态上报的局限UPB 设备不总是主动上报状态。例如调用渐变类动作后设备可能不会立即报告新的亮度此时调用homeassistant.update_entity可强制设备向 Home Assistant 报告当前状态见 集成文档 NotesUPStart 配置变更需重新导出在 UPStart 中修改 UPB 配置后必须重新导出.upe文件且文件名需与 config 目录中现有文件保持一致否则 Home Assistant 读取的仍是旧配置调光开关手动操作不被上报的前提若未在 UPStart 中把每个调光开关配置为手动操作时上报状态用户在墙上的手动改变开/关/亮度不会反映到 Home Assistant调试日志排查upb.link_goto无响应等问题时在configuration.yaml中启用 debug 日志并重启logger: logs: upb_lib: debug homeassistant.components.upb: debug重启后日志输出在 config 目录的homeassistant.log中。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考