Home Assistant 中 xiaomi_aqara.add_device 操作实战：为 Aqara 网关开启 30 秒配对窗口

Home Assistant 中 xiaomi_aqara.add_device 操作实战为 Aqara 网关开启 30 秒配对窗口【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读本文围绕 Home Assistant 的Xiaomi Gateway (Aqara)集成域名为xiaomi_aqara提供的add_device操作展开。该操作可在自动化或脚本中远程开启网关的配对许可 30 秒让你无需打开 Mi Home 手机 App 即可把新的传感器或开关接入网关。读完本文你将掌握该操作在 UI 与 YAML 两种方式下的完整配置方法、gw_mac参数的使用要点以及它与remove_device、play_ringtone、stop_ringtone等兄弟操作配合的实战套路。操作概述add_device 做什么在 xiaomi_aqara.add_device 操作文档 中定义Add device操作会开启指定 Xiaomi Aqara 网关的加入许可join permission持续30 秒。在这段时间内新设备只要按下一次配对按钮即可被网关识别并完成入网。该操作的核心价值在于免 App 配网传统方式下给网关添加子设备通常要打开 Mi Home App 手动操作通过 Home Assistant 自动化你可以把入网许可窗口变成可编程、可触发的流程。可自动化例如先用自动化让网关进入配对状态再去按设备配对键完全不需要掏出手机。脚本可编排脚本中可先调用add_device等待片刻后校验新设备是否出现再配合remove_device完成设备迁移。从操作行为看它与 remove_device移除已配对设备、play_ringtone播放铃声、stop_ringtone停止铃声共同构成该集成在 Home Assistant 中的四个原生操作均在操作文档头部通过related_actions字段互相引用。前提条件网关与集成add_device操作依赖 Xiaomi Gateway (Aqara) 集成 已成功配置。该集成ha_integration_type: hub支持以下设备控制面binary_sensor、cover、light、lock、sensor、switchIoT 类别为 Local Push支持通过配置流ha_config_flow: true与 zeroconf 自动发现接入。集成文档特别提示了两个网关版本的差异v1 网关可直接配合 Home Assistant 使用无特殊问题。v2 网关启用本地 API 可能较为曲折甚至可能需要拆机操作Xiaomi 官方曾表示该能力在规划中。若使用 Hub 2 遇到问题可参考集成文档的 Troubleshooting 一节排查。配置时可选参数包括interface使用的网络接口默认any、key网关密钥仅使用传感器/二进制传感器时可省略、name网关名称。方式一从用户界面UI触发add_device操作不支持 targets——在 UI 中你不会被提示选择区域area、设备、实体或标签label只要求填写网关 MAC 地址。这是因为该操作作用于网关本身而非具体实体。在 UI 中从自动化或脚本调用该操作的步骤如下进入设置自动化与场景Settings Automations scenes。打开一个现有的自动化或脚本或选择创建自动化创建新自动化。如果新建的是自动化需要在当...时When部分添加触发器脚本不需要触发器脚本在被其他东西调用时才会运行。在然后执行Then do部分选择添加操作Add action。在搜索框中搜索并选择Xiaomi Gateway (Aqara): Add device。填写网关 MACGateway MAC。点击保存Save。UI 中的选项选项说明必填网关 MACGateway MAC网关的 MAC 地址只有一个网关时自动选中是方式二在 YAML 中使用在 YAML 中该操作以xiaomi_aqara.add_device引用。最基本的示例如下来自 操作文档action: xiaomi_aqara.add_device data: gw_mac: aa:bb:cc:dd:ee:ff注意在自动化中该 YAML 通常作为actions列表中的一项- alias: Pair new device to Aqara gateway triggers: - trigger: state entity_id: input_boolean.pairing_mode to: on actions: - action: xiaomi_aqara.add_device data: gw_mac: aa:bb:cc:dd:ee:ffYAML 选项说明字段类型必填说明gw_macstring是网关的 MAC 地址只有一个网关时自动使用参数深度解读gw_macgw_mac是add_device操作的唯一参数其语义在 remove_device 等兄弟操作中保持一致MAC 地址用于在多网关环境下精确定位目标网关。单网关场景文档明确说明当只有一个网关时它会被自动选中/使用。因此即便不显式指定gw_macHome Assistant 也会自动推断。多网关场景必须显式传入目标网关的 MAC否则操作无法确定要开启哪个网关的配对许可。MAC 地址的格式为小写十六进制、冒号分隔如aa:bb:cc:dd:ee:ff。另外从 Xiaomi Gateway (Aqara) 集成 的 Troubleshooting 可以了解到如果网关 MAC 以04:CF:8C或7C:49:EB开头很可能其 9898 端口处于关闭状态导致本地 API 方式不可用——这类网关需要额外的硬件级处理文档提及需要焊接和电工操作使用add_device前应先确认网关可被正常发现和控制。实战场景一配合 remove_device 迁移设备add_device最常见的组合拳是与remove_device一起使用。根据 remove_device 操作文档Remove device操作从指定网关移除一个已配对设备。当你想把设备配对到另一个网关时必须先把它从当前网关移除。因此迁移流程为先调用xiaomi_aqara.remove_device移除旧网关上的设备再对目标网关调用xiaomi_aqara.add_device开启 30 秒配对窗口最后按下设备配对键。remove_device的 YAML 示例action: xiaomi_aqara.remove_device data: gw_mac: aa:bb:cc:dd:ee:ff device_id: 158d000xxxxxc2其中device_id是待移除设备的硬件地址必填string 类型。可以看到两个操作的参数风格完全一致gw_mac定位网关设备级参数如device_id定位具体子设备。实战场景二配合 play_ringtone 实现配对提示开启配对窗口后用户往往需要走到设备旁按下配对键。为了让状态更直观可以先调用 play_ringtone 播放提示音。该操作要求网关固件至少为1.4.1_145支持的铃声 ID 分为几组警报类0 警车1、1 警车2、2 事故、3 倒计时、4 幽灵、5 狙击枪、6 战斗、7 空袭、8 犬吠门铃类10 门铃、11 敲门、12 Amuse、13 闹钟闹钟类20 MiMix、21 Enthusiastic、22 GuitarClassic、23 IceWorldPiano、24 LeisureTime、25 ChildHood、26 MorningStreamLiet、27 MusicBox、28 Orange、29 Thinker自定义铃声通过 Mi Home App 上传的自定义铃声ID 从 10001 起对应 YAMLaction: xiaomi_aqara.play_ringtone data: gw_mac: aa:bb:cc:dd:ee:ff ringtone_id: 8 ringtone_vol: 8铃声播放后可用 stop_ringtone 立即停止如报警被确认后静音其 YAML 只需gw_mac一个参数。实战场景三完整自动化示例将上述能力组合成一个一键配对新设备的自动化当开关被打开时先播放提示音再开启 30 秒配对窗口并给手机推送通知。- alias: Open Aqara gateway for pairing triggers: - trigger: state entity_id: input_boolean.pairing_mode to: on actions: - action: xiaomi_aqara.play_ringtone data: gw_mac: aa:bb:cc:dd:ee:ff ringtone_id: 10 ringtone_vol: 50 - action: xiaomi_aqara.add_device data: gw_mac: aa:bb:cc:dd:ee:ff - action: notify.notify_person data: message: 配对窗口已开启请在 30 秒内按下设备配对键快速验证在 Actions 工具中试运行不想写 YAML 也可以直接验证该操作打开设置工具操作Actions搜索xiaomi_aqara.add_device填写网关 MAC 后点击执行操作Perform action即可在真实网关上看效果。这也是排查参数是否正确的最快路径。常见问题与排查思路操作执行后设备仍未入网确认已在 30 秒窗口内按下设备配对键若超时需重新触发操作。多网关环境下不指定gw_mac操作可能无法确定目标网关建议始终显式传入 MAC。网关无法被发现/控制参考 Xiaomi Gateway (Aqara) 集成 的 Troubleshooting——检查 LAN 访问是否已启用、系统防火墙是否拦截、路由器是否支持组播multicast网关的硬性要求Docker 部署需使用--nethost若日志出现{error:Invalid key}可尝试用 Android 手机或模拟器重新生成密钥某些 iOS 生成的密钥存在兼容问题。MAC 以04:CF:8C或7C:49:EB开头这类网关的 9898 端口很可能被关闭本地 API 方案不可用需要硬件级处理。小结xiaomi_aqara.add_device是 Home Assistant 操作xiaomi_aqara域下实现免 App 配网的关键操作通过gw_mac定位网关一次调用即可开启 30 秒配对窗口。结合remove_device可完成设备跨网关迁移结合play_ringtone/stop_ringtone可构建带声音反馈的完整配网流程。无论是 UI 可视化配置还是纯 YAML 编写掌握这一操作都能显著提升 Aqara 设备的接入效率。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考