Azure IoT Hub

Particle and Microsoft have teamed up to provide a 1st-class integration with Azure IoT Hub. Azure IoT Hub provides a seamless way to send Particle device data into Azure, effective both during prototyping and when at scale.

Send device data from Particle into Azure IoT Hub with ease

Acting as the "front door" to Azure, streaming from Particle into IoT Hub will make it easy to forward device data onto any of Azure's products to add intelligence and robustness to your IoT product or application. Here are some examples of things you could do with Particle + Azure IoT Hub:

• Predict when a piece of equipment needs maintenance ahead of time using predictive analytics
• Detect anomalies in product behavior by analyzing device data from an entire fleet simultaneously
• Trigger a notification to a device owner when supplies are running low

Some of the most relevant Azure products to use with Particle are:

• Stream Analytics: Real time data stream processing from millions of IoT devices
• Machine Learning: Powerful cloud based predictive analytics tool to enable predictive maintenance
• Notification Hubs: A scalable, push notification engine for quickly sending millions of messages
• Power BI: A suite of business analytics tools to analyze data and share insights.

Send device data into Azure through IoT Hub, then onto other Azure products

Note that Azure IoT Hub has many features, but the main focus of this integration as it currently exists is to provide one-way event ingestion from Particle to Azure IoT Hub (and then onto other Azure products).

Key concepts in IoT hub

Before using this integration, it is helpful to understand a few key concepts fundamental to how Azure IoT Hub works. These concepts will come up during use of the IoT Hub integration.

Device identities and identity registry

From IoT Hub's documentation:

"Every IoT Hub has an identity registry that stores information about the devices that are permitted to connect to the IoT hub. Before a device can connect to an IoT hub, there must be an entry for that device in the IoT hub's identity registry."

Each Particle device that triggers this integration will have its counterpart device identity in your IoT Hub. The Particle cloud will manage this entirely for you, there is no need to manually create your own device identities for your fleet of Particle devices.

The identity in the IoT Hub registry will be created with the same device ID as used in the Particle system for easy correlation of data and events. The identity will be created automatically in your Hub the first time an approved device publishes an event that triggers the integration.

Device-to-cloud message

Related to device identities are device-to-cloud messages. Each device in the IoT Hub registry has its own unique messaging stream. This allows the Particle cloud to publish messages on behalf of individual devices to their corresponding stream.

From IoT Hub's documentation:

"Use device-to-cloud messages for sending time series telemetry and alerts from your device...You send device-to-cloud messages through a device-facing endpoint"

The Particle cloud will ensure that events emitted from a given device in your fleet will be sent as a device-to-cloud message to the correct device-specific stream. Specifically, when a device executes Particle.publish() in its firmware with a matching event name, this event (plus its included data) will be sent to it's corresponding message stream in IoT Hub.

Shared access policy

The Particle cloud must successfully authenticate with your IoT Hub to have permissions to both manage the device identity registry as well as publish device-to-cloud messages. This is done through the use of shared access policies.

From IoT Hub's documentation:

"Shared access policies can grant any combination of permissions...Azure IoT Hub grants access to endpoints by verifying a token against the shared access policies"

Each policy can be scoped to be granted permissions to interact with the IoT Hub in various ways. It is important that the access policy given to Particle to authenticate with your IoT Hub has the right permissions to send device data successfully.

For a full description of authentication and security on Azure IoT Hub, please visit the Developer guide on security.

Device twin

The device twin is a virtual representation of a device's state in IoT Hub, stored as JSON. Particle will use the twin in IoT Hub to sync a device's name in the Particle cloud with Azure. Device name syncing happens once, at the time of creation in the IoT Hub device registry. If no name exists for the device at this time, this step will be skipped. Check out the section on confirming data reaches Azure for details on how to access the name from the device twin once it's synced.

Note: Device name syncing with IoT Hub requires that you provide a shared access policy to Particle that has the "service connect" permission enabled when creating the integration.

Preconfiguration in Azure IoT hub

You will need to do some setup in Azure IoT Hub before your integration will function successfully. Follow the steps outlined below to get started. Most of this information is also available when you enable the Azure IoT Hub integration on the Particle Console.

Sign up for an azure account

If you don't already have one, you'll need to sign up for an Azure account to use this integration.

Visit the Microsoft Azure signup page. Click the "Try for free" button, and follow the instructions to register for a new account. Upon signup, you will be given $200 in Microsoft Azure credit.

For more details on Azure pricing, please check out Azure's pricing overview.

Create an azure IoT hub

Once you have created an Azure account, the next step is to create an Azure IoT Hub. You will need to create an Azure IoT Hub to receive events from your fleet of Particle devices. The Particle cloud will communicate directly with your IoT Hub when devices in your fleet publish events that trigger the integration.

Navigate to IoT hub

In your Azure portal, click the + icon in the side bar, then click Internet of Things > IoT Hub.

Configure new IoT hub

A new IoT Hub blade will appear. Fill out all required fields of the form. For detailed information on how to configure an IoT Hub for your specific needs, please visit the IoT Hub Developer Documentation.

Want to get started quickly? If you are looking to test out the Azure IoT Hub integration with a small number of devices, use the configuration below:

Heads up! A few things to point out when configuring your IoT Hub:

• A free IoT Hub cannot be converted to a paid tier once created
• You will need your IoT Hub Name to enable the integration successfully in the next step

When you're ready, click the Create button. It will take a few minutes for Azure to successfully provision your new IoT Hub.

Add a shared access policy

You will need to provide Particle with a shared access policy to allow the Particle cloud to create Azure IoT Hub device identities on your behalf. For security reasons, you should create a separate access policy specifically for this integration.

Create the new policy

Once your IoT Hub has been successfully created, click on its icon from your Azure portal dashboard. Then, click Shared access policies > + Add from the IoT Hub blade. Give your policy a name, and ensure that you give your new policy registry read, registry write, service connect, and device connect permissions (check all the boxes) as shown below:

When you're ready, click Create to add the new shared access policy. It will take a few moments for Azure to create your new policy successfully.

Retrieve relevant policy info

To enable this integration successfully, you will need both the policy name as well as the policy primary key. You can access this information at any time by clicking on your new policy from the list of shared access policies for your IoT Hub.

Awesome! You now have everything you need to move on to enabling the integration on the Particle Console.

Enabling the integration

Particle Console

Now that you've done all of the pre-configuration required, you are now ready to enable the Azure IoT Hub integration on the Particle Console.

Start by going to the integrations hub by clicking on the integrations icon in the sidebar (), or by simply following this link. If you'd like to enable the integration for a product, you'll need to visit the integrations hub for the desired product. Do this by clicking the products icon () in the sidebar, finding your product, then clicking on the integrations icon () in the product context.

Once in the integrations hub, click on the "New Integration" button. From the list of available integrations, click on "Azure IoT Hub".

You'll see a reminder that setup is required before continuing to enable the integration. If you have followed the steps outlined in Preconfiguration in Azure IoT Hub, you should be good to go. Click the "I have done all these things" button to advance.

The next step is configuring the integration. Fill out the following fields:

• Event Name: The name of the event that will trigger publishing an event to Azure IoT Hub. This is the name of your event when you call Particle.publish() in your firmware.
• IoT Hub Name: The name given when you created your Azure IoT Hub
• Shared Policy Name: The name of the Azure shared policy that you created during setup
• Shared Policy Key: The associated key of the Azure shared policy that you created during setup
• Device: Select which of your devices will trigger publishing to Azure. If you'd like the publish to trigger from any of the devices you own, select 'Any.'

Click "Enable Integration." You have now successfully told the Particle cloud to stream data to Azure IoT Hub! Make sure that the integration is configured properly by clicking on the TEST button (available for integrations not scoped to a single device).

Firmware

Now that the integration is enabled in the Particle cloud, the final step required to get data streaming into Azure IoT Hub is to flash a device with some firmware that publishes the targeted event. Head over to the Particle Web IDE, Local IDE, or whichever IDE you are using for firmware development.

If you're already working on a firmware application, just make sure you include a Particle.publish() with the event name matching the event used to enable the IoT Hub integration above. Otherwise, if you need some sample firmware, paste in the below code into your firmware app:

// The on-board LED
int led = D7;

void setup() {
  pinMode(led, OUTPUT);
}
void loop() {
  // Turn the LED Off
  digitalWrite(led, HIGH);
  // Publish an event to trigger the integration
  // Replace "my-event" with the event name you used when configuring the integration
  // Replace "test-data" with the real data you'd like to send to Azure
  // IoT Hub
  Particle.publish("my-event", "test-data", PRIVATE);
  // Wait for 3 seconds
  delay(3000);
  // Turn the LED off
  digitalWrite(led, LOW);
  delay(3000);
}

The above code will publish an event every 6 seconds, when the on-board LED turns on. In reality, you might publish an event containing the readings from a temperature or humidity sensor every few minutes, when motion is detected, or when a user interacts with the device by pushing a button. This firmware is entirely meant as a sample to illustrate the minimum code needed to stream data into Azure IoT Hub.

Go ahead and flash the firmware with the Particle.publish() that will trigger the integration to a Particle device.

Once confident in the firmware, you can stream data from large numbers of devices by rolling out the firmware to a product fleet. Remember that this requires creating the integration under the product scope, allowing any device in the product fleet to trigger the it.

Congrats! This is all you need to get the integration working end-to-end. Your device will now begin to publish the targeted event, which will signal to the Particle cloud to send a device-to-cloud message to IoT Hub.

Confirming the data reaches azure IoT hub

To ensure that the data is successfully being published to Azure IoT Hub, you can use the Azure CLI IoT Extension, an Node-based command line interface (CLI).

Install the IoT Hub explorer and run the following command:

az iot hub monitor-events [particle-device-id] --login [IoT-Hub-connection-string]

Example:

az iot hub monitor-events 2a003123456789012345678 --login "HostName=iothubfreeblahblah.azure-devices.net;SharedAccessKeyName=particle-iot-hub;SharedAccessKey=CNZ6PARTICLEwerISfasdfTHElkhaeBESTg/ked="

You can find your Hub's connection string in the Azure portal by clicking Shared access policies > iothubowner > then click the clipboard next to Connection string--primary key.

You can find your IoT Hub connection string in the shared access policies view

You should see output like this in your terminal:

Monitoring events from device 3e003f000547343233323032...
{
  "data": "70",
  "device_id": "3e003f000547343233323032",
  "event": "temperature",
  "published_at": "2016-12-02T02:12:28.825Z",
  "fw_version": "1"
}
-------------------
{
  "data": "70",
  "device_id": "3e003f000547343233323032",
  "event": "temperature",
  "published_at": "2016-12-02T02:12:28.825Z"
}
-------------------
{
  "data": "69",
  "device_id": "3e003f000547343233323032",
  "event": "temperature",
  "published_at": "2016-12-02T02:12:34.821Z",
  "fw_version": "1"
}
-------------------

In addition, you should now see this Particle device ID appear in your device registry:

Yay! You are successfully sending data from Particle devices to your IoT Hub.

If you'd like to get the device name from IoT Hub that was synced from Particle, you can run the following command:

iothub-explorer get-twin <device-id>

and you should see the deviceName attribute in the output:

...
properties:
  desired:
    deviceName: <device-name>
        ...
deviceId: <device-id>

Example use cases

After you have connected your device to IoT Hub, you can explore additional IoT scenarios that use other Azure tools and services. Below are 7 different example use cases, taken from Azure IoT hub documentation:

• Using iothub-explorer tool: Use iothub-explorer to send and receive messages between your device and IoT Hub
• Using Azure table storage: Save IoT Hub messages that contain information like sensor data to Azure table storage
• Using Microsoft Power BI and Azure Web Apps: Visualize real-time sensor data from Azure IoT Hub using Power BI
• Using Azure Web Apps: Visualize real-time sensor data from Azure IoT Hub using Azure Web Apps
• Using Azure Machine Learning: Weather forecast using the sensor data from your IoT hub in Azure Machine Learning
• Using iothub-explorer tool: Use iothub-explorer for Azure IoT Hub device management
• Using Azure Logic Apps: IoT remote monitoring and notifications with Azure Logic Apps connecting your IoT hub and mailbox