1 總覽
ONVIF設備管理標準分爲如下子標準,其中前5個是ONVIF設備必須實現的,後面2個是可選操作
Capabilities |
ONVIF設備能力集相關API |
Network |
網絡相關API |
System |
系統配置相關API |
Security |
安全相關API |
Input/Output(I/O) |
|
Auxiliary operation |
|
Storage Configuration |
|
2 Capabilities API
2.1 wsdl獲取API
GetWsdlUrl # 獲取設計wsdl, API不開放權限給用戶
2.2 Capabilities exchange API
一系列獲取設備能力的API
GetServices #獲取dev支持的服務,可附加服務能力集+設備能力集
例子:如下報文描述了設備若干能力集,可以包括tds作用域下的能力也包括其他作用域能力集
|
||||||||||||
GetServiceCapabilities #獲取網絡服務能力集,注:必須實現,若實現GetServices
|
||||||||||||
GetCapabilities # 獲取設備能力集,注:必須實現,若實現GetServices
|
3 Network API
GetHostname #返回主機域名,注:域名可以是從DHCP獲取的 |
SetHostname #設置主機域名,注:主機域名可以從DHCP獲取,若設備具有HostnameFromDHCP能力,此時只需要提交空的 Name 字段 |
SetHostnameFromDHCP #設置設備是否從DHCP獲取域名功能 |
GetDNS #獲取DNS設置,獲取包括DHCP開關、搜索域(不明)、DHCP獲取的DNS服務IP列表(要求DHCP開關必須開啓)、手動DNS服務IP列表 |
SetDNS #設置DNS,包括開啓DHCP開關、設置搜索域、手動設置DNS服務。錯誤碼(忽略常規錯誤碼):sender(指收到錯誤碼的位請求發送方)-無效參數-IP地址無效(應該是指手動配置的DNS服務IP無效) |
GetNTP #獲取NTP(網絡時間協議) 配置,獲取包括NTP服務IP的DHCP開關、DHCP NTP IP列表、手動NTP IP列表 |
SetNTP #配置NTP,包括DHCP開關、手動NTP服務IP列表,錯誤碼:sender-無效參數-設備的當前時間格式要求配置NTP服務 |
GetDynamicDNS #獲取動態DNS配置(要求Dev支持DynDNS能力),包括更新規則、DNS名(當DNS主動更新)、DNS保活時間(當DNS主動更新,原理類似UDP P2P保活) |
SetDynamicDNS #設置上述屬性,要求設備支持 [RFC 2136] and [RFC 4702]標準,即DynDNS能力 |
GetNetworkInterfaces #獲取API屬性(比如API是否啓用、連接設置、MTU分包策略、IPv4/IPv6設置)列表,參考:tt:NetworkInterfaceInfo |
SetNetworkInterfaces #配置設備支持的API屬性,配置成功後,如果返回屬性RebootNeeded爲true,則表明配置需要重啓設備後生效(比如IP地址),這時候需要向設備發送SystemReboot請求;若屬性爲false,則表明配置立即生效。 |
GetNetworkProtocols #獲取應用層網絡協議(ONVIF18.12支持HTTP\HTTPS\RTP) |
SetNetworkProtocols #配置應用層協議,與上述協議成對 |
GetNetworkDefaultGateway #返回手動配置的默認網關IP |
SetNetworkDefaultGateway #設置默認網關 |
GetZeroConfiguration #從設備獲取zero-configuration(設備自動配置)相關參數,設備如果支持RFC3927標準, 請求返回 IPv4 zero configuration address 和 status(應該指 InterfaceToken 字段) 參考:[RFC3927]簡介 |
SetZeroConfiguration #配置設備zero-configuration相關參數,要求設備支持RFC3927標準,且支持ZeroConfiguration 能力 |
GetIPAddressFilter #獲取設備IP過濾規則(要求設置支持 IPFilter 能力) |
AddIPAddressFilter #增加設備IP過濾規則,禁止那些IP訪問、允許那些IP訪問 |
RemoveIPAddressFilter #刪除設備IP過濾規則 |
IEEE 802.11 configuration #IEEE 802.11系列配置項(要求設備支持IEEE 802.11標準(wifi)具有Dot11Configuration 能力) ONVIF要求能夠對設備進行如下配置:(具體方式ONVIF不做限制)
GetDot11Capabilities #獲取設備支持的Dot11能力,IEEE 802.11定義了TKIP、ScanAvailableNetworks 、MultipleConfiguration 、AdHocStationMode 、WEP 5種能力 GetDot11Status #獲取無線網狀態,如下 ScanAvailableDot11Networks #掃描可用Dot11局域網,就是手機wifi網絡掃描功能 |
4 System API
GetDeviceInformation #獲取設備的製造商、軟件模型、固件版本、序列號、硬件id |
GetSystemUris #獲取從Dev提取日誌、診斷信息、系統備份信息的url |
GetSystemBackup #從Dev獲取系統備份(要求Dev具備SystemBackup能力,API已被棄用 ,替代API參考GetSystemUris 和 StartSystemRestore)系統備份可以用於回覆設備的配置,注恢復設備的IP配置可能不同。 系統備份文件的傳輸協議 爲[MTOM] |
RestoreSystem #恢復系統備份(要求Dev具備SystemBackup能力,API已被棄用,替代API參考GetSystemUris 和 StartSystemRestore) 系統備份文件的傳輸協議 爲[MTOM] |
StartSystemRestore #恢復系統備份,Dev返回上傳備份數據的URL及上傳有效時間(避免客戶端惡意佔用上傳網絡資源) 上傳並恢復備份步驟:
|
GetSystemDateAndTime #獲取系統時間,會表明時間來自手動設置或NTP(此時要求SetNTP、GetNTP有效)、夏至時開關、時區、UTC時間、Dev本地時間。注:雖然UTC時間格式爲可選但是爲了向後兼容,設備shall提供UTC時間。 |
SetSystemDateAndTime #設置系統時間,GetSystemDateAndTime成對 |
SetSystemFactoryDefault #恢復出廠設置,設備必須支持軟、硬件初上設置。注:ONVIF對軟件出廠設置未做定義,要是要求設備軟出廠恢復後之前的IP仍能可達。這表明軟出廠恢復時要求網絡設置:IP地址、子網及網關設置、DHCP設置被保持。防止操作後設備丟失! |
UpgradeSystemFirmware #固件升級(API已遺棄),升級包通過MTOM協議傳輸,同樣要求網絡設置:IP地址、子網及網關設置、DHCP設置被保持 |
StartFirmwareUpgrade #固件升級,具體的固件數據格式ONVIF不做定義,若上傳的固件數據無效,Dev返回Http狀態碼"415 Unsupported Media Type",若升級失敗適應爲Dev故障則返回Http狀態碼"500 Internal Server Error"。POST數據時,Content-Type字段要求"application/octet stream"。同樣要求升級後網絡配置不變。 上傳文件及升級操作步驟:
|
GetSystemLog #獲取日誌(可選系統日誌、客戶端訪問日誌),傳輸遵守[MTOM],具體日誌格式ONVIF不做規定。獲取日誌的url從GetSystemUris 取得 |
GetSystemSupportInformation #獲取系統診斷信息,設備可選傳回二進制數據或文本數據,傳輸遵守[MTOM],具體日誌格式ONVIF不做規定。獲取日誌的url從GetSystemUris 取得 |
SystemReboot #設備重啓 |
GetScopes #獲取scope相關參數(scope用於匹配設備發現probe message),返回固定scope和可配置scope |
SetScopes #重置可配scope,注:會覆蓋現有的所有可配scope!,支持多個scope,用列表下標作爲索引號 |
AddScopes #爲已有可配scope增加scope url參數,用列表下標作爲scope索引 |
RemoveScopes #爲已有可配scope刪除scope url參數,用列表下標作爲scope索引 |
GetDiscoveryMode #獲取設備發現模式(可發現、不可發現) |
SetDiscoveryMode #設置設備發現模式 |
GetGeoLocation #獲取地理信息,(要求設備支持 GeoLocationEntities 能力,若設備支持AutoGeo能力AutoGeo條目有效) 地理信息條目包括(設備不一定要支持全部地理信息條目):
|
SetGeoLocation #改變地理信息條目配置,成功設置後,會影響GetGeoLocation 返回信息 |
DeleteGeoLocation #刪除地理信息條目,刪除後GetGeoLocation 不再顯示 |
5 Security API
GetAccessPolicy #獲取設備訪問規則(二進制數據),包括用戶級別、服務訪問權限信息,若設備支持 SetAccessPolicy ,則必須實現本API。 |
SetAccessPolicy #設置訪問規則 |
GetUsers #獲取用戶信息列表(不包含證據或密碼) |
CreateUsers #新建用戶,需要輸入用戶名、密碼、用戶級別 |
DeleteUsers #刪除用戶,根據用戶名 |
SetUser #改變用戶設置,(用戶名不能變,密碼、級別可以變),重置密碼時如果密碼太簡單設備返回ter:PasswordTooWeak錯誤碼 |
GetRemoteUser #獲取遠程用戶(遠程用戶是什麼用戶?和普通用戶有什麼區別?)列表,(要求設備支持RemoteUserHandling 能力) |
SetRemoteUser #設置遠程用戶(The user is only valid for the WS-UserToken profile or as a HTTP / RTSP user) |
GetEndpointReference #獲取設備服務端引用屬性(服務的GUID),從文檔中描述看,這個GUID可以用於計算遠程用戶操作的密碼。 |
6 I/O API
本節I/O相關的接口,主要用於保證後端兼容性。控制、獲取IO端口的狀態。更廣泛的IO接口參考ONVIF Device IO Specification。
GetRelayOutputs #獲取可用relay(什麼是relay輸出?可能是類似NVR通道的概念)輸出列表 |
SetRelayOutputSettings #設置relay輸出 |
7 輔助外設
SendAuxiliaryCommand #發送設備輔助外設控制指令,比如控制紅外線照明燈、加熱器、雨刮器、溫度計等 請求報文類型tt:AuxiliaryData實際是一個xsd字符串,onvif不規定指令的風格,但必須複合格式"tt:command|parameter",如:
|
8 存儲配置
以下接口允許客戶端對設備數據存儲進行設置,可以參考 DAS, NAS, 和CDMI Server的存儲配置。要求設備具有Storage Configuration能力
GetStorageConfigurations #獲取所有存儲配置項(不太明白這個存儲配置指什麼?) |
CreateStorageConfiguration #新建存儲配置 |
GetStorageConfiguration #通過tt:ReferenceTokentt:ReferenceToken獲取存儲配置 |
SetStorageConfiguration #重置已有的配置 |
DeleteStorageConfiguration #刪除配置 |
9 設備監控事件
設備主動上報運行狀態的事件
tns1:Monitoring/ProcessorUsage // 上報設備處理器實時信息,Source應該是用來描述Data是什麼 |
tns1:Monitoring/LinkStatus //上報設備的連接狀態 |
tns1:Monitoring/UploadStatus // 當設備正在升級固件或系統時,上報升級狀態,進度 |
注:設備上報時時間格式複合UTC的格林尼治標準 tns1:Monitoring/OperatingTime/DefinedLimitReached // 到達操作時限時上報 tns1:Monitoring/OperatingTime/MeanTimeBetweenFailuresDefaultLimitReached //MTBF(平均故障間隔時間)時限時上報,設備故障狀態,用於計算設備無故障運行時間 tns1:Monitoring/OperatingTime/LastReset //恢復出廠前上報 tns1:Monitoring/OperatingTime/LastReboot //reboot前上報 tns1:Monitoring/OperatingTime/LastClockSynchronization //時鐘同步後上報,由 NTP message或SetSystemDateAndTime call引發 tns1:Monitoring/Maintenance/Last //設備上報最後保持激活狀態的時間(設備之後應該是休眠) tns1:Monitoring/Maintenance/NextScheduled //上報下次激活的時間 tns1:Monitoring/Backup/Last //設備恢復備份後上報 tns1:Monitoring/AreaOfOperation/OutsideCertifiedArea //當設備被認證爲不因爲外界原因而鬆動時上報(沒明白啥意思) tns1:Monitoring/AreaOfOperation/OutsideConfiguredArea //當設備被配置爲不因爲外界原因而鬆動時上報 |
tns1:Monitoring/EnvironmentalConditions/RelativeHumidity //上報溼度信息,要求設備支持環境監測能力 tns1:Monitoring/EnvironmentalConditions/Temperature //上報溫度信息,上報策略可以是6s/次或溫差大於5%時,防止引發“事件洪水” |
tns1:Monitoring/BatteryCapacity //上報剩餘電池量,recommended to use a 2% change |
tns1:Monitoring/AsynchronousOperationStatus //上報異步操作的進度。Token 字段用標識異步操作,區分同一類型一步操作的不同會話; OperationName 操作名; ServiceName 異步操作的服務名;OperationName 和ServiceName 可用於區別不同的異步操作; Progress 字段展示操作執行進度[0.0, 1.0]; Error 字段展示操作錯誤,錯誤碼標準要求符合soapenv:Fault |
tns1:Device/OperationMode/ShutdownInitiated //關機前發送 tns1:Device/OperationMode/UploadInitiated //升級開始前發送 |
tns1:Monitoring/Washer/LiquidLow //上報水箱液體等級 |
tns1:Device/HardwareFailure/FanFailure //散熱風扇故障 tns1:Device/HardwareFailure/PowerSupplyFailure //供電故障 tns1:Device/HardwareFailure/StorageFailure //存儲設備故障 tns1:Device/HardwareFailure/TemperatureCritical //設備溫度過載報警 |
tns1:Monitoring/GeoLocation //上報地理位置(針對便攜式設備) |
10 事件通知
"設備事件"是設備的主動活動或者檢測到有事發生時產生,當客戶端定於某種類型的事件後,當事件產生時設備以某種形式推送消息給客戶端。事件的處理,在[WS-BaseNotification]和[WS-Topics] 規範基礎上擴展
事件訂閱/通知方式:
10.1 Pull-Point Notification(拉模式通知)
從時序圖可以看出,事件通知並不是設備主動上報而是需要客戶端發送PullMessages拉取。這種方式無需在客戶端和設備間維護鏈路,但要求客戶端能夠主動連接設備,當設備IP不固定的時候(比如Iot場景下),拉模式通知往往需要在設備主動建立交互之後才能進行,這導致這種場景下通知不夠實時
<1> client通過CreatePullPointSubscriptionRequest向device申請PullPointSubscription(拉訂閱點)。這個request包含了此訂閱的詳細描述信息。並且與the Basic Notification Interface不同之處就是此處需要省略consumerReference。
<2>當subscribe被接受的時候device評估此訂閱後返回CreatePullPointSubscriptionResponse 或者返回一個錯誤代碼。
<3>訂閱被接受後,反饋的response需要包含SubscriptionManager的WS-EndpointReference. WS-Endpoint必須提供PullMessage操作,Pullmessage用於客戶端檢索通知信息,以及由訂閱管理manager接口去描述WS-BaseeNotification。Base Subscription Manager 接口包含PullMessage,Renew,Unsubscribe 等操作。交互序列如上圖。PullMessage包含Timeout以及MessageLimit 參數
<4>一旦有來自client的查詢通知則device必須立即響應,如果沒有則device一直保持等待client所訂閱的通知到來或者等待超時發生。一般情況下至少包括response,且通知個數是被指定的。client在發出的一個PullMessagesRequest並收到PullMessagesResponse後既可以實時輪詢通知接口(類似於一問一答式的服務)
<5>如果在CreatePullPointSubscriptionRequest中未指定結束或者相關結束時間,則每個PullMessagesRequest理解爲保持激活狀態等待相應的PullPointSubscription.並且結束時間會根據相關聯的結束時間或者裝置內置數值進行再計算。爲了通知client去更新結束時PullMessageResponse必須包含CurrentTime以及terminalTime選項。當PullMessagesRequest處於激活狀態並等待相應的PullPointSubscription,此時由WS-BaseNotification定義的RenewRequest不能被Client,因此device需要支持PullPointSubscription。(在沒有訂閱的前提下發送PullMessagesRequest,需要等待PullPointSubscription去創建訂閱完成才能繼續運行)
<6>如果device支持通知持續保存,則WS-Endpoint必須支持Seek操作,其支持將pull指針重新拉回原位置。爲防止將指針的放置位置超出了buffer的起始位置,第一次調用PullMessage要從buffer的起始位置開始。(9.12.9)SeekRequest包含了UtcTime參數,UtcTime參數必須NotificationMessage中的屬性相匹配。當使用seek,則pull指針要放置在包含NotificationMessage的且其UtcTime少於等於seek參數的buffer中。SeekRequest包含一個可選的對立參數,這個參數可以將PullMessageResquest的pull方向反向。
接口:
CreatePullPointSubscription //創建訂閱,請求中可以指定要訂閱的事件類型,訂閱持續事件 |
PullMessages //拉取事件 |
Renew //要求設備支持MaxNotificationProducers能力,可能是重置訂閱,具體用法不清楚 |
Unsubscribe //取消所有訂閱 |
Seek //如果設備支持時間存儲,則應該支持事件檢索 |
10.2 Basic Notification(WS-BaseNotification通知)
從時序圖即可看出,這種消息通知方式,是設備主動的,要求設備能夠主動連接設備。或者TCP長連接,或者通過UDP鏈路保活,或者client IP固定。