Device

Device (Core) service implementation.

`Device`

Bases: ONVIFService

Device service client.

Property	Details
First introduced	ONVIF Core
Binding name	`DeviceBinding` (`ver10/device/wsdl/devicemgmt.wsdl`)
Operations	devicemgmt.wsdl
Specification	Core.xml

`GetServiceCapabilities()`

Returns the capabilities of the device service.

The result is returned in a typed answer.

`GetCapabilities(Category=None)`

This method has been replaced by the more generic GetServices method.

For capabilities of individual services refer to the GetServiceCapabilities methods.

`GetServices(IncludeCapability)`

Returns information about services on the device.

`GetDeviceInformation()`

This operation gets basic device information from the device.

`SendAuxiliaryCommand(AuxiliaryCommand)`

Manage auxiliary commands supported by a device, such as controlling an Infrared (IR) lamp, a heater or a wiper or a thermometer that is connected to the device.

The supported commands can be retrieved via the AuxiliaryCommands capability.

Although the name of the auxiliary commands can be freely defined, commands starting with the prefix tt: are reserved to define frequently used commands and these reserved commands shall all share the "tt:command|parameter" syntax.

tt:Wiper|On - Request to start the wiper.
tt:Wiper|Off - Request to stop the wiper.
tt:Washer|On - Request to start the washer.
tt:Washer|Off - Request to stop the washer.
tt:WashingProcedure|On - Request to start the washing procedure.
tt: WashingProcedure |Off - Request to stop the washing procedure.
tt:IRLamp|On - Request to turn ON an IR illuminator attached to the unit.
tt:IRLamp|Off - Request to turn OFF an IR illuminator attached to the unit.
tt:IRLamp|Auto - Request to configure an IR illuminator attached to the unit so that it automatically turns ON and OFF.

A device that indicates auxiliary service capability shall support this command.

`SetSystemDateAndTime(DateTimeType, DaylightSavings, TimeZone=None, UTCDateTime=None)`

This operation sets the device system date and time.

The device shall support the configuration of the daylight saving setting and of the manual system date and time (if applicable) or indication of NTP time (if applicable) through the SetSystemDateAndTime command.

If system time and date are set manually, the client shall include UTCDateTime in the request.

A TimeZone token which is not formed according to the rules of IEEE 1003.1 section 8.3 is considered as invalid timezone.

The DayLightSavings flag should be set to true to activate any DST settings of the TimeZone string. Clear the DayLightSavings flag if the DST portion of the TimeZone settings should be ignored.

`GetSystemDateAndTime()`

This operation gets the device system date and time.

The device shall support the return of the daylight saving setting and of the manual system date and time (if applicable) or indication of NTP time (if applicable) through the GetSystemDateAndTime command.

A device shall provide the UTCDateTime information.

`SetSystemFactoryDefault(FactoryDefault)`

This operation reloads the parameters on the device to their factory default values.

`UpgradeSystemFirmware(Firmware)`

This operation upgrades a device firmware version.

After a successful upgrade the response message is sent before the device reboots. The device should support firmware upgrade through the UpgradeSystemFirmware command. The exact format of the firmware data is outside the scope of this standard.

`SystemReboot()`

This operation reboots the device.

`RestoreSystem(BackupFiles)`

This operation restores the system backup configuration files(s) previously retrieved from a device.

The device should support restore of backup configuration file(s) through the RestoreSystem command. The exact format of the backup configuration file(s) is outside the scope of this standard. If the command is supported, it shall accept backup files returned by the GetSystemBackup command.

`GetSystemBackup()`

This operation is retrieves system backup configuration file(s) from a device.

The device should support return of back up configuration file(s) through the GetSystemBackup command. The backup is returned with reference to a name and mime-type together with binary data. The exact format of the backup configuration files is outside the scope of this standard.

`GetSystemLog(LogType)`

This operation gets a system log from the device.

The exact format of the system logs is outside the scope of this standard.

`GetSystemSupportInformation()`

This operation gets arbitary device diagnostics information from the device.

`GetScopes()`

This operation requests the scope parameters of a device.

The scope parameters are used in the device discovery to match a probe message, see Section 7.

The Scope parameters are of two different types:

Fixed
Configurable

Fixed scope parameters are permanent device characteristics and cannot be removed through the device management interface. The scope type is indicated in the scope list returned in the get scope parameters response. A device shall support retrieval of discovery scope parameters through the GetScopes command. As some scope parameters are mandatory, the device shall return a non-empty scope list in the response.

`SetScopes(Scopes)`

