企业官网建设流程全解析

Home Assistant Homematic 集成：详解 set_install_mode 动作——让 CCU 进入安装模式配对新设备

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

本文基于 Home Assistant 官方文档仓库（home-assistant.io）中的动作参考页 homematic.set_install_mode 展开，讲解homematic.set_install_mode动作的完整参数、UI 与 YAML 两种配置方式及其底层原理。读完后，你将能够：在自动化或脚本中让 Homematic XML-RPC 接口进入安装模式（install mode），以配对/学习新的无线设备；理解interface、mode、time、address各参数的取值含义与默认值；并将其与 homematic.reconnect、homematic.set_device_value、homematic.virtualkey、homematic.put_paramset、homematic.set_variable_value 等同类动作组合，形成一套可脚本化的 Homematic 设备接入流程。

什么是 set_install_mode 动作

homematic.set_install_mode是 Home Assistant 中 Homematic 集成 提供的服务动作之一，其官方描述为：将某个 Homematic XML-RPC 接口置入安装模式（Sets a Homematic XML-RPC interface into installation mode）。

Homematic 集成通过 XML-RPC 与你的 CCU/Homegear 建立双向通信：一方面用 XML-RPC 向设备下发数值，另一方面订阅 CCU 推送的设备事件。当你想把一台尚未配对的无线设备（例如新的 HM 无线开关、无线温度传感器）纳入系统时，必须先让 CCU 侧对应的无线接口进入"安装模式"（也称学习模式），接口才会在time指定的时间窗口内接收并学习新设备。这个动作就是干这件事的：

action: homematic.set_install_mode data: interface: wireless time: 120

也就是说，你可以在自动化里一键打开安装窗口，配合手机通知提醒，再手动按下待配对设备的配对键——整个"配新设备"流程被脚本化，无需登录 CCU 的 Web 管理界面。

需要特别注意该动作的权限与目标限制（官方文档明确说明）：此动作不支持 targets——在 UI 中不会让你选择区域、设备、实体或标签；并且只有拥有管理员权限（administrator）的用户才能执行此动作。原因是该操作作用于整个 XML-RPC 接口层面，而不是某个具体实体。

YAML 参数详解

在 YAML 中引用该动作为homematic.set_install_mode。官方给出的最小示例为：

action: | action: homematic.set_install_mode data: interface: wireless time: 120

各参数说明（源自文档的 Options in YAML，含类型、必填性与默认值）：

参数使用要点

interface 必须与配置一致。Homematic 集成在configuration.yaml中以interfaces声明多个 XML-RPC 接口，例如：

homematic: interfaces: wireless: host: 127.0.0.1 wired: host: 127.0.0.1 port: 2000

（配置变量说明与多接口示例可参见 Homematic 集成文档 的 Configuration 一节。）动作中的interface值就是上面这些键名。接口默认使用 2001 端口（无线设备），有线设备通常走 2000 端口，IP 设备走 2010 端口，CCU 提供的虚拟恒温器组走 9292 端口且需将path设为/groups；CCU3 启用 SSL 后端口号前会加一个 4（2001 变 42001）。安装模式只对无线接口有意义——有线与 IP 设备不走"配对/学习"流程，所以示例中使用的正是名为wireless的无线接口。

mode 的两种取值。mode: 1是常规的"正常模式"，用于学习新设备；mode: 2会移除该接口下已存在的旧链接（links），适用于需要重建链接关系的场景（例如设备换接口、链接错乱后重新配对）。不确定时保持默认1即可。

time 控制学习窗口。默认 60 秒。若设备较多或需要在多个位置按配对键，可以把时间放大，示例中的time: 120即把窗口延长到 2 分钟。窗口结束后接口自动退出安装模式，无需再发命令关闭。

address 可选但有用。指定待学习设备的地址或BidCoS-RF可让接口聚焦于学习目标设备。例如 Home Assistant 的virtualkey动作文档中，虚拟遥控器地址就是"BidCoS-RF"——如果你要学习的就是这台虚拟遥控器上的新按键，可在本动作中传入该地址。

在 UI 中使用该动作

官方文档给出的图形界面操作步骤（与 reconnect 等动作相同的入口）：

1. 进入Settings>Automations & scenes；
2. 打开一个已有自动化或脚本，或选择Create automation>Create new automation；
3. 若是新建自动化，先在When部分添加触发条件；脚本不需要触发器，它由其他东西调用时执行；
4. 在Then do部分选择Add action；
5. 在搜索框中搜索并选择Homematic: Set install mode；
6. 输入Interface，以及可选的Mode、Time、Address；
7. 选择Save。

UI 中的可选项与 YAML 参数一一对应：

• Interface：要置入安装模式的接口（必填）；
• Mode：安装模式，1 为正常模式，2 为移除已有旧链接；
• Time：保持安装模式的秒数；
• Address：要学习的 Homematic 设备或 BidCoS-RF 的地址。

再次强调文档中的限制：此动作不支持 targets（UI 中不提示选择区域、设备、实体或标签），且只有管理员可以执行。

