AzureIotHubClientV2 (community library)

Summary

Name Value
Name AzureIotHubClientV2
Version 1.0.2
Installs 11370
License MIT
Author Steve Webster
Download .tar.gz
All Versions 1.0.2, 1.0.1, 1.0.0

Azure IoT Hub Client library for XENON, ARGON and BORON. Connect your Particle Mesh directly to Azure IoT Hub and Azure IoT Central for device to cloud, cloud to device messaging and Direct Method invocation support.

Example Build Testing

Device OS Version:

This table is generated from an automated build. Success only indicates that the code compiled successfully.

Library Read Me

This content is provided by the library maintainer and has not been validated or approved.

Connect your Particle Photon Directly to Azure IoT Hub or IoT Central

Author Dave Glover, Microsoft Cloud Developer Advocate
Documentation README
Platform Particle Photon, Azure IoT Central, Azure IoT Hub
Video Training What is Azure IoT Central, Introduction to Azure IoT Hub
Screencasts How to create the Azure IoT Central Application, How to create an Azure IoT Hub
Date As at Nov 2018
Acknowledgment This AzureIoTHubClient library depends and builds upon the fantastic MQTT-TLS library.

Now you can connect your Particle Photon directly to the Particle Cloud, Azure IoT Hub, and Azure IoT Central. The AzureIoTHubClient library supports two-way messaging, Direct Methods, and soon Device Twins.

photon in action (image removed)

Introduction

A Particle Photon using the AzureIoTHubClient library can publish 50 messages per second to Azure IoT Hub. The free tier of Azure IoT Hub limits the number of messages to 8000 per day. At 50 messages per second, you will reach the 8000-message limit in under 3 minutes. So be sure to throttle the telemetry publish rate.

Azure IoT Central is a "no code" service to graph and analysis telemetry, control devices, and trigger other processes. Under the covers, the service uses Azure IoT Hub, Azure Time Series Insights, and the Azure IoT Hub Device Provisioning Service. Hence this library and documentation apply Azure IoT Hub and Azure IoT Central.

What you need
  1. Particle Photon

  2. Particle Cloud Account

  3. Azure IoT Central Application

  4. Azure IoT Central is available as a free 7-day trial or as a Pay-As-You-Go (free for the first 5 devices) service.

  5. Or you can also use an Azure IoT Hub instead of Azure IoT Central. For more information read how to Create an Azure IoT Hub (Free Tier - limited to 8000 messages per day).

Why connect your Particle Photon to Azure Services

Here are some reasons to connect your Particle Photon directly to Azure.

  1. Azure IoT Central is perfect if you have limited development skills, time, or budget to bring an IoT project to life.

iot central (image removed)

  1. You want two-way messaging and direct method invocation from Azure.

  2. You are already using Azure and you want to connect, control, and integrate your devices with other business processes.

  3. You want to learn how to do interesting things with your telemetry such as:

  4. Weather forecasting using the sensor data from your IoT hub in Azure Machine Learning,
  5. Visualize real-time sensor data from your Azure IoT hub by using the Web Apps feature of Azure App Service,
  6. IoT remote monitoring and notifications with Azure Logic Apps connecting your IoT hub and mailbox.

How to connect your Particle Photon to IoT Central or Azure IoT Hub

  1. Login to the Particle Web IDE.

  2. Click the Libraries icon and type "AzureIotHubClient" in the Community Libraries" text box.

new-particle-project-library.JPG (image removed)

  1. Select the AzureIotHubClient library

  2. Choose the AzureIotHub-Full example

  3. Click on "Use This Example"

select library (image removed)

  1. Azure IoT Central or Azure IoT Hub

For simplicity create an IoT Central application. If you want to connect to Azure IoT Hub then read how to set up an Azure IoT Hub (Free Tier) and skip the next step.

  1. Create an Azure IoT Central Application

Watch this 5-minute screencast on how to create the Azure IoT Central Application to chart telemetry and send commands to your Particle Photon.

screencast

To summarize the screencast:

  1. Create an Azure IoT Central application from https://azure.microsoft.com/en-au/services/iot-central. Then click Get Started
  2. Select Trial, Custom Application, type your application name. Then click Create
  3. Click Create Device Templates, name your template, for example, "Particle". Then click Create
  4. Edit the Template, add Measurements for Temperature, Humidity, and Pressure telemetry.
Display Name Field name Units Minimum Maximum Decimals
Humidity humidity % 0 100 0
Temperature temp degC -10 60 0
Pressure pressure hPa 800 1260 0

Then click Done.

  1. Click Commands tab, add commands for "lighton", "lightoff", "fanon", and "fanoff". Then click Done.
  2. Click Device Explorer on the sidebar menu, select the template you created. Then add a Real Device create a real device (image removed)
  3. When you have created your real device click the Connect button in the top right-hand corner of the screen to display the device credentials. You will need these credentials for the next step.

Device Connection (image removed)

  1. Create an IoT Central Device Connection String

You need to generate a connection string for the IoT Central device. You can either:

  1. Download the Connection String Generator for Windows, macOS, or Linux. The README has the run instructions.
  2. Or use my unofficial web-based Connection String Generator".
Update the Particle project CONNECTION_STRING
  1. Update the CONNECTION_STRING in the Particle Photon project with the connection string you generated in the previous step.

Update connection string (image removed)

Flash your Particle Photon project
  1. Set your Particle Photon Firmware to 6.3

Set the device target firmware to 6.3. Your mileage may vary. I found firmware 6.3 to be more reliable than 7.0. WiFi recovery worked, 802.11n worked, and it uses less memory. See Updating Particle Photon Firmware to 6.3.

Target firmware 6.3 (image removed)

  1. Flash your Particle Photon with Azure IoT Hub Client app your device from the Particle IDE.

Understanding the AzureIotHubClient Library

The AzureIotHubClient library includes these examples to help you understand its use.

Example: AzureIotHub-Simple
API Description
hub.loop Call "loop" often as it handles processing of inbound messages and direct methods. It returns true if there is an active connection to Azure IoT Hub or IoT Central.
hub.publish Publishes the telemetry to Azure IoT Hub or IoT Central. It returns true if successful.
#define CONNECTION_STRING "< your connection string >"

IotHub hub(CONNECTION_STRING);
count = 0;

setup()
{}

loop()
{
if (hub.loop())
{
if (count++ % 25 == 0)
{
hub.publish("\"temperature\":25");
}
}
delay(200);
}
Example: AzureIotHub-Full
Callbacks Description
callbackCloud2Device This function is called to process Cloud to Device messages.
callbackDirectMethod This function is called when a Direct Method (or an Azure IoT Central Command) is invoked cloud side. It includes a JSON payload.
// define callback signature
void callbackCloud2Device(char *topic, byte *payload, unsigned int length);
int callbackDirectMethod(char *method, byte *payload, unsigned int length);

IotHub hub(CONNECTION_STRING, callbackCloud2Device, callbackDirectMethod);
count = 0;

setup()
{
RGB.control(true);
}

loop()
{
if (hub.loop())
{
if (count++ % 25 == 0)  // slow down the publish rate to every 25 loops
{
hub.publish("\"temperature\":25");
}
}
delay(200);
}

void callbackCloud2Device(char *topic, byte *payload, unsigned int length)
{
char* msg = (char*)payload;
if (strncmp(msg, "red", length) == 0)
{
RGB.color(255, 0, 0);
}
}

int callbackDirectMethod(char *method, byte *payload, unsigned int payloadLength)
{
if (strcmp(method, "lighton") == 0)
{
RGB.color(255, 255, 0);
}
else
{
return 400;
}
return 200;
}
Example: Tuning Parameters
Parameter Description
maxBufferSize Defaults to 500 bytes. Increase for larger messages.
sasExpiryPeriodInSeconds Defaults to 3600 seconds (60 minutes).
int maxBufferSize = 500;
time_t sasExpiryPeriodInSeconds = 3600;

IotHub hub(CONNECTION_STRING, callbackCloud2Device, callbackDirectMethod, maxBufferSize, sasExpiryPeriodInSeconds);

Passing in tuning parameters with no callbacks.

// with no callbacks
IotHub hub(CONNECTION_STRING, NULL, NULL, maxBufferSize, sasExpiryPeriodInSeconds);

How to set up an Azure IoT Hub (Free Tier)

  1. Create a free Azure Account.

  2. Watch this screencast for an introduction to creating an Azure IoT Hub and an IoT Device.

screencast

  1. For more information see Create an Azure IoT Hub (free tier) using the Azure portal

Updating Particle Photon Firmware to 6.3

  1. Download v0.6.3 Firmware Release (Photon/P1)

  2. Install Particle CLI tools

  3. Updating your Particle Photon over the Air (OTA) is the easiest choice if your device is already connected to the Particle Cloud. For more information see Upgrading and downgrading Particle Device OS.

  4. If upgrading to firmware 6.3

    particle flash <your device id> system-part1-0.6.3-photon.bin
    particle flash <your device id> system-part2-0.6.3-photon.bin
    
  5. If downgrading to firmware 6.3 (reverse order)
    particle flash <your device id> system-part2-0.6.3-photon.bin
    particle flash <your device id> system-part1-0.6.3-photon.bin
    

Browse Library Files