企业官网建设流程全解析

Home Assistant 实战指南：使用 xiaomi_aqara.play_ringtone 让小米 Aqara 网关播放铃声

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

本文围绕 Home Assistant 的xiaomi_aqara.play_ringtone动作展开，完整讲解如何通过 UI 与 YAML 两种方式在小米 Aqara 网关上播放内置铃声（如门铃、报警音），并附上完整铃声 ID 清单与门铃/报警自动化实战示例。读完本文，你将能直接把 Aqara 网关打造成门铃或安防警报器，并与按钮、门窗传感器、烟雾探测器等设备联动。

动作概览与适用场景

xiaomi_aqara.play_ringtone是 Home Assistant 中 Xiaomi Gateway (Aqara) 集成提供的动作（action），作用是在小米 Aqara 网关上播放一条指定的铃声。

它的典型用途是把网关改造成门铃或报警音：

• 有人按下按钮时播放一声清脆的提示音；
• 门被打开时播放一条警示音；
• 烟雾或燃气报警联动时播放高音量警报（参见集成文档中的 Smoke 报警示例）。

固件前置条件：网关固件版本必须不低于1.4.1_145，否则该动作可能无法正常工作。

不支持 targets：与light.turn_on等支持目标选择（区域、设备、实体、标签）的动作不同，play_ringtone不支持 targets。在 UI 中配置时，你不会被提示选择区域、设备、实体或标签，而是直接填写网关 MAC 地址与铃声参数。

前置条件：先接入 Xiaomi Gateway (Aqara) 集成

调用该动作前，需要先把 Aqara 网关接入 Home Assistant：

1. 前往Settings>Devices & services，Aqara 网关通常会被自动发现；
2. 若未自动出现，点击右下角+，搜索xiaomi_aqara并进入配置流程；
3. 多个网关可通过重复配置流程来添加。

集成支持可选的key配置（仅使用传感器/二进制传感器时可省略），以及interface（使用的网络接口，默认any）与name（网关名称）。网关启用本地 API 的方式与版本有关：v1 网关可直接使用；v2 网关在启用本地 API 时可能较为繁琐，甚至需要拆机操作，遇到问题可参考集成文档的 Troubleshooting 章节。

通过 UI 配置该动作

如果你偏好可视化构建自动化，Home Assistant 会逐步引导你完成配置，无需编写 YAML。在自动化或脚本中播放铃声的操作步骤如下：

1. 进入Settings>Automations & scenes；
2. 打开现有的自动化或脚本，或选择Create automation>Create new automation；
3. 若是新建自动化，在When部分添加一个触发器；脚本不需要触发器，它们在被其他内容调用时才运行；
4. 在Then do部分选择Add action；
5. 在搜索框中搜索并选择Xiaomi Gateway (Aqara): Play ringtone；
6. 填写Gateway MAC与Ringtone ID，可选填Ringtone volume；
7. 选择Save保存。

UI 中的选项

通过 YAML 调用该动作

在 YAML 中，该动作的名称为xiaomi_aqara.play_ringtone。以下是一个基础示例：

action: xiaomi_aqara.play_ringtone data: gw_mac: aa:bb:cc:dd:ee:ff ringtone_id: 8 ringtone_vol: 8

YAML 中的选项

铃声 ID 完整清单

网关内置铃声分为三组，另有通过米家 App 上传的自定义铃声：

• Alarms（警报）
  • 0：警车 1（Police car 1）
  • 1：警车 2（Police car 2）
  • 2：事故（Accident）
  • 3：倒计时（Countdown）
  • 4：幽灵（Ghost）
  • 5：狙击枪（Sniper rifle）
  • 6：战斗（Battle）
  • 7：空袭（Air raid）
  • 8：狗吠（Bark）
• Doorbells（门铃）
  • 10：门铃（Doorbell）
  • 11：敲门（Knock at a door）
  • 12：逗趣（Amuse）
  • 13：闹钟（Alarm clock）
