ONVIF

Protocol

---

Created: —

Updated: —

 View source on Github View all issues

---

The ONVIF component allows you to manage and control ONVIF cameras directly in Viseron using the Profile S Client requirements implementation. Currently, the implementation is limited to the Device, Media, Imaging, and PTZ (pan-tilt-zoom) services. And not all operations on the service are implemented in this component, if you feel the implementation of the operation is lacking, please contribute!

All services can be configured directly via the Viseron Dashboard (Camera Tuning), and the PTZ service can also be controlled via the Telegram component or via Live View page.

Since this component's implementation uses the onvif-python library, you can visit the project's GitHub Repository for more details.

Configuration​

onvif:
  cameras:
    camera_one:
      port: 2020
      username: !secret onvif_username
      password: !secret onvif_password
      timeout: 15 # set timeout for ONVIF connections
      use_https: true # use HTTPS for ONVIF connections
      verify_ssl: false # set to false if using self-signed certificated
    camera_two:
      port: 8000
      username: my_username
      password: "@myS3curepassword"
      auto_config: false # will use the configuration below
      device:
        datetime_type: NTP
        ntp_from_dhcp: false
        ntp_manual:
        - ntp_type: DNS
          ntp_server: pool.ntp.org
      imaging:
        brightness: 50.0
        color_saturation: 50.0
        contrast: 50.0
        sharpness: 75.5
        ircut_filter: AUTO
        backlight_compensation: OFF
        exposure:
          mode: AUTO
          min_gain: 0.0
          max_gain: 100.0
        white_balance:
          mode: AUTO
        defogging:
          mode: ON
          level: 0.6
      ptz:
        home_position: false
        reverse_pan: true
        reverse_tilt: false
        min_pan: -0.73 # used to limit pan swings to useful fov
        max_pan: 0.04 # used to limit pan swings to useful fov
        presets: # allows switching between pre-defined (absolute) positions
          - name: front # name them
            x: 1.0
            y: 0.4
            z: 0.7
            on_startup: true # have the camera move to this preset when Viseron starts
          - name: left
            x: -0.5
            y: 0.0
          - name: right
            x: 0.5
            y: 0.0

Services​

The ONVIF component is structured around several core ONVIF services, each representing a distinct set of capabilities exposed by an ONVIF-compliant device. A service defines what kind of operations can be performed, such as retrieving device information, configuring video streams, adjusting image parameters, or controlling camera movement.

Not every camera supports all services or all operations within a service, as availability depends on the device’s hardware and firmware. This section describes the supported ONVIF services in Viseron, outlines their purpose, and lists the specific operations that are implemented for each service.

Device​

Device service allows you to manage ONVIF devices in the following subcategories: capabilities, system, security, and network. Device service is mandatory for all ONVIF devices, so regardless of your camera brand/model, device service will always be available.

But it should be noted that not all operations are supported by all types of cameras, and this ONVIF component does not implement all operations. For a more detailed explanation, you can refer to the official document regarding this service. The operations implemented by this component in the Device service are described as follows:

All Device service operations and settings can be configured via the Camera Tuning page.

Media​

The Media service allows you to manage and configure the video and audio streams transmitted by your ONVIF camera. This service is responsible for stream profiles, video encoder configuration, audio encoder configuration, and managing the camera's built-in OSD (On-Screen Display).

The Media service is mandatory for ONVIF devices that provide media streaming capabilities, so all ONVIF-compatible cameras with video output will support this service. However, not all cameras support all Media operations or configuration options, as availability depends on the camera hardware and firmware.

This ONVIF component does not implement all Media service operations defined in the ONVIF specification. For a more detailed explanation, you can refer to the official document regarding this service. The operations implemented by this component in the Media service are described as follows:

All Media service operations and settings can be configured via the Camera Tuning page.

If you decide not to use auto configuration (auto_config is set to false), this ONVIF component assumes that you know the variable options for each key in video_encoder and audio_encoder. If you fill them in incorrectly, an error will appear.

Imaging​

Imaging service allows you to control and configure the imaging properties of your ONVIF camera video. The Imaging service is mandatory for ONVIF camera devices with a video source, so if your ONVIF device is a camera, this service is definitely present. For a more detailed explanation, you can refer to the official document regarding this service.

Please note that not all Imaging service operations parameters are supported by your camera, this component will adjust automatically in the frontend (Camera Tuning page) based on your camera capabilities. The operations implemented by this component in the Imaging service are described as follows:

All Imaging service operations and settings can be configured via the Camera Tuning page.

If you decide not to use auto configuration (auto_config is set to false) the brightness, color_saturation, contrast, and sharpness parameters have their units unspecified and you must know their minimum and maximum values beforehand. If you enter the unit incorrectly, an error will appear.

Then for the parameters exposure, focus, wide_dynamic_range, white_balance, image_stabilization, ircut_filter_auto_adjustment, tone_compensation, defogging, and noise_reduction must be filled with keys in "snake_case" form, you can see all the key parameters available in this WSDL document.

For example, based on the ONVIF WSDL document, WideDynamicRange has several key parameters like this:

WideDynamicRange - optional; [WideDynamicRange20]
  Mode [WideDynamicMode]
  Level - optional; [float]

Then for wide_dynamic_range it should be configured like this:

wide_dynamic_range:
  mode: ON
  level: 50.0

PTZ​

PTZ service allows you to control and configure the Pan, Tilt, and Zoom movements of your ONVIF PTZ camera. As explained in the ONVIF component description above, this PTZ can be controlled via the Telegram component or via Live View page (as a player menu).

But it should be noted that not all operations are supported by all types of cameras, and this ONVIF component does not implement all operations. For a more detailed explanation, you can refer to the official document regarding this service. The operations implemented by this component in the PTZ service are described as follows:

All PTZ service settings can be configured via the Camera Tuning page and some settings/operations can be configured on the Live View page.

For transparency, PTZ Control available in Live View uses the ContinuousMove operation, which is mandatory for all ONVIF PTZ cameras. PTZ Control in the Telegram component, however, will use the RelativeMove operation if supported by the camera, and will use ContinuousMove as a fallback.

Troubleshooting​

logger:
  logs:
    viseron.components.onvif: debug

Known Issues​

• Optional Action Not Implemented / Action Not Supported: Some cameras may return an "Optional Action Not Implemented" or "Action Not Supported" error when attempting to perform certain operations. This can occur if the camera does not support a specific ONVIF operation or if the operation is not implemented in the camera's firmware. In such cases, it is recommended to check the camera's documentation or contact the manufacturer for more information on supported ONVIF operations.

• Timeout/Network Error: A timeout error may occur when the camera takes too long to respond to an ONVIF request. This can happen due to network latency, camera processing delays, or other factors. To resolve this issue, you can try increasing the timeout value in the ONVIF component configuration or optimizing the network connection between Viseron and the camera.

• Camera ignores parameters: Some cameras may ignore certain parameters when setting up the configuration or adjusting operating parameters (e.g. PTZ Speed, Brightness Level) via ONVIF. This can happen if the camera does not support specific configuration options or if the parameters are not valid for the camera model or the camera completely ignores it. In such cases, it is recommended to check the camera's documentation or contact the manufacturer for more information on supported configuration options.

• Different schema definitions: Some cameras may have different schema definitions for certain ONVIF operations, which can lead to compatibility issues when trying to perform those operations. You can try to work around this by using a WSDL that matches your camera's ONVIF version by adding wsdl_dir to the key under <CAMERA_IDENTIFIER>. For more information on this, please see the onvif-python library documentation.

Strange camera behavior​

Although this ONVIF component has tried to implement all configurations dynamically based on the camera's capabilities, there are still some cameras that have non-standard/uncommon behavior in general ONVIF compliant cameras.

Moreover, if your camera brand/model is not registered in ONVIF Conformant Products, then there is a big possibility that your camera will behave strangely. Some of the issues commonly encountered regarding the compatibility of ONVIF components are:

• Some cameras do not properly implement the ONVIF specification, causing certain operations to fail or return unexpected results. This can lead to issues when trying to configure or control the camera using standard ONVIF commands.
• Some cameras may have limitations in their ONVIF implementation, such as not supporting certain features or operations defined in the ONVIF specification. This can result in missing functionality when using the ONVIF component.
• Differences in how cameras interpret and respond to ONVIF commands can lead to inconsistencies in behavior across different camera models. This can make it challenging to create a universal ONVIF component that works seamlessly with all cameras.
• Some cameras may require specific configurations or settings to be enabled in order to fully utilize their ONVIF capabilities. If these settings are not properly configured, it can lead to issues when using the ONVIF component.