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 subscriptionAPI 处理设备事件并自动生成传感器实体同时通过 ONVIF 辅助命令auxiliary command和成像服务imaging service暴露开关实体例如红外灯ir_lamp、自动对焦autofocus与镜头雨刷wiper。PTZ 动作则是在此基础上对设备云台能力的调用。官方文档明确强调了一个前提Good to know你的摄像头必须支持 PTZ这个动作才会产生任何效果。对于不具备云台能力的固定摄像头调用onvif.ptz不会报错但也不会有实际作用。在自动化或脚本中调用 PTZ 动作UI 方式要移动摄像头可以在自动化Automations或脚本Scripts中通过界面添加该动作进入SettingsAutomations scenes。打开现有的自动化或脚本或选择Create automationCreate new automation。如果是新建自动化在When触发条件部分添加一个触发器。脚本不需要触发器——脚本在被其他对象调用时才运行。在Then do执行动作部分选择Add action。选择要控制的对象。在By target按目标参见下文 Targets 一节下选择要移动的 ONVIF 摄像头。从该目标可用的动作中选择PTZ。填写要使用的选项。选择Save保存。UI 中的选项说明选项说明Pan平移方向取值为LEFT或RIGHTTilt倾斜方向取值为UP或DOWNZoom变焦方向取值为ZOOM_IN或ZOOM_OUTDistance距离系数决定一次请求中摄像头移动多少取值范围 0 到 1Speed速度系数决定摄像头移动多快取值范围 0 到 1Move Mode移动模式取值为ContinuousMove、RelativeMove、AbsoluteMove、GotoPreset或StopContinuous duration仅对ContinuousMove模式有效移动停止前的延迟秒数Preset要移动到的 PTZ 预设位profile token仅配合GotoPreset移动模式使用在 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 选项完整参考字段类型必填默认值说明panstring否—平移方向LEFT或RIGHTtiltstring否—倾斜方向UP或DOWNzoomstring否—变焦方向ZOOM_IN或ZOOM_OUTdistancefloat否0.1距离系数决定一次请求中摄像头移动多少取值范围 0 到 1speedfloat否—速度系数决定摄像头移动多快取值范围 0 到 1move_modestring否RelativeMove移动模式ContinuousMove、RelativeMove、AbsoluteMove、GotoPreset或Stopcontinuous_durationfloat否0.5仅用于ContinuousMove模式移动停止前的延迟秒数presetstring否—要移动到的 PTZ 预设位 profile token仅配合GotoPreset模式使用各参数实战要点方向三选可组合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.5continuous_duration 的定时语义该参数默认0.5秒仅在move_mode: ContinuousMove时生效可理解为移动开始后经过该秒数便自动发送停止指令。Targets动作的目标定向机制onvif.ptz必须指定目标target目标即动作的作用对象。你可以把动作指向单个实体、设备、区域area、楼层floor或标签labelHome 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Home Assistant ONVIF 集成 PTZ 动作（onvif.ptz）完全指南：云台控制、变焦与预设位移动
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 subscriptionAPI 处理设备事件并自动生成传感器实体同时通过 ONVIF 辅助命令auxiliary command和成像服务imaging service暴露开关实体例如红外灯ir_lamp、自动对焦autofocus与镜头雨刷wiper。PTZ 动作则是在此基础上对设备云台能力的调用。官方文档明确强调了一个前提Good to know你的摄像头必须支持 PTZ这个动作才会产生任何效果。对于不具备云台能力的固定摄像头调用onvif.ptz不会报错但也不会有实际作用。在自动化或脚本中调用 PTZ 动作UI 方式要移动摄像头可以在自动化Automations或脚本Scripts中通过界面添加该动作进入SettingsAutomations scenes。打开现有的自动化或脚本或选择Create automationCreate new automation。如果是新建自动化在When触发条件部分添加一个触发器。脚本不需要触发器——脚本在被其他对象调用时才运行。在Then do执行动作部分选择Add action。选择要控制的对象。在By target按目标参见下文 Targets 一节下选择要移动的 ONVIF 摄像头。从该目标可用的动作中选择PTZ。填写要使用的选项。选择Save保存。UI 中的选项说明选项说明Pan平移方向取值为LEFT或RIGHTTilt倾斜方向取值为UP或DOWNZoom变焦方向取值为ZOOM_IN或ZOOM_OUTDistance距离系数决定一次请求中摄像头移动多少取值范围 0 到 1Speed速度系数决定摄像头移动多快取值范围 0 到 1Move Mode移动模式取值为ContinuousMove、RelativeMove、AbsoluteMove、GotoPreset或StopContinuous duration仅对ContinuousMove模式有效移动停止前的延迟秒数Preset要移动到的 PTZ 预设位profile token仅配合GotoPreset移动模式使用在 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 选项完整参考字段类型必填默认值说明panstring否—平移方向LEFT或RIGHTtiltstring否—倾斜方向UP或DOWNzoomstring否—变焦方向ZOOM_IN或ZOOM_OUTdistancefloat否0.1距离系数决定一次请求中摄像头移动多少取值范围 0 到 1speedfloat否—速度系数决定摄像头移动多快取值范围 0 到 1move_modestring否RelativeMove移动模式ContinuousMove、RelativeMove、AbsoluteMove、GotoPreset或Stopcontinuous_durationfloat否0.5仅用于ContinuousMove模式移动停止前的延迟秒数presetstring否—要移动到的 PTZ 预设位 profile token仅配合GotoPreset模式使用各参数实战要点方向三选可组合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.5continuous_duration 的定时语义该参数默认0.5秒仅在move_mode: ContinuousMove时生效可理解为移动开始后经过该秒数便自动发送停止指令。Targets动作的目标定向机制onvif.ptz必须指定目标target目标即动作的作用对象。你可以把动作指向单个实体、设备、区域area、楼层floor或标签labelHome 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考