Configure the connector for ONVIF

In Azure IoT Operations, the connector for ONVIF enables you to discover and use an ONVIF compliant camera that's connected to your Azure IoT Operations cluster.

An asset in Azure IoT Operations is a logical entity that you create to represent a physical asset or device. An Azure IoT Operations asset can have custom properties, data points, streams, and events that describe its behavior and characteristics. An asset is associated with one or more devices. Azure IoT Operations stores asset definitions in the Azure Device Registry.

A device in Azure IoT Operations is a logical entity that defines the connections to physical assets or devices. Without a device, data can't flow from a physical device or asset to the MQTT broker. When you configure a device and asset, a connection is established to the physical asset or device and data point values, events, and streams arrive in Azure IoT Operations instance. A device has one or more inbound endpoints. Azure IoT Operations stores device definitions in the Azure Device Registry.

The connector for ONVIF for Azure IoT Operations connects ONVIF conformant cameras to your Azure IoT Operations instance and registers them in the Azure Device Registry. The connector then automatically discovers:

• The capabilities, such as pan-tilt-zoom (PTZ), of the ONVIF device.
• The media endpoints exposed by the ONVIF device.
• Details of the media streams such as framerate, resolution, and encoding.

After the camera is registered, examples of management operations include:

• Retrieving and updating the configuration of the camera to adjust the output image configuration.
• Controlling the camera pan, tilt, and zoom (PTZ).

The media connector can access the media sources exposed by these cameras.

Together, the media connector, connector for ONVIF, Azure IoT Operations, and companion services enable you to use Azure IoT Operations to implement use cases such as:

• Wait and dwell time tracking to track the time spent in line by customers.
• Order accuracy to track that the correct orders are packed by comparing items to POS receipt.
• Defect detection and quality assurance by cameras to detect any defects in products on the assembly line.
• Safety monitoring such as collision detection, safety zone detection, and personal safety equipment detection.

This article describes how to use the operations experience web UI and Azure CLI to:

• Add a device that has an ONVIF endpoint for a compliant camera.
• View the assets and devices discovered at the ONVIF endpoint.
• Create a device that represents the media endpoints exposed by the ONVIF camera.
• Create an asset that captures snapshots from the media endpoint and publishes them to the MQTT broker.

The connector for ONVIF supports the following authentication methods:

• Username/password authentication
• Anonymous access for testing purposes

To establish a TLS connection to the ONVIF camera, you can configure a certificate trust list for the connector.

Prerequisites

A deployed instance of Azure IoT Operations with resource sync rules enabled. To enable resource sync rules run the following command on your Azure IoT Operations instance. This command also sets the required permissions on the custom location:

az iot ops enable-rsync -n <my instance> -g <my resource group>

To sign in to the operations experience web UI, you need a Microsoft Entra ID account with at least contributor permissions for the resource group that contains your Kubernetes - Azure Arc instance. You can't sign in with a Microsoft account (MSA). For more information, see Troubleshoot access to the operations experience web UI.

An ONVIF compliant camera that you can reach from your Azure IoT Operations cluster.

ONVIF compliance

ONVIF has several categories for compliance, such as discovery, device, media, imaging, analytics, events, and pan-tilt-zoom (PTZ) services. To learn more, see ONVIF - Profiles, Add-ons, and Specifications.

The connector for ONVIF in Azure IoT Operations focuses on support for camera devices that implement the following profiles:

• Profile S for basic video streaming
• Profile T for advanced video streaming

The connector enables support for the following capabilities:

• Discovery of device information and capabilities.
• Monitoring events from devices.
• Discovery of the media URIs exposed by a device. The connector for ONVIF makes these URIs available to the media connector.
• Imaging control such as filters and receiving motion and tampering events.
• Controlling device PTZ.

Deploy the connector for ONVIF

When you deploy Azure IoT Operations, the deployment includes various connectors. Before you can use the connectors (such as ONVIF, media, and HTTP/REST) in the operations experience web UI, an administrator must add connector template instances to your Azure IoT Operations instance.

