ONVIF実装方法のFAQ - Genius Vision

Event Templateは、Genius Visionによって定義されたパラメータで、ONVIFの一部があいまいであるか、イベント通知メカニズムの実際の実装について十分に明確でないという事実を補償します。実際には、開発者はONVIFの仕様書をいくつか若干異なる方法で想像して実装するため、相互運用性は不完全です。

私たちのプリンシパルの1つとして述べられているように、欠陥や矛盾のないという完全な仕様書がこの世に存在しないため、このような仕様の問題を回避し、これらの互換性の問題に対応するためにいくつかの代替実装を提供するためです。

この資料では、各Event Templateの要約された定義を参照することができます。

以下は、あるNVRチャネルに対してEvent Templateを設定する方法の例を示します。

どのONVIF仕様書が参照されていますか？

Translated: en=>ja from What ONVIF specs are referenced?

実装のヒントをどのように扱うべきか？

Translated: en=>ja from How should I treat the implementation hints

利用規約

カメラ開発者に、専門知識を使用して数十のONVIF仕様書を見回して検索する努力を惜しむために、この文書にいくつかの実装ヒントを入れました。ただし、これらのヒントを読む前に、次の規則を理解する必要があります。

実装のヒントはサポートされていません。サポートすることには、コンサルタントサービスの対象となり、料金を支払う必要があります。
実装のヒントに示されている正確性の保証はありません。自己責任で使用してください。
ONVIFの実装を検証することは、XMLまたは「テストレポート」を解釈することによって行うべきではありません。むしろ、ソフトウェアとカメラを実際操作して手動と視覚的に行い、それらが期待通りに相互運用できるかどうかを確認する必要があります。多くのカメラのONVIF欠陥は、プログラマが「テストツール」に依存していることが原因であることが知られています。人間は、責任をマシンに取れせてはならなく、特にプログラマは人間であり、テストツールを「チート」する方法を知っているのです。詳細はこの記事をお読みください。
実装のヒントは、ONVIF仕様書に取って代わるものではありません。私たちはなお、ONVIFを理解する最善の方法は、仕様書を読んで熟すことだと考えています。
ONVIF実行可能なソフトウェアをテストする必要がある場合は、ONVIF検証ポータルから試用版ソフトウェアをダウンロードすることを歓迎します。
参照される実際の仕様書については、ONVIFの仕様書を参照しているものを参照してください。

XML namespaces

Except for additionally described, all XML namespace prefix definitions used in the XML examples are consistent with ONVIF-Core-Specification-v230.pdf, 5.3 Namespaces.

Legends

In the XML example, if you see this green-highlighted text, it means you must substitute the highlighted text into programmatic or proper value.
The "<ver20/imaging>GetOptions" is a short-hand notation, meaning it refers to the GetOptions command of Imaging service 2.0, and it's actually different from Imaging service 1.0. This notation is required to clearly express the XML namespace changes among spec versions, especially from 1.0 to 2.0. For more details please refer to this technical article: What does ONVIF version 1.0, 1.1, 1.2, 2.0 generally means? Why version 1.0, 1.1, 1.2, 2.0 can be incompatible?
The bold black text, depending on context, such as "GetProfiles" usually means a command name defined ONVIF spec, where bold green text, such as "Channel" usually means an internal NVR variable or configurable parameter used to determine the actual software behavior.

If I'm going to use Genius Vision NVR to verify my camera, what basic knowledge should I have for this software?

Translated: en=>ja from If I'm going to use Genius Vision NVR to verify my camera, what basic knowledge should I have for this software?

Please refer to following link for a short version of Genius Vision NVR manual for ONVIF self-verification.

Setup Genius Vision NVR for ONVIF Testing

What is the "Channel" parameter of the NVR software

Translated: en=>ja from What is the "Channel" parameter of the NVR software

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Channel is a NVR channel configuration parameter (as illustrated by the image below), which identifies the video source of a potentially multi-channel device. Normally the value is "1" and it means the first video source. If you change it to "2", it will select the second video source, and etc.

In the terminology of ONVIF, this mostly means that among the video sources returned by GetVideSources, only that matches what is specified by Channel will be used, while among profiles returned by GetProfiles, only the profiles matching the aforementioned video source will be used.

ONVIFのカメラ接続初期化プロトコル系列とは何ですか？

