Page History

Prerequisites

• Create an IoT Hub in Azure: https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal?view=iotedge-2020-11
• Register an IoT Edge Device in IoT Hub: https://docs.microsoft.com/en-us/azure/iot-edge/how-to-register-device?view=iotedge-2020-11&tabs=azure-portal
• Install Azure Edge: https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge?view=iotedge-2020-11
• Configure the CA certificates for the IoT Device: https://docs.microsoft.com/en-us/azure/iot-edge/how-to-manage-device-certificates?view=iotedge-2020-11
• Install Azure CLI on a development system: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

Summary

The tutorial will provide step by step instructions for the following:

• Configuring Azure IoT Hub to allow client connections to a deployed IoT Edge Hub
• Connecting Azure Injector to the IoT Edge Hub
• Publishing data from Azure Injector to Azure IoT Edge Hub and viewing the data

• Install Azure Edge
• Configure the CA certificates for the IoT Device

• Anchor
  installazurecli installazurecli

  Install Azure CLI on a development system

Summary

The tutorial will provide step by step instructions for the following:

• Configuring Azure IoT Hub to allow client connections to a deployed IoT Edge Hub
• Connecting Azure Injector to the IoT Edge Hub
• Publishing data from Azure Injector to Azure IoT Edge Hub and viewing the data

Tutorial

There are two primary ways to connect to an Azure Edge Hub via MQTT from an MQTT client. These are 'module' or 'device' connections. A module connection typically involves an application deployed as a docker container that runs in Azure Edge. This is the preferred way of connecting the Azure Injector module to Azure Edge Hub. This tutorial will use this method for connecting to Azure IoT Edge.

...

Note this shows an error that the '417 - The device's deployment configuration is not set'. This can be fixed by creating a deployment configuration for this Azure Edge Device.

Step 1: Create Deployment Configuration

Begin by clicking the Device in the Azure Portal. After doing so, you should see something similar to what is shown below.

...

• Set the following fields under 'Module Settings'.
  • IoT Edge Module Name: Ignition

  • Image URI: inductiveautomation/ignition:8.1.

    7Note Ignition v8

    x where x is the latest stable release from the 8.1.

    7 is the latest as of this writing. New versions may be posted

    x branch.

    Tip
    The latest version is updated and available here: https://hub.docker.com/r/inductiveautomation/ignition

    
    

  • Restart Policy: always
  • Desired Status: running
  • Image Pull Policy: On create
  • Startup Order: 200
• Leave the 'Environment Variables' blank

