Connectware & Azure IoT Hub Integration

Ragavendra Lingamaneni 2020-07-30

Prerequisites

In this lesson, we will send data published on Connectware MQTT Broker to Azure IoT Hub. It is required that you already have Connectware and Azure IoT Hub setup. We assume you are already familiar with Connectware and its service concept. If not, please head over to articles Connectware Technical Overview and Service Basics for a quick introduction. Further, this lesson requires basic understanding of MQTT and how to publish data on a MQTT topic. If you want to refresh your MQTT skills, please refer to following lessons MQTT Basics and How to connect an MQTT client to publish and subscribe data.

Introduction

This article is divided into two parts. In the first part, a general background about Azure IoT services and their differences is described. Feel free to skip this section if you are familiar with Azure IoT Hub and the difference between IoT Edge Runtime and IoT Device SDKs. In the second part, current integration mechanisms between Connectware and Azure IoT Hub are explained in an hands-on approach.

Azure IoT Hub

IoT Hub is a core component of the Azure IoT offerings. It is a fully managed service that enables reliable and secure bi-directional communications between IoT devices and an application back-end. Azure IoT Hub offers reliable device-to-cloud and cloud-to-device hyper-scale messaging, enables secure communications using per-device security credentials and access control, and includes device libraries for the most popular languages and platforms.

There are two ways you can send data to Azure IoT Hub which are described below.

Azure IoT Hub Edge

Azure IoT Edge lets you offload parts of your IoT workload from your Azure cloud services to your devices. IoT Edge can reduce latency in your solution, reduce the amount of data your devices exchange with the cloud, and enable off-line scenarios. You can manage IoT Edge devices from IoT Central and some solution accelerators.

Azure IoT Edge is made up of three components:

  • Edge modules: These are containers which are deployed on the edge devices and run Azure and other third-party services. You can build your own modules to send telemetry to the IoT Hub.
  • Edge runtime: It runs on each IoT Edge device and manages the modules deployed to each device.
  • Web interface: A cloud-based interface is used to remotely monitor and manage IoT Edge devices.

Azure IoT Edge Architecture

Azure IoT Hub Device SDKs

IoT Hub Device SDKs enable you to build apps that run on your IoT devices. These apps send telemetry to your IoT Hub, and optionally receive messages, job, method, or twin updates from your IoT Hub. The device SDKs support multiple operating systems, such as Linux, Windows, and real-time operating systems. There are SDKs for multiple programming languages, such as C, Node.js, Java, .NET, and Python.

Connectware & Azure IoT Hub Integration

Before proceeding further, setup Azure IoT Hub if you haven't already and get the device connection string. You can follow the instructions on this page for the same.

Data exchange between Azure IoT Hub and Connectware is possible in a couple of ways which are described below.

Cybus Azure IoT Hub connector service

Azure-IoT-Connector is a Cybus provided service available as a docker image. It uses Azure IoT Hub Device Node.js SDK and MQTT as transport protocol. This is a simple solution to send data to the IoT Hub and much of the complexity is obfuscated and a simple interface is provided for configuration in the form of "connector configuration". This service is capable of sending telemetry data and blob data to the IoT Hub and does not support receiving data from the IoT Hub. Additionally, data buffering is build in so that data is stored locally when there is a temporary disruption of connection to the IoT Hub.

Below commissioning file sends data published on topics '/machine/temperature' and '/machine/vibration' as telemetry data to Azure IoT Hub. Before installing the service, make sure you are publishing data on the Connectware broker on topics '/machine/temperature' and '/machine/vibration'. Please follow the instructions in the tutorial How to connect an MQTT client to publish and subscribe data if you are not sure how to do it.

description: >
    Azure IoT Hub connector service

metadata:
  name: Azure IoT Hub connector
  icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg
  provider: cybus
  homepage: https://www.cybus.io
  version: 0.0.1

definitions:
  MQTT_ROOT_TOPIC : !ref Mqtt_Root_Topic

parameters:

  Azure_Iot_Hub_Connection_String:
    type: string

  Mqtt_Root_Topic:
    type: string
    default: machine

resources:

  #----------------------------------------------------------------------------
  # Cybus Azure IoT Hub Connector Service
  #----------------------------------------------------------------------------

  azureIoTConnector:
    type: Cybus::Container
    properties:
      image: registry.cybus.io/cybus-services/azure-iot-connector:0.0.5
      environment:
        LOG_LEVEL: 'info'
        CONNECTOR_CONFIG: !sub  |
          {
            "general": {
              "name": "Azure Connector"
            },
            "source": {
              "driver": "azure.iot",
              "connection": {
                "connectionString": "${Azure_Iot_Hub_Connection_String}"
              },
              "defaults": {
                "operation": "write"
              }
            },
            "target": {
              "driver": "mqtt",
              "connection": {
                "protocol": "mqtt",
                "host": ${Cybus::MqttHost},
                "port": ${Cybus::MqttPort},
                "username": ${Cybus::MqttUser},
                "password": ${Cybus::MqttPassword}
              },
              "defaults": {
                "operation": "subscribe",
                "topicPrefix": "${Mqtt_Root_Topic}"
              }
            },
            "mappings": [
              {
                "source": {
                  "name": "temperature",
                  "type": "telemetry"
                },
                "target": {
                  "topic": "temperature"
                }
              },
              {
                "source": {
                  "name": "vibration",
                  "type": "telemetry"
                },
                "target": {
                  "topic": "vibration"
                }
              }
            ]
          }

azure-iot-connector container is passed with CONNECTOR_CONFIG environment variable. This JSON object has three important parts :

  • Source configuration

    In the source section, only configurable paramater is the device 'connectionString' to connect to a particular device on Azure IoT Hub. This string is defined as a paramater for the service commissioning file and asked during the installation on the service.

  • Target configuration

    In this section, MQTT broker connection parameters are defined. Any MQTT broker can be specified and in this case Connectware broker is used. Optionally, a default MQTT topic prefix can be specified within this section.

  • Mappings

    Every object within the mappings array defines a mapping between source type which corresponds to IoT Hub device parameter and target MQTT topic (on the Connectware broker). In the above commissioning file, we are sending data published on topics 'temperature' and 'vibration' to IoT Hub as telemetry data with corresponding name.

Cybus workbench service

Workbench service is basically a Node-Red application running securely on the Connectware as a service. This opens up the possibility to install any node-red nodes within the service container for quick prototyping as well as for production environment. If your use-case cannot be achieved with the above service commissioning file, using the workbench will give you some flexibility and additional tools to prototype your solution using third party node-red modules.

node-red-contrib-azure-iot-hub is a Node-RED module that allows you to send messages and register devices with Azure IoT Hub. It contains a total of four Node-RED cloud nodes: Azure IoT Hub, Azure IoT Registry, Azure IoT Hub Receiver and Azure IoT Hub Device Twin. These nodes can be used for configuring more complex data handling.

Azure IoT Hub Node Red nodes

Tools

Now that we are successfully sending the data to the IoT Hub, we can monitor the sent data using various tools described below.

Azure IoT Tools for Visual Studio Code

Azure IoT Tools is a collection of VS code extensions for working with Azure IoT Hub. Using these extensions, you can interact with an Azure loT Hub, manage connected devices, and enable distributed tracing for your Azure loT applications. Further, you can easily subscribe to telemetry messages sent to the IoT Hub for quick testing. Please go to Visual Studio Marketplace to find further documentation regarding installation and usage of the Azure IoT tools.

Azure IoT Tools for Visual Studio Code

Azure IoT Explorer

Azure IoT Explorer is an open source cross-platform UI for interacting with Azure IoT Hub without logging into the Azure portal. This tool can be used to perform tasks like creating, deleting and quering devices within the IoT Hub. Device functionalities such as sending and receive telemetry and editing device and module twin configuration is also possible with this tool. You can find more information about the explorer on its GitHub page.

Azure IoT Explorer

Summary

In this lesson, you had a quick introduction to Azure IoT Hub and it's various components & SDKs available for integration with other services. Then we shared how to send data from Connectware MQTT Broker to Azure IoT Hub using a simple commissioning file using azure-iot-connector. Additionally, you were introduced to IoT Hub Node Red modules which can be used with Cybus workbench service for prototyping more advanced scenarios. In the end, we shared some of the tools used by us for monitoring data flow between Azure IoT Hub and Connectware.

Where to go from here

You can take a look at more advanced scenarios involving Azure IoT Hub such as Machine Condition Monitoring in Connectware documentation pages.