This operation sets the scope parameters of a device.

The scope parameters are used in the device discovery to match a probe message. This operation replaces all existing configurable scope parameters (not fixed parameters). If this shall be avoided, one should use the scope add command instead. The device shall support configuration of discovery scope parameters through the SetScopes command.

`AddScopes(ScopeItem)`

This operation adds new configurable scope parameters to a device.

The scope parameters are used in the device discovery to match a probe message. The device shall support addition of discovery scope parameters through the AddScopes command.

`RemoveScopes(ScopeItem)`

This operation deletes scope-configurable scope parameters from a device.

The scope parameters are used in the device discovery to match a probe message, see Section 7. The device shall support deletion of discovery scope parameters through the RemoveScopes command. Table

`GetDiscoveryMode()`

This operation gets the discovery mode of a device.

See Section 7.2 for the definition of the different device discovery modes. The device shall support retrieval of the discovery mode setting through the GetDiscoveryMode command.

`SetDiscoveryMode(DiscoveryMode)`

This operation sets the discovery mode operation of a device.

See Section 7.2 for the definition of the different device discovery modes. The device shall support configuration of the discovery mode setting through the SetDiscoveryMode command.

`GetRemoteDiscoveryMode()`

This operation gets the remote discovery mode of a device.

See Section 7.4 for the definition of remote discovery extensions. A device that supports remote discovery shall support retrieval of the remote discovery mode setting through the GetRemoteDiscoveryMode command.

`SetRemoteDiscoveryMode(RemoteDiscoveryMode)`

This operation sets the remote discovery mode of operation of a device.

See Section 7.4 for the definition of remote discovery remote extensions. A device that supports remote discovery shall support configuration of the discovery mode setting through the SetRemoteDiscoveryMode command.

`GetDPAddresses()`

This operation gets the remote DP address or addresses from a device.

If the device supports remote discovery, as specified in Section 7.4, the device shall support retrieval of the remote DP address(es) through the GetDPAddresses command.

`GetEndpointReference()`

A client can ask for the device service endpoint reference address property that can be used to derive the password equivalent for remote user operation.

The device shall support the GetEndpointReference command returning the address property of the device service endpoint reference.

`GetRemoteUser()`

This operation returns the configured remote user (if any).

A device supporting remote user handling shall support this operation. The user is only valid for the WS-UserToken profile or as an HTTP / RTSP user.

The algorithm to use for deriving the password is described in section 5.12.2.1 of the core specification.

`SetRemoteUser(RemoteUser=None)`

This operation sets the remote user.

A device supporting remote user handling shall support this operation. The user is only valid for the WS-UserToken profile or as an HTTP / RTSP user.

The password that is set shall always be the original (not derived) password.

If UseDerivedPassword is set password derivation shall be done by the device when connecting to a remote device.The algorithm to use for deriving the password is described in section 5.12.2.1 of the core specification.

To remove the remote user SetRemoteUser should be called without the RemoteUser parameter.

`GetUserRoles(UserRole=None)`

This operation returns the editable user levels configured in the device.

Whenever an editable user level is passed in the request, information only about that level is returned.

`SetUserRole(UserRole)`

This operation configures an editable user level in the device.

If the level passed in UserRole already exists in the device, its configuration is overwritten. Otherwise, a new editable user level is created.

`DeleteUserRole(UserRole)`

This operation deletes an editable user level in the device.

`GetUsers()`

This operation lists the registered users and corresponding credentials on a device.

The device shall support retrieval of registered device users and their credentials for the user token through the GetUsers command.

`CreateUsers(User)`

This operation creates new device users and corresponding credentials on a device for authentication purposes.

The device shall support creation of device users and their credentials through the CreateUsers command. Either all users are created successfully or a fault message shall be returned without creating any user.

ONVIF compliant devices are recommended to support password length of at least 28 bytes, as clients may follow the password derivation mechanism which results in 'password equivalent' of length 28 bytes, as described in section 3.1.2 of the ONVIF security white paper.

`DeleteUsers(Username)`

This operation deletes users on a device.

The device shall support deletion of device users and their credentials through the DeleteUsers command. A device may have one or more fixed users that cannot be deleted to ensure access to the unit. Either all users are deleted successfully or a fault message shall be returned and no users be deleted.

`SetUser(User)`

This operation updates the settings for one or several users on a device for authentication purposes.

The device shall support update of device users and their credentials through the SetUser command. Either all change requests are processed successfully or a fault message shall be returned and no change requests be processed.

`GetWsdlUrl()`

This method allows to provide a URL where product specific WSDL and schema definitions can be retrieved.

This method is deprecated.

`GetPasswordComplexityOptions()`

This method allows retrieval of all the available parameters and their valid ranges for the password complexity configuration.

`GetPasswordComplexityConfiguration()`

This method allows retrieval of the current password complexity configuration settings.

`SetPasswordComplexityConfiguration(MinLen=None, Uppercase=None, Number=None, SpecialChars=None, BlockUsernameOccurrence=None, PolicyConfigurationLocked=None)`

This method allows setting of the password complexity configuration.

`GetPasswordHistoryConfiguration()`

This method allows retrieval of the current password history configuration settings.

`SetPasswordHistoryConfiguration(Enabled, Length)`

This method allows setting of the password history configuration.

`GetAuthFailureWarningOptions()`

This method allows retrieval of all the available parameters and their valid ranges for the authentication failure warning configuration.

`GetAuthFailureWarningConfiguration()`

This method allows retrieval of the current authentication failure warning configuration settings.

`SetAuthFailureWarningConfiguration(Enabled, MonitorPeriod, MaxAuthFailures)`

This method allows setting of the authentication failure warning configuration.

`SetHashingAlgorithm(Algorithm)`

This operation sets the hashing algorithm(s) used in HTTP and RTSP Digest Authentication.

`SetDPAddresses(DPAddress=None)`

This operation sets the remote DP address or addresses on a device.

If the device supports remote discovery, as specified in Section 7.4, the device shall support configuration of the remote DP address(es) through the SetDPAddresses command.

`GetHostname()`

This operation is used by an endpoint to get the hostname from a device.

The device shall return its hostname configurations through the GetHostname command.

`SetHostname(Name)`

This operation sets the hostname on a device.

It shall be possible to set the device hostname configurations through the SetHostname command.

A device shall accept string formated according to RFC 1123 section 2.1 or alternatively to RFC 952, other string shall be considered as invalid strings.

`SetHostnameFromDHCP(FromDHCP)`

This operation controls whether the hostname is set manually or retrieved via DHCP.

`GetDNS()`

This operation gets the DNS settings from a device.

The device shall return its DNS configurations through the GetDNS command.

`SetDNS(FromDHCP, SearchDomain=None, DNSManual=None)`

This operation sets the DNS settings on a device.

It shall be possible to set the device DNS configurations through the SetDNS command.

`GetNTP()`

This operation gets the NTP settings from a device.

If the device supports NTP, it shall be possible to get the NTP server settings through the GetNTP command.

`SetNTP(FromDHCP, NTPManual=None)`

This operation sets the NTP settings on a device.

If the device supports NTP, it shall be possible to set the NTP server settings through the SetNTP command.

A device shall accept string formated according to RFC 1123 section 2.1 or alternatively to RFC 952, other string shall be considered as invalid strings.

Changes to the NTP server list will not affect the clock mode DateTimeType. Use SetSystemDateAndTime to activate NTP operation.

`GetDynamicDNS()`

This operation gets the dynamic DNS settings from a device.

If the device supports dynamic DNS as specified in [RFC 2136] and [RFC 4702], it shall be possible to get the type, name and TTL through the GetDynamicDNS command.

`SetDynamicDNS(Type, Name=None, TTL=None)`

This operation sets the dynamic DNS settings on a device.

If the device supports dynamic DNS as specified in [RFC 2136] and [RFC 4702], it shall be possible to set the type, name and TTL through the SetDynamicDNS command.

`GetNetworkInterfaces()`

This operation gets the network interface configuration from a device.

The device shall support return of network interface configuration settings as defined by the NetworkInterface type through the GetNetworkInterfaces command.

`SetNetworkInterfaces(InterfaceToken, NetworkInterface)`

This operation sets the network interface configuration on a device.

The device shall support network configuration of supported network interfaces through the SetNetworkInterfaces command.

For interoperability with a client unaware of the IEEE 802.11 extension a device shall retain its IEEE 802.11 configuration if the IEEE 802.11 configuration element isn't present in the request.

`GetNetworkProtocols()`

This operation gets defined network protocols from a device.

The device shall support the GetNetworkProtocols command returning configured network protocols.

`SetNetworkProtocols(NetworkProtocols)`

This operation configures defined network protocols on a device.

The device shall support configuration of defined network protocols through the SetNetworkProtocols command.

`GetNetworkDefaultGateway()`

This operation gets the default gateway settings from a device.

The device shall support the GetNetworkDefaultGateway command returning configured default gateway address(es).

