AzureIotHubClientV2 (community library)
Summary
Name | Value |
---|---|
Name | AzureIotHubClientV2 |
Version | 1.0.2 |
Installs | |
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
Azure IoT Central Application
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.
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.
- 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)
You want two-way messaging and direct method invocation from Azure.
You are already using Azure and you want to connect, control, and integrate your devices with other business processes.
You want to learn how to do interesting things with your telemetry such as:
- Weather forecasting using the sensor data from your IoT hub in Azure Machine Learning,
- Visualize real-time sensor data from your Azure IoT hub by using the Web Apps feature of Azure App Service,
- 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
Login to the Particle Web IDE.
Click the Libraries icon and type "AzureIotHubClient" in the Community Libraries" text box.
new-particle-project-library.JPG (image removed)
Select the AzureIotHubClient library
Choose the AzureIotHub-Full example
Click on "Use This Example"
select library (image removed)
- 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.
- 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.
To summarize the screencast:
- Create an Azure IoT Central application from https://azure.microsoft.com/en-au/services/iot-central. Then click Get Started
- Select Trial, Custom Application, type your application name. Then click Create
- Click Create Device Templates, name your template, for example, "Particle". Then click Create
- 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.
- Click Commands tab, add commands for "lighton", "lightoff", "fanon", and "fanoff". Then click Done.
- Click Device Explorer on the sidebar menu, select the template you created. Then add a Real Device create a real device (image removed)
- 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)
- Create an IoT Central Device Connection String
You need to generate a connection string for the IoT Central device. You can either:
- Download the Connection String Generator for Windows, macOS, or Linux. The README has the run instructions.
- Or use my unofficial web-based Connection String Generator".
Update the Particle project CONNECTION_STRING
- 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
- 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)
- 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)
Create a free Azure Account.
Watch this screencast for an introduction to creating an Azure IoT Hub and an IoT Device.
- For more information see Create an Azure IoT Hub (free tier) using the Azure portal
Updating Particle Photon Firmware to 6.3
Download v0.6.3 Firmware Release (Photon/P1)
Install Particle CLI tools
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.
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
- 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