View Source

Imports scalar data from iot devices connected to the Azure IOT Hub: https://azure.microsoft.com/en-us/services/iot-hub/

Overview

Available since 2020.01.

The AzureIotHub Import connects to the built-in endpoint of the Azure IOT Hub. By default the IOT Hub exposes the endpoint as an Azure Service Bus compatible endpoint. This allows clients to connect using the AMQPS protocol, which is used by the AzureIotHub import. The default port for AMQPS is port 5671 and a forecasting shell server should be allowed to connect to the Azure IOT Hub using this port from the Forecasting Shell Server.

The AzureIotHub import is a long running import that will keep running for one hour and will keep listening voor messages to arrive. After one hour the import will finish and state is store to keep track of the messages that have been imported. Since the import is completed after one hour, imports should be scheduled hourly and the import should never run in parallel on multiple Forecasting Shell Servers.

The current implementation only supports PI XML as content format.

Import Configuration

General Section

importType: AzureIotHub
serverUrl: a valid URL is required, but is used for informational purposes only and will be displayed in the import status. It can be set to the event hub domain url, for example: https://delft-fews-iot-hub.azure-devices.net
dataFeedId: required and can be set to any unique dataFeedId. For example: Delft-FEWS Azure IOT Hub

Properties

To configure the AzureIotHub import, some required properties have to be specified:

Property name	Description	Example value	Azure Portal Screenshot
eventHubCompatiblePath consumersGroup		iothub-ehub-delft-fews-3109254-e665c23b62 $Default	AzureIotHub-Built-inendpoint
eventHubCompatibleHostname		ihsuprodamres086dednamespace.servicebus.windows.net	AzureIotHub-Built-inendpoint
numberOfPartitions		2	AzureIotHub-Built-inendpoint
sharedAccessPolicyName		service	AzureIotHub-SharedAccessPolicies
sharedAccessPolicyKey		V86dqC3AhjIqSgvAuShKDSsNamUJh5rJrqZ1e3hw7EA=	AzureIotHub-SharedAccessPolicies
runningTimeMilliseconds	Optional property. Specifies how long the import will run in milliseconds. Default is one hour. Should only be changed for testing.	120000	not relevant

Example Import Configuration

This example is configured to import scalar observations from the Azure IOT Hub

<?xml version="1.0" encoding="UTF-8"?>
<timeSeriesImportRun xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews
http://fews.wldelft.nl/schemas/version1.0/timeSeriesImportRun.xsd">
	<import>
		<general>	
            <importType>AzureIotHub</importType>
			<serverUrl>https://delft-fews-iot-hub.azure-devices.net</serverUrl> <!-- Not actually used -->
   			<relativeViewPeriod unit="day" start="-7" end="1" ></relativeViewPeriod>
            <missingValue>-99.99</missingValue>
            <dataFeedId>Azure IOT Hub</dataFeedId> <!-- data feed id is required for IOT hub -->
        </general>
		<properties>
			<string key="eventHubCompatiblePath" value="iothub-ehub-delft-fews-3109254-e665c23b62" />
			<string key="consumersGroup" value="$Default" />
			<string key="eventHubCompatibleHostname" value="ihsuprodamres086dednamespace.servicebus.windows.net" />			
			<string key="sharedAccessPolicyName" value="service" />			
			<string key="sharedAccessPolicyKey" value="V86dqC3AhjIqSgvAuShKDSsNamUJh5rJrqZ1e3hw7EA=" />			
			<int key="numberOfPartitions" value="2" />
			<int key="runningTimeMilliseconds" value="120000" /> <!-- run for 2 minutes for testing. Overrules the default running time of one hour -->
		</properties>	
		<timeSeriesSet>
			<moduleInstanceId>ImportObserved</moduleInstanceId>
			<valueType>scalar</valueType>
			<parameterId>T.obs</parameterId>
			<locationSetId>LocationSetId</locationSetId>
			<timeSeriesType>external historical</timeSeriesType>
			<timeStep unit="nonequidistant"/>
			<readWriteMode>add originals</readWriteMode>
			<expiryTime unit="year" multiplier="1"/>
		</timeSeriesSet>
	</import>
</timeSeriesImportRun>

Azure Portal

To configure the AzureIotHub some information from the Azure Portal is required. This sections shows the relevant parts of the Azure Portal to set the required properties.

Built-in endpoint

From the Azure IOT Hub built-in endpoint page, the following properties can be determined:

numberOfPartitions: set to 2 in this example
consumersGroup: Set the $Default in this example

eventHubCompatibleHostname: ihsuprodamres086dednamespace.servicebus.windows.net

eventHubCompatiblePath: iothub-ehub-delft-fews-3109254-e665c23b62

DELFT-FEWS Documentation > AzureIotHub > image2020-4-15_12-5-48.png

Shared Access Policies

From the Azure IOT Hub shared access policies page, the following properties can be determined:

sharedAccessPolicyName: set to 2 in service. If a custom policy is used, make sure at least the Service connect permissing has been assigned to the policy.
sharedAccessPolicyKey: Either the Primary Key or Secondary key can be used for that. It should be similar to: V86dqC3AhjIqSgvAuShKDSsNamUJh5rJrqZ1e3hw7EA=

DELFT-FEWS Documentation > AzureIotHub > image2020-4-15_12-50-26.png

Testing

To be able to send test messages to the Azure IoT Hub, a device has to be registered. See the following example of the Azure Portal where on the IoT device a device has been registered called "deltares-test-iot-device".

DELFT-FEWS Documentation > AzureIotHub > image2020-4-15_13-8-22.png

DELFT-FEWS Documentation > AzureIotHub > image2020-4-15_13-10-12.png

There are different ways to test the import.

Microsoft Visual Studio Code has a IoT Hub extension that can be used to send Device to Cloud messages (D2C messages). See the following screenshot to see how to send a D2C message from the test client.