`SetNetworkDefaultGateway(IPv4Address=None, IPv6Address=None)`

This operation sets the default gateway settings on a device.

The device shall support configuration of default gateway through the SetNetworkDefaultGateway command.

`GetZeroConfiguration()`

This operation gets the zero-configuration from a device.

If the device supports dynamic IP configuration according to [RFC3927], it shall support the return of IPv4 zero configuration address and status through the GetZeroConfiguration command.

Devices supporting zero configuration on more than one interface shall use the extension to list the additional interface settings.

`SetZeroConfiguration(InterfaceToken, Enabled)`

This operation sets the zero-configuration.

Use GetCapabilities to get if zero-configuration is supported or not.

`GetIPAddressFilter()`

This operation gets the IP address filter settings from a device.

If the device supports device access control based on IP filtering rules (denied or accepted ranges of IP addresses), the device shall support the GetIPAddressFilter command.

`SetIPAddressFilter(IPAddressFilter)`

This operation sets the IP address filter settings on a device.

If the device supports device access control based on IP filtering rules (denied or accepted ranges of IP addresses), the device shall support configuration of IP filtering rules through the SetIPAddressFilter command.

`AddIPAddressFilter(IPAddressFilter)`

This operation adds an IP filter address to a device.

If the device supports device access control based on IP filtering rules (denied or accepted ranges of IP addresses), the device shall support adding of IP filtering addresses through the AddIPAddressFilter command.

`RemoveIPAddressFilter(IPAddressFilter)`

This operation deletes an IP filter address from a device.

If the device supports device access control based on IP filtering rules (denied or accepted ranges of IP addresses), the device shall support deletion of IP filtering addresses through the RemoveIPAddressFilter command.

`GetAccessPolicy()`

Access to different services and sub-sets of services should be subject to access control.

The WS-Security framework gives the prerequisite for end-point authentication. Authorization decisions can then be taken using an access security policy. This standard does not mandate any particular policy description format or security policy but this is up to the device manufacturer or system provider to choose policy and policy description format of choice. However, an access policy (in arbitrary format) can be requested using this command. If the device supports access policy settings based on WS-Security authentication, then the device shall support this command.

`SetAccessPolicy(PolicyFile)`

This command sets the device access security policy (for more details on the access security policy see the Get command).

If the device supports access policy settings based on WS- Security authentication, then the device shall support this command.

`CreateCertificate(CertificateID=None, Subject=None, ValidNotBefore=None, ValidNotAfter=None)`

This operation creates a new certificate on the device.

`GetCertificates()`

This operation gets the list of certificates on the device.

`GetCertificatesStatus()`

This operation gets the status of the certificates on the device.

`SetCertificatesStatus(CertificateStatus=None)`

This operation sets the status of the certificates on the device.

`DeleteCertificates(CertificateID)`

This operation deletes a certificate on the device.

`GetPkcs10Request(CertificateID, Subject=None, Attributes=None)`

This operation gets the PKCS#10 request for a certificate on the device.

`LoadCertificates(NVTCertificate)`

This operation loads certificates onto the device.

`GetClientCertificateMode()`

This operation gets the client certificate mode.

`SetClientCertificateMode(Enabled)`

This operation sets the client certificate mode.

`GetCACertificates()`

This operation gets the list of CA certificates on the device.

`LoadCertificateWithPrivateKey(CertificateWithPrivateKey)`

This operation loads a certificate with private key onto the device.

`GetCertificateInformation(CertificateID)`

This operation gets the information of a specific certificate.

`LoadCACertificates(CACertificate)`

This operation loads CA certificates onto the device.

`GetRelayOutputs()`

This operation gets a list of all available relay outputs and their settings.

This method has been deprecated with version 2.0. Refer to the DeviceIO service.

`SetRelayOutputSettings(RelayOutputToken, Properties)`

This operation sets the settings of a relay output.

This method has been deprecated with version 2.0. Refer to the DeviceIO service.

`SetRelayOutputState(RelayOutputToken, LogicalState)`

This operation sets the state of a relay output.

This method has been deprecated with version 2.0. Refer to the DeviceIO service.

`CreateDot1XConfiguration(Dot1XConfiguration)`

This operation creates a new 802.1X configuration on the device.

`SetDot1XConfiguration(Dot1XConfiguration)`

This operation sets the 802.1X configuration on the device.

`GetDot1XConfiguration(Dot1XConfigurationToken)`

This operation gets the 802.1X configuration from the device.

`GetDot1XConfigurations()`

This operation gets the list of 802.1X configurations from the device.