All the connectors can publish captured data to the MQTT broker.

To add a connector template instance to your Azure IoT Operations instance:

1. In the Azure portal, go to your Azure IoT Operations instance, select Connector templates, and then select Add connector template instances:

   

2. On the first page of the Add an Akri connector template wizard, select the type and version of connector template you want to add, such as ONVIF, Media, HTTP/REST, SSE, or MQTT. Then select Metadata.

   

3. On the Metadata page, accept the defaults, and then select Device inbound endpoint type.

4. On the Device inbound endpoint type page, accept the defaults, and then select Diagnostics configurations.

5. On the Diagnostics configurations page, accept the defaults, and then select Runtime configuration.

6. On the Runtime configuration page, accept the defaults, and then select Review.

7. On the Review page, review the details of the connector template instance, and then select Create to create the connector template instance.

An OT user can now use the operations experience web UI to create a device with a connector endpoint.

---

Create a device with an ONVIF endpoint

To add a device that includes an ONVIF endpoint for a compliant camera:

Operations experience

1. In the operations experience web UI, select Devices from the left navigation pane:

   

2. Select Create new. On the Device details page, enter a name for the device such as my-onvif-camera. To define the inbound endpoint, select New on the Microsoft.Onvif tile. Enter the details for your ONVIF camera, such as:

   

   Select Save to add the endpoint to the device. The Device details page now shows the ONVIF endpoint.

3. On the Device details page, select Next.

4. On the Add custom property page, you can optionally update or add custom properties to the device. Select Next when you're done.

5. The Summary page shows the details of the device. Review the details, and then select Create to create the device. After a few minutes, the Devices page shows the new device.

   

Azure CLI

Run the following commands:

az iot ops ns device create -n onvif-connector-cli -g {your resource group name} --instance {your instance name}

az iot ops ns device endpoint inbound add onvif --device onvif-connector-cli -g {your resource group name} -i {your instance name}  --name onvif-connector-cli-0 --endpoint-address http://myonvifcam:2020/onvif/device_service

To learn more, see az iot ops ns device.

Configure a device to use a username and password

The previous example uses the Anonymous authentication mode. This mode doesn't require a username or password.

To use the Username password authentication mode, complete the following steps:

Operations experience

Follow the steps in Manage secrets for your Azure IoT Operations deployment to add secrets for username and password in Azure Key Vault, project them into Kubernetes cluster, and reference them from your device configuration.

Azure CLI

1. Follow the steps in Manage secrets for your Azure IoT Operations deployment to add secrets for username and password in Azure Key Vault, and project them into Kubernetes cluster.

2. Use the az iot ops ns device endpoint inbound add command with the --user-ref and --pass-ref parameters to add the references to the Azure Key Vault secrets you created.

Other security options

To manage the trusted certificates list for the connector for ONVIF, see Manage certificates for external communications.

When you create the inbound endpoint in the operations experience, you can also select the following options on the Advanced tab:

Option	Type	Description
Accept invalid hostnames	Yes/No	Accept invalid hostnames in certificates for the ONVIF connection, defaults to No
Accept invalid certificates	Yes/No	Accept invalid certificates for the ONVIF connection, defaults to No
Fallback to username token auth	Yes/No	Fall back to UsernameToken authentication if digest authentication fails for the ONVIF connection, defaults to No

Tip

For more information about how to use the Azure CLI to configure these settings, see the az iot ops ns device endpoint inbound add command reference.

View the discovered assets and devices

After you create a device with an ONVIF endpoint, the connector for ONVIF automatically discovers the ONVIF assets and media devices that are available at the endpoint. To view the discovered assets and devices in the operations experience web UI, select Discovery from the left navigation pane:

• Choose Import and create asset from the discovered ONVIF asset to create an asset that represents the capabilities of the ONVIF compliant camera. For example, you can create an asset that captures events from the ONVIF camera or enables you to control the ONVIF camera. For more information, see the section Create an ONVIF asset for event management and control.

• Choose Import and create device from the discovered ONVIF device to create a device that connects to the media endpoints exposed by the ONVIF compliant camera. After you create the media device, you can create media assets that capture snapshots or video streams from the media endpoints. For more information, see the section Create a device with media endpoints.

Create a device with media endpoints

To create a device with media endpoints from the discovered device, follow these steps:

1. In the operations experience web UI, select Discovery from the left navigation pane. Then select Discovered devices.

2. Select the discovered media device, such as my-onvif-camera. Then select Import and create device.

3. The Device details page shows all the discovered media inbound endpoints. Enter a name for the device, such as my-onvif-camera-media, and select an Authentication method for each endpoint:

   

   Tip

   You can remove an inbound endpoint that you don't need by selecting it and then selecting Remove inbound endpoint.

   Then select Next.

4. On the Add custom property page, you can see the discovered properties. You can optionally update, remove, or add custom properties to the device. Select Next when you're done.

5. On the Summary page, review the details of the device. Select Create to create the device. After a few minutes, the Devices page shows the new media device.

   

Create a media asset to capture snapshots

You can now use the discovered media device to create an asset that captures snapshots from the camera and publishes them to the MQTT broker. To create the media asset, follow these steps:

1. In the operations experience web UI, select Assets from the left navigation pane. Then select Create asset.

2. On the Asset details page, enter a name for the asset, such as my-onvif-camera-media-asset. Then select the discovered endpoint you want to use to capture snapshots.

   

   Update any custom properties for the media asset and then select Next.

3. On the Streams page, select Add stream. Use the following settings to configure an example stream that publishes snapshots to the MQTT broker:

   • Stream name: myassetvideo
   • Destination: MQTT
   • Topic: myassetvideo
   • Task type: snapshot-to-mqtt

   Tip

   The topic you choose here is automatically nested under azure-iot-operations/data/<asset-name>/ when the connector for ONVIF publishes the snapshots to the MQTT broker.

   Leave the other settings as default. Then select Add. The stream is added to the asset configuration:

   

4. Select Next to go to the Review page. Review the details of the asset, and then select Create to create the asset. After a few minutes, the Assets page shows the new asset.

   

The media asset is now configured to capture snapshots from the ONVIF compliant camera and publish them to the MQTT broker.

Create an ONVIF asset for event management and control

ONVIF compliant cameras can generate events such as motion detection and respond to control commands such as pan, tilt, and zoom. You can create an ONVIF asset from the discovered ONVIF device that captures these events and enables you to control the camera.

After you add an ONVIF device in the operations experience, a discovered ONVIF asset is created automatically:

To create an ONVIF asset for event management and control:

1. Select the discovered asset and then select Import and create asset.

2. On the Asset details page, enter a name and description for the asset. The device inbound endpoint is already selected for you and the custom properties are prepopulated from the discovered asset:

   

   Select Next to continue.

3. On the Event groups page, select the event group to review the discovered events. You can remove any events that you don't want to use:

   

4. For each event you keep, configure the MQTT topic it publishes to:

   

   Select Next to continue.

5. On the Management groups page, configure the actions, such as pan, tilt, and zoom, that you want to use to control the ONVIF camera.

   

   For more information about configuring management groups, see Manage and control the camera.

   Select Next to continue.

6. Review the summary of the ONVIF asset configuration and then select Create to create the asset. After a few minutes, the Assets page shows the new asset.

Manage and control the camera

To interact with the ONVIF camera, you can publish MQTT messages that the connector for ONVIF subscribes to. The message format is based on the ONVIF network interface specifications.

The Azure IoT Operations connector for ONVIF PTZ Demo sample application shows how to use the connector for ONVIF to:

• Use the media asset definition to retrieve a profile token from the camera's media service.
• Use the profile token when you use the camera's PTZ capabilities control its position and orientation.

The sample application uses the Azure IoT Operations MQTT broker to send commands to interact with the connector for ONVIF. To learn more, see Publish and subscribe MQTT messages using MQTT broker.