Configure the connector for MQTT (preview)

This is a preview version of the connector for MQTT connector that lets you model external MQTT endpoints as assets in Azure IoT Operations. The MQTT connector can detect new topic paths as they appear, you can view the custom resources that represent the detected topics.

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 MQTT (preview) supports the following features:

• Enables topics from MQTT device to be represented as assets in Azure Device Registry (ADR).
• Establishes communication with MQTT broker for northbound and southbound connections.
• Detects new topics that appear under a given topic path and communicates with Akri. Akri creates the detected asset custom resource ready for OT approval and import into ADR.
• Detects new topics that appear under a given MQTT wildcard path and communicates with Akri. Akri creates the detected asset custom resource ready for OT approval and import into ADR.
• For approved or imported assets, the connector copies data from raw paths to user-assigned unified namespace paths.
• Follows MQTTS practices for secure communications with the Azure IoT Operations MQTT broker.

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

• Define the devices that connect MQTT sources to your Azure IoT Operations instance.
• Add assets, and define the data points to enable the data flow from the MQTT source to the MQTT broker.

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.

Your IT administrator must have configured the connector for MQTT template for your Azure IoT Operations instance in the Azure portal.

You need any credentials required to access the MQTT source. If the MQTT source requires authentication, you need to create a Kubernetes secret that contains the username and password for the MQTT source.

Deploy the connector for MQTT

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

To configure the connector for MQTT, first create a device that defines the connection to the MQTT topic to subscribe from. The device includes the address of the MQTT topic and any credentials you need to access it:

1. In the operations experience web UI, select Devices in the left navigation pane. Then select Create new.

2. Enter a name for your device, such as mqtt-connector. To add the inbound endpoint for the connector for MQTT, select New on the Microsoft.Mqtt tile.

3. Add the URL of the inbound endpoint for the connector for MQTT and any authentication credentials on the Basic page:

   

   Add the topic details on the Advanced page:

   

   The Asset level specifies the level in topic tree where the connector looks for the asset name.

   The Topic filter specifies how to filter for topics to subscribe to. The setting supports a single level wild card.

   The Topic mapping prefix maps the incoming topic to a unified namespace path.

   Select Apply to save the endpoint.

4. On the Device details page, select Next to continue.

5. On the Add custom property page, you can add any other properties you want to associate with the device. For example, you might add a property to indicate the manufacturer of the device. Then select Next to continue

6. On the Summary page, review the details of the device and select Create to create the asset.

7. After the device is created, you can view it in the Devices list:

   

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:

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.

Configure a certificate trust list for a device to use

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

Discover and create assets

When you send a message to a topic that matches the topic filter you specified when creating the device, the connector for MQTT detects the new topic and creates a detected asset custom resource. For example, if you specified the topic filter as A/B/+, and you send a message to the topic A/B/asset1, the connector for MQTT detects the new topic and creates a detected asset that you can view in the operations experience web UI:

To create an asset from the detected asset, follow these steps:

1. In the operations experience, select the detected asset from the list and then select Import and create asset.

2. On the Asset details page, the inbound endpoint is already selected from the device. Use the name of the discovered asset as the name of the asset, add a description, and any custom properties you want to associate with the asset. Then select Next to continue.

   Important

   The name of the asset you create must match the name of the discovered asset.

3. On the Datasets page, there's a dataset that was created automatically from the detected asset using the topic filter and asset name:

   

   Tip

   You can add more datasets if required to capture messages from other topics.

   Select Next to continue.

4. On the review page, review the details of the asset and select Create to create the asset. After a few minutes, the asset is listed on the Assets page:

   

In this example, the imported asset has a dataset definition with the following settings:

Setting	Value
Dataset name	A/B/asset1
Data source	A/B/asset1
Destination topic	X/Y/A/B/asset1

Now, any messages published to the topic A/B/asset1 are copied to the unified namespace topic X/Y/A/B/asset1 by the connector.