`DeleteDot1XConfiguration(Dot1XConfigurationToken=None)`

This operation deletes an 802.1X configuration from the device.

`GetDot11Capabilities()`

This operation returns the IEEE802.11 capabilities.

The device shall support this operation.

`GetDot11Status(InterfaceToken)`

This operation returns the status of a wireless network interface.

The device shall support this command.

`ScanAvailableDot11Networks(InterfaceToken)`

This operation returns a lists of the wireless networks in range of the device.

A device should support this operation.

`GetSystemUris()`

This operation is used to retrieve URIs from which system information may be downloaded using HTTP.

URIs may be returned for the following system information:

System Logs. Multiple system logs may be returned, of different types. The exact format of the system logs is outside the scope of this specification.

Support Information. This consists of arbitrary device diagnostics information from a device. The exact format of the diagnostic information is outside the scope of this specification.

System Backup. The received file is a backup file that can be used to restore the current device configuration at a later date. The exact format of the backup configuration file is outside the scope of this specification.

If the device allows retrieval of system logs, support information or system backup data, it should make them available via HTTP GET. If it does, it shall support the GetSystemUris command.

`StartFirmwareUpgrade()`

This operation initiates a firmware upgrade using the HTTP POST mechanism.

The response to the command includes an HTTP URL to which the upgrade file may be uploaded. The actual upgrade takes place as soon as the HTTP POST operation has completed. The device should support firmware upgrade through the StartFirmwareUpgrade command. The exact format of the firmware data is outside the scope of this specification. Firmware upgrade over HTTP may be achieved using the following steps:

Client calls StartFirmwareUpgrade.
Server responds with upload URI and optional delay value.
Client waits for delay duration if specified by server.
Client transmits the firmware image to the upload URI using HTTP POST.
Server reprograms itself using the uploaded image, then reboots.

If the firmware upgrade fails because the upgrade file was invalid, the HTTP POST response shall be "415 Unsupported Media Type". If the firmware upgrade fails due to an error at the device, the HTTP POST response shall be "500 Internal Server Error".

The value of the Content-Type header in the HTTP POST request shall be "application/octetstream".

`UpgradeFirmware(Version)`

This operation initiates a firmware upgrade using between the device and the MCS, without further actions from the client.

Cloud firmware upgrade may be achieved using the following steps:

Client retrieves the list of available firmware versions from the MCS.
Client calls UpgradeFirmware, selecting the desired FW version.
Device service responds with a downtime value.
Device and MCS perform the firmware upgrade procedure without further interaction from the Client.
Device notifies the Client of the result by emitting the appropriate CloudFirmwareUpgrade event

After applying a firmware upgrade the device shall keep the basic network configuration like IP address, subnet mask and gateway or DHCP settings, as well as all the parameters of the Uplink and Security service unchanged, so that it can connect to the cloud. Additionally a firmware upgrade shall not change user credentials.

`StartSystemRestore()`

This operation initiates a system restore from backed up configuration data using the HTTP POST mechanism.

The response to the command includes an HTTP URL to which the backup file may be uploaded. The actual restore takes place as soon as the HTTP POST operation has completed. Devices should support system restore through the StartSystemRestore command. The exact format of the backup configuration data is outside the scope of this specification.

System restore over HTTP may be achieved using the following steps:

Client calls StartSystemRestore.
Server responds with upload URI.
Client transmits the configuration data to the upload URI using HTTP POST.
Server applies the uploaded configuration, then reboots if necessary.

If the system restore fails because the uploaded file was invalid, the HTTP POST response shall be "415 Unsupported Media Type". If the system restore fails due to an error at the device, the HTTP POST response shall be "500 Internal Server Error".

The value of the Content-Type header in the HTTP POST request shall be "application/octetstream".

`GetStorageConfigurations()`

This operation lists all existing storage configurations for the device.

`CreateStorageConfiguration(StorageConfiguration)`

This operation creates a new storage configuration.

The configuration data shall be created in the device and shall be persistent (remain after reboot).

`GetStorageConfiguration(Token)`

This operation retrieves the Storage configuration associated with the given storage configuration token.

`SetStorageConfiguration(StorageConfiguration)`

This operation modifies an existing Storage configuration.

`DeleteStorageConfiguration(Token)`

This operation deletes the given storage configuration and configuration change shall always be persistent.

`GetGeoLocation()`

This operation lists all existing geo location configurations for the device.

`SetGeoLocation(Location)`

This operation allows to modify one or more geo configuration entries.

`DeleteGeoLocation(Location)`

This operation deletes the given geo location entries.