Configure the media connector (preview)

In Azure IoT Operations, the media connector (preview) enables access to media from media sources such as edge-attached cameras.

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.

This article explains how to use the media connector to perform tasks such as:

• Define the devices that connect media sources to your Azure IoT Operations instance.
• Add assets, and define their streams for capturing media from the media source.
• Send an image snapshot to the MQTT broker.
• Save a video clip to Azure storage.

Prerequisites

To configure devices and assets, you need a running preview instance of Azure IoT Operations.

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). To create a suitable Microsoft Entra ID account in your Azure tenant:

1. Sign in to the Azure portal with the same tenant and user name that you used to deploy Azure IoT Operations.
2. In the Azure portal, go to the Microsoft Entra ID section, select Users > +New user > Create new user. Create a new user and make a note of the password, you need it to sign in later.
3. In the Azure portal, go to the resource group that contains your Kubernetes - Azure Arc instance. On the Access control (IAM) page, select +Add > Add role assignment.
4. On the Add role assignment page, select Privileged administrator roles. Then select Contributor and then select Next.
5. On the Members page, add your new user to the role.
6. Select Review and assign to complete setting up the new user.

You can now use the new user account to sign in to the operations experience web UI.

A camera connected to your network and accessible from your Azure IoT Operations cluster. The camera must support the Real Time Streaming Protocol for video streaming. You also need the camera's username and password to authenticate with it.

Media source types

The media connector can connect to various sources, including:

Task types

The media connector supports the following task types:

Example uses

Example uses of the media connector include:

• Capture snapshots from a video stream or from an image URL and publish them to an MQTT topic. A subscriber to the MQTT topic can use the captured images for further processing or analysis.

• Save video streams to a local file system on your cluster. Use Azure Container Storage enabled by Azure Arc to provide a reliable and fault-tolerant solution for uploading the captured video to the cloud for storage or processing.

• Proxy a live video stream from a camera to an endpoint that an operator can access. For security and performance reasons, only the media connector should have direct access to an edge camera. The media connector uses a separate media server component to stream video to an operator's endpoint. This media server can transcode to various protocols such as RTSP, RTCP, SRT, and HLS. You need to deploy your own media server to provide these capabilities.

Deploy the media connector

When you deploy the preview version of Azure IoT Operations, the deployment includes the three preview connectors. You can verify that you have a preview instance of Azure IoT Operations by checking in the Azure portal that preview features are enabled for your instance:

Before you can use the preview connectors (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 three preview connectors can publish captured data to the MQTT broker. The media connector can also save captured data to storage. Azure IoT Operations uses Azure Container Storage enabled by Azure Arc to transfer the captured data to cloud storage destinations such as Azure Blob Storage. When you configure a connector template instance, you specify a persistent volume claim and mount path for the connector to use to save captured data. To learn how to create a suitable persistent volume claim, see Cloud Ingest Edge Volumes configuration.

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 of connector template you want to add, such as ONVIF, Media, HTTP/REST, or SSE HTTP. 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, select Add a volume claim and enter the details of the persistent volume claim you created previously. 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 preview connector endpoint.

Create a device with a media endpoint

To configure the media connector, first create a device that defines the connection to the media source. The device includes the URL of the media source and any credentials you need to access the media source:

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

az iot ops ns device endpoint inbound add media --device media-connector-cli -g {your resource group name} -i {your instance name}  --name media-connector-cli-0 --endpoint-address rtsp://samplecamera:554/stream1

Create an asset to publish an image snapshot

To define a namespace asset that publishes an image snapshot from the media source to the MQTT broker:

az iot ops ns asset media create --name mymediaasset --instance {your instance name}  -g {your resource group name} --device media-connector-cli --endpoint media-connector-cli-0 --task-type snapshot-to-mqtt --task-format jpeg --snapshots-per-sec 0.25 --stream-dest topic="azure-iot-operations/data/snapshots" qos=Qos1 retain=Never ttl=60

Verify the published messages

To verify that the connector is publishing messages, you can use an MQTT client to subscribe to the topic azure-iot-operations/data/{asset name}/{stream name}. If the device and namespace asset are configured correctly, you receive messages containing JPEG image snapshots when you subscribe to this topic.

The following steps show you how to run the mosquitto_sub tool in the cluster. To learn more about this tool and alternative approaches, see MQTT tools:

Verify data is flowing to the MQTT broker by using the mosquitto_sub tool. In this example, you run the mosquitto_sub tool inside your Kubernetes cluster:

1. Run the following command to deploy a pod that includes the mosquitto_pub and mosquitto_sub tools that are useful for interacting with the MQTT broker in the cluster:

   kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/main/samples/quickstarts/mqtt-client.yaml
   

   The following snippet shows the YAML file that you applied:

   # Important: do not use in production environments
   # Create a service account
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: mqtt-client
     namespace: azure-iot-operations
   ---
   # Creates a pod with mosquitto-clients and mqttui utilities in your cluster
   apiVersion: v1
   kind: Pod
   metadata:
     name: mqtt-client
     # The namespace must match the IoT MQ BrokerListener's namespace
     # Otherwise use the long hostname: aio-broker.azure-iot-operations.svc.cluster.local
     namespace: azure-iot-operations
   spec:
     # Use the "mqtt-client" service account which comes with default deployment
     # Otherwise create it with `kubectl create serviceaccount mqtt-client -n azure-iot-operations`
     serviceAccountName: mqtt-client
     containers:
       # Install mosquitto and mqttui utilities on Alpine linux
     - image: alpine
       name: mqtt-client
       command: ["sh", "-c"]
       args: ["apk add mosquitto-clients mqttui && sleep infinity"]
       resources:
         limits:
           cpu: 500m
           memory: 200Mi
         requests:
           cpu: 100m
           memory: 100Mi
       volumeMounts:
       - name: broker-sat
         mountPath: /var/run/secrets/tokens
       - name: trust-bundle
         mountPath: /var/run/certs
     volumes:
     - name: broker-sat
       projected:
         sources:
         - serviceAccountToken:
             path: broker-sat
             audience: aio-internal # Must match audience in BrokerAuthentication
             expirationSeconds: 86400
     - name: trust-bundle
       configMap:
         name: azure-iot-operations-aio-ca-trust-bundle # Default root CA cert
   

   Caution

   This configuration isn't secure. Don't use this configuration in a production environment.

2. When the mqtt-client pod is running, run the following command to create a shell environment in the pod you created:

   kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh
   

3. At the Bash shell in the mqtt-client pod, run the following command to connect to the MQTT broker using the mosquitto_sub tool and use a wildcard to subscribe to the data/# topics:

   mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/#" -v --debug --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)
   

   This command continues to run and displays messages as they arrive on any data/# topics until you press Ctrl+C to stop it. To exit the shell environment, type exit.

To save the payload of a single message, use a command like the following:

mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/my-camera/#" -C 1 -F %p --cafile /var/run/certs/
ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat) > image1.
jpeg

The following screenshot shows the topic name that uses the asset name and stream name:

Add a stream to save a video clip

In this section, you add a stream to the asset that saves video clips from the media source to the file system.

az iot ops ns asset media stream add --asset mymediaasset --instance {your instance name}  -g {your resource group name} --name clipStream --task-type clip-to-fs --format mp4 --duration 30 --path /data/clips

Verify the saved messages

The following steps assume that you configured a persistent volume claim (PVC) to save the clips to your Azure Blob storage account with these settings:

After the connector captures the clips, it uploads them to the /pvc/clips folder in your container: