ONVIF

ONVIF 来自 Open Network Video Interface Forum（开放网络视频接口论坛）的首字母缩写，是一种在安防领域广泛应用的网络协议。ONVIF 官方 发布了很多协议规范，本文以 Profile S 规范为例，讲述 ONVIF 服务端和客户端的相关信息。

功能描述

ONVIF 是典型的客户端和服务端模型，在 同一局域网 内，服务端用于 IPC 产品，客户端用于 NVR 产品。

• IPC 一般作为 Server，接收来自 Client 端的请求。

  对于集成 ONVIF 功能的 IPC 设备，支持在 NVR 上通过 ONVIF 协议添加 IPC 设备，实现视频预览功能。

• NVR 或者其他后端设备作为 Client，主动发起连接和控制请求。

  对于集成 ONVIF 功能的 NVR 设备，可添加支持 ONVIF 协议的 IPC 设备，获取 IPC 设备的视频流。

  

以下主要讲述 Server 端的功能。

Server 端支持的功能

本小节从最基本功能开始描述 ONVIF 的基本工作过程。

• 启动 ONVIF Server

  • 启动后，IPC 设备可以被 ONVIF Client 端发现，连接后可以进行拉流、获取事件等动作。

  • 考虑到嵌入式设备资源有限，当前实现的 ONVIF Server 仅支持以下接口：

    设备管理类	媒体类	PTZ 控制类
    GetCapabilities	GetProfile	GetConfiguration
    GetDeviceInformation	GetProfiles	GetConfigurations
    GetServices	GetAudioSources	GetNode
    GetServiceCapabilities	GetAudioSourceConfiguration	GetNodes
    -	GetAudioSourceConfigurations	ContinuousMove
    -	GetAudioEncoderConfiguration	Stop
    -	GetAudioEncoderConfigurations	GetStatus
    -	GetVideoSources	AbsoluteMove
    -	GetVideoSourceConfiguration	RelativeMove
    -	GetVideoSourceConfigurations	GetPresets
    -	GetVideoEncoderConfiguration	SetPreset
    -	GetVideoEncoderConfigurations	RemovePreset
    -	GetVideoEncoderConfigurationOptions	GotoPreset
    -	SetVideoEncoderConfiguration	-
    -	GetStreamUri	-

    以上功能详细描述，请访问 ONVIF 官方文档 查看详情。

• 关闭 ONVIF Server

  关闭 ONVIF Server 与 Client 连接，此时 Server 端所有功能将会停用，设备将不会被发现。

开发指导

关联组件

• app_user_event
• app_user_onvif
• 支持 RTSP 功能的 IPC SDK

使用方法

在 ability.config 配置文件中，将以下配置使能：

ENV_TUYA_ONVIF_ENABLE=1
ENV_TY_SYS_ONVIF_SERVER_ENABLE=1

ENV_FIRMNAME=\"xxxxx\" # 将用于设备被发现时所显示的名称

数据结构

以下主要介绍 app_user_onvif 中相关数据结构。

类型定义

typedef enum {
    ONVIF_EVENT_TYPE_CELL_MOTION_DETECTION = 1,   // 移动侦测
    ONVIF_EVENT_TYPE_TRIGGER_DIGITAL_INPUT,       // 暂时未用，后续扩展
    ONVIF_EVENT_TYPE_TRIGGER_RELAY,               // 暂时未用，后续扩展
    ONVIF_EVENT_TYPE_VIDEO_SIGNAL_LOSS,           // 暂时未用，后续扩展
    ONVIF_EVENT_TYPE_DETECTED_SOUND,              // 暂时未用，后续扩展
    ONVIF_EVENT_TYPE_PTZPRESETS_INVOKED,          // 暂时未用，后续扩展
    ONVIF_EVENT_TYPE_PTZPRESETS_REACHED,          // 暂时未用，后续扩展
    ONVIF_EVENT_TYPE_PTZPRESETS_ABORTED,          // 暂时未用，后续扩展
    ONVIF_EVENT_TYPE_PTZPRESETS_LEFT,             // 暂时未用，后续扩展
} ONVIF_EVENT_TYPE_T;     // 事件类型

typedef struct {
    int channel;                        // 事件发生的通道号
    int state;                          // 事件发生状态
} ONVIF_EVENT_CELL_MOTION_DETECTION_T; // 移动侦测信息

typedef struct {
    int input_channel;
    int logical_state;
} ONVIF_EVENT_TRIGGER_DIGITAL_INPUT_T; // 暂时未用，后续扩展

typedef struct
{
    ONVIF_EVENT_TYPE_T event_type;          // 事件类型
    union {
        ONVIF_EVENT_CELL_MOTION_DETECTION_T cell_motion_detection;
        ONVIF_EVENT_TRIGGER_DIGITAL_INPUT_T digital_input;
    } event;                                // 事件详情
    uint64_t event_timestamp_ms;            // 事件时间戳
    char* snapshot_buf;                     // 事件抓图 buff(暂不支持)
    unsigned int snapshot_size;             // 事件抓图大小(暂不支持)
} ONVIF_EVENT_T;

API 说明

以下主要介绍 app_user_onvif Server 端相关 API。

ONVIF Server 启动与初始化

执行后，IPC 设备将被同局域网内的 NVR 等设备发现。该 API 会立即返回，具体 ONVIF 业务响应步骤将异步执行。

/**
* @ start ONVIF Server
*
* @return int 0 表示成功，非 0 异常
* @warning:
*/
int ty_user_onvif_server_start(void);

终止 ONVIF Server

停止 Server 端服务后，该 API 返回。

/**
* @ stop ONVIF Server
*
* @return int 0 表示成功，非 0 异常
* @warning:
*/
int ty_user_onvif_server_stop(void);

启动接收内部消息

用于 App 端下发 ONVIF 相关命令后的响应。

该 API 会立即返回，具体响应步骤将异步执行。

/**
* @ start receiving internal messages
*
* @return int 0 表示成功，非 0 异常
* @warning:
*/
int ty_user_onvif_msg_start(void);

事件上报

该 API 会立即返回，具体响应步骤将异步执行。

/**
* @ Reporting an Event
*
* @param[in] ONVIF_EVENT_T: event info
* @return int 0 表示成功，非 0 异常
* @warning:
*/
int ty_user_onvif_server_event_handling(ONVIF_EVENT_T *event)

注意事项

• 注意 ability.config 配置文件中的 ONVIF 使能项。
• 需要使用带有 RTSP（Real Time Streaming Protocol）功能的 SDK，否则后端无法通过 ONVIF 协议获取流。
• 暂不支持 事件抓图 功能。
• 因安全测试等相关原因，本 ONVIF 服务（ONVIF Server）中只使用 http digest 的鉴权方法。可能与其他厂商的从设备（ONVIF Client）存在兼容问题，可能问题有无法连接、无法拉流等问题。

常见问题

为什么 App 使能 ONVIF 后 NVR 设备无法拉流？

• 确认用户名和密码是否正确。
• 确认 NVR 等后端设备的鉴权方式，非 http digest 方式鉴权，会存在兼容问题。

为什么 NVR 等设备拉流且接收 IPC 事件后，PTZ 功能响应缓慢？

请确认 NVR 等后端设备的鉴权方式，非 http digest 方式鉴权，后端设备会存在持续鉴权等问题，多消耗 IPC 的 CPU 和带宽资源，导致其他功能响应缓慢。

为什么 NVR 等多台设备拉流后，若干台设备无法连接拉流？

可能超过 IPC ONVIF 和 RTSP 协议最大连接能力。目前可通过联系开发人员修改。