• Under 'Container Create Options' set the following JSON as the value. The 'Binds' field is required and there to preserve Ignition configuration across container deployments.

  Code Block
  { "HostConfig": { "PortBindingsBinds": {[ "8088/tcp": [ IgnitionData:/usr/local/bin/ignition/data" ], "PortBindings": { "8088/tcp": [ { "HostPort": "8088" } ], "8043/tcp": [ { "HostPort": "8043" } ], "8060/tcp": [ { "HostPort": "8060" } ] } } }

  
  

• Leave the 'Module Twin Settings' blank

...

Copy the 'Connection string (primary key)' and save it for later use. This will be used in the Ignition configuration to establish an MQTT Connection from Ignition's Azure Injector module to Azure IoT Edge Hub.

Step 2: Install Ignition

At this point, Ignition is running as a Docker container in Azure Edge. You should be able to browse to http://[ip_address_of_azure_edge]:8088. Replace [ip_address_of_azure_edge] with the IP address of your Azure Edge system. You should see something similar to the following.

Select 'Ignition' or 'Ignition Edge' depending on your preference. We'll use Ignition for this tutorial. After selecting an Ignition type, you should see the following.

Image Removed

Follow the steps in the Installing Ignition documentation and select either Ignition or Ignition Edge for this tutorial.

Step 3: Install and configure the Azure Injector Module

Follow the steps in the Module Installation guide to install the latest Azure Injector Module.

Now select 'Settings' under the Azure Injector section in the left navigation panel near the bottom. After doing so, you should see Accept the Inductive Automation Software License Agreement if you read and agree with the terms and conditions and click 'Next'. This will open the following page.

Image RemovedImage Added

Now select 'Azure IoT Edges' from the tabs near the top of the page. This will open the following page.

Image Added

Now select the 'Certificates' tab next to 'Settings'. This will show specify the username and password to use for your Ignition system. Save these for later as they will be required any time you log into the Ignition Web UI. Now click 'Finish Setup' which will open the following page.

Image RemovedImage Added

Click 'Start GatewayCreate new Certificate'. This will take a few minutes to start the Ignition Gateway. When it is complete, you will see the following page.

Image Removed

If you are unfamiliar with Ignition or want to enable the 'Quick Start', select it. Otherwise, click 'start from scratch'. Now click 'Config' in the far left navigation panel. You should now see the following page. Note you may be asked to log in.

Image Removed

Now click 'Modules' under the 'System' section in the blue left navigation panel. This will open the following page.

Image Removed

Scroll to the bottom and click the 'Install or Upgrade a Module...' link near the bottom of the page. This will open the following page.

Image Removed

Go to https://inductiveautomation.com/downloads/third-party-modules/ and download the latest Azure Injector module. Use this on the upload form in the Ignition Web UI. After installing you should see the Azure Injector module in the modules list as shown below.

Image Removed

Then browse to the Azure IoT Edge Device Root CA that you provisioned during the installation and configuration of the Azure IoT Edge Device. Give it a friendly name as shown below.Image Added

Now click 'Create New Certificate'. After doing so you should see something similar to the following.Image Added

Now select the 'Settings' tab directly to the left of the 'Certificates' tab. Then click the 'Create new Azure IoT Edge Setting...' link. This will open the following page.Image Added

Set the following parameters in the form (leave all others in their default state)

• Main Section
  • Setting Name: Azure IoT Edge
•  Authentication Section
  • Password: The Connection String associated with the 'Ignition' module you captured earlier in this tutorial.
  • CA Certificate File: The 'IoT Edge Device Root CA' created in the previous step

After the parameters are set, click the 'Save Changes' button at the bottom of the pageNow select 'Settings' under the Azure Injector section in the left navigation panel near the bottom. After doing so, you should see the following page.

Image Removed

Now select 'Azure IoT Edge Hubs' from the tabs near the top of the page. This will open the following page.

Image Removed

Now select the 'Certificates' tab next to 'Settings'. This will show the following page.

Image Removed

Click 'Create new Certificate'. Then browse to the Azure IoT Edge Device Root CA that you provisioned during the installation and configuration of the Azure IoT Edge Device. Give it a friendly name as shown below.

Image Removed

Now click 'Create New Certificate'. After doing so you should see something similar to the following.

Image Removed

Now select the 'Settings' tab directly to the left of the 'Certificates' tab. Then click the 'Create new Azure IoT Edge Hub Setting...' link. This will open the following page.

Image Removed

Set the following parameters in the form (leave all others in their default state)

• Main Section
  • Setting Name: Azure IoT Edge
•  Authentication Section
  • Password: The Connection String associated with the 'Ignition' module you captured earlier in this tutorial.
  • CA Certificate File: The 'IoT Edge Device Root CA' created in the previous step

After the parameters are set, click the 'Save Changes' button at the bottom of the page. After doing so, you should see the following.

Image Removed

If everything went well, you should also see 'Connected' under the Status column. Note it may take a couple of seconds to switch to a Connected status.

Once the system is showing connected, tags can be created in Ignition Designer. Begin by using the following document to launch Designer: https://docs.inductiveautomation.com/display/DOC80/Designer+Launcher

With Ignition Designer launched, you should see something similar to the following.

Image Removed

In the lower left 'Tag Browser' pane make sure the 'default' tag provider is selected. Then right click on the 'Edge Nodes' folder and select 'New Tag' and then 'New Folder'. Name the new folder 'My Group' and click OK. You should now see the following.

Image Removed

Repeat this process until you have a folder structure of 'Edge Nodes/My Group/My Edge Node/My Device' as shown below.

Image Removed

Now right click on the 'My Device' folder and select 'New Tag' → 'New Standard Tag' → 'Memory Tag'. In the dialog, set the following parameters and leave all other tags default.

• Name: My Tag
• Value: 123

After clicking 'OK', you should see the following.

Image Removed

Using the Azure Command Line tools you previously installed on a development machine (from the prereqs here), run the following command

az iot hub monitor-events --hub-name YOUR_HUB_NAME --consumer-group YOUR_CONSUMER_GROUP --timeout 0

You should see a message denoting the monitor is running as follows

Starting event monitor, use ctrl-c to stop...

Now from the Tag Browser dropdown menu at the top select 'Azure

Image Removed

This will show tags from the Azure Injector Tag Provider. Expand 'Azure Injector Control' and write a 'true' to the 'Refresh' tag boolean by clicking on the checkbox. You will be asked to change to Read/Write mode as shown below. Click 'Enable Read/Write Mode'.

Image Removed

After doing so, writing true to the 'Refresh' boolean tag will cause the Azure Injector to rescan the tag tree and publish the Sparkplug BIRTH sequence to Azure IoT Edge Hub. In the Azure CLI event monitor output you should see the following.

Image Added

If everything went well, you should also see 'Connected' under the Status column.

Step 4: Create tags to be published in Designer

Once the system is showing connected, tags can be created in Ignition Designer. Review the Inductive Automation documentation for Launching Designer against the Ignition gateway

When the Azure Injector modules is installed in Ignition, an Edge Node folder is automatically created in the 'default' Ignition tag provider.

Image Added

Create a tree structure under this folder as shown below with a memory tags - this folder structure creates the same hierarchy that is described in the Sparkplug B specification of Group ID, Edge ID, and Device ID.

Image Added

Step 5: Publishing data

Using the Azure Command Line tools you previously installed on a development machine (from the prereqs here), run the following command

az iot hub monitor-events --hub-name YOUR_HUB_NAME --consumer-group YOUR_CONSUMER_GROUP --timeout 0

You should see a message denoting the monitor is running as follows

Starting event monitor, use ctrl-c to stop...

When the Azure Injector module is installed in Ignition, an Azure Injector tag provider is automatically created. This folder will contain both information tags about the module's version and state, as well as control tags for refreshing the module and Tag Agents.

Make sure that the Ignition Designer has read/write communications turned on by selecting the Project/Comm Read/Write button highlighted in the image below. 

Image Added

To refresh the default Tag Agent, open the folder "Azure Injector Control" and click on the Refresh Boolean. When this happens, the Tag Agent will scan the "Edge Nodes" folder and publish the Sparkplug BIRTH sequence to the Azure IoT Edge Hub.

Image Added

In the Azure CLI event monitor output you should see the following:

{
    "event": {
        "origin": "My-IoT-Edge",
        "payload": "{\"topic\":{\"namespace\":\"spBv1.0\",\"edgeNodeDescriptor\":\"My Group/My Edge Node\",\"groupId\":\"My Group\",\"edgeNodeId\":\"My Edge Node\",\"type\":\"NBIRTH\"},\"payload\":{\"timestamp\":1627401528598,\"metrics\":[{\"name\":\"bdSeq\",\"timestamp\":1627401528573,\"dataType\":\"Int64\",\"value\":0}],\"seq\":0}}"
    }
}
{
    "event": {
        "origin": "My-IoT-Edge",
        "payload": "{\"topic\":{\"namespace\":\"spBv1.0\",\"edgeNodeDescriptor\":\"My Group/My Edge Node\",\"groupId\":\"My Group\",\"edgeNodeId\":\"My Edge Node\",\"deviceId\":\"My Device\",\"type\":\"DBIRTH\"},\"payload\":{\"timestamp\":1627401528604,\"metrics\":[{\"name\":\"My Tag\",\"timestamp\":1627401528604,\"dataType\":\"Int32\",\"metaData\":{},\"properties\":{\"Quality\":{\"type\":\"Int32\",\"value\":192}},\"value\":123

{
    "event": {
        "origin": "My-IoT-Edge",
        "payload": "{\"topic\":{\"namespace\":\"spBv1.0\",\"edgeNodeDescriptor\":\"My Group/My Edge Node\",\"groupId\":\"My Group\",\"edgeNodeId\":\"My Edge Node\",\"type\":\"NBIRTH\"},\"payload\":{\"timestamp\":1627401528598,\"metrics\":[{\"name\":\"bdSeq\",\"timestamp\":1627401528573,\"dataType\":\"Int64\",\"value\":0}],\"seq\":01}}"
    }
}
{
    "event": {
        "origin": "My-IoT-Edge",
        "payload": "{\"topic\":{\"namespace\":\"spBv1.0\",\"edgeNodeDescriptor\":\"My Group/My Edge Node\",\"groupId\":\"My Group\",\"edgeNodeId\":\"My Edge Node\",\"deviceId\":\"My Device\",\"type\":\"DBIRTH\"},\"payload\":{\"timestamp\":1627401528604,\"metrics\":[{\"name\":\"My Tag\",\"timestamp\":1627401528604,\"dataType\":\"Int32\",\"metaData\":{},\"properties\":{\"Quality\":{\"type\":\"Int32\",\"value\":192}},\"value\":123}],\"seq\":1}}"
    }
}

The messages flowing into Azure IoT Edge Hub are also automatically routed to Azure IoT Hub because of the module deployment that was specified in the Azure IoT Edge.

The messages flowing into Azure IoT Edge Hub are also automatically routed to Azure IoT Hub because of the module deployment that was specified in the Azure IoT Edge.

Step 6: Force a data change

At At this point you can also change the value of the tag that was created in Designer. The messages coming out of Azure Injector are 'event driven' meaning that a tag must change for data to flow. By changing Changing the tag value to 122 results in the following message going to Azure Event Hub.

...

{
    "event": {
        "origin": "My-IoT-Edge",
        "payload": "{\"topic\":{\"namespace\":\"spBv1.0\",\"edgeNodeDescriptor\":\"My Group/My Edge Node\",\"groupId\":\"My Group\",\"edgeNodeId\":\"My Edge Node\",\"deviceId\":\"My Device  "origin": "My-IoT-Edge",
        "payload": "{\"topic\":{\"namespace\":\"spBv1.0\",\"typeedgeNodeDescriptor\":\"DDATAMy Group/My Edge Node\"},\"payloadgroupId\":{\"timestampMy Group\":1627403950739,\"metrics\":[{\"nameedgeNodeId\":\"My Edge TagNode\",\"timestampdeviceId\":1627403949486,\"dataTypeMy Device\":,\"Int32type\",:\"valueDDATA\":122}],\"seqpayload\":2}}"
    }
}

Additional Resources

...

• Azure Tutorials/Howtos

...

• https://docs.microsoft.com/en-us/azure/time-series-insights/concepts-ingestion-overview

...

• https://docs.microsoft.com/en-us/azure/time-series-insights/concepts-model-overview

...

• https://inductiveautomation.com/downloads/

...

• https://inductiveautomation.com/downloads/third-party-modules

...

• Check out the Cirrus Link Forum: https://forum.cirrus-link.com/
• Contact support: support@cirrus-link.com

...

• Email: sales@cirrus-link.com
• Phone: +1 (844) 924-7787

{\"timestamp\":1627403950739,\"metrics\":[{\"name\":\"My Tag\",\"timestamp\":1627403949486,\"dataType\":\"Int32\",\"value\":122}],\"seq\":2}}"
    }
}

...