Skip to content

Onvif Camera Device Service Specifications

This Onvif Camera Device Service is developed to control/communicate ONVIF-compliant cameras accessible via http in an EdgeX deployment

Table of Contents

Device ONVIF API Specifications

The latest version main of the device service API specifications can be found here.

ONVIF Device Service Protocol Properties

ONVIF Protocol

All properties in the Onvif protocol field are defined by internal device information and some user defined information.

Property Description EdgeX Value Type
Address The IP address of the camera. String
Port The internet port of the camera. String
EndpointRefAddress A GUID used to indentify the camera endpoint. String
DeviceStatus The discovery and authentication status of the camera. String
     UpWithAuth The device can execute commands requiring credentials.
     UpWithoutAuth The device can only execute commands that do not require credentials. Usually this means the camera's credentials have not been registered with the service yet, or have been changed.
     Reachable The device can be discovered but no commands can be received.
     Unreachable The device cannot be seen by service at all. Typically, this means that there is a connection issue either physically or with the network.
LastSeen The time that the device was last seen on the network. String
MACAddress The MAC address of the camera. String
FriendlyName The user defined name for the camera. String
Manufacturer The manufacturer of the camera. String
Model The model description of the camera. String
FirmwareVersion The firmware version of the camera. Format will vary by manufacturer and model. String
SerialNumber The serial number of the camera. String
HardwareId The hardware ID of the camera. String

Custom Metadata Protocol

All properties in the CustomMetadata protocol field are user defined. It can hold multiple different entries. For more information, see here

Property Description EdgeX Value Type
UserDefined User defined. String

ONVIF Features

The device service supports the onvif features listed in the following table:

Feature Onvif Web Service Onvif Function EdgeX Value Type
User Authentication Core WS-Usernametoken Authentication
HTTP Digest
Auto Discovery Core WS-Discovery
Device GetDiscoveryMode Object
SetDiscoveryMode Object
GetScopes Object
SetScopes Object
AddScopes Object
RemoveScopes Object
Network Configuration Device GetHostname Object
SetHostname Object
GetDNS Object
SetDNS Object
GetNetworkInterfaces Object
SetNetworkInterfaces Object
GetNetworkProtocols Object
SetNetworkProtocols Object
GetNetworkDefaultGateway Object
SetNetworkDefaultGateway Object
System Function Device GetDeviceInformation Object
GetSystemDateAndTime Object
SetSystemDateAndTime Object
SetSystemFactoryDefault Object
SystemReboot Object
User Handling Device GetUsers Object
CreateUsers Object
DeleteUsers Object
SetUser Object
Metadata Configuration Media GetMetadataConfiguration Object
GetMetadataConfigurations Object
GetCompatibleMetadataConfigurations Object
GetMetadataConfigurationOptions Object
AddMetadataConfiguration Object
RemoveMetadataConfiguration Object
SetMetadataConfiguration Object
Video Streaming Media GetProfiles Object
GetStreamUri Object
VideoEncoder Config Media GetVideoEncoderConfiguration Object
SetVideoEncoderConfiguration Object
GetVideoEncoderConfigurationOptions Object
PTZ Node PTZ GetNode Object
GetNodes Object
PTZ Configuration GetConfigurations Object
GetConfiguration Object
GetConfigurationOptions Object
SetConfiguration Object
Media AddPTZConfiguration Object
Media RemovePTZConfiguration Object
PTZ Actuation PTZ AbsoluteMove Object
RelativeMove Object
ContinuousMove Object
Stop Object
GetStatus Object
GetPresets Object
GotoPreset Object
RemovePreset Object
PTZ Home Position PTZ GotoHomePosition Object
SetHomePosition Object
PTZ Auxiliary Operations PTZ SendAuxiliaryCommand Object
Event Handling Event Notify Object
Subscribe Object
Renew Object
Unsubscribe Object
CreatePullPointSubscription Object
PullMessages Object
TopicFilter Object
MessageContentFilter Object
Analytics Profile Configuration Media2 GetProfiles Object
GetAnalyticsConfigurations Object
AddConfiguration Object
RemoveConfiguration Object
Analytics Module Configuration Analytics GetSupportedAnalyticsModules Object
GetAnalyticsModules Object
CreateAnalyticsModules Object
DeleteAnalyticsModules Object
GetAnalyticsModuleOptions Object
ModifyAnalyticsModules Object
Rule Configuration Analytics GetSupportedRules Object
GetRules Object
CreateRules Object
DeleteRules Object
GetRuleOptions Object
ModifyRule Object

Note

The functions in the bold text are mandatory for Onvif protocol.