• Alarm clock（闹钟类）
  • 20：MiMix
  • 21：Enthusiastic
  • 22：GuitarClassic
  • 23：IceWorldPiano
  • 24：LeisureTime
  • 25：ChildHood
  • 26：MorningStreamLiet
  • 27：MusicBox
  • 28：Orange
  • 29：Thinker
• Custom ringtones（自定义铃声）：通过米家 App 上传的铃声，ID 从10001开始。

在集成文档的 Smoke 报警示例 中，ringtone_id: 2（事故音）配合ringtone_vol: 100用于火灾报警场景，可见音量与铃声组合可以灵活适应不同告警强度。

实战示例：长按按钮播放狗吠声

下面这个示例在长按一代圆形按钮时播放狗吠声（铃声 ID8）。它使用xiaomi_aqara.click事件作为触发器，click_type为long_click_press：

automation: triggers: - trigger: event event_type: xiaomi_aqara.click event_data: entity_id: binary_sensor.switch_158d000xxxxxc2 click_type: long_click_press actions: - action: xiaomi_aqara.play_ringtone data: gw_mac: aa:bb:cc:dd:ee:ff ringtone_id: 8 ringtone_vol: 8

将gw_mac替换为你网关注册时的 MAC 地址，entity_id替换为实际按钮的实体 ID。

实战示例：烟雾报警联动播放铃声

参考集成文档中的 Smoke 自动化示例，当烟雾传感器状态变为on时，同时发送通知并让网关播放警报铃声：

- alias: "Send notification on fire alarm" triggers: - trigger: state entity_id: binary_sensor.smoke_sensor_158d0001574899 from: "off" to: "on" actions: - action: notify.html5 data: title: "Fire alarm!" message: "Fire/Smoke detected!" - action: xiaomi_aqara.play_ringtone data: gw_mac: xxxxxxxxxxxx ringtone_id: 2 ringtone_vol: 100

联动停止铃声：stop_ringtone

铃声会在播放完毕后自动停止，但如果你需要在听到警报后立即静音，可以调用配套动作xiaomi_aqara.stop_ringtone（详见 stop_ringtone 动作文档）。它只接受一个必填参数gw_mac：

action: xiaomi_aqara.stop_ringtone data: gw_mac: aa:bb:cc:dd:ee:ff

集成文档中的经典玩法是：长按按钮播放狗吠，单击按钮立即停止：

- alias: "Stop barking immediately on single click" triggers: - trigger: event event_type: xiaomi_aqara.click event_data: entity_id: binary_sensor.switch_158d000xxxxxc2 click_type: single actions: - action: xiaomi_aqara.stop_ringtone data: gw_mac: xxxxxxxxxxxx

快速测试：不用写 YAML 也能验证

想先验证动作是否生效？打开Settings>Tools>Actions，搜索该动作，填入字段后点击Perform action，即可在真实网关上立即看到效果，无需编写任何 YAML。

相关动作

以下动作与play_ringtone配合良好：

• Stop ringtone：立即停止网关上正在播放的铃声；
• Add device：将设备添加到网关；
• Remove device：从网关移除设备。

常见问题排查

如果铃声播放不生效，可参考 集成文档 Troubleshooting 章节 中的排查思路：

• 网关未被发现：日志出现No gateway discovered时，多半是局域网问题或防火墙拦截，请确认已开启网关的 LAN 访问、关闭运行 Home Assistant 主机的防火墙、并保证路由器支持组播（multicast，Aqara 网关的必需条件）。
• Invalid key错误：尝试用 Android 手机或模拟器重新生成 key（iOS 应用生成的 key 在部分情况下存在问题）。
• 端口 9898 问题：若网关 MAC 以04:CF:8C或7C:49:EB开头，端口9898可能被关闭，该方法将无法工作。
• Docker 部署：若在 Docker 中运行 Home Assistant，请使用--net=host网络模式。
• 固件版本：再次确认网关固件不低于1.4.1_145，否则play_ringtone动作不受支持。

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