Translated: en=>ja from What is the initial camera attaching sequence

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Calling sequence

Calls <device>GetCapabilities to obtain device capabilities and various endpoints
Calls GetVideoSources to obtain a list of video sources. For one channel in Genius Vision NVR, only one video source will be used and it's determined by the Channel parameter (explained here) in NVR. Channel of value "1" designates the first video source, etc.
Calls GetProfiles to obtain a list of media profiles. Each profile token will be listed in the available stream selection of Genius Vision NVR. Please note only those profiles matching the designated video source (as specified by Channel) will be used.
Calls <ver20/imaging>GetOptions to obtain supported imaging options, if this call fails, the NVR will try to call <ver10/imaging>GetOptions instead. At this moment, an automatic protocol version detection of imaging service is performed and result is stored to an internal variable called ImagingVersion. The result of available imaging option will be listed on NVR.
Compare NVR imaging settings against the camera settings (using the result of GetProfiles), the NVR will determine a list of imaging parameters that needs to be changed, and then calls <ver20/imaging>SetImagingSettings, or <ver10/imaging>SetImagingSettings, depend on ImagingVersion.
Calls GetVideoEncoderConfigurationOptions for each stream configured. Available options will be listed on the NVR.
Compare NVR video encoder settings against the camera settings (using the result of GetProfiles). NVR will then determine a list of video encoder settings that needs to be changed, and then calls SetVideoEncoderConfiguration.
Calls GetStreamUri to obtain media URI, in order to get audio/video streaming, then use the designated parameter to invoke RTSP.

Mandatory commands summary

From the above we can understand that in order to properly support Genius Vision NVR, following ONVIF commands need to be implemented, but not all of them are mandatory. The mandatory commands are:

<device>GetCapabilities - mandatory
GetVideoSources - mandatory
GetProfiles - mandatory
GetStreamUri - mandatory

Optional commands summary

Lacking support of some commands will causes disabling of some NVR functions, but it can still work as a ordinary video camera:

<ver20/imaging>GetOptions or <ver10/imaging>GetOptions - optional. Lacking support for this command causes NVR to disable all ImagingOptions functions.
<ver20/imaging>SetImagingSettings or <ver10/imaging>SetImagingSettings - optional. Lacking support for this command causes NVR to disable all ImagingOptions functions.
GetVideoEncoderConfigurationOptions - optional. Lacking support for this command causes NVR to disable all VideoEncoderOptions functions.
SetVideoEncoderConfiguration - optional. Lacking support for this command causes NVR to disable all VideoEncoderOptions functions.

デュアルストリーミングの実装方法は

Translated: en=>ja from How to implement dual-streaming

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

To understand this part, please read the following hint first:

What is the initial camera attaching sequence

For ONVIF dual-streaming, Genius Vision NVR will call GetProfiles to obtain a list of supported media profiles. Each profile token will be listed in the stream selection of Genius Vision NVR. To support dual-streaming, at least two profiles must be supported. Please note only those profiles matching the designated video source (as specified by Channel, explained here) will be used.

VideoEncoderOptions（解像度、コーデック、フレームレートなど）の設定を実装する方法は

Translated: en=>ja from How to implement configuring of VideoEncoderOptions (Resolution, Codec, FrameRate etc)

Warning! This is an implementation hint article. Read this first.

To understand this part, please read the following hint first:

What is the initial camera attaching sequence

To support configuring of VideoEncoderOptions, following commands must be supported by the camera:

GetProfiles
GetVideoEncoderConfigurationOptions
SetVideoEncoderConfiguration

ImagingOptionsの設定（明るさ、彩度など）の実装方法は

Translated: en=>ja from How to implement configuring of ImagingOptions (Brightness, Saturation, etc)

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

To understand this part, please read the following hint first:

What is the initial camera attaching sequence

To support configuring of ImagingOptions, following commands must be supported by the camera:

GetProfiles. The existence of each value under the returned by the matching Profile/VideoSource/Imaging (including BacklightCompensation, Brightness, ColorSaturation, Contrast, Exposure, Focus, IrCutFilter, Sharpness, WideDynamicRange, WhiteBalance, etc) determines if that value is can be used in NVR client.
<ver20/imaging>GetOptions or <ver10/imaging>GetOptions
<ver20/imaging>SetImagingSettings, or <ver10/imaging>SetImagingSettings

PTZの実装方法は

Translated: en=>ja from How to implement PTZ

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Calling sequence

Check the NVR configuration parameter UsePTZ to see if PTZ is enabled. If not enabled, entire PTZ function initialization is skipped. The setting of UsePTZ will also be used to determine if version 1.0 or verision 2.0 of ONVIF PTZ will be used to communicate with the camera.
Calls <ver20/ptz>GetPresets or <ver10/ptz>GetPresets (depend on the value of UsePTZ) to get a list of PTZ presets.
If mouse PTZ operation is commenced, calls <ver20/ptz>ContinuousMove or <ver10/ptz>ContinuousMove (depend on the value of UsePTZ) to engage PTZ moving operation.
If preset-goto operation is commenced, calls <ver20/ptz>GotoPreset or <ver10/ptz>GotoPreset (depend on the value of UsePTZ) to engage PTZ preset-goto operation.

ONVIF仕様書によってイベント通知をサポートする方法は

Translated: en=>ja from How to support event notification under ONVIF spec

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

There are generally two ways to support event notification, as defined in ONVIF spec

Basic notification
Pull-point style notification

Due to the reasons stated here, Genius Vision NVR does not support basic notification. So you should use pull-point style notification only, in order to pass our verification.

P.S. According to the spec, there is actually a third way to support event notification using RTP, but since we haven't seen any vendor has supported it, we won't be able to support it.

関連項目

How to implement ONVIF Pull-point style event notification (ET01)

Genius Vision NVRはbasic notification（ONVIF基本的な通知）をサポートしていますか

Translated: en=>ja from Does Genius Vision NVR supports basic notification

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

No.

Basic notification, as defined in ONVIF spec, only applies IP camera and NVR in the same network segment. The notification will not be able to be transmitted if the camera is on the Internet and NVR is inside an NAT. This call-back style requirement also potentially requires the user to turn off any firewall mechanism that might exist, even in production stage.

The limitation & requirements introduced by basic notification will likely to cause extreme confusion when problems arise in the field, and it's very difficult to sort out the cause of problem in short time or in an obvious way. In practical sense, using basic notification will significantly increase the support cost to all roles of IP video deployment, including system integrators, VMS software developers, and IP camera manufacturers. In contrast, pull-point style notification does not have these problems.

Therefore, we believe that using real-time pull-point style notification is the most appropriate & easy way for deployment of ONVIF event notification, which spares the users the effort from (1) having more IT/network knowledge (2) knowing the exact IP locations of camera and the NVR, in order to use event notification.

Furthermore, requiring users to turning firewall off even in production environment is controversy, we will not recommend users to do that.

For all the reasons stated above, we don't plan to add basic notification to Genius Vision NVR.

ONVIFプルポイントスタイルのイベント通知（ET01）を実装する方法は

Translated: en=>ja from How to implement ONVIF Pull-point style event notification (ET01)

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Calling sequence

This sequence only applies when Event.Template (explained here) is set to ET01.
Calls CreatePullPointSubscription
Repeatedly calls to PullMessage to get notification message. Notification schema is consolidated at here. (Please pay attention to ET01, which is gathered from the spec)

MotionAlarm（動き検出）イベント（ET01）の実装方法は

Translated: en=>ja from How to implement MotionAlarm event (ET01)

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Calling sequence

This sequence only applies when Event.Template (explained here) is set to ET01.
Engage event notification sequence.

Event definition

ONVIF-Imaging-Service-Spec-v221.pdf

Message XML example

<wsnt:NotificationMessage>

<wsnt:Topic Dialect="http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet">

tns1:VideoSource/MotionAlarm

</wsnt:Topic>

<wsnt:Message>

<tt:Message UtcTime="2008-10-10T12:24:57.321Z">

<tt:Source>

<tt:SimpleItem Name="Source" Value="[videoSourceToken]" />

</tt:Source>

<tt:Data>

<tt:SimpleItem Name="State" Value="[motionState]" />

</tt:Data>

</tt:Message>

</wsnt:Message>

</wsnt:NotificationMessage>

[videoSourceToken]: Must match one of the tokens returned by GetVideoSources
[motionState]: true if motion is in progress, false if not.

関連項目

How to verify ONVIF motion detection

ONVIFの文脈でイベントのプロパティとは何ですか？SetSynchronizationPointとは何ですか？これはどのように実装されるべきですか？

