|
| 1 | +--- |
| 2 | +title: How to use the media connector (preview) |
| 3 | +description: How to use the media connector (preview) to perform tasks such as sending an image snapshot to the MQTT broker or saving a video stream to a local file system. |
| 4 | +author: dominicbetts |
| 5 | +ms.author: dobett |
| 6 | +ms.service: azure-iot-operations |
| 7 | +ms.topic: how-to |
| 8 | +ms.date: 10/07/2024 |
| 9 | + |
| 10 | +#CustomerIntent: As an industrial edge IT or operations user, I want to configure the media connector so that I can access snapshots and videos from a media source such as a IP video camera. |
| 11 | +--- |
| 12 | + |
| 13 | +# Configure the media connector (preview) |
| 14 | + |
| 15 | +In Azure IoT Operations, the media connector (preview) enables access to media from media sources such as edge-attached cameras. This article explains how to use the media connector to perform tasks such as sending an image snapshot to the MQTT broker or saving a video stream to a local file system. |
| 16 | + |
| 17 | +The media connector: |
| 18 | + |
| 19 | +- Uses _asset endpoints_ to access media sources. An asset endpoint defines a connection to a media source such as a camera. The asset endpoint configuration includes the URL of the media source, the type of media source, and any credentials needed to access the media source. |
| 20 | + |
| 21 | +- Uses _assets_ to represent media sources such as cameras. An asset defines the capabilities and properties of a media source such as a camera. |
| 22 | + |
| 23 | +## Prerequisites |
| 24 | + |
| 25 | +A deployed instance of Azure IoT Operations. If you don't already have an instance, see [Quickstart: Run Azure IoT Operations Preview in GitHub Codespaces with K3s](../get-started-end-to-end-sample/quickstart-deploy.md). |
| 26 | + |
| 27 | +## Deploy the media server |
| 28 | + |
| 29 | +If you're using the media connector to stream live video, you need to install your own media server. To deploy a sample media server to use with the media connector, run the following command: |
| 30 | + |
| 31 | +```console |
| 32 | +kubectl create namespace media-server --dry-run=client -o yaml | kubectl apply -f - & kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/refs/heads/main/samples/media-connector-invoke-test/media-server/media-server-deployment.yaml --validate=false & kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/refs/heads/main/samples/media-connector-invoke-test/media-server/media-server-service.yaml --validate=false & kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/refs/heads/main/samples/media-connector-invoke-test/media-server/media-server-service-public.yaml --validate=false |
| 33 | +``` |
| 34 | + |
| 35 | +## Use Bicep to configure the media connector (preview) |
| 36 | + |
| 37 | +You can use Bicep to define the asset endpoint and asset for a media source such as a camera. The following Bicep code shows how to define an asset endpoint and asset for a media source. The asset endpoint uses the anonymous authentication method to connect to the video stream: |
| 38 | + |
| 39 | +```bicep |
| 40 | +metadata description = 'Asset endpoint profile and asset for a media source' |
| 41 | +param resourceName string |
| 42 | +param targetAddress string |
| 43 | +param customLocationName string |
| 44 | +param assetName string |
| 45 | +param strDescription string |
| 46 | +param bolEnabled bool |
| 47 | +param datasetsName string |
| 48 | +param datasetsDataPoints array |
| 49 | +
|
| 50 | +/*****************************************************************************/ |
| 51 | +/* Existing AIO cluster */ |
| 52 | +/*****************************************************************************/ |
| 53 | +resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = { |
| 54 | + name: customLocationName |
| 55 | +} |
| 56 | +/*****************************************************************************/ |
| 57 | +/* Asset endpoint profile */ |
| 58 | +/*****************************************************************************/ |
| 59 | +resource assetEndpoint 'Microsoft.DeviceRegistry/assetEndpointProfiles@2024-11-01' = { |
| 60 | + name: resourceName |
| 61 | + location: resourceGroup().location |
| 62 | + extendedLocation: { |
| 63 | + type: 'CustomLocation' |
| 64 | + name: customLocation.id |
| 65 | + } |
| 66 | + properties: { |
| 67 | + targetAddress: targetAddress |
| 68 | + endpointProfileType: 'Microsoft.Media' |
| 69 | + authentication: { |
| 70 | + method: 'Anonymous' |
| 71 | + } |
| 72 | + additionalConfiguration: '{"$schema": "https://aiobrokers.blob.core.windows.net/aio-media-connector/1.0.0.json"}' |
| 73 | + } |
| 74 | +} |
| 75 | +/*****************************************************************************/ |
| 76 | +/* Asset */ |
| 77 | +/*****************************************************************************/ |
| 78 | +resource asset 'Microsoft.DeviceRegistry/assets@2024-11-01' = { |
| 79 | + name: assetName |
| 80 | + location: resourceGroup().location |
| 81 | + extendedLocation: { |
| 82 | + type: 'CustomLocation' |
| 83 | + name: customLocation.id |
| 84 | + } |
| 85 | + properties: { |
| 86 | + displayName: assetName |
| 87 | + assetEndpointProfileRef: assetEndpoint.name |
| 88 | + description: strDescription |
| 89 | + enabled: bolEnabled |
| 90 | + datasets: [ |
| 91 | + { |
| 92 | + name: datasetsName |
| 93 | + dataPoints: datasetsDataPoints |
| 94 | + } |
| 95 | + ] |
| 96 | + } |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +The following JSON snippet shows a set of parameter values to use: |
| 101 | + |
| 102 | +```json |
| 103 | +{ |
| 104 | + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", |
| 105 | + "contentVersion": "1.0.0.0", |
| 106 | + "parameters": { |
| 107 | + "resourceName": { |
| 108 | + "value": "aep-public-http-anonymous-1" |
| 109 | + }, |
| 110 | + "assetName": { |
| 111 | + "value": "asset-public-http-anonymous-1-snapshot-to-mqtt-autostart" |
| 112 | + }, |
| 113 | + "strDescription": { |
| 114 | + "value": "snapshot to mqtt (autostart)" |
| 115 | + }, |
| 116 | + "bolEnabled": { |
| 117 | + "value": true |
| 118 | + }, |
| 119 | + "targetAddress": { |
| 120 | + "value": "https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/refs/heads/main/samples/shared-multimedia/IntroducingAzureIoTOperations.mp4" |
| 121 | + }, |
| 122 | + "datasetsName": { |
| 123 | + "value": "snapshot-to-mqtt-autostart" |
| 124 | + }, |
| 125 | + "datasetsDataPoints": { |
| 126 | + "value": [ |
| 127 | + { |
| 128 | + "name": "snapshot-to-mqtt", |
| 129 | + "dataSource": "snapshot-to-mqtt", |
| 130 | + "dataPointConfiguration": "{\"taskType\":\"snapshot-to-mqtt\",\"autostart\":true,\"realtime\":true,\"loop\":true,\"format\":\"jpeg\",\"fps\":1}" |
| 131 | + } |
| 132 | + ] |
| 133 | + } |
| 134 | + } |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +These parameters configure: |
| 139 | + |
| 140 | +- The asset endpoint to connect to a video stream at `https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/refs/heads/main/samples/shared-multimedia/IntroducingAzureIoTOperations.mp4`. |
| 141 | +- The asset to capture snapshots from the video stream and publish them to an MQTT topic. |
| 142 | + |
| 143 | +The default MQTT topic name that the connector publishes to is `<connector namespace>/data/<asset name>`. |
| 144 | + |
| 145 | +To apply the previous configuration, save the previous examples as files, and run the following command: |
| 146 | + |
| 147 | +```azurecli |
| 148 | +az deployment group create --resource-group <your resource group> --template-file aep-camera-anonymous.bicep --parameters snapshot-to-mqtt-autostart.json --parameters customLocationName=<your custom location> |
| 149 | +``` |
| 150 | + |
| 151 | +[!INCLUDE [discover-custom-location](../includes/discover-custom-location.md)] |
| 152 | + |
| 153 | +This asset configuration publishes snapshots from the video stream to an MQTT topic. To view the snapshots, you can subscribe to the MQTT topic. To learn more about how to subscribe to an MQTT topic in a nonproduction environment, see [Test connectivity to MQTT broker with MQTT clients](../manage-mqtt-broker/howto-test-connection.md). |
| 154 | + |
| 155 | +## Dataset configuration |
| 156 | + |
| 157 | +The `datasetsDataPoints` parameter specifies the action the media connector takes on the asset. The previous example configures the camera to capture snapshots to publish to an MQTT broker topic. A camera asset supports the following five task types: |
| 158 | + |
| 159 | +| Task type | Description | |
| 160 | +|-----------|-------------| |
| 161 | +| `snapshot-to-mqtt` | Capture snapshots from a camera and publishes them to an MQTT topic. | |
| 162 | +| `snapshot-to-fs` | Capture snapshots from a camera and saves them to the local file system. | |
| 163 | +| `clip-to-mqtt` | Capture video clips from a camera and publishes them to an MQTT topic. | |
| 164 | +| `clip-to-fs` | Capture video clips from a camera and saves them to the local file system. | |
| 165 | +| `stream-to-rtsp` | Sends a live video stream from a camera to a media server. | |
| 166 | + |
| 167 | +You can use the following settings to configure individual tasks: |
| 168 | + |
| 169 | +- `autostart`: Whether the task starts automatically when the asset starts. |
| 170 | +- `realtime`: Whether the task runs in real time. |
| 171 | +- `loop`: Whether the task runs continuously. |
| 172 | +- `format`: The format of the media file. |
| 173 | +- `fps`: The frames per second for the media file. |
| 174 | +- `audioEnabled`: Whether audio is enabled for the media file. |
| 175 | +- `duration`: The duration of the media file. |
| 176 | + |
| 177 | +The following YAML snippets show example dataset configurations for each task type. The `taskType` value determines the task type to configure: |
| 178 | + |
| 179 | +```yaml |
| 180 | +datasets: |
| 181 | + - name: dataset1 |
| 182 | + dataPoints: |
| 183 | + - name: snapshot-to-mqtt |
| 184 | + dataSource: snapshot-to-mqtt |
| 185 | + dataPointConfiguration: |- |
| 186 | + { |
| 187 | + "taskType": "snapshot-to-mqtt", |
| 188 | + "autostart": true, |
| 189 | + "realtime": true, |
| 190 | + "loop": true, |
| 191 | + "format": "jpeg", |
| 192 | + "fps": 1 |
| 193 | + } |
| 194 | +``` |
| 195 | +
|
| 196 | +```yaml |
| 197 | +datasets: |
| 198 | + - name: dataset1 |
| 199 | + dataPoints: |
| 200 | + - name: snapshot-to-fs |
| 201 | + dataSource: snapshot-to-fs |
| 202 | + dataPointConfiguration: |- |
| 203 | + { |
| 204 | + "taskType": "snapshot-to-fs", |
| 205 | + "autostart": false, |
| 206 | + "realtime": true, |
| 207 | + "loop": true, |
| 208 | + "format": "jpeg", |
| 209 | + "fps": 1 |
| 210 | + } |
| 211 | +``` |
| 212 | +
|
| 213 | +
|
| 214 | +```yaml |
| 215 | + datasets: |
| 216 | + - name: dataset1 |
| 217 | + dataPoints: |
| 218 | + - name: clip-to-mqtt |
| 219 | + dataSource: clip-to-mqtt |
| 220 | + dataPointConfiguration: |- |
| 221 | + { |
| 222 | + "taskType": "clip-to-mqtt", |
| 223 | + "format": "avi", |
| 224 | + "autostart": true, |
| 225 | + "realtime": true, |
| 226 | + "loop": true, |
| 227 | + "fps": 3, |
| 228 | + "audioEnabled": false, |
| 229 | + "duration": 3 |
| 230 | + } |
| 231 | +``` |
| 232 | +
|
| 233 | +```yaml |
| 234 | +datasets: |
| 235 | + - name: dataset1 |
| 236 | + dataPoints: |
| 237 | + - name: clip-to-fs |
| 238 | + dataSource: clip-to-fs |
| 239 | + dataPointConfiguration: |- |
| 240 | + { |
| 241 | + "taskType": "clip-to-fs", |
| 242 | + "format": "avi", |
| 243 | + "autostart": true, |
| 244 | + "realtime": true, |
| 245 | + "loop": true, |
| 246 | + "duration": 3 |
| 247 | + } |
| 248 | +``` |
| 249 | +
|
| 250 | +```yaml |
| 251 | +datasets: |
| 252 | + - name: dataset1 |
| 253 | + dataPoints: |
| 254 | + - name: stream-to-rtsp |
| 255 | + dataSource: stream-to-rtsp |
| 256 | + dataPointConfiguration: |- |
| 257 | + { |
| 258 | + "taskType": "stream-to-rtsp", |
| 259 | + "autostart": true, |
| 260 | + "realtime": true, |
| 261 | + "loop": true |
| 262 | + } |
| 263 | +``` |
| 264 | +
|
| 265 | +## Samples |
| 266 | +
|
| 267 | +For more examples that show how to configure and use the media connector, see the [Azure IoT Operations samples repository](https://github.com/Azure-Samples/explore-iot-operations/blob/main/samples/media-connector-invoke-test/README.md). |
0 commit comments