博客

中控系统如何通过 ONVIF 协议控制网络摄像机?设备发现与 PTZ 指令详解

面向中控系统开发,介绍ONVIF协议设备发现、Profile选型、服务地址获取、Media Profile与PTZ控制方法,并说明常用接口、请求参数及实际集成中的注意事项。

IFU ·


utools_1795266147986.webp

在中控系统项目中,网络摄像机除了提供视频画面,还可能需要接受中控主机的统一控制。例如,操作人员通过触摸屏控制摄像机转动、调整镜头焦距、调用预置位,或者根据不同场景自动切换摄像机拍摄方向。

对于支持网络控制的摄像机,ONVIF 是一种值得优先考虑的标准化接入方式。

与传统串口控制协议不同,ONVIF 不仅定义了摄像机的 PTZ 云台控制接口,还提供设备发现、设备信息查询、媒体配置、事件订阅等服务。

本文重点从中控软件开发角度介绍 ONVIF 的设备发现流程、PTZ 控制方法、常用操作接口、请求参数和实际集成注意事项。

一、什么是 ONVIF 协议?

ONVIF(Open Network Video Interface Forum)是一个面向网络视频设备互操作性的行业标准组织。

它的目标是让不同厂商的网络摄像机、视频编码器、录像设备及管理软件能够通过统一的网络接口进行交互。

ONVIF 采用基于 Web Services 的通信机制,主要涉及:

  • WS-Discovery:网络设备发现

  • SOAP:服务请求与响应

  • WSDL:服务接口描述

  • XML:请求和响应数据格式

  • HTTP / HTTPS:网络传输

  • RTSP:常见的视频流传输方式

从中控系统角度看,ONVIF 最有价值的部分是将设备管理、云台控制和状态查询等功能统一为标准服务接口。

例如,不同厂商的 PTZ 摄像机可能具有不同的内部控制实现,但只要对应功能按照 ONVIF PTZ 服务实现,中控软件就可以使用统一的操作接口进行控制。

需要注意:ONVIF 并不意味着所有摄像机的所有功能都完全一致。标准定义了通用接口,厂商仍可能提供额外的私有功能。

二、ONVIF Profile 应该如何选择?

ONVIF 通过 Profile 定义设备和客户端之间需要具备的功能范围。

对于摄像机控制项目,需要特别关注 Profile S 和 Profile T。

Profile主要用途相关功能
Profile S基础视频流与配置视频流、设备配置及相关 PTZ 功能
Profile T高级视频流H.264/H.265、图像设置、事件、PTZ 控制
Profile G边缘存储录像存储和检索
Profile M元数据与事件视频分析元数据和事件

如果项目重点是网络摄像机的云台控制,建议优先确认设备与客户端对 Profile T 的支持情况。

这里有一个重要的版本变化:

ONVIF 已宣布逐步结束 Profile S 支持,最后提交 Profile S 产品符合性认证的日期为 2027 年 3 月 31 日。Profile T 是其推荐替代方案。

Profile S 现有产品并不会在该日期自动停止工作,但新项目在选型和软件开发时,应当优先考虑 Profile T 及其更安全的认证机制。

另外,Profile T 客户端的 PTZ 控制属于强制支持功能,但设备是否具备 PTZ 硬件能力仍然取决于具体产品。固定摄像机不能因为支持 Profile T 就获得物理云台功能。

参考:ONVIF 官方 Profile T 与 Profile S 弃用说明。

三、ONVIF 的通信方式与常用参数

ONVIF 不是简单地向某个 TCP 端口发送一串控制字符串。

它通常采用 SOAP XML 请求,通过 HTTP 或 HTTPS 调用设备提供的服务接口。

常见通信参数如下:

参数常见情况说明
设备发现UDP 组播WS-Discovery
发现组播地址239.255.255.250IPv4 组播地址
发现端口UDP 3702WS-Discovery
服务通信HTTP / HTTPSSOAP 请求
HTTP 端口80、8080 等由设备配置决定
HTTPS 端口443 或其他由设备配置决定
视频流RTSP 等与控制服务分离
数据格式XMLSOAP 消息
PTZ 服务ONVIF PTZ Service云台控制接口

需要特别注意:

ONVIF 没有一个适用于所有设备的固定 HTTP 控制端口。

例如,有些摄像机使用 80 端口,有些使用 8080 或其他端口。正确的做法是通过设备发现或设备管理服务获取实际服务地址,而不是将某个端口写死在中控程序中。

四、第一步:通过 WS-Discovery 发现摄像机

如果项目中摄像机数量较多,逐台手动录入 IP 地址并不方便。

ONVIF 提供 WS-Discovery 机制,可以在局域网内搜索支持相应发现机制的设备。

典型发现流程:

  1. 中控主机向组播地址发送 Probe 请求。

  2. 网络中的 ONVIF 设备接收请求。

  3. 支持发现功能的设备返回 ProbeMatches。

  4. 中控程序解析设备地址和相关信息。

  5. 再通过设备管理服务获取设备能力和服务地址。

1. WS-Discovery 参数

参数数值
协议UDP
IPv4 组播地址239.255.255.250
UDP 端口3702
消息类型Probe
返回类型ProbeMatches

2. Probe 请求示例

下面是简化的 WS-Discovery XML 请求结构:

<?xml version="1.0" encoding="UTF-8"?>
<e:Envelope
 xmlns:e="http://www.w3.org/2003/05/soap-envelope"
 xmlns:w="http://schemas.xmlsoap.org/ws/2004/08/addressing"
 xmlns:d="http://schemas.xmlsoap.org/ws/2005/04/discovery">

  <e:Header>
    <w:MessageID>
      uuid:12345678-1234-1234-1234-123456789abc
    </w:MessageID>

    <w:To>
      urn:schemas-xmlsoap-org:ws:2005:04:discovery
    </w:To>

    <w:Action>
      http://schemas.xmlsoap.org/ws/2005/04/discovery/Probe
    </w:Action>
  </e:Header>

  <e:Body>
    <d:Probe/>
  </e:Body>

</e:Envelope>

这是便于理解的请求示意。实际实现还需要正确处理 WS-Addressing、UUID、XML 命名空间及设备返回数据。

3. 发现结果如何处理?

设备返回 ProbeMatches 后,中控程序应重点提取:

  • EndpointReference:设备唯一标识

  • Types:设备类型

  • Scopes:设备范围信息

  • XAddrs:设备服务地址

其中 XAddrs 尤其重要。

例如,设备可能返回:

http://192.168.110.21/onvif/device_service

这就是后续调用设备管理服务的入口地址。

不能假定所有摄像机的服务路径完全相同。

4. 设备发现的实际限制

WS-Discovery 通常依赖局域网组播。

如果摄像机和中控主机处于不同 VLAN、不同子网,或者交换机、无线 AP 禁止组播转发,设备发现可能失败。

因此,实际项目中建议同时支持:

  • 自动发现设备

  • 手动录入设备 IP

  • 手动配置 ONVIF 服务地址

这样即使网络环境不允许组播,也不会影响摄像机接入。

五、第二步:获取摄像机设备能力和服务地址

发现摄像机后,中控程序还不能立即调用 PTZ 控制接口。

需要先通过设备管理服务获取设备能力和服务地址。

常用操作包括:

操作名称作用
GetDeviceInformation获取厂商、型号、固件版本等
GetCapabilities查询设备服务能力
GetServices查询设备提供的服务地址
GetSystemDateAndTime查询设备时间
GetNetworkInterfaces查询网络接口信息

其中 GetCapabilities 和 GetServices 是后续接入的重要步骤。

1. GetCapabilities

该操作用于查询设备支持的服务能力,例如:

  • Media

  • PTZ

  • Events

  • Imaging

  • DeviceIO

如果设备具有 PTZ 服务,中控程序就可以继续获取 PTZ 服务地址。

2. GetServices

通过 GetServices,可以获得具体服务的 XAddr。

例如:

http://192.168.110.21/onvif/ptz_service

这是示意地址,真实地址必须以设备响应为准。

对于不同品牌设备,Media、PTZ、Imaging 等服务的 URL 可能不同。

建议中控软件将各服务地址分别保存,而不是通过固定路径拼接所有接口。

六、第三步:获取 Media Profile 和 PTZ 配置

在调用 PTZ 控制接口前,需要先获得设备的 Media Profile。

Profile 可以理解为设备的一套媒体配置组合,其中包含视频源、编码配置以及可能关联的 PTZ 配置。

常见操作:

操作作用
GetProfiles获取所有 Media Profile
GetProfile获取指定 Profile
GetConfigurations获取 PTZ 配置
GetConfigurationOptions获取配置可用参数

1. 获取 Media Profile

调用 Media 服务的 GetProfiles 后,设备会返回一个或多个 Profile。

例如:

ProfileToken = Profile_1

这个 Token 是后续 PTZ 控制时非常重要的参数。

2. 为什么需要 ProfileToken?

ONVIF PTZ 控制通常通过 ProfileToken 确定控制目标。

例如:

ProfileToken = Profile_1

它表示选择该媒体配置关联的摄像机控制配置。

实际项目中,不能假设所有设备都使用 Profile_1。必须先调用 GetProfiles,再读取设备真实返回的 Token。

对于多路视频源或多个配置文件的设备,尤其要注意选择正确的 Profile。

七、ONVIF PTZ 常用控制命令

ONVIF PTZ 服务是中控系统控制网络云台摄像机的核心。

常见操作如下:

操作ONVIF 方法功能
查询云台节点GetNodes获取 PTZ 节点
查询 PTZ 配置GetConfiguration获取配置
查询控制范围GetConfigurationOptions获取可用范围
获取预置位GetPresets查询预置位
保存预置位SetPreset保存预置位
删除预置位RemovePreset删除预置位
调用预置位GotoPreset移动至指定预置位
连续移动ContinuousMove持续移动
相对移动RelativeMove相对当前位置移动
绝对移动AbsoluteMove移动至指定坐标
停止移动Stop停止云台运动
查询状态GetStatus获取当前位置和运动状态

下面重点介绍实际项目中最常用的几个操作。

1. ContinuousMove:云台连续移动

ContinuousMove 是中控触摸屏方向控制最常使用的操作。

它可以控制摄像机向左、向右、向上、向下移动,也可以同时进行水平、垂直和变焦操作。

主要参数:

参数说明
ProfileToken媒体配置 Token
PanTilt.x水平速度
PanTilt.y垂直速度
Zoom.x变焦速度
Timeout连续移动超时时间

典型的速度参数通常采用归一化坐标,但实际取值范围必须通过 GetConfigurationOptions 获取。

例如,常见设备的 PanTilt 范围可能是:

X:-1.0 ~ 1.0
Y:-1.0 ~ 1.0

Zoom 范围可能是:

X:-1.0 ~ 1.0

这些只是常见的归一化范围示例,并不是所有摄像机的固定规定。

负数通常表示反方向,正数表示正方向,具体坐标方向和速度范围需要结合设备返回的空间定义判断。

SOAP 请求示例

以下为 ContinuousMove 的核心请求结构:

<tptz:ContinuousMove
 xmlns:tptz="http://www.onvif.org/ver20/ptz/wsdl">

  <tptz:ProfileToken>Profile_1</tptz:ProfileToken>

  <tptz:Velocity>
    <tt:PanTilt
      xmlns:tt="http://www.onvif.org/ver10/schema"
      x="-0.5"
      y="0.0"/>

    <tt:Zoom
      xmlns:tt="http://www.onvif.org/ver10/schema"
      x="0.0"/>
  </tptz:Velocity>

  <tptz:Timeout>PT2S</tptz:Timeout>

</tptz:ContinuousMove>

参数说明:

  • Profile_1:实际设备返回的 ProfileToken。

  • PanTilt.x=-0.5:水平负方向运动,速度示例为 0.5。

  • PanTilt.y=0.0:不进行垂直运动。

  • Zoom.x=0.0:不进行变焦。

  • PT2S:连续运动超时时间为 2 秒。

这里的 PT2S 是 ISO 8601 Duration 格式,不是普通的毫秒数字。

2. Stop:停止云台运动

Stop 用于停止正在执行的 PTZ 移动操作。

主要参数:

参数说明
ProfileToken媒体配置 Token
PanTilt是否停止水平和垂直运动
Zoom是否停止变焦

请求示例:

<tptz:Stop
 xmlns:tptz="http://www.onvif.org/ver20/ptz/wsdl">

  <tptz:ProfileToken>Profile_1</tptz:ProfileToken>

  <tptz:PanTilt>true</tptz:PanTilt>
  <tptz:Zoom>true</tptz:Zoom>

</tptz:Stop>

其中:

  • PanTilt=true:停止水平和垂直运动。

  • Zoom=true:停止变焦。

在中控界面中,建议将方向按钮设计为按下移动、松开停止。

例如:

按下左键
    ↓
ContinuousMove
    ↓
摄像机向左运动
    ↓
松开左键
    ↓
Stop

停止命令应尽可能及时发送。

另外,还应设置运动超时和异常停止机制,避免触摸终端断线、按钮事件丢失等情况造成摄像机持续运动。

3. GotoPreset:调用预置位

预置位是摄像机控制中非常实用的功能。

摄像机可以预先保存多个拍摄位置,例如:

  • 预置位 1:全景

  • 预置位 2:主席位置

  • 预置位 3:发言席

  • 预置位 4:观众区域

首先调用 GetPresets 获取设备已经保存的预置位。

返回数据中会包含:

  • PresetToken

  • Name

  • 其他可选信息

例如:

PresetToken = Preset_1
Name = 全景

调用时使用 GotoPreset:

<tptz:GotoPreset
 xmlns:tptz="http://www.onvif.org/ver20/ptz/wsdl">

  <tptz:ProfileToken>Profile_1</tptz:ProfileToken>
  <tptz:PresetToken>Preset_1</tptz:PresetToken>

</tptz:GotoPreset>

注意:Preset_1 是示意 Token,实际调用必须使用 GetPresets 返回的值。

4. SetPreset:保存预置位

如果需要通过中控界面保存当前摄像机位置,可以使用 SetPreset。

主要参数:

参数说明
ProfileToken媒体配置 Token
PresetName预置位名称,可选
PresetToken已有预置位 Token,可选

请求示例:

<tptz:SetPreset
 xmlns:tptz="http://www.onvif.org/ver20/ptz/wsdl">

  <tptz:ProfileToken>Profile_1</tptz:ProfileToken>
  <tptz:PresetName>全景</tptz:PresetName>

</tptz:SetPreset>

设备成功执行后会返回新的 PresetToken。

中控软件应保存这个真实 Token,而不是自行假定预置位一定按照 1、2、3、4 的顺序编号。

5. GetStatus:查询摄像机状态

GetStatus 可以用于查询摄像机当前 PTZ 状态。

主要信息包括:

  • PanTilt 当前位置

  • Zoom 当前值

  • MoveStatus

  • 设备时间(如果设备支持)

其中 MoveStatus 常见状态:

状态含义
IDLE空闲
MOVING正在运动
UNKNOWN状态未知

通过 GetStatus,中控程序可以判断摄像机是否仍在移动,以及当前云台位置。

但需要注意:不同设备可能对状态返回的支持程度不同,不能将某次状态查询失败直接解释为摄像机离线。

八、ONVIF 控制中常用参数和数据类型

为了让中控软件具备更好的兼容性,建议将常用参数单独整理。

参数数据类型作用
ProfileToken字符串媒体配置标识
NodeToken字符串PTZ 节点标识
ConfigurationToken字符串PTZ 配置标识
PresetToken字符串预置位标识
PanTilt.x浮点数水平运动参数
PanTilt.y浮点数垂直运动参数
Zoom.x浮点数变焦参数
TimeoutDuration移动超时时间
PanTilt布尔值是否停止云台移动
Zoom布尔值是否停止变焦

这里最容易出错的是各种 Token。

ProfileToken、PresetToken、NodeToken 和 ConfigurationToken 都是设备返回的标识符。

它们不是固定的数字,也不应由中控程序直接生成。

建议设备初始化时读取并保存这些数据,在后续控制中使用真实返回值。

九、ONVIF 身份认证与安全问题

ONVIF 设备通常需要用户名和密码认证。

实际接入时,需要根据设备支持的认证机制配置客户端。

常见方式包括:

  • HTTP Digest Authentication

  • WS-Security UsernameToken

  • HTTPS / TLS

其中,HTTP Digest 与 WS-Security UsernameToken 是不同层面的认证机制,不能将两者混为一谈。

较旧的 Profile S 规范强制使用 UsernameToken 认证。ONVIF 已明确指出该方式不再符合当前安全建议,并推荐采用 Profile T 所支持的更安全认证方式。

实际项目建议:

  1. 不使用摄像机默认账号密码。

  2. 为中控系统配置独立的控制账号。

  3. 根据需要限制摄像机账号权限。

  4. 优先使用 HTTPS 和设备支持的安全认证机制。

  5. 不在日志中记录明文密码或完整认证数据。

  6. 将摄像机控制网络与不可信网络隔离。

另外,设备时间不准确可能影响部分 WS-Security 时间戳认证。必要时应检查摄像机与中控主机的时间同步情况。

十、ONVIF 与 RTSP 有什么区别?

在实际集成时,经常有人将 ONVIF 和 RTSP 混为一谈。

实际上,两者承担不同的工作。

项目ONVIFRTSP
主要用途设备管理与控制媒体流会话控制
常见数据SOAP / XMLRTSP 文本请求与响应
云台控制支持 PTZ 服务不负责标准 PTZ 控制
设备发现支持 WS-Discovery不负责 ONVIF 设备发现
视频传输可获取媒体配置与流地址用于建立视频流会话

在中控项目中,可以通过 ONVIF 查询摄像机信息、调用预置位、控制云台,然后通过 RTSP 将视频流提供给支持 RTSP 的显示终端或视频平台。

需要注意:ONVIF 并不负责所有视频数据的实际传输,视频流地址通常通过 Media 服务获取。

因此,建议在中控软件中将摄像机控制服务与视频流播放服务分开管理。

十一、中控系统如何封装 ONVIF 摄像机控制?

如果项目中只有一台摄像机,可以直接调用相关接口。

但如果需要同时管理多个品牌、多台摄像机,就应该建立统一的设备控制层。

建议分为以下几个模块。

1. 设备发现模块

负责:

  • WS-Discovery

  • 设备 IP 获取

  • 设备识别

  • 手动添加

  • 设备重复识别

2. 设备管理模块

负责:

  • 用户认证

  • 获取设备信息

  • 获取服务地址

  • 查询设备能力

  • 获取 ProfileToken

3. PTZ 控制模块

负责:

  • 连续移动

  • 停止移动

  • 绝对移动

  • 相对移动

  • 变焦

  • 预置位保存与调用

  • 状态查询

4. 设备状态模块

建议至少维护:

状态获取方式
通信状态SOAP 请求结果及超时
云台位置GetStatus
变焦位置GetStatus
运动状态MoveStatus
预置位列表GetPresets
服务能力GetCapabilities / GetServices

5. 场景控制模块

例如,用户在触摸屏点击“汇报场景”:

  1. 调用摄像机预置位。

  2. 等待摄像机执行。

  3. 查询 PTZ 状态。

  4. 更新中控界面。

  5. 记录操作结果。

这样可以让 ONVIF 摄像机成为中控系统中的一个标准设备对象,而不是每个项目都重新编写一套摄像机控制逻辑。

十二、实际对接常见问题

1. 搜索不到摄像机

可能原因:

  • 中控与摄像机不在同一网段。

  • 交换机禁止组播。

  • 防火墙阻止 UDP 3702。

  • 摄像机关闭了 ONVIF 服务。

  • 摄像机发现服务未启用。

解决方式:先检查网络连通性,再尝试手动配置设备地址和服务 URL。

2. 能发现设备,但无法调用 PTZ

可能原因:

  • 设备没有 PTZ 功能。

  • PTZ 服务未启用。

  • 账号没有 PTZ 控制权限。

  • 没有获取正确的 ProfileToken。

  • 设备只支持部分 PTZ 操作。

建议通过 GetServices 和 GetCapabilities 检查服务能力。

3. 云台速度不正确

不同设备可能提供不同的速度空间和范围。

不能直接把其他摄像机的 -1.0~1.0 参数复制到当前设备。

建议先获取 GetConfigurationOptions,再按照设备返回的范围进行参数映射。

4. 连续移动后摄像机没有停止

可能原因:

  • Stop 请求没有成功发送。

  • 触摸终端松开事件丢失。

  • 网络通信延迟。

  • 移动请求的 Timeout 设置过长。

建议在控制逻辑中增加停止保护和最大运动时间限制。

5. 预置位调用失败

常见原因:

  • 使用了错误的 PresetToken。

  • 当前 ProfileToken 与预置位配置不匹配。

  • 设备不支持相关操作。

  • 预置位已被删除。

应当通过 GetPresets 重新读取设备的预置位列表。

6. 能控制云台,但无法获取视频画面

这是因为 ONVIF PTZ 服务和 RTSP 视频流属于不同功能。

应当检查 Media 服务返回的流地址、视频编码和 RTSP 连接情况,而不是只检查 PTZ 服务。

十三、总结

ONVIF 是中控系统接入网络摄像机时非常重要的一种标准化接口。

它能够将设备发现、设备信息获取、PTZ 控制、预置位管理和状态查询整合到统一的网络服务体系中。

对于中控系统开发人员来说,重点应该掌握以下内容:

  1. 通过 WS-Discovery 发现摄像机。

  2. 通过 GetCapabilities 和 GetServices 获取设备能力与服务地址。

  3. 通过 GetProfiles 获取真实的 ProfileToken。

  4. 通过 ContinuousMove、Stop、GotoPreset 实现 PTZ 控制。

  5. 通过 GetStatus 获取摄像机运行状态。

  6. 通过 RTSP 独立处理视频流。

  7. 通过认证、超时和异常处理保证控制可靠性。

对于多品牌摄像机集成项目,建议优先使用 ONVIF 标准接口实现通用功能,再针对厂商特有功能补充私有协议适配。

这样既可以提高中控软件的设备兼容能力,也能减少项目之间重复开发的工作量。

如果你在实际项目中遇到 ONVIF 设备发现、认证失败、PTZ 参数、预置位调用或不同品牌兼容方面的问题,欢迎在文章下方留言,或者通过邮件联系 IFU。请尽量提供摄像机品牌、具体型号和相关报错信息,方便进一步分析与交流。


官方参考资料

  1. ONVIF 官方 Profile T:
    https://www.onvif.org/profiles/profile-t/

  2. ONVIF 官方网络接口规范:
    https://www.onvif.org/profiles-specifications-new/

  3. ONVIF PTZ 服务操作索引:
    https://www.onvif.org/onvif/ver20/util/operationIndex.html

  4. ONVIF Profile S 弃用说明:
    https://www.onvif.org/ch/profile-s/profile-s-deprecation-qna/

  5. ONVIF 2026 年 6 月规范版本记录:
    https://www.onvif.org/profiles/specifications/specification-history/june-2026/

协议说明: 本文 XML 为展示核心操作参数的示例结构,并非包含全部认证头和传输头的完整 SOAP 报文。实际开发需要使用设备返回的服务地址、ProfileToken、PTZ 空间范围和认证信息。不同厂商对标准功能的实现可能存在差异,应以具体型号的官方文档和实际响应为准。



← 中控系统如何通过 PJLink 协议控制投影机?常用命令与参数详解 中控系统如何通过 Modbus 协议控制设备?RTU、TCP 通信与寄存器读写详解 →

这篇文章解决不了的,直接问我们

把现场条件和使用场景说清楚,对接工程师会给出明确结论。