企业官网建设流程全解析

Home Assistant ONVIF 集成 PTZ 动作（onvif.ptz）完全指南：云台控制、变焦与预设位移动

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

导读

onvif.ptz是 Home Assistant 中用于控制 ONVIF 标准摄像头云台（Pan/Tilt/Zoom，即 PTZ）的核心动作（action）。本文基于 onvif.ptz 动作文档 与 ONVIF 集成文档，完整讲解如何在自动化与脚本中调用该动作、全部 UI 与 YAML 参数的语义与默认值、Targets 定向机制，以及 PTZ 动作生效的设备前提。读完本文，你将能在自动化或脚本中实现摄像头左右转动、上下倾斜、变焦、按指定距离与速度移动，以及跳转到已保存的预设位（Preset）。

ONVIF 集成与 PTZ 动作的关系

onvif.ptz动作隶属于 ONVIF 集成。该集成允许在 Home Assistant 中使用符合 ONVIF Profile S 标准的设备，需要先配置ffmpeg集成。集成通过 ONVIF 拉取点订阅（PullPoint subscription）API 处理设备事件并自动生成传感器实体，同时通过 ONVIF 辅助命令（auxiliary command）和成像服务（imaging service）暴露开关实体，例如红外灯ir_lamp、自动对焦autofocus与镜头雨刷wiper。

PTZ 动作则是在此基础上对设备云台能力的调用。官方文档明确强调了一个前提（Good to know）：你的摄像头必须支持 PTZ，这个动作才会产生任何效果。对于不具备云台能力的固定摄像头，调用onvif.ptz不会报错，但也不会有实际作用。

在自动化或脚本中调用 PTZ 动作（UI 方式）

要移动摄像头，可以在自动化（Automations）或脚本（Scripts）中通过界面添加该动作：

1. 进入Settings>Automations & scenes。
2. 打开现有的自动化或脚本，或选择Create automation>Create new automation。
3. 如果是新建自动化，在When（触发条件）部分添加一个触发器。脚本不需要触发器——脚本在被其他对象调用时才运行。
4. 在Then do（执行动作）部分，选择Add action。
5. 选择要控制的对象。在By target（按目标，参见下文 Targets 一节）下，选择要移动的 ONVIF 摄像头。
6. 从该目标可用的动作中选择PTZ。
7. 填写要使用的选项。
8. 选择Save保存。

UI 中的选项说明

在 YAML 中使用 onvif.ptz

在 YAML 中，该动作以onvif.ptz作为动作标识。基础示例：

action: onvif.ptz target: entity_id: camera.front_door data: pan: RIGHT tilt: UP

上述配置的效果是：将摄像头向右（RIGHT）平移并向上（UP）倾斜。注意方向字段并非互斥——你可以同时指定pan、tilt、zoom中的多个，让摄像头在同一请求内沿多个轴运动。

YAML 选项完整参考

各参数实战要点

• 方向三选（可组合）：pan/tilt/zoom均为可选字符串，任意组合后即可在单次调用中同时控制多个轴。未指定的轴不会动作。
• distance 与 speed 的取值区间：两者都是 0 到 1 之间的浮点系数。distance默认0.1，即默认只移动很小的步进量；需要大幅转动时应显式增大该值。speed没有默认值，若摄像头端对速度系数敏感，建议显式设置以获得稳定的移动节奏。
• move_mode 的默认行为：move_mode默认为RelativeMove（相对移动），即以当前画面为基准按给定的方向与距离移动一段；ContinuousMove为持续移动，移动会持续到continuous_duration（默认0.5秒）耗尽后自动停止；AbsoluteMove为绝对移动，需要配合坐标信息使用；GotoPreset用于跳转预设位；Stop用于立即停止当前移动。
• preset 与 GotoPreset 的配合：preset接受摄像头端返回的 PTZ 预设位 profile token。只有将move_mode设置为GotoPreset时该字段才有意义，例如：

action: onvif.ptz target: entity_id: camera.front_door data: move_mode: GotoPreset preset: "1" speed: 0.5

• continuous_duration 的定时语义：该参数默认0.5秒，仅在move_mode: ContinuousMove时生效，可理解为"移动开始后经过该秒数便自动发送停止指令"。

Targets：动作的目标定向机制

onvif.ptz必须指定目标（target），目标即动作的作用对象。你可以把动作指向单个实体、设备、区域（area）、楼层（floor）或标签（label），Home Assistant 会对该目标下所有匹配的 camera 实体执行动作：

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

此外，同一动作中可以混用不同类型的多个目标，例如同时指定一个具体实体和一个区域，让动作同时对两者执行。

与 ONVIF 集成的其他能力协同

PTZ 动作是 ONVIF 集成实体体系的一部分。该集成还会通过拉取点订阅 API 自动生成大量事件传感器（如移动报警、Tamper 检测、存储故障、处理器使用率、最后重启时间等）以及三个开关实体（红外灯、自动对焦、镜头雨刷），这些实体与onvif.ptz一起构成了对 ONVIF 摄像头的完整控制面：

• 传感器类：移动报警（Motion alarm）、多边形区域检测（Field detection）、人形识别（Human shape detection）、声音检测（Detected sound）、画面模糊/过暗/过亮、全局场景变化、篡改检测（Tamper detector）、存储故障、录像任务状态等，均以 binary_sensor / sensor 形式自动加入 Home Assistant。
• 开关类：ir_lamp（通过IrCutFilter成像设置控制红外灯）、autofocus（通过AutoFocusMode控制自动对焦）、wiper（通过 ONVIF 辅助命令控制镜头雨刷）。

实际联动时，你可以先让摄像头跳转到某个预设位（GotoPreset），再开启ir_lamp开关调整夜间补光，形成完整的安防巡检流程。

前提条件与注意事项

• 设备必须支持 PTZ：这是onvif.ptz生效的第一前提，官方文档在 Good to know 一节中明确强调。
• 设备需符合 ONVIF Profile S 且为 H.264 编码：ONVIF 集成在发现设备时要求至少存在一路 H.264 视频流。若出现 "No usable cameras were found" 错误，需在摄像头端把至少一路子码流设置为 H.264（主码流可保留 H.265）。
• 推荐为 Home Assistant 单独创建设备用户：集成文档建议在设备上为 Home Assistant 创建专用用户，当前全部功能使用标准用户即可满足。
• 多 profile 情形：多数 ONVIF 设备支持多个音视频 profile（不同画质或 NVR 下的多路摄像头），集成会为所有兼容且编码为 H.264 的 profile 添加实体；默认使用画质最高的第一个 profile，可通过界面禁用不需要的实体。
• try it与排障入口：可在开发者工具中直接试运行该动作验证设备响应；若动作未生效，优先确认摄像头固件是否支持 PTZ、ONVIF 用户权限是否足够，以及目标实体是否正确选中。

总结

onvif.ptz以统一的方式把 ONVIF 标准云台能力接入 Home Assistant 自动化体系：UI 与 YAML 两种途径完全等价，全部参数（方向、距离、速度、移动模式、连续移动时长、预设位）均可按需组合。理解move_mode五种模式的语义（ContinuousMove/RelativeMove/AbsoluteMove/GotoPreset/Stop）以及默认值（距离 0.1、相对移动、连续时长 0.5 秒）是写出稳定可复用的摄像头控制脚本的关键。配合 ONVIF 集成自带的事件传感器与红外灯/雨刷开关，你可以构建从"事件感知"到"云台动作响应"的完整监控自动化链路。

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