Custom Features

The device service also include custom function to enhance the usage for the EdgeX user.

Feature Service Function EdgeX Value Type Description
System Function EdgeX RebootNeeded Bool Read only. Used to indicate the camera should reboot to apply the configuration change
System Function EdgeX CameraEvent Bool A device resource which is used to send the async event to north bound
System Function EdgeX SubscribeCameraEvent Bool Create a subscription to subscribe the event from the camera
System Function EdgeX UnsubscribeCameraEvent Bool Unsubscribe all subscription from the camera
Media EdgeX GetSnapshot Binary Get Snapshot from the snapshot uri
Custom Metadata EdgeX CustomMetadata Object Read and write custom metadata to the camera entry in EdgeX
Custom Metadata EdgeX DeleteCustomMetadata Object Delete custom metadata fields from the camera entry in EdgeX

How does the device service work?

The Onvif camera uses Web Services standards such as XML, SOAP 1.2 and WSDL1.1 over an IP network. - XML is used as the data description syntax - SOAP is used for message transfer - and WSDL is used for describing the services.

The spec can refer to ONVIF-Core-Specification.

For example, we can send a SOAP request to the Onvif camera as below: 

curl --request POST 'http://192.168.12.128:2020/onvif/service' \
--header 'Content-Type: application/soap+xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<soap-env:Envelope xmlns:soap-env="http://www.w3.org/2003/05/soap-envelope" xmlns:soap-enc="http://www.w3.org/2003/05/soap-encoding" xmlns:tan="http://www.onvif.org/ver20/analytics/wsdl" xmlns:onvif="http://www.onvif.org/ver10/schema" xmlns:trt="http://www.onvif.org/ver10/media/wsdl" xmlns:timg="http://www.onvif.org/ver20/imaging/wsdl" xmlns:tds="http://www.onvif.org/ver10/device/wsdl" xmlns:tev="http://www.onvif.org/ver10/events/wsdl" xmlns:tptz="http://www.onvif.org/ver20/ptz/wsdl" >
    <soap-env:Header>
        <Security xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <UsernameToken>
                <Username>myUsername</Username>
                <Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">+HKcvc+LCGClVwuros1sJuXepQY=</Password>
                <Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">w490bn6rlib33d5rb8t6ulnqlmz9h43m</Nonce>
                <Created xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2021-10-21T03:43:21.02075Z</Created>
            </UsernameToken>
        </Security>
    </soap-env:Header>
    <soap-env:Body>
        <trt:GetStreamUri>
            <trt:ProfileToken>profile_1</trt:ProfileToken>
        </trt:GetStreamUri>
    </soap-env:Body>
  </soap-env:Envelope>'
And the response should be like the following XML data: 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope" xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
    xmlns:wsdd="http://schemas.xmlsoap.org/ws/2005/04/discovery" xmlns:chan="http://schemas.microsoft.com/ws/2005/02/duplex"
    xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:xmime="http://tempuri.org/xmime.xsd" xmlns:xop="http://www.w3.org/2004/08/xop/include" xmlns:wsrfbf="http://docs.oasis-open.org/wsrf/bf-2"
    xmlns:wstop="http://docs.oasis-open.org/wsn/t-1" xmlns:wsrfr="http://docs.oasis-open.org/wsrf/r-2" xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:tt="http://www.onvif.org/ver10/schema" xmlns:ter="http://www.onvif.org/ver10/error" xmlns:tns1="http://www.onvif.org/ver10/topics"
    xmlns:tds="http://www.onvif.org/ver10/device/wsdl" xmlns:trt="http://www.onvif.org/ver10/media/wsdl"
    xmlns:tev="http://www.onvif.org/ver10/events/wsdl" xmlns:tdn="http://www.onvif.org/ver10/network/wsdl" xmlns:timg="http://www.onvif.org/ver20/imaging/wsdl"
    xmlns:trp="http://www.onvif.org/ver10/replay/wsdl" xmlns:tan="http://www.onvif.org/ver20/analytics/wsdl" xmlns:tptz="http://www.onvif.org/ver20/ptz/wsdl">
    <SOAP-ENV:Header></SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <trt:GetStreamUriResponse>
            <trt:MediaUri>
                <tt:Uri>rtsp://192.168.12.128:554/stream1</tt:Uri>
                <tt:InvalidAfterConnect>false</tt:InvalidAfterConnect>
                <tt:InvalidAfterReboot>false</tt:InvalidAfterReboot>
                <tt:Timeout>PT0H0M2S</tt:Timeout>
            </trt:MediaUri>
        </trt:GetStreamUriResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Since the SOAP message is an HTTP call, the device service can just do the transformation between REST(JSON) and SOAP(XML).

