Home Assistant 的 fritz.dial 动作：让 FRITZ!Box 自动拨号实现门铃与通知呼叫

Home Assistant 的 fritz.dial 动作让 FRITZ!Box 自动拨号实现门铃与通知呼叫【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iofritz.dial是 Home Assistant 中FRITZ!Box Tools集成提供的一个动作action它让路由器根据你给定的号码发起一次电话呼叫从而让连接在 FRITZ!Box 上的所有电话响起——这非常适合把普通座机变成门铃、警报器或事件通知终端。读完本文你将掌握在界面和 YAML 两种方式下调用fritz.dial的完整方法、全部参数含义与取值边界并了解它的前置条件与典型自动化场景。动作概览fritz.dial 能做什么fritz.dial的中文含义是“拨打一个电话号码”。根据 fritz.dial 动作文档 的定义使用该动作让您的 FRITZ!Box 拨打一个电话号码。当您希望连接的电话响起以作为通知时这非常方便例如在前门检测到运动时响铃。也就是说动作的执行者是 FRITZ!Box 路由器本身而不是手机或软电话。只要电话有线座机或 DECT 无绳电话连接在 FRITZ!Box 上路由器拨号后它们就会振铃。在 Home Assistant 的术语体系中动作action是自动化和脚本的构建单元——打开灯、设置恒温器、播放音乐、重启系统都属于动作。动作列表页面 对动作做了如下定位Actions are the things Home Assistant can do for you... They are the building blocks of automations and scripts.fritz.dial正是 FRITZ!Box Tools 集成下两个已文档化的动作之一另一个是 fritz.set_guest_wifi_password设置访客 Wi-Fi 密码两者在文档中互为 related actions相关动作。前置条件让拨号动作可用在调用fritz.dial之前需要在 FRITZ!Box 上确认两项设置否则动作无法正常工作。这一点在 FRITZ!Box Tools 集成文档 中被明确列为前置条件PrerequisitesTR-064允许应用访问与 UPnP通过 UPnP 传输状态信息协议必须开启路径为 FRITZ!Box 的Home Network家庭网络 Network网络 Network settings网络设置 Access Settings in the Home Network家庭网络中的访问设置。Home Assistant 依赖这两个协议登录路由器并读取设备信息。Click to Dial点击拨号服务必须开启路径为Telephony电话 Calls呼叫 Click to Dial。文档明确说明To use the dial action, the click to dial service of the FRITZ!Box must also be enabled.也就是说fritz.dial在底层实际上是调用了 FRITZ!Box 的 Click to Dial 服务FRITZ!Box 通过 TR-064 接口暴露的拨号能力这也是该动作被称为“由路由器拨号”的根本原因。此外集成还建议为 Home Assistant 创建独立用户System FRITZ!Box Users Users Add User并授予该用户FRITZ!Box Settings权限若使用预置管理员账号从 FRITZ!OS 7.24 起系统会生成以fritz开头、后跟四位随机数字的用户名可在System FRITZ!Box Users Users中查看。在界面UI中使用该动作如果你偏好可视化地构建自动化与脚本UI 使用说明 指出 Home Assistant 会逐步引导你完成动作配置选择目标、微调选项、保存即可无需任何 YAML 知识。按照 fritz.dial 动作文档 的步骤进入设置Settings 自动化与场景Automations scenes。打开一个现有的自动化或脚本或选择创建自动化Create automation 创建新自动化Create new automation。如果是新建自动化在When何时部分添加触发器脚本不需要触发器它们由其他内容调用时运行。在Then do然后执行部分选择添加动作Add action。从动作列表中搜索并选择Dial a phone number拨打一个电话号码。选择要拨号的FRITZ!Box 设备FRITZ!Box device并设置电话号码Phone number与最大振铃时长Maximum ring duration。选择保存Save。UI 中的选项界面中提供的选项及其含义如下来自 fritz.dial 动作文档选项说明FRITZ!Box 设备FRITZ!Box device指定从哪台 FRITZ!Box 拨号。电话号码Phone number要拨打的电话号码。最大振铃时长Maximum ring duration拨号后最多振铃的秒数。实际振铃时间可能更短取决于被叫电话的设置。默认为 15 秒。这些选项在文档构建层面由 plugins/options_ui.rb 中的options_uiLiquid 标签渲染它会为每个选项生成带名称、必填/可选标识与描述说明的 HTML 条目并复用与configuration_basic相同的样式结构。在 YAML 中使用该动作如果你直接编写 YAML或想确切了解 Home Assistant 底层做了什么YAML 使用说明 指出这一节提供技术参考列出 YAML 中的字段名、类型以及哪些是必填项。在 YAML 中该动作的名称为fritz.dial。一个基础示例来自 fritz.dial 动作文档action: fritz.dial data: device_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 number: **9 max_ring_seconds: 15YAML 中的字段字段说明必填类型device_id指定从哪台 FRITZ!Box 拨号。是stringnumber要拨打的电话号码。是stringmax_ring_seconds拨号后最多振铃的秒数。实际振铃时间可能更短取决于被叫电话的设置。默认为 15 秒。是integer这些字段在文档构建层面由 plugins/options_yaml.rb 中的options_yamlLiquid 标签渲染它复用共享的ConfigurationBlock渲染逻辑为每个字段生成带类型链接与 Required/Optional 徽标的配置条目保证 UI 说明与 YAML 参考的一致性。两点细节值得注意device_id是 FRITZ!Box 集成设备的内部 ID。它通常不是手动记忆的字符串而是在界面中选择设备时由系统自动填入示例中的a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4只是文档中的占位符格式。在 YAML 中编写时建议先通过界面创建一个动作再切换到 YAML 模式查看真实的device_id值。number字段的取值不仅限于普通电话号码还支持 FRITZ!Box 的拨号代码见下文“Good to know”。Good to know拨号代码与取值范围fritz.dial 动作文档 给出了两条重要的补充知识拨打**9会振铃所有连接在 FRITZ!Box 上的内部电话internal phones非常适合用作门铃doorbell或警报信号alarm signal。在 FRITZ!Box 的拨号体系中**9是呼叫内部话机的快捷代码无需真实外呼即可触发全屋电话同时振铃——这是把fritz.dial用作通知手段的关键技巧。最大振铃时长max_ring_seconds的取值范围是 1 到 300 秒。默认值为 15 秒超过 300 秒的取值是无效的。结合这两点最典型的用法是检测到门口有人如人体传感器触发时调用fritz.dial并拨打**9让家中所有电话振铃起到门铃或提醒的作用。典型自动化示例fritz.dial通常与其他动作或集成配合使用。下面给出两个基于文档内容的可直接落地的示例。示例一门口检测到运动时让全屋电话振铃这是动作文档开头描述的首选场景。在自动化中以运动传感器作为触发器在动作部分调用fritz.dialautomation: - alias: Doorbell ring when motion at front door triggers: - trigger: state entity_id: binary_sensor.front_door_motion to: on actions: - action: fritz.dial data: device_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 number: **9 max_ring_seconds: 15number: **9让所有内部电话振铃max_ring_seconds: 15表示最多响 15 秒。注意**9需要加上引号避免被 YAML 解析为特殊语法。示例二拨打到指定外部号码如果不使用内部拨号代码也可以直接拨打真实号码例如让 FRITZ!Box 呼叫你的手机action: fritz.dial data: device_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 number: 8613800138000 max_ring_seconds: 30实际振铃时长取决于被叫方这里是你的手机的设置例如对方开启静音或拒接时振铃会提前结束。与 fritz.set_guest_wifi_password 的关系fritz.dial 动作文档 的前置元数据中列出了 related actions相关动作fritz.set_guest_wifi_password。反过来fritz.set_guest_wifi_password 文档 也把fritz.dial列为相关动作。二者同属 FRITZ!Box Tools 集成fritz.dial负责“让电话响起”fritz.set_guest_wifi_password负责“轮换访客 Wi-Fi 密码”。在文档站构建时plugins/related.md 对应的 actions/related.md 会根据页面元数据自动在页面底部生成“Related actions”章节将这些动作互相串联。一个自然的组合场景是定时轮换访客 Wi-Fi 密码后用fritz.dial拨打**9振铃提示家庭成员密码已更新。故障排查与进一步阅读如果调用fritz.dial没有效果请优先按顺序检查Click to Dial 是否开启FRITZ!Box 的Telephony Calls Click to Dial。TR-064 与 UPnP 是否开启FRITZ!Box 的Home Network Network Network settings Access Settings in the Home Network。账号权限使用的用户是否具备FRITZ!Box Settings权限参考 FRITZ!Box Tools 集成文档 中的用户说明。device_id是否正确建议从界面创建一次动作再切换到 YAML 模式复制真实设备 ID。max_ring_seconds是否在 1–300 秒范围内超出范围的值不会生效。该动作属于FRITZ!Box Tools集成ha_domain: fritz配置方式为 config flow质量等级 gold更多关于设备跟踪、访客 Wi-Fi、家长控制开关、端口转发开关、Wi-Fi 开关等能力可参阅 FRITZ!Box Tools 集成文档。整个动作文档体系还包含“仍然卡住Still stuck?”提示actions/stuck.md当动作未按预期工作时可向 Home Assistant 社区寻求帮助并在提问时附上你调用的动作与预期行为。小结fritz.dial让 FRITZ!Box 作为拨号方是 Home Assistant 中把普通电话变成通知/门铃/警报终端的利器。UI 与 YAML 两种方式等价界面操作无需 YAML 知识YAML 则提供device_id、number、max_ring_seconds三个字段的完整技术参考。关键技巧拨打**9可振铃所有内部电话max_ring_seconds取值 1–300 秒默认 15 秒。使用前务必确认 FRITZ!Box 的 Click to Dial 服务已开启并保证 TR-064/UPnP 访问权限正常。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考