Azure IoT Hub Connector¶

NEW: Federation Support

An integration with Azure IoT Core is now easier using Exosite's Device Cloud Federation API.

Contact Exosite support for more information.

The following information walks through setting up the IoT Connector integration to Azure IoT Hub.

Prerequisites¶

In Azure¶

The cost of operating the Microsoft Azure services is something to keep in mind, which is outside of the Exosite software and offering.

Have an IoT Hub Service in Microsoft Azure with device telemetry being reported to it
Ensure MS EventGrid is registered/enabled in the account

Info

EventGrid is enabled through the subscription service on the Azure account. Select the subscription service, then "Resource Providers". Select Microsoft.EventGrid, then "Register".

In Exosite¶

An Exosite account with an instance of ExoSense.

Add the IoT Connector Template in Exosite¶

Inside of your Exosite's platform account, navigate to the Azure IoT Hub Connector Template in the IoT Marketplace.

Azure IoT Connector card in the Exosite IoT Marketplace

Select "Create IoT Connector" and select a name for the connector. In this example, we will have our IoT Connector named "Azure IoT Hub Connector"

Add Device Configuration¶

In the newly created IoT Connector, we need to define the configuration of the devices that are sending data. That is what data channels will be sent, and what types of data is it.

Modify the module vendor.configIO to define the device channels. An example configuration is already there to get started. More information on format of this configuration can be found here. Additionally, the available data types and data units can be found here.

Connector vendor.configIO Module configuration

Connect from Azure¶

In Azure, we are going to create an "Event Subscription" to forward data to Exosite when it is received at the IoT Hub Service in Azure.

Warning

From Azure the data format is assumed to be of a JSON type with a key/value pairing of a channel_id and the data value. In the default example, the channel ids are "temperature", "humidity", and "pressure".

If the data is not in this format, the module vendor.azure_utils will need to be modified to transform the data into this format. Contact support for assistance.

Create a new Event Subscription using the following settings:

Event Property	Setting
Event Schema	`Event Grid Schema`
Topic Type	`Azure IoT Hub Account`
Filter to Event Types	All 5 event types
Endpoint Type	`Web Hook`
Endpoint	`https://<SolutionDomain>/vendor/data_in`

The SolutionDomain is specific to your Exosite IoT Connector Solution which has a webservice enabled. This solution domain is diffrent then the IoT Connector's Device API endpoint. See below for details on finding this.

Finding and using the IoT Connector's Solution Endpoint Domain

The Solution ID of your IoT Connector can be found from inside the connector management page by selecting the "www" icon in the upper left corner. This will open a new browser window or tab to the solution domain. Copy this. The format is <solution>.apps.exosite.io and the full endpoint that is needed is https://<solution>.apps.exosite.io/vendor/data_in.

Translate Data¶

The data being transmitted from Azure will likely need to be translated to be consumed by ExoSense.

To translate the data, modify the module vendor.azure_utils in your IoT Connector.

In this module, modify the function azure_utils.handle_telemetry. In this function:

Identify the deviceID and set it to the corresponding variable.
Populate the data_in variable with an dictionary of key/value pairs. (Where the keys correspond to a channel_id in the config_io)

Handling Base64 encoded payloads

If your data is Base64 encoded, you can decode the data with

base64 = require('vendor.base64')
data = base64.decode(data)

Connecting to ExoSense¶

Once the Event Subscription is created, new devices should appear in the Devices tab of the IoT Connector in the Exosite IoT Platform.

To connect these devices to ExoSense. select ADD TO SOLUTION and select your ExoSense Instance to connect your connector service to from the Marketplace.

Next Steps¶

You can now claim the devices in the connector from ExoSense and create Assets to visualize the incoming data.