企业官网建设流程全解析

Home Assistant 中 Reolink PTZ move 动作实战：为摄像头云台控制设置自定义速度

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

reolink.ptz_move是 Home Assistant 官方 Reolink 集成提供的动作，用于以自定义速度移动支持变速的 Reolink PTZ（pan-tilt-zoom，平移-倾斜-变焦）摄像头。本文以 reolink.ptz_move 动作文档为主体，结合 Reolink 集成文档中的按钮实体机制，完整讲解该动作在 UI 与 YAML 两种模式下的配置方法、Speed 参数取值，以及它与 PTZ 方向按钮实体协同工作的原理。读完本文，你将能在自动化或脚本中精确控制摄像头云台的转动速度，并理解为什么某些摄像头不会显示该动作的目标实体。

动作概览：一个动作控制云台转动速度

reolink.ptz_move的作用是"以你选择的速度移动一台 Reolink 摄像头"。它不是直接发送一次性的方向指令，而是与摄像头上的PTZ left、right、up、down、zoom in、zoom out等按钮实体（button 实体）配合使用：按钮实体决定转动方向，speed参数决定转动快慢。

从 Reolink 集成文档的按钮实体一节可以看到，集成会按摄像头型号支持情况创建以下 PTZ 相关按钮实体：

• PTZ stop
• PTZ left / PTZ right / PTZ up / PTZ down
• PTZ left up* / PTZ left down* / PTZ right up* / PTZ right down*（带*表示默认禁用）
• PTZ calibrate
• PTZ zoom in* / PTZ zoom out*
• PTZ continuous rotation*
• Guard go to / Guard set current position

其中PTZ left、right、up、down、left up、left down、right up、right down、zoom in、zoom out会持续朝对应方向移动摄像头，直到调用PTZ stop或触达硬件限位为止。只有"支持不同移动速度"的摄像头型号，才会在与这些方向按钮配合时启用reolink.ptz_move动作。

前置条件：确认你的摄像头支持自定义 PTZ 速度

在配置动作之前，需要先确认摄像头是否支持变速云台：

• 在自动化/脚本中为动作选择目标时，如果能看到PTZ left、PTZ right、PTZ up、PTZ down、PTZ zoom in、PTZ zoom out等按钮实体，说明该摄像头支持自定义 PTZ 速度，reolink.ptz_move可以正常使用。
• 如果选择目标时没有出现这些 PTZ 按钮实体，则该摄像头不支持自定义 PTZ 速度，此时无法使用本动作（见原文档"Good to know"一节）。

此外，需要先完成 Reolink 集成本身的配置（主机地址、设备用户名与密码），具体流程见 Reolink 集成配置文档。

在 UI 中调用：自动化/脚本逐步配置

原文档给出了在 Home Assistant 可视化编辑器中调用该动作的完整步骤：

1. 进入Settings>Automations & scenes（自动化与场景）。
2. 打开一个已有的自动化或脚本，或者选择Create automation>Create new automation（新建自动化）。
3. 如果是新建自动化，先在When（何时）区域添加一个触发器；脚本（scripts）不需要触发器，它们在被其他对象调用时运行。
4. 在Then do（然后执行）区域，选择Add action（添加动作）。
5. 在By target（按目标）下，选择要控制的 Reolink PTZ 按钮实体，例如PTZ left（目标的选择方式详见下文"动作目标"小节）。
6. 从该目标可用的动作列表中，选择PTZ move。
7. 输入你想要移动的Speed（速度）。
8. 选择Save（保存）。

在 UI 中，动作只有一个选项：

可视化编辑器的好处是不需要掌握 YAML 语法，Home Assistant 会逐步引导你完成目标选择、参数填写和保存。

在 YAML 中使用：动作与参数参考

如果你直接编写 YAML，或者想了解 Home Assistant 在底层发送了什么，可以使用下面的技术参考。

在 YAML 中，该动作以reolink.ptz_move引用。原文档给出的基础示例：

action: reolink.ptz_move target: entity_id: button.trackmix_ptz_left data: speed: 10

这个示例的含义是：使用button.trackmix_ptz_left实体，以速度10向左移动摄像头（示例中的 TrackMix 型号摄像头支持变速 PTZ）。

YAML 选项参考

动作目标（Targets）

该动作必须指定目标。目标就是动作的作用对象，可以指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的button域实体执行该动作：

• Entity（实体）：某一个具体的 button 实体，例如button.trackmix_ptz_left。
• Device（设备）：属于某台设备的所有 button 实体。
• Area（区域）：某个房间/区域内的所有 button 实体。
• Floor（楼层）：某个楼层上的所有 button 实体。
• Label（标签）：共享某个标签的所有 button 实体。

同一动作中可以混合选择多种目标类型，例如同时添加一个具体实体和一个区域，动作会对两者同时执行。

关于目标的详细通用说明可参见 actions/targets.md 模板。

与关联动作搭配使用

reolink.ptz_move在文档头部声明了关联动作 reolink.play_chime。该动作用于在 Reolink Chime 设备上播放铃声（例如在检测到移动时播放），两者可结合用于安防联动场景：PTZ move 负责转动摄像头对准目标，play chime 负责声音提醒。关联动作的自动生成逻辑可见 related.md 模板。

快速验证与故障排查

立即尝试（Try it yourself）

想不写一行 YAML 就验证效果？打开Settings>Tools>Actions（工具 > 动作），搜索reolink.ptz_move，填入字段后选择Perform action（执行动作），即可在真实实体上看到效果。UI 头部说明见 ui_header.md 模板，YAML 头部说明见 yaml_header.md 模板。

常见问题

• 选择目标时看不到 PTZ 按钮实体：如前文所述，这说明该摄像头型号不支持自定义 PTZ 速度，reolink.ptz_move无法用于该设备。
• PTZ 方向按钮是"持续移动"行为：调用reolink.ptz_move并指定方向按钮后，摄像头会持续转动，直到调用PTZ stop（reolink.ptz_move之外可配合 PTZ stop 按钮实体）或到达硬件限位。
• 默认禁用的实体需要先启用：带*的按钮实体（如 PTZ left up、zoom in 等）默认禁用，若需要作为目标，请先在实体设置中启用（参考 Reolink 集成文档）。

如果问题仍未解决，可以在 Home Assistant 社区（Discord、社区论坛、r/homeassistant）中描述你调用的动作与预期结果，获取实时帮助。

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