For the concept of implementation: - The device service accepts the REST request from the client, then transforms the request to SOAP format and forward it to the Onvif camera. - Once the device service receives the response from the Onvif camera, the device service will transform the SOAP response to REST format for the client. 

                  - Onvif Web Service

                  - Onvif Function  ┌────────────────────┐
                                    │                    │
┌──────────────┐  - Input Parameter │   Device Service   │               ┌─────────────────┐
│              │                    │                    │               │                 │
│              │ REST request       │                    │ SOAP request  │                 │
│    Client  ──┼────────────────────┼──►  Transform  ────┼───────────────┼──► Onvif Camera │
│              │                    │   to SOAP request  │               │                 │
│              │                    │                    │               │                 │
└──────────────┘                    └────────────────────┘               └─────────────────┘


                                    ┌────────────────────┐
                                    │                    │
┌──────────────┐                    │   Device Service   │               ┌─────────────────┐
│              │                    │                    │               │                 │
│              │ REST response      │                    │ SOAP response │                 │
│    Client  ◄─┼────────────────────┼───  Transform   ◄──┼───────────────┼── Onvif Camera  │
│              │                    │   to REST response │               │                 │
│              │                    │                    │               │                 │
└──────────────┘                    └────────────────────┘               └─────────────────┘

Warning

Both REST and SOAP commands over the network can be subject to attacks while in transit. Please take all necessary precautions to protect network traffic.

Tested Onvif Cameras

The following table shows the Onvif functions tested for various Onvif cameras:

  • '✔' means the function works for the specified camera.
  • '❌' means the function does not work or is not implemented by the specified camera.
  • 'ⓘ' means there is additional details available. Click it to read more.
  • Empty cells means the function has not yet been tested.

Camera Documentation

Use these links to access maufacturer documentation

User Authentication

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Core WS-UsernameToken ✔ ✔ ✔ ✔ ✔
HTTP Digest ✔ ❌ ✔ ❌ ❌

Capabilities

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Device GetCapabilities ✔ ❌
GetServiceCapabilities ✔ ❌
Media GetServiceCapabilities ✔ ✔
PTZ GetServiceCapabilities ✔ ✔
Imaging GetServiceCapabilities ❌ ✔
Event GetServiceCapabilities ✔ ✔

Auto Discovery

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Core WS-Discovery ✔ ✔ ✔ ✔ ✔
Device GetDiscoveryMode ✔ ✔ ✔ ✔ ✔
SetDiscoveryMode ✔ ✔ ✔ ✔ ✔
GetScopes ✔ ✔ ✔ ✔ ✔
SetScopes ✔ ✔ ✔ ✔ ❌
AddScopes ✔ ❌ ✔ ✔ ✔
RemoveScopes ✔ ❌ ✔ ✔ ✔
GetEndpointReference ❌ ✔ ❌

Network Configuration

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Device GetHostname ✔ ✔ ✔ ✔ ✔
SetHostname ✔ ❌ ✔ ✔ ✔
GetDNS ✔ ❌ ✔ ✔ ✔
SetDNS ✔ ❌ ✔ ✔ ✔
GetNetworkInterfaces ✔ ✔ ✔ ✔ ✔
SetNetworkInterfaces ✔ ❌ ✔ ✔ ❌
GetNetworkProtocols ✔ ✔ ✔ ✔ ✔
SetNetworkProtocols ✔ ❌ ✔ ✔ ✔
GetNetworkDefaultGateway ✔ ❌ ✔ ✔ ✔
SetNetworkDefaultGateway ✔ ❌ ✔ ✔ ✔

System Function

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Device GetDeviceInformation ✔ ✔ ✔ ✔ ✔
GetSystemDateAndTime ✔ ✔ ✔ ✔ ✔
SetSystemDateAndTime ✔ ✔ ⓘ ✔ ✔ ✔
SetSystemFactoryDefault ✔ ✔ ✔ ✔ ✔
SystemReboot ✔ ✔ ✔ ✔ ✔

User Handling

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Device GetUsers ✔ ❌ ⓘ ✔ ✔ ✔
CreateUsers ✔ ❌ ⓘ ✔ ✔ ✔
DeleteUsers ✔ ❌ ⓘ ✔ ✔ ✔
SetUser ✔ ❌ ⓘ ✔ ✔ ✔

