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.
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.|
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
- If needed create following the Microsoft Set up an Azure Digital Twins instance and authentication (portal) instructions
- Collect the Host name as this is used in the IBAZ: Configuration
Step 3: Configure the Azure Digital Twins instance
- Assign the Azure Digital Twins Data Owner role to your Azure Active Directory app registration identity and an additional Azure user(s)
- Add a system-managed identity to your instance
Step 4: Create an event Hubs Namespace
- If needed create following the Microsoft Create an event hub using Azure portal instructions
Step 5: Create an Azure Data Explorer Cluster
- If needed create following the Microsoft Create an Azure Data Explorer cluster and database instructions
Step 6: Configure the Azure Data Explorer Cluster
- Configure the database permissions to add your Azure Digital Twins Instance with a Database Admin role (may happen as part of setting up Data History on your Azure Digital Twins Service instance above)
- 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
- If needed create following the Microsoft Create an app registration to use with Azure Digital Twins instructions
- Collect the client ID, tenant ID and Client secret Value as these are used in the IBAZ: Configuration
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.
At this point, IBAZ should connect to MQTT Distributor and be ready to receive MQTT Sparkplug messages. Verify by running the following command.
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.
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|