
在中控系统项目中,网络摄像机除了提供视频画面,还可能需要接受中控主机的统一控制。例如,操作人员通过触摸屏控制摄像机转动、调整镜头焦距、调用预置位,或者根据不同场景自动切换摄像机拍摄方向。
对于支持网络控制的摄像机,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.250 | IPv4 组播地址 |
| 发现端口 | UDP 3702 | WS-Discovery |
| 服务通信 | HTTP / HTTPS | SOAP 请求 |
| HTTP 端口 | 80、8080 等 | 由设备配置决定 |
| HTTPS 端口 | 443 或其他 | 由设备配置决定 |
| 视频流 | RTSP 等 | 与控制服务分离 |
| 数据格式 | XML | SOAP 消息 |
| PTZ 服务 | ONVIF PTZ Service | 云台控制接口 |
需要特别注意:
ONVIF 没有一个适用于所有设备的固定 HTTP 控制端口。
例如,有些摄像机使用 80 端口,有些使用 8080 或其他端口。正确的做法是通过设备发现或设备管理服务获取实际服务地址,而不是将某个端口写死在中控程序中。
四、第一步:通过 WS-Discovery 发现摄像机
如果项目中摄像机数量较多,逐台手动录入 IP 地址并不方便。
ONVIF 提供 WS-Discovery 机制,可以在局域网内搜索支持相应发现机制的设备。
典型发现流程:
中控主机向组播地址发送 Probe 请求。
网络中的 ONVIF 设备接收请求。
支持发现功能的设备返回 ProbeMatches。
中控程序解析设备地址和相关信息。
再通过设备管理服务获取设备能力和服务地址。
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 | 浮点数 | 变焦参数 |
| Timeout | Duration | 移动超时时间 |
| 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 所支持的更安全认证方式。
实际项目建议:
不使用摄像机默认账号密码。
为中控系统配置独立的控制账号。
根据需要限制摄像机账号权限。
优先使用 HTTPS 和设备支持的安全认证机制。
不在日志中记录明文密码或完整认证数据。
将摄像机控制网络与不可信网络隔离。
另外,设备时间不准确可能影响部分 WS-Security 时间戳认证。必要时应检查摄像机与中控主机的时间同步情况。
十、ONVIF 与 RTSP 有什么区别?
在实际集成时,经常有人将 ONVIF 和 RTSP 混为一谈。
实际上,两者承担不同的工作。
| 项目 | ONVIF | RTSP |
|---|---|---|
| 主要用途 | 设备管理与控制 | 媒体流会话控制 |
| 常见数据 | SOAP / XML | RTSP 文本请求与响应 |
| 云台控制 | 支持 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. 场景控制模块
例如,用户在触摸屏点击“汇报场景”:
调用摄像机预置位。
等待摄像机执行。
查询 PTZ 状态。
更新中控界面。
记录操作结果。
这样可以让 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 控制、预置位管理和状态查询整合到统一的网络服务体系中。
对于中控系统开发人员来说,重点应该掌握以下内容:
通过 WS-Discovery 发现摄像机。
通过 GetCapabilities 和 GetServices 获取设备能力与服务地址。
通过 GetProfiles 获取真实的 ProfileToken。
通过 ContinuousMove、Stop、GotoPreset 实现 PTZ 控制。
通过 GetStatus 获取摄像机运行状态。
通过 RTSP 独立处理视频流。
通过认证、超时和异常处理保证控制可靠性。
对于多品牌摄像机集成项目,建议优先使用 ONVIF 标准接口实现通用功能,再针对厂商特有功能补充私有协议适配。
这样既可以提高中控软件的设备兼容能力,也能减少项目之间重复开发的工作量。
如果你在实际项目中遇到 ONVIF 设备发现、认证失败、PTZ 参数、预置位调用或不同品牌兼容方面的问题,欢迎在文章下方留言,或者通过邮件联系 IFU。请尽量提供摄像机品牌、具体型号和相关报错信息,方便进一步分析与交流。
官方参考资料
ONVIF 官方 Profile T:
https://www.onvif.org/profiles/profile-t/ONVIF 官方网络接口规范:
https://www.onvif.org/profiles-specifications-new/ONVIF PTZ 服务操作索引:
https://www.onvif.org/onvif/ver20/util/operationIndex.htmlONVIF Profile S 弃用说明:
https://www.onvif.org/ch/profile-s/profile-s-deprecation-qna/ONVIF 2026 年 6 月规范版本记录:
https://www.onvif.org/profiles/specifications/specification-history/june-2026/
协议说明: 本文 XML 为展示核心操作参数的示例结构,并非包含全部认证头和传输头的完整 SOAP 报文。实际开发需要使用设备返回的服务地址、ProfileToken、PTZ 空间范围和认证信息。不同厂商对标准功能的实现可能存在差异,应以具体型号的官方文档和实际响应为准。