Overview

This section explains how to provision a gateway and how to connect to the Azure IoT Services using a Connection String. This connection method is used directly with the IoT Hub.

If connecting only via Transparent Gateway, continue to the next section and ignore any steps mentioning Module Client.

If connecting only via Module Client, provisioning the device is not needed, so skip to here. A parent device does need to be created in IoT Hub for the module client in order to get a working connection though.

If connecting via Transparent Gateway and Module Client, follow all instructions on this page to create a combined Connection String.

🚧

ESF Cloud Connector for Azure IoT, Version 2.0.0 and Above Only

These instructions apply to the ESF Cloud Connector for Azure IoT, Version 2.0.0 and above. See Legacy v2 Azure IoT Connection if you are using any version under 2.0.0.

Provision Device

Go to your IoT Hub in the Azure Portal.

Note: This is in your IoT Hub, not your IoT Hub DPS. Ensure the Azure resource type is IoT Hub when you are selecting the resource.

Go to the Devices page and click + Add Device.

On the Create a device page, enter the following information:

• Device ID: This can be any unique designator. A good method to ensure this is unique is to use the gateway's MAC address and serial number (in the format [MACAddress]-[SerialNumber])
• Authentication Type: Symmetric Key
• Primary key: Leave blank (will be auto-generated)
• Secondary key: Leave blank (will be auto-generated)
• Auto-generate keys: Ensure this box is checked
• Select a parent device if using a Transparent Gateway configuration
• All other fields: Leave at the default values

Click Save.

Create a Connection String cloud connection

In the ESF Web interface, go to the Cloud Connection section and click New Connection.

On the New Cloud Connection dialog, enter the following information:

• Cloud Connection Factory PID: AzureConnectionString
• Cloud Connection Service PID: AzureConnectionString or other valid Cloud Connection Service PID

Click Apply.

Select the new connection and go to the ConnectionStringMqttDataTransport tab.

Select the appropriate Device Model ID from the list of options. If a device model does not need to be specified your application, leave the default 'None' field'. Set the 'Device Model ID Version' to the appropriate version of the Device Model.

For Transparent Gateway Configurations

If the gateway is being used in a Transparent Gateway configuration, then specify the correct location of the required certificate if it differs from the default location. For the Connection String for a Transparent Gateway, go to the Devices page in your IoT Hub. The Azure Portal should have already directed you here after creating the new device. Locate your device on the list of devices and click its Device ID to go to the device details page.

Additionally, the connection string must contain "GatewayHostName=" in it, so that the Azure Cloud Connector will be able to identify it as a transparent gateway connection. The hostname used in the Azure Iot config file hosted on the gateway should be the value of GatewayHostName in the connection string.

For Module Client Configurations

Follow the instructions at the following page for generating the connection string for ESF: https://azure.github.io/iot-identity-service/develop-an-agent.html#sas-authentication-with-a-connection-string-walkthrough

The module id must be included in the connection string as well i.e. ModuleId={module_id}. The module id must match the configuration file for the module that will connect to Iot Edge.

Copy the Primary Connection String and paste it into the Connection String in ESF.

📘

Copying the Connection String

Copying the connection string in the Azure Portal can be accomplished by clicking the "copy" icon to the right of the Primary Connection String field, or by making the connection string visible by clicking the eyeball icon and manually selecting and copying the connection string.