Translated: en=>ja from What is Property in the context of ONVIF event? What is SetSynchronizationPoint? How should this be implemented?

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Introduction of Property in spec

Property, as described in ONVIF-Core-Specification-v230.pdf, is a simplified way to represent status change by ONVIF event notification mechanism:

Property operations

According to the spec, there are three kinds of property operation, Initialized, Deleted, and Changed:

What is a Synchronization Point

According to spec,

Notice the red highlighted text, a Synchronzation Point is requested automatically when CreatePullPointSubscription is requested. What it really means is that the NVC (client) does not need to issue SetSynchronizationPoint explicitly.

Does the NVC (client) need to send SetSynchronizationPoint explicitly

No.

Please refer to previous section. This is clearly defined in spec without ambiguity.

What does it really mean by Synchronization Point, I still don't understand

The ONVIF specs tend to get very technical about some pretty simple concepts. What you really need to do is that after receiving CreatePullPointSubscription request, NVT should treat the client doesn't know anything about the current device status. Therefore NVT should send all (subscribed) properties with their states to the client, with PropertyOperation="Initialized" in NotificationMessage. This way the client would know the initial state of each subscribed property.

For example, say a digital input is at ON state. When an NVT received CreatePullPointSubscription request from client, it should immediately send the ON state event to client (with PropertyOperation="Initialized"), so the client wouldn't wrongfully assume the digital input state is at OFF state (because the client is not told the correct information).

If NVC doesn't need to send SetSynchronizationPoint, then what's the point of having such a command

According to spec:

The SetSynchronizationPoint command is reserved for notification streaming interface (what is this?). Genius Vision NVR uses exclusively Pull-Point style event notification, so this command is never called by Genius Vision NVR.

通知ストリーミングインターフェイスとは何ですか？

Translated: en=>ja from What is notification streaming interface?

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

According to spec (ONVIF-Core-Specification-v230.pdf),

This special type of notification interface works in conjunction with RTP/RTSP, in which the NVT embeds notification packet inside RTP packets. Genius Vision NVR does not currently support this type of notification interface.

デジタル入力（ET01）の実装方法は

Translated: en=>ja from How to implement Digital Input (ET01)

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Calling sequence

For ONVIF digital input function, the calling sequence of Genius Vision NVR can be summerized as follows:

This sequence only applies when Event.Template (explained here) is set to ET01.
Calls <device>GetDigitalInputs to obtain number of input and their tokens. If failed, NVR will try to call <ver10/deviceio>GetDigitalInputs.
Engage event notification sequence.

Reflecting digital input state change

Event definition in spec

ONVIF-DeviceIo-Service-Spec-v221.pdf

Message XML example

<wsnt:NotificationMessage>

<wsnt:Topic Dialect="http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet">

tns1:Device/Trigger/DigitalInput

</wsnt:Topic>

<wsnt:Message>

<tt:Message UtcTime="2008-10-10T12:24:57.321Z">

<tt:Source>

<tt:SimpleItem Name="InputToken" Value="[digitalInputToken]" />

</tt:Source>

<tt:Data>

<tt:SimpleItem Name="LogicalState" Value="[digitalInputState]" />

</tt:Data>

</tt:Message>

</wsnt:Message>

</wsnt:NotificationMessage>

[digitalInputToken]: Must match one of the tokens returned by <device>GetDigitalInputs or <ver10/deviceio>GetDigitalInputs.
[digitalInputState]: true if ON, false if OFF.

関連項目

How to setup & verify ONVIF DIO (Digital Input/Relay Output)

リレー出力（ET01）の実装方法は

Translated: en=>ja from How to implement Relay Output (ET01)

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Calling sequence

For ONVIF relay output function, the calling sequence of Genius Vision NVR can be summerized as follows:

This sequence only applies when Event.Template (explained here) is set to ET01.
Calls <device>GetRelayOutputs to obtain number of input and their tokens. If failed, NVR will try to call <ver10/deviceio>GetRelayOutputs. This automatic protocol version detection will be remember in an internal variable called RelayUseDevIO.
Engage event notification sequence.
If relay is operated by user to switch ON or OFF, NVR will call <device>SetRelayOutputState or <ver10/deviceio>SetRelayOutputState, depending on RelayUseDevIO.

Reflecting relay state change

Event definition in spec

ONVIF-DeviceIo-Service-Spec-v221.pdf