Metadata Configuration

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Media GetMetadataConfigurations ✔ ❌ ✔ ✔ ✔
GetMetadataConfiguration ✔ ❌ ✔ ✔ ✔
GetCompatibleMetadataConfigurations ✔ ❌ ✔ ✔ ✔
GetMetadataConfigurationOptions ✔ ❌ ✔ ✔ ✔
AddMetadataConfiguration ✔ ❌ ✔ ✔ ✔
RemoveMetadataConfiguration ✔ ❌ ✔ ✔ ✔
SetMetadataConfiguration ✔ ❌ ✔ ✔ ✔

Video Streaming

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Media GetProfiles ✔ ✔ ✔ ✔ ✔
GetStreamUri ✔ ✔ ✔ ✔ ✔

VideoEncoder Config

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Media GetVideoEncoderConfigurations
GetVideoEncoderConfiguration ✔ ✔ ✔ ✔ ✔
SetVideoEncoderConfiguration ✔ ❌ ✔ ✔ ✔
GetVideoEncoderConfigurationOptions ✔ ✔ ✔ ✔ ✔

PTZ Node

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
PTZ GetNodes ❌ ✔ ❌ ❌ ✔
GetNode ❌ ✔ ❌ ❌ ✔

PTZ Configuration

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
PTZ GetConfigurations ❌ ✔ ❌ ❌ ✔
GetConfiguration ❌ ✔ ❌ ❌ ✔
GetConfigurationOptions ❌ ✔ ❌ ❌ ✔
SetConfiguration ❌ ❌ ❌ ❌ ✔
Media AddPTZConfiguration ❌ ❌ ❌ ❌ ✔
Media RemovePTZConfiguration ❌ ❌ ❌ ❌ ✔

PTZ Actuation

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
PTZ AbsoluteMove ❌ ✔ ❌ ❌ ✔
RelativeMove ❌ ✔ ❌ ❌ ✔
ContinuousMove ❌ ✔ ❌ ❌ ✔
Stop ❌ ✔ ❌ ❌ ✔
GetStatus ❌ ✔ ❌ ❌ ✔

PTZ Preset

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
PTZ SetPreset ❌ ✔ ❌ ❌ ✔
GetPresets ❌ ✔ ❌ ❌ ✔
GotoPreset ❌ ✔ ❌ ❌ ✔
RemovePreset ❌ ✔ ❌ ❌ ✔

PTZ Home Position

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
PTZ GotoHomePosition ❌ ❌ ❌ ❌ ✔
SetHomePosition ❌ ❌ ❌ ❌ ✔

PTZ Auxiliary Operations

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
PTZ SendAuxiliaryCommand ❌ ❌ ❌ ❌ ❌

Event Handling

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Event Notify ✔ ❌ ✔ ❌
Subscribe ✔ ❌ ✔ ❌
Renew ❌ ❌ ✔ ❌
Unsubscribe ✔ ❌ ✔ ❌
CreatePullPointSubscription ✔ ❌ ✔ ❌
PullMessages ✔ ❌ ✔ ❌
TopicFilter ✔ ❌ ✔ ❌
MessageContentFilter ❌ ❌ ❌ ❌
GetEventProperties ✔

Analytics Profile Configuration

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Media2 GetProfiles ❌ ❌ ✔ ❌ ✔
GetAnalyticsConfigurations ❌ ❌ ✔ ❌ ✔
AddConfiguration ❌ ❌ ✔ ❌ ❌
RemoveConfiguration ❌ ❌ ✔ ❌ ❌

Analytics Module Configuration

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Analytics GetSupportedAnalyticsModules ❌ ❌ ✔ ❌ ❌
GetAnalyticsModules ❌ ❌ ✔ ❌ ❌
CreateAnalyticsModules ❌ ❌ ❌ ❌ ❌
DeleteAnalyticsModules ❌ ❌ ❌ ❌ ❌
GetAnalyticsModuleOptions ❌ ❌ ✔ ❌ ❌
ModifyAnalyticsModules ❌ ❌ ✔ ❌ ❌

Rule Configuration

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
Analytics GetSupportedRules ❌ ❌ ✔ ❌ ❌
GetRules ❌ ❌ ✔ ❌ ❌
CreateRules ❌ ❌ ✔ ❌ ❌
DeleteRules ❌ ❌ ✔ ❌ ❌
GetRuleOptions ❌ ❌ ✔ ❌ ❌
ModifyRules ❌ ❌ ✔ ❌ ❌

Custom EdgeX

Onvif Web Service Onvif Function Hikvision DFI6256TE Tapo C200 BOSCH DINION IP starlight 6000 HD GeoVision GV-BX8700 Hikvision DS-2DE2A404IW-DE3
EdgeX GetSnapshot ✔ ❌ ✔ ⓘ ❌ ✔