实战：用自动化脚本化配对流程

把该动作放进自动化后，你可以做到"发一条通知提醒自己去按配对键，CCU 同时自动打开 120 秒的学习窗口"。以下示例综合了官方 YAML 示例的写法（action:块写法）与 Homematic 集成文档 中按键触发事件（homematic.keypress）的用法，属于组合运用：

automation: - alias: "开始学习新 Homematic 设备" triggers: # 例：按下虚拟遥控器 BidCoS-RF 的 1 通道短按，触发打开安装窗口 - trigger: event event_type: homematic.keypress event_data: name: "BidCoS-RF" channel: 1 param: PRESS_SHORT actions: - action: homematic.set_install_mode data: interface: wireless mode: 1 time: 120 # 提醒用户去按新设备的配对键 - action: notify.persistent_notification data: message: "无线接口已进入安装模式，请在 120 秒内按新设备的配对键"

关于用homematic.keypress事件触发，有两点依据来自集成文档：

• 带按钮的设备（如 HM-Sen-MDIR-WM55、遥控器）会触发homematic.keypress事件，事件数据包含name、channel、param三个字段，param可能是PRESS_SHORT、PRESS_LONG、PRESS_CONT、PRESS_LONG_RELEASE之一；
• name字段取决于是否启用了名称解析：未解析时是设备 ID（如LEQ1234657），解析成功时是你在 CCU/元数据中设置的名称（如"Kitchen Switch"）。示例中使用BidCoS-RF这一固定地址作为name过滤条件，对应未做名称解析时的取值形式。

与相关动作的配合

文档 front matter 的related_actions列出了五个相关动作，它们与本动作共同构成 Homematic 集成的动作族：

• homematic.reconnect：重连所有 Homematic 主机。集成文档指出，CCU/Homegear 重启后 Home Assistant 会停止收到设备更新，而该协议无法自动恢复连接，必须手动调用homematic.reconnect。因此典型运维自动化是"检测某传感器长时间未更新 → 调用 reconnect"（集成文档给出了完整的 template + automation 示例）。如果你在 CCU 重启后配对新设备，通常先 reconnect、再 set_install_mode，两步组合能覆盖"重启后配对"这一常见场景；
• homematic.set_device_value：直接调用设备setValue方法控制设备，适合设备未被完全支持时做参数级控制；
• homematic.virtualkey：模拟按键，例如对 BidCoS-RF 虚拟遥控器发PRESS_LONG，或对 KeyMatic 门锁发OPEN；
• homematic.put_paramset：直接调用putParamset方法修改设备参数集（如壁式恒温器的周程序WEEK_PROGRAM_POINTER），对 BidCoS-RF 设备还支持BURST/WAKEUP两种接收模式；
• homematic.set_variable_value：读写 CCU/Homegear 上的系统变量。

一个可复制的"学习新设备"完整序列是：

1. homematic.reconnect——确保 Home Assistant 与 CCU 连接正常；
2. homematic.set_install_mode——打开学习窗口（interface: wireless，time: 120）；
3. 在窗口内按下新设备的配对键；
4. 若新设备支持完整设备类型，Home Assistant 会自动检测并生成实体；集成文档提示，20 台以上设备的名称解析（resolvenames）可能让设备实体延迟约一分钟才在 UI 中出现。

适用前提与限制

结合 Homematic 集成文档，使用本动作前请确认以下前提：

• 已在configuration.yaml中配置homematic集成并重启 Home Assistant，且至少存在一个无线接口（默认 2001 端口）；
• CCU 3 及以上版本默认启用内部防火墙，必须在 CCU 安全设置中放行XML-RPC API，或将 Home Assistant 实例的 IP 加入白名单，否则接口层命令无法到达 CCU；
• 该集成当前标记为 legacy 质量级别（front matter 中ha_quality_scale: legacy），支持的实体类型包括 binary_sensor、climate、cover、light、lock、notify、sensor、switch；动作本身不受实体支持范围限制，因为它直接操作接口而非实体；
• 多主机（multiple hosts）场景下，接口名必须唯一且仅限 ASCII 字母；集成文档提示，多主机时动作只能使用其中一个连接，因此动作能操作的设备/变量范围受限于该主机/协议的范围——这不影响实体本身工作，但选择interface时要选对承载目标设备的那一个。

小结

homematic.set_install_mode用一个必填参数interface和三个可选参数（mode默认 1、time默认 60、address可选）就把"打开 CCU 无线接口学习窗口"这一步纳入了 Home Assistant 的自动化体系。它不支持 targets、仅限管理员执行，作用域是整个 XML-RPC 接口而非单个实体。把它与homematic.reconnect及homematic.keypress事件配合，即可实现"通知提醒 + 自动开窗 + 手动配对"的完整设备接入流程；对于接口下已有旧链接需要清理的场景，mode: 2提供了先清后配的手段。

参考文档：set_install_mode 动作参考、Homematic 集成、reconnect、set_device_value、virtualkey、put_paramset、set_variable_value。

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