This is only supported in 4.0.7 or newer release of Azure Injector.

Prerequisites

Summary

This tutorial will provide step-by-step instructions for the following:

  • Setting up an Azure storage account and storage container for message storage
  • Modifying the Azure Injector Module to connect to an existing Azure IoT Hub with proper 'content type' and 'content encoding' settings
  • Publishing live tag data and events to Azure IoT Hub
  • Viewing the data that has been routed to the Storage Container in Azure

Upon completion of this tutorial you will have an Ignition Gateway with the Azure Injector module connected and publishing live tag data to an Azure IoT Hub. Those messages will then be automatically routed and stored in an Azure Storage Container.

Tutorial

Step 1: Make sure you have completed the Getting Started: Azure Injector Quick Start tutorial

Parts of the environment created and configured in the Quick Start are used in this tutorial. So, make sure you have completed this before proceeding.

Step 2: Create an Azure Storage Account and Container

In Azure, browse to 'Storage Accounts'. You should see something similar to what is shown below:


Click 'Create' in the upper left corner. This will open the following window:

Specify the Subscription, Resource Group, Storage account name, and Location as shown above. Leave the other fields default. Now click 'Review + Create' near the bottom of the screen. All of the other tab fields (under Networking, Data Protection, Advanced, and Tags) can be left default for the purposes of this example. However, if this is intended to run in production make sure to visit these tabs and set up the Storage Account appropriately for your use case and security needs. After creating the Storage Account, you should see it on the main Storage Accounts page as shown below:

Now select the Storage Account and and scroll down to 'Containers' in the navigation pane for the Storage Account. This is under the 'Data Storage' section as shown below.

Click the '+ Container' button near the top of the main panel. This will open a new panel on the right. Give the new container a name as shown below and click 'Create' in the lower right of the page.

You should now see the new container as shown below.

At this point the Storage Account and Container are ready to receive routed messages from Azure IoT Hub.

Step 3: Configure a Message Route in Azure IoT Hub

In the Azure portal, browse to the IoT Hub that was provisioned as part of the prerequisites of this tutorial. Using the left navigation pane, scroll down to 'Message routing' under the 'Messaging' heading as shown below.

In the main panel you will see tabs including 'Routes', 'Custom Endpoints', and 'Enrich messages'. Select 'Custom endpoints' as shown below:

Now click the '+ Add' button to add a new Custom Endpoint. This will open the page below. Select 'Storage' as the endpoint type as shown below.

Enter a name and select the Storage Container that was created during Step 2 of this tutorial. Also, make sure to set the 'Encoding' type to JSON as shown above. Leave all other fields default. Finally click 'Create'. Next, it will progress to create a route.:

Set the Name, Endpoint (use the storage endpoint you just created) and leave the Data source to the default of 'Device Telemetry Messages'. Also set the Routing Query to the following (and as shown above):

$body.topic.groupId = 'Routed Group'

Finally, click "Create" to save the route. You should now see the newly created route as shown below.

At this point, IoT Hub should be ready to route messages based on the content of the message.

Step 4: Reconfigure Azure Injector to Support Message Based Routing

Now browse to the Ignition Gateway Web UI and to the Azure Injector Settings and finally to the 'Azure IoT Hubs'. You should see the 'Test Setting' that was created in the prerequisite tutorial as shown below.

Click the 'edit' button on the right for that setting to edit it. Then scroll down and click the 'Show advanced properties' checkbox near the bottom as shown below.

Note the 'Content Type' and 'Content Encoding' fields. In order for Azure message routing to work, the 'Content Type' MUST be set to APPLICATION_JSON and the 'Content Encoding' should be set to UTF_8.

During the prerequisite tutorial a set of tags were created to publish to Azure IoT Hub. At this point, we will create some new tags that will be will be routed to the container based on the configuration that now exists in Azure. Because we created a message route that filtered on a Sparkplug Group ID of 'Routed Group' we should create a structure that includes this in the tag tree. Expanding on the tag tree created previously, add a new Sparkplug Group, Edge Node, and Device folder structure with a single boolean tag along side the original structure created in the quickstart as shown below. Note for the message route in Azure to work properly, the Group ID MUST be 'Routed Group' as shown below.

Step 5: Publish Data to Azure IoT Hub

After creating this tag structure with the 'Routed Group', browse to the Azure Injector tag provider and write a 'true' to the 'Azure Injector Control/Refresh' tag shown below. This will cause Azure Injector to rescan the tag tree and publish messages to IoT Hub.

Now that Azure Injector has scanned the tag tree, generate some tag change events by manually changing the following two tags. Make sure as you change these values you wait a couple of seconds between each change. This will ensure that a series of MQTT messages will be published to Azure IoT Hub.

[default]Edge Nodes/Routed Group/Routed Edge Node/Routed Device/Boolean Tag

[default]Edge Nodes/Tutorial Group/Tutorial Edge Node/Tutorial Device/Boolean001

At this point, Azure should route the 'Routed Group' messages to the storage container but ignore the 'Tutorial Group' messages. This can be verified in the next step of this tutorial.

Step 6: View the Data in the Azure Storage Container

At this point, the data should be flowing into the container. To view it, got to Data Storage → Containers → your container

Then browse into your IoT Hub folder down through the levels to find the JSON files. These folders represent the time at which various files were created. When you get to the final folder, you should see something similar to what is shown below in that the final leaf folder contains one or more JSON files.:

Select a JSON file and click to "Edit." You should see something similar to the following:



If you scroll to the right, you should ultimately see the 'body' of the message. This is the raw message that was sent to Azure from the Azure Injector module. Each one of these messages represents a message that was sent from Azure Injector to IoT Hub.

Note that all of the messages shown here are from the 'Routed Group'. This is because of how the Azure IoT Hub message route was configured. The 'routing query' is looking for a 'groupId' of 'Routed Group'. So, all messages from the original 'Tutorial Group' were ignored and not routed to the container.

Additional Resources

  • No labels

New to MQTT? Start Here!