Message XML example

Relay output state is reflected using notification events.

<wsnt:NotificationMessage>

<wsnt:Topic Dialect="http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet">

tns1:Device/Trigger/Relay

</wsnt:Topic>

<wsnt:Message>

<tt:Message UtcTime="2008-10-10T12:24:57.321Z">

<tt:Source>

<tt:SimpleItem Name="RelayToken" Value="[relayToken]" />

</tt:Source>

<tt:Data>

<tt:SimpleItem Name="LogicalState" Value="[relayLogicalState]" />

</tt:Data>

</tt:Message>

</wsnt:Message>

</wsnt:NotificationMessage>

[relayToken]: Must match one of the tokens returned by <device>GetRelayOutputs or <ver10/deviceio>GetRelayOutputs, depending on RelayUseDevIO.
[relayLogicalState]: active or inactive, reflecting actual relay status.

Changing relay state

Camera must implement <device>GetRelayOutputs or <ver10/deviceio>GetRelayOutputs in order to indicate its support to relay ouptuts.
Camera must implement <device>SetRelayOutputState or <ver10/deviceio>SetRelayOutputState in order to be able to change relay state.
The version of spec implemented by the relay output commands must be consistent.

関連項目

How to setup & verify ONVIF DIO (Digital Input/Relay Output)

InitialTerminationTimeの問題は何ですか？

Translated: en=>ja from What is the InitialTerminationTime issue

NOTE: 申し訳無いがこの記事がまだ翻訳されているです。この記事の緊急の必要がある場合は、私たちに連絡し、この記事の翻訳を迅速に行います。

Warning! This is an implementation hint article. Read this first.

Relevant spec hints

The meaning of InitialTerminationTime in CreatePullPointSubscription command is not very clearly defined in the spec. However it can be roughly interpreted as:

If InitialTerminationTime defined in relative time, the camera should automatically extend the actual termination time by the value specified with InitialTerminationTime each time the camera respond to a PullMessageRequest.

Status

Due to the principle stated here, in later versions of NVR software, an new template ET02 is added to accomodate this particular blurred spec issue.

Technical details

This interpretation can be extrapolated by following spec reading (ONVIF-Core-Specification-v230.pdf, with annotation in colors):

ONVIFプロトコルの実装方法を教えてくれないか？

実装例として詳細なXMLダイアログを提供できますか？

Event Templateとは何で、なぜそれが必要なのですか？

どのONVIF仕様書が参照されていますか？

実装のヒントをどのように扱うべきか？

利用規約

XML namespaces

Legends

If I'm going to use Genius Vision NVR to verify my camera, what basic knowledge should I have for this software?

What is the "Channel" parameter of the NVR software

ONVIFのカメラ接続初期化プロトコル系列とは何ですか？

Calling sequence

Mandatory commands summary

Optional commands summary

デュアルストリーミングの実装方法は

VideoEncoderOptions（解像度、コーデック、フレームレートなど）の設定を実装する方法は

ImagingOptionsの設定（明るさ、彩度など）の実装方法は

PTZの実装方法は

Calling sequence

ONVIF仕様書によってイベント通知をサポートする方法は

Genius Vision NVRはbasic notification（ONVIF基本的な通知）をサポートしていますか

ONVIFプルポイントスタイルのイベント通知（ET01）を実装する方法は

Calling sequence

MotionAlarm（動き検出）イベント（ET01）の実装方法は

Calling sequence

Event definition

Message XML example

ONVIFの文脈でイベントのプロパティとは何ですか？SetSynchronizationPointとは何ですか？ これはどのように実装されるべきですか？

Introduction of Property in spec

Property operations

What is a Synchronization Point

Does the NVC (client) need to send SetSynchronizationPoint explicitly

What does it really mean by Synchronization Point, I still don't understand

If NVC doesn't need to send SetSynchronizationPoint, then what's the point of having such a command

通知ストリーミングインターフェイスとは何ですか？

デジタル入力（ET01）の実装方法は

Calling sequence

Reflecting digital input state change

リレー出力（ET01）の実装方法は

Calling sequence

Reflecting relay state change

Changing relay state

InitialTerminationTimeの問題は何ですか？

Relevant spec hints

Status

Technical details

ONVIFの文脈でイベントのプロパティとは何ですか？SetSynchronizationPointとは何ですか？これはどのように実装されるべきですか？