Summary

IoT Bridge for Azure (IBAZ) is an application that connects to an MQTT Server and consumes MQTT Sparkplug messages from Edge devices.

These messages must be formatted as Sparkplug Templates which are defined in the Sparkplug Specification. The Templates are used to create the Models in Azure Digital Twins automatically with no additional coding or configuration.  Then multiple instances of these Templates generate the Assets and start to populate with real time data sent on change only, thus significantly reducing the amount of data being sent to the cloud.

For further details on Azure Digital Twins terminology, refer to the Azure Digital Twins documentation. For further details on Eclipse Sparkplug, refer to the Eclipse Sparkplug resources.

This quickstart document covers how IoT Bridge can be used to consume MQTT Sparkplug data and create and update Azure Digital Twins Asset Models and Assets. This will show how to configure IoT Bridge as well as show how to use Inductive Automation's Ignition platform along with Cirrus Link's MQTT modules to publish device data to an MQTT Server. This data will ultimately be consumed by IoT Bridge to create and update the Azure Digital Twins components.

This tutorial will use the MQTT Distributor implementation however the IBAZ does work with any MQTT v3.1.1 compliant MQTT Server.


Ignition in conjunction with Cirrus Link's MQTT Transmission module converts Ignition User Defined Types (UDTs) to Sparkplug Templates. This is done automatically by the MQTT Transmission module. So, much of this document will refer to UDTs rather than Sparkplug Templates since that is what they are in Ignition.

More information on Inductive Automation's Ignition platform can be found here. Additional information on Cirrus Link's MQTT Transmission module can be found here.


Step 1: IBAZ Installation

  • Complete the IBAZ Installation process
  • This will install the Virtual machine, Disk, Network interface and Public IP address resources

Step 2: Create an Azure Digital Twins instance

Step 3: Configure the Azure Digital Twins instance

Step 4: Create an event Hubs Namespace

Step 5: Create an Azure Data Explorer Cluster

Step 6: Configure the Azure Data Explorer Cluster

  • Configure the database permissions to add your Azure Digital Twins Instance with a Database Admin role
  • Add additional Viewer role(s) to be able to query data

Step 7: Configure the Azure Digital Twins instance data history connection

Step 8: Create an Azure Active Directory App Registration


In our example below we have all the resources in the same Resource group:

Step 9: Install Ignition and MQTT Modules

For this setup, we'll install Inductive Automation's Ignition platform along with the MQTT Distributor (MQTT Server) and MQTT Transmission (Edge device) modules from Cirrus Link.

Installation of Ignition is very straightforward following the instructions in the Installing and Upgrading Ignition guide.

With Ignition installed, the Cirrus Link modules must be installed as a plugin to Ignition. Follow the instructions in our Module Installation guide.

Step 10: IBAZ Configuration

Update your configuration properties in the IBAZ configuration file located on the VM at /opt/ibaz/conf/ibaz.properties.  Instructions for accessing the VM can be found here.

Follow our IBAZ configuration guide for details.

With the default MQTT Distributor configuration use the following properties:

mqtt_server_url = tcp://youripaddress of installed Ignition instance:1883

mqtt_username = admin

mqtt_password = changeme


Now the IBAZ service can be restarted to pick up the new configuration. Do so by running the following command.

sudo systemctl restart ibaz


At this point, IBAZ should connect to MQTT Distributor and be ready to receive MQTT Sparkplug messages. Verify by running the following command.

tail -f /opt/ibaz/log/wrapper.log


After doing so, you should see something similar to what is shown below.

Note the last line is 'MQTT Client connected to ...'. and this indicates that we have successfully configured IBAZ and properly provisioned MQTT Distributor.



Now we can configure our Ignition MQTT Transmission module to connect to the MQTT Distributor server in order to publish data into Azure. We will also import some UDT Definitions and UDT Instances that will be mapped to Azure Models and Digital Twins.

Step 11: Import UDTs and tags

For this quick start, we have created a number of sample UDTs and associated tags that can be easily imported. Using the Ignition Designer, import these UDTs and tags into the default Tag Browser.

IBAZ_quickstart_UDTs.json

IBAZ_quickstart_tags.json

Once imported, you can browse into each tag to see the structure of the UDT and UDT Instances.



Refer to Inductive Automations Exporting and Importing Tags documentation if you are unfamiliar with importing tags.

Step 12: Edge Device Configuration

Now we can configure the MQTT Transmission module to connect to MQTT Distributor. From the left hand menu bar in Ignition, select MQTT Transmission > Settings.

Select the Transmitters tab and edit the Default Transmitter by setting the following properties:

  • Tag Path = Azure Smart Factory
  • Convert UDTs = Unchecked
  • Publish UDT Definitions = Checked
  • Optimize UDTs = Checked


Once this configuration is saved, you can confirm you are connected by switching to the Servers tab and verifying that the Connected status shows 1 of 1


Step 13: Confirm connection with the Azure Digital Twins Explorer

Navigate to your Azure Digital Twins Explorer by clicking on the Overview for your Azure Digital twins and selecting the Open Azure Digital Twins Explorer (preview) link at the top



This will display the Azure Digital Twins Explorer view:


Run Query as SELECT * FROM digitaltwins and you will see two digital twins created; one for the IBAZ instance and one for the connected MQTT Client

Refer to the IBAZ: Mappings and Constraints document for details on digital twin properties


From Ignition Designer, refresh Transmission to publish the edge node tags to Azure 

Run Query as SELECT * FROM digitaltwins and also refresh your MODELS. Now you will see that that Digital Twins have been created for each of your UDT Instances and an addition digital twin containing metrics for the edge node.



You can drill into each Digital Twin by selecting the twin and verifying the associated data by checking the Twin Properties. From the Edge Device, change the tag values and see that they are updated.



You will need to Run Query each time to see refreshed data through the Azure Digital Twins Explorer UI.

If you looking to query data on a single digital twin, you can modify the query using the WHERE statement for example: SELECT * FROM digitaltwins WHERE $dtId = 'Smart_Factory_1%2FFactory_Energy%2FLine_3%2FPaint_Booth'


Step 14: Confirm data in database

Navigate to your Azure Data Cluster Explorer and select Databases from the left hand menu bar.


Click on the link for your database and select Query from the left hand menu bar:



You can now query the data using the Azure Data Explorer tooling to view the data from each of the digital twins.

Data received by Azure Digital Twins Explorer can take up to 5 minutes to be available in Azure Data Explorer



Now the data is in the cloud, there are existing Microsoft documentation useful for processing this data for managing anomaly detection, active monitoring and trending/reporting.  The reference links are include below: