Table of Contents

Overview
Azure and IoT
What is Azure IoT Hub?
Overview of device management
Get Started
Use a simulated device
.NET
Java
Node
Use a Raspberry Pi
Node.js
C
Use an Intel Edison
Node.js
C
Use an Arduino
Node.js
Use the Gateway SDK
Simulation on Linux
Simulation on Windows
Use the IoT Gateway Starter Kit
Simulated device
SensorTag device
Use the IoT device SDK for C
Introduction
Use the IoTHubClient
Use the serializer
How To
Plan
Comparison of IoT Hub to Event Hubs
Scale your solution
High availability and disaster recovery
Supporting additional protocols
Develop
Developer guide
Process device-to-cloud messages
Send cloud-to-device messages
Upload files from devices
Get started with device twins
Use direct methods
Get started with device management
How to use twin properties
Use device jobs to update device firmware
Schedule and broadcast jobs
Manage
Create an IoT hub
Configure file upload
Bulk manage IoT devices
Usage metrics
Operations monitoring
Configure IP filtering
Secure
Security from the ground up
Security best practices
Security architecture
Secure your IoT deployment
Gateway SDK
Simulate a device
Use a real device
Reference
Azure CLI 2.0 Preview
.NET (Service)
.NET (Devices)
Java (Service)
Java (Devices)
Azure IoT SDKs
Gateway SDK
REST (Resource Provider)
REST (Device Identities)
REST (Device Twins)
REST (Device Messaging)
REST (Jobs)
Related
Azure IoT Suite
Azure Event Hubs
Stream Analytics
Machine Learning
Resources
Pricing
MSDN forum
Stack Overflow
Videos
Service updates
Learning path
Azure IoT Developer Center
Azure Certified for IoT device catalog
Azure and Internet of Things
1/24/2017 • 5 min to read • Edit on GitHub

Welcome to Microsoft Azure and the Internet of Things (IoT). This article introduces an IoT solution architecture that
describes the common characteristics of an IoT solution you might deploy using Azure services. IoT solutions
require secure, bidirectional communication between devices, possibly numbering in the millions, and a solution
back end. For example, a solution back end might use automated, predictive analytics to uncover insights from your
device-to-cloud event stream.
Azure IoT Hub is a key building block when you implement this IoT solution architecture using Azure services. IoT
Suite provides complete, end-to-end, implementations of this architecture for specific IoT scenarios. For example:
The remote monitoring solution enables you to monitor the status of devices such as vending machines.
The predictive maintenance solution helps you to anticipate maintenance needs of devices such as pumps in
remote pumping stations and to avoid unscheduled downtime.

IoT solution architecture

The following diagram shows a typical IoT solution architecture. The diagram does not include the names of any
specific Azure services, but describes the key elements in a generic IoT solution architecture. In this architecture, IoT
devices collect data that they send to a cloud gateway. The cloud gateway makes the data available for processing
by other back-end services from where data is delivered to other line-of-business applications or to human
operators through a dashboard or other presentation device.
NOTE
For an in-depth discussion of IoT architecture, see the Microsoft Azure IoT Reference Architecture.

Device connectivity
In this IoT solution architecture, devices send telemetry, such as sensor readings from a pumping station, to a cloud
endpoint for storage and processing. In a predictive maintenance scenario, the solution back end might use the
stream of sensor data to determine when a specific pump requires maintenance. Devices can also receive and
respond to cloud-to-device messages by reading messages from a cloud endpoint. For example, in the predictive
maintenance scenario the solution back end might send messages to other pumps in the pumping station to begin
rerouting flows just before maintenance is due to start to make sure the maintenance engineer can get started
when she arrives.
One of the biggest challenges facing IoT projects is how to reliably and securely connect devices to the solution
back end. IoT devices have different characteristics as compared to other clients such as browsers and mobile apps.
IoT devices:
Are often embedded systems with no human operator.
Can be deployed in remote locations, where physical access is expensive.
May only be reachable through the solution back end. There is no other way to interact with the device.
May have limited power and processing resources.
May have intermittent, slow, or expensive network connectivity.
May need to use proprietary, custom, or industry-specific application protocols.
Can be created using a large set of popular hardware and software platforms.
In addition to the requirements above, any IoT solution must also deliver scale, security, and reliability. The resulting
set of connectivity requirements is hard and time-consuming to implement using traditional technologies such as
web containers and messaging brokers. Azure IoT Hub and the Azure IoT device SDKs make it easier to implement
solutions that meet these requirements.
A device can communicate directly with a cloud gateway endpoint, or if the device cannot use any of the
communications protocols that the cloud gateway supports, it can connect through an intermediate gateway. For
example, the Azure IoT protocol gateway can perform protocol translation if devices cannot use any of the
protocols that IoT Hub supports.
Data processing and analytics
In the cloud, an IoT solution back end is where most of the data processing occurs, such as filtering and aggregating
telemetry and routing it to other services. The IoT solution back end:
Receives telemetry at scale from your devices and determines how to process and store that data.
May enable you to send commands from the cloud to specific device.
Provides device registration capabilities that enable you to provision devices and to control which devices are
permitted to connect to your infrastructure.
Enables you to track the state of your devices and monitor their activities.
In the predictive maintenance scenario, the solution back end stores historical telemetry data. The solution back end
can use this data to use to identify patterns that indicate maintenance is due on a specific pump.
IoT solutions can include automatic feedback loops. For example, an analytics module in the solution back end can
identify from telemetry that the temperature of a specific device is above normal operating levels. The solution can
then send a command to the device, instructing it to take corrective action.
Presentation and business connectivity
The presentation and business connectivity layer allows end users to interact with the IoT solution and the devices.
It enables users to view and analyze the data collected from their devices. These views can take the form of
dashboards or BI reports that can display both historical data or near real-time data. For example, an operator can
check on the status of particular pumping station and see any alerts raised by the system. This layer also allows
integration of the IoT solution back end with existing line-of-business applications to tie into enterprise business
processes or workflows. For example, the predictive maintenance solution can integrate with a scheduling system
that books an engineer to visit a pumping station when the solution identifies a pump in need of maintenance.

Next steps
Azure IoT Hub is an Azure service that enables secure and reliable bi-directional communications between your
solution back end and millions of devices. It enables the solution back end to:
Receive telemetry at scale from your devices.
Route data from your devices to a stream event processor.
Receive file uploads from devices.
Send cloud-to-device messages to specific devices.
You can use IoT Hub to implement your own solution back end. In addition, IoT Hub includes an identity registry
used to provision devices, their security credentials, and their rights to connect to the IoT hub. To learn more about
IoT Hub, see What is IoT Hub?.
To learn how Azure IoT Hub enables standards-based device management for you to remotely manage, configure,
and update your devices, see Overview of device management with IoT Hub.
To implement client applications on a wide variety of device hardware platforms and operating systems, you can
use the Azure IoT device SDKs. The device SDKs include libraries that facilitate sending telemetry to an IoT hub and
receiving cloud-to-device messages. When you use the device SDKs, you can choose from several network
protocols to communicate with IoT Hub. To learn more, see the information about device SDKs.
To get started writing some code and running some samples, see the Get started with IoT Hub tutorial.
You may also be interested in Azure IoT Suite, which is a collection of preconfigured solutions. IoT Suite enables
you to get started quickly and scale IoT projects to address common IoT scenarios--such as remote monitoring,
asset management, and predictive maintenance.
What is Azure IoT Hub?
1/31/2017 • 6 min to read • Edit on GitHub

Welcome to Azure IoT Hub. This article provides an overview of Azure IoT Hub and describes why you should use
this service to implement an Internet of Things (IoT) solution. Azure IoT Hub is a fully managed service that
enables reliable and secure bidirectional communications between millions of IoT devices and a solution back
end. Azure IoT Hub:
Provides multiple device-to-cloud and cloud-to-device communication options, including one-way messaging,
file transfer, and request-reply methods.
Provides built-in declarative message routing to other Azure services.
Provides a queryable store for device metadata and synchronized state information.
Enables secure communications and access control using per-device security keys or X.509 certificates.
Provides extensive monitoring for device connectivity and device identity management events.
Includes device libraries for the most popular languages and platforms.
The article Comparison of IoT Hub and Event Hubs describes the key differences between these two services and
highlights the advantages of using IoT Hub in your IoT solutions.
Refer to Internet of Things security from the ground up for more information on how Azure and IoT Hub help
secure your IoT solution.

NOTE
For an in-depth discussion of IoT architecture, see the Microsoft Azure IoT Reference Architecture.
IoT device-connectivity challenges
IoT Hub and the device libraries help you to meet the challenges of how to reliably and securely connect devices
to the solution back end. IoT devices:
Are often embedded systems with no human operator.
Can be in remote locations, where physical access is expensive.
May only be reachable through the solution back end.
May have limited power and processing resources.
May have intermittent, slow, or expensive network connectivity.
May need to use proprietary, custom, or industry-specific application protocols.
Can be created using a large set of popular hardware and software platforms.
In addition to the requirements above, any IoT solution must also deliver scale, security, and reliability. The
resulting set of connectivity requirements is hard and time-consuming to implement when you use traditional
technologies, such as web containers and messaging brokers.

Why use Azure IoT Hub

In addition to a rich set of device-to-cloud and cloud-to-device communication options, including messaging, file
transfers, and request-reply methods, Azure IoT Hub addresses the device-connectivity challenges in the following
ways:
Device twins. Using Device twins, you can store, synchronize, and query device metadata and state
information. Device twins are JSON documents that store device state information (metadata, configurations,
and conditions). IoT Hub persists a device twin for each device that you connect to IoT Hub.
Per-device authentication and secure connectivity. You can provision each device with its own security
key to enable it to connect to IoT Hub. The IoT Hub identity registry stores device identities and keys in a
solution. A solution back end can add individual devices to allow or deny lists to enable complete control over
device access.
Route device-to-cloud messages to Azure services based on declarative rules. IoT Hub enables you to
define message routes based on routing rules to control where your hub sends device-to-cloud messages.
Routing rules do not require you to write any code, and can take the place of custom post-ingestion message
dispatchers.
Monitoring of device connectivity operations. You can receive detailed operation logs about device
identity management operations and device connectivity events. This monitoring capability enables your IoT
solution to identify connectivity issues, such as devices that try to connect with wrong credentials, send
messages too frequently, or reject all cloud-to-device messages.
An extensive set of device libraries. Azure IoT device SDKs are available and supported for various
languages and platforms--C for many Linux distributions, Windows, and real-time operating systems. Azure
IoT device SDKs also support managed languages, such as C#, Java, and JavaScript.
IoT protocols and extensibility. If your solution cannot use the device libraries, IoT Hub exposes a public
protocol that enables devices to natively use the MQTT v3.1.1, HTTP 1.1, or AMQP 1.0 protocols. You can
also extend IoT Hub to provide support for custom protocols by:
Creating a field gateway with the Azure IoT Gateway SDK that converts your custom protocol to one of
the three protocols understood by IoT Hub.
Customizing the Azure IoT protocol gateway, an open source component that runs in the cloud.
Scale. Azure IoT Hub scales to millions of simultaneously connected devices and millions of events per second.

Gateways
A gateway in an IoT solution is typically either a protocol gateway that is deployed in the cloud or a field gateway
that is deployed locally with your devices. A protocol gateway performs protocol translation, for example MQTT to
AMQP. A field gateway can run analytics on the edge, make time-sensitive decisions to reduce latency, provide
device management services, enforce security and privacy constraints, and also perform protocol translation. Both
gateway types act as intermediaries between your devices and your IoT hub.
A field gateway differs from a simple traffic routing device (such as a network address translation device or
firewall) because it typically performs an active role in managing access and information flow in your solution.
A solution may include both protocol and field gateways.

How does IoT Hub work?

Azure IoT Hub implements the service-assisted communication pattern to mediate the interactions between your
devices and your solution back end. The goal of service-assisted communication is to establish trustworthy,
bidirectional communication paths between a control system, such as IoT Hub, and special-purpose devices that
are deployed in untrusted physical space. The pattern establishes the following principles:
Security takes precedence over all other capabilities.
Devices do not accept unsolicited network information. A device establishes all connections and routes in an
outbound-only fashion. For a device to receive a command from the solution back end, the device must
regularly initiate a connection to check for any pending commands to process.
Devices should only connect to or establish routes to well-known services they are peered with, such as IoT
Hub.
The communication path between device and service or between device and gateway is secured at the
application protocol layer.
System-level authorization and authentication are based on per-device identities. They make access credentials
and permissions nearly instantly revocable.
Bidirectional communication for devices that connect sporadically due to power or connectivity concerns is
facilitated by holding commands and device notifications until a device connects to receive them. IoT Hub
maintains device-specific queues for the commands it sends.
Application payload data is secured separately for protected transit through gateways to a particular service.
The mobile industry has used the service-assisted communication pattern at enormous scale to implement push
notification services such as Windows Push Notification Services, Google Cloud Messaging, and Apple Push
Notification Service.
IoT Hub is supported over ExpressRoute's public peering path.

Next steps
To learn how to send messages from a device and receive them from IoT Hub, as well as how to configure
message routes, see Send and receive messages with IoT Hub.
To learn how IoT Hub enables standards-based device management for you to remotely manage, configure, and
update your devices, see Overview of device management with IoT Hub.
To implement client applications on a wide variety of device hardware platforms and operating systems, you can
use the Azure IoT device SDKs. The device SDKs include libraries that facilitate sending telemetry to an IoT hub
and receiving cloud-to-device messages. When you use the device SDKs, you can choose from various network
protocols to communicate with IoT Hub. To learn more, see the information about device SDKs.
To get started writing some code and running some samples, see the Get started with IoT Hub tutorial.
Overview of device management with IoT Hub
1/25/2017 • 5 min to read • Edit on GitHub

Introduction
Azure IoT Hub provides the features and an extensibility model that enable device and back-end developers to
build robust device management solutions. Devices range from constrained sensors and single purpose
microcontrollers, to powerful gateways that route communications for groups of devices. In addition, the use cases
and requirements for IoT operators vary significantly across industries. Despite this variation, device management
with IoT Hub provides the capabilities, patterns, and code libraries to cater to a diverse set of devices and end
users.
A crucial part of creating a successful enterprise IoT solution is to provide a strategy for how operators handle the
ongoing management of their collection of devices. IoT operators require simple and reliable tools and
applications that enable them to focus on the more strategic aspects of their jobs. This article provides:
A brief overview of Azure IoT Hub approach to device management.
A description of common device management principles.
A description of the device lifecycle.
An overview of common device management patterns.

Device management principles

IoT brings with it a unique set of device management challenges and every enterprise-class solution must address
the following principles:

Scale and automation: IoT solutions require simple tools that can automate routine tasks and enable a
relatively small operations staff to manage millions of devices. Day-to-day, operators expect to handle device
operations remotely, in bulk, and to only be alerted when issues arise that require their direct attention.
Openness and compatibility: The device ecosystem is extraordinarily diverse. Management tools must be
tailored to accommodate a multitude of device classes, platforms, and protocols. Operators must be able to
support many types of devices, from the most constrained embedded single-process chips, to powerful and
fully functional computers.
Context awareness: IoT environments are dynamic and ever-changing. Service reliability is paramount. Device
management operations must factor in SLA maintenance windows, network and power states, in-use
conditions, and device geolocation to ensure that maintenance downtime doesn't affect critical business
operations or create dangerous conditions.
Service many roles: Support for the unique workflows and processes of IoT operations roles is crucial. The
operations staff must work harmoniously with the given constraints of internal IT departments. They must also
find sustainable ways to surface realtime device operations information to supervisors and other business
managerial roles.

Device lifecycle
There is a set of general device management stages that are common to all enterprise IoT projects. In Azure IoT,
there are five stages within the device lifecycle:

Within each of these five stages, there are several device operator requirements that should be fulfilled to provide
a complete solution:
Plan: Enable operators to create a device metadata scheme that enables them to easily and accurately
query for, and target a group of devices for bulk management operations. You can use the device twin to
store this device metadata in the form of tags and properties.
Further reading: Get started with device twins, Understand device twins, How to use device twin properties
Provision: Securely provision new devices to IoT Hub and enable operators to immediately discover device
capabilities. Use the IoT Hub identity registry to create flexible device identities and credentials, and perform
this operation in bulk by using a job. Build devices to report their capabilities and conditions through device
properties in the device twin.
Further reading: Manage device identities, Bulk management of device identities, How to use device twin
properties
Configure: Facilitate bulk configuration changes and firmware updates to devices while maintaining both
health and security. Perform these device management operations in bulk by using desired properties or
with direct methods and broadcast jobs.
Further reading: Use direct methods, Invoke a direct method on a device, How to use device twin properties,
Schedule and broadcast jobs, Schedule jobs on multiple devices
Monitor: Monitor overall device collection health, the status of ongoing operations, and alert operators to
issues that might require their attention. Apply the device twin to allow devices to report realtime operating
conditions and status of update operations. Build powerful dashboard reports that surface the most
immediate issues by using device twin queries.
Further reading: How to use device twin properties, IoT Hub query language for device twins and jobs
Retire: Replace or decommission devices after a failure, upgrade cycle, or at the end of the service lifetime.
Use the device twin to maintain device info if the physical device is being replaced, or archived if being
retired. Use the IoT Hub identity registry for securely revoking device identities and credentials.
Further reading: How to use device twin properties, Manage device identities

Device management patterns

IoT Hub enables the following set of device management patterns. The device management tutorials show you in
more detail how to extend these patterns to fit your exact scenario and how to design new patterns based on these
core templates.
Reboot - The back-end app informs the device through a direct method that it has initiated a reboot. The
device uses the reported properties to update the reboot status of the device.

Factory Reset - The back-end app informs the device through a direct method that it has initiated a factory
reset. The device uses the reported properties to update the factory reset status of the device.

Configuration - The back-end app uses the desired properties to configure software running on the
device. The device uses the reported properties to update configuration status of the device.
Firmware Update - The back-end app informs the device through a direct method that it has initiated a
firmware update. The device initiates a multistep process to download the firmware image, apply the
firmware image, and finally reconnect to the IoT Hub service. Throughout the mult-step process, the device
uses the reported properties to update the progress and status of the device.

Reporting progress and status - The solution back end runs device twin queries, across a set of devices,
to report on the status and progress of actions running on the devices.
Next Steps
You can use the capabilities, patterns, and code libraries that IoT Hub provides for device management, to create
IoT applications that fulfill the enterprise IoT operator requirements within in each device lifecycle stage.
To continue learning about the device management features in IoT Hub, see the Get started with device
management tutorial.
Get started with Azure IoT Hub (.NET)
1/17/2017 • 10 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications
between millions of Internet of Things (IoT) devices and a solution back end. One of the biggest challenges that
IoT projects face is how to reliably and securely connect devices to the solution back end. To address this
challenge, IoT Hub:
Offers reliable device-to-cloud and cloud-to-device hyper-scale messaging.
Enables secure communications using per-device security credentials and access control.
Includes device libraries for the most popular languages and platforms.
This tutorial shows you how to:
Use the Azure portal to create an IoT hub.
Create a device identity in your IoT hub.
Create a simulated device app that sends telemetry to your solution back end, and receives commands
from your solution back end.
At the end of this tutorial, you have three .NET console apps:
CreateDeviceIdentity, which creates a device identity and associated security key to connect your
simulated device app.
ReadDeviceToCloudMessages, which displays the telemetry sent by your simulated device app.
SimulatedDevice, which connects to your IoT hub with the device identity created earlier, and sends a
telemetry message every second by using the MQTT protocol.

NOTE
For information about the Azure IoT SDKs that you can use to build both applications to run on devices, and your
solution back end, see Azure IoT SDKs.

To complete this tutorial, you need the following:

Microsoft Visual Studio 2015.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete
this task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check
mark appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the
free F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information,
see Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in
the Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal
to open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access
policies.

6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of
the IoT Hub connection string in the iothubowner blade. For more information, see Access control in
the "IoT Hub developer guide."

You have now created your IoT hub, and you have the host name and IoT Hub connection string that you need
to complete the rest of this tutorial.

Create a device identity

In this section, you create a .NET console app that creates a device identity in the identity registry in your IoT
hub. A device cannot connect to IoT hub unless it has an entry in the identity registry. For more information,
see the "Identity registry" section of the IoT Hub developer guide. When you run this console app, it generates
a unique device ID and key that your device can use to identify itself when it sends device-to-cloud messages
to IoT Hub.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the
Console Application project template. Make sure the .NET Framework version is 4.5.1 or later. Name
the project CreateDeviceIdentity.
2. In Solution Explorer, right-click the CreateDeviceIdentity project, and then click Manage NuGet
Packages.
3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select
Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure
downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its
dependencies.

4. Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;

5. Add the following fields to the Program class. Replace the placeholder value with the IoT Hub
connection string for the hub that you created in the previous section.

static RegistryManager registryManager;

static string connectionString = "{iot hub connection string}";

6. Add the following method to the Program class:

private static async Task AddDeviceAsync()
{
string deviceId = "myFirstDevice";
Device device;
try
{
device = await registryManager.AddDeviceAsync(new Device(deviceId));
}
catch (DeviceAlreadyExistsException)
{
device = await registryManager.GetDeviceAsync(deviceId);
}
Console.WriteLine("Generated device key: {0}", device.Authentication.SymmetricKey.PrimaryKey);
}

This method creates a device identity with ID myFirstDevice. (If that device ID already exists in the
identity registry, the code simply retrieves the existing device information.) The app then displays the
primary key for that identity. You use this key in the simulated device app to connect to your IoT hub.
7. Finally, add the following lines to the Main method:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddDeviceAsync().Wait();
Console.ReadLine();

8. Run this application, and make a note of the device key.

NOTE
The IoT Hub identity registry only stores device identities to enable secure access to the IoT hub. It stores device IDs
and keys to use as security credentials, and an enabled/disabled flag that you can use to disable access for an individual
device. If your application needs to store other device-specific metadata, it should use an application-specific store. For
more information, see IoT Hub developer guide.

Receive device-to-cloud messages

In this section, you create a .NET console app that reads device-to-cloud messages from IoT Hub. An IoT hub
exposes an Azure Event Hubs-compatible endpoint to enable you to read device-to-cloud messages. To keep
things simple, this tutorial creates a basic reader that is not suitable for a high throughput deployment. To
learn how to process device-to-cloud messages at scale, see the Process device-to-cloud messages tutorial.
For more information about how to process messages from Event Hubs, see the Get Started with Event Hubs
tutorial. (This tutorial is applicable to the IoT Hub Event Hub-compatible endpoints.)

NOTE
The Event Hub-compatible endpoint for reading device-to-cloud messages always uses the AMQP protocol.

1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution, by using the
Console Application project template. Make sure the .NET Framework version is 4.5.1 or later. Name
the project ReadDeviceToCloudMessages.

2. In Solution Explorer, right-click the ReadDeviceToCloudMessages project, and then click Manage
NuGet Packages.
3. In the NuGet Package Manager window, search for WindowsAzure.ServiceBus, select Install, and
accept the terms of use. This procedure downloads, installs, and adds a reference to Azure Service Bus, with
all its dependencies. This package enables the application to connect to the Event Hub-compatible endpoint
on your IoT hub.
4. Add the following using statements at the top of the Program.cs file:

using Microsoft.ServiceBus.Messaging;
using System.Threading;

5. Add the following fields to the Program class. Replace the placeholder value with the IoT Hub
connection string for the hub you created in the "Create an IoT hub" section.

static string connectionString = "{iothub connection string}";

static string iotHubD2cEndpoint = "messages/events";
static EventHubClient eventHubClient;

6. Add the following method to the Program class:

private static async Task ReceiveMessagesFromDeviceAsync(string partition, CancellationToken ct)
{
var eventHubReceiver = eventHubClient.GetDefaultConsumerGroup().CreateReceiver(partition,
DateTime.UtcNow);
while (true)
{
if (ct.IsCancellationRequested) break;
EventData eventData = await eventHubReceiver.ReceiveAsync();
if (eventData == null) continue;

string data = Encoding.UTF8.GetString(eventData.GetBytes());

Console.WriteLine("Message received. Partition: {0} Data: '{1}'", partition, data);
}
}

This method uses an EventHubReceiver instance to receive messages from all the IoT hub device-to-
cloud receive partitions. Notice how you pass a DateTime.Now parameter when you create the
EventHubReceiver object, so that it only receives messages sent after it starts. This filter is useful in a
test environment so you can see the current set of messages. In a production environment, your code
should make sure that it processes all the messages. For more information, see the How to process IoT
Hub device-to-cloud messages tutorial.
7. Finally, add the following lines to the Main method:

Console.WriteLine("Receive messages. Ctrl-C to exit.\n");

eventHubClient = EventHubClient.CreateFromConnectionString(connectionString, iotHubD2cEndpoint);

var d2cPartitions = eventHubClient.GetRuntimeInformation().PartitionIds;

CancellationTokenSource cts = new CancellationTokenSource();

System.Console.CancelKeyPress += (s, e) =>

{
e.Cancel = true;
cts.Cancel();
Console.WriteLine("Exiting...");
};

var tasks = new List<Task>();

foreach (string partition in d2cPartitions)
{
tasks.Add(ReceiveMessagesFromDeviceAsync(partition, cts.Token));
}
Task.WaitAll(tasks.ToArray());

Create a simulated device app

In this section, you create a .NET console app that simulates a device that sends device-to-cloud messages to
an IoT hub.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution, by using the
Console Application project template. Make sure the .NET Framework version is 4.5.1 or later. Name
the project SimulatedDevice.
2. In Solution Explorer, right-click the SimulatedDevice project, and then click Manage NuGet Packages.
3. In the NuGet Package Manager window, select Browse, search for Microsoft.Azure.Devices.Client,
select Install to install the Microsoft.Azure.Devices.Client package, and accept the terms of use. This
procedure downloads, installs, and adds a reference to the Azure IoT device SDK NuGet package and its
dependencies.
4. Add the following using statement at the top of the Program.cs file:

using Microsoft.Azure.Devices.Client;
using Newtonsoft.Json;

5. Add the following fields to the Program class. Substitute the placeholder values with the IoT hub host
name you retrieved in the "Create an IoT hub" section, and the device key retrieved in the "Create a
device identity" section.

static DeviceClient deviceClient;

static string iotHubUri = "{iot hub hostname}";
static string deviceKey = "{device key}";

6. Add the following method to the Program class:

private static async void SendDeviceToCloudMessagesAsync()
{
double avgWindSpeed = 10; // m/s
Random rand = new Random();

while (true)
{
double currentWindSpeed = avgWindSpeed + rand.NextDouble() * 4 - 2;

var telemetryDataPoint = new

{
deviceId = "myFirstDevice",
windSpeed = currentWindSpeed
};
var messageString = JsonConvert.SerializeObject(telemetryDataPoint);
var message = new Message(Encoding.ASCII.GetBytes(messageString));

await deviceClient.SendEventAsync(message);
Console.WriteLine("{0} > Sending message: {1}", DateTime.Now, messageString);

Task.Delay(1000).Wait();
}
}

This method sends a new device-to-cloud message every second. The message contains a JSON-
serialized object, with the device ID and a randomly generated number to simulate a wind speed sensor.
7. Finally, add the following lines to the Main method:

Console.WriteLine("Simulated device\n");
deviceClient = DeviceClient.Create(iotHubUri, new
DeviceAuthenticationWithRegistrySymmetricKey("myFirstDevice", deviceKey), TransportType.Mqtt);

SendDeviceToCloudMessagesAsync();
Console.ReadLine();

By default, the Create method creates a DeviceClient instance that uses the AMQP protocol to
communicate with IoT Hub. To use the MQTT or HTTP protocol, use the override of the Create method
that enables you to specify the protocol. If you use the HTTP protocol, you should also add the
Microsoft.AspNet.WebApi.Client NuGet package to your project to include the
System.Net.Http.Formatting namespace.
This tutorial takes you through the steps to create an IoT Hub simulated device app. You can also use the
Connected Service for Azure IoT Hub Visual Studio extension to add the necessary code to your device app.

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement
retry policies (such as an exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Run the apps

You are now ready to run the apps.
1. In Visual Studio, in Solution Explorer, right-click your solution, and then click Set StartUp projects.
Select Multiple startup projects, and then select Start as the action for both the
ReadDeviceToCloudMessages and SimulatedDevice projects.
2. Press F5 to start both apps running. The console output from the SimulatedDevice app shows the
messages your simulated device app sends to your IoT hub. The console output from the
ReadDeviceToCloudMessages app shows the messages that your IoT hub receives.

3. The Usage tile in the Azure portal shows the number of messages sent to the IoT hub:
Next steps
In this tutorial, you configured an IoT hub in the Azure portal, and then created a device identity in the IoT
hub's identity registry. You used this device identity to enable the simulated device app to send device-to-
cloud messages to the IoT hub. You also created an app that displays the messages received by the IoT hub.
To continue getting started with IoT Hub and to explore other IoT scenarios, see:
Connecting your device
Getting started with device management
Getting started with the IoT Gateway SDK
To learn how to extend your IoT solution and process device-to-cloud messages at scale, see the Process
device-to-cloud messages tutorial.
Get started with Azure IoT Hub (Java)
2/14/2017 • 13 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications between
millions of Internet of Things (IoT) devices and a solution back end. One of the biggest challenges that IoT
projects face is how to reliably and securely connect devices to the solution back end. To address this challenge,
IoT Hub:
Offers reliable device-to-cloud and cloud-to-device hyper-scale messaging.
Enables secure communications using per-device security credentials and access control.
Includes device libraries for the most popular languages and platforms.
This tutorial shows you how to:
Use the Azure portal to create an IoT hub.
Create a device identity in your IoT hub.
Create a simulated device app that sends telemetry to your solution back end, and receives commands from
your solution back end.
At the end of this tutorial, you have three Java console apps:
create-device-identity, which creates a device identity and associated security key to connect your
simulated device app.
read-d2c-messages, which displays the telemetry sent by your simulated device app.
simulated-device, which connects to your IoT hub with the device identity created earlier, and sends a
telemetry message every second using the MQTT protocol.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both apps to run on
devices and your solution back end.

To complete this tutorial, you need the following:

Java SE 8.
Prepare your development environment describes how to install Java for this tutorial on either Windows or
Linux.
Maven 3.
Prepare your development environment describes how to install Maven for this tutorial on either Windows or
Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete
this task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.

3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access
policies.

6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

As a final step, make a note of the Primary key value. Then click Endpoints and the Events built-in endpoint. On
the Properties blade, make a note of the Event Hub-compatible name and the Event Hub-compatible
endpoint address. You need these three values when you create your read-d2c-messages app.
You have now created your IoT hub. You have the IoT Hub host name, IoT Hub connection string, IoT Hub Primary
Key, Event Hub-compatible name, and Event Hub-compatible endpoint you need to complete this tutorial.

Create a device identity

In this section, you create a Java console app that creates a device identity in the identity registry in your IoT hub.
A device cannot connect to IoT hub unless it has an entry in the identity registry. For more information, see the
Identity Registry section of the IoT Hub developer guide. When you run this console app, it generates a unique
device ID and key that your device can use to identify itself when it sends device-to-cloud messages to IoT Hub.
1. Create an empty folder called iot-java-get-started. In the iot-java-get-started folder, create a Maven project
called create-device-identity using the following command at your command prompt. Note this is a
single, long command:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=create-device-identity -

DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

2. At your command prompt, navigate to the create-device-identity folder.

3. Using a text editor, open the pom.xml file in the create-device-identity folder and add the following
dependency to the dependencies node. This dependency enables you to use the iothub-service-sdk
package in your app:

<dependency>
<groupId>com.microsoft.azure.iothub-java-client</groupId>
<artifactId>iothub-java-service-client</artifactId>
<version>1.0.11</version>
</dependency>

4. Save and close the pom.xml file.

5. Using a text editor, open the create-device-identity\src\main\java\com\mycompany\app\App.java file.
6. Add the following import statements to the file:

import com.microsoft.azure.iot.service.exceptions.IotHubException;
import com.microsoft.azure.iot.service.sdk.Device;
import com.microsoft.azure.iot.service.sdk.RegistryManager;

import java.io.IOException;
import java.net.URISyntaxException;
7. Add the following class-level variables to the App class, replacing {yourhubconnectionstring} with the
value your noted earlier:

private static final String connectionString = "{yourhubconnectionstring}";

private static final String deviceId = "myFirstJavaDevice";

8. Modify the signature of the main method to include the exceptions as follows:

public static void main( String[] args ) throws IOException, URISyntaxException, Exception

9. Add the following code as the body of the main method. This code creates a device called javadevice in
your IoT Hub identity registry if doesn't already exist. It then displays the device ID and key that you need
later:

RegistryManager registryManager = RegistryManager.createFromConnectionString(connectionString);

Device device = Device.createFromId(deviceId, null, null);

try {
device = registryManager.addDevice(device);
} catch (IotHubException iote) {
try {
device = registryManager.getDevice(deviceId);
} catch (IotHubException iotf) {
iotf.printStackTrace();
}
}
System.out.println("Device ID: " + device.getDeviceId());
System.out.println("Device key: " + device.getPrimaryKey());

10. Save and close the App.java file.

11. To build the create-device-identity app using Maven, execute the following command at the command
prompt in the create-device-identity folder:

mvn clean package -DskipTests

12. To run the create-device-identity app using Maven, execute the following command at the command
prompt in the create-device-identity folder:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

13. Make a note of the Device ID and Device key. You need these values later when you create an app that
connects to IoT Hub as a device.

NOTE
The IoT Hub identity registry only stores device identities to enable secure access to the IoT hub. It stores device IDs and
keys to use as security credentials and an enabled/disabled flag that you can use to disable access for an individual device.
If your app needs to store other device-specific metadata, it should use an app-specific store. For more information, see the
IoT Hub developer guide.

Receive device-to-cloud messages

In this section, you create a Java console app that reads device-to-cloud messages from IoT Hub. An IoT hub
exposes an Event Hub-compatible endpoint to enable you to read device-to-cloud messages. To keep things
simple, this tutorial creates a basic reader that is not suitable for a high throughput deployment. The Process
device-to-cloud messages tutorial shows you how to process device-to-cloud messages at scale. The Get Started
with Event Hubs tutorial provides further information on how to process messages from Event Hubs and is
applicable to the IoT Hub Event Hub-compatible endpoints.

NOTE
The Event Hub-compatible endpoint for reading device-to-cloud messages always uses the AMQP protocol.

1. In the iot-java-get-started folder you created in the Create a device identity section, create a Maven project
called read-d2c-messages using the following command at your command prompt. Note this is a single,
long command:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=read-d2c-messages -

DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

2. At your command prompt, navigate to the read-d2c-messages folder.

3. Using a text editor, open the pom.xml file in the read-d2c-messages folder and add the following
dependency to the dependencies node. This dependency enables you to use the eventhubs-client
package in your app to read from the Event Hub-compatible endpoint:

<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-eventhubs</artifactId>
<version>0.10.0</version>
</dependency>

4. Save and close the pom.xml file.

5. Using a text editor, open the read-d2c-messages\src\main\java\com\mycompany\app\App.java file.
6. Add the following import statements to the file:

import java.io.IOException;
import com.microsoft.azure.eventhubs.*;
import com.microsoft.azure.servicebus.*;

import java.io.IOException;
import java.nio.charset.Charset;
import java.time.*;
import java.util.Collection;
import java.util.concurrent.ExecutionException;
import java.util.function.*;
import java.util.logging.*;

7. Add the following class-level variables to the App class. Replace {youriothubkey},
{youreventhubcompatibleendpoint}, and {youreventhubcompatiblename} with the values you
noted previously:

private static String connStr = "Endpoint={youreventhubcompatibleendpoint};EntityPath=

{youreventhubcompatiblename};SharedAccessKeyName=iothubowner;SharedAccessKey={youriothubkey}";

8. Add the following receiveMessages method to the App class. This method creates an EventHubClient
instance to connect to the Event Hub-compatible endpoint and then asynchronously creates a
PartitionReceiver instance to read from an Event Hub partition. It loops continuously and prints the
message details until the app terminates.

private static EventHubClient receiveMessages(final String partitionId)

{
EventHubClient client = null;
try {
client = EventHubClient.createFromConnectionStringSync(connStr);
}
catch(Exception e) {
System.out.println("Failed to create client: " + e.getMessage());
System.exit(1);
}
try {
client.createReceiver(
EventHubClient.DEFAULT_CONSUMER_GROUP_NAME,
partitionId,
Instant.now()).thenAccept(new Consumer<PartitionReceiver>()
{
public void accept(PartitionReceiver receiver)
{
System.out.println("** Created receiver on partition " + partitionId);
try {
while (true) {
Iterable<EventData> receivedEvents = receiver.receive(100).get();
int batchSize = 0;
if (receivedEvents != null)
{
for(EventData receivedEvent: receivedEvents)
{
System.out.println(String.format("Offset: %s, SeqNo: %s, EnqueueTime: %s",
receivedEvent.getSystemProperties().getOffset(),
receivedEvent.getSystemProperties().getSequenceNumber(),
receivedEvent.getSystemProperties().getEnqueuedTime()));
System.out.println(String.format("| Device ID: %s",
receivedEvent.getSystemProperties().get("iothub-connection-device-id")));
System.out.println(String.format("| Message Payload: %s", new
String(receivedEvent.getBody(),
Charset.defaultCharset())));
batchSize++;
}
}
System.out.println(String.format("Partition: %s, ReceivedBatch Size: %s",
partitionId,batchSize));
}
}
catch (Exception e)
{
System.out.println("Failed to receive messages: " + e.getMessage());
}
}
});
}
catch (Exception e)
{
System.out.println("Failed to create receiver: " + e.getMessage());
}
return client;
}
NOTE
This method uses a filter when it creates the receiver so that the receiver only reads messages sent to IoT Hub after
the receiver starts running. This technique is useful in a test environment so you can see the current set of
messages. In a production environment, your code should make sure that it processes all the messages - for more
information, see the How to process IoT Hub device-to-cloud messages tutorial.

9. Modify the signature of the main method to include the exception as follows:

public static void main( String[] args ) throws IOException

10. Add the following code to the main method in the App class. This code creates the two EventHubClient
and PartitionReceiver instances and enables you to close the app when you have finished processing
messages:

EventHubClient client0 = receiveMessages("0");

EventHubClient client1 = receiveMessages("1");
System.out.println("Press ENTER to exit.");
System.in.read();
try
{
client0.closeSync();
client1.closeSync();
System.exit(0);
}
catch (ServiceBusException sbe)
{
System.exit(1);
}

NOTE
This code assumes you created your IoT hub in the F1 (free) tier. A free IoT hub has two partitions named "0" and
"1".

11. Save and close the App.java file.

12. To build the read-d2c-messages app using Maven, execute the following command at the command
prompt in the read-d2c-messages folder:

mvn clean package -DskipTests

Create a simulated device app

In this section, you create a Java console app that simulates a device that sends device-to-cloud messages to an
IoT hub.
1. In the iot-java-get-started folder you created in the Create a device identity section, create a Maven project
called simulated-device using the following command at your command prompt. Note this is a single,
long command:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -

DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
2. At your command prompt, navigate to the simulated-device folder.
3. Using a text editor, open the pom.xml file in the simulated-device folder and add the following
dependencies to the dependencies node. This dependency enables you to use the iothub-java-client
package in your app to communicate with your IoT hub and to serialize Java objects to JSON:

<dependency>
<groupId>com.microsoft.azure.iothub-java-client</groupId>
<artifactId>iothub-java-device-client</artifactId>
<version>1.0.16</version>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.3.1</version>
</dependency>

4. Save and close the pom.xml file.

5. Using a text editor, open the simulated-device\src\main\java\com\mycompany\app\App.java file.
6. Add the following import statements to the file:

import com.microsoft.azure.iothub.DeviceClient;
import com.microsoft.azure.iothub.IotHubClientProtocol;
import com.microsoft.azure.iothub.Message;
import com.microsoft.azure.iothub.IotHubStatusCode;
import com.microsoft.azure.iothub.IotHubEventCallback;
import com.microsoft.azure.iothub.IotHubMessageResult;
import com.google.gson.Gson;
import java.io.IOException;
import java.net.URISyntaxException;
import java.util.Random;
import java.util.concurrent.Executors;
import java.util.concurrent.ExecutorService;

7. Add the following class-level variables to the App class. Replacing {youriothubname} with your IoT hub
name, and {yourdevicekey} with the device key value you generated in the Create a device identity
section:

private static String connString = "HostName={youriothubname}.azure-

devices.net;DeviceId=myFirstJavaDevice;SharedAccessKey={yourdevicekey}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myFirstJavaDevice";
private static DeviceClient client;

This sample app uses the protocol variable when it instantiates a DeviceClient object. You can use either
the MQTT, AMQP, or HTTP protocol to communicate with IoT Hub.
8. Add the following nested TelemetryDataPoint class inside the App class to specify the telemetry data
your device sends to your IoT hub:
private static class TelemetryDataPoint {
public String deviceId;
public double windSpeed;

public String serialize() {

Gson gson = new Gson();
return gson.toJson(this);
}
}

9. Add the following nested EventCallback class inside the App class to display the acknowledgement
status that the IoT hub returns when it processes a message from the simulated device app. This method
also notifies the main thread in the app when the message has been processed:

private static class EventCallback implements IotHubEventCallback

{
public void execute(IotHubStatusCode status, Object context) {
System.out.println("IoT Hub responded to message with status: " + status.name());

if (context != null) {
synchronized (context) {
context.notify();
}
}
}
}

10. Add the following nested MessageSender class inside the App class. The run method in this class
generates sample telemetry data to send to your IoT hub and waits for an acknowledgement before
sending the next message:
private static class MessageSender implements Runnable {
public volatile boolean stopThread = false;

public void run() {

try {
double avgWindSpeed = 10; // m/s
Random rand = new Random();

while (!stopThread) {
double currentWindSpeed = avgWindSpeed + rand.nextDouble() * 4 - 2;
TelemetryDataPoint telemetryDataPoint = new TelemetryDataPoint();
telemetryDataPoint.deviceId = deviceId;
telemetryDataPoint.windSpeed = currentWindSpeed;

String msgStr = telemetryDataPoint.serialize();

Message msg = new Message(msgStr);
System.out.println("Sending: " + msgStr);

Object lockobj = new Object();

EventCallback callback = new EventCallback();
client.sendEventAsync(msg, callback, lockobj);

synchronized (lockobj) {
lockobj.wait();
}
Thread.sleep(1000);
}
} catch (InterruptedException e) {
System.out.println("Finished.");
}
}
}

This method sends a new device-to-cloud message one second after the IoT hub acknowledges the
previous message. The message contains a JSON-serialized object with the deviceId and a randomly
generated number to simulate a wind speed sensor.
11. Replace the main method with the following code that creates a thread to send device-to-cloud messages
to your IoT hub:

public static void main( String[] args ) throws IOException, URISyntaxException {

client = new DeviceClient(connString, protocol);
client.open();

MessageSender sender = new MessageSender();

ExecutorService executor = Executors.newFixedThreadPool(1);

executor.execute(sender);

System.out.println("Press ENTER to exit.");

System.in.read();
executor.shutdownNow();
client.close();
}

12. Save and close the App.java file.

13. To build the simulated-device app using Maven, execute the following command at the command
prompt in the simulated-device folder:

mvn clean package -DskipTests

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as an exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Run the apps

You are now ready to run the apps.
1. At a command prompt in the read-d2c folder, run the following command to begin monitoring the first
partition in your IoT hub:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

2. At a command prompt in the simulated-device folder, run the following command to begin sending
telemetry data to your IoT hub:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

3. The Usage tile in the Azure portal shows the number of messages sent to the IoT hub:

Next steps
In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT
hub's identity registry. You used this device identity to enable the simulated device app to send device-to-cloud
messages to the IoT hub. You also created an app that displays the messages received by the IoT hub.
To continue getting started with IoT Hub and to explore other IoT scenarios, see:
Connecting your device
Getting started with device management
Getting started with the IoT Gateway SDK
To learn how to extend your IoT solution and process device-to-cloud messages at scale, see the Process device-
to-cloud messages tutorial.
Get started with Azure IoT Hub (Node)
1/17/2017 • 9 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications
between millions of Internet of Things (IoT) devices and a solution back end. One of the biggest challenges that
IoT projects face is how to reliably and securely connect devices to the solution back end. To address this
challenge, IoT Hub:
Offers reliable device-to-cloud and cloud-to-device hyper-scale messaging.
Enables secure communications using per-device security credentials and access control.
Includes device libraries for the most popular languages and platforms.
This tutorial shows you how to:
Use the Azure portal to create an IoT hub.
Create a device identity in your IoT hub.
Create a simulated device app that sends telemetry to your solution back end, and receives commands from
your solution back end.
At the end of this tutorial, you have three Node.js console apps:
CreateDeviceIdentity.js, which creates a device identity and associated security key to connect your
simulated device app.
ReadDeviceToCloudMessages.js, which displays the telemetry sent by your simulated device app.
SimulatedDevice.js, which connects to your IoT hub with the device identity created earlier, and sends a
telemetry message every second using the MQTT protocol.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both applications to
run on devices and your solution back end.

To complete this tutorial, you need the following:

Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete
this task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check
mark appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information,
see Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in
the Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access
policies.

6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

You have now created your IoT hub. You have the IoT Hub host name and the IoT Hub connection string that you
need to complete the rest of this tutorial.

Create a device identity

In this section, you create a Node.js console app that creates a device identity in the identity registry in your IoT
hub. A device cannot connect to IoT hub unless it has an entry in the identity registry. For more information, see
the Identity Registry section of the IoT Hub developer guide. When you run this console app, it generates a
unique device ID and key that your device can use to identify itself when it sends device-to-cloud messages to
IoT Hub.
1. Create a new empty folder called createdeviceidentity. In the createdeviceidentity folder, create a
package.json file using the following command at your command prompt. Accept all the defaults:

npm init
2. At your command prompt in the createdeviceidentity folder, run the following command to install the
azure-iothub Service SDK package:

npm install azure-iothub --save

3. Using a text editor, create a CreateDeviceIdentity.js file in the createdeviceidentity folder.

4. Add the following require statement at the start of the CreateDeviceIdentity.js file:

'use strict';

var iothub = require('azure-iothub');

5. Add the following code to the CreateDeviceIdentity.js file and replace the placeholder value with the IoT
Hub connection string for the hub you created in the previous section:

var connectionString = '{iothub connection string}';

var registry = iothub.Registry.fromConnectionString(connectionString);

6. Add the following code to create a device definition in the identity registry in your IoT hub. This code
creates a device if the device ID does not exist in the identity registry, otherwise it returns the key of the
existing device:

var device = new iothub.Device(null);

device.deviceId = 'myFirstNodeDevice';
registry.create(device, function(err, deviceInfo, res) {
if (err) {
registry.get(device.deviceId, printDeviceInfo);
}
if (deviceInfo) {
printDeviceInfo(err, deviceInfo, res)
}
});

function printDeviceInfo(err, deviceInfo, res) {

if (deviceInfo) {
console.log('Device ID: ' + deviceInfo.deviceId);
console.log('Device key: ' + deviceInfo.authentication.symmetricKey.primaryKey);
}
}

7. Save and close CreateDeviceIdentity.js file.

8. To run the createdeviceidentity application, execute the following command at the command prompt in
the createdeviceidentity folder:

node CreateDeviceIdentity.js

9. Make a note of the Device ID and Device key. You need these values later when you create an application
that connects to IoT Hub as a device.
NOTE
The IoT Hub identity registry only stores device identities to enable secure access to the IoT hub. It stores device IDs and
keys to use as security credentials and an enabled/disabled flag that you can use to disable access for an individual device.
If your application needs to store other device-specific metadata, it should use an application-specific store. For more
information, see the IoT Hub developer guide.

Receive device-to-cloud messages

In this section, you create a Node.js console app that reads device-to-cloud messages from IoT Hub. An IoT hub
exposes an Event Hubs-compatible endpoint to enable you to read device-to-cloud messages. To keep things
simple, this tutorial creates a basic reader that is not suitable for a high throughput deployment. The Process
device-to-cloud messages tutorial shows you how to process device-to-cloud messages at scale. The Get Started
with Event Hubs tutorial provides further information on how to process messages from Event Hubs and is
applicable to the IoT Hub Event Hub-compatible endpoints.

NOTE
The Event Hub-compatible endpoint for reading device-to-cloud messages always uses the AMQP protocol.

1. Create an empty folder called readdevicetocloudmessages. In the readdevicetocloudmessages

folder, create a package.json file using the following command at your command prompt. Accept all the
defaults:

npm init

2. At your command prompt in the readdevicetocloudmessages folder, run the following command to
install the azure-event-hubs package:

npm install azure-event-hubs --save

3. Using a text editor, create a ReadDeviceToCloudMessages.js file in the readdevicetocloudmessages

folder.
4. Add the following require statements at the start of the ReadDeviceToCloudMessages.js file:

'use strict';

var EventHubClient = require('azure-event-hubs').Client;

5. Add the following variable declaration and replace the placeholder value with the IoT Hub connection
string for your hub:

var connectionString = '{iothub connection string}';

6. Add the following two functions that print output to the console:
var printError = function (err) {
console.log(err.message);
};

var printMessage = function (message) {

console.log('Message received: ');
console.log(JSON.stringify(message.body));
console.log('');
};

7. Add the following code to create the EventHubClient, open the connection to your IoT Hub, and create a
receiver for each partition. This application uses a filter when it creates a receiver so that the receiver only
reads messages sent to IoT Hub after the receiver starts running. This filter is useful in a test environment
so you see just the current set of messages. In a production environment, your code should make sure
that it processes all the messages. For more information, see the How to process IoT Hub device-to-cloud
messages tutorial:

var client = EventHubClient.fromConnectionString(connectionString);

client.open()
.then(client.getPartitionIds.bind(client))
.then(function (partitionIds) {
return partitionIds.map(function (partitionId) {
return client.createReceiver('$Default', partitionId, { 'startAfterTime' :
Date.now()}).then(function(receiver) {
console.log('Created partition receiver: ' + partitionId)
receiver.on('errorReceived', printError);
receiver.on('message', printMessage);
});
});
})
.catch(printError);

8. Save and close the ReadDeviceToCloudMessages.js file.

Create a simulated device app

In this section, you create a Node.js console app that simulates a device that sends device-to-cloud messages to
an IoT hub.
1. Create an empty folder called simulateddevice. In the simulateddevice folder, create a package.json
file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the simulateddevice folder, run the following command to install the
azure-iot-device Device SDK package and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a SimulatedDevice.js file in the simulateddevice folder.

4. Add the following require statements at the start of the SimulatedDevice.js file:
'use strict';

var clientFromConnectionString = require('azure-iot-device-mqtt').clientFromConnectionString;

var Message = require('azure-iot-device').Message;

5. Add a connectionString variable and use it to create a Client instance. Replace {youriothostname}
with the name of the IoT hub you created the Create an IoT Hub section. Replace {yourdevicekey} with
the device key value you generated in the Create a device identity section:

var connectionString = 'HostName={youriothostname};DeviceId=myFirstNodeDevice;SharedAccessKey=

{yourdevicekey}';

var client = clientFromConnectionString(connectionString);

6. Add the following function to display output from the application:

function printResultFor(op) {
return function printResult(err, res) {
if (err) console.log(op + ' error: ' + err.toString());
if (res) console.log(op + ' status: ' + res.constructor.name);
};
}

7. Create a callback and use the setInterval function to send a message to your IoT hub every second:

var connectCallback = function (err) {

if (err) {
console.log('Could not connect: ' + err);
} else {
console.log('Client connected');

// Create a message and send it to the IoT Hub every second

setInterval(function(){
var windSpeed = 10 + (Math.random() * 4);
var data = JSON.stringify({ deviceId: 'myFirstNodeDevice', windSpeed: windSpeed });
var message = new Message(data);
console.log("Sending message: " + message.getData());
client.sendEvent(message, printResultFor('send'));
}, 1000);
}
};

8. Open the connection to your IoT Hub and start sending messages:

client.open(connectCallback);

9. Save and close the SimulatedDevice.js file.

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as an exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Run the apps

You are now ready to run the apps.
1. At a command prompt in the readdevicetocloudmessages folder, run the following command to begin
monitoring your IoT hub:

node ReadDeviceToCloudMessages.js

2. At a command prompt in the simulateddevice folder, run the following command to begin sending
telemetry data to your IoT hub:

node SimulatedDevice.js

3. The Usage tile in the Azure portal shows the number of messages sent to the IoT hub:
Next steps
In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT
hub's identity registry. You used this device identity to enable the simulated device app to send device-to-cloud
messages to the IoT hub. You also created an app that displays the messages received by the IoT hub.
To continue getting started with IoT Hub and to explore other IoT scenarios, see:
Connecting your device
Getting started with device management
Getting started with the IoT Gateway SDK
To learn how to extend your IoT solution and process device-to-cloud messages at scale, see the Process device-
to-cloud messages tutorial.
Get started with Raspberry Pi 3 (Node.js)
1/24/2017 • 3 min to read • Edit on GitHub

In this tutorial, you begin by learning the basics of working with Raspberry Pi 3 that's running Raspbian. You then
learn how to seamlessly connect your devices to the cloud by using Azure IoT Hub. For Windows 10 IoT Core
samples, go to the Windows Dev Center.
Don't have a kit yet? Start here.

Lesson 1: Configure your device

In this lesson, you configure your Raspberry Pi 3 device with an operating system, set up your development
environment, and deploy an application to Pi.
Configure your device
Configure Raspberry Pi 3 for first-time use and install Raspbian. Raspbian is a free operating system that is
optimized for the Raspberry Pi hardware.
Estimated time to complete: 30 minutes
Go to Configure your device.
Get the tools
Download the tools and software to build and deploy your first application for Raspberry Pi 3.
Estimated time to complete: 20 minutes
Go to Get the tools.
Create and deploy the blink application
Clone the sample Node.js blink application from GitHub, and use gulp to deploy this application to your Raspberry
Pi 3 board. This sample application blinks the LED connected to the board every two seconds.
Estimated time to complete: 5 minutes
Go to Create and deploy the blink application.

Lesson 2: Create your IoT hub

In this lesson, you create your free Azure account, provision your Azure IoT hub, and create your first device in the
IoT hub.
Complete Lesson 1 before you start this lesson.
Get the Azure tools
Install the Azure command-line interface (Azure CLI).
Estimated time to complete: 10 minutes
Go to Get Azure tools.
Create your IoT hub and register Raspberry Pi 3
Create your resource group, provision your first Azure IoT hub, and add your first device to the IoT hub by using
Azure CLI.
Estimated time to complete: 10 minutes
Go to Create your IoT hub and register Raspberry Pi 3.

Lesson 3: Send device-to-cloud messages

In this lesson, you send messages from Pi to your IoT hub. You also create an Azure function app that gets
incoming messages from your IoT hub and writes them to Azure Table storage.
Complete Lesson 1 and Lesson 2 before you start this lesson.
Create an Azure function app and Azure Storage account
Use an Azure Resource Manager template to create an Azure function app and an Azure Storage account.
Estimated time to complete: 10 minutes
Go to Create an Azure function app and Azure storage account.
Run a sample application to send device -to -cloud messages
Deploy and run a sample application to your Raspberry Pi 3 device that sends messages to the IoT hub.
Estimated time to complete: 10 minutes
Go to Run a sample application to send device-to-cloud messages.
Read messages persisted in Azure Storage
Monitor the device-to-cloud messages as they are written to Azure Storage.
Estimated time to complete: 5 minutes
Go to Read messages persisted in Azure Storage.

Lesson 4: Send cloud-to-device messages

This lesson shows how to send messages from your Azure IoT hub to Raspberry Pi 3. The messages control the on
and off behavior of the LED that is connected to Pi. A sample application is prepared for you to achieve this task.
Complete Lesson 1, Lesson 2, and Lesson 3 before you start this lesson.
Run the sample application to receive cloud-to -device messages
The sample application in Lesson 4 runs on Pi and monitors incoming messages from your IoT hub. A new gulp
task sends messages to Pi from your IoT hub to blink the LED.
Estimated time to complete: 10 minutes
Go to Run the sample application to receive cloud-to-device messages.
Optional section: Change the on and off behavior of the LED
Customize the messages to change the LED’s on and off behavior.
Estimated time to complete: 10 minutes
Go to Optional section: Change the on and off behavior of the LED.

Troubleshooting
If you have any trouble during the lessons, you can seek solutions in the Troubleshooting article.
Configure your device
1/24/2017 • 3 min to read • Edit on GitHub

What you will do

Configure Pi for first-time use and install the Raspbian operating system. Raspbian is a free operating system that
is optimized for the Raspberry Pi hardware. If you have any problems, you can seek solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install Raspbian on Pi.
How to power up Pi by using a USB cable.
How to connect Pi to the network by using an Ethernet cable or wireless network.
How to add an LED to the breadboard and connect it to Pi.

What you will need

To complete this operation, you need the following parts from your Raspberry Pi 3 Starter Kit:
The Raspberry Pi 3 board
The 16-GB microSD card
The 5-volt 2-amp power supply with the 6-foot micro USB cable
The breadboard
Connector wires
A 560-ohm resistor
A diffused 10-mm LED
The Ethernet cable

You also need:

A wired or wireless connection for Pi to connect to.
A USB-SD adapter or miniSD card to burn the operating system image onto the microSD card.
A computer running Windows, Mac, or Linux. The computer is used to install Raspbian on the microSD card.
An Internet connection to download the necessary tools and software.

Install Raspbian on the microSD card

Prepare the microSD card for installation of the Raspbian image.
1. Download Raspbian.
a. Download the .zip file for Raspbian Jessie with Pixel.
b. Extract the Raspbian image to a folder on your computer.
2. Install Raspbian to the microSD card.
a. Download and install the Etcher SD card burner utility.
b. Run Etcher and select the Raspbian image that you extracted in step 1.
c. Select the microSD card drive. Note that Etcher may have already selected the correct drive.
d. Click Flash to install Raspbian to the microSD card.
e. Remove the microSD card from your computer when installation is complete. It's safe to remove the
microSD card directly because Etcher automatically ejects or unmounts the microSD card upon
completion.
f. Insert the microSD card into Pi.

Turn on Pi
Turn on Pi by using the micro USB cable and the power supply.
NOTE
It is important to use the power supply in the kit that is at least 2A to make sure that your Raspberry has enough power to
work correctly.

Connect Raspberry Pi 3 to the network

You can connect Pi to a wired network or to a wireless network. Make sure that Pi is connected to the same
network as your computer. For example, you can connect Pi to the same switch that your computer is connected to.
Connect to a wired network
Use the Ethernet cable to connect Pi to your wired network. The two LEDs on Pi turn on if the connection is
established.
Connect to a wireless network
Follow the instructions from the Raspberry Pi Foundation to connect Pi to your wireless network. These
instructions require you to first connect a monitor and a keyboard to Pi.

Connect the LED to Pi

To complete this task, use the breadboard, the connector wires, the LED, and the resistor. Connect them to the
general-purpose input/output (GPIO) ports of Pi.

1. Connect the shorter leg of the LED to GPIO GND (Pin 6).
2. Connect the longer leg of the LED to one leg of the resistor.
3. Connect the other leg of the resistor to GPIO 4 (Pin 7).
Note that the LED polarity is important. This polarity setting is commonly known as Active Low.
Congratulations! You've successfully configured Pi.

Summary
In this article, you’ve learned how to configure Pi by installing Raspbian, connecting Pi to a network, and
connecting an LED to Pi. Note that the LED doesn't yet light up. The next task is to install the necessary tools and
software in preparation for running a sample application on Pi.
Next steps
Get the tools
Get the tools (Windows 7 or later)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for Raspberry Pi 3. If you have
any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum version requirement of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Windows.

Install Git and Node.js

Click the following links to download and install Git and Node.js LTS for Windows.
Get Git for Windows
Get Node.js LTS for Windows

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Pi. You also use the device-discovery-cli to
retrieve network information about your IoT devices.
Start a command prompt as an administrator. Install gulp and device-discovery-cli by running the following
command:

npm install -g device-discovery-cli gulp

If you experience issues installing Node.js and these additional Node.js development tools on your computer, see
the troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Pi.

Next steps
Create and deploy the blink sample application
Get the tools (Ubuntu 16.04)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for Raspberry Pi 3. If you have
any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What do you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Ubuntu 16.04 or later.

Install Git, Node.js, and NPM

Use the keyboard shortcut Ctrl + Alt + T to open a terminal and run the following commands:

sudo apt-get update

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install git

Install additional Node.js development tools

You use gulp.js to automate the deployment of the sample application to Pi. You also use the device-discovery-cli
to retrieve network information about your IoT devices.
Install gulp and device-discovery-cli by running the following command in the terminal:

sudo npm install -g device-discovery-cli gulp

If you experience issues installing Node.js and these additional development tools on Ubuntu, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Pi.

Next steps
Create and deploy the blink sample application
Get the tools (macOS 10.10)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Raspberry Pi 3. If you
have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A Mac that is running macOS Yosemite (10.10) or later.

Install Git and Node.js

To install Git and Node.js, use the Homebrew package management utility by following these steps:
1. Install Homebrew. If you've already installed Homebrew, go to step 2.
a. Press Cmd + Space and enter Terminal to open a terminal.
b. Run the following command:

/usr/bin/ruby -e "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Install Git and Node.js by running the following command:

brew install node git

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Pi. Use the device-discovery-cli to retrieve
network information about your IoT devices.
Install gulp and device-discovery-cli by running the following command in the terminal:
npm install -g device-discovery-cli gulp

If you experience issues installing Node.js and these additional development tools on macOS, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Pi.

Next steps
Create and deploy the blink sample application
Create and deploy the blink application
2/15/2017 • 3 min to read • Edit on GitHub

What you will do

Clone the sample Node.js application from GitHub and use the gulp tool to deploy the sample application to your
Raspberry Pi 3. The sample application blinks the LED connected to the board every two seconds. If you have any
problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to use the device-discover-cli tool to retrieve networking information about Pi.
How to deploy and run the sample application on Pi.
How to deploy and debug applications running remotely on Pi.

What you need

You must have successfully completed the following operations:
Configure your device
Get the tools

Obtain the IP address and host name of Pi

Open a command prompt in Windows or a terminal in macOS or Ubuntu, and then run the following command:

devdisco list --eth

You should see an output that is similar to the following:

Take note of the IP address and hostname of Pi. You need this information later in this article.

NOTE
Make sure that Pi is connected to the same network as your computer. For example, if your computer is connected to a
wireless network while Pi is connected to a wired network, you might not see the IP address in the devdisco output.
Clone the sample application
To open the sample code, follow these steps:
1. Clone the sample repository from GitHub by running the following command:

git clone https://github.com/Azure-Samples/iot-hub-node-raspberrypi-getting-started.git

2. Open the sample application in Visual Studio Code by running the following commands:

cd iot-hub-node-raspberrypi-getting-started
cd Lesson1
code .

The app.js file in the app subfolder is the key source file that contains the code to control the LED.
Install application dependencies
Install the libraries and other modules you need for the sample application by running the following command:

npm install

Configure the device connection

To configure the device connection, follow these steps:
1. Generate the device configuration file by running the following command:
gulp init

The configuration file config-raspberrypi.json contains the user credentials you use to log in to Pi. To
avoid the leak of user credentials, the configuration file is generated in the subfolder
.iot-hub-getting-started of the home folder on your computer.

2. Open the device configuration file in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-raspberrypi.json

# For macOS or Ubuntu

code ~/.iot-hub-getting-started/config-raspberrypi.json

3. Replace the placeholder [device hostname or IP address] with the IP address or the host name that you got
previously in "Obtain the IP address and host name of Pi."
NOTE
You can use SSH key instead of user name and password when connecting to Raspberry Pi. In order to do this you will have
to generate the key using ssh-keygen and ssh-copy-id pi@<device address>.
On Windows these commands are available in Git Bash.
On MacOS you need to run brew install ssh-copy-id.
After successfully uploading the key to the Raspberry Pi, replace device_password with device_key_path property in
config-raspberrypi.json.
Updated lines should look as below:

"device_user_name": "pi",
"device_key_path": "id_rsa",

Congratulations! You've successfully created the first sample application for Pi.

Deploy and run the sample application

Install Node.js and NPM on Pi
Install Node.js and NPM on Pi by running the following command:

gulp install-tools

This task might take 10 minutes to complete the first time you run it.
Deploy and run the sample app
Deploy and run the sample application by running the following command:

gulp deploy && gulp run

Verify the app works

You should now see the LED on Pi blinking every two seconds. If you don’t see the LED blinking, see the
troubleshooting guide for solutions to common problems.
Summary
You've installed the required tools to work with Pi and deployed a sample application to Pi to blink the LED. You
can now create, deploy, and run another sample application that connects Pi to Azure IoT Hub to send and receive
messages.

Next steps
Get the Azure tools
Get Azure tools (Windows 7 and later)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install Python and the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on
the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Python.
How to install the Azure CLI.

What you need

A Windows computer with an Internet connection.
An active Azure subscription. If you don't have an Azure account, create a free Azure trial account in just a few
minutes.

Install Python
Install Python on your Windows computer. You can install Python 2.7, 3.4 or 3.5. This tutorial is based on Python
2.7. If you've already installed Python, go to the next section and install the Azure CLI.
You also need to add the path of the folders where python.exe and pip.exe are installed to the system PATH
environment variable. By default, python.exe is installed in C:\Python27 and pip.exe is installed in
C:\Python27\Scripts .

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command-line to provision and manage resources.
To install the Azure CLI, follow these steps:
1. Open a Command Prompt window as an administrator.
2. Run the following commands:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

3. Verify the installation by running the following command:

az iot -h

You see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Raspberry Pi 3
Get Azure tools (Ubuntu 16.04)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install the Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

An Ubuntu computer with an Internet connection.
An active Azure subscription. If you don't have an account, you can create a free trial account in just a few
minutes.

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure, enabling you to work directly from
your command-line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

sudo apt-get update

sudo apt-get install -y libssl-dev libffi-dev
sudo apt-get install -y python-dev
sudo apt-get install -y build-essential
sudo apt-get install -y python-pip
sudo pip install --upgrade azure-cli
sudo pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity using the Azure
CLI.

Next steps
Create your IoT hub and register Raspberry Pi 3
Get Azure tools (macOS 10.10)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

A Mac with an Internet connection.
An active Azure subscription. If you don't have an Azure account, you can create a free Azure trial account in just
a few minutes.

Install Python
Although macOS comes with Python 2.7 out of the box, we recommend that you install Python through
Homebrew. See Installing Python on macOS.
Install Python and pip by running the following command:

brew install python

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command-line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Raspberry Pi 3
Create your IoT hub and register Raspberry Pi 3
2/15/2017 • 2 min to read • Edit on GitHub

What you will do

Create a resource group.
Create your Azure IoT hub in the resource group.
Add Raspberry Pi 3 to the Azure IoT hub by using the Azure command-line interface (Azure CLI).
When you use Azure CLI to add Pi to your IoT hub, the service generates a key for Pi to authenticate with the
service. If you have any problems, seek solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to use Azure CLI to create an IoT hub
How to create a device identity for Pi in your IoT hub

What you need

An Azure account
A Mac or a Windows computer with the Azure CLI installed

Create your IoT hub

Azure IoT Hub helps you connect, monitor, and manage millions of IoT assets. To create your IoT hub, follow these
steps:
1. Sign in to your Azure account by running the following command:

az login

All your available subscriptions are listed after a successful sign-in.

2. Set the default subscription that you want to use by running the following command:

az account set --subscription {subscription id or name}

subscription ID or name can be found in the output of the az login or the az account list command.
3. Register the provider by running the following command. Resource providers are services that provide
resources for your application. You must register the provider before you can deploy the Azure resource
that the provider offers.

az provider register -n "Microsoft.Devices"

4. Create a resource group named iot-sample in the West US region by running the following command:
az group create --name iot-sample --location westus

westus is the location you create your resource group. If you want to use another location, you can run
az account list-locations -o table to see all the locations Azure supports.

5. Create an IoT hub in the iot-sample resource group by running the following command:

az iot hub create --name {my hub name} --resource-group iot-sample

By default, the tool creates an IoT Hub in the Free pricing tier. For more infomation, see Azure IoT Hub
pricing.

NOTE
The name of your IoT hub must be globally unique. You can create only one F1 edition of Azure IoT Hub under your Azure
subscription.

Register Pi in your IoT hub

Each device that sends messages to your IoT hub and receives messages from your IoT hub must be registered
with a unique ID. You will use Azure CLI to register your Pi and create a self-signed X.509 certificate for device
authentication.
Run the following command:

# For Windows command prompt

az iot device create --device-id myraspberrypi --hub-name {my hub name} --x509 --output-dir
%USERPROFILE%\.iot-hub-getting-started

# For macOS or Ubuntu

az iot device create --device-id myraspberrypi --hub-name {my hub name} --x509 --output-dir ~/.iot-hub-
getting-started

Summary
You've created an IoT hub and registered Pi with a device identity in your IoT hub. You're ready to learn how to
send messages from Pi to your IoT hub.

Next steps
Create an Azure function app and an Azure storage account to process and store IoT hub messages
Run a sample application to send device-to-cloud
messages
1/24/2017 • 2 min to read • Edit on GitHub

What you will do

This article will show you how to deploy and run a sample application on Raspberry Pi 3 that sends messages to
your IoT hub. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

You will learn how to use the gulp tool to deploy and run the sample Node.js application on Pi.

What you need

Before you start this task, you must have successfully completed Create an Azure function app and a storage
account to process and store IoT hub messages.

Get your IoT hub and device connection strings

The device connection string is used by your Pi to connect to your IoT hub. The IoT hub connection string is used to
connect to the identity registry in your IoT hub to manage the devices that are allowed to connect to your IoT hub.
List all your IoT hubs in your resource group by running the following Azure CLI command:

az iot hub list -g iot-sample --query [].name

Use iot-sample as the value of {resource group name} if you didn't change the value.
Get the IoT hub connection string by running the following Azure CLI command:

az iot hub show-connection-string --name {my hub name} -g iot-sample

{my hub name} is the name that you specified when you created your IoT hub and registered Pi.
Get the device connection string by running the following command:

az iot device show-connection-string --hub-name {my hub name} --device-id myraspberrypi -g iot-sample

Use myraspberrypi as the value of {device id} if you didn't change the value.

Configure the device connection

1. Initialize the configuration file by running the following commands:

npm install
gulp init
2. Open the device configuration file config-raspberrypi.json in Visual Studio Code by running the following
command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-raspberrypi.json

# For macOS or Ubuntu

code ~/.iot-hub-getting-started/config-raspberrypi.json

3. Make the following replacements in the config-raspberrypi.json file:

Replace [device hostname or IP address] with the device IP address or host name you got from
device-discovery-cli or with the value inherited when you configured your device.
Replace [IoT device connection string] with the device connection string you obtained.
Replace [IoT hub connection string] with the iot hub connection string you obtained.

Update the config-raspberrypi.json file so that you can deploy the sample application from your computer.

Deploy and run the sample application

Deploy and run the sample application on Pi by running the following command:

gulp deploy && gulp run

Verify that the sample application works

You should see the LED that is connected to Pi blinking every two seconds. Every time the LED blinks, the sample
application sends a message to your IoT hub and verifies that the message has been successfully sent to your IoT
hub. In addition, each message received by the IoT hub is printed in the console window. The sample application
terminates automatically after sending 20 messages.

Summary
You've deployed and run the new blink sample application on Pi to send device-to-cloud messages to your IoT hub.
You can now monitor your messages as they are written to the storage account.

Next steps
Read messages persisted in Azure Storage
Read messages persisted in Azure Storage
2/15/2017 • 1 min to read • Edit on GitHub

What you will do

Monitor the device-to-cloud messages that are sent from Raspberry Pi 3 to your IoT hub as the messages are
written to your Azure Table storage. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn how to use the gulp read-message task to read messages persisted in your Azure Table
storage.

What you need

Before starting this process, you must have successfully completed Run the Azure blink sample application on
Raspberry Pi 3.

Read new messages from your storage account

In the previous article, you ran a sample application on Pi. The sample application sent messages to your Azure IoT
hub. The messages sent to your IoT hub are stored into your Azure Table storage via the Azure function app. You
need the Azure storage connection string to read messages from your Azure Table storage.
To read messages stored in your Azure Table storage, follow these steps:
1. Get the connection string by running the following commands:

az storage account list -g iot-sample --query [].name

az storage account show-connection-string -g iot-sample -n {storage name}

The first command retrieves the storage name that is used in the second command to get the connection
string. Use iot-sample as the value of {resource group name} if you didn't change the value.
2. Open the configuration file config-raspberrypi.json in Visual Studio Code by running the following
command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-raspberrypi.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-raspberrypi.json

3. Replace [Azure storage connection string] with the connection string you got in step 1.
4. Save the config-raspberrypi.json file.
5. Send messages again and read them from your Azure Table storage by running the following command:

gulp run --read-storage

The logic for reading from Azure Table storage is in the azure-table.js file.
Summary
You've successfully connected Pi to your IoT hub in the cloud and used the blink sample application to send device-
to-cloud messages. You also used the Azure function app to store incoming IoT hub messages to your Azure Table
storage. You can now send cloud-to-device messages from your IoT hub to Pi.

Next steps
Run the sample application to receive cloud-to-device messages
Run the sample application to receive cloud-to-
device messages
2/15/2017 • 3 min to read • Edit on GitHub

In this article, you deploy a sample application on Raspberry Pi 3. The sample application monitors incoming
messages from your IoT hub. You also run a gulp task on your computer to send messages to Pi from your IoT
hub. When the sample application receives the messages, it blinks the LED. If you have any problems, seek
solutions on the troubleshooting page.

What you will do

Connect the sample application to your IoT hub.
Deploy and run the sample application.
Send messages from your IoT hub to Pi to blink the LED.

What you will learn

In this article, you will learn:
How to monitor incoming messages from your IoT hub
How to send cloud-to-device messages from your IoT hub to Pi.

What you need

Raspberry Pi 3, set up for use. To learn how to set up Pi, see Configure your device.
An IoT hub that is created in your Azure subscription. To learn how to create your IoT hub, see Create your IoT
hub and register Raspberry Pi 3.

Connect the sample application to your IoT hub

1. Make sure that you're in the repo folder iot-hub-node-raspberrypi-getting-started . Open the sample
application in Visual Studio Code by running the following commands:

cd Lesson4
code .

Notice the app.js file in the app subfolder. The app.js file is the key source file that contains the code to
monitor incoming messages from the IoT hub. The blinkLED function blinks the LED.
2. Initialize the configuration file by using the following commands:

npm install
gulp init

If you completed the steps in Create an Azure function app and storage account on this computer, all the
configurations are inherited, so you can skip to the task of deploying and running the sample application. If
you completed the steps in Create an Azure function app and storage account on a different computer, you
need to replace the placeholders in the config-raspberrypi.json file. The config-raspberrypi.json file is in
the subfolder of your home folder.
Replace [device hostname or IP address] with the IP address of Pi or the host name that you get by running
the devdisco list --eth command.
Replace [IoT device connection string] with the device connection string that you get by running the
az iot device show-connection-string --hub-name {my hub name} --device-id {device id} -g iot-sample
{resource group name}
command.
Replace [IoT hub connection string] with the IoT hub connection string that you get by running the
az iot hub show-connection-string --name {my hub name} -g iot-sample {resource group name} command.

NOTE
Run gulp install-tools as well, if you haven't done it in Lesson 1.

Deploy and run the sample application

Deploy and run the sample application on Pi by running the following command:

gulp deploy && gulp run

The command deploys the sample application to Pi. Then, it runs the application on Pi and a separate task on your
host computer to send 20 blink messages to Pi from your IoT hub.
After the sample application runs, it starts listening to messages from your IoT hub. Meanwhile, the gulp task sends
several "blink" messages from your IoT hub to Pi. For each blink message that Pi receives, the sample application
calls the blinkLED function to blink the LED.
You should see the LED blink every two seconds as the gulp task sends 20 messages from your IoT hub to Pi. The
last one is a "stop" message that tells the application to stop running.
Summary
You’ve successfully sent messages from your IoT hub to Pi to blink the LED. The next task is optional: change the on
and off behavior of the LED.

Next steps
Change the on and off behavior of the LED
Change the on and off behavior of the LED
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Customize the messages to change the LED’s on and off behavior. If you have any problems, seek solutions on the
troubleshooting page.

What you will learn

Use additional Node.js functions to change the LED’s on and off behavior.

What you need

You must have successfully completed Run a sample application on Raspberry Pi to receive cloud-to-device
messages.

Add Node.js functions

1. Open the sample application in Visual Studio code by running the following commands:

cd Lesson4
code .

2. Open the app.js file, and then add the following functions at the end:

function turnOnLED() {
wpi.digitalWrite(CONFIG_PIN, 1);
}

function turnOffLED() {
wpi.digitalWrite(CONFIG_PIN, 0);
}
3. Add the following conditions before the default one in the switch-case block of the receiveMessageCallback
function:

case 'on':
turnOnLED();
break;
case 'off':
turnOffLED();
break;

Now you’ve configured the sample application to respond to more instructions through messages. The "on"
instruction turns on the LED, and the "off" instruction turns off the LED.
4. Open the gulpfile.js file, and then add a new function before the function sendMessage :

var buildCustomMessage = function (messageId) {

if ((messageId & 1) && (messageId < MAX_MESSAGE_COUNT)) {
return new Message(JSON.stringify({ command: 'on', messageId: messageId }));
} else if (messageId < MAX_MESSAGE_COUNT) {
return new Message(JSON.stringify({ command: 'off', messageId: messageId }));
} else {
return new Message(JSON.stringify({ command: 'stop', messageId: messageId }));
}
}
5. In the sendMessage function, replace the line var message = buildMessage(sentMessageCount); with the new
line shown in the following snippet:

var message = buildCustomMessage(sentMessageCount);

6. Save all the changes.

Deploy and run the sample application
Deploy and run the sample application on Pi by running the following command:

gulp deploy && gulp run

You should see the LED turn on for two seconds, and then turn off for another two seconds. The last "stop"
message stops the sample application from running.
Congratulations! You’ve successfully customized the messages that are sent to Pi from your IoT hub.
Summary
This optional section demonstrates how to customize messages so that the sample application can control the on
and off behavior of the LED in a different way.
Troubleshooting
2/10/2017 • 4 min to read • Edit on GitHub

Hardware issues
The application runs well but the LED is not blinking
This issue is always related to hardware circuit connectivity. Use the following steps to identify problems:
1. Check that you chose the correct GPIO on your board. The two ports should be GPIO GND (Pin 6) and
GPIO 04 (Pin 7).
2. Check that the polarity of your LED is correct. The longer leg should indicate the positive, anode pin.
3. Use the 3.3V Pin and GND Pin on Raspberry Pi 3. Treat Pi as the DC power. Check that the LED works fine.

Other hardware issues

For information about solving common problems on Raspberry Pi 3, see the official troubleshooting page.

Node.js package issues

No response during gulp tasks
If you encounter problems in running gulp tasks, you can add the --verbose option for debugging. Try to
terminate current gulp tasks by using Ctrl + C, and then run the following command in your console window
to see debug messages. You might see detailed error messages in your console output.

gulp --verbose

Device discovery issues

For help in troubleshooting common problems with the devdisco command, check the readme.
npm issues
Try to update your npm package by using the following command:

npm install -g npm

If the problem still exists, leave your comments at the end of this article or create a GitHub issue in our sample
repository.

Remote debugging
Run the sample application in debug mode

gulp run --debug

When the debug engine is ready, you should see Debugger listening on port 5858 in the console output.
Configure Visual Studio Code to connect to the remote device
1. Open the Debug panel on the left side.
2. Click the green Start Debugging (F5) button. Visual Studio Code opens a launch.json file.
3. Update the launch.json file with the following content. Replace [device hostname or IP address] with the
actual device IP address or host name.

NOTE
To learn more about the Visual Studio Debugging, please refer to Debugging in Visual Studio Code.

{
"version": "0.2.0",
"configurations": [
{
"name": "Attach",
"type": "node",
"request": "attach",
"port": 5858,
"address": "[device hostname or IP address]",
"restart": false,
"sourceMaps": false,
"outDir": null,
"localRoot": "${workspaceRoot}",
"remoteRoot": null
}
]
}
Attach to the remote application
Click the green Start Debugging (F5) button to start debugging.
Read JavaScript in VS Code to learn more about the debugger.
Azure CLI issues
The Azure command-line interface (Azure CLI) is a preview build. To seek solutions, you can use the Preview
Install Guide.
If you encounter any bugs with the tool, file an issue in the Issues section of the GitHub repo.
For help in troubleshooting common problems, check the readme.

Python installation issues

Legacy installation issues (macOS )
When you're installing pip, a permission error is thrown when older packages are installed with su
permissions. This situation occurs because a previous installation of Python using brew (macOS) is not
uninstalled completely. Some pip packages from a previous installation were created by root, which causes the
permission error. The solution is to remove those packages installed by root. Use the following steps to
complete this task:
1. Go to: /usr/local/lib/python2.7/site-packages
2. List packages created by root: ls -l | grep root
3. Uninstall packages from step 2: sudo rm -rf {package name}
4. Reinstall Python.

Azure IoT Hub issues

If you've successfully provisioned your Azure IoT hub with Azure CLI, and you need a tool to manage the
devices that are connecting to your IoT hub, try the following tools.
Device explorer
The Device explorer tool runs on your Windows local machine and connects to your IoT hub in Azure. It
communicates with the following IoT Hub endpoints:
Device identity management to provision and manage devices registered with your IoT hub.
Receive device-to-cloud so you can monitor messages sent from your device to your IoT hub.
Send cloud-to-device so you can send messages to your devices from your IoT hub.
Configure your IoT hub connection string within this tool to use all its capabilities.
iothub-explorer
iothub-explorer is a sample multiplatform CLI tool to manage devices. You can use the tool to manage the
devices in the identity registry, monitor device-to-cloud messages, and send cloud-to-device messages.
To install the latest (prerelease) version of the iothub-explorer tool, run the following command in your
command-line environment:

npm install -g iothub-explorer@latest

You can use the following command to get additional help about all the iothub-explorer commands and their
parameters:

iothub-explorer help

Azure portal
A full CLI experience helps you create and manage all your Azure resources. You might also want to use the
Azure portal to help provision, manage, and debug your Azure resources.

Azure Storage issues

Microsoft Azure Storage Explorer (preview) is a standalone app from Microsoft that you can use to work with
Azure Storage data on Windows, macOS, and Linux. By using this tool, you can connect to your table and see
the data in it. You can use this tool to troubleshoot your Azure Storage issues.
Get started with Raspberry Pi 3 (C)
1/24/2017 • 3 min to read • Edit on GitHub

In this tutorial, you begin by learning the basics of working with Raspberry Pi 3 that's running Raspbian. You then
learn how to seamlessly connect your devices to the cloud by using Azure IoT Hub. For Windows 10 IoT Core
samples, go to the Windows Dev Center.

Lesson 1: Configure your device

In this lesson, you configure your Raspberry Pi 3 device with an operating system, set up the development
environment, and deploy an application to Pi.
Configure your device
Configure Raspberry Pi 3 for first-time use and install Raspbian. Raspbian is a free operating system that is
optimized for the Raspberry Pi hardware.
Estimated time to complete: 30 minutes
Go to Configure your device.
Get the tools
Download the tools and software to build and deploy your first application for Raspberry Pi 3.
Estimated time to complete: 20 minutes
Go to Get the tools.
Create and deploy the blink application
Clone the sample C blink application from GitHub, and use gulp to deploy this application to your Raspberry Pi 3
board. This sample application blinks the LED connected to the board every two seconds.
Estimated time to complete: 5 minutes
Go to Create and deploy the blink application.

Lesson 2: Create your IoT hub

In this lesson, you create your free Azure account, provision your Azure IoT hub and create your first device in the
IoT hub.
Complete Lesson 1 before you start this lesson.
Get the Azure tools
Install the Azure command-line interface (Azure CLI).
Estimated time to complete: 10 minutes
Go to Get Azure tools.
Create your IoT hub and register Raspberry Pi 3
Create your resource group, provision your first Azure IoT hub, and add your first device to the IoT hub using Azure
CLI.
Estimated time to complete: 10 minutes
Go to Create your IoT hub and register Raspberry Pi 3.

Lesson 3: Send device-to-cloud messages

In this lesson, you send messages from Pi to your IoT hub. You also create an Azure function app that gets
incoming messages from your IoT hub and writes them to Azure Table storage.
Complete Lessons 1 and Lesson 2 before you start this lesson.
Create an Azure function app and Azure Storage account
Use an Azure Resource Manager template to create an Azure function app and an Azure Storage account.
Estimated time to complete: 10 minutes
Go to Create an Azure function app and Azure Storage account.
Run a sample application to send device -to -cloud messages
Deploy and run a sample application to your Raspberry Pi 3 device that sends messages to the IoT hub.
Estimated time to complete: 10 minutes
Go to Run a sample application to send device-to-cloud messages.
Read messages persisted in Azure Storage
Monitor the device-to-cloud messages as they are written to Azure Storage.
Estimated time to complete: 5 minutes
Go to Read messages persisted in Azure Storage.

Lesson 4: Send cloud-to-device messages

This lesson shows how to send messages from your Azure IoT hub to Raspberry Pi 3. The messages control the on
and off behavior of the LED that is connected to Pi. A sample application is prepared for you to achieve this task.
Complete Lessons 1, Lesson 2 and Lesson 3 before you start this lesson.
Run the sample application to receive cloud-to -device messages
The sample application in Lesson 4 runs on Pi and monitors incoming messages from your IoT hub. A new gulp
task sends messages to Pi from your IoT hub to blink the LED.
Estimated time to complete: 10 minutes
Go to Run the sample application to receive cloud-to-device messages.
Optional section: Change the on and off behavior of the LED
Customize the messages to change the LED’s on and off behavior.
Estimated time to complete: 10 minutes
Go to Optional section: Change the on and off behavior of the LED.

Troubleshooting
If you have any problems during the lessons, look for solutions in the Troubleshooting article.
Configure your device
1/24/2017 • 3 min to read • Edit on GitHub

What you will do

Configure Pi for first-time use and install the Raspbian operating system. Raspbian is a free operating system that
is optimized for the Raspberry Pi hardware. If you have any problems, look for solutions on the troubleshooting
page.

What you will learn

In this article, you will learn:
How to install Raspbian on Pi.
How to power up Pi by using a USB cable.
How to connect Pi to the network by using an Ethernet cable or wireless network.
How to add an LED to the breadboard and connect it to Pi.

What you need

To complete this operation, you need the following parts from your Raspberry Pi 3 Starter Kit:
The Raspberry Pi 3 board
The 16-GB microSD card
The 5-volt 2-amp power supply with the 6-foot micro USB cable
The breadboard
Connector wires
A 560-ohm resistor
A diffused 10-mm LED
The Ethernet cable

You also need:

A wired or wireless connection for Pi to connect to.
A USB-SD adapter or mini-SD card to burn the OS image onto the microSD card.
A computer running Windows, Mac, or Linux. The computer is used to install Raspbian on the microSD card.
An Internet connection to download the necessary tools and software.

Install Raspbian on the MicroSD card

Prepare the microSD card for installation of the Raspbian image.
1. Download Raspbian.
a. Download the .zip file for Raspbian Jessie with Pixel.
b. Extract the Raspbian image to a folder on your computer.
2. Install Raspbian to the microSD card.
a. Download and install the Etcher SD card burner utility.
b. Run Etcher and select the Raspbian image that you extracted in step 1.
c. Select the microSD card drive. Note that Etcher may have already selected the correct drive.
d. Click Flash to install Raspbian to the microSD card.
e. Remove the microSD card from your computer when installation is complete. It is safe to remove the
microSD card directly because Etcher automatically ejects or unmounts the microSD card upon
completion.
f. Insert the microSD card into your Pi.

Turn on Pi
Turn on Pi by using the micro USB cable and the power supply.
NOTE
It is important to use the power supply in the kit that is at least 2A to make sure that your Raspberry has enough power to
work correctly.

Connect Raspberry Pi 3 to the network

You can connect Pi to a wired network or to a wireless network. Make sure that Pi is connected to the same
network as your computer. For example, you can connect Pi to the same switch that your computer is connected to.
Connect to a wired network
Use the Ethernet cable to connect Pi to your wired network. The two LEDs on Pi turn on if the connection is
established.
Connect to a wireless network
Follow the instructions from the Raspberry Pi Foundation to connect Pi to your wireless network. These
instructions require you to first connect a monitor and a keyboard to Pi.

Connect the LED to Pi

To complete this task, use the breadboard, the connector wires, the LED, and the resistor. Connect them to the
general-purpose input/output (GPIO) ports of Pi.

1. Connect the shorter leg of the LED to GPIO GND (Pin 6).
2. Connect the longer leg of the LED to one leg of the resistor.
3. Connect the other leg of the resistor to GPIO 4 (Pin 7).
Note that the LED polarity is important. This polarity setting is commonly known as Active Low.
Congratulations! You've successfully configured Pi.

Summary
In this article, you’ve learned how to configure Pi by installing Raspbian, connecting Pi to a network, and
connecting an LED to Pi. Note that the LED doesn't yet light up. The next task is to install the necessary tools and
software in preparation for running a sample application on Pi.
Next steps
Get the tools
Get the tools (Windows 7 or later)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for Raspberry Pi 3. If you have
any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is C, Node.js tools are used in the lessons to discover devices, and
build and deploy sample applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum version requirement of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Windows.

Install Git and Node.js

Click the links below to download and install Git and Node.js LTS for Windows.
Get Git for Windows
Get Node.js LTS for Windows

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Pi. Use the device-discovery-cli to retrieve
network information about your IoT devices.
Start a command prompt as an administrator. Install gulp and device-discovery-cli by running the following
command:

npm install -g device-discovery-cli gulp

If you experience issues installing Node.js and these additional Node.js development tools on your computer, see
the troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Pi.

Next steps
Create and deploy the blink application
Get the tools (Ubuntu 16.04)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Raspberry Pi 3. If you
have any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is C, Node.js tools are used in the lessons to discover devices, and
build and deploy sample applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Ubuntu 16.04 or later.

Install Git, Node.js, and NPM

Use the keyboard shortcut Ctrl + Alt + T to open a terminal and run the following commands:

sudo apt-get update

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install git

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Pi. Use the device-discovery-cli to retrieve
network information about your IoT devices.
Install gulp and device-discovery-cli by running the following command in the terminal:
sudo npm install -g device-discovery-cli gulp

If you experience issues installing Node.js and these additional development tools on Ubuntu, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Pi.

Next steps
Create and deploy the blink application
Get the tools (macOS 10.10)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Raspberry Pi 3. If you
have any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is C, Node.js tools are used in the lessons to discover devices, and
build and deploy sample applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A Mac that is running macOS Yosemite (10.10) or later.

Install Git and Node.js

To install Git and Node.js, use the Homebrew package management utility by following these steps:
1. Install Homebrew. If you've already installed Homebrew, go to step 2.
a. Press Cmd + Space and enter Terminal to open a terminal.
b. Run the following command:

/usr/bin/ruby -e "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Install Git and Node.js by running the following command:

brew install node git

Install additional Node.js development tools
Use gulp.js to automate the deployment of the sample application to your Pi. Use the device-discovery-cli to
retrieve network information about your IoT devices.
Install gulp and device-discovery-cli by running the following command in the terminal:

sudo npm install -g device-discovery-cli gulp

If you experience issues installing Node.js and these additional development tools on macOS, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Pi.

Next steps
Create and deploy the blink application
Create and deploy the blink application
1/24/2017 • 3 min to read • Edit on GitHub

What you will do

Clone the sample C application from GitHub, and use the gulp tool to deploy the sample application to Raspberry
Pi 3. The sample application blinks the LED connected to the board every two seconds. If you have any problems,
look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to use the device-discover-cli tool to retrieve networking information about Pi.
How to deploy and run the sample application on Pi.
How to deploy and debug applications running remotely on Pi.

What you need

You must have successfully completed the following operations:
Configure your device
Get the tools

Obtain the IP address and host name of Pi

Open a command prompt in Windows or a terminal in macOS or Ubuntu, and then run the following command:

devdisco list --eth

You should see an output that is similar to the following:

Take note of the IP address and hostname of Pi. You need this information later in this article.

NOTE
Make sure that Pi is connected to the same network as your computer. For example, if your computer is connected to a
wireless network while Pi is connected to a wired network, you might not see the IP address in the devdisco output.
Open the sample application
To open the sample application, follow these steps:
1. Clone the sample repository from GitHub by running the following command:

git clone https://github.com/Azure-Samples/iot-hub-c-raspberrypi-getting-started.git

2. Open the sample application in Visual Studio Code by running the following commands:

cd iot-hub-c-raspberrypi-getting-started
cd Lesson1
code .

The main.c file in the app subfolder is the key source file that contains the code to control the LED.
Install application dependencies
Install the libraries and other modules you need for the sample application by running the following command:

npm install

Configure the device connection

To configure the device connection, follow these steps:
1. Generate the device configuration file by running the following command:
gulp init

The configuration file config-raspberrypi.json contains the user credentials you use to log in to Pi. To
avoid the leak of user credentials, the configuration file is generated in the subfolder
.iot-hub-getting-started of the home folder on your computer.

2. Open the device configuration file in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-raspberrypi.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-raspberrypi.json

3. Replace the placeholder [device hostname or IP address] with the IP address or the host name that you got
previously in "Obtain the IP address and host name of Pi."
NOTE
You can use SSH key instead of user name and password when connecting to Raspberry Pi. In order to do this you will have
to generate the key using ssh-keygen and ssh-copy-id pi@<device address>.
On Windows these commands are available in Git Bash.
On MacOS you need to run brew install ssh-copy-id.
After successfully uploading the key to the Raspberry Pi, replace device_password with device_key_path property in
config-raspberrypi.json.
Updated lines should look as below:

"device_user_name": "pi",
"device_key_path": "id_rsa",

Congratulations! You've successfully created the first sample application for Pi.

Deploy and run the sample application

Install the Azure IoT Hub SDK on Pi
Install the Azure IoT Hub SDK on Pi by running the following command:

gulp install-tools

This task might take a few minutes to complete the first time you run it.
Deploy and run the sample app
Deploy and run the sample application by running the following command:

gulp deploy && gulp run

Verify the app works

The sample application terminates automatically after the LED blinks for 20 times. If you don’t see the LED
blinking, see the troubleshooting guide for solutions to common problems.
Summary
You've installed the required tools to work with Pi and deployed a sample application to Pi to blink the LED. You
can now create, deploy, and run another sample application that connects Pi to Azure IoT Hub to send and receive
messages.

Next steps
Get Azure tools
Get Azure tools (Windows 7 and later)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install Python and the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on
the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Python.
How to install the Azure CLI.

What you need

A Windows computer with an Internet connection.
An active Azure subscription. If you don't have an Azure account, create a free Azure trial account in just a few
minutes.

Install Python
Install Python on your Windows computer. You can install Python 2.7, 3.4 or 3.5. This tutorial is based on Python
2.7. If you've already installed Python, go to the next section and install the Azure CLI.
You also need to add the path of the folders where python.exe and pip.exe are installed to the system PATH
environment variable. By default, python.exe is installed in C:\Python27 and pip.exe is installed in
C:\Python27\Scripts .

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the Azure CLI, follow these steps:
1. Open a Command Prompt window as an administrator.
2. Run the following commands:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

3. Verify the installation by running the following command:

az iot -h

You see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Raspberry Pi 3
Get Azure tools (Ubuntu 16.04)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install the Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

An Ubuntu computer with an Internet connection.
An active Azure subscription. If you don't have an account, you can create a free trial account in just a few
minutes.

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure, enabling you to work directly from
your command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

sudo apt-get update

sudo apt-get install -y libssl-dev libffi-dev
sudo apt-get install -y python-dev
sudo apt-get install -y build-essential
sudo apt-get install -y python-pip
sudo pip install --upgrade azure-cli
sudo pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity using the Azure
CLI.

Next steps
Create your IoT hub and register Raspberry Pi 3
Get Azure tools (macOS 10.10)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

A Mac with an Internet connection.
An active Azure subscription. If you don't have an Azure account, you can create a free Azure trial account in just
a few minutes.

Install Python
Although macOS comes with Python 2.7 out of the box, we recommend that you install Python through
Homebrew. See Installing Python on macOS.
Install Python and pip by running the following command:

brew install python

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Raspberry Pi 3
Create your IoT hub and register Raspberry Pi 3
1/24/2017 • 2 min to read • Edit on GitHub

What you will do

Create a resource group.
Create your Azure IoT hub in the resource group.
Add Raspberry Pi 3 to the Azure IoT hub by using the Azure command-line interface (Azure CLI).
When you use the Azure CLI to add Pi to your IoT hub, the service generates a key for Pi to authenticate with the
service. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to use the Azure CLI to create an IoT hub.
How to create a device identity for Pi in your IoT hub.

What you need

An Azure account
A Mac or a Windows computer with the Azure CLI installed

Create your IoT hub

Azure IoT Hub helps you connect, monitor, and manage millions of IoT assets. To create your IoT hub, follow these
steps:
1. Sign in to your Azure account by running the following command:

az login

All your available subscriptions are listed after a successful sign-in.

2. Set the default subscription that you want to use by running the following command:

az account set --subscription {subscription id or name}

subscription ID or name can be found in the output of the az login or the az account list command.
3. Register the provider by running the following command. Resource providers are services that provide
resources for your application. You must register the provider before you can deploy the Azure resource
that the provider offers.

az provider register -n "Microsoft.Devices"

4. Create a resource group named iot-sample in the West US region by running the following command:
az group create --name iot-sample --location westus

westus is the location you create your resource group. If you want to use another location, you can run
az account list-locations -o table to see all the locations Azure supports.

5. Create an IoT hub in the iot-sample resource group by running the following command:

az iot hub create --name {my hub name} --resource-group iot-sample

By default, the tool creates an IoT Hub in the Free pricing tier. For more infomation, see Azure IoT Hub
pricing.

NOTE
The name of your IoT hub must be globally unique. You can create only one F1 edition of Azure IoT Hub under your Azure
subscription.

Register Pi in your IoT hub

Each device that sends messages to your IoT hub and receives messages from your IoT hub must be registered
with a unique ID.
Register Pi in your hub by running following command:

az iot device create --device-id myraspberrypi --hub {my hub name} --resource-group iot-sample

Summary
You've created an IoT hub and registered Pi with a device identity in your IoT hub. You're ready to learn how to
send messages from Pi to your IoT hub.

Next steps
Create an Azure function app and an Azure Storage account to process and store IoT hub messages.
Create an Azure function app and Azure storage
account
1/24/2017 • 2 min to read • Edit on GitHub

Azure Functions is a solution for easily running functions (small pieces of code) in the cloud. An Azure function app
hosts the execution of your functions in Azure.

What will you do

Use an Azure Resource Manager template to create an Azure function app and an Azure storage account. The
Azure function app listens to Azure IoT hub events, processes incoming messages, and writes them to Azure Table
storage. If you have any problems, look for solutions on the troubleshooting page.

What will you learn

In this article, you will learn:
How to use Azure Resource Manager to deploy Azure resources.
How to use an Azure function app to process IoT hub messages and write them to a table in Azure Table
storage.

What do you need

You must have successfully completed:
Get started with your Raspberry Pi 3
Create your Azure IoT hub

Open the sample app

Open the sample project in Visual Studio Code by running the following commands:

cd Lesson3
code .
The main.c file in the app subfolder is the key source file. This source file contains the code to send a message
20 times to your IoT hub and blink the LED for each message it sends.
The arm-template.json file is the Azure Resource Manager template that contains an Azure function app and an
Azure storage account.
The arm-template-param.json file is the configuration file used by the Azure Resource Manager template.
The ReceiveDeviceMessages subfolder contains the Node.js code for the Azure function.

Configure Azure Resource Manager templates and create resources in

Azure
Update the arm-template-param.json file in Visual Studio Code.
Replace [your IoT Hub name] with {my hub name} that you specified when you created your IoT hub and
registered Raspberry Pi 3.
Replace [prefix string for new resources] with any prefix you want. The prefix ensures that the resource
name is globally unique to avoid conflict. Do not use a dash or number initial in the prefix.
After you update the arm-template-param.json file, deploy the resources to Azure by running the following
command:

az group deployment create --template-file arm-template.json --parameters @arm-template-param.json -g iot-

sample

It takes about five minutes to create these resources. While the resource creation is in progress, you can move on
to the next article.

Summary
You've created your Azure function app to process IoT hub messages and an Azure storage account to store these
messages. You can now deploy and run the sample to send device-to-cloud messages on Pi.

Next steps
Run a sample application to send device-to-cloud messages
Run a sample application to send device-to-cloud
messages
1/24/2017 • 2 min to read • Edit on GitHub

What you will do

This article will show you how to deploy and run a sample application on Raspberry Pi 3 that sends messages to
your IoT hub. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

You will learn how to use the gulp tool to deploy and run the sample Node.js application on Pi.

What you need

Before you start this task, you must have successfully completed Create an Azure function app and a storage
account to process and store IoT hub messages.

Get your IoT hub and device connection strings

The device connection string is used by your Pi to connect to your IoT hub. The IoT hub connection string is used to
connect to the identity registry in your IoT hub to manage the devices that are allowed to connect to your IoT hub.
List all your IoT hubs in your resource group by running the following Azure CLI command:

az iot hub list -g iot-sample --query [].name

Use iot-sample as the value of {resource group name} if you didn't change the value.
Get the IoT hub connection string by running the following Azure CLI command:

az iot hub show-connection-string --name {my hub name} -g iot-sample

{my hub name} is the name that you specified when you created your IoT hub and registered Pi.
Get the device connection string by running the following command:

az iot device show-connection-string --hub-name {my hub name} --device-id myraspberrypi -g iot-sample

Use myraspberrypi as the value of {device id} if you didn't change the value.

Configure the device connection

1. Initialize the configuration file by running the following commands:

npm install
gulp init
NOTE
Run gulp install-tools as well, if you haven't done it in Lesson 1.

1. Open the device configuration file config-raspberrypi.json in Visual Studio Code by running the following
command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-raspberrypi.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-raspberrypi.json

2. Make the following replacements in the config-raspberrypi.json file:

Replace [device hostname or IP address] with the device IP address or host name you got from
device-discovery-cli or with the value inherited when you configured your device.
Replace [IoT device connection string] with the device connection string you obtained.
Replace [IoT hub connection string] with the iot hub connection string you obtained.

NOTE
You don't need azure_storage_connection_string in this article. Keep it as is.

Update the config-raspberrypi.json file so that you can deploy the sample application from your computer.

Deploy and run the sample application

Deploy and run the sample application on Pi by running the following command:
gulp deploy && gulp run

Verify that the sample application works

You should see the LED that is connected to Pi blinking every two seconds. Every time the LED blinks, the sample
application sends a message to your IoT hub and verifies that the message has been successfully sent to your IoT
hub. In addition, each message received by the IoT hub is printed in the console window. The sample application
terminates automatically after sending 20 messages.

Summary
You've deployed and run the new blink sample application on Pi to send device-to-cloud messages to your IoT
hub. You now monitor your messages as they are written to the storage account.

Next steps
Read messages persisted in Azure Storage
Read messages persisted in Azure Storage
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Monitor the device-to-cloud messages that are sent from Raspberry Pi 3 to your IoT hub as the messages are
written to your Azure Table storage. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn how to use the gulp read-message task to read messages persisted in your Azure Table
storage.

What you need

Before starting this process, you must have successfully completed Run the Azure blink sample application on
Raspberry Pi 3.

Read new messages from your storage account

In the previous article, you ran a sample application on Pi. The sample application sent messages to your Azure IoT
hub. The messages sent to your IoT hub are stored into your Azure Table storage via the Azure function app. You
need the Azure storage connection string to read messages from your Azure Table storage.
To read messages stored in your Azure Table storage, follow these steps:
1. Get the connection string by running the following commands:

az storage account list -g iot-sample --query [].name

az storage account show-connection-string -g iot-sample -n {storage name}

The first command retrieves the storage name that is used in the second command to get the connection
string. Use iot-sample as the value of {resource group name} if you didn't change the value.
2. Open the configuration file config-raspberrypi.json in Visual Studio Code by running the following
command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-raspberrypi.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-raspberrypi.json

3. Replace [Azure storage connection string] with the connection string you got in step 1.
4. Save the config-raspberrypi.json file.
5. Send messages again and read them from your Azure Table storage by running the following command:

gulp run --read-storage

The logic for reading from Azure Table storage is in the azure-table.js file.
Summary
You've successfully connected Pi to your IoT hub in the cloud and used the blink sample application to send device-
to-cloud messages. You also used the Azure function app to store incoming IoT hub messages to your Azure Table
storage. You can now send cloud-to-device messages from your IoT hub to Pi.

Next steps
Run a sample application to receive cloud-to-device messages
Run a sample application to receive cloud-to-device
messages
1/27/2017 • 3 min to read • Edit on GitHub

In this article, you deploy a sample application on Raspberry Pi 3. The sample application monitors incoming
messages from your IoT hub. You also run a gulp task on your computer to send messages to Pi from your IoT
hub. When the sample application receives the messages, it blinks the LED. If you have any problems, look for
solutions on the troubleshooting page.

What you will do

Connect the sample application to your IoT hub.
Deploy and run the sample application.
Send messages from your IoT hub to Pi to blink the LED.

What you will learn

In this article, you will learn:
How to monitor incoming messages from your IoT hub.
How to send cloud-to-device messages from your IoT hub to Pi.

What you need

Raspberry Pi 3, set up for use. To learn how to set up Pi, see Configure your device.
An IoT hub that is created in your Azure subscription. To learn how to create your IoT hub, see Create your IoT
hub and register Raspberry Pi 3.

Connect the sample application to your IoT hub

1. Make sure that you're in the repo folder iot-hub-c-raspberrypi-getting-started . Open the sample
application in Visual Studio Code by running the following commands:

cd Lesson4
code .

Notice the app.c file in the app subfolder. The app.c file is the key source file that contains the code to
monitor incoming messages from the IoT hub. The blinkLED function blinks the LED.
2. Initialize the configuration file by running the following commands:

npm install
gulp init

If you completed the steps in Create an Azure function app and storage account on this computer, all the
configurations are inherited, so you can skip to step to the task of deploying and running the sample
application. If you completed the steps in Create an Azure function app and storage account on a different
computer, you need to replace the placeholders in the config-raspberrypi.json file. The
config-raspberrypi.json file is in the subfolder of your home folder.
Replace [device hostname or IP address] with Pi’s IP address or host name that you get by running the
devdisco list --eth command.
Replace [IoT device connection string] with the device connection string that you get by running the
az iot device show-connection-string --hub-name {my hub name} --device-id {device id} -g iot-sample
{resource group name}
command.
Replace [IoT hub connection string] with the IoT hub connection string that you get by running the
az iot hub show-connection-string --name {my hub name} -g iot-sample {resource group name} command.

NOTE
Run gulp install-tools as well, if you haven't done it in Lesson 1.

Deploy and run the sample application

Deploy and run the sample application on Pi by running the following commands:

gulp deploy && gulp run

The gulp command runs the install-tools task first. Then it deploys the sample application to Pi. Finally, it runs the
application on Pi and a separate task on your host computer to send 20 blink messages to Pi from your IoT hub.
After the sample application runs, it starts listening to messages from your IoT hub. Meanwhile, the gulp task sends
several "blink" messages from your IoT hub to Pi. For each blink message that Pi receives, the sample application
calls the blinkLED function to blink the LED.
You should see the LED blink every two seconds as the gulp task sends 20 messages from your IoT hub to Pi. The
last one is a "stop" message that stops the application from running.
Summary
You’ve successfully sent messages from your IoT hub to Pi to blink the LED. The next task is optional: change the on
and off behavior of the LED.

Next steps
Change the on and off behavior of the LED
Change the on and off behavior of the LED
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Customize the messages to change the LED’s on and off behavior. If you have any problems, look for solutions on
the troubleshooting page.

What you will learn

Use additional Node.js functions to change the LED’s on and off behavior.

What you need

You must have successfully completed Run a sample application on Raspberry Pi to receive cloud to device
messages.

Add functions to main.c and gulpfile.js

1. Open the sample application in Visual Studio code by running the following commands:

cd Lesson4
code .

2. Open the main.c file, and then add the following functions after blinkLED() function:

static void turnOnLED()

{
digitalWrite(LED_PIN, HIGH);
}

static void turnOffLED()

{
digitalWrite(LED_PIN, LOW);
}
3. Add the following conditions before the default one in the if block of the receiveMessageCallback function:

else if (0 == strcmp((const char*)value, "\"on\""))

{
turnOnLED();
}
else if (0 == strcmp((const char*)value, "\"off\""))
{
turnOffLED();
}

Now you’ve configured the sample application to respond to more instructions through messages. The "on"
instruction turns on the LED, and the "off" instruction turns off the LED.
4. Open the gulpfile.js file, and then add a new function before the function sendMessage :

var buildCustomMessage = function (messageId) {

if ((messageId & 1) && (messageId < MAX_MESSAGE_COUNT)) {
return new Message(JSON.stringify({ command: 'on', messageId: messageId }));
} else if (messageId < MAX_MESSAGE_COUNT) {
return new Message(JSON.stringify({ command: 'off', messageId: messageId }));
} else {
return new Message(JSON.stringify({ command: 'stop', messageId: messageId }));
}
}
5. In the sendMessage function, replace the line var message = buildMessage(sentMessageCount); with the new
line shown in the following snippet:

var message = buildCustomMessage(sentMessageCount);

6. Save all the changes.

Deploy and run the sample application
Deploy and run the sample application on Pi by running the following command:

gulp deploy && gulp run

You should see the LED turn on for two seconds, and then turn off for another two seconds. The last "stop"
message stops the sample application from running.
Congratulations! You’ve successfully customized the messages that are sent to Pi from your IoT hub.
Summary
This optional section demonstrates how to customize messages so that the sample application can control the on
and off behavior of the LED in a different way.
Troubleshooting
1/24/2017 • 3 min to read • Edit on GitHub

Hardware issues
The application runs well but the LED is not blinking
This issue is always related to the hardware circuit connectivity. Use the following steps to identify problems.
1. Check that you chose the correct GPIO on your board. The two ports should be GPIO GND (Pin 6) and
GPIO 04 (Pin 7).
2. Check that the polarity of your LED is correct. The longer leg should indicate the positive, anode pin.
3. Use the 3.3V Pin and GND Pin on Raspberry Pi 3. Treat Pi as the DC power. Check that the LED works fine.

Other hardware issues

For information about solving common problems on Raspberry Pi 3, see the official troubleshooting page.

Node.js package issues

No response during gulp tasks
If you encounter problems running gulp tasks, you can add the --verbose option for debugging. Try to
terminate current gulp tasks by using Ctrl + C , and then run the following command in your console window
to see debug messages. You might see detailed error messages in your console output.

gulp --verbose

Device discovery issues

For help in troubleshooting common problems with the devdisco command, check the readme.
NPM issues
Try to update your NPM package with the following command:

npm install -g npm

If the problem still exists, leave your comments at the end of this article or create a GitHub issue in our sample
repository

Remote debugging
Remote debugging support will be available soon in Visual Studio Code C/C++ Extension.
In a meanwhile you can use GDB via your favourite SSH terminal:

cd c-pi-lesson-x
sudo gdb app

Azure-CLI issues
The Azure command-line interface (Azure CLI) is a preview build. Look for solution in the Preview Install Guide
to seek solutions. Try to upgrade Azure-cli to latest version when commands don’t work as expected.
If you encounter any bugs with the tool, file an issue in the Issues section of the GitHub repo.
For help troubleshooting common problems, check the readme.
If you meet "Could not find a version that satisfies the requirement", please run the following command to
upgrade pip to lastest version.

python -m pip install --upgrade pip

Python installation issues

Legacy installation issues (macOS )
When you're installing pip, a permission error is thrown when older packages that are installed with su
permissions. This situation occurs because a previous installation of Python using brew (macOS) is not
uninstalled completely. Some pip packages from a previous installation were created by root, which causes
the permission error. The solution is to remove those packages installed by root. Use the following steps to
complete this task:
1. Go to: /usr/local/lib/python2.7/site-packages
2. List packages create by root: ls -l | grep root
3. Uninstall packages from step 2: sudo rm -rf {package name}
4. Reinstall Python.

Azure IoT Hub issues

If you've successfully provisioned your Azure IoT hub with azure-cli , and you need a tool to manage the
devices that are connecting to your IoT hub, try the following tools:
Device Explorer
Device Explorer runs on your Windows local machine and connects to your IoT hub in Azure. It communicates
with the following IoT Hub endpoints:
Device identity management to provision and manage devices registered with your IoT hub.
Receive device-to-cloud so you can monitor messages sent from your device to your IoT hub.
Send cloud-to-device so you can send messages to your devices from your IoT hub.
Configure your IoT hub connection string within this tool to use all its capabilities.
IoT hub Explorer
IoT hub Explorer is a sample multiplatform CLI tool to manage device clients. You can use the tool to manage
the devices in the identity registry, monitor device-to-cloud messages, and send cloud-to-device commands.
To install the latest (prerelease) version of the iothub-explorer tool, run the following command in your
command-line environment:

npm install -g iothub-explorer@latest

You can use the following command to get additional help about all the iothub-explorer commands and their
parameters:

iothub-explorer help

Azure portal
A full CLI experience helps you create and manage all your Azure resources. You might also want to use the
Azure portal to help provision, manage, and debug your Azure resources.

Azure storage issues

Microsoft Azure Storage Explorer (preview) is a standalone app from Microsoft that you can use to work with
Azure Storage data on Windows, macOS, and Linux. By using this tool, you can connect to your table and see
the data in it. You can use this tool to troubleshoot your Azure Storage issues.
Get started with Intel Edison (Node.js)
1/25/2017 • 3 min to read • Edit on GitHub

In this tutorial, you begin by learning the basics of working with Intel Edison. You then learn how to seamlessly
connect your devices to the cloud by using Azure IoT Hub.
Don't have a kit yet? Start here

Lesson 1: Configure your device

In this lesson, you configure your Intel Edison with an operating system, set up the development environment, and
deploy an application to Edison.
Configure your device
Configure Intel Edison for first-time use by assembling the board, powering it up and installing configuration tool
to your desktop OS to flash Edison's firmware, set its password and connect it to Wi-Fi.
Estimated time to complete: 30 minutes
Go to Configure your device.
Get the tools
Download the tools and software to build and deploy your first application for Intel Edison.
Estimated time to complete: 20 minutes
Go to Get the tools.
Create and deploy the blink application
Clone the sample blink application from GitHub, and use gulp to deploy this application to your Intel Edison board.
This sample application blinks the LED connected to the board every two seconds.
Estimated time to complete: 5 minutes
Go to Create and deploy the blink application.

Lesson 2: Create your IoT hub

In this lesson, you create your free Azure account, provision your Azure IoT hub and create your first device in the
IoT hub.
Complete Lesson 1 before you start this lesson.
Get the Azure tools
Install the Azure command-line interface (Azure CLI).
Estimated time to complete: 10 minutes
Go to Get Azure tools.
Create your IoT hub and register Intel Edison
Create your resource group, provision your first Azure IoT hub, and add your first device to the IoT hub using Azure
CLI.
Estimated time to complete: 10 minutes
Go to Create your IoT hub and register Intel Edison.

Lesson 3: Send device-to-cloud messages

In this lesson, you send messages from Edison to your IoT hub. You also create an Azure function app that gets
incoming messages from your IoT hub and writes them to Azure Table storage.
Complete Lessons 1 and Lesson 2 before you start this lesson.
Create an Azure function app and Azure Storage account
Use an Azure Resource Manager template to create an Azure function app and an Azure Storage account.
Estimated time to complete: 10 minutes
Go to Create an Azure function app and Azure Storage account.
Run a sample application to send device -to -cloud messages
Deploy and run a sample application to your Intel Edison device that sends messages to the IoT hub.
Estimated time to complete: 10 minutes
Go to Run a sample application to send device-to-cloud messages.
Read messages persisted in Azure Storage
Monitor the device-to-cloud messages as they are written to Azure Storage.
Estimated time to complete: 5 minutes
Go to Read messages persisted in Azure Storage.

Lesson 4: Send cloud-to-device messages

This lesson shows how to send messages from your Azure IoT hub to Intel Edison. The messages control the on and
off behavior of the LED that is connected to Edison. A sample application is prepared for you to achieve this task.
Complete Lessons 1, Lesson 2 and Lesson 3 before you start this lesson.
Run the sample application to receive cloud-to -device messages
The sample application in Lesson 4 runs on Edison and monitors incoming messages from your IoT hub. A new
gulp task sends messages to Edison from your IoT hub to blink the LED.
Estimated time to complete: 10 minutes
Go to Run the sample application to receive cloud-to-device messages.
Optional section: Change the on and off behavior of the LED
Customize the messages to change the LED’s on and off behavior.
Estimated time to complete: 10 minutes
Go to Optional section: Change the on and off behavior of the LED.

Troubleshooting
If you have any problems during the lessons, look for solutions in the Troubleshooting article.
Configure your Intel Edison
1/25/2017 • 4 min to read • Edit on GitHub

What you will do

Configure Intel Edison for first-time use by assembling the board, powering it up and installing configuration tool
to your desktop OS to flash Edison's firmware, set its password and connect it to Wi-Fi. If you have any problems,
look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to assemble Edison board and power it up.
How to flash Edison's firmware, set password and connect Wi-Fi.

What you need

To complete this operation, you need the following parts from your Intel Edison Starter Kit:
Intel® Edison module
Arduino expansion board
Any spacer bars or screws included in the packaging, including two screws to fasten the module to the
expansion board and four sets of screws and plastic spacers.
A Micro B to Type A USB cable
A direct current (DC) power supply. Your power supply should be rated as follows:
7-15V DC
At least 1500mA
The center/inner pin should be the positive pole of the power supply

You also need:

A computer running Windows, Mac, or Linux.
A wireless connection for Edison to connect to.
An Internet connection to download configuration tool.
Assemble your board
This section contains steps to attach your Intel® Edison module to your expansion board.
1. Place the Intel® Edison module within the white outline on your expansion board, lining up the holes on the
module with the screws on the expansion board.
2. Press down on the module just below the words What will you make? until you feel a snap.

3. Use the two hex nuts (included in the package) to secure the module to the expansion board.
4. Insert a screw in one of the four corner holes on the expansion board. Twist and tighten one of the white
plastic spacers onto the screw.

5. Repeat for the other three corner spacers.

Now your board is assembled.

Power up Edison
1. Plug in the power supply.

2. A green LED(labeled DS1 on the Arduino* expansion board) should light up and stay lit.
3. Wait one minute for the board to finish booting up.

NOTE
If you do not have a DC power supply, you can still power the board through a USB port. See
Connect Edison to your computer section for details. Powering your board in this fashion may result in
unpredictable behavior from your board, especially when using Wi-Fi or driving motors.

Connect Edison to your computer

1. Toggle down the microswitch towards the two micro USB ports, so that Edison is in device mode. For
differences between device mode and host mode, please reference here.
2. Plug the micro USB cable into the top micro USB port.
3. Plug the other end of USB cable into your computer.

4. You will know that your board is fully initialized when your computer mounts a new drive (much like
inserting a SD card into your computer).
Download and run the configuration tool
Get the latest configuration tool from this link listed under the Installers heading. Execute the tool and follow its
on-screen instructions, clicking Next where needed
Flash firmware
1. On the Set up options page, click Flash Firmware .
2. Select the image to flash onto your board by doing one of the following:
To download and flash your board with the latest firmware image available from Intel, select
Download the latest image version xxxx .
To flash your board with an image you already have saved on your computer, select
Select the local image . Browse to and select the image you want to flash to your board.
3. The setup tool will attempt to flash your board. The entire flashing process may take up to 10 minutes.
Set password
1. On the Set up options page, click Enable Security .
2. You can set a custom name for your Intel® Edison board. This is optional.
3. Type a password for your board, then click Set password .
4. Mark down the password, which is used later.
Connect Wi-Fi
1. On the Set up options page, click Connect Wi-Fi . Wait up to one minute as your computer scans for available
Wi-Fi networks.
2. From the Detected Networks drop-down list, select your network.
3. From the Security drop-down list, select the network's security type.
4. Provide your login and password information, then click Configure Wi-Fi .
5. Mark down the IP address, which is used later.

NOTE
Make sure that Edison is connected to the same network as your computer. Your computer connects to your Edison by
using the IP address.

Congratulations! You've successfully configured Edison.

Summary
In this article, you’ve learned how to assemble the Edison board, flash its firmware, setup password and connect it
to Wi-Fi by using configuration tool. Note that the LED doesn't yet light up. The next task is to install the necessary
tools and software in preparation for running a sample application on Edison.

Next steps
Get the tools
Get the tools (Windows 7 or later)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for Intel Edison. If you have any
problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum version requirement of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Windows.

Install Git and Node.js

Click the links below to download and install Git and Node.js LTS for Windows.
Get Git for Windows
Get Node.js LTS for Windows

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Edison.
Start a command prompt as an administrator. Install gulp by running the following command:

npm install -g gulp

If you experience issues installing Node.js and these additional Node.js development tools on your computer, see
the troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.
Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Edison.

Next steps
Create and deploy the blink application
Get the tools (Ubuntu 16.04)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Intel Edison. If you have
any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Git and Node.js
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Ubuntu 16.04 or later.

Install Git, Node.js, and NPM

Use the keyboard shortcut Ctrl + Alt + T to open a terminal and run the following commands:

sudo apt-get update

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install git

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Edison.
Install gulp by running the following command in the terminal:

sudo npm install -g gulp

If you experience issues installing Node.js and these additional development tools on Ubuntu, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Edison.

Next steps
Create and deploy the blink sample application
Get the tools (macOS 10.10)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Intel Edison. If you have
any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A Mac that is running macOS Yosemite (10.10) or later.

Install Git and Node.js

To install Git and Node.js, use the Homebrew package management utility by following these steps:
1. Install Homebrew. If you've already installed Homebrew, go to step 2.
a. Press Cmd + Space and enter Terminal to open a terminal.
b. Run the following command:

/usr/bin/ruby -e "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Install Git and Node.js by running the following command:

brew install node git

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to your Edison.
Install gulp by running the following command in the terminal:
sudo npm install -g gulp

If you experience issues installing Node.js and these additional development tools on macOS, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Edison.

Next steps
Create and deploy the blink application
Create and deploy the blink application
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Clone the sample C application from GitHub, and use the gulp tool to deploy the sample application to Intel
Edison. The sample application blinks the LED connected to the board every two seconds. If you have any
problems, look for solutions on the troubleshooting page.

What you will learn

How to deploy and run the sample application on Edison.

What you need

You must have successfully completed the following operations:
Configure your device
Get the tools

Open the sample application

To open the sample application, follow these steps:
1. Clone the sample repository from GitHub by running the following command:

git clone https://github.com/Azure-Samples/iot-hub-node-edison-getting-started.git

2. Open the sample application in Visual Studio Code by running the following commands:

cd iot-hub-node-edison-getting-started
cd Lesson1
code .
The file in the app subfolder is the key source file that contains the code to control the LED.
Install application dependencies
Install the libraries and other modules you need for the sample application by running the following command:

npm install

Configure the device connection

To configure the device connection, follow these steps:
1. Generate the device configuration file by running the following command:

gulp init

The configuration file config-edison.json contains the user credentials you use to log in to Edison. To avoid
the leak of user credentials, the configuration file is generated in the subfolder .iot-hub-getting-started of
the home folder on your computer.
2. Open the device configuration file in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-edison.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-edison.json

3. Replace the placeholder [device hostname or IP address] and [device password] with the IP address and
password that you marked down in previous lesson.
Congratulations! You've successfully created the first sample application for Edison.

Deploy and run the sample application

Deploy and run the sample app
Deploy and run the sample application by running the following command:

gulp deploy && gulp run

Verify the app works

The sample application terminates automatically after the LED blinks for 20 times. If you don’t see the LED
blinking, see the troubleshooting guide for solutions to common problems.
Summary
You've installed the required tools to work with Edison and deployed a sample application to Edison to blink the
LED. You can now create, deploy, and run another sample application that connects Edison to Azure IoT Hub to
send and receive messages.

Next steps
Get the Azure tools
Get Azure tools (Windows 7 and later)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Install Python and the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on
the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Python.
How to install the Azure CLI.

What you need

A Windows computer with an Internet connection.
An active Azure subscription. If you don't have an Azure account, create a free Azure trial account in just a few
minutes.

Install Python
Install Python on your Windows computer. You can install Python 2.7, 3.4 or 3.5. This tutorial is based on Python
2.7. If you've already installed Python, go to the next section and install the Azure CLI.
You also need to add the path of the folders where python.exe and pip.exe are installed to the system PATH
environment variable. By default, python.exe is installed in C:\Python27 and pip.exe is installed in
C:\Python27\Scripts .

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the Azure CLI, follow these steps:
1. Open a Command Prompt window as an administrator.
2. Run the following commands:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

3. Verify the installation by running the following command:

az iot -h

You see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Intel Edison
Get Azure tools (Ubuntu 16.04)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install the Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

An Ubuntu computer with an Internet connection.
An active Azure subscription. If you don't have an account, you can create a free trial account in just a few
minutes.

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure, enabling you to work directly from
your command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

sudo apt-get update

sudo apt-get install -y libssl-dev libffi-dev
sudo apt-get install -y python-dev
sudo apt-get install -y build-essential
sudo apt-get install -y python-pip
sudo pip install --upgrade azure-cli
sudo pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity using the Azure
CLI.

Next steps
Create your IoT hub and register Intel Edison
Get Azure tools (macOS 10.10)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

A Mac with an Internet connection.
An active Azure subscription. If you don't have an Azure account, you can create a free Azure trial account in just
a few minutes.

Install Python
Although macOS comes with Python 2.7 out of the box, we recommend that you install Python through
Homebrew. See Installing Python on macOS.
Install Python and pip by running the following command:

brew install python

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Intel Edison
Create your IoT hub and register Intel Edison
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Create a resource group.
Create your Azure IoT hub in the resource group.
Add Intel Edison to the Azure IoT hub by using the Azure command-line interface (Azure CLI).
When you use the Azure CLI to add Edison to your IoT hub, the service generates a key for Edison to authenticate
with the service. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to use the Azure CLI to create an IoT hub.
How to create a device identity for Edison in your IoT hub.

What you need

An Azure account. If you don't have an Azure account, create a free Azure trial account in just a few minutes.
You should have the Azure CLI installed.

Create your IoT hub

Azure IoT Hub helps you connect, monitor, and manage millions of IoT assets. To create your IoT hub, follow these
steps:
1. Sign in to your Azure account by running the following command:

az login

All your available subscriptions are listed after a successful sign-in.

2. Set the default subscription that you want to use by running the following command:

az account set --subscription {subscription id or name}

subscription ID or name can be found in the output of the az login or the az account list command.
3. Register the provider by running the following command. Resource providers are services that provide
resources for your application. You must register the provider before you can deploy the Azure resource
that the provider offers.

az provider register -n "Microsoft.Devices"

4. Create a resource group named iot-sample in the West US region by running the following command:
az group create --name iot-sample --location westus

westus is the location you create your resource group. If you want to use another location, you can run
az account list-locations -o table to see all the locations Azure supports.

5. Create an IoT hub in the iot-sample resource group by running the following command:

az iot hub create --name {my hub name} --resource-group iot-sample

By default, the tool creates an IoT Hub in the Free pricing tier. For more infomation, see Azure IoT Hub pricing.

NOTE
The name of your IoT hub must be globally unique. You can create only one F1 edition of Azure IoT Hub under your Azure
subscription.

Register Edison in your IoT hub

Each device that sends messages to your IoT hub and receives messages from your IoT hub must be registered
with a unique ID.
Register Edison in your IoT hub by running following command:

az iot device create --device-id myinteledison --hub-name {my hub name}

Summary
You've created an IoT hub and registered Edison with a device identity in your IoT hub. You're ready to learn how
to send messages from Edison to your IoT hub.

Next steps
Create an Azure function app and an Azure Storage account to process and store IoT hub messages.
Run a sample application to send device-to-cloud
messages
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

This article will show you how to deploy and run a sample application on Intel Edison that sends messages to your
IoT hub. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

You will learn how to use the gulp tool to deploy and run the sample C application on Edison.

What you need

Before you start this task, you must have successfully completed Create an Azure function app and a storage
account to process and store IoT hub messages.

Get your IoT hub and device connection strings

The device connection string is used to connect Edison to your IoT hub. The IoT hub connection string is used to
connect your IoT hub to the device identity that represents Edison in the IoT hub.
List all your IoT hubs in your resource group by running the following Azure CLI command:

az iot hub list -g iot-sample --query [].name

Use iot-sample as the value of {resource group name} if you didn't change the value.
Get the IoT hub connection string by running the following Azure CLI command:

az iot hub show-connection-string --name {my hub name}

{my hub name} is the name that you specified when you created your IoT hub and registered Edison.
Get the device connection string by running the following command:

az iot device show-connection-string --hub-name {my hub name} --device-id myinteledison

Use myinteledison as the value of {device id} if you didn't change the value.

Configure the device connection

1. Initialize the configuration file by running the following commands:

npm install
gulp init
2. Open the device configuration file config-edison.json in Visual Studio Code by running the following
command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-edison.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-edison.json

3. Make the following replacements in the config-edison.json file:

Replace [device hostname or IP address] with the device IP address you marked down when you
configured your device.
Replace [IoT device connection string] with the device connection string you obtained.
Replace [IoT hub connection string] with the iot hub connection string you obtained.

NOTE
You don't need azure_storage_connection_string in this article. Keep it as is.

Deploy and run the sample application

Deploy and run the sample application on Edison by running the following command:

gulp deploy && gulp run

Verify that the sample application works

You should see the LED that is connected to Edison blinking every two seconds. Every time the LED blinks, the
sample application sends a message to your IoT hub and verifies that the message has been successfully sent to
your IoT hub. In addition, each message received by the IoT hub is printed in the console window. The sample
application terminates automatically after sending 20 messages.

Summary
You've deployed and run the new blink sample application on Edison to send device-to-cloud messages to your IoT
hub. You now monitor your messages as they are written to the storage account.

Next steps
Read messages persisted in Azure Storage
Read messages persisted in Azure Storage
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Monitor the device-to-cloud messages that are sent from Intel Edison to your IoT hub as the messages are written
to your Azure Table storage. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn how to use the gulp read-message task to read messages persisted in your Azure Table
storage.

What you need

Before starting this process, you must have successfully completed Run the Azure blink sample application on Intel
Edison.

Read new messages from your storage account

In the previous article, you ran a sample application on Edison. The sample application sent messages to your
Azure IoT hub. The messages sent to your IoT hub are stored into your Azure Table storage via the Azure function
app. You need the Azure storage connection string to read messages from your Azure Table storage.
To read messages stored in your Azure Table storage, follow these steps:
1. Get the connection string by running the following commands:

az storage account list -g iot-sample --query [].name

az storage account show-connection-string -g iot-sample -n {storage name}

The first command retrieves the storage name that is used in the second command to get the connection
string. Use iot-sample as the value of {resource group name} if you didn't change the value.
2. Open the configuration file config-edison.json in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-edison.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-edison.json

3. Replace [Azure storage connection string] with the connection string you got in step 1.
4. Save the config-edison.json file.
5. Send messages again and read them from your Azure Table storage by running the following command:

gulp run --read-storage

The logic for reading from Azure Table storage is in the azure-table.js file.
Summary
You've successfully connected Edison to your IoT hub in the cloud and used the blink sample application to send
device-to-cloud messages. You also used the Azure function app to store incoming IoT hub messages to your
Azure Table storage. You can now send cloud-to-device messages from your IoT hub to Edison.

Next steps
Run a sample application to receive cloud-to-device messages
Run a sample application to receive cloud-to-device
messages
1/25/2017 • 2 min to read • Edit on GitHub

In this article, you deploy a sample application on Intel Edison. The sample application monitors incoming
messages from your IoT hub. You also run a gulp task on your computer to send messages to Edison from your IoT
hub. When the sample application receives the messages, it blinks the LED. If you have any problems, look for
solutions on the troubleshooting page.

What you will do

Connect the sample application to your IoT hub.
Deploy and run the sample application.
Send messages from your IoT hub to Edison to blink the LED.

What you will learn

In this article, you will learn:
How to monitor incoming messages from your IoT hub.
How to send cloud-to-device messages from your IoT hub to Edison.

What you need

Intel Edison, set up for use. To learn how to set up Edison, see Configure your device.
An IoT hub that is created in your Azure subscription. To learn how to create your IoT hub, see Create your
Azure IoT Hub.

Connect the sample application to your IoT hub

1. Make sure that you're in the repo folder iot-hub-node-edison-getting-started . Open the sample application
in Visual Studio Code by running the following commands:

cd Lesson4
code .

The file in the app subfolder is the key source file that contains the code to monitor incoming messages
from the IoT hub. The blinkLED function blinks the LED.
2. Initialize the configuration file by running the following commands:

npm install
gulp init

If you completed the steps in Create an Azure function app and storage account on this computer, all the
configurations are inherited, so you can skip the step to the task of deploying and running the sample
application. If you completed the steps in Create an Azure function app and storage account on a different
computer, you need to replace the placeholders in the config-edison.json file. The config-edison.json file
is in the subfolder of your home folder.
Replace [device hostname or IP address] with the device IP address you marked down when you
configured your device.
Replace [IoT device connection string] with the device connection string that you get by running the
az iot device show-connection-string --hub-name {my hub name} --device-id {device id} command.
Replace [IoT hub connection string] with the IoT hub connection string that you get by running the
az iot hub show-connection-string --name {my hub name} command.

Deploy and run the sample application

Deploy and run the sample application on Edison by running the following commands:

gulp deploy && gulp run

The gulp command deploys the sample application to Edison. Then, it runs the application on Edison and a
separate task on your host computer to send 20 blink messages to Edison from your IoT hub.
After the sample application runs, it starts listening to messages from your IoT hub. Meanwhile, the gulp task sends
several "blink" messages from your IoT hub to Edison. For each blink message that Edison receives, the sample
application calls the blinkLED function to blink the LED.
You should see the LED blink every two seconds as the gulp task sends 20 messages from your IoT hub to Edison.
The last one is a "stop" message that stops the application from running.
Summary
You’ve successfully sent messages from your IoT hub to Edison to blink the LED. The next task is optional: change
the on and off behavior of the LED.

Next steps
Change the on and off behavior of the LED
Change the on and off behavior of the LED
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Customize the messages to change the LED’s on and off behavior. If you have any problems, look for solutions on
the troubleshooting page.

What you will learn

Use additional functions to change the LED’s on and off behavior.

What you need

You must have successfully completed Run a sample application on Intel Edison to receive cloud to device
messages.

Add functions to app.js and gulpfile.js

1. Open the sample application in Visual Studio code by running the following commands:

cd Lesson4
code .

2. Open the app.js file, and then add the following functions after blinkLED() function:

function turnOnLED() {
myLed.write(1);
}

function turnOffLED() {
myLed.write(0);
}
3. Add the following conditions before the 'blink' case in the switch-case block of the receiveMessageCallback
function:

case 'on':
turnOnLED();
break;
case 'off':
turnOffLED();
break;

Now you’ve configured the sample application to respond to more instructions through messages. The "on"
instruction turns on the LED, and the "off" instruction turns off the LED.
4. Open the gulpfile.js file, and then add a new function before the function sendMessage :

var buildCustomMessage = function (messageId) {

if ((messageId & 1) && (messageId < MAX_MESSAGE_COUNT)) {
return new Message(JSON.stringify({ command: 'on', messageId: messageId }));
} else if (messageId < MAX_MESSAGE_COUNT) {
return new Message(JSON.stringify({ command: 'off', messageId: messageId }));
} else {
return new Message(JSON.stringify({ command: 'stop', messageId: messageId }));
}
}
5. In the sendMessage function, replace the line var message = buildMessage(sentMessageCount); with the new
line shown in the following snippet:

var message = buildCustomMessage(sentMessageCount);

6. Save all the changes.

Deploy and run the sample application
Deploy and run the sample application on Edison by running the following command:

gulp deploy && gulp run

You should see the LED turn on for two seconds, and then turn off for another two seconds. The last "stop"
message stops the sample application from running.
Congratulations! You’ve successfully customized the messages that are sent to Edison from your IoT hub.
Summary
This optional section demonstrates how to customize messages so that the sample application can control the on
and off behavior of the LED in a different way.
Troubleshooting
1/25/2017 • 3 min to read • Edit on GitHub

Hardware issues
For information about solving common problems on Intel Edison, see the official troubleshooting page.

Node.js package issues

No response during gulp tasks
If you encounter problems running gulp tasks, you can add the --verbose option for debugging. Try to
terminate current gulp tasks by using Ctrl + C , and then run the following command in your console window
to see debug messages. You might see detailed error messages in your console output.

gulp --verbose

NPM issues
Try to update your NPM package with the following command:

npm install -g npm

If the problem still exists, leave your comments at the end of this article or create a GitHub issue in our sample
repository.

Remote debugging
Run the sample application in debug mode

gulp run --debug

Once the debug engine is ready, you should be able to see Debugger listening on port 5858 from the console
output.
Configure VS Code to connect to the remote device
Open the Debug panel from the left side.
Click the green Start Debugging (F5) button. VS Code would open a launch.json file, which you need to
update.
Update the launch.json file with the following content, replace [device hostname or IP address] with the
actual device IP address or hostname.
{
"version": "0.2.0",
"configurations": [
{
"name": "Attach",
"type": "node",
"request": "attach",
"port": 5858,
"address": "[device hostname or IP address]",
"restart": false,
"sourceMaps": false,
"outDir": null,
"localRoot": "${workspaceRoot}",
"remoteRoot": null
}
]
}

Attach to the remote application

Click the green Start Debugging (F5) button and enjoy debugging.
You can read JavaScript in VS Code to learn more about the debugger.
Azure-CLI issues
The Azure command-line interface (Azure CLI) is a preview build. Look for solution in the Preview Install Guide
to seek solutions. Try to upgrade Azure-cli to latest version when commands don’t work as expected.
If you encounter any bugs with the tool, file an issue in the Issues section of the GitHub repo.
For help troubleshooting common problems, check the readme.
If you meet "Could not find a version that satisfies the requirement", please run the following command to
upgrade pip to lastest version.

python -m pip install --upgrade pip

Python installation issues

Legacy installation issues (macOS )
When you're installing pip, a permission error is thrown when older packages that are installed with su
permissions. This situation occurs because a previous installation of Python using brew (macOS) is not
uninstalled completely. Some pip packages from a previous installation were created by root, which causes the
permission error. The solution is to remove those packages installed by root. Use the following steps to
complete this task:
1. Go to: /usr/local/lib/python2.7/site-packages
2. List packages create by root: ls -l | grep root
3. Uninstall packages from step 2: sudo rm -rf {package name}
4. Reinstall Python.
Azure IoT Hub issues
If you've successfully provisioned your Azure IoT hub with azure-cli , and you need a tool to manage the
devices that are connecting to your IoT hub, try the following tools:
Device Explorer
Device Explorer runs on your Windows local machine and connects to your IoT hub in Azure. It communicates
with the following IoT Hub endpoints:
Device identity management to provision and manage devices registered with your IoT hub.
Receive device-to-cloud so you can monitor messages sent from your device to your IoT hub.
Send cloud-to-device so you can send messages to your devices from your IoT hub.
Configure your IoT hub connection string within this tool to use all its capabilities.
IoT hub Explorer
IoT hub Explorer is a sample multiplatform CLI tool to manage device clients. You can use the tool to manage
the devices in the identity registry, monitor device-to-cloud messages, and send cloud-to-device commands.
To install the latest (prerelease) version of the iothub-explorer tool, run the following command in your
command-line environment:

npm install -g iothub-explorer@latest

You can use the following command to get additional help about all the iothub-explorer commands and their
parameters:

iothub-explorer help

Azure portal
A full CLI experience helps you create and manage all your Azure resources. You might also want to use the
Azure portal to help provision, manage, and debug your Azure resources.

Azure storage issues

Microsoft Azure Storage Explorer (preview) is a standalone app from Microsoft that you can use to work with
Azure Storage data on Windows, macOS, and Linux. By using this tool, you can connect to your table and see
the data in it. You can use this tool to troubleshoot your Azure Storage issues.

Next steps
This page only includes the most common problems of Intel Edison kit. You can also leave bottom comments
to report issues for further troubleshooting.
Go back to Get started with Intel Edison (Node.js)
Get started with Intel Edison (C)
1/25/2017 • 3 min to read • Edit on GitHub

In this tutorial, you begin by learning the basics of working with Intel Edison. You then learn how to seamlessly
connect your devices to the cloud by using Azure IoT Hub.
Don't have a kit yet? Start here

Lesson 1: Configure your device

In this lesson, you configure your Intel Edison with an operating system, set up the development environment, and
deploy an application to Edison.
Configure your device
Configure Intel Edison for first-time use by assembling the board, powering it up and installing configuration tool
to your desktop OS to flash Edison's firmware, set its password and connect it to Wi-Fi.
Estimated time to complete: 30 minutes
Go to Configure your device.
Get the tools
Download the tools and software to build and deploy your first application for Intel Edison.
Estimated time to complete: 20 minutes
Go to Get the tools.
Create and deploy the blink application
Clone the sample blink application from GitHub, and use gulp to deploy this application to your Intel Edison board.
This sample application blinks the LED connected to the board every two seconds.
Estimated time to complete: 5 minutes
Go to Create and deploy the blink application.

Lesson 2: Create your IoT hub

In this lesson, you create your free Azure account, provision your Azure IoT hub and create your first device in the
IoT hub.
Complete Lesson 1 before you start this lesson.
Get the Azure tools
Install the Azure command-line interface (Azure CLI).
Estimated time to complete: 10 minutes
Go to Get Azure tools.
Create your IoT hub and register Intel Edison
Create your resource group, provision your first Azure IoT hub, and add your first device to the IoT hub using
Azure CLI.
Estimated time to complete: 10 minutes
Go to Create your IoT hub and register Intel Edison.

Lesson 3: Send device-to-cloud messages

In this lesson, you send messages from Edison to your IoT hub. You also create an Azure function app that gets
incoming messages from your IoT hub and writes them to Azure Table storage.
Complete Lessons 1 and Lesson 2 before you start this lesson.
Create an Azure function app and Azure Storage account
Use an Azure Resource Manager template to create an Azure function app and an Azure Storage account.
Estimated time to complete: 10 minutes
Go to Create an Azure function app and Azure Storage account.
Run a sample application to send device -to -cloud messages
Deploy and run a sample application to your Intel Edison device that sends messages to the IoT hub.
Estimated time to complete: 10 minutes
Go to Run a sample application to send device-to-cloud messages.
Read messages persisted in Azure Storage
Monitor the device-to-cloud messages as they are written to Azure Storage.
Estimated time to complete: 5 minutes
Go to Read messages persisted in Azure Storage.

Lesson 4: Send cloud-to-device messages

This lesson shows how to send messages from your Azure IoT hub to Intel Edison. The messages control the on
and off behavior of the LED that is connected to Edison. A sample application is prepared for you to achieve this
task.
Complete Lessons 1, Lesson 2 and Lesson 3 before you start this lesson.
Run the sample application to receive cloud-to -device messages
The sample application in Lesson 4 runs on Edison and monitors incoming messages from your IoT hub. A new
gulp task sends messages to Edison from your IoT hub to blink the LED.
Estimated time to complete: 10 minutes
Go to Run the sample application to receive cloud-to-device messages.
Optional section: Change the on and off behavior of the LED
Customize the messages to change the LED’s on and off behavior.
Estimated time to complete: 10 minutes
Go to Optional section: Change the on and off behavior of the LED.

Troubleshooting
If you have any problems during the lessons, look for solutions in the Troubleshooting article.
Configure your Intel Edison
1/25/2017 • 4 min to read • Edit on GitHub

What you will do

Configure Intel Edison for first-time use by assembling the board, powering it up and installing configuration tool
to your desktop OS to flash Edison's firmware, set its password and connect it to Wi-Fi. If you have any problems,
look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to assemble Edison board and power it up.
How to flash Edison's firmware, set password and connect Wi-Fi.

What you need

To complete this operation, you need the following parts from your Intel Edison Starter Kit:
Intel® Edison module
Arduino expansion board
Any spacer bars or screws included in the packaging, including two screws to fasten the module to the
expansion board and four sets of screws and plastic spacers.
A Micro B to Type A USB cable
A direct current (DC) power supply. Your power supply should be rated as follows:
7-15V DC
At least 1500mA
The center/inner pin should be the positive pole of the power supply

You also need:

A computer running Windows, Mac, or Linux.
A wireless connection for Edison to connect to.
An Internet connection to download configuration tool.
Assemble your board
This section contains steps to attach your Intel® Edison module to your expansion board.
1. Place the Intel® Edison module within the white outline on your expansion board, lining up the holes on the
module with the screws on the expansion board.
2. Press down on the module just below the words What will you make? until you feel a snap.

3. Use the two hex nuts (included in the package) to secure the module to the expansion board.
4. Insert a screw in one of the four corner holes on the expansion board. Twist and tighten one of the white
plastic spacers onto the screw.

5. Repeat for the other three corner spacers.

Now your board is assembled.

Power up Edison
1. Plug in the power supply.

2. A green LED(labeled DS1 on the Arduino* expansion board) should light up and stay lit.
3. Wait one minute for the board to finish booting up.

NOTE
If you do not have a DC power supply, you can still power the board through a USB port. See
Connect Edison to your computer section for details. Powering your board in this fashion may result in
unpredictable behavior from your board, especially when using Wi-Fi or driving motors.

Connect Edison to your computer

1. Toggle down the microswitch towards the two micro USB ports, so that Edison is in device mode. For
differences between device mode and host mode, please reference here.
2. Plug the micro USB cable into the top micro USB port.
3. Plug the other end of USB cable into your computer.

4. You will know that your board is fully initialized when your computer mounts a new drive (much like
inserting a SD card into your computer).
Download and run the configuration tool
Get the latest configuration tool from this link listed under the Installers heading. Execute the tool and follow its
on-screen instructions, clicking Next where needed
Flash firmware
1. On the Set up options page, click Flash Firmware .
2. Select the image to flash onto your board by doing one of the following:
To download and flash your board with the latest firmware image available from Intel, select
Download the latest image version xxxx .
To flash your board with an image you already have saved on your computer, select
Select the local image . Browse to and select the image you want to flash to your board.
3. The setup tool will attempt to flash your board. The entire flashing process may take up to 10 minutes.
Set password
1. On the Set up options page, click Enable Security .
2. You can set a custom name for your Intel® Edison board. This is optional.
3. Type a password for your board, then click Set password .
4. Mark down the password, which is used later.
Connect Wi-Fi
1. On the Set up options page, click Connect Wi-Fi . Wait up to one minute as your computer scans for available
Wi-Fi networks.
2. From the Detected Networks drop-down list, select your network.
3. From the Security drop-down list, select the network's security type.
4. Provide your login and password information, then click Configure Wi-Fi .
5. Mark down the IP address, which is used later.

NOTE
Make sure that Edison is connected to the same network as your computer. Your computer connects to your Edison by
using the IP address.

Congratulations! You've successfully configured Edison.

Summary
In this article, you’ve learned how to assemble the Edison board, flash its firmware, setup password and connect it
to Wi-Fi by using configuration tool. Note that the LED doesn't yet light up. The next task is to install the necessary
tools and software in preparation for running a sample application on Edison.

Next steps
Get the tools
Get the tools (Windows 7 or later)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for Intel Edison. If you have any
problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is C, Node.js tools are used in the lessons to build and deploy sample
applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum version requirement of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Windows.

Install Git and Node.js

Click the links below to download and install Git and Node.js LTS for Windows.
Get Git for Windows
Get Node.js LTS for Windows

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Edison.
Start a command prompt as an administrator. Install gulp by running the following command:

npm install -g gulp

If you experience issues installing Node.js and these additional Node.js development tools on your computer, see
the troubleshooting guide for solutions to common problems.
Install Visual Studio Code
Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Edison.

Next steps
Create and deploy the blink application
Get the tools (Ubuntu 16.04)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Intel Edison. If you have
any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is C, Node.js tools are used in the lessons to build and deploy sample
applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Ubuntu 16.04 or later.

Install Git, Node.js, and NPM

Use the keyboard shortcut Ctrl + Alt + T to open a terminal and run the following commands:

sudo apt-get update

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install git

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to Edison.
Install gulp by running the following command in the terminal:

sudo npm install -g gulp

If you experience issues installing Node.js and these additional development tools on Ubuntu, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Edison.

Next steps
Create and deploy the blink sample application
Get the tools (macOS 10.10)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Intel Edison. If you have
any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is C, Node.js tools are used in the lessons to build and deploy sample
applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A Mac that is running macOS Yosemite (10.10) or later.

Install Git and Node.js

To install Git and Node.js, use the Homebrew package management utility by following these steps:
1. Install Homebrew. If you've already installed Homebrew, go to step 2.
a. Press Cmd + Space and enter Terminal to open a terminal.
b. Run the following command:

/usr/bin/ruby -e "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Install Git and Node.js by running the following command:

brew install node git

Install additional Node.js development tools
Use gulp.js to automate the deployment of the sample application to your Edison.
Install gulp by running the following command in the terminal:

sudo npm install -g gulp

If you experience issues installing Node.js and these additional development tools on macOS, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on Edison.

Next steps
Create and deploy the blink application
Create and deploy the blink application
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Clone the sample C application from GitHub, and use the gulp tool to deploy the sample application to Intel
Edison. The sample application blinks the LED connected to the board every two seconds. If you have any
problems, look for solutions on the troubleshooting page.

What you will learn

How to deploy and run the sample application on Edison.

What you need

You must have successfully completed the following operations:
Configure your device
Get the tools

Open the sample application

To open the sample application, follow these steps:
1. Clone the sample repository from GitHub by running the following command:

git clone https://github.com/Azure-Samples/iot-hub-c-edison-getting-started.git

2. Open the sample application in Visual Studio Code by running the following commands:

cd iot-hub-c-edison-getting-started
cd Lesson1
code .
The file in the app subfolder is the key source file that contains the code to control the LED.
Install application dependencies
Install the libraries and other modules you need for the sample application by running the following command:

npm install

Configure the device connection

To configure the device connection, follow these steps:
1. Generate the device configuration file by running the following command:

gulp init

The configuration file config-edison.json contains the user credentials you use to log in to Edison. To avoid
the leak of user credentials, the configuration file is generated in the subfolder .iot-hub-getting-started of
the home folder on your computer.
2. Open the device configuration file in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-edison.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-edison.json

3. Replace the placeholder [device hostname or IP address] and [device password] with the IP address and
password that you marked down in previous lesson.
Congratulations! You've successfully created the first sample application for Edison.

Deploy and run the sample application

Install the Azure IoT Hub SDK on Edison
Install the Azure IoT Hub SDK on Edison by running the following command:

gulp install-tools

This task might take a long time to complete, depending on your network connection. It needs to be run only once
for one Edison.
Deploy and run the sample app
Deploy and run the sample application by running the following command:

gulp deploy && gulp run

Verify the app works

The sample application terminates automatically after the LED blinks for 20 times. If you don’t see the LED
blinking, see the troubleshooting guide for solutions to common problems.
Summary
You've installed the required tools to work with Edison and deployed a sample application to Edison to blink the
LED. You can now create, deploy, and run another sample application that connects Edison to Azure IoT Hub to
send and receive messages.

Next steps
Get the Azure tools
Get Azure tools (Windows 7 and later)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Install Python and the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on
the troubleshooting page.

What you will learn

In this article, you will learn:
How to install Python.
How to install the Azure CLI.

What you need

A Windows computer with an Internet connection.
An active Azure subscription. If you don't have an Azure account, create a free Azure trial account in just a few
minutes.

Install Python
Install Python on your Windows computer. You can install Python 2.7, 3.4 or 3.5. This tutorial is based on Python
2.7. If you've already installed Python, go to the next section and install the Azure CLI.
You also need to add the path of the folders where python.exe and pip.exe are installed to the system PATH
environment variable. By default, python.exe is installed in C:\Python27 and pip.exe is installed in
C:\Python27\Scripts .

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the Azure CLI, follow these steps:
1. Open a Command Prompt window as an administrator.
2. Run the following commands:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

3. Verify the installation by running the following command:

az iot -h

You see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Intel Edison
Get Azure tools (Ubuntu 16.04)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install the Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

An Ubuntu computer with an Internet connection.
An active Azure subscription. If you don't have an account, you can create a free trial account in just a few
minutes.

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure, enabling you to work directly from
your command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

sudo apt-get update

sudo apt-get install -y libssl-dev libffi-dev
sudo apt-get install -y python-dev
sudo apt-get install -y build-essential
sudo apt-get install -y python-pip
sudo pip install --upgrade azure-cli
sudo pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity using the Azure
CLI.

Next steps
Create your IoT hub and register Intel Edison
Get Azure tools (macOS 10.10)
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page.

What you will learn

In this article, you will learn:
How to install Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

A Mac with an Internet connection.
An active Azure subscription. If you don't have an Azure account, you can create a free Azure trial account in just
a few minutes.

Install Python
Although macOS comes with Python 2.7 out of the box, we recommend that you install Python through
Homebrew. See Installing Python on macOS.
Install Python and pip by running the following command:

brew install python

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register Intel Edison
Create your IoT hub and register Intel Edison
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Create a resource group.
Create your Azure IoT hub in the resource group.
Add Intel Edison to the Azure IoT hub by using the Azure command-line interface (Azure CLI).
When you use the Azure CLI to add Edison to your IoT hub, the service generates a key for Edison to authenticate
with the service. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to use the Azure CLI to create an IoT hub.
How to create a device identity for Edison in your IoT hub.

What you need

An Azure account. If you don't have an Azure account, create a free Azure trial account in just a few minutes.
You should have the Azure CLI installed.

Create your IoT hub

Azure IoT Hub helps you connect, monitor, and manage millions of IoT assets. To create your IoT hub, follow these
steps:
1. Sign in to your Azure account by running the following command:

az login

All your available subscriptions are listed after a successful sign-in.

2. Set the default subscription that you want to use by running the following command:

az account set --subscription {subscription id or name}

subscription ID or name can be found in the output of the az login or the az account list command.
3. Register the provider by running the following command. Resource providers are services that provide
resources for your application. You must register the provider before you can deploy the Azure resource
that the provider offers.

az provider register -n "Microsoft.Devices"

4. Create a resource group named iot-sample in the West US region by running the following command:
az group create --name iot-sample --location westus

westus is the location you create your resource group. If you want to use another location, you can run
az account list-locations -o table to see all the locations Azure supports.

5. Create an IoT hub in the iot-sample resource group by running the following command:

az iot hub create --name {my hub name} --resource-group iot-sample

By default, the tool creates an IoT Hub in the Free pricing tier. For more infomation, see Azure IoT Hub pricing.

NOTE
The name of your IoT hub must be globally unique. You can create only one F1 edition of Azure IoT Hub under your Azure
subscription.

Register Edison in your IoT hub

Each device that sends messages to your IoT hub and receives messages from your IoT hub must be registered
with a unique ID.
Register Edison in your IoT hub by running following command:

az iot device create --device-id myinteledison --hub-name {my hub name}

Summary
You've created an IoT hub and registered Edison with a device identity in your IoT hub. You're ready to learn how
to send messages from Edison to your IoT hub.

Next steps
Create an Azure function app and an Azure Storage account to process and store IoT hub messages.
Create an Azure function app and Azure storage
account
1/25/2017 • 2 min to read • Edit on GitHub

Azure Functions is a solution for easily running functions (small pieces of code) in the cloud. An Azure function app
hosts the execution of your functions in Azure.

What will you do

Use an Azure Resource Manager template to create an Azure function app and an Azure storage account. The
Azure function app listens to Azure IoT hub events, processes incoming messages, and writes them to Azure Table
storage. The storage account is used for reading the persisted copies of messages from Azure table. If you have
any problems, look for solutions on the troubleshooting page.

What will you learn

In this article, you will learn:
How to use Azure Resource Manager to deploy Azure resources.
How to use an Azure function app to process IoT hub messages and write them to a table in Azure Table
storage.

What do you need

You must have successfully completed:
Get started with your Intel Edison
Create your Azure IoT hub

Open the sample app

Open the sample project in Visual Studio Code by running the following commands:

cd Lesson3
code .
The file in the app subfolder is the key source file. This source file contains the code to send a message 20
times to your IoT hub and blink the LED for each message it sends.
The arm-template.json file is the Azure Resource Manager template that contains an Azure function app and an
Azure storage account.
The arm-template-param.json file is the configuration file used by the Azure Resource Manager template.
The ReceiveDeviceMessages subfolder contains the Node.js code for the Azure function.

Configure Azure Resource Manager templates and create resources in

Azure
Update the arm-template-param.json file in Visual Studio Code.

Replace [your IoT Hub name] with {my hub name} that you specified when you created your IoT hub and
registered Intel Edison.
Replace [prefix string for new resources] with any prefix you want. The prefix ensures that the resource
name is globally unique to avoid conflict. Do not use a dash or number initial in the prefix.
After you update the arm-template-param.json file, deploy the resources to Azure by running the following
command:

az group deployment create --template-file arm-template.json --parameters @arm-template-param.json -g iot-

sample

It takes about five minutes to create these resources. While the resource creation is in progress, you can move on
to the next article.
Summary
You've created your Azure function app to process IoT hub messages and an Azure storage account to store these
messages. You can now deploy and run the sample to send device-to-cloud messages on Edison.

Next steps
Run a sample application to send device-to-cloud messages on Intel Edison.
Run a sample application to send device-to-cloud
messages
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

This article will show you how to deploy and run a sample application on Intel Edison that sends messages to your
IoT hub. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

You will learn how to use the gulp tool to deploy and run the sample C application on Edison.

What you need

Before you start this task, you must have successfully completed Create an Azure function app and a storage
account to process and store IoT hub messages.

Get your IoT hub and device connection strings

The device connection string is used to connect Edison to your IoT hub. The IoT hub connection string is used to
connect your IoT hub to the device identity that represents Edison in the IoT hub.
List all your IoT hubs in your resource group by running the following Azure CLI command:

az iot hub list -g iot-sample --query [].name

Use iot-sample as the value of {resource group name} if you didn't change the value.
Get the IoT hub connection string by running the following Azure CLI command:

az iot hub show-connection-string --name {my hub name}

{my hub name} is the name that you specified when you created your IoT hub and registered Edison.
Get the device connection string by running the following command:

az iot device show-connection-string --hub-name {my hub name} --device-id myinteledison

Use myinteledison as the value of {device id} if you didn't change the value.

Configure the device connection

1. Initialize the configuration file by running the following commands:

npm install
gulp init
NOTE
Run gulp install-tools as well, if you haven't done it in Lesson 1.

2. Open the device configuration file config-edison.json in Visual Studio Code by running the following
command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-edison.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-edison.json

3. Make the following replacements in the config-edison.json file:

Replace [device hostname or IP address] with the device IP address you marked down when you
configured your device.
Replace [IoT device connection string] with the device connection string you obtained.
Replace [IoT hub connection string] with the iot hub connection string you obtained.

NOTE
You don't need azure_storage_connection_string in this article. Keep it as is.

Deploy and run the sample application

Deploy and run the sample application on Edison by running the following command:
gulp deploy && gulp run

Verify that the sample application works

You should see the LED that is connected to Edison blinking every two seconds. Every time the LED blinks, the
sample application sends a message to your IoT hub and verifies that the message has been successfully sent to
your IoT hub. In addition, each message received by the IoT hub is printed in the console window. The sample
application terminates automatically after sending 20 messages.

Summary
You've deployed and run the new blink sample application on Edison to send device-to-cloud messages to your IoT
hub. You now monitor your messages as they are written to the storage account.

Next steps
Read messages persisted in Azure Storage
Read messages persisted in Azure Storage
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Monitor the device-to-cloud messages that are sent from Intel Edison to your IoT hub as the messages are written
to your Azure Table storage. If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn how to use the gulp read-message task to read messages persisted in your Azure Table
storage.

What you need

Before starting this process, you must have successfully completed Run the Azure blink sample application on Intel
Edison.

Read new messages from your storage account

In the previous article, you ran a sample application on Edison. The sample application sent messages to your
Azure IoT hub. The messages sent to your IoT hub are stored into your Azure Table storage via the Azure function
app. You need the Azure storage connection string to read messages from your Azure Table storage.
To read messages stored in your Azure Table storage, follow these steps:
1. Get the connection string by running the following commands:

az storage account list -g iot-sample --query [].name

az storage account show-connection-string -g iot-sample -n {storage name}

The first command retrieves the storage name that is used in the second command to get the connection
string. Use iot-sample as the value of {resource group name} if you didn't change the value.
2. Open the configuration file config-edison.json in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-edison.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-edison.json

3. Replace [Azure storage connection string] with the connection string you got in step 1.
4. Save the config-edison.json file.
5. Send messages again and read them from your Azure Table storage by running the following command:

gulp run --read-storage

The logic for reading from Azure Table storage is in the azure-table.js file.
Summary
You've successfully connected Edison to your IoT hub in the cloud and used the blink sample application to send
device-to-cloud messages. You also used the Azure function app to store incoming IoT hub messages to your
Azure Table storage. You can now send cloud-to-device messages from your IoT hub to Edison.

Next steps
Run a sample application to receive cloud-to-device messages
Run a sample application to receive cloud-to-device
messages
1/25/2017 • 2 min to read • Edit on GitHub

In this article, you deploy a sample application on Intel Edison. The sample application monitors incoming
messages from your IoT hub. You also run a gulp task on your computer to send messages to Edison from your IoT
hub. When the sample application receives the messages, it blinks the LED. If you have any problems, look for
solutions on the troubleshooting page.

What you will do

Connect the sample application to your IoT hub.
Deploy and run the sample application.
Send messages from your IoT hub to Edison to blink the LED.

What you will learn

In this article, you will learn:
How to monitor incoming messages from your IoT hub.
How to send cloud-to-device messages from your IoT hub to Edison.

What you need

Intel Edison, set up for use. To learn how to set up Edison, see Configure your device.
An IoT hub that is created in your Azure subscription. To learn how to create your IoT hub, see Create your
Azure IoT Hub.

Connect the sample application to your IoT hub

1. Make sure that you're in the repo folder iot-hub-c-edison-getting-started . Open the sample application in
Visual Studio Code by running the following commands:

cd Lesson4
code .

The file in the app subfolder is the key source file that contains the code to monitor incoming messages
from the IoT hub. The blinkLED function blinks the LED.
2. Initialize the configuration file by running the following commands:

npm install
gulp init

If you completed the steps in Create an Azure function app and storage account on this computer, all the
configurations are inherited, so you can skip the step to the task of deploying and running the sample
application. If you completed the steps in Create an Azure function app and storage account on a different
computer, you need to replace the placeholders in the config-edison.json file. The config-edison.json file
is in the subfolder of your home folder.
Replace [device hostname or IP address] with the device IP address you marked down when you
configured your device.
Replace [IoT device connection string] with the device connection string that you get by running the
az iot device show-connection-string --hub-name {my hub name} --device-id {device id} command.
Replace [IoT hub connection string] with the IoT hub connection string that you get by running the
az iot hub show-connection-string --name {my hub name} command.

NOTE
Run gulp install-tools as well, if you haven't done it in Lesson 1.

Deploy and run the sample application

Deploy and run the sample application on Edison by running the following commands:

gulp deploy && gulp run

The gulp command deploys the sample application to Edison. Then, it runs the application on Edison and a
separate task on your host computer to send 20 blink messages to Edison from your IoT hub.
After the sample application runs, it starts listening to messages from your IoT hub. Meanwhile, the gulp task sends
several "blink" messages from your IoT hub to Edison. For each blink message that Edison receives, the sample
application calls the blinkLED function to blink the LED.
You should see the LED blink every two seconds as the gulp task sends 20 messages from your IoT hub to Edison.
The last one is a "stop" message that stops the application from running.
Summary
You’ve successfully sent messages from your IoT hub to Edison to blink the LED. The next task is optional: change
the on and off behavior of the LED.

Next steps
Change the on and off behavior of the LED
Change the on and off behavior of the LED
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Customize the messages to change the LED’s on and off behavior. If you have any problems, look for solutions on
the troubleshooting page.

What you will learn

Use additional functions to change the LED’s on and off behavior.

What you need

You must have successfully completed Run a sample application on Intel Edison to receive cloud to device
messages.

Add functions to main.c and gulpfile.js

1. Open the sample application in Visual Studio code by running the following commands:

cd Lesson4
code .

2. Open the main.c file, and then add the following functions after blinkLED() function:

static void turnOnLED()

{
mraa_gpio_write(context, 1);
}

static void turnOffLED()

{
mraa_gpio_write(context, 0);
}
3. Add the following conditions before the else if block of the receiveMessageCallback function:

else if (0 == strcmp((const char*)value, "\"on\""))

{
turnOnLED();
}
else if (0 == strcmp((const char*)value, "\"off\""))
{
turnOffLED();
}

Now you’ve configured the sample application to respond to more instructions through messages. The "on"
instruction turns on the LED, and the "off" instruction turns off the LED.
4. Open the gulpfile.js file, and then add a new function before the function sendMessage :

var buildCustomMessage = function (messageId) {

if ((messageId & 1) && (messageId < MAX_MESSAGE_COUNT)) {
return new Message(JSON.stringify({ command: 'on', messageId: messageId }));
} else if (messageId < MAX_MESSAGE_COUNT) {
return new Message(JSON.stringify({ command: 'off', messageId: messageId }));
} else {
return new Message(JSON.stringify({ command: 'stop', messageId: messageId }));
}
}
5. In the sendMessage function, replace the line var message = buildMessage(sentMessageCount); with the new
line shown in the following snippet:

var message = buildCustomMessage(sentMessageCount);

6. Save all the changes.

Deploy and run the sample application
Deploy and run the sample application on Edison by running the following command:

gulp deploy && gulp run

You should see the LED turn on for two seconds, and then turn off for another two seconds. The last "stop"
message stops the sample application from running.
Congratulations! You’ve successfully customized the messages that are sent to Edison from your IoT hub.
Summary
This optional section demonstrates how to customize messages so that the sample application can control the on
and off behavior of the LED in a different way.
Troubleshooting
1/25/2017 • 3 min to read • Edit on GitHub

Hardware issues
For information about solving common problems on Intel Edison, see the official troubleshooting page.

Node.js package issues

No response during gulp tasks
If you encounter problems running gulp tasks, you can add the --verbose option for debugging. Try to
terminate current gulp tasks by using Ctrl + C , and then run the following command in your console window
to see debug messages. You might see detailed error messages in your console output.

gulp --verbose

NPM issues
Try to update your NPM package with the following command:

npm install -g npm

If the problem still exists, leave your comments at the end of this article or create a GitHub issue in our sample
repository.

Azure-CLI issues
The Azure command-line interface (Azure CLI) is a preview build. Look for solution in the Preview Install Guide
to seek solutions. Try to upgrade Azure-cli to latest version when commands don’t work as expected.
If you encounter any bugs with the tool, file an issue in the Issues section of the GitHub repo.
For help troubleshooting common problems, check the readme.
If you meet "Could not find a version that satisfies the requirement", please run the following command to
upgrade pip to lastest version.

python -m pip install --upgrade pip

Python installation issues

Legacy installation issues (macOS )
When you're installing pip, a permission error is thrown when older packages that are installed with su
permissions. This situation occurs because a previous installation of Python using brew (macOS) is not
uninstalled completely. Some pip packages from a previous installation were created by root, which causes the
permission error. The solution is to remove those packages installed by root. Use the following steps to
complete this task:
1. Go to: /usr/local/lib/python2.7/site-packages
2. List packages create by root: ls -l | grep root
3. Uninstall packages from step 2: sudo rm -rf {package name}
4. Reinstall Python.

Azure IoT Hub issues

If you've successfully provisioned your Azure IoT hub with azure-cli , and you need a tool to manage the
devices that are connecting to your IoT hub, try the following tools:
Device Explorer
Device Explorer runs on your Windows local machine and connects to your IoT hub in Azure. It communicates
with the following IoT Hub endpoints:
Device identity management to provision and manage devices registered with your IoT hub.
Receive device-to-cloud so you can monitor messages sent from your device to your IoT hub.
Send cloud-to-device so you can send messages to your devices from your IoT hub.
Configure your IoT hub connection string within this tool to use all its capabilities.
IoT hub Explorer
IoT hub Explorer is a sample multiplatform CLI tool to manage device clients. You can use the tool to manage
the devices in the identity registry, monitor device-to-cloud messages, and send cloud-to-device commands.
To install the latest (prerelease) version of the iothub-explorer tool, run the following command in your
command-line environment:

npm install -g iothub-explorer@latest

You can use the following command to get additional help about all the iothub-explorer commands and their
parameters:

iothub-explorer help

Azure portal
A full CLI experience helps you create and manage all your Azure resources. You might also want to use the
Azure portal to help provision, manage, and debug your Azure resources.

Azure storage issues

Microsoft Azure Storage Explorer (preview) is a standalone app from Microsoft that you can use to work with
Azure Storage data on Windows, macOS, and Linux. By using this tool, you can connect to your table and see
the data in it. You can use this tool to troubleshoot your Azure Storage issues.

Next steps
This page only includes the most common problems of Intel Edison kit. You can also leave bottom comments
to report issues for further troubleshooting.
Go back to Get started with Intel Edison (C)
Get started with your Arduino board: Adafruit Feather
M0 WiFi
1/24/2017 • 3 min to read • Edit on GitHub

In this tutorial, you begin by learning the basics of working with your Arduino board. You then learn how to
seamlessly connect your devices to the cloud by using Azure IoT Hub.

Lesson 1: Configure your device

In this lesson, you configure your Arduino board with an operating system, set up the development environment,
and deploy an application to your Arduino board.
Configure your device
Configure your Arduino board for first-time use by assembling the board, powering it up.
Estimated time to complete: 5 minutes
Go to Configure your device.
Get the tools
Download the tools and software to build and deploy your first application for your Arduino board.
Estimated time to complete: 20 minutes
Go to Get the tools
Create and deploy the blink application
Clone the sample Arduino blink application from GitHub, and use gulp to deploy this application to your Arduino
board. This sample application blinks the GPIO #13 on-board LED every two seconds.
Estimated time to complete: 5 minutes
Go to Create and deploy the blink application.

Lesson 2: Create your IoT hub

In this lesson, you create your free Azure account, provision your Azure IoT hub and create your first device in the
IoT hub.
Complete Lesson 1 before you start this lesson.
Get the Azure tools
Install the Azure command-line interface (Azure CLI).
Estimated time to complete: 10 minutes
Go to Get Azure tools.
Create your IoT hub and register your Arduino board
Create your resource group, provision your first Azure IoT hub, and add your first device to the IoT hub using Azure
CLI.
Estimated time to complete: 10 minutes
Go to Create your IoT hub and register your Arduino board.

Lesson 3: Send device-to-cloud messages

In this lesson, you send messages from your Arduino board to your IoT hub. You also create an Azure function app
that gets incoming messages from your IoT hub and writes them to Azure Table storage.
Complete Lessons 1 and Lesson 2 before you start this lesson.
Create an Azure function app and Azure Storage account
Use an Azure Resource Manager template to create an Azure function app and an Azure Storage account.
Estimated time to complete: 10 minutes
Go to Create an Azure function app and Azure Storage account.
Run a sample application to send device -to -cloud messages
Deploy and run a sample application to your Arduino board that sends messages to the IoT hub.
Estimated time to complete: 10 minutes
Go to Run a sample application to send device-to-cloud messages.
Read messages persisted in Azure Storage
Monitor the device-to-cloud messages as they are written to Azure Storage.
Estimated time to complete: 5 minutes
Go to Read messages persisted in Azure Storage.

Lesson 4: Send cloud-to-device messages

This lesson shows how to send messages from your Azure IoT hub to your Arduino board. The messages control
the on and off behavior of the GPIO #13 on-board LED. A sample application is prepared for you to achieve this
task.
Complete Lessons 1, Lesson 2 and Lesson 3 before you start this lesson.
Run the sample application to receive cloud-to -device messages
The sample application in Lesson 4 runs on your Arduino board and monitors incoming messages from your IoT
hub. A new gulp task sends messages to your Arduino board from your IoT hub to blink the LED.
Estimated time to complete: 10 minutes
Go to Run the sample application to receive cloud-to-device messages.
Optional section: Change the on and off behavior of the LED
Customize the messages to change the LED’s on and off behavior.
Estimated time to complete: 10 minutes
Go to Optional section: Change the on and off behavior of the LED.

Troubleshooting
If you have any problems during the lessons, look for solutions in the Troubleshooting article.
Configure your device
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Configure your Adafruit Feather M0 WiFi Arduino board for first-time use by assembling the board, powering it up.
If you have any problems, look for solutions on the troubleshooting page.

What you need

To complete this operation, you need the following parts for your Adafruit Feather M0 WiFi Starter Kit:
The Adafruit Feather M0 WiFi board
A Micro B to Type A USB cable

You also need:

A computer running Windows, Mac, or Linux.
A wireless connection for your Arduino board to connect to.
An Internet connection to download configuration tool.

What you will learn

In this article, you will learn:
How to assemble your Arduino board and power it up for the following lessons.
How to add serial port permissions on Ubuntu.

Connect your Arduino board to your computer

1. Plug the micro USB cable into the top micro USB port.
2. Plug the other end of USB cable into your computer.
Add serial port permissions on Ubuntu
You can skip this section if you use Windows or macOS. For Ubuntu, you need the following steps to make sure the
normal linux user has the permissions to operate on the USB port of your Arduino board.
1. Now as normal user from terminal:

ls -l /dev/ttyUSB*
# Or
ls -l /dev/ttyACM*
You will get something like:

crw-rw---- 1 root uucp 188, 0 5 apr 23.01 ttyUSB0

# Or
crw-rw---- 1 root dialout 188, 0 5 apr 23.01 ttyACM0

The "0" might be a different number, or multiple entries might be returned. In the first case the data we need
is uucp , in the second is dialout , which is the group owner of the file.
2. Add user to the to the group:

sudo usermod -a -G group-name username

Where group-name is the data found in the first step, and username is your linux user name.
3. You will need to log out and in again for this change to take effect and complete the setup.

Summary
In this article, you’ve learned how to configure your Arduino board. The next task is to install the necessary tools
and software in preparation for running a sample application on your Arduino board.

Next steps
Get the tools
Get the tools (Windows 7 or later)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Adafruit Feather M0
WiFi Arduino board.
If you have any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is Arduino, Node.js tools are used in the lessons to build and deploy
sample applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum version requirement of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Windows.

Install Git and Node.js

Click the links below to download and install Git and Node.js LTS for Windows.
Get Git for Windows
Get Node.js LTS for Windows

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to your Arduino board.
Start a command prompt as an administrator. Install gulp , device-discovery-cli by running the following
command in the terminal:

npm install -g gulp device-discovery-cli

If you experience issues installing Node.js and these additional Node.js development tools on your computer, see
the troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on your Arduino board.

Next steps
Create and deploy the blink sample application
Get the tools (Ubuntu 16.04)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Adafruit Feather M0
WiFi Arduino board.
If you have any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is Arduino, Node.js tools are used in the lessons to build and deploy
sample applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A computer that is running Ubuntu 16.04 or later.

Install Git, Node.js, and NPM

Use the keyboard shortcut Ctrl + Alt + T to open a terminal and run the following commands:

sudo apt-get update

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install git

Install additional Node.js development tools

Use gulp.js to automate the deployment of the sample application to your Arduino board.
Install gulp , device-discovery-cli by running the following command in the terminal:
sudo npm install -g gulp device-discovery-cli

If you experience issues installing Node.js and these additional development tools on Ubuntu, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on your Arduino board.

Next steps
Create and deploy the blink sample application
Get the tools (macOS 10.10)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Download the development tools and the software for the first sample application for your Adafruit Feather M0
WiFi Arduino board.
If you have any problems, look for solutions on the troubleshooting page.

NOTE
Although the programming language of the main logic is Arduino, Node.js tools are used in the lessons to build and deploy
sample applications.

What you will learn

In this article, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this article is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install additional Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.

What you need

To complete this operation, you will need:
An Internet connection to download the development tools and the software.
A Mac that is running macOS Yosemite (10.10) or later.

Install Git and Node.js

To install Git and Node.js, use the Homebrew package management utility by following these steps:
1. Install Homebrew. If you've already installed Homebrew, go to step 2.
a. Press Cmd + Space and enter Terminal to open a terminal.
b. Run the following command:

/usr/bin/ruby -e "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Install Git and Node.js by running the following command:

brew install node git

Install additional Node.js development tools
Use gulp.js to automate the deployment of the sample application to your Arduino board.
Install gulp , device-discovery-cli by running the following command in the terminal:

sudo npm install -g gulp device-discovery-cli

If you experience issues installing Node.js and these additional development tools on macOS, see the
troubleshooting guide for solutions to common problems.

Install Visual Studio Code

Download and install Visual Studio Code. Visual Studio Code is a lightweight but powerful source code editor for
Windows, Linux, and macOS. You use this editor later in the tutorial to edit the sample code.

Summary
You've installed the required development tools and software for the first sample application. The next task is to
create, deploy, and run the sample application on your Arduino board.

Next steps
Create and deploy the blink application
Create and deploy the blink application
1/24/2017 • 2 min to read • Edit on GitHub

What you will do

Clone the sample Arduino application from GitHub, and use the gulp tool to deploy the sample application to your
Adafruit Feather M0 WiFi Arduino board. The sample application blinks the GPIO #13 on-barod LED every two
seconds.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

How to deploy and run the sample application on your Arduino board.

What you need

You must have successfully completed the following operations:
Configure your device
Get the tools

Open the sample application

To open the sample application, follow these steps:
1. Clone the sample repository from GitHub by running the following command:

git clone https://github.com/Azure-Samples/iot-hub-c-feather-m0-getting-started.git

2. Open the sample application in Visual Studio Code by running the following commands:

cd iot-hub-c-feather-m0-getting-started
cd Lesson1
code .
The app.ino file in the app subfolder is the key source file that contains the code to control the LED.
Install application dependencies
Install the libraries and other modules you need for the sample application by running the following command:

npm install

Configure the device connection

To configure the device connection, follow these steps:
1. Obtain the serial port of the device with the device discovery cli:

devdisco list --usb

You should see an output that is similar to the following and find the usb COM port for your Arduino board:

2. Open the file config.json in the lesson folder and add the value of the found COM port number:
{
"device_port" : "COM1"
}

NOTE
For the COM port, on Windows platform, it has the format of COM1, COM2, ... . On macOS or Ubuntu, it starts
with /dev/ .

Deploy and run the sample application

Install the required tools for your Arduino board
Install the Azure IoT Hub SDK for your Arduino board by running the following command:

gulp install-tools

This task might take a long time to complete, depending on your network connection.

NOTE
Please exit the running Arduino IDE instance when running gulp tasks: install-tools , run .

Deploy and run the sample app

Deploy and run the sample application by running the following command:
gulp run

# You can monitor the serial port by running listen task:

gulp listen

# Or you can combine above two gulp tasks into one:

gulp run --listen

Verify the app works

If you don’t see the LED blinking, see the troubleshooting guide for solutions to common problems.

Summary
You've installed the required tools to work with your Arduino board and deployed a sample application to your
Arduino board to blink the LED. You can now create, deploy, and run another sample application that connects
your Arduino board to Azure IoT Hub to send and receive messages.

Next steps
Get the Azure tools
Get Azure tools (Windows 7 and later)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install Python and the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on
the troubleshooting page for your Adafruit Feather M0 WiFi Arduino board.

What you will learn

In this article, you will learn:
How to install Python.
How to install the Azure CLI.

What you need

A Windows computer with an Internet connection.
An active Azure subscription. If you don't have an Azure account, create a free Azure trial account in just a few
minutes.

Install Python
Install Python on your Windows computer. You can install Python 2.7, 3.4 or 3.5. This tutorial is based on Python
2.7. If you've already installed Python, go to the next section and install the Azure CLI.
You also need to add the path of the folders where python.exe and pip.exe are installed to the system PATH
environment variable. By default, python.exe is installed in C:\Python27 and pip.exe is installed in
C:\Python27\Scripts .

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the Azure CLI, follow these steps:
1. Open a Command Prompt window as an administrator.
2. Run the following commands:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

3. Verify the installation by running the following command:

az iot -h

You see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register your Arduino board
Get Azure tools (Ubuntu 16.04)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page for your Adafruit Feather M0 WiFi Arduino board.

What you will learn

In this article, you will learn:
How to install the Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

An Ubuntu computer with an Internet connection.
An active Azure subscription. If you don't have an account, you can create a free trial account in just a few
minutes.

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure, enabling you to work directly from
your command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

sudo apt-get update

sudo apt-get install -y libssl-dev libffi-dev
sudo apt-get install -y python-dev
sudo apt-get install -y build-essential
sudo apt-get install -y python-pip
sudo pip install --upgrade azure-cli
sudo pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity using the Azure
CLI.

Next steps
Create your IoT hub and register your Arduino board
Get Azure tools (macOS 10.10)
1/24/2017 • 1 min to read • Edit on GitHub

What you will do

Install the Azure command-line interface (Azure CLI). If you have any problems, look for solutions on the
troubleshooting page for your Adafruit Feather M0 WiFi Arduino board.

What you will learn

In this article, you will learn:
How to install Azure CLI.
How to add an IoT subgroup of the Azure CLI.

What you need

A Mac with an Internet connection.
An active Azure subscription. If you don't have an Azure account, you can create a free Azure trial account in just
a few minutes.

Install Python
Although macOS comes with Python 2.7 out of the box, we recommend that you install Python through
Homebrew. See Installing Python on macOS.
Install Python and pip by running the following command:

brew install python

Install the Azure CLI

The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from your
command line to provision and manage resources.
To install the latest Azure CLI, follow these steps:
1. Run the following commands in a terminal window. It might take five minutes to install the Azure CLI.

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Summary
You've installed the Azure CLI. Your next task is to create your Azure IoT hub and device identity by using the Azure
CLI.

Next steps
Create your IoT hub and register your Arduino board
Run a sample application to send device-to-cloud
messages
1/24/2017 • 3 min to read • Edit on GitHub

What you will do

This article will show you how to deploy and run a sample application on your Adafruit Feather M0 WiFi Arduino
board that sends messages to your IoT hub.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

You will learn how to use the gulp tool to deploy and run the sample Arduino application on your Arduino board.

What you need

Before you start this task, you must have successfully completed Create an Azure function app and a storage
account to process and store IoT hub messages.

Get your IoT hub and device connection strings

The device connection string is used to connect your Arduino board to your IoT hub. The IoT hub connection string
is used to connect your IoT hub to the device identity that represents your Arduino board in the IoT hub.
List all your IoT hubs in your resource group by running the following Azure CLI command:

az iot hub list -g iot-sample --query [].name

Use iot-sample as the value of {resource group name} if you didn't change the value.
Get the IoT hub connection string by running the following Azure CLI command:

az iot hub show-connection-string --name {my hub name}

{my hub name} is the name that you specified when you created your IoT hub and registered your Arduino board.
Get the device connection string by running the following command:

az iot device show-connection-string --hub-name {my hub name} --device-id mym0wifi

Use mym0wifi as the value of {device id} if you didn't change the value.

Configure the device connection

To configure the device connection, follow these steps:
1. Obtain the serial port of the device with the device discovery cli:
devdisco list --usb

You should see an output that is similar to the following and find the usb COM port for your Arduino board:

2. Open the file config.json in the lesson folder and add the value of the found COM port number:

{
"device_port" : "COM1"
}

NOTE
For the COM port, on Windows platform, it has the format of COM1, COM2, ... . On macOS or Ubuntu, it starts
with /dev/ .

3. Initialize the configuration file by running the following commands:

npm install
gulp init
gulp install-tools

4. Open the device configuration file config-arduino.json in Visual Studio Code by running the following
command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-arduino.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-arduino.json

5. Make the following replacements in the config-arduino.json file:

Replace [Wi-Fi SSID] with your Wi-Fi SSID that connected to the Internet.
Replace [Wi-Fi password] with your Wi-Fi password. Remove the string if your Wi-Fi doesn't require
password.
Replace [IoT device connection string] with the device connection string you obtained.
Replace [IoT hub connection string] with the iot hub connection string you obtained.

NOTE
You don't need azure_storage_connection_string in this article. Keep it as is.

Deploy and run the sample application

Deploy and run the sample application on your Arduino board by running the following command:
gulp run
# You can monitor the serial port by running listen task:
gulp listen

# Or you can combine above two gulp tasks into one:

gulp run --listen

NOTE
The default gulp task runs install-tools and run tasks sequentially. When you deployed the blink app, you ran these
tasks separately.

Verify that the sample application works

You should see the GPIO #0 on-board LED blinking every two seconds. Every time the LED blinks, the sample
application sends a message to your IoT hub and verifies that the message has been successfully sent to your IoT
hub. In addition, each message received by the IoT hub is printed in the console window. The sample application
terminates automatically after sending 20 messages.

Summary
You've deployed and run the new blink sample application on your Arduino board to send device-to-cloud
messages to your IoT hub. You now monitor your messages as they are written to the storage account.

Next steps
Read messages persisted in Azure Storage
Read messages persisted in Azure Storage
1/24/2017 • 2 min to read • Edit on GitHub

What you will do

Monitor the device-to-cloud messages that are sent from your Adafruit Feather M0 WiFi Arduino board to your IoT
hub as the messages are written to your Azure Table storage.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn how to use the gulp read-message task to read messages persisted in your Azure Table
storage.

What you need

Before starting this process, you must have successfully completed Run the Azure blink sample application on your
Arduino board.

Read new messages from your storage account

In the previous article, you ran a sample application on your Arduino board. The sample application sent messages
to your Azure IoT hub. The messages sent to your IoT hub are stored into your Azure Table storage via the Azure
function app. You need the Azure storage connection string to read messages from your Azure Table storage.
To read messages stored in your Azure Table storage, follow these steps:
1. Get the connection string by running the following commands:

az storage account list -g iot-sample --query [].name

az storage account show-connection-string -g iot-sample -n {storage name}

The first command retrieves the storage name that is used in the second command to get the connection
string. Use iot-sample as the value of {resource group name} if you didn't change the value.
2. Open the configuration file config-arduino.json in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-arduino.json

# For MacOS or Ubuntu

code ~/.iot-hub-getting-started/config-arduino.json

3. Replace [Azure storage connection string] with the connection string you got in step 1.
4. Save the config-arduino.json file.
5. Send messages again and read them from your Azure Table storage by running the following command:
gulp run --read-storage

# You can monitor the serial port by running listen task:

gulp listen

# Or you can combine above two gulp tasks into one:

gulp run --read-storage --listen

The logic for reading from Azure Table storage is in the azure-table.js file.

Summary
You've successfully connected your Arduino board to your IoT hub in the cloud and used the blink sample
application to send device-to-cloud messages. You also used the Azure function app to store incoming IoT hub
messages to your Azure Table storage. You can now send cloud-to-device messages from your IoT hub to your
Arduino board.

Next steps
Send cloud-to-device messages
Change the on and off behavior of the LED
1/24/2017 • 2 min to read • Edit on GitHub

What you will do

Customize the messages to change the LED’s on and off behavior. If you have any problems, look for solutions on
the troubleshooting page for your Adafruit Feather M0 WiFi Arduino board.

What you will learn

Use additional Arduino functions to change the LED’s on and off behavior.

What you need

You must have successfully completed Run a sample application on your Arduino board to receive cloud to device
messages.

Add functions to main.c and gulpfile.js

1. Open the sample application in Visual Studio code by running the following commands:

cd Lesson4
code .

2. Open the app.ino file, and then add the following functions after blinkLED() function:

static void turnOnLED()

{
digitalWrite(LED_PIN, HIGH);
}

static void turnOffLED()

{
digitalWrite(LED_PIN, LOW);
}
3. Add the following conditions before the else if block of the receiveMessageCallback function:

else if (strcmp((const char*)value, "\"on\"") == 0)

{
turnOnLED();
}
else if (0 == strcmp((const char*)value, "\"off\"") == 0)
{
turnOffLED();
}

Now you’ve configured the sample application to respond to more instructions through messages. The "on"
instruction turns on the LED, and the "off" instruction turns off the LED.
4. Open the gulpfile.js file, and then add a new function before the function sendMessage :

var buildCustomMessage = function (messageId) {

if ((messageId & 1) && (messageId < MAX_MESSAGE_COUNT)) {
return new Message(JSON.stringify({ command: 'on', messageId: messageId }));
} else if (messageId < MAX_MESSAGE_COUNT) {
return new Message(JSON.stringify({ command: 'off', messageId: messageId }));
} else {
return new Message(JSON.stringify({ command: 'stop', messageId: messageId }));
}
};
5. In the sendMessage function, replace the line var message = buildMessage(sentMessageCount); with the new
line shown in the following snippet:

var message = buildCustomMessage(sentMessageCount);

6. Save all the changes.

Deploy and run the sample application
Deploy and run the sample application on your Arduino board by running the following command:

gulp run
# You can monitor the serial port by running listen task:
gulp listen

# Or you can combine above two gulp tasks into one:

gulp run --listen

You should see the LED turn on for two seconds, and then turn off for another two seconds. The last "stop"
message stops the sample application from running.
Congratulations! You’ve successfully customized the messages that are sent to your Arduino board from your IoT
hub.
Summary
This optional section demonstrates how to customize messages so that the sample application can control the on
and off behavior of the LED in a different way.
Troubleshooting
1/24/2017 • 3 min to read • Edit on GitHub

Hardware issues
For information about solving common problems on your Adafruit Feather M0 WiFi Arduino board, see the
official troubleshooting page.

Node.js package issues

No response during gulp tasks
If you encounter problems running gulp tasks, you can add the --verbose option for debugging. Try to
terminate current gulp tasks by using Ctrl + C , and then run the following command in your console window
to see debug messages. You might see detailed error messages in your console output.

gulp --verbose

Or you can add --listen to open serial port to output device log information.

gulp --listen

NPM issues
Try to update your NPM package with the following command:

npm install -g npm

If the problem still exists, leave your comments at the end of this article or create a GitHub issue in our sample
repository.

Azure-CLI issues
The Azure command-line interface (Azure CLI) is a preview build. Look for solution in the Preview Install Guide
to seek solutions. Try to upgrade Azure-cli to latest version when commands don’t work as expected.
If you encounter any bugs with the tool, file an issue in the Issues section of the GitHub repo.
For help troubleshooting common problems, check the readme.
If you meet "Could not find a version that satisfies the requirement", please run the following command to
upgrade pip to lastest version.

python -m pip install --upgrade pip

Python installation issues

Legacy installation issues (macOS )
When you're installing pip, a permission error is thrown when older packages that are installed with su
permissions. This situation occurs because a previous installation of Python using brew (macOS) is not
uninstalled completely. Some pip packages from a previous installation were created by root, which causes the
permission error. The solution is to remove those packages installed by root. Use the following steps to
complete this task:
1. Go to: /usr/local/lib/python2.7/site-packages
2. List packages create by root: ls -l | grep root
3. Uninstall packages from step 2: sudo rm -rf {package name}
4. Reinstall Python.

Azure IoT Hub issues

If you've successfully provisioned your Azure IoT hub with azure-cli , and you need a tool to manage the
devices that are connecting to your IoT hub, try the following tools:
Device Explorer
Device Explorer runs on your Windows local machine and connects to your IoT hub in Azure. It communicates
with the following IoT Hub endpoints:
Device identity management to provision and manage devices registered with your IoT hub.
Receive device-to-cloud so you can monitor messages sent from your device to your IoT hub.
Send cloud-to-device so you can send messages to your devices from your IoT hub.
Configure your IoT hub connection string within this tool to use all its capabilities.
IoT hub Explorer
IoT hub Explorer is a sample multiplatform CLI tool to manage device clients. You can use the tool to manage
the devices in the identity registry, monitor device-to-cloud messages, and send cloud-to-device commands.
To install the latest (prerelease) version of the iothub-explorer tool, run the following command in your
command-line environment:

npm install -g iothub-explorer@latest

You can use the following command to get additional help about all the iothub-explorer commands and their
parameters:

iothub-explorer help

Azure portal
A full CLI experience helps you create and manage all your Azure resources. You might also want to use the
Azure portal to help provision, manage, and debug your Azure resources.

Azure storage issues

Microsoft Azure Storage Explorer (preview) is a standalone app from Microsoft that you can use to work with
Azure Storage data on Windows, macOS, and Linux. By using this tool, you can connect to your table and see
the data in it. You can use this tool to troubleshoot your Azure Storage issues.
Get started with the Azure IoT Gateway SDK (Linux)
1/18/2017 • 11 min to read • Edit on GitHub

This article provides a detailed walkthrough of the Hello World sample code to illustrate the fundamental
components of the Azure IoT Gateway SDK architecture. The sample uses the Azure IoT Gateway SDK to build a
simple gateway that logs a "hello world" message to a file every five seconds.
This walkthrough covers:
Concepts: A conceptual overview of the components that compose any gateway you create with the IoT
Gateway SDK.
Hello World sample architecture: Describes how the concepts apply to the Hello World sample and how
the components fit together.
How to build the sample: The steps required to build the sample.
How to run the sample: The steps required to run the sample.
Typical output: An example of the output to expect when you run the sample.
Code snippets: A collection of code snippets to show how the Hello World sample implements key gateway
components.

Azure IoT Gateway SDK concepts

Before you examine the sample code or create your own field gateway using the IoT Gateway SDK, you should
understand the key concepts that underpin the architecture of the SDK.
Modules
You build a gateway with the Azure IoT Gateway SDK by creating and assembling modules. Modules use
messages to exchange data with each other. A module receives a message, performs some action on it, optionally
transforms it into a new message, and then publishes it for other modules to process. Some modules might only
produce new messages and never process incoming messages. A chain of modules creates a data processing
pipeline with each module performing a transformation on the data at one point in that pipeline.

The SDK contains the following:

Pre-written modules which perform common gateway functions.
The interfaces a developer can use to write custom modules.
The infrastructure necessary to deploy and run a set of modules.
The SDK provides an abstraction layer that enables you to build gateways to run on a variety of operating
systems and platforms.
Messages
Although thinking about modules passing messages to each other is a convenient way to conceptualize how a
gateway functions, it does not accurately reflect what happens. Modules use a broker to communicate with each
other, they publish messages to the broker (bus, pubsub, or any other messaging pattern) and then let the broker
route the message to the modules connected to it.
A module uses the Broker_Publish function to publish a message to the broker. The broker delivers messages to
a module by invoking a callback function. A message consists of a set of key/value properties and content passed
as a block of memory.

Message routing and filtering

There are two ways of directing messages to the correct modules. A set of links can be passed to the broker so
the broker knows the source and sink for each module, or the module can filter on the properties of the message.
A module should only act upon a message if the message is intended for it. The links and message filtering is
what effectively creates a message pipeline.

Hello World sample architecture

The Hello World sample illustrates the concepts described in the previous section. The Hello World sample
implements a gateway that has a pipeline made up of two modules:
The hello world module creates a message every five seconds and passes it to the logger module.
The logger module writes the messages it receives to a file.

As described in the previous section, the Hello World module does not pass messages directly to the logger
module every five seconds. Instead, it publishes a message to the broker every five seconds.
The logger module receives the message from the broker and acts upon it, writing the contents of the message to
a file.
The logger module only consumes messages from the broker, it never publishes new messages to the broker.

The figure above shows the architecture of the Hello World sample and the relative paths to the source files that
implement different portions of the sample in the repository. Explore the code on your own, or use the code
snippets below as a guide.

How to build the sample

Before you get started, you must set up your development environment for working with the SDK on Linux.
1. Open a shell.
2. Navigate to the root folder in your local copy of the azure-iot-gateway-sdk repository.
3. Run the tools/build.sh script. This script uses the cmake utility to create a folder called build in the root
folder of your local copy of the azure-iot-gateway-sdk repository and generate a makefile. The script then
builds the solution, skipping unit tests and end to end tests. Add the --run-unittests parameter if you want to
build and run the unit tests. Add the --run-e2e-tests if you want to build and run the end to end tests.

NOTE
Every time you run the build.sh script, it deletes and then recreates the build folder in the root folder of your local copy of
the azure-iot-gateway-sdk repository.

How to run the sample

1. The build.sh script generates its output in the build folder in your local copy of the azure-iot-gateway-
sdk repository. This includes the two modules used in this sample.
The build script places liblogger.so in the build/modules/logger/ folder and libhello_world.so in the
build/modules/hello_world/ folder. Use these paths for the module path value as shown in the JSON
settings file below.
2. The hello_world_sample process takes the path to a JSON configuration file as an argument in the
command-line. An example JSON file has been provided as part of the repo at azure-iot-gateway-
sdk/samples/hello_world/src/hello_world_win.json and is copied below. It will work as is unless you
have modified the build script to place modules or sample executables in non-default locations.

NOTE
The module paths are relative to the current working directory from where the hello_world_sample executable is
launched, not the directory where the executable is located. The sample JSON configuration file defaults to writing
'log.txt' in your current working directory.

{
"modules" :
[
{
"name" : "logger",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/logger/liblogger.so"
}
},
"args" : {"filename":"log.txt"}
},
{
"name" : "hello_world",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/hello_world/libhello_world.so"
}
},
"args" : null
}
],
"links":
[
{
"source": "hello_world",
"sink": "logger"
}
]
}

3. Navigate to azure-iot-gateway-sdk/build folder.

4. Run the following command:

./samples/hello_world/hello_world_sample ./../samples/hello_world/src/hello_world_lin.json

Typical output
Below is an example of the output written to the log file by the Hello World sample. Newline and Tab characters
have been added for legibility:
[{
"time": "Mon Apr 11 13:48:07 2016",
"content": "Log started"
}, {
"time": "Mon Apr 11 13:48:48 2016",
"properties": {
"helloWorld": "from Azure IoT Gateway SDK simple sample!"
},
"content": "aGVsbG8gd29ybGQ="
}, {
"time": "Mon Apr 11 13:48:55 2016",
"properties": {
"helloWorld": "from Azure IoT Gateway SDK simple sample!"
},
"content": "aGVsbG8gd29ybGQ="
}, {
"time": "Mon Apr 11 13:49:01 2016",
"properties": {
"helloWorld": "from Azure IoT Gateway SDK simple sample!"
},
"content": "aGVsbG8gd29ybGQ="
}, {
"time": "Mon Apr 11 13:49:04 2016",
"content": "Log stopped"
}]

Code snippets
This section discusses some key parts of the code in the Hello World sample.
Gateway creation
The developer must write the gateway process. This program creates the internal infrastructure (the broker),
loads the modules, and sets everything up to function correctly. The SDK provides the
Gateway_Create_From_JSON function to enable you to bootstrap a gateway from a JSON file. To use the
Gateway_Create_From_JSON function you must pass it the path to a JSON file that specifies the modules to
load.
You can find the code for the gateway process in the Hello World sample in the main.c file. For legibility, the
snippet below shows an abbreviated version of the gateway process code. This program creates a gateway and
then waits for the user to press the ENTER key before it tears down the gateway.

int main(int argc, char** argv)

{
GATEWAY_HANDLE gateway;
if ((gateway = Gateway_Create_From_JSON(argv[1])) == NULL)
{
printf("failed to create the gateway from JSON\n");
}
else
{
printf("gateway successfully created from JSON\n");
printf("gateway shall run until ENTER is pressed\n");
(void)getchar();
Gateway_LL_Destroy(gateway);
}
return 0;
}

The JSON settings file contains a list of modules to load and links between the modules. Each module must
specify a:
name: a unique name for the module.
loader: a loader which knows how to load the desired module. Loaders are an extension point for loading
different types of modules. We provide loaders for use with modules written in native C, Node.js, Java, and
.NET. The Hello World sample only uses the "native" loader since all the modules in this sample are
dynamic libraries written in C. Please refer to the Node.js, Java, or .NET samples for more information on
using modules written in different languages.
name: name of the loader used to load the module.
entrypoint: the path to the library containing the module. For Linux this is a .so file, on Windows this is
a .dll file. Note that this entry point is specific to the type of loader being used. For example, the Node.js
loader's entry point is a .js file, the Java loader's entry point is a classpath + class name, and the .NET
loader's entry point is an assembly name + class name.
args: any configuration information the module needs.
The following code shows the JSON used to declare all of the modules for the Hello World sample on Linux.
Whether a module requires any arguments depends on the design of the module. In this example, the logger
module takes an argument which is the path to the output file and the Hello World module does not take any
arguments.

"modules" :
[
{
"name" : "logger",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/logger/liblogger.so"
}
},
"args" : {"filename":"log.txt"}
},
{
"name" : "hello_world",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/hello_world/libhello_world.so"
}
},
"args" : null
}
]

The JSON file also contains the links between the modules that will be passed to the broker. A link has two
properties:
source: a module name from the modules section, or "*".
sink: a module name from the modules section.

Each link defines a message route and direction. Messages from module source are to be delivered to the
module sink . The source may be set to "*", indicating that messages from any module will be received by
sink .

The following code shows the JSON used to configure links between the modules used in the Hello World sample
on Linux. Every message produced by module hello_world will be consumed by module logger .
"links":
[
{
"source": "hello_world",
"sink": "logger"
}
]

Hello World module message publishing

You can find the code used by the "hello world" module to publish messages in the 'hello_world.c' file. The
snippet below shows an amended version with additional comments and some error handling code removed for
legibility:

int helloWorldThread(void *param)

{
// create data structures used in function.
HELLOWORLD_HANDLE_DATA* handleData = param;
MESSAGE_CONFIG msgConfig;
MAP_HANDLE propertiesMap = Map_Create(NULL);

// add a property named "helloWorld" with a value of "from Azure IoT

// Gateway SDK simple sample!" to a set of message properties that
// will be appended to the message before publishing it.
Map_AddOrUpdate(propertiesMap, "helloWorld", "from Azure IoT Gateway SDK simple sample!")

// set the content for the message

msgConfig.size = strlen(HELLOWORLD_MESSAGE);
msgConfig.source = HELLOWORLD_MESSAGE;

// set the properties for the message

msgConfig.sourceProperties = propertiesMap;

// create a message based on the msgConfig structure

MESSAGE_HANDLE helloWorldMessage = Message_Create(&msgConfig);

while (1)
{
if (handleData->stopThread)
{
(void)Unlock(handleData->lockHandle);
break; /*gets out of the thread*/
}
else
{
// publish the message to the broker
(void)Broker_Publish(handleData->brokerHandle, helloWorldMessage);
(void)Unlock(handleData->lockHandle);
}

(void)ThreadAPI_Sleep(5000); /*every 5 seconds*/

}

Message_Destroy(helloWorldMessage);

return 0;
}

Hello World module message processing

The Hello World module never needs to process any messages that other modules publish to the broker. This
makes implementation of the message callback in the Hello World module a no-op function.
static void HelloWorld_Receive(MODULE_HANDLE moduleHandle, MESSAGE_HANDLE messageHandle)
{
/* No action, HelloWorld is not interested in any messages. */
}

Logger module message publishing and processing

The Logger module receives messages from the broker and writes them to a file. It never publishes any
messages. Therefore, the code of the logger module never calls the Broker_Publish function.
The Logger_Recieve function in the logger.c file is the callback the broker invokes to deliver messages to the
logger module. The snippet below shows an amended version with additional comments and some error
handling code removed for legibility:

static void Logger_Receive(MODULE_HANDLE moduleHandle, MESSAGE_HANDLE messageHandle)

{

time_t temp = time(NULL);

struct tm* t = localtime(&temp);
char timetemp[80] = { 0 };

// Get the message properties from the message

CONSTMAP_HANDLE originalProperties = Message_GetProperties(messageHandle);
MAP_HANDLE propertiesAsMap = ConstMap_CloneWriteable(originalProperties);

// Convert the collection of properties into a JSON string

STRING_HANDLE jsonProperties = Map_ToJSON(propertiesAsMap);

// base64 encode the message content

const CONSTBUFFER * content = Message_GetContent(messageHandle);
STRING_HANDLE contentAsJSON = Base64_Encode_Bytes(content->buffer, content->size);

// Start the construction of the final string to be logged by adding

// the timestamp
STRING_HANDLE jsonToBeAppended = STRING_construct(",{\"time\":\"");
STRING_concat(jsonToBeAppended, timetemp);

// Add the message properties

STRING_concat(jsonToBeAppended, "\",\"properties\":");
STRING_concat_with_STRING(jsonToBeAppended, jsonProperties);

// Add the content

STRING_concat(jsonToBeAppended, ",\"content\":\"");
STRING_concat_with_STRING(jsonToBeAppended, contentAsJSON);
STRING_concat(jsonToBeAppended, "\"}]");

// Write the formatted string

LOGGER_HANDLE_DATA *handleData = (LOGGER_HANDLE_DATA *)moduleHandle;
addJSONString(handleData->fout, STRING_c_str(jsonToBeAppended);
}

Next steps
To learn about how to use the IoT Gateway SDK, see the following:
IoT Gateway SDK – send device-to-cloud messages with a simulated device using Linux.
Azure IoT Gateway SDK on GitHub.
Get started with the Azure IoT Gateway SDK
(Windows)
1/18/2017 • 10 min to read • Edit on GitHub

This article provides a detailed walkthrough of the Hello World sample code to illustrate the fundamental
components of the Azure IoT Gateway SDK architecture. The sample uses the Azure IoT Gateway SDK to build a
simple gateway that logs a "hello world" message to a file every five seconds.
This walkthrough covers:
Concepts: A conceptual overview of the components that compose any gateway you create with the IoT
Gateway SDK.
Hello World sample architecture: Describes how the concepts apply to the Hello World sample and how the
components fit together.
How to build the sample: The steps required to build the sample.
How to run the sample: The steps required to run the sample.
Typical output: An example of the output to expect when you run the sample.
Code snippets: A collection of code snippets to show how the Hello World sample implements key gateway
components.

Azure IoT Gateway SDK concepts

Before you examine the sample code or create your own field gateway using the IoT Gateway SDK, you should
understand the key concepts that underpin the architecture of the SDK.
Modules
You build a gateway with the Azure IoT Gateway SDK by creating and assembling modules. Modules use messages
to exchange data with each other. A module receives a message, performs some action on it, optionally transforms
it into a new message, and then publishes it for other modules to process. Some modules might only produce new
messages and never process incoming messages. A chain of modules creates a data processing pipeline with each
module performing a transformation on the data at one point in that pipeline.

The SDK contains the following:

Pre-written modules which perform common gateway functions.
The interfaces a developer can use to write custom modules.
The infrastructure necessary to deploy and run a set of modules.
The SDK provides an abstraction layer that enables you to build gateways to run on a variety of operating systems
and platforms.
Messages
Although thinking about modules passing messages to each other is a convenient way to conceptualize how a
gateway functions, it does not accurately reflect what happens. Modules use a broker to communicate with each
other, they publish messages to the broker (bus, pubsub, or any other messaging pattern) and then let the broker
route the message to the modules connected to it.
A module uses the Broker_Publish function to publish a message to the broker. The broker delivers messages to a
module by invoking a callback function. A message consists of a set of key/value properties and content passed as
a block of memory.

Message routing and filtering

There are two ways of directing messages to the correct modules. A set of links can be passed to the broker so the
broker knows the source and sink for each module, or the module can filter on the properties of the message. A
module should only act upon a message if the message is intended for it. The links and message filtering is what
effectively creates a message pipeline.

Hello World sample architecture

The Hello World sample illustrates the concepts described in the previous section. The Hello World sample
implements a gateway that has a pipeline made up of two modules:
The hello world module creates a message every five seconds and passes it to the logger module.
The logger module writes the messages it receives to a file.

As described in the previous section, the Hello World module does not pass messages directly to the logger
module every five seconds. Instead, it publishes a message to the broker every five seconds.
The logger module receives the message from the broker and acts upon it, writing the contents of the message to a
file.
The logger module only consumes messages from the broker, it never publishes new messages to the broker.

The figure above shows the architecture of the Hello World sample and the relative paths to the source files that
implement different portions of the sample in the repository. Explore the code on your own, or use the code
snippets below as a guide.

How to build the sample

Before you get started, you must set up your development environment for working with the SDK on Windows.
1. Open a Developer Command Prompt for VS2015 command prompt.
2. Navigate to the root folder in your local copy of the azure-iot-gateway-sdk repository.
3. Run the tools\build.cmd script. This script creates a Visual Studio solution file and builds the solution. You can
find the Visual Studio solution in the build folder in your local copy of the azure-iot-gateway-sdk repository.
Additional parameters can be given to the script to build and run unit and end to end tests. These paramaters
are --run-unittests and --run-e2e-tests respectively.

How to run the sample

1. The build.cmd script creates a folder called build in your local copy of the repository. This folder contains
the two modules used in this sample.
The build script places logger.dll in the build\modules\logger\Debug folder and hello_world.dll in the
build\modules\hello_world\Debug folder. Use these paths for the module path value as shown in the
following JSON settings file.
2. The hello_world_sample process takes the path to a JSON configuration file as an argument in the
command-line. The following example JSON file has been provided as part of the repo at azure-iot-
gateway-sdk\samples\hello_world\src\hello_world_win.json. It works as is unless you have modified
the build script to place modules or sample executables in non-default locations.
NOTE
The module paths are relative to the directory where the hello_world_sample.exe is located. The sample JSON
configuration file defaults to writing 'log.txt' in your current working directory.

{
"modules": [
{
"name": "logger",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "..\\..\\..\\modules\\logger\\Debug\\logger.dll"
}
},
"args": { "filename": "log.txt" }
},
{
"name": "hello_world",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "..\\..\\..\\modules\\hello_world\\Debug\\hello_world.dll"
}
},
"args": null
}
],
"links": [
{
"source": "hello_world",
"sink": "logger"
}
]
}

3. Navigate to the root folder of your local copy of the azure-iot-gateway-sdk repository.
4. Run the following command:

build\samples\hello_world\Debug\hello_world_sample.exe samples\hello_world\src\hello_world_win.json

Typical output
Below is an example of the output written to the log file by the Hello World sample. Newline and Tab characters
have been added for legibility:
[{
"time": "Mon Apr 11 13:48:07 2016",
"content": "Log started"
}, {
"time": "Mon Apr 11 13:48:48 2016",
"properties": {
"helloWorld": "from Azure IoT Gateway SDK simple sample!"
},
"content": "aGVsbG8gd29ybGQ="
}, {
"time": "Mon Apr 11 13:48:55 2016",
"properties": {
"helloWorld": "from Azure IoT Gateway SDK simple sample!"
},
"content": "aGVsbG8gd29ybGQ="
}, {
"time": "Mon Apr 11 13:49:01 2016",
"properties": {
"helloWorld": "from Azure IoT Gateway SDK simple sample!"
},
"content": "aGVsbG8gd29ybGQ="
}, {
"time": "Mon Apr 11 13:49:04 2016",
"content": "Log stopped"
}]

Code snippets
This section discusses some key parts of the code in the Hello World sample.
Gateway creation
The developer must write the gateway process. This program creates the internal infrastructure (the broker), loads
the modules, and sets everything up to function correctly. The SDK provides the Gateway_Create_From_JSON
function to enable you to bootstrap a gateway from a JSON file. To use the Gateway_Create_From_JSON
function you must pass it the path to a JSON file that specifies the modules to load.
You can find the code for the gateway process in the Hello World sample in the main.c file. For legibility, the
snippet below shows an abbreviated version of the gateway process code. This program creates a gateway and
then waits for the user to press the ENTER key before it tears down the gateway.

int main(int argc, char** argv)

{
GATEWAY_HANDLE gateway;
if ((gateway = Gateway_Create_From_JSON(argv[1])) == NULL)
{
printf("failed to create the gateway from JSON\n");
}
else
{
printf("gateway successfully created from JSON\n");
printf("gateway shall run until ENTER is pressed\n");
(void)getchar();
Gateway_LL_Destroy(gateway);
}
return 0;
}

The JSON settings file contains a list of modules to load and links between the modules. Each module must specify
a:
name: a unique name for the module.
loader: a loader which knows how to load the desired module. Loaders are an extension point for loading
different types of modules. We provide loaders for use with modules written in native C, Node.js, Java, and
.NET. The Hello World sample only uses the "native" loader since all the modules in this sample are dynamic
libraries written in C. Please refer to the Node.js, Java, or .NET samples for more information on using
modules written in different languages.
name: name of the loader used to load the module.
entrypoint: the path to the library containing the module. For Linux this is a .so file, on Windows this is a
.dll file. Note that this entry point is specific to the type of loader being used. For example, the Node.js
loader's entry point is a .js file, the Java loader's entry point is a classpath + class name, and the .NET
loader's entry point is an assembly name + class name.
args: any configuration information the module needs.
The following code shows the JSON used to declare all of the modules for the Hello World sample on Linux.
Whether a module requires any arguments depends on the design of the module. In this example, the logger
module takes an argument which is the path to the output file and the Hello World module does not take any
arguments.

"modules" :
[
{
"name" : "logger",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/logger/liblogger.so"
}
},
"args" : {"filename":"log.txt"}
},
{
"name" : "hello_world",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/hello_world/libhello_world.so"
}
},
"args" : null
}
]

The JSON file also contains the links between the modules that will be passed to the broker. A link has two
properties:
source: a module name from the modules section, or "*".
sink: a module name from the modules section.

Each link defines a message route and direction. Messages from module source are to be delivered to the module
sink . The source may be set to "*", indicating that messages from any module will be received by sink .

The following code shows the JSON used to configure links between the modules used in the Hello World sample
on Linux. Every message produced by module hello_world will be consumed by module logger .
"links":
[
{
"source": "hello_world",
"sink": "logger"
}
]

Hello World module message publishing

You can find the code used by the "hello world" module to publish messages in the 'hello_world.c' file. The snippet
below shows an amended version with additional comments and some error handling code removed for legibility:

int helloWorldThread(void *param)

{
// create data structures used in function.
HELLOWORLD_HANDLE_DATA* handleData = param;
MESSAGE_CONFIG msgConfig;
MAP_HANDLE propertiesMap = Map_Create(NULL);

// add a property named "helloWorld" with a value of "from Azure IoT

// Gateway SDK simple sample!" to a set of message properties that
// will be appended to the message before publishing it.
Map_AddOrUpdate(propertiesMap, "helloWorld", "from Azure IoT Gateway SDK simple sample!")

// set the content for the message

msgConfig.size = strlen(HELLOWORLD_MESSAGE);
msgConfig.source = HELLOWORLD_MESSAGE;

// set the properties for the message

msgConfig.sourceProperties = propertiesMap;

// create a message based on the msgConfig structure

MESSAGE_HANDLE helloWorldMessage = Message_Create(&msgConfig);

while (1)
{
if (handleData->stopThread)
{
(void)Unlock(handleData->lockHandle);
break; /*gets out of the thread*/
}
else
{
// publish the message to the broker
(void)Broker_Publish(handleData->brokerHandle, helloWorldMessage);
(void)Unlock(handleData->lockHandle);
}

(void)ThreadAPI_Sleep(5000); /*every 5 seconds*/

}

Message_Destroy(helloWorldMessage);

return 0;
}

Hello World module message processing

The Hello World module never needs to process any messages that other modules publish to the broker. This
makes implementation of the message callback in the Hello World module a no-op function.
static void HelloWorld_Receive(MODULE_HANDLE moduleHandle, MESSAGE_HANDLE messageHandle)
{
/* No action, HelloWorld is not interested in any messages. */
}

Logger module message publishing and processing

The Logger module receives messages from the broker and writes them to a file. It never publishes any messages.
Therefore, the code of the logger module never calls the Broker_Publish function.
The Logger_Recieve function in the logger.c file is the callback the broker invokes to deliver messages to the
logger module. The snippet below shows an amended version with additional comments and some error handling
code removed for legibility:

static void Logger_Receive(MODULE_HANDLE moduleHandle, MESSAGE_HANDLE messageHandle)

{

time_t temp = time(NULL);

struct tm* t = localtime(&temp);
char timetemp[80] = { 0 };

// Get the message properties from the message

CONSTMAP_HANDLE originalProperties = Message_GetProperties(messageHandle);
MAP_HANDLE propertiesAsMap = ConstMap_CloneWriteable(originalProperties);

// Convert the collection of properties into a JSON string

STRING_HANDLE jsonProperties = Map_ToJSON(propertiesAsMap);

// base64 encode the message content

const CONSTBUFFER * content = Message_GetContent(messageHandle);
STRING_HANDLE contentAsJSON = Base64_Encode_Bytes(content->buffer, content->size);

// Start the construction of the final string to be logged by adding

// the timestamp
STRING_HANDLE jsonToBeAppended = STRING_construct(",{\"time\":\"");
STRING_concat(jsonToBeAppended, timetemp);

// Add the message properties

STRING_concat(jsonToBeAppended, "\",\"properties\":");
STRING_concat_with_STRING(jsonToBeAppended, jsonProperties);

// Add the content

STRING_concat(jsonToBeAppended, ",\"content\":\"");
STRING_concat_with_STRING(jsonToBeAppended, contentAsJSON);
STRING_concat(jsonToBeAppended, "\"}]");

// Write the formatted string

LOGGER_HANDLE_DATA *handleData = (LOGGER_HANDLE_DATA *)moduleHandle;
addJSONString(handleData->fout, STRING_c_str(jsonToBeAppended);
}

Next steps
To learn about how to use the IoT Gateway SDK, see the following:
IoT Gateway SDK – send device-to-cloud messages with a simulated device using Linux.
Azure IoT Gateway SDK on GitHub.
Get started with IoT Gateway Starter Kit with a
simulated device
1/25/2017 • 2 min to read • Edit on GitHub

In this tutorial, you begin by learning the basics of working with IoT Gateway Starter Kit. You will be working with
Intel NUC that's running Wind River Linux. You will learn how to seamleesly connect your devices to the cloud by
using Azure IoT Hub.

Don't have a kit yet?: Click here.

Lesson 1: Configure your NUC

In this lesson, you set up Intel NUC (Next Unit of Computing) in the Kit as an Azure IoT gateway, install the Azure
IoT Gateway SDK package on NUC, and run a sample app to verify the gateway functionality.
Estimated time to complete: 15 minutes
Go to Set up Intel NUC as an IoT gateway

Lesson 2: Create your IoT Hub

In this lesson, you install the tools and software on your host computer. Then you create your free Azure account,
provision your Azure IoT hub and create your first device in the IoT hub.
Complete Lesson 1 before you start this lesson.
Get the tools
Install the tools and software on your host computer.
Estimated time to complete: 20 minutes
Go to Get the tools
Create an IoT hub and register your device
Create your resource group, provision your first Azure IoT hub, and add your first device to the IoT hub using the
Azure CLI.
Estimated time to complete: 10 minutes
Go to Create an IoT hub and register your device

Lesson 3: Receive messages from the simulated device and read

messages from your IoT hub
In this lesson, you will use scripts to automate the configuration and execution of a simulated device app in your
gateway. The simulated device app generates sample temperature data and sends it to an IoT hub module. The IoT
hub module packages the data received and sends it to your IoT hub through the gateway framework provided in
the Azure IoT Gateway SDK.

Configure and run a simulated device

Prepare the sample codes. Then configure and run the simulated device sample application.
Estimated time to complete: 15 minutes
Go to Configure and run a simulated device
Read messages from your IoT hub
Run a sample code on your host computer to read the messages from your IoT hub.
Estimated time to complete: 15 minutes
Go to Read messages from your IoT hub

Lesson 4: Save messages to Azure Table storage

Create an Azure function app that gets incoming messages from your IoT hub and writes them to Azure Table
storage.
Create an Azure function app and Azure Storage account
Use an Azure Resource Manager template to create an Azure function app and an Azure Storage account.
Estimated time to complete: 10 minutes
Go to Create an Azure function app and Azure Storage account
Read messages persisted in Azure Table storage
Monitor the gateway-to-cloud messages as they are written to Azure Table storage.
Estimated time to complete: 5 minutes
Go to Read messages persisted in Azure Table storage.

Troubleshooting
If you have any problems during the lessons, look for solutions in the Troubleshooting article.

Explore more
Visit the Intel IoT Gateway Kit developer zone to learn more.
Set up Intel NUC as an IoT gateway
1/25/2017 • 3 min to read • Edit on GitHub

What you will do

Set up Intel NUC as an IoT gateway.
Install the Azure IoT Gateway SDK package on Intel NUC.
Run a "hello_world" sample application on Intel NUC to verify the gateway functionality. If you have any
problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to connect Intel NUC with peripherals.
How to install and update the required packages on Intel NUC using the Smart Package Manager.
How to run the "hello_world" sample application to verify the gateway functionality.

What you need

An Intel NUC Kit DE3815TYKE with the Intel IoT Gateway Software Suite (Wind River Linux *7.0.0.13)
preinstalled.
An Ethernet cable.
A keyboard.
An HDMI or VGA cable.
A monitor with an HDMI or VGA port.

Connect Intel NUC with the peripherals

The image below is an example of Intel NUC that is connected with various peripherals:
1. Connected to a keyboard.
2. Connected to the monitor by a VGA cable or HDMI cable.
3. Connected to a wired network by an Ethernet cable.
4. Connected to the power supply with a power cable.

Connect to the Intel NUC system from host computer via Secure Shell
(SSH)
Here you need keyboard and monitor to get the IP address of your NUC device. If you already know the IP address,
you can skip to step 3 in this section.
1. Turn on Intel NUC by pressing the Power button and log in the system.
The default user name and password are both root .
2. Get the IP address of NUC by running the ifconfig command. This step is done on the NUC device.
Here is an example of the command output.

In this example, the value that follows inet addr: is the IP address that you need when you plan to connect
remotely from a host computer to Intel NUC.
3. Use one of the following SSH clients from your host machine to connect to Intel NUC.
PuTTY for Windows.
The build-in SSH client on Ubuntu or macOS.
It is more efficient and productive to operate on Intel NUC from a host computer. You need the the IP
address, user name and password to connect the NUC via SSH client. Here is the example use SSH client on
macOS.

Install the Azure IoT Gateway SDK package

The Azure IoT Gateway SDK package contains the pre-compiled binaries of the SDK and its dependencies. These
binaries are the Azure IoT Gateway SDK, the Azure IoT SDK and the corresponding tools. The package also contains
a "hello_world" sample application that is used to validate the gateway functionality. The SDK is the core part of the
gateway. To install the package, follow these steps:
1. Add the IoT cloud repository by running the following commands in a terminal window:

rpm --import http://iotdk.intel.com/misc/iot_pub.key

smart channel --add IoT_Cloud type=rpm-md name="IoT_Cloud" baseurl=http://iotdk.intel.com/repos/iot-
cloud/wrlinux7/rcpl13/ -y

The rpm command imports the rpm key. The smart channel command adds the rpm channel to the Smart
Package Manager. Before you run the smart update command, you see an output like below.
smart update

2. Install the package by running the following command:

smart install packagegroup-cloud-azure -y

packagegroup-cloud-azure is the name of the package. The smart install command is used to install the
package.
After the package is installed, Intel NUC is expected to work as a gateway.

Run the Azure IoT Gateway SDK "hello_world" sample application

Go to azureiotgatewaysdk/samples and run the sample "hello_world" sample application. This sample application
creates a gateway from the hello_world.json file and uses the fundamental components of the Azure IoT Gateway
SDK architecture to log a hello world message to a file every 5 seconds.
You can run the sample "hello_world" sample application by running the following command:

cd /usr/share/azureiotgatewaysdk/samples/hello_world/
./hello_world hello_world.json

The sample application produces the following output if the gateway functionality is working correctly:

If you have any problems, look for solutions on the troubleshooting page.

Summary
Congratulations! You've finished setting up Intel NUC as a gateway. Now you're ready to move on to the next
lesson to set up your host computer, create an Azure IoT hub and register your Azure IoT hub logical device.

Next steps
Get your host computer and Azure IoT hub ready
Get the tools (Windows 7 and later)
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Install Git, Node.js, Gulp, Python.
Install the Azure command-line interface (Azure CLI).
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this lesson is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.
How to install Visual Studio Code.
Visual Studio Code is a cross platform, lightweight but powerful source code editor for Windows, Linux,
and macOS. It has great support for debugging, embedded Git control, syntax highlighting, intelligent
code completion, snippets, and code refactoring as well.
How to install Python.
Python is a widely used high-level, general-purpose, interpreted and dynamic programming language.
How to install the Azure CLI.
The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from a
command line to provision and manage resources.
How to use the Azure CLI to create an IoT hub.

What you need

An Internet connection to download the tools and software.
A Windows computer.

Install Git and Node.js

Click the following links to download and install Git and Node.js LTS for Windows.
Get Git for Windows
Get Node.js LTS for Windows

Install Node.js development tools

You use gulp.js to automate deployment and execution of scripts.
Press Windows + R , type cmd and press Enter to open a Command Prompt window, and then run the following
command:

npm install -g gulp

If you experience issues with the installation, see the troubleshooting guide for solutions to common problems.

NOTE
Node, NPM and Gulp are required to run automation scripts developed in Node.js.

Install Python
You can choose from Python 2.7, 3.4 or 3.5. In this tutorial, we use Python 2.7. If you've already installed python,
go to the next section.
Get Python for Windows
You also need to add the path of the folders where Python.exe and pip.exe are installed to the system PATH
environment variable. By default, python.exe is installed in C:\Python27 and pip.exe is installed in
C:\Python27\Scripts .

Install the Azure CLI

To install the Azure CLI, follow these steps:
1. Open a Command Prompt window as an administrator.
2. Install the Azure CLI by running the following commands:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

The installation might take 5 minutes.

3. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Install Visual Studio Code
You use Visual Studio Code later in the tutorial to edit configuration files.
Download and install Visual Studio Code.

Summary
You've installed all the required tools and software on your host computer. Your next task is to use the Azure CLI
to create an IoT hub and register your device in your IoT hub.

Next steps
Create an IoT hub and register your device
Get the tools (Ubuntu 16.04)
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Install Git, Node.js, Gulp, Python.
Install the Azure command-line interface (Azure CLI).
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this lesson is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.
How to install Visual Studio Code.
Visual Studio Code is a cross platform, lightweight but powerful source code editor for Windows, Linux,
and macOS. It has great support for debugging, embedded Git control, syntax highlighting, intelligent
code completion, snippets, and code refactoring as well.
How to install the Azure CLI
The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from a
command line to provision and manage resources.
How to use the Azure CLI to create an IoT hub.

What you need

An Internet connection to download the tools and software.
A computer that is running Ubuntu 16.04 or later.

Install Git and Node.js

To install Git and Node.js, follow these steps:
1. Press Ctrl + Alt + T to open a terminal.
2. Run the following commands:

sudo apt-get update

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install git

Install Node.js development tools

You use gulp.js to automate deployment and execution of scripts.
To install gulp, run the following command in the terminal:

sudo npm install -g gulp

If you experience issues with the installation, see the troubleshooting guide for solutions to common problems.

NOTE
Node, NPM and Gulp are required to run automation scripts developed in Node.js.

Install the Azure CLI

To install the Azure CLI, follow these steps:
1. Run the following commands in the terminal:

sudo apt-get update

sudo apt-get install -y libssl-dev libffi-dev
sudo apt-get install -y python-dev
sudo apt-get install -y build-essential
sudo apt-get install -y python-pip
sudo pip install --upgrade azure-cli
sudo pip install --upgrade azure-cli-iot

The installation might take 5 minutes.

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Install Visual Studio Code

You use Visual Studio Code later in the tutorial to edit configuration files.
Download and install Visual Studio Code.
Summary
You've installed all the required tools and software on your host computer. Your next task is to use the Azure CLI to
create an IoT hub and register your device in your IoT hub.

Next steps
Create an IoT hub and register your device
Get the tools (macOS)
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Install Git, Node.js, Gulp, Python.
Install the Azure command-line interface (Azure CLI).
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this lesson is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.
How to install Visual Studio Code.
Visual Studio Code is a cross platform, lightweight but powerful source code editor for Windows, Linux,
and macOS. It has great support for debugging, embedded Git control, syntax highlighting, intelligent
code completion, snippets, and code refactoring as well.
How to install Python.
Python is a widely used high-level, general-purpose, interpreted and dynamic programming language.
How to install the Azure CLI.
The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from a
command line to provision and manage resources.
How to use the Azure CLI to create an IoT hub.

What you need

An Internet connection to download the tools and software.
A Mac computer that’s running OS X Yosemite (10.10) or later.

Install Git and Node.js

To install Git and Node.js, use the Homebrew package management utility by following these steps:
1. Download and install Homebrew. If you’ve already installed Homebrew, go to step 2.
a. Press Cmd + Space and enter Terminal to open a terminal.
b. Run the following command:

/usr/bin/ruby -e "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"
2. Install Git and Node.js by running the following command:

brew install node git

Install Node.js development tools

You use gulp.js to automate deployment and execution of scripts.
To install gulp, run the following command in the terminal:

npm install -g gulp

If you experience issues with the installation, see the troubleshooting guide for solutions to common problems.

NOTE
Node, NPM and Gulp are required to run automation scripts developed in Node.js.

Install Python
Although Mac OS X comes with Python 2.7, we recommend that you install Python through Homebrew. See
Installing Python on Mac OS X.
Install Python and pip by running the following command:

brew install python

Install the Azure CLI

To install the Azure CLI, follow these steps:
1. Run the following commands in the terminal:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

The installation might take 5 minutes.

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Install Visual Studio Code
You use Visual Studio Code later in the tutorial to edit configuration files.
Download and install Visual Studio Code.

Summary
You’ve installed all the required tools and software on your Mac computer. Your next task is to use the Azure CLI to
create an IoT hub and register your device in your IoT hub.

Next steps
Create an IoT hub and register Device
Create your Azure IoT hub and register your device
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Create a resource group
Create your first IoT hub
Register your device in your IoT hub by using the Azure CLI.
When you register your device in your IoT hub, the Azure IoT Hub service generates a key for your device to use to
authenticate with the service.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to use the Azure CLI to create an IoT hub.
How to register a device in an IoT hub.

What you need

An active Azure subscription. If you don't have an Azure account, you can create a free Azure trial account in
just a few minutes.
You should have the Azure CLI installed.

Create an IoT hub

To create an IoT hub, follow these steps:
1. Sign in to your Azure account by running the following command:

az login

All your available subscriptions will be listed after a successful sign-in.

2. Set the default Azure subscription that you want to use by running the following command:

az account set --subscription {subscription id or name}

subscription ID or name can be found in the output of the az login or the az account list command.
3. Register the provider by running the following command. Resource providers are services that provide
resources for your application. You must register the provider before you can deploy the Azure resource
that the provider offers.

az provider register -n "Microsoft.Devices"

4. Create a resource group named iot-gateway in the West US region by running the following command:
az group create --name iot-gateway --location westus

westus is the location you create your resource group. If you want to use another location, you can run
az account list-locations -o table to see all the locations Azure supports.

5. Create an IoT hub in the iot-gateway resource group by running the following command:

az iot hub create --name {my hub name} --resource-group iot-gateway

By default, the tool creates an IoT Hub in the Free pricing tier. For more infomation, see Azure IoT Hub pricing.

NOTE
The name of your IoT hub must be globally unique. You can create only one F1 edition of Azure Iot Hub under your Azure
subscription.

Register your device in your IoT hub

Each device that sends messages to your IoT hub and receives messages from your IoT hub must be registered
with a unique ID. Register your device in your IoT hub by running following command:

az iot device create --device-id mydevice --hub-name {my hub name} --resource-group iot-gateway

Summary
You've created an IoT hub and registered your logical device with a device identity in your IoT hub. You're ready to
learn how to configure and run a gateway sample application to send data from your physical device to your IoT
hub in the cloud.

Next steps
Configure and run a simulated device cloud upload sample application
Configure and run a simulated device sample app
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Clone the sample repository.
Use the Azure CLI to get your IoT hub and logical device information for simulated device sample application.
Configure and run the simulated device sample application.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to configure and run the simulated device sample application.

What you need

You must have successfully completed
Create an IoT hub and register your device

Clone the sample repository to the host computer

To clone the sample repository, follow these steps on the host computer:
1. Open a Command Prompt in Windows or open a terminal in macOS or Ubuntu.
2. Run the following commands:

git clone https://github.com/Azure-samples/iot-hub-c-intel-nuc-gateway-getting-started

cd iot-hub-c-intel-nuc-gateway-getting-started

Configure the simulated device and your NUC

1. Open the configuration file config.json in Visual Studio Code by running the following command:

code config.json

2. Replace "has_sensortag": true with "has_sensortag": false

3. Initialize the configuration file by running the following commands:

cd Lesson3
npm install
gulp init

4. Open config-gateway.json in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-gateway.json
# For macOS or Ubuntu
code ~/.iot-hub-getting-started/config-gateway.json

5. Locate the following line of code and replace [device hostname or IP address] with IP address or host
name of the Intel NUC.
Get the connection string of your IoT hub logical device
To get the Azure IoT hub connection string of your logical device, run the following command on the host
computer:

az iot device show-connection-string --hub-name {IoT hub name} --device-id mydevice --resource-group iot-
gateway

{IoT hub name} is the IoT hub name that you used. Use iot-gateway as the value of {resource group name} and use
mydevice as the value of {device id} if you didn't change the value in Lesson 2.

Configure the simulated device cloud upload sample application

To configure and run the simulated device cloud upload sample application, follow these steps on the host
computer:
1. Open config-sensortag.json in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-sensortag.json
# For macOS or Ubuntu
code ~/.iot-hub-getting-started/config-sensortag.json
2. Make the following replacements in the code:
Replace [IoT hub name] with the IoT hub name.
Replace [IoT device connection string] with the connection string of your IoT hub logical device.
3. Run the application.
Deploy and run the application by running the following command:

gulp run

Verify the sample application works

You should now see output like the following:
The application sends temperature data to your IoT hub, which lasts for 40 seconds.

Summary
You've successfully configured and run the simulated device cloud upload sample application which sends data to
your IoT hub with simulated device.

Next steps
Read messages from your IoT hub
Read messages from your IoT hub
1/25/2017 • 1 min to read • Edit on GitHub

What you will do

Run sample code on your host computer to read messages from your IoT hub.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

How to use the gulp tool to read messages from your IoT hub.

What you need

The simulated device sample in Configure and run a simulated device cloud upload sample application.

Get your IoT hub and device connection strings

The device connection string is used by your simulated device to connect to your IoT hub. The IoT hub connection
string is used to connect to the identity registry in your IoT hub to manage the devices that are allowed to connect
to your IoT hub.
List all your IoT hubs in your resource group by running the following command:

az iot hub list -g iot-gateway --query [].name

Use iot-gateway as the value of {resource group name} if you didn't change it.
Get the IoT hub connection string by running the following command:

az iot hub show-connection-string --name {my hub name} -g iot-gateway

{my hub name} is the name that you specified in Lesson 2.

Configure the device connection for the sample code

Update IoT hub and device connection configurations in config-azure.json by performing the following steps:
1. Open config-azure.json in Visual Studio Code by running the following command in a console window:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-azure.json
# For MacOS or Ubuntu
code ~/.iot-hub-getting-started/config-azure.json

2. Make the following replacements in the config-azure.json file:

Replace [IoT hub connection string] with the IoT hub connection string.

Read messages from your IoT hub

Run the simulated device sample application and read IoT Hub messages by the following command:

gulp run --iot-hub

The command runs the application that sends messages to your IoT hub every 2 seconds. It also spawns a child
process to receive the message.
The messages that are being sent and received are all displayed instantly on the same console window in the host
machine. The application will exit in 40 seconds.
Summary
You've successfully run the sample application to send data to your IoT hub with simulated device. You've also
read the messages that have been sent to your IoT hub.

Next steps
Create an Azure function app and Azure Storage account
Create an Azure function app and storage account
1/25/2017 • 1 min to read • Edit on GitHub

Azure Functions is a solution for easily running functions (small pieces of code) in the cloud. An Azure function app
hosts the execution of your functions in Azure.

What you will do

Use an Azure Resource Manager template to create an Azure function app and an Azure storage account. The
Azure function app listens to Azure IoT hub events, processes incoming messages, and writes them to Azure
Table storage.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to use Azure Resource Manager to deploy Azure resources.
How to use an Azure function app to process IoT Hub messages and write them to a table in Azure Table
storage.

What you need

You must have successfully completed the previous lessons:
Lesson 1: Set up your Intel NUC as an IoT gateway
Lesson 2: Get your host computer and Azure IoT hub ready
Lesson 3: Receive messages from the simulated device and read messages from your IoT hub

Open a sample app

Go to your iot-hub-c-intel-nuc-gateway-getting-started repo folder, initialize the configuration files, and then
open the sample project in Visual Studio Code by running the following command:

cd Lesson4
npm install
gulp init
code .
The arm-template.json file is the Azure Resource Manager template that contains an Azure function app and an
Azure storage account.
The arm-template-param.json file is the configuration file used by the Azure Resource Manager template.
The ReceiveDeviceMessages subfolder contains the Node.js code for the Azure function.

Configure Azure Resource Manager templates and create resources in

Azure
Update the arm-template-param.json file in Visual Studio Code.
Replace [your IoT Hub name] with {my hub name} that you specified in Lesson 2.

After you update the arm-template-param.json file, deploy the resources to Azure by running the following
command:

az group deployment create --template-file arm-template.json --parameters @arm-template-param.json -g iot-

gateway

Use iot-gateway as the value of {resource group name} if you didn't change the value in Lesson 2.

Summary
You've created your Azure function app to process IoT hub messages and an Azure storage account to store these
messages. You can now read messages that are sent by your gateway to your IoT hub.

Next steps
Read messages persisted in Azure Storage.
Read messages persisted in Azure Table storage
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Run the gateway sample application on your gateway that sends messages to your IoT hub.
Run sample code on your host computer to read messages in your Azure Table storage.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

How to use the gulp tool to run the sample code to read messages in your Azure Table storage.

What you need

You have have successfully done the following tasks:
Created the Azure function app and the Azure storage account.
Run the gateway sample application.
Read messages from your IoT hub.

Get your Azure storage connection strings

Early in this lesson, you successfully created an Azure storage account. To get the connection string of the Azure
storage account, run the following commands:
List all your storage accounts.

az storage account list -g iot-gateway --query [].name

Get azure storage connection string.

az storage account show-connection-string -g iot-gateway -n {storage name}

Use iot-gateway as the value of {resource group name} if you didn't change the value in Lesson 2.

Configure the device connection

Update the config-azure.json file so that the sample code that runs on the host computer can read message in
your Azure Table storage. To configure the device connection, follow these steps:
1. Open the device configuration file config-azure.json by running the following commands:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-azure.json
# For MacOS or Ubuntu
code ~/.iot-hub-getting-started/config-azure.json
2. Replace [Azure storage connection string] with the Azure storage connection string that you obtained.
[IoT hub connection string] should already be replaced in section Read messages from Azure IoT Hub in
Lesson3.

Read messages in your Azure Table storage

Run the gateway sample application and read Azure Table storage messages by the following command:

gulp run --table-storage

Your IoT hub triggers your Azure Function application to save message into your Azure Table storage when new
message arrives. The gulp run command runs gateway sample application that sends messages to your IoT hub.
With table-storage parameter, it also spawns a child process to receive the saved message in your Azure Table
storage.
The messages that are being sent and received are all displayed instantly on the same console window in the host
machine. The sample application instance will terminate automatically in 40 seconds.
Summary
You've run the sample code to read the messages in your Azure Table storage saved by your Azure Function
application.
Troubleshooting
1/25/2017 • 4 min to read • Edit on GitHub

Hardware issues
TI SensorTag cannot be connected
To troubleshoot SensorTag connectivity issues, use the SensorTag app.
Have an issue with Intel NUC
To troubleshoot boot issues, refer to troubleshooting No Boot Issues on Intel NUC.
To troubleshoot operating system issues, refer to troubleshooting Operating System Issues on Intel NUC.
To troubleshoot other issues, refer to Blink Codes and Beep Codes for Intel NUC.

Node.js package issues

No response during gulp tasks
If you encounter problems in running gulp tasks, you can add the --verbose option for debugging. Try to
terminate current gulp tasks by using Ctrl + C , and then run the following command in your console window
to see debug messages. You might see detailed error messages in your console output.

gulp --verbose

Device discovery issues

For help in troubleshooting common problems with the discover-sensortag command, check the wiki page.
npm issues
Try to update your npm package by running the following command:

npm install -g npm

If the problem still exists, leave your comments at the end of this article or create a GitHub issue in our sample
repository.

Remote Debugging
Below instructions are meant for debugging node.js scripts used in this tutorial.
Run the sample application in debug mode

Run the sample application in debug mode by running the following command:

gulp run --debug

When the debug engine is ready, you should see Debugger listening on port 5858 in the console output.
Configure Visual Studio Code to connect to the remote device
1. Open the Debug panel on the left side.
2. Click the green Start Debugging (F5) button. Visual Studio Code opens a launch.json file.
3. Update the launch.json file with the following content. Replace [device hostname or IP address] with
the actual device IP address or host name.

{
"version": "0.2.0",
"configurations": [
{
"name": "Attach",
"type": "node",
"request": "attach",
"port": 5858,
"address": "[device hostname or IP address]",
"restart": false,
"sourceMaps": false,
"outDir": null,
"localRoot": "${workspaceRoot}",
"remoteRoot": "~/ble_sample"
}
]
}

Attach to the remote application

Click the green Start Debugging (F5) button to start debugging.
Read JavaScript in VS Code to learn more about the debugger.
Azure CLI issues
The Azure command-line interface (Azure CLI) is a preview build. To seek solutions, you can use the Preview
Install Guide.
If you encounter any bugs with the tool, file an issue in the Issues section of the GitHub repo.
For help in troubleshooting common problems, check the readme.
If you meet "Could not find a version that satisfies the requirement", please run the following command to
upgrade pip to lastest version.

python -m pip install --upgrade pip

Python installation issues

Legacy installation issues (macOS )
When you're installing pip, a permission error is thrown when older packages are installed with su permissions.
This situation occurs because a previous installation of Python using brew (macOS) is not uninstalled
completely. Some pip packages from a previous installation were created by root, which causes the permission
error. The solution is to remove those packages installed by root. Use the following steps to complete this task:
1. Go to /usr/local/lib/python2.7/site-packages
2. List packages created by root: ls -l | grep root
3. Uninstall packages from step 2: sudo rm -rf {package name}
4. Reinstall Python.
Azure IoT Hub issues
If you've successfully provisioned your Azure IoT hub with the Azure CLI, and you need a tool to manage the
devices that are connecting to your IoT hub, try the following tools.
Device Explorer
Device Explorer runs on your Windows local machine and connects to your IoT hub in Azure. It communicates
with the following IoT Hub endpoints:
Device identity management to provision and manage devices registered with your IoT hub.
Receive device-to-cloud so you can monitor messages sent from your device to your IoT hub.
Send cloud-to-device so you can send messages to your devices from your IoT hub.
Configure your IoT hub connection string within this tool to use all its capabilities.
iothub-explorer
iothub-explorer is a sample multiplatform CLI tool to manage device clients. You can use the tool to manage the
devices in the identity registry, monitor device-to-cloud messages, and send cloud-to-device commands.
To install the latest (prerelease) version of the iothub-explorer tool, run the following command:

npm install -g iothub-explorer@latest

To get additional help about all the iothub-explorer commands and their parameters, run the following
command:

iothub-explorer help

The Azure portal

A full CLI experience helps you create and manage all your Azure resources. You might also want to use the
Azure portal to help provision, manage, and debug your Azure resources.

Azure Storage issues

Microsoft Azure Storage Explorer (preview) is a standalone app from Microsoft that you can use to work with
Azure Storage data on Windows, macOS, and Linux. By using this tool, you can connect to your table and see the
data in it. You can use this tool to troubleshoot your Azure Storage issues.
Get started with IoT Gateway Starter Kit with a
SensorTag
1/25/2017 • 2 min to read • Edit on GitHub

In this tutorial, you begin by learning the basics of working with IoT Gateway Starter Kit. You will be working with
Intel NUC that's running Wind River Linux and the TI SensorTag. You will learn how to seamleesly connect your
devices to the cloud by using Azure IoT Hub.

Don't have a kit yet?: Click here. Don't have a SensorTag?: Start with a simulated device or buy a SensorTag

Lesson 1: Configure your NUC

In this lesson, you set up Intel NUC (Next Unit of Computing) in the Kit as an Azure IoT gateway, install the Azure
IoT Gateway SDK package on NUC, and run a sample app to verify the gateway functionality.
Estimated time to complete: 15 minutes
Go to Set up Intel NUC as an IoT gateway

Lesson 2: Create your IoT Hub

In this lesson, you install the tools and software on your host computer. Then you create your free Azure account,
provision your Azure IoT hub and create your first device in the IoT hub.
Complete Lesson 1 before you start this lesson.
Get the tools
Install the tools and software on your host computer.
Estimated time to complete: 20 minutes
Go to Get the tools
Create an IoT hub and register your device
Create your resource group, provision your first Azure IoT hub, and add your first device to the IoT hub using the
Azure CLI.
Estimated time to complete: 10 minutes
Go to Create an IoT hub and register your device

Lesson 3: Receive messages from SensorTag and read messages from

your IoT hub
In this lesson, you will use scripts to automate the configuration and execution of a BLE sample application in your
gateway. Such applications use a collection of modules to aggregate and transform data, process commands, or
perform any number of related tasks. Modules communicate with one another via a message broker. The sample
application has a BLE module and an IoT hub module. The BLE module receives data from BLE SensorTag. The IoT
hub module packages the data received and sends it to your IoT hub through the gateway framework provided in
the Azure IoT Gateway SDK.

Configure and run the BLE sample app

Set up the connectivity between SensorTag and your gateway. Then finish the configuration and run the BLE
sample application.
Estimated time to complete: 15 minutes
Go to Configure and run the BLE sample app
Read messages from your IoT hub
Run sample code on your host computer to read messages from your IoT hub.
Estimated time to complete: 15 minutes
Go to Read messages from your IoT hub

Lesson 4: Save messages to Azure Table storage

Create an Azure function app that gets incoming messages from your IoT hub and writes them to Azure Table
storage.
Create an Azure function app and Azure Storage account
Use an Azure Resource Manager template to create an Azure function app and an Azure Storage account.
Estimated time to complete: 10 minutes
Go to Create an Azure function app and Azure Storage account
Read messages persisted in Azure Table storage
Monitor the gateway-to-cloud messages as they are written to Azure Table storage.
Estimated time to complete: 5 minutes
Go to Read messages persisted in Azure Table storage.

Troubleshooting
If you have any problems during the lessons, look for solutions in the Troubleshooting article.

Explore more
Visit the Intel IoT Gateway Kit developer zone to learn more.
Set up Intel NUC as an IoT gateway
1/25/2017 • 3 min to read • Edit on GitHub

What you will do

Set up Intel NUC as an IoT gateway.
Install the Azure IoT Gateway SDK package on Intel NUC.
Run a "hello_world" sample application on Intel NUC to verify the gateway functionality. If you have any
problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to connect Intel NUC with peripherals.
How to install and update the required packages on Intel NUC using the Smart Package Manager.
How to run the "hello_world" sample application to verify the gateway functionality.

What you need

An Intel NUC Kit DE3815TYKE with the Intel IoT Gateway Software Suite (Wind River Linux *7.0.0.13)
preinstalled.
An Ethernet cable.
A keyboard.
An HDMI or VGA cable.
A monitor with an HDMI or VGA port.

Connect Intel NUC with the peripherals

The image below is an example of Intel NUC that is connected with various peripherals:
1. Connected to a keyboard.
2. Connected to the monitor by a VGA cable or HDMI cable.
3. Connected to a wired network by an Ethernet cable.
4. Connected to the power supply with a power cable.

Connect to the Intel NUC system from host computer via Secure Shell
(SSH)
Here you need keyboard and monitor to get the IP address of your NUC device. If you already know the IP address,
you can skip to step 3 in this section.
1. Turn on Intel NUC by pressing the Power button and log in the system.
The default user name and password are both root .
2. Get the IP address of NUC by running the ifconfig command. This step is done on the NUC device.
Here is an example of the command output.

In this example, the value that follows inet addr: is the IP address that you need when you plan to connect
remotely from a host computer to Intel NUC.
3. Use one of the following SSH clients from your host machine to connect to Intel NUC.
PuTTY for Windows.
The build-in SSH client on Ubuntu or macOS.
It is more efficient and productive to operate on Intel NUC from a host computer. You need the the IP
address, user name and password to connect the NUC via SSH client. Here is the example use SSH client on
macOS.

Install the Azure IoT Gateway SDK package

The Azure IoT Gateway SDK package contains the pre-compiled binaries of the SDK and its dependencies. These
binaries are the Azure IoT Gateway SDK, the Azure IoT SDK and the corresponding tools. The package also contains
a "hello_world" sample application is used to validate the gateway functionality. The SDK is the core part of the
gateway. To install the package, follow these steps:
1. Add the IoT cloud repository by running the following commands in a terminal window:

rpm --import http://iotdk.intel.com/misc/iot_pub.key

smart channel --add IoT_Cloud type=rpm-md name="IoT_Cloud" baseurl=http://iotdk.intel.com/repos/iot-
cloud/wrlinux7/rcpl13/ -y

The rpm command imports the rpm key. The smart channel command adds the rpm channel to the Smart
Package Manager. Before you run the smart update command, you see an output like below.
smart update

2. Install the package by running the following command:

smart install packagegroup-cloud-azure -y

packagegroup-cloud-azure is the name of the package. The smart install command is used to install the
package.
After the package is installed, Intel NUC is expected to work as a gateway.

Run the Azure IoT Gateway SDK "hello_world" sample application

Go to azureiotgatewaysdk/samples and run the sample "hello_world" sample application. This sample application
creates a gateway from the hello_world.json file and uses the fundamental components of the Azure IoT Gateway
SDK architecture to log a hello world message to a file every 5 seconds.
You can run the sample "hello_world" sample application by running the following command:

cd /usr/share/azureiotgatewaysdk/samples/hello_world/
./hello_world hello_world.json

The sample application produces the following output if the gateway functionality is working correctly:

If you have any problems, look for solutions on the troubleshooting page.

Summary
Congratulations! You've finished setting up Intel NUC as a gateway. Now you're ready to move on to the next
lesson to set up your host computer, create an Azure IoT hub and register your Azure IoT hub logical device.

Next steps
Get your host computer and Azure IoT hub ready
Get the tools (Windows 7 and later)
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Install Git, Node.js, Gulp, Python.
Install the Azure command-line interface (Azure CLI).
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this lesson is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.
How to install Visual Studio Code.
Visual Studio Code is a cross platform, lightweight but powerful source code editor for Windows, Linux,
and macOS. It has great support for debugging, embedded Git control, syntax highlighting, intelligent
code completion, snippets, and code refactoring as well.
How to install Python.
Python is a widely used high-level, general-purpose, interpreted and dynamic programming language.
How to install the Azure CLI.
The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from a
command line to provision and manage resources.
How to use the Azure CLI to create an IoT hub.

What you need

An Internet connection to download the tools and software.
A Windows computer.

Install Git and Node.js

Click the following links to download and install Git and Node.js LTS for Windows.
Get Git for Windows
Get Node.js LTS for Windows

Install Node.js development tools

You use gulp.js to automate deployment and execution of scripts.
Press Windows + R , type cmd and press Enter to open a Command Prompt window, and then run the following
command:

npm install -g gulp

If you experience issues with the installation, see the troubleshooting guide for solutions to common problems.

NOTE
Node, NPM and Gulp are required to run automation scripts developed in Node.js.

Install Python
You can choose from Python 2.7, 3.4 or 3.5. In this tutorial, we use Python 2.7. If you've already installed python,
go to the next section.
Get Python for Windows
You also need to add the path of the folders where Python.exe and pip.exe are installed to the system PATH
environment variable. By default, python.exe is installed in C:\Python27 and pip.exe is installed in
C:\Python27\Scripts .

Install the Azure CLI

To install the Azure CLI, follow these steps:
1. Open a Command Prompt window as an administrator.
2. Install the Azure CLI by running the following commands:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

The installation might take 5 minutes.

3. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Install Visual Studio Code
You use Visual Studio Code later in the tutorial to edit configuration files.
Download and install Visual Studio Code.

Summary
You've installed all the required tools and software on your host computer. Your next task is to use the Azure CLI
to create an IoT hub and register your device in your IoT hub.

Next steps
Create an IoT hub and register your device
Get the tools (Ubuntu 16.04)
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Install Git, Node.js, Gulp, Python.
Install the Azure command-line interface (Azure CLI).
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this lesson is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.
How to install Visual Studio Code.
Visual Studio Code is a cross platform, lightweight but powerful source code editor for Windows, Linux,
and macOS. It has great support for debugging, embedded Git control, syntax highlighting, intelligent
code completion, snippets, and code refactoring as well.
How to install the Azure CLI
The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from a
command line to provision and manage resources.
How to use the Azure CLI to create an IoT hub.

What you need

An Internet connection to download the tools and software.
A computer that is running Ubuntu 16.04 or later.

Install Git and Node.js

To install Git and Node.js, follow these steps:
1. Press Ctrl + Alt + T to open a terminal.
2. Run the following commands:

sudo apt-get update

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install git

Install Node.js development tools

You use gulp.js to automate deployment and execution of scripts.
To install gulp, run the following command in the terminal:

sudo npm install -g gulp

If you experience issues with the installation, see the troubleshooting guide for solutions to common problems.

NOTE
Node, NPM and Gulp are required to run automation scripts developed in Node.js.

Install the Azure CLI

To install the Azure CLI, follow these steps:
1. Run the following commands in the terminal:

sudo apt-get update

sudo apt-get install -y libssl-dev libffi-dev
sudo apt-get install -y python-dev
sudo apt-get install -y build-essential
sudo apt-get install -y python-pip
sudo pip install --upgrade azure-cli
sudo pip install --upgrade azure-cli-iot

The installation might take 5 minutes.

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Install Visual Studio Code

You use Visual Studio Code later in the tutorial to edit configuration files.
Download and install Visual Studio Code.
Summary
You've installed all the required tools and software on your host computer. Your next task is to use the Azure CLI to
create an IoT hub and register your device in your IoT hub.

Next steps
Create an IoT hub and register your device
Get the tools (MacOS)
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Install Git, Node.js, Gulp, Python.
Install the Azure command-line interface (Azure CLI).
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to install Git and Node.js.
Git is an open source distributed version control system. The sample application for this lesson is stored
on Git.
Node.js is a JavaScript runtime with a rich package ecosystem.
How to use NPM to install Node.js development tools.
The minimum required version of Node.js is 4.5 LTS.
NPM is one of the package managers for Node.js.
How to install Visual Studio Code.
Visual Studio Code is a cross platform, lightweight but powerful source code editor for Windows, Linux,
and macOS. It has great support for debugging, embedded Git control, syntax highlighting, intelligent
code completion, snippets, and code refactoring as well.
How to install Python.
Python is a widely used high-level, general-purpose, interpreted and dynamic programming language.
How to install the Azure CLI.
The Azure CLI provides a multiplatform command-line experience for Azure. You work directly from a
command line to provision and manage resources.
How to use the Azure CLI to create an IoT hub.

What you need

An Internet connection to download the tools and software.
A Mac computer that’s running OS X Yosemite (10.10) or later.

Install Git and Node.js

To install Git and Node.js, use the Homebrew package management utility by following these steps:
1. Download and install Homebrew. If you’ve already installed Homebrew, go to step 2.
a. Press Cmd + Space and enter Terminal to open a terminal.
b. Run the following command:

/usr/bin/ruby -e "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"
2. Install Git and Node.js by running the following command:

brew install node git

Install Node.js development tools

You use gulp.js to automate deployment and execution of scripts.
To install gulp, run the following command in the terminal:

npm install -g gulp

If you experience issues with the installation, see the troubleshooting guide for solutions to common problems.

NOTE
Node, NPM and Gulp are required to run automation scripts developed in Node.js.

Install Python
Although Mac OS X comes with Python 2.7, we recommend that you install Python through Homebrew. See
Installing Python on Mac OS X.
Install Python and pip by running the following command:

brew install python

Install the Azure CLI

To install the Azure CLI, follow these steps:
1. Run the following commands in the terminal:

pip install --upgrade azure-cli

pip install --upgrade azure-cli-iot

The installation might take 5 minutes.

2. Verify the installation by running the following command:

az iot -h

You should see the following output if the installation is successful.

Install Visual Studio Code
You use Visual Studio Code later in the tutorial to edit configuration files.
Download and install Visual Studio Code.

Summary
You’ve installed all the required tools and software on your Mac computer. Your next task is to use the Azure CLI to
create an IoT hub and register your device in your IoT hub.

Next steps
Create an IoT hub and register Device
Create your Azure IoT hub and register your device
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Create a resource group
Create your first IoT hub
Register your device in your IoT hub by using the Azure CLI.
When you register your device in your IoT hub, the Azure IoT Hub service generates a key for your device to use to
authenticate with the service.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to use the Azure CLI to create an IoT hub.
How to register a device in an IoT hub.

What you need

An active Azure subscription. If you don't have an Azure account, you can create a free Azure trial account in
just a few minutes.
You should have the Azure CLI installed.

Create an IoT hub

To create an IoT hub, follow these steps:
1. Sign in to your Azure account by running the following command:

az login

All your available subscriptions will be listed after a successful sign-in.

2. Set the default Azure subscription that you want to use by running the following command:

az account set --subscription {subscription id or name}

subscription ID or name can be found in the output of the az login or the az account list command.
3. Register the provider by running the following command. Resource providers are services that provide
resources for your application. You must register the provider before you can deploy the Azure resource
that the provider offers.

az provider register -n "Microsoft.Devices"

4. Create a resource group named iot-gateway in the West US region by running the following command:
az group create --name iot-gateway --location westus

westus is the location you create your resource group. If you want to use another location, you can run
az account list-locations -o table to see all the locations Azure supports.

5. Create an IoT hub in the iot-gateway resource group by running the following command:

az iot hub create --name {my hub name} --resource-group iot-gateway

By default, the tool creates an IoT Hub in the Free pricing tier. For more infomation, see Azure IoT Hub pricing.

NOTE
The name of your IoT hub must be globally unique. You can create only one F1 edition of Azure Iot Hub under your Azure
subscription.

Register your device in your IoT hub

Each device that sends messages to your IoT hub and receives messages from your IoT hub must be registered
with a unique ID. Register your device in your IoT hub by running following command:

az iot device create --device-id mydevice --hub-name {my hub name} --resource-group iot-gateway

Summary
You've created an IoT hub and registered your logical device with a device identity in your IoT hub. You're ready to
learn how to configure and run a gateway sample application to send data from your physical device to your IoT
hub in the cloud.

Next steps
Configure and run a BLE sample app
Configure and run a BLE sample application
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Clone the sample repository.
Set up the connectivity between SensorTag and Intel NUC.
Use the Azure CLI to get your IoT hub and SensorTag information for a BLE(Bluetooth Low Energy) sample
application. And configure and run the BLE sample application.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this article, you will learn:
How to configure and run the BLE sample application.

What you need

You must have successfully completed
Create an IoT hub and register SensorTag

Clone the sample repository to the host computer

To clone the sample repository, follow these steps on the host computer:
1. Open a Command Prompt window in Windows or open a terminal in macOS or Ubuntu.
2. Run the following commands:

git clone https://github.com/Azure-samples/iot-hub-c-intel-nuc-gateway-getting-started

cd iot-hub-c-intel-nuc-gateway-getting-started

Set up the connectivity between SensorTag and Intel NUC

To set up the connectivity, follow these steps on the host computer:
1. Initialize the configuration file by running the following commands:

cd Lesson3
npm install
gulp init

2. Open config-gateway.json in Visual Studio Code by running the following command:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-gateway.json
# For macOS or Ubuntu
code ~/.iot-hub-getting-started/config-gateway.json
3. Locate the following line of code and replace [device hostname or IP address] with the IP address or host
name of Intel NUC.

4. Install helper tools on Intel NUC by running the following command:

gulp install-tools

5. Turn on SensorTag by pressing the power button as the following picture, and the green LED should blink.
6. Scan SensorTag devices by running the following commands:

gulp discover-sensortag

7. Test the connectivity between the SensorTag and Intel NUC by running the following command:

gulp test-connectivity --mac {mac address}

Replace {mac address} with the MAC address that you obtained in the previous step.

Get the connection string of SensorTag

To get the Azure IoT hub connection string of SensorTag, run the following command on the host computer:

az iot device show-connection-string --hub-name {IoT hub name} --device-id mydevice --resource-group iot-
gateway

{IoT hub name} is the IoT hub name that you used. Use iot-gateway as the value of {resource group name} and use
mydevice as the value of {device id} if you didn't change the value in Lesson 2.

Configure the BLE sample application

To configure and run the BLE sample application, follow these steps on the host computer:
1. Open config-sensortag.json in Visual Studio Code by running the following command:
# For Windows command prompt
code %USERPROFILE%\.iot-hub-getting-started\config-sensortag.json
# For macOS or Ubuntu
code ~/.iot-hub-getting-started/config-sensortag.json

2. Make the following replacements in the code:

Replace [IoT hub name] with the IoT hub name that you used.
Replace [IoT device connection string] with the connection string of SensorTag that you obtained.
Replace [device_mac_address] with the MAC address of the SensorTag that you obtained.
3. Run the BLE sample application.
To run the BLE sample application, follow these steps on the host computer:
a. Turn on SensorTag.
b. Deploy and run the BLE sample application on Intel NUC by running the following command:

gulp run

Verify that the BLE sample application works

You should now see an output like the following:
The sample application keeps collecting temperature data and sent it to your IoT hub. The sample application
terminates automatically after sending 40 seconds.

Summary
You've successfully set up the connectivity between SensorTag and Intel NUC, and run a BLE sample application
which collects and sends data from SensorTag to your IoT hub. You're ready to learn how to verify that your IoT
hub has received the data.

Next steps
Read messages from your IoT hub
Read messages from your IoT hub
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Run sample code on your host computer to read messages from your IoT hub.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

How to use the gulp tool to read messages from your IoT hub.

What you need

The BLE sample application that you ran successfully in Lesson 3.

Get your IoT hub and device connection strings

The device connection string is used by your device (TI SensorTag or simulated device) to connect to your IoT hub.
The IoT hub connection string is used to connect to the identity registry in your IoT hub to manage the devices that
are allowed to connect to your IoT hub.
List all your IoT hubs in your resource group by running the following command:

az iot hub list -g iot-gateway --query [].name

Use iot-gateway as the value of {resource group name} if you didn't change the value.
Get the IoT hub connection string by running the following command:

az iot hub show-connection-string --name {my hub name} -g iot-gateway

{my hub name} is the name that you specified in Lesson 2.

Configure the device connection for the sample code

Update the device configuration file config-azure.json so that you can read messages from your IoT hub on your
host computer. To do this, follow these steps:
1. Open config-azure.json in Visual Studio Code by running the following command in a console window:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-azure.json
# For MacOS or Ubuntu
code ~/.iot-hub-getting-started/config-azure.json

2. Make the following replacements in the config-azure.json file:

Replace [IoT hub connection string] with the IoT hub connection string that you obtained.

Read messages from your IoT hub

If you have a TI SensorTag, make sure you have already powered on your SensorTag. Run the gateway sample
application and read IoT Hub messages by the following command:

gulp run --iot-hub

The command runs the BLE sample application that reads and packages temperature data from your SensorTag or
simulated device and sends the message to your IoT hub every 2 seconds. It also spawns a child process to receive
the message.
The messages that are being sent and received are all displayed instantly on the same console window in the host
machine. The sample application instance will terminate automatically in 40 seconds.
Summary
You've run a sample code to read messages from your IoT hub. You're ready to read the messages that are stored
in your Azure table storage.

Next steps
Create an Azure function app and Azure Storage account
Create an Azure function app and storage account
1/25/2017 • 1 min to read • Edit on GitHub

Azure Functions is a solution for easily running functions (small pieces of code) in the cloud. An Azure function app
hosts the execution of your functions in Azure.

What you will do

Use an Azure Resource Manager template to create an Azure function app and an Azure storage account. The
Azure function app listens to Azure IoT hub events, processes incoming messages, and writes them to Azure
Table storage.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

In this lesson, you will learn:
How to use Azure Resource Manager to deploy Azure resources.
How to use an Azure function app to process IoT Hub messages and write them to a table in Azure Table
storage.

What you need

You must have successfully completed the previous lessons:
Lesson 1: Set up your Intel NUC as an IoT gateway
Lesson 2: Get your host computer and Azure IoT hub ready
Lesson 3: Receive messages from SensorTag and read messages from IoT hub

Open a sample app

Go to your iot-hub-c-intel-nuc-gateway-getting-started repo folder, initialize the configuration files, and then
open the sample project in Visual Studio Code by running the following command:

cd Lesson4
npm install
gulp init
code .
The arm-template.json file is the Azure Resource Manager template that contains an Azure function app and an
Azure storage account.
The arm-template-param.json file is the configuration file used by the Azure Resource Manager template.
The ReceiveDeviceMessages subfolder contains the Node.js code for the Azure function.

Configure Azure Resource Manager templates and create resources in

Azure
Update the arm-template-param.json file in Visual Studio Code.
Replace [your IoT Hub name] with {my hub name} that you specified in Lesson 2.

After you update the arm-template-param.json file, deploy the resources to Azure by running the following
command:

az group deployment create --template-file arm-template.json --parameters @arm-template-param.json -g iot-

gateway

Use iot-gateway as the value of {resource group name} if you didn't change the value in Lesson 2.

Summary
You've created your Azure function app to process IoT hub messages and an Azure storage account to store these
messages. You can now read messages that are sent by your gateway to your IoT hub.

Next steps
Read messages persisted in Azure Storage.
Read messages persisted in Azure Table storage
1/25/2017 • 2 min to read • Edit on GitHub

What you will do

Run the gateway sample application on your gateway that sends messages to your IoT hub.
Then run a sample code on your host computer to read the messages in your Azure Table storage.
If you have any problems, look for solutions on the troubleshooting page.

What you will learn

How to use the gulp tool to run the sample code to read messages in your Azure Table storage.

What you need

You have have successfully done the following tasks:
Created the Azure function app and the Azure storage account.
Run the gateway sample application.
Read messages from your IoT hub.

Get your Azure storage connection strings

Early in this lesson, you successfully created an Azure storage account. To get the connection string of the Azure
storage account, run the following commands:
List all your storage accounts.

az storage account list -g iot-gateway --query [].name

Get azure storage connection string.

az storage account show-connection-string -g iot-gateway -n {storage name}

Use iot-gateway as the value of {resource group name} if you didn't change the value in Lesson 2.

Configure the device connection

Update the config-azure.json file so that the sample code that runs on the host computer can read message in
your Azure Table storage. To configure the device connection, follow these steps:
1. Open the device configuration file config-azure.json by running the following commands:

# For Windows command prompt

code %USERPROFILE%\.iot-hub-getting-started\config-azure.json
# For MacOS or Ubuntu
code ~/.iot-hub-getting-started/config-azure.json
2. Replace [Azure storage connection string] with the Azure storage connection string that you obtained.
[IoT hub connection string] should already be replaced in section Read messages from Azure IoT Hub in
Lesson3.

Read messages in your Azure Table storage

Run the gateway sample application and read Azure Table storage messages by the following command:

gulp run --table-storage

Your IoT hub triggers your Azure Function application to save message into your Azure Table storage when new
message arrives. The gulp run command runs gateway sample application that sends messages to your IoT hub.
With table-storage parameter, it also spawns a child process to receive the saved message in your Azure Table
storage.
The messages that are being sent and received are all displayed instantly on the same console window in the host
machine. The sample application instance will terminate automatically in 40 seconds.
Summary
You've run the sample code to read the messages in your Azure Table storage saved by your Azure Function
application.
Troubleshooting
1/25/2017 • 4 min to read • Edit on GitHub

Hardware issues
TI SensorTag cannot be connected
To troubleshoot SensorTag connectivity issues, use the SensorTag app.
Have an issue with Intel NUC
To troubleshoot boot issues, refer to troubleshooting No Boot Issues on Intel NUC.
To troubleshoot operating system issues, refer to troubleshooting Operating System Issues on Intel NUC.
To troubleshoot other issues, refer to Blink Codes and Beep Codes for Intel NUC.

Node.js package issues

No response during gulp tasks
If you encounter problems in running gulp tasks, you can add the --verbose option for debugging. Try to
terminate current gulp tasks by using Ctrl + C , and then run the following command in your console window
to see debug messages. You might see detailed error messages in your console output.

gulp --verbose

Device discovery issues

For help in troubleshooting common problems with the discover-sensortag command, check the wiki page.
npm issues
Try to update your npm package by running the following command:

npm install -g npm

If the problem still exists, leave your comments at the end of this article or create a GitHub issue in our sample
repository.

Remote Debugging
Below instructions are meant for debugging node.js scripts used in this tutorial.
Run the sample application in debug mode

Run the sample application in debug mode by running the following command:

gulp run --debug

When the debug engine is ready, you should see Debugger listening on port 5858 in the console output.
Configure Visual Studio Code to connect to the remote device
1. Open the Debug panel on the left side.
2. Click the green Start Debugging (F5) button. Visual Studio Code opens a launch.json file.
3. Update the launch.json file with the following content. Replace [device hostname or IP address] with
the actual device IP address or host name.

{
"version": "0.2.0",
"configurations": [
{
"name": "Attach",
"type": "node",
"request": "attach",
"port": 5858,
"address": "[device hostname or IP address]",
"restart": false,
"sourceMaps": false,
"outDir": null,
"localRoot": "${workspaceRoot}",
"remoteRoot": "~/ble_sample"
}
]
}

Attach to the remote application

Click the green Start Debugging (F5) button to start debugging.
Read JavaScript in VS Code to learn more about the debugger.
Azure CLI issues
The Azure command-line interface (Azure CLI) is a preview build. To seek solutions, you can use the Preview
Install Guide.
If you encounter any bugs with the tool, file an issue in the Issues section of the GitHub repo.
For help in troubleshooting common problems, check the readme.
If you meet "Could not find a version that satisfies the requirement", please run the following command to
upgrade pip to lastest version.

python -m pip install --upgrade pip

Python installation issues

Legacy installation issues (macOS )
When you're installing pip, a permission error is thrown when older packages are installed with su permissions.
This situation occurs because a previous installation of Python using brew (macOS) is not uninstalled
completely. Some pip packages from a previous installation were created by root, which causes the permission
error. The solution is to remove those packages installed by root. Use the following steps to complete this task:
1. Go to /usr/local/lib/python2.7/site-packages
2. List packages created by root: ls -l | grep root
3. Uninstall packages from step 2: sudo rm -rf {package name}
4. Reinstall Python.
Azure IoT Hub issues
If you've successfully provisioned your Azure IoT hub with the Azure CLI, and you need a tool to manage the
devices that are connecting to your IoT hub, try the following tools.
Device Explorer
Device Explorer runs on your Windows local machine and connects to your IoT hub in Azure. It communicates
with the following IoT Hub endpoints:
Device identity management to provision and manage devices registered with your IoT hub.
Receive device-to-cloud so you can monitor messages sent from your device to your IoT hub.
Send cloud-to-device so you can send messages to your devices from your IoT hub.
Configure your IoT hub connection string within this tool to use all its capabilities.
iothub-explorer
iothub-explorer is a sample multiplatform CLI tool to manage device clients. You can use the tool to manage the
devices in the identity registry, monitor device-to-cloud messages, and send cloud-to-device commands.
To install the latest (prerelease) version of the iothub-explorer tool, run the following command:

npm install -g iothub-explorer@latest

To get additional help about all the iothub-explorer commands and their parameters, run the following
command:

iothub-explorer help

The Azure portal

A full CLI experience helps you create and manage all your Azure resources. You might also want to use the
Azure portal to help provision, manage, and debug your Azure resources.

Azure Storage issues

Microsoft Azure Storage Explorer (preview) is a standalone app from Microsoft that you can use to work with
Azure Storage data on Windows, macOS, and Linux. By using this tool, you can connect to your table and see
the data in it. You can use this tool to troubleshoot your Azure Storage issues.
Azure IoT device SDK for C
2/13/2017 • 17 min to read • Edit on GitHub

The Azure IoT device SDK is a set of libraries designed to simplify the process of sending events and receiving
messages from the Azure IoT Hub service. There are different variations of the SDK, each targeting a specific
platform, but this article describes the Azure IoT device SDK for C.
The Azure IoT device SDK for C is written in ANSI C (C99) to maximize portability. This makes it well-suited to
operate on a number of platforms and devices, especially where minimizing disk and memory footprint is a
priority.
There are a broad range of platforms on which the SDK has been tested (see the Azure Certified for IoT device
catalog for details). Although this article includes walkthroughs of sample code running on the Windows platform,
keep in mind that the code described in this article is exactly the same across the range of supported platforms.
In this article you'll be introduced to the architecture of the Azure IoT device SDK for C. We'll demonstrate how to
initialize the device library, send events to IoT Hub as well as receive messages from it. The information in this
article should be enough to get started using the SDK, but also provides pointers to additional information about
the libraries.

SDK architecture
You can find the Azure IoT device SDK for C GitHub repository and view details of the API in the C API reference.
The latest version of the libraries can be found in the master branch of this repository:
This repository contains the entire family of Azure IoT device SDKs. However, this article is about the Azure IoT
device SDK for C which can be found in the c folder.

The core implementation of the SDK can be found in the iothub_client folder which contains the
implementation of the lowest API layer in the SDK: the IoTHubClient library. The IoTHubClient library
contains APIs implementing raw messaging for sending messages to IoT Hub as well as receiving messages
from it. When using this library, you are responsible for implementing message serialization (eventually using
the serializer sample described below), but other details of communicating with IoT Hub are handled for you.
The serializer folder contains helper functions and samples showing how to serialize data before sending to
Azure IoT Hub using the client library. Note that the use of the serializer is not mandatory and only provided as
a convenience. If you use the serializer library, you start by defining a model that specifies the events you
want to send to IoT Hub as well as the messages you expect to receive from it. Once the model is defined, the
SDK provides you an API surface that enables you to easily work with events and messages without having to
worry about serialization details. The library depends on other open source libraries that implement transport
using several protocols (MQTT, AMQP).
The IoTHubClient library depends on other open source libraries:
The Azure C shared utility library which provides common functionality for basic tasks (like string, list
manipulation, IO, etc. ...) needed across several Azure-related C SDKs
The Azure uAMQP library which is client side implementation of AMQP optimized for resource
constraint devices.
The Azure uMQTT library which is a general-purpose library implementing the MQTT protocol and
optimized for resource constraint devices.
All of this is easier to understand by looking at example code. The following sections walk you through a couple of
the sample applications that are included in the SDK. This should give you a good feel for the various capabilities
of the architectural layers of the SDK as well as an introduction to how the APIs work.

Before running the samples

Before you can run the samples in the Azure IoT device SDK for C you must create an instance of the service on
your Azure subscription if you don't already have one and complete 2 tasks:
prepare your development environment
obtain device credentials.
If you need to create an instance of Azure IoT Hub on your Azure subscription, follow the instructions here.
The readme file included with the SDK provides instructions for preparing your development environment and
obtain device credentials. The following sections include some additional commentary on those instructions.
Preparing your development environment
While packages are provided for some platforms (such as NuGet for Windows or apt_get for Debian and Ubuntu)
and the samples use these packages when available, the below instructions detail how to build the library and the
samples directly form the code.
First, you'll need to obtain a copy of the SDK from GitHub and then build the source. You should get a copy of the
source from the master branch of the GitHub repository.
When you’ve downloaded a copy of the source, you must complete the steps described in the SDK article "Prepare
your development environment".
The following are a few tips to help you complete the procedure described in the preparation guide:
When you install the CMake utility, choose the option to add CMake to the system PATH for all users
(adding to the current user works as well):

Before you open the Developer Command Prompt for VS2015, install the Git command-line tools. To
install these tools, complete the following steps:
1. Launch the Microsoft Visual Studio 2015 setup program (or chose Microsoft Visual Studio 2015
from the Programs and Features control panel and select Change).
2. Make sure the Git for Windows feature is selected in the installer but you may also want to check
the GitHub Extension for Visual Studio option to provide IDE integration:
3. Complete the setup wizard to install the tools.
4. Add the Git tools bin directory to the system PATH environment variable. On Windows, this looks
like the following:

When you have completed all the steps described in the "Prepare your development environment" page, you're
ready to compile the sample applications.
Obtaining device credentials
Now that your development environment is set up, the next thing to do is to get a set of device credentials. For a
device to be able to access an IoT hub, you must first add the device to the IoT Hub identity registry. When you
add your device you'll get a set of device credentials which you'll need in order for the device to be able to
connect to an IoT hub. The sample applications that we’ll look at in the next section expect these credentials in the
form of a device connection string.
There are a couple tools provided in the SDK open source repository to help managing the IoT Hub. One is a
Windows application called device explorer, the second one is a node.js based cross platform CLI tool called
iothub-explorer. You can learn more about these tools here.
As we are going through running the samples on Windows in this article, we are using the device explorer tool.
But you can also use iothub-explorer if you prefer CLI tools.
The device explorer tool uses the Azure IoT service libraries to perform various functions on IoT Hub, including
adding devices. If you use the device explorer tool to add a device, you’ll get a corresponding connection string.
You need this connection string to make the sample applications run.
In case you're not already familiar with the process, the following procedure describes how to use the device
explorer tool to add a device and obtain a device connection string.
You can find a Windows installer for the device explorer tool on the SDK release page. But you can also run the
tool directly from its code opening DeviceExplorer.sln in Microsoft Visual Studio 2015 and building the
solution.
When you run the program you’ll see this interface:

Enter your IoT Hub Connection String in the first field and click Update. This configures the tool so that it can
communicate with IoT Hub.
Once the IoT Hub connection string is configured click the Management tab:
This is where you’ll manage the devices registered in your IoT hub.
You can create a device by clicking the Create button. A dialog is displayed with a set of pre-populated keys
(primary and secondary). All you have to do is enter a Device ID and then click Create.

Once the device is created, the Devices list is updated with all registered devices, including the one you just
created. If you right-click your new device, you’ll see this menu:
If you choose the Copy connection string for selected device option, the device connection string is copied to
the clipboard. Keep a copy of the device connection string. You’ll need it when running the sample applications
described in the next sections.
Once you've completed the steps above, you're ready to start running some code. Both samples have a constant
at the top of the main source file that enables you to enter a connection string. For example, the corresponding
line from the iothub_client_sample_amqp application appears as follows.

static const char* connectionString = "[device connection string]";

If you want to follow along, enter your device connection string here, recompile the solution, and you'll be able to
run the sample.

IoTHubClient
Within the iothub_client folder in the azure-iot-sdk-c repository, there is a samples folder that contains an
application called iothub_client_sample_amqp.
The Windows version of the iothub_client_sample_ampq application includes the following Visual Studio
solution:

This solution contains a single project. It is worth noting that there are four NuGet packages installed in this
solution:
Microsoft.Azure.C.SharedUtility
Microsoft.Azure.IoTHub.AmqpTransport
Microsoft.Azure.IoTHub.IoTHubClient
Microsoft.Azure.uamqp
You always need the Microsoft.Azure.C.SharedUtility package when you are working with the SDK. Since this
sample relies on AMQP, you must also include the Microsoft.Azure.uamqp and
Microsoft.Azure.IoTHub.AmqpTransport packages (there are equivalent packages for MQTT and HTTP).
Because the sample uses the IoTHubClient library, you must also include the
Microsoft.Azure.IoTHub.IoTHubClient package in your solution.
You can find the implementation for the sample application in the iothub_client_sample_amqp.c source file.
We'll use this sample application to walk you through what’s required to use the IoTHubClient library.
Initializing the library

NOTE
Before you start working with the libraries, you may need to perform some platform specific initialization. For example, if you
plan to use AMQP on Linux you must initialize the OpenSSL library. The samples in the GitHub repository call the utility
function platform_init when the client starts and call the platform_deinit function before exiting. These functions are
declared in the "platform.h" header file. You should examine the definitions of these functions for your target platform in the
repository to determine whether you need to include any platform initialization code in your client.

To start working with the libraries you must first allocate an IoT Hub client handle:

IOTHUB_CLIENT_HANDLE iotHubClientHandle;
iotHubClientHandle = IoTHubClient_CreateFromConnectionString(connectionString, AMQP_Protocol);

Note that we’re passing a copy of the device connection string to this function (the one we obtained from the
device explorer tool). We also designate the protocol that we want to use. This example uses AMQP, but MQTT and
HTTP are also an option.
When you have a valid IOTHUB_CLIENT_HANDLE, you can start calling the APIs to send events and receive
messages from IoT Hub. We’ll look at that next.
Sending events
Sending events to IoT Hub requires that you complete the following steps:
First, create a message:

EVENT_INSTANCE message;
sprintf_s(msgText, sizeof(msgText), "Message_%d_From_IoTHubClient_Over_AMQP", i);
message.messageHandle = IoTHubMessage_CreateFromByteArray((const unsigned char*)msgText, strlen(msgText);

Next, send the message:

IoTHubClient_SendEventAsync(iotHubClientHandle, message.messageHandle, SendConfirmationCallback, &message);

Every time you send a message, you specify a reference to a callback function that’s invoked when the data is sent:
static void SendConfirmationCallback(IOTHUB_CLIENT_CONFIRMATION_RESULT result, void* userContextCallback)
{
EVENT_INSTANCE* eventInstance = (EVENT_INSTANCE*)userContextCallback;
(void)printf("Confirmation[%d] received for message tracking id = %d with result = %s\r\n",
callbackCounter, eventInstance->messageTrackingId, ENUM_TO_STRING(IOTHUB_CLIENT_CONFIRMATION_RESULT,
result));
/* Some device specific action code goes here... */
callbackCounter++;
IoTHubMessage_Destroy(eventInstance->messageHandle);
}

Note the call to the IoTHubMessage_Destroy function when you’re done with the message. You must make this
call to free the resources allocated when you created the message.
Receiving messages
Receiving a message is an asynchronous operation. First, you register a callback to be invoked when the device
receives a message:

int receiveContext = 0;
IoTHubClient_SetMessageCallback(iotHubClientHandle, ReceiveMessageCallback, &receiveContext);

The last parameter is a void pointer to whatever you want. In the sample, it’s a pointer to an integer but it could be
a pointer to a more complex data structure. This enables the callback function to operate on shared state with the
caller of this function.
When the device receives a message, the registered callback function is invoked:

static IOTHUBMESSAGE_DISPOSITION_RESULT ReceiveMessageCallback(IOTHUB_MESSAGE_HANDLE message, void*

userContextCallback)
{
int* counter = (int*)userContextCallback;
const char* buffer;
size_t size;
if (IoTHubMessage_GetByteArray(message, (const unsigned char**)&buffer, &size) == IOTHUB_MESSAGE_OK)
{
(void)printf("Received Message [%d] with Data: <<<%.*s>>> & Size=%d\r\n", *counter, (int)size,
buffer, (int)size);
}

/* Some device specific action code goes here... */

(*counter)++;
return IOTHUBMESSAGE_ACCEPTED;
}

Note that you use the IoTHubMessage_GetByteArray function to retrieve the message, which in this example is
a string.
Uninitializing the library
When you’re done sending events and receiving messages, you can uninitialize the IoT library. To do so, issue the
following function call:

IoTHubClient_Destroy(iotHubClientHandle);

This frees up the resources previously allocated by the IoTHubClient_CreateFromConnectionString function.

As you can see, it’s easy to send events and receive messages with the IoTHubClient library. The library handles
the details of communicating with IoT Hub, including which protocol to use (from the perspective of the
developer, this is a simple configuration option).
The IoTHubClient library also provides precise control over how to serialize the events your device sends to IoT
Hub. In some cases this is an advantage, but in other cases this is an implementation detail with which you don’t
want to be concerned. If that's the case, you might consider using the serializer library, which we'll describe in the
next section.

Serializer
Conceptually the serializer library sits on top of the IoTHubClient library in the SDK. It uses the IoTHubClient
library for the underlying communication with IoT Hub, but it adds modeling capabilities that remove the burden
of dealing with message serialization from the developer. How this library works is best demonstrated by an
example.
Within the serializer folder in the azure-iot-sdk-c repository is a samples folder that contains an application
called simplesample_amqp. The Windows version of this sample includes the following Visual Studio solution:

As with the previous sample, this one includes several NuGet packages:
Microsoft.Azure.C.SharedUtility
Microsoft.Azure.IoTHub.AmqpTransport
Microsoft.Azure.IoTHub.IoTHubClient
Microsoft.Azure.IoTHub.Serializer
Microsoft.Azure.uamqp
We've seen most of these in the previous sample, but Microsoft.Azure.IoTHub.Serializer is new. This is
required when we use the serializer library.
You can find the implementation of the sample application in the simplesample_amqp.c file.
The following sections walk you through the key parts of this sample.
Initializing the library
To start working with the serializer library, you must call the initialization APIs:

serializer_init(NULL);

IOTHUB_CLIENT_HANDLE iotHubClientHandle = IoTHubClient_CreateFromConnectionString(connectionString,

AMQP_Protocol);

ContosoAnemometer* myWeather = CREATE_MODEL_INSTANCE(WeatherStation, ContosoAnemometer);

The call to the serializer_init function is a one-time call and is used to initialize the underlying library. Then, you
call the IoTHubClient_CreateFromConnectionString function, which is the same API as in the IoTHubClient
sample. This call sets your device connection string (this is also where you choose the protocol you want to use).
Note that this sample uses AMQP as the transport, but could have used HTTP.
Finally, call the CREATE_MODEL_INSTANCE function. Note that WeatherStation is the namespace of the model
and ContosoAnemometer is the name of the model. Once the model instance is created, you can use it to start
sending events and receiving messages. However, it's important to understand what a model is.
Defining the model
A model in the serializer library defines the events that your device can send to IoT Hub and the messages, called
actions in the modeling language, which it can receive. You define a model using a set of C macros as in the
simplesample_amqp sample application:

BEGIN_NAMESPACE(WeatherStation);

DECLARE_MODEL(ContosoAnemometer,
WITH_DATA(ascii_char_ptr, DeviceId),
WITH_DATA(double, WindSpeed),
WITH_ACTION(TurnFanOn),
WITH_ACTION(TurnFanOff),
WITH_ACTION(SetAirResistance, int, Position)
);

END_NAMESPACE(WeatherStation);

The BEGIN_NAMESPACE and END_NAMESPACE macros both take the namespace of the model as an
argument. It’s expected that anything between these macros is the definition of your model(s) and the data
structures that the models use.
In this example, there is a single model called ContosoAnemometer. This model defines two events that your
device can send to IoT Hub: DeviceId and WindSpeed. It also defines three actions (messages) that your device
can receive: TurnFanOn, TurnFanOff, and SetAirResistance. Each event has a type, and each action has a name
(and optionally a set of parameters).
The events and actions defined in the model define an API surface that you can use to send events to IoT Hub, as
well as respond to messages being sent to the device. This is best understood through an example.
Sending events
The model defines the events that you can send to IoT Hub. In this example, that means one of the two events
defined using the WITH_DATA macro. For example, if you want to send a WindSpeed event to an IoT hub, there
are a few steps involved in making this happen. The first is to set the data we want to send:

myWeather->WindSpeed = 15;

The model we defined earlier allows us to do this by setting a member of a struct. Next, we serialize the event we
want to send:

unsigned char* destination;

size_t destinationSize;

SERIALIZE(&destination, &destinationSize, myWeather->WindSpeed);

This code serializes the event to a buffer (referenced by destination). Finally, we’ll send the event to IoT hub with
this code:

sendMessage(iotHubClientHandle, destination, destinationSize);

This is a helper function in the sample application that sends our serialized event to IoT Hub:
static void sendMessage(IOTHUB_CLIENT_HANDLE iotHubClientHandle, const unsigned char* buffer, size_t size)
{
static unsigned int messageTrackingId;
IOTHUB_MESSAGE_HANDLE messageHandle = IoTHubMessage_CreateFromByteArray(buffer, size);
if (messageHandle != NULL)
{
if (IoTHubClient_SendEventAsync(iotHubClientHandle, messageHandle, sendCallback, (void*)
(uintptr_t)messageTrackingId) != IOTHUB_CLIENT_OK)
{
printf("failed to hand over the message to IoTHubClient");
}
else
{
printf("IoTHubClient accepted the message for delivery\r\n");
}

IoTHubMessage_Destroy(messageHandle);
}
free((void*)buffer);
messageTrackingId++;
}

This code is very similar to what we saw in the iothub_client_sample_amqp application, in which we created a
message from a byte array and then used IoTHubClient_SendEventAsync to send it to IoT Hub. After that we
just have to free the message handle and serialized data buffer we allocated earlier.
The second to last parameter of IoTHubClient_SendEventAsync is a reference to a callback function that’s called
when the data is successfully sent. Here's an example of a callback function:

void sendCallback(IOTHUB_CLIENT_CONFIRMATION_RESULT result, void* userContextCallback)

{
int messageTrackingId = (intptr_t)userContextCallback;

(void)printf("Message Id: %d Received.\r\n", messageTrackingId);

(void)printf("Result Call Back Called! Result is: %s \r\n",

ENUM_TO_STRING(IOTHUB_CLIENT_CONFIRMATION_RESULT, result));
}

The second parameter is a pointer to user context; the same pointer we passed to
IoTHubClient_SendEventAsync. In this case the context is a simple counter, but it can be anything you want.
That's all there is to sending events. The only thing left to cover is how to receive messages.
Receiving messages
Receiving a message works similarly to the way messages work in the IoTHubClient library. First, you register a
message callback function:

IoTHubClient_SetMessageCallback(iotHubClientHandle, IoTHubMessage, myWeather)

Then, you write the callback function that's invoked when a message is received:
static IOTHUBMESSAGE_DISPOSITION_RESULT IoTHubMessage(IOTHUB_MESSAGE_HANDLE message, void*
userContextCallback)
{
IOTHUBMESSAGE_DISPOSITION_RESULT result;
const unsigned char* buffer;
size_t size;
if (IoTHubMessage_GetByteArray(message, &buffer, &size) != IOTHUB_MESSAGE_OK)
{
printf("unable to IoTHubMessage_GetByteArray\r\n");
result = EXECUTE_COMMAND_ERROR;
}
else
{
/*buffer is not zero terminated*/
char* temp = malloc(size + 1);
if (temp == NULL)
{
printf("failed to malloc\r\n");
result = EXECUTE_COMMAND_ERROR;
}
else
{
memcpy(temp, buffer, size);
temp[size] = '\0';
EXECUTE_COMMAND_RESULT executeCommandResult = EXECUTE_COMMAND(userContextCallback, temp);
result =
(executeCommandResult == EXECUTE_COMMAND_ERROR) ? IOTHUBMESSAGE_ABANDONED :
(executeCommandResult == EXECUTE_COMMAND_SUCCESS) ? IOTHUBMESSAGE_ACCEPTED :
IOTHUBMESSAGE_REJECTED;
free(temp);
}
}
return result;
}

This code is boilerplate -- it's the same for any solution. This function receives the message and takes care of
routing it to the appropriate function through the call to EXECUTE_COMMAND. The function called at this point
depends on the definition of the actions in our model.
When you define an action in your model, you're required to implement a function that's called when your device
receives the corresponding message. For example, if your model defines this action:

WITH_ACTION(SetAirResistance, int, Position)

You must define a function with this signature:

EXECUTE_COMMAND_RESULT SetAirResistance(ContosoAnemometer* device, int Position)

{
(void)device;
(void)printf("Setting Air Resistance Position to %d.\r\n", Position);
return EXECUTE_COMMAND_SUCCESS;
}

Note that the name of the function matches the name of the action in the model and that the parameters of the
function match the parameters specified for the action. The first parameter is always required and contains a
pointer to the instance of our model.
When the device receives a message that matches this signature, the corresponding function is called. Therefore,
aside from having to include the boilerplate code from IoTHubMessage, receiving messages is just a matter of
defining a simple function for each action defined in your model.
Uninitializing the library
When you’re done sending data and receiving messages, you can uninitialize the IoT library:

DESTROY_MODEL_INSTANCE(myWeather);
}
IoTHubClient_Destroy(iotHubClientHandle);
}
serializer_deinit();

Each of these three functions aligns with the three initialization functions described previously. Calling these APIs
ensures that you free previously allocated resources.

Next Steps
This article covered the basics of using the libraries in the Azure IoT device SDK for C. It provided you with
enough information to understand what’s included in the SDK, its architecture, and how to get started working
with the Windows samples. The next article continues the description of the SDK by explaining more about the
IoTHubClient library.
To learn more about developing for IoT Hub, see the Azure IoT SDKs.
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Azure IoT device SDK for C – more about
IoTHubClient
2/13/2017 • 13 min to read • Edit on GitHub

The first article in this series introduced the Azure IoT device SDK for C. That article explained that there are two
architectural layers in SDK. At the base is the IoTHubClient library which directly manages communication with
IoT Hub. There's also the serializer library that builds on top of that to provide serialization services. In this article
we'll provide additional detail on the IoTHubClient library.
The previous article described how to use the IoTHubClient library to send events to IoT Hub and receive
messages. This article extends that discussion by explaining how to more precisely manage when you send and
receive data, introducing you to the lower-level APIs. We'll also explain how to attach properties to events (and
retrieve them from messages) using the property handling features in the IoTHubClient library. Finally, we'll
provide additional explanation of different ways to handle messages received from IoT Hub.
The article concludes by covering a couple of miscellaneous topics, including more about device credentials and
how to change the behavior of the IoTHubClient through configuration options.
We'll use the IoTHubClient SDK samples to explain these topics. If you want to follow along, see the
iothub_client_sample_http and iothub_client_sample_amqp applications that are included in the Azure IoT
device SDK for C. Everything described in the following sections is demonstrated in these samples.
You can find the Azure IoT device SDK for C GitHub repository and view details of the API in the C API reference.

The lower-level APIs

The previous article described the basic operation of the IotHubClient within the context of the
iothub_client_sample_amqp application. For example, it explained how to initialize the library using this code.

IOTHUB_CLIENT_HANDLE iotHubClientHandle;
iotHubClientHandle = IoTHubClient_CreateFromConnectionString(connectionString, AMQP_Protocol);

It also described how to send events using this function call.

IoTHubClient_SendEventAsync(iotHubClientHandle, message.messageHandle, SendConfirmationCallback, &message);

The article also described how to receive messages by registering a callback function.

int receiveContext = 0;
IoTHubClient_SetMessageCallback(iotHubClientHandle, ReceiveMessageCallback, &receiveContext);

The article also showed how to free resources using code such as the following.

IoTHubClient_Destroy(iotHubClientHandle);

However there are companion functions to each of these APIs:

IoTHubClient_LL_CreateFromConnectionString
IoTHubClient_LL_SendEventAsync
IoTHubClient_LL_SetMessageCallback
IoTHubClient_LL_Destroy
These functions all include “LL” in the API name. Other than that, the parameters of each of these functions are
identical to their non-LL counterparts. However, the behavior of these functions is different in one important way.
When you call IoTHubClient_CreateFromConnectionString, the underlying libraries create a new thread that
runs in the background. This thread sends events to, and receives messages from, IoT Hub. No such thread is
created when working with the "LL" APIs. The creation of the background thread is a convenience to the developer.
You don’t have to worry about explicitly sending events and receiving messages from IoT Hub -- it happens
automatically in the background. In contrast, the "LL" APIs give you explicit control over communication with IoT
Hub, if you need it.
To understand this better, let’s look at an example:
When you call IoTHubClient_SendEventAsync, what you're actually doing is putting the event in a buffer. The
background thread created when you call IoTHubClient_CreateFromConnectionString continually monitors
this buffer and sends any data that it contains to IoT Hub. This happens in the background at the same time that
the main thread is performing other work.
Similarly, when you register a callback function for messages using IoTHubClient_SetMessageCallback, you're
instructing the SDK to have the background thread invoke the callback function when a message is received,
independent of the main thread.
The "LL" APIs don’t create a background thread. Instead, a new API must be called to explicitly send and receive
data from IoT Hub. This is demonstrated in the following example.
The iothub_client_sample_http application that’s included in the SDK demonstrates the lower-level APIs. In that
sample, we send events to IoT Hub with code such as the following:

EVENT_INSTANCE message;
sprintf_s(msgText, sizeof(msgText), "Message_%d_From_IoTHubClient_LL_Over_HTTP", i);
message.messageHandle = IoTHubMessage_CreateFromByteArray((const unsigned char*)msgText, strlen(msgText));

IoTHubClient_LL_SendEventAsync(iotHubClientHandle, message.messageHandle, SendConfirmationCallback, &message)

The first three lines create the message, and the last line sends the event. However, as mentioned previously,
"sending" the event means that the data is simply placed in a buffer. Nothing is transmitted on the network when
we call IoTHubClient_LL_SendEventAsync. In order to actually ingress the data to IoT Hub, you must call
IoTHubClient_LL_DoWork, as in this example:

while (1)
{
IoTHubClient_LL_DoWork(iotHubClientHandle);
ThreadAPI_Sleep(1000);
}

This code (from the iothub_client_sample_http application) repeatedly calls IoTHubClient_LL_DoWork. Each
time IoTHubClient_LL_DoWork is called, it sends some events from the buffer to IoT Hub and it retrieves a
queued message being sent to the device. The latter case means that if we registered a callback function for
messages, then the callback is invoked (assuming any messages are queued up). We would have registered such a
callback function with code such as the following:

IoTHubClient_LL_SetMessageCallback(iotHubClientHandle, ReceiveMessageCallback, &receiveContext)

The reason that IoTHubClient_LL_DoWork is often called in a loop is that each time it’s called, it sends some
buffered events to IoT Hub and retrieves the next message queued up for the device. Each call isn’t guaranteed to
send all buffered events or to retrieve all queued messages. If you want to send all events in the buffer and then
continue on with other processing you can replace this loop with code such as the following:

IOTHUB_CLIENT_STATUS status;

while ((IoTHubClient_LL_GetSendStatus(iotHubClientHandle, &status) == IOTHUB_CLIENT_OK) && (status ==

IOTHUB_CLIENT_SEND_STATUS_BUSY))
{
IoTHubClient_LL_DoWork(iotHubClientHandle);
ThreadAPI_Sleep(1000);
}

This code calls IoTHubClient_LL_DoWork until all events in the buffer have been sent to IoT Hub. Note this does
not also imply that all queued messages have been received. Part of the reason for this is that checking for "all"
messages isn’t as deterministic an action. What happens if you retrieve "all" of the messages, but then another one
is sent to the device immediately after? A better way to deal with that is with a programmed timeout. For example,
the message callback function could reset a timer every time it’s invoked. You can then write logic to continue
processing if, for example, no messages have been received in the last X seconds.
When you’re finished ingressing events and receiving messages, be sure to call the corresponding function to
clean up resources.

IoTHubClient_LL_Destroy(iotHubClientHandle);

Basically there’s only one set of APIs to send and receive data with a background thread and another set of APIs
that does the same thing without the background thread. A lot of developers may prefer the non-LL APIs, but the
lower-level APIs are useful when the developer wants explicit control over network transmissions. For example,
some devices collect data over time and only ingress events at specified intervals (for example, once an hour or
once a day). The lower-level APIs give you the ability to explicitly control when you send and receive data from IoT
Hub. Others will simply prefer the simplicity that the lower-level APIs provide. Everything happens on the main
thread rather than some work happening in the background.
Whichever model you choose, be sure to be consistent in which APIs you use. If you start by calling
IoTHubClient_LL_CreateFromConnectionString, be sure you only use the corresponding lower-level APIs for
any follow-up work:
IoTHubClient_LL_SendEventAsync
IoTHubClient_LL_SetMessageCallback
IoTHubClient_LL_Destroy
IoTHubClient_LL_DoWork
The opposite is true as well. If you start with IoTHubClient_CreateFromConnectionString, then use the non-LL
APIs for any additional processing.
In the Azure IoT device SDK for C, see the iothub_client_sample_http application for a complete example of the
lower-level APIs. The iothub_client_sample_amqp application can be referenced for a full example of the non-LL
APIs.

Property handling
So far when we've described sending data, we've been referring to the body of the message. For example, consider
this code:
EVENT_INSTANCE message;
sprintf_s(msgText, sizeof(msgText), "Hello World");
message.messageHandle = IoTHubMessage_CreateFromByteArray((const unsigned char*)msgText, strlen(msgText));
IoTHubClient_LL_SendEventAsync(iotHubClientHandle, message.messageHandle, SendConfirmationCallback, &message)

This example sends a message to IoT Hub with the text "Hello World." However, IoT Hub also allows properties to
be attached to each message. Properties are name/value pairs that can be attached to the message. For example,
we can modify the previous code to attach a property to the message:

MAP_HANDLE propMap = IoTHubMessage_Properties(message.messageHandle);

sprintf_s(propText, sizeof(propText), "%d", i);
Map_AddOrUpdate(propMap, "SequenceNumber", propText);

We start by calling IoTHubMessage_Properties and passing it the handle of our message. What we get back is a
MAP_HANDLE reference that enables us to start adding properties. The latter is accomplished by calling
Map_AddOrUpdate, which takes a reference to a MAP_HANDLE, the property name, and the property value. With
this API we can add as many properties as we like.
When the event is read from Event Hubs, the receiver can enumerate the properties and retrieve their
corresponding values. For example, in .NET this would be accomplished by accessing the Properties collection on
the EventData object.
In the previous example, we’re attaching properties to an event that we send to IoT Hub. Properties can also be
attached to messages received from IoT Hub. If we want to retrieve properties from a message, we can use code
such as the following in our message callback function:

static IOTHUBMESSAGE_DISPOSITION_RESULT ReceiveMessageCallback(IOTHUB_MESSAGE_HANDLE message, void*

userContextCallback)
{
. . .

// Retrieve properties from the message

MAP_HANDLE mapProperties = IoTHubMessage_Properties(message);
if (mapProperties != NULL)
{
const char*const* keys;
const char*const* values;
size_t propertyCount = 0;
if (Map_GetInternals(mapProperties, &keys, &values, &propertyCount) == MAP_OK)
{
if (propertyCount > 0)
{
printf("Message Properties:\r\n");
for (size_t index = 0; index < propertyCount; index++)
{
printf("\tKey: %s Value: %s\r\n", keys[index], values[index]);
}
printf("\r\n");
}
}
}

. . .
}

The call to IoTHubMessage_Properties returns the MAP_HANDLE reference. We then pass that reference to
Map_GetInternals to obtain a reference to an array of the name/value pairs (as well as a count of the properties).
At that point it's a simple matter of enumerating the properties to get to the values we want.
You don't have to use properties in your application. However, if you need to set them on events or retrieve them
from messages, the IoTHubClient library makes it easy.

Message handling
As stated previously, when messages arrive from IoT Hub the IoTHubClient library responds by invoking a
registered callback function. There is a return parameter of this function that deserves some additional
explanation. Here’s an excerpt of the callback function in the iothub_client_sample_http sample application:

static IOTHUBMESSAGE_DISPOSITION_RESULT ReceiveMessageCallback(IOTHUB_MESSAGE_HANDLE message, void*

userContextCallback)
{
. . .
return IOTHUBMESSAGE_ACCEPTED;
}

Note that the return type is IOTHUBMESSAGE_DISPOSITION_RESULT and in this particular case we return
IOTHUBMESSAGE_ACCEPTED. There are other values we can return from this function that change how the
IoTHubClient library reacts to the message callback. Here are the options.
IOTHUBMESSAGE_ACCEPTED – The message has been processed successfully. The IoTHubClient library will
not invoke the callback function again with the same message.
IOTHUBMESSAGE_REJECTED – The message was not processed and there is no desire to do so in the future.
The IoTHubClient library should not invoke the callback function again with the same message.
IOTHUBMESSAGE_ABANDONED – The message was not processed successfully, but the IoTHubClient
library should invoke the callback function again with the same message.
For the first two return codes, the IoTHubClient library sends a message to IoT Hub indicating that the message
should be deleted from the device queue and not delivered again. The net effect is the same (the message is
deleted from the device queue), but whether the message was accepted or rejected is still recorded. Recording this
distinction is useful to senders of the message who can listen for feedback and find out if a device has accepted or
rejected a particular message.
In the last case a message is also sent to IoT Hub, but it indicates that the message should be redelivered. Typically
you’ll abandon a message if you encounter some error but want to try to process the message again. In contrast,
rejecting a message is appropriate when you encounter an unrecoverable error (or if you simply decide you don’t
want to process the message).
In any case, be aware of the different return codes so that you can elicit the behavior you want from the
IoTHubClient library.

Alternate device credentials

As explained previously, the first thing to do when working with the IoTHubClient library is to obtain a
IOTHUB_CLIENT_HANDLE with a call such as the following:

IOTHUB_CLIENT_HANDLE iotHubClientHandle;
iotHubClientHandle = IoTHubClient_CreateFromConnectionString(connectionString, AMQP_Protocol);

The arguments to IoTHubClient_CreateFromConnectionString are the device connection string and a

parameter that indicates the protocol we use to communicate with IoT Hub. The device connection string has a
format that appears as follows:
HostName=IOTHUBNAME.IOTHUBSUFFIX;DeviceId=DEVICEID;SharedAccessKey=SHAREDACCESSKEY

There are four pieces of information in this string: IoT Hub name, IoT Hub suffix, device ID, and shared access key.
You obtain the fully qualified domain name (FQDN) of an IoT hub when you create your IoT hub instance in the
Azure portal — this gives you the IoT hub name (the first part of the FQDN) and the IoT hub suffix (the rest of the
FQDN). You get the device ID and the shared access key when you register your device with IoT Hub (as described
in the previous article).
IoTHubClient_CreateFromConnectionString gives you one way to initialize the library. If you prefer, you can
create a new IOTHUB_CLIENT_HANDLE by using these individual parameters rather than the device connection
string. This is achieved with the following code:

IOTHUB_CLIENT_CONFIG iotHubClientConfig;
iotHubClientConfig.iotHubName = "";
iotHubClientConfig.deviceId = "";
iotHubClientConfig.deviceKey = "";
iotHubClientConfig.iotHubSuffix = "";
iotHubClientConfig.protocol = HTTP_Protocol;
IOTHUB_CLIENT_HANDLE iotHubClientHandle = IoTHubClient_LL_Create(&iotHubClientConfig);

This accomplishes the same thing as IoTHubClient_CreateFromConnectionString.

It may seem obvious that you would want to use IoTHubClient_CreateFromConnectionString rather than this
more verbose method of initialization. Keep in mind, however, that when you register a device in IoT Hub what you
get is a device ID and device key (not a connection string). The device explorer SDK tool introduced in the previous
article uses libraries in the Azure IoT service SDK to create the device connection string from the device ID,
device key, and IoT Hub host name. So calling IoTHubClient_LL_Create may be preferable because it saves you
the step of generating a connection string. Use whichever method is convenient.

Configuration options
So far everything described about the way the IoTHubClient library works reflects its default behavior. However,
there are a few options that you can set to change how the library works. This is accomplished by leveraging the
IoTHubClient_LL_SetOption API. Consider this example:

unsigned int timeout = 30000;

IoTHubClient_LL_SetOption(iotHubClientHandle, "timeout", &timeout);

There are a couple of options that are commonly used:

SetBatching (bool) – If true, then data sent to IoT Hub is sent in batches. If false, then messages are sent
individually. The default is false. Note that the SetBatching option only applies to the HTTP protocol and not
to the MQTT or AMQP protocols.
Timeout (unsigned int) – This value is represented in milliseconds. If sending an HTTP request or receiving a
response takes longer than this time, then the connection times out.
The batching option is important. By default, the library ingresses events individually (a single event is whatever
you pass to IoTHubClient_LL_SendEventAsync). If the batching option is true, the library collects as many
events as it can from the buffer (up to the maximum message size that IoT Hub will accept). The event batch is sent
to IoT Hub in a single HTTP call (the individual events are bundled into a JSON array). Enabling batching typically
results in big performance gains since you’re reducing network round-trips. It also significantly reduces bandwidth
since you are sending one set of HTTP headers with an event batch rather than a set of headers for each individual
event. Unless you have a specific reason to do otherwise, typically you’ll want to enable batching.
Next steps
This article describes in detail the behavior of the IoTHubClient library found in the Azure IoT device SDK for C.
With this information, you should have a good understanding of the capabilities of the IoTHubClient library. The
next article provides similar detail on the serializer library.
To learn more about developing for IoT Hub, see the Azure IoT SDKs.
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Azure IoT device SDK for C – more about serializer
2/13/2017 • 20 min to read • Edit on GitHub

The first article in this series introduced the Azure IoT device SDK for C. The next article provided a more detailed
description of the IoTHubClient. This article completes coverage of the SDK by providing a more detailed
description of the remaining component: the serializer library.
The introductory article described how to use the serializer library to send events to and receive messages from
IoT Hub. In this article, we extend that discussion by providing a more complete explanation of how to model your
data with the serializer macro language. The article also includes more detail about how the library serializes
messages (and in some cases how you can control the serialization behavior). We'll also describe some parameters
you can modify that determine the size of the models you create.
Finally, the article revisits some topics covered in previous articles such as message and property handling. As we'll
find out, those features work in the same way using the serializer library as they do with the IoTHubClient
library.
Everything described in this article is based on the serializer SDK samples. If you want to follow along, see the
simplesample_amqp and simplesample_http applications included in the Azure IoT device SDK for C.
You can find the Azure IoT device SDK for C GitHub repository and view details of the API in the C API reference.

The modeling language

The introductory article in this series introduced the Azure IoT device SDK for C modeling language through the
example provided in the simplesample_amqp application:

BEGIN_NAMESPACE(WeatherStation);

DECLARE_MODEL(ContosoAnemometer,
WITH_DATA(ascii_char_ptr, DeviceId),
WITH_DATA(double, WindSpeed),
WITH_ACTION(TurnFanOn),
WITH_ACTION(TurnFanOff),
WITH_ACTION(SetAirResistance, int, Position)
);

END_NAMESPACE(WeatherStation);

As you can see, the modeling language is based on C macros. You always begin your definition with
BEGIN_NAMESPACE and always end with END_NAMESPACE. It's common to name the namespace for your
company or, as in this example, the project that you're working on.
What goes inside the namespace are model definitions. In this case, there is a single model for an anemometer.
Once again, the model can be named anything, but typically this is named for the device or type of data you want
to exchange with IoT Hub.
Models contain a definition of the events you can ingress to IoT Hub (the data) as well as the messages you can
receive from IoT Hub (the actions). As you can see from the example, events have a type and a name; actions have a
name and optional parameters (each with a type).
What’s not demonstrated in this sample are additional data types that are supported by the SDK. We'll cover that
next.
NOTE
IoT Hub refers to the data a device sends to it as events, while the modeling language refers to it as data (defined using
WITH_DATA). Likewise, IoT Hub refers to the data you send to devices as messages, while the modeling language refers to it
as actions (defined using WITH_ACTION). Be aware that these terms may be used interchangeably in this article.

Supported data types

The following data types are supported in models created with the serializer library:

TYPE DESCRIPTION

double double precision floating point number

int 32 bit integer

float single precision floating point number

long long integer

int8_t 8 bit integer

int16_t 16 bit integer

int32_t 32 bit integer

int64_t 64 bit integer

bool boolean

ascii_char_ptr ASCII string

EDM_DATE_TIME_OFFSET date time offset

EDM_GUID GUID

EDM_BINARY binary

DECLARE_STRUCT complex data type

Let’s start with the last data type. The DECLARE_STRUCT allows you to define complex data types, which are
groupings of the other primitive types. These groupings allow us to define a model that looks like this:
DECLARE_STRUCT(TestType,
double, aDouble,
int, aInt,
float, aFloat,
long, aLong,
int8_t, aInt8,
uint8_t, auInt8,
int16_t, aInt16,
int32_t, aInt32,
int64_t, aInt64,
bool, aBool,
ascii_char_ptr, aAsciiCharPtr,
EDM_DATE_TIME_OFFSET, aDateTimeOffset,
EDM_GUID, aGuid,
EDM_BINARY, aBinary
);

DECLARE_MODEL(TestModel,
WITH_DATA(TestType, Test)
);

Our model contains a single data event of type TestType. TestType is a complex type that includes several
members, which collectively demonstrate the primitive types supported by the serializer modeling language.
With a model like this, we can write code to send data to IoT Hub that appears as follows:

TestModel* testModel = CREATE_MODEL_INSTANCE(MyThermostat, TestModel);

testModel->Test.aDouble = 1.1;
testModel->Test.aInt = 2;
testModel->Test.aFloat = 3.0f;
testModel->Test.aLong = 4;
testModel->Test.aInt8 = 5;
testModel->Test.auInt8 = 6;
testModel->Test.aInt16 = 7;
testModel->Test.aInt32 = 8;
testModel->Test.aInt64 = 9;
testModel->Test.aBool = true;
testModel->Test.aAsciiCharPtr = "ascii string 1";

time_t now;
time(&now);
testModel->Test.aDateTimeOffset = GetDateTimeOffset(now);

EDM_GUID guid = { { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E,
0x0F } };
testModel->Test.aGuid = guid;

unsigned char binaryArray[3] = { 0x01, 0x02, 0x03 };

EDM_BINARY binaryData = { sizeof(binaryArray), &binaryArray };
testModel->Test.aBinary = binaryData;

SendAsync(iotHubClientHandle, (const void*)&(testModel->Test));

Basically, we’re assigning a value to every member of the Test structure and then calling SendAsync to send the
Test data event to the cloud. SendAsync is a helper function that sends a single data event to IoT Hub:
void SendAsync(IOTHUB_CLIENT_LL_HANDLE iotHubClientHandle, const void *dataEvent)
{
unsigned char* destination;
size_t destinationSize;
if (SERIALIZE(&destination, &destinationSize, *(const unsigned char*)dataEvent) ==
{
// null terminate the string
char* destinationAsString = (char*)malloc(destinationSize + 1);
if (destinationAsString != NULL)
{
memcpy(destinationAsString, destination, destinationSize);
destinationAsString[destinationSize] = '\0';
IOTHUB_MESSAGE_HANDLE messageHandle = IoTHubMessage_CreateFromString(destinationAsString);
if (messageHandle != NULL)
{
IoTHubClient_SendEventAsync(iotHubClientHandle, messageHandle, sendCallback, (void*)0);

IoTHubMessage_Destroy(messageHandle);
}
free(destinationAsString);
}
free(destination);
}
}

This function serializes the given data event and sends it to IoT Hub using IoTHubClient_SendEventAsync. This is
the same code discussed in previous articles (SendAsync encapsulates the logic into a convenient function).
One other helper function used in the previous code is GetDateTimeOffset. This function transforms the given
time into a value of type EDM_DATE_TIME_OFFSET:

EDM_DATE_TIME_OFFSET GetDateTimeOffset(time_t time)

{
struct tm newTime;
gmtime_s(&newTime, &time);
EDM_DATE_TIME_OFFSET dateTimeOffset;
dateTimeOffset.dateTime = newTime;
dateTimeOffset.fractionalSecond = 0;
dateTimeOffset.hasFractionalSecond = 0;
dateTimeOffset.hasTimeZone = 0;
dateTimeOffset.timeZoneHour = 0;
dateTimeOffset.timeZoneMinute = 0;
return dateTimeOffset;
}

If you run this code, the following message is sent to IoT Hub:

{"aDouble":1.100000000000000, "aInt":2, "aFloat":3.000000, "aLong":4, "aInt8":5, "auInt8":6, "aInt16":7,

"aInt32":8, "aInt64":9, "aBool":true, "aAsciiCharPtr":"ascii string 1", "aDateTimeOffset":"2015-09-
14T21:18:21Z", "aGuid":"00010203-0405-0607-0809-0A0B0C0D0E0F", "aBinary":"AQID"}

Note that the serialization is JSON, which is the format generated by the serializer library. Also note that each
member of the serialized JSON object matches the members of the TestType that we defined in our model. The
values also exactly match those used in the code. However, note that the binary data is base64-encoded: "AQID" is
the base64 encoding of {0x01, 0x02, 0x03}.
This example demonstrates the advantage of using the serializer library -- it enables us to send JSON to the cloud,
without having to explicitly deal with serialization in our application. All we have to worry about is setting the
values of the data events in our model and then calling simple APIs to send those events to the cloud.
With this information, we can define models that include the range of supported data types, including complex
types (we could even include complex types within other complex types). However, he serialized JSON generated
by the example above brings up an important point. How we send data with the serializer library determines
exactly how the JSON is formed. That particular point is what we'll cover next.

More about serialization

The previous section highlights an example of the output generated by the serializer library. In this section, we'll
explain how the library serializes data and how you can control that behavior using the serialization APIs.
In order to advance the discussion on serialization, we'll work with a new model based on a thermostat. First, let's
provide some background on the scenario we're trying to address.
We want to model a thermostat that measures temperature and humidity. Each piece of data is going to be sent to
IoT Hub differently. By default, the thermostat ingresses a temperature event once every 2 minutes; a humidity
event is ingressed once every 15 minutes. When either event is ingressed, it must include a timestamp that shows
the time that the corresponding temperature or humidity was measured.
Given this scenario, we'll demonstrate two different ways to model the data, and we'll explain the effect that
modeling has on the serialized output.
Model 1
Here's the first version of a model that supports the previous scenario:

BEGIN_NAMESPACE(Contoso);

DECLARE_STRUCT(TemperatureEvent,
int, Temperature,
EDM_DATE_TIME_OFFSET, Time);

DECLARE_STRUCT(HumidityEvent,
int, Humidity,
EDM_DATE_TIME_OFFSET, Time);

DECLARE_MODEL(Thermostat,
WITH_DATA(TemperatureEvent, Temperature),
WITH_DATA(HumidityEvent, Humidity)
);

END_NAMESPACE(Contoso);

Note that the model includes two data events: Temperature and Humidity. Unlike previous examples, the type of
each event is a structure defined using DECLARE_STRUCT. TemperatureEvent includes a temperature
measurement and a timestamp; HumidityEvent contains a humidity measurement and a timestamp. This model
gives us a natural way to model the data for the scenario described above. When we send an event to the cloud,
we'll either send a temperature/timestamp or a humidity/timestamp pair.
We can send a temperature event to the cloud using code such as the following:
time_t now;
time(&now);
thermostat->Temperature.Temperature = 75;
thermostat->Temperature.Time = GetDateTimeOffset(now);

unsigned char* destination;

size_t destinationSize;
if (SERIALIZE(&destination, &destinationSize, thermostat->Temperature) == IOT_AGENT_OK)
{
sendMessage(iotHubClientHandle, destination, destinationSize);
}

We'll use hard-coded values for temperature and humidity in the sample code, but imagine that we’re actually
retrieving these values by sampling the corresponding sensors on the thermostat.
The code above uses the GetDateTimeOffset helper that was introduced previously. For reasons that will become
clear later, this code explicitly separates the task of serializing and sending the event. The previous code serializes
the temperature event into a buffer. Then, sendMessage is a helper function (included in simplesample_amqp)
that sends the event to IoT Hub:

static void sendMessage(IOTHUB_CLIENT_HANDLE iotHubClientHandle, const unsigned char* buffer, size_t size)
{
static unsigned int messageTrackingId;
IOTHUB_MESSAGE_HANDLE messageHandle = IoTHubMessage_CreateFromByteArray(buffer, size);
if (messageHandle != NULL)
{
IoTHubClient_SendEventAsync(iotHubClientHandle, messageHandle, sendCallback, (void*)
(uintptr_t)messageTrackingId);

IoTHubMessage_Destroy(messageHandle);
}
free((void*)buffer);
}

This code is a subset of the SendAsync helper described in the previous section, so we won’t go over it again here.
When we run the previous code to send the Temperature event, this serialized form of the event is sent to IoT Hub:

{"Temperature":75, "Time":"2015-09-17T18:45:56Z"}

We're sending a temperature which is of type TemperatureEvent and that struct contains a Temperature and
Time member. This is directly reflected in the serialized data.
Similarly, we can send a humidity event with this code:

thermostat->Humidity.Humidity = 45;
thermostat->Humidity.Time = GetDateTimeOffset(now);
if (SERIALIZE(&destination, &destinationSize, thermostat->Humidity) == IOT_AGENT_OK)
{
sendMessage(iotHubClientHandle, destination, destinationSize);
}

The serialized form that’s sent to IoT Hub appears as follows:

{"Humidity":45, "Time":"2015-09-17T18:45:56Z"}

Again, this is as expected.

With this model, you can imagine how additional events can easily be added. You define more structures using
DECLARE_STRUCT, and include the corresponding event in the model using WITH_DATA.
Now, let’s modify the model so that it includes the same data but with a different structure.
Model 2
Consider this alternative model to the one above:

DECLARE_MODEL(Thermostat,
WITH_DATA(int, Temperature),
WITH_DATA(int, Humidity),
WITH_DATA(EDM_DATE_TIME_OFFSET, Time)
);

In this case we've eliminated the DECLARE_STRUCT macros and are simply defining the data items from our
scenario using simple types from the modeling language.
Just for the moment let’s ignore the Time event. With that aside, here’s the code to ingress Temperature:

time_t now;
time(&now);
thermostat->Temperature = 75;

unsigned char* destination;

size_t destinationSize;
if (SERIALIZE(&destination, &destinationSize, thermostat->Temperature) == IOT_AGENT_OK)
{
sendMessage(iotHubClientHandle, destination, destinationSize);
}

This code sends the following serialized event to IoT Hub:

{"Temperature":75}

And the code for sending the Humidity event appears as follows:

thermostat->Humidity = 45;
if (SERIALIZE(&destination, &destinationSize, thermostat->Humidity) == IOT_AGENT_OK)
{
sendMessage(iotHubClientHandle, destination, destinationSize);
}

This code sends this to IoT Hub:

{"Humidity":45}

So far there are still no surprises. Now let's change how we use the SERIALIZE macro.
The SERIALIZE macro can take multiple data events as arguments. This enables us to serialize the Temperature
and Humidity event together and send them to IoT Hub in one call:

if (SERIALIZE(&destination, &destinationSize, thermostat->Temperature, thermostat->Humidity) == IOT_AGENT_OK)

{
sendMessage(iotHubClientHandle, destination, destinationSize);
}
You might guess that the result of this code is that two data events are sent to IoT Hub:
[
{"Temperature":75},
{"Humidity":45}
]
In other words, you might expect that this code is the same as sending Temperature and Humidity separately. It’s
just a convenience to pass both events to SERIALIZE in the same call. However, that’s not the case. Instead, the
code above sends this single data event to IoT Hub:
{"Temperature":75, "Humidity":45}
This may seem strange because our model defines Temperature and Humidity as two separate events:

DECLARE_MODEL(Thermostat,
WITH_DATA(int, Temperature),
WITH_DATA(int, Humidity),
WITH_DATA(EDM_DATE_TIME_OFFSET, Time)
);

More to the point, we didn’t model these events where Temperature and Humidity are in the same structure:

DECLARE_STRUCT(TemperatureAndHumidityEvent,
int, Temperature,
int, Humidity,
);

DECLARE_MODEL(Thermostat,
WITH_DATA(TemperatureAndHumidityEvent, TemperatureAndHumidity),
);

If we used this model, it would be easier to understand how Temperature and Humidity would be sent in the
same serialized message. However it may not be clear why it works that way when you pass both data events to
SERIALIZE using model 2.
This behavior is easier to understand if you know the assumptions that the serializer library is making. To make
sense of this let’s go back to our model:

DECLARE_MODEL(Thermostat,
WITH_DATA(int, Temperature),
WITH_DATA(int, Humidity),
WITH_DATA(EDM_DATE_TIME_OFFSET, Time)
);

Think of this model in object-oriented terms. In this case we’re modeling a physical device (a thermostat) and that
device includes attributes like Temperature and Humidity.
We can send the entire state of our model with code such as the following:

if (SERIALIZE(&destination, &destinationSize, thermostat->Temperature, thermostat->Humidity, thermostat->Time)

== IOT_AGENT_OK)
{
sendMessage(iotHubClientHandle, destination, destinationSize);
}
Assuming the values of Temperature, Humidity and Time are set, we would see an event like this sent to IoT Hub:

{"Temperature":75, "Humidity":45, "Time":"2015-09-17T18:45:56Z"}

Sometimes you may only want to send some properties of the model to the cloud (this is especially true if your
model contains a large number of data events). It’s useful to send only a subset of data events, such as in our
earlier example:

{"Temperature":75, "Time":"2015-09-17T18:45:56Z"}

This generates exactly the same serialized event as if we had defined a TemperatureEvent with a Temperature
and Time member, just as we did with model 1. In this case we were able to generate exactly the same serialized
event by using a different model (model 2) because we called SERIALIZE in a different way.
The important point is that if you pass multiple data events to SERIALIZE, then it assumes each event is a property
in a single JSON object.
The best approach depends on you and how you think about your model. If you’re sending "events" to the cloud
and each event contains a defined set of properties, then the first approach makes a lot of sense. In that case you
would use DECLARE_STRUCT to define the structure of each event and then include them in your model with the
WITH_DATA macro. Then you send each event as we did in the first example above. In this approach you would
only pass a single data event to SERIALIZER.
If you think about your model in an object-oriented fashion, then the second approach may suit you. In this case,
the elements defined using WITH_DATA are the "properties" of your object. You pass whatever subset of events to
SERIALIZE that you like, depending on how much of your "object’s" state you want to send to the cloud.
Nether approach is right or wrong. Just be aware of how the serializer library works, and pick the modeling
approach that best fits your needs.

Message handling
So far this article has only discussed sending events to IoT Hub, and hasn't addressed receiving messages. The
reason for this is that what we need to know about receiving messages has largely been covered in an earlier
article. Recall from that article that you process messages by registering a message callback function:

IoTHubClient_SetMessageCallback(iotHubClientHandle, IoTHubMessage, myWeather)

You then write the callback function that’s invoked when a message is received:
static IOTHUBMESSAGE_DISPOSITION_RESULT IoTHubMessage(IOTHUB_MESSAGE_HANDLE message, void*
userContextCallback)
{
IOTHUBMESSAGE_DISPOSITION_RESULT result;
const unsigned char* buffer;
size_t size;
if (IoTHubMessage_GetByteArray(message, &buffer, &size) != IOTHUB_MESSAGE_OK)
{
printf("unable to IoTHubMessage_GetByteArray\r\n");
result = EXECUTE_COMMAND_ERROR;
}
else
{
/*buffer is not zero terminated*/
char* temp = malloc(size + 1);
if (temp == NULL)
{
printf("failed to malloc\r\n");
result = EXECUTE_COMMAND_ERROR;
}
else
{
memcpy(temp, buffer, size);
temp[size] = '\0';
EXECUTE_COMMAND_RESULT executeCommandResult = EXECUTE_COMMAND(userContextCallback, temp);
result =
(executeCommandResult == EXECUTE_COMMAND_ERROR) ? IOTHUBMESSAGE_ABANDONED :
(executeCommandResult == EXECUTE_COMMAND_SUCCESS) ? IOTHUBMESSAGE_ACCEPTED :
IOTHUBMESSAGE_REJECTED;
free(temp);
}
}
return result;
}

This implementation of IoTHubMessage calls the specific function for each action in your model. For example, if
your model defines this action:

WITH_ACTION(SetAirResistance, int, Position)

You must define a function with this signature:

EXECUTE_COMMAND_RESULT SetAirResistance(ContosoAnemometer* device, int Position)

{
(void)device;
(void)printf("Setting Air Resistance Position to %d.\r\n", Position);
return EXECUTE_COMMAND_SUCCESS;
}

SetAirResistance is then called when that message is sent to your device.

What we haven't explained yet is what the serialized version of message looks like. In other words, if you want to
send a SetAirResistance message to your device, what does that look like?
If you're sending a message to a device, you would do so through the Azure IoT service SDK. You still need to know
what string to send to invoke a particular action. The general format for sending a message appears as follows:

{"Name" : "", "Parameters" : "" }

You're sending a serialized JSON object with two properties: Name is the name of the action (message) and
Parameters contains the parameters of that action.
For example, to invoke SetAirResistance you can send this message to a device:

{"Name" : "SetAirResistance", "Parameters" : { "Position" : 5 }}

The action name must exactly match an action defined in your model. The parameter names must match as well.
Also note case sensitivity. Name and Parameters are always uppercase. Make sure to match the case of your
action name and parameters in your model. In this example, the action name is "SetAirResistance" and not
"setairresistance".
The two other actions TurnFanOn and TurnFanOff can be invoked by sending these messages to a device:

{"Name" : "TurnFanOn", "Parameters" : {}}

{"Name" : "TurnFanOff", "Parameters" : {}}

This section described everything you need to know when sending events and receiving messages with the
serializer library. Before moving on, let's cover some parameters you can configure that control how large your
model is.

Macro configuration
If you’re using the Serializer library an important part of the SDK to be aware of is found in the azure-c-shared-
utility library. If you have cloned the Azure-iot-sdk-c repository from GitHub using the --recursive option, then you
will find this shared utility library here:

.\\c-utility

If you have not cloned the library, you can find it here.
Within the shared utility library, you will find the following folder:

azure-c-shared-utility\\macro\_utils\_h\_generator.

This folder contains a Visual Studio solution called macro_utils_h_generator.sln:

The program in this solution generates the macro_utils.h file. There’s a default macro_utils.h file included with the
SDK. This solution allows you to modify some parameters and then recreate the header file based on these
parameters.
The two key parameters to be concerned with are nArithmetic and nMacroParameters which are defined in
these two lines found in macro_utils.tt:
<#int nArithmetic=1024;#>
<#int nMacroParameters=124;/*127 parameters in one macro definition in C99 in chapter 5.2.4.1 Translation
limits*/#>

These values are the default parameters included with the SDK. Each parameter has the following meaning:
nMacroParameters – Controls how many parameters you can have in one DECLARE_MODEL macro definition.
nArithmetic – Controls the total number of members allowed in a model.
The reason these parameters are important is because they control how large your model can be. For example,
consider this model definition:

DECLARE_MODEL(MyModel,
WITH_DATA(int, MyData)
);

As mentioned previously, DECLARE_MODEL is just a C macro. The names of the model and the WITH_DATA
statement (yet another macro) are parameters of DECLARE_MODEL. nMacroParameters defines how many
parameters can be included in DECLARE_MODEL. Effectively, this defines how many data event and action
declarations you can have. As such, with the default limit of 124 this means that you can define a model with a
combination of about 60 actions and data events. If you try to exceed this limit, you'll receive compiler errors that
look similar to this:

The nArithmetic parameter is more about the internal workings of the macro language than your application. It
controls the total number of members you can have in your model, including DECLARE_STRUCT macros. If you
start seeing compiler errors such as this, then you should try increasing nArithmetic:

If you want to change these parameters, modify the values in the macro_utils.tt file, recompile the
macro_utils_h_generator.sln solution, and run the compiled program. When you do so, a new macro_utils.h file is
generated and placed in the .\common\inc directory.
In order to use the new version of macro_utils.h, remove the serializer NuGet package from your solution and in
its place include the serializer Visual Studio project. This enables your code to compile against the source code of
the serializer library. This includes the updated macro_utils.h. If you want to do this for simplesample_amqp, start
by removing the NuGet package for the serializer library from the solution:
Then add this project to your Visual Studio solution:

.\c\serializer\build\windows\serializer.vcxproj

When you're done, your solution should look like this:

Now when you compile your solution, the updated macro_utils.h is included in your binary.
Note that increasing these values high enough can exceed compiler limits. To this point, the nMacroParameters is
the main parameter with which to be concerned. The C99 spec specifies that a minimum of 127 parameters are
allowed in a macro definition. The Microsoft compiler follows the spec exactly (and has a limit of 127), so you won't
be able to increase nMacroParameters beyond the default. Other compilers might allow you to do so (for
example, the GNU compiler supports a higher limit).
So far we've covered just about everything you need to know about how to write code with the serializer library.
Before concluding, let's revisit some topics from previous articles that you may be wondering about.

The lower-level APIs

The sample application on which this article focused is simplesample_amqp. This sample uses the higher-level
(the non-"LL") APIs to send events and receive messages. If you use these APIs, a background thread runs which
takes care of both sending events and receiving messages. However, you can use the lower-level (LL) APIs to
eliminate this background thread and take explicit control over when you send events or receive messages from
the cloud.
As described in a previous article, there is a set of functions that consists of the higher-level APIs:
IoTHubClient_CreateFromConnectionString
IoTHubClient_SendEventAsync
IoTHubClient_SetMessageCallback
IoTHubClient_Destroy
These APIs are demonstrated in simplesample_amqp.
There is also an analogous set of lower-level APIs.
IoTHubClient_LL_CreateFromConnectionString
IoTHubClient_LL_SendEventAsync
IoTHubClient_LL_SetMessageCallback
IoTHubClient_LL_Destroy
Note that the lower-level APIs work exactly the same way as described in the previous articles. You can use the first
set of APIs if you want a background thread to handle sending events and receiving messages. You use the second
set of APIs if you want explicit control over when you send and receive data from IoT Hub. Either set of APIs work
equally well with the serializer library.
For an example of how the lower-level APIs are used with the serializer library, see the simplesample_http
application.

Additional topics
A few other topics worth mentioning again are property handling, using alternate device credentials, and
configuration options. These are all topics covered in a previous article. The main point is that all of these features
work in the same way with the serializer library as they do with the IoTHubClient library. For example, if you
want to attach properties to an event from your model, you use IoTHubMessage_Properties and
Map_AddorUpdate, the same way as described previously:

MAP_HANDLE propMap = IoTHubMessage_Properties(message.messageHandle);

sprintf_s(propText, sizeof(propText), "%d", i);
Map_AddOrUpdate(propMap, "SequenceNumber", propText);

Whether the event was generated from the serializer library or created manually using the IoTHubClient library
does not matter.
For the alternate device credentials, using IoTHubClient_LL_Create works just as well as
IoTHubClient_CreateFromConnectionString for allocating an IOTHUB_CLIENT_HANDLE.
Finally, if you're using the serializer library, you can set configuration options with IoTHubClient_LL_SetOption
just as you did when using the IoTHubClient library.
A feature that is unique to the serializer library are the initialization APIs. Before you can start working with the
library, you must call serializer_init:

serializer_init(NULL);
This is done just before you call IoTHubClient_CreateFromConnectionString.
Similarly, when you're done working with the library, the last call you’ll make is to serializer_deinit:

serializer_deinit();

Otherwise, all of the other features listed above work the same in the serializer library as they do in the
IoTHubClient library. For more information about any of these topics, see the previous article in this series.

Next steps
This article describes in detail the unique aspects of the serializer library contained in the Azure IoT device SDK
for C. With the information provided you should have a good understanding of how to use models to send events
and receive messages from IoT Hub.
This also concludes the three-part series on how to develop applications with the Azure IoT device SDK for C.
This should be enough information to not only get you started but give you a thorough understanding of how the
APIs work. For additional information, there are a few samples in the SDK not covered here. Otherwise, the SDK
documentation is a good resource for additional information.
To learn more about developing for IoT Hub, see the Azure IoT SDKs.
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Comparison of Azure IoT Hub and Azure Event Hubs
1/31/2017 • 2 min to read • Edit on GitHub

One of the main use cases for IoT Hub is to gather telemetry from devices. For this reason, IoT Hub is often
compared to Azure Event Hubs. Like IoT Hub, Event Hubs is an event processing service that enables event and
telemetry ingress to the cloud at massive scale, with low latency and high reliability.
However, the services have many differences, which are detailed in the following table:

AREA IOT HUB EVENT HUBS

Communication patterns Enables device-to-cloud Only enables event ingress (usually

communications (messaging, file considered for device-to-cloud
uploads, and reported properties) and scenarios).
cloud-to-device communications (direct
methods, desired properties,
messaging).

Device state information Device twins can store and query device No device state information can be
state information. stored.

Device protocol support Supports MQTT, MQTT over Supports AMQP, AMQP over
WebSockets, AMQP, AMQP over WebSockets, and HTTP.
WebSockets, and HTTP. Additionally,
IoT Hub works with the Azure IoT
protocol gateway, a customizable
protocol gateway implementation to
support custom protocols.

Security Provides per-device identity and Provides Event Hubs-wide shared

revocable access control. See the access policies, with limited revocation
Security section of the IoT Hub support through publisher's policies.
developer guide. IoT solutions are often required to
implement a custom solution to
support per-device credentials and
anti-spoofing measures.

Operations monitoring Enables IoT solutions to subscribe to a Exposes only aggregate metrics.
rich set of device identity management
and connectivity events such as
individual device authentication errors,
throttling, and bad format exceptions.
These events enable you to quickly
identify connectivity problems at the
individual device level.

Scale Is optimized to support millions of Can support a more limited number of

simultaneously connected devices. simultaneous connections--up to 5,000
AMQP connections, as per Azure
Service Bus quotas. On the other hand,
Event Hubs enables you to specify the
partition for each message sent.
AREA IOT HUB EVENT HUBS

Device SDKs Provides device SDKs for a large variety Is supported on .NET, Java, and C, in
of platforms and languages, in addition addition to AMQP and HTTP send
to direct MQTT, AMQP, and HTTP APIs. interfaces.

File upload Enables IoT solutions to upload files Not supported.

from devices to the cloud. Includes a file
notification endpoint for workflow
integration and an operations
monitoring category for debugging
support.

Route messages to multiple endpoints Up to 10 custom endpoints are Requires additional code to be written
supported. Rules determine how and hosted for message dispatching.
messages are routed to custom
endpoints. For more information, see
Send and receive messages with IoT
Hub.

In summary, even if the only use case is device-to-cloud telemetry ingress, IoT Hub provides a service that is
designed for IoT device connectivity. It continues to expand the value propositions for these scenarios with IoT-
specific features. Event Hubs is designed for event ingress at a massive scale, both in the context of inter-
datacenter and intra-datacenter scenarios.
It is not uncommon to use both IoT Hub and Event Hubs in the same solution. IoT Hub handles the device-to-cloud
communication, and Event Hubs handles later-stage event ingress into real-time processing engines.
Next steps
To learn more about planning your IoT Hub deployment, see Scaling, HA, and DR.
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
Scaling IoT Hub
1/17/2017 • 1 min to read • Edit on GitHub

Azure IoT Hub can support up to a million simultaneously connected devices. For more information, see IoT Hub
pricing. Each IoT Hub unit allows a certain number of daily messages.
To properly scale your solution, consider your particular use of IoT Hub. In particular, consider the required peak
throughput for the following categories of operations:
Device-to-cloud messages
Cloud-to-device messages
Identity registry operations
In addition to this throughput information, see IoT Hub quotas and throttles and design your solution accordingly.

Device-to-cloud and cloud-to-device message throughput

The best way to size an IoT Hub solution is to evaluate the traffic on a per-unit basis.
Device-to-cloud messages follow these sustained throughput guidelines.

TIER SUSTAINED THROUGHPUT SUSTAINED SEND RATE

S1 Up to 1111 KB/minute per unit Average of 278 messages/minute per

(1.5 GB/day/unit) unit
(400,000 messages/day per unit)

S2 Up to 16 MB/minute per unit Average of 4167 messages/minute per

(22.8 GB/day/unit) unit
(6 million messages/day per unit)

S3 Up to 814 MB/minute per unit Average of 208,333 messages/minute

(1144.4 GB/day/unit) per unit
(300 million messages/day per unit)

Identity registry operation throughput

IoT Hub identity registry operations are not supposed to be run-time operations, as they are mostly related to
device provisioning.
For specific burst performance numbers, see IoT Hub quotas and throttles.

Sharding
While a single IoT hub can scale to millions of devices, sometimes your solution requires specific performance
characteristics that a single IoT hub cannot guarantee. In that case, it is recommended that you partition your
devices into multiple IoT hubs. Multiple IoT hubs smooth traffic bursts and obtain the required throughput or
operation rates that are required.

Next steps
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
IoT Hub high availability and disaster recovery
1/24/2017 • 3 min to read • Edit on GitHub

As an Azure service, IoT Hub provides high availability (HA) using redundancies at the Azure region level, without
any additional work required by the solution. The Microsoft Azure platform also includes features to help you build
solutions with disaster recovery (DR) capabilities or cross-region availability. If you want to provide global, cross-
region high availability for devices or users, design and prepare your solutions to take advantage of these Azure DR
features. The article Azure Business Continuity Technical Guidance describes the built-in features in Azure for
business continuity and DR. The Disaster recovery and high availability for Azure applications paper provides
architecture guidance on strategies for Azure applications to achieve HA and DR.

Azure IoT Hub DR

In addition to intra-region HA, IoT Hub implements failover mechanisms for disaster recovery that require no
intervention from the user. IoT Hub DR is self-initiated and has a recovery time objective (RTO) of 2-26 hours, and
the following recovery point objectives (RPOs).

FUNCTIONALITY RPO

Service availability for registry and communication operations Possible CName loss

Identity data in identity registry 0-5 mins data loss

Device-to-cloud messages All unread messages are lost

Operations monitoring messages All unread messages are lost

Cloud-to-device messages 0-5 mins data loss

Cloud-to-device feedback queue All unread messages are lost

Regional failover with IoT Hub

A complete treatment of deployment topologies in IoT solutions is outside the scope of this article. The article
discusses the regional failover deployment model for the purpose of high availability and disaster recovery.
In a regional failover model, the solution back end runs primarily in one datacenter location, and a secondary IoT
hub and back end are deployed in another datacenter location. If the IoT hub in the primary datacenter suffers an
outage or the network connectivity from the device to the primary datacenter is interrupted. Devices use a
secondary service endpoint whenever the primary gateway cannot be reached. With a cross-region failover
capability, the solution availability can be improved beyond the high availability of a single region.
At a high level, to implement a regional failover model with IoT Hub, you need the following:
A secondary IoT hub and device routing logic: In the case of a service disruption in your primary region,
devices must start connecting to your secondary region. Given the state-aware nature of most services involved,
it is common for solution administrators to trigger the inter-region failover process. The best way to
communicate the new endpoint to devices, while maintaining control of the process, is to have them regularly
check a concierge service for the current active endpoint. The concierge service can be a web application that is
replicated and kept reachable using DNS-redirection techniques (for example, using Azure Traffic Manager).
Identity registry replication - To be usable, the secondary IoT hub must contain all device identities that can
connect to the solution. The solution should keep geo-replicated backups of device identities, and upload them
to the secondary IoT hub before switching the active endpoint for the devices. The device identity export
functionality of IoT Hub is useful in this context. For more information, see IoT Hub developer guide - identity
registry.
Merging logic - When the primary region becomes available again, all the state and data that have been
created in the secondary site must be migrated back to the primary region. This state and data mostly relates to
device identities and application metadata, which must be merged with the primary IoT hub and any other
application-specific stores in the primary region. To simplify this step, you should use idempotent operations.
Idempotent operations minimize the side-effects from the eventual consistent distribution of events, and from
duplicates or out-of-order delivery of events. In addition, the application logic should be designed to tolerate
potential inconsistencies or "slightly" out of date-state. This situation can occur due to the additional time it
takes for the system to "heal" based on recovery point objectives (RPO).

Next steps
Follow these links to learn more about Azure IoT Hub:
Get started with IoT Hubs (Tutorial)
What is Azure IoT Hub?
Support additional protocols for IoT Hub
1/17/2017 • 1 min to read • Edit on GitHub

Azure IoT Hub natively supports communication over the MQTT, AMQP, and HTTP protocols. In some cases,
devices or field gateways might not be able to use one of these standard protocols and will require protocol
adaptation. In such cases, you can use a custom gateway. A custom gateway can enable protocol adaptation for
IoT Hub endpoints by bridging the traffic to and from IoT Hub. You can use the Azure IoT protocol gateway as a
custom gateway to enable protocol adaptation for IoT Hub.

Azure IoT protocol gateway

The Azure IoT protocol gateway is a framework for protocol adaptation that is designed for high-scale,
bidirectional device communication with IoT Hub. The protocol gateway is a pass-through component that accepts
device connections over a specific protocol. It bridges the traffic to IoT Hub over AMQP 1.0. The Azure IoT protocol
gateway is available as an open-source software project to provide flexibility for adding support for various
protocols and protocol versions.
You can deploy the protocol gateway in Azure in a highly scalable way by using Azure Service Fabric, Azure Cloud
Services worker roles, or Windows Virtual Machines. In addition, the protocol gateway can be deployed in on-
premises environments, such as field gateways.
The Azure IoT protocol gateway includes an MQTT protocol adapter that enables you to customize the MQTT
protocol behavior if necessary. Since IoT Hub provides built-in support for the MQTT v3.1.1 protocol, you should
only consider using the MQTT protocol adapter if protocol customizations or specific requirements for additional
functionality are required.
The MQTT adapter also demonstrates the programming model for building protocol adapters for other protocols.
In addition, the Azure IoT protocol gateway programming model allows you to plug in custom components for
specialized processing such as custom authentication, message transformations, compression/decompression, or
encryption/decryption of traffic between the devices and IoT Hub.
For flexibility, the protocol gateway and MQTT implementation are provided in an open-source software project.
This allows you to customize the implementation as needed.

Next steps
To learn more about the Azure IoT protocol gateway and how to use and deploy it as part of your IoT solution, see:
Azure IoT protocol gateway repository on GitHub
Azure IoT protocol gateway developer guide
To learn more about planning your IoT Hub deployment, see:
Compare with Event Hubs
Scaling, HA and DR
IoT Hub developer guide
Azure IoT Hub developer guide
1/31/2017 • 2 min to read • Edit on GitHub

Azure IoT Hub is a fully managed service that helps enable reliable and secure bi-directional communications
between millions of devices and a solution back end.
Azure IoT Hub provides you with:
Secure communications by using per-device security credentials and access control.
Multiple device-to-cloud and cloud-to-device hyper-scale communication options.
Queryable storage of per-device state information and meta-data.
Easy device connectivity with device libraries for the most popular languages and platforms.
This IoT Hub developer guide includes the following articles:
Send and receive messages with IoT Hub describes the messaging features (device-to-cloud and cloud-to-
device) that IoT Hub exposes. The article also includes information about topics such as message routing,
message formats, and the supported communications protocols and the port numbers they use.
Device-to-cloud communication guidance helps you choose between device-to-cloud messages, device
twin's reported properties, and file upload.
Cloud-to-device communication guidance helps you choose between direct methods, device twin's desired
properties, and cloud-to-device messages.
Upload files from a device describes how you can upload files from a device. The article also includes
information about topics such as the notifications the upload process can send.
Manage device identities in IoT Hub describes what information each IoT hub's identity registry stores, and
how you can access and modify it.
Control access to IoT Hub describes the security model used to grant access to IoT Hub functionality for
both devices and cloud components. The article includes information about using tokens and X.509
certificates, and details of the permissions you can grant.
Use device twins to synchronize state and configurations describes the device twin concept and the
functionality it exposes such as synchronizing a device with its device twin. The article includes information
about the data stored in a device twin.
Invoke a direct method on a device describes the lifecycle of a direct method, information about how to
invoke methods on a device from your back-end app and handle the direct method on your device.
Schedule jobs on multiple devices describes how you can schedule jobs on multiple devices. The article
describes how to submit jobs that perform tasks as executing a direct method, updating a device using a
device twin. It also describes how to query the status of a job.
Reference - IoT Hub endpoints describes the various endpoints that each IoT hub exposes for runtime and
management operations. The article also describes how you can create additional endpoints in your IoT hub,
and how to use a field gateway to enable devices connectivity to your IoT Hub endpoints in non-standard
scenarios.
Reference - IoT Hub query language for device twins and jobs describes that IoT Hub query language that
enables you to retrieve information from your hub about your device twins and jobs.
Reference - quotas and throttling summarizes the quotas set in the IoT Hub service and the throttling
behavior you can expect to see when you exceed a quota.
Reference - pricing provides general information on different SKUs and pricing for IoT Hub and details on
how the various IoT Hub functionalities are metered as messages by IoT Hub.
Reference - Device and service SDKs lists the Azure IoT SDKs you can use to develop both device and service
apps that interact with your IoT hub. The article includes links to online API documentation.
Reference - IoT Hub MQTT support provides detailed information about how IoT Hub supports the MQTT
protocol. The article describes the support for the MQTT protocol built-in to the Azure IoT SDKs and
provides information about using the MQTT protocol directly.
Glossary a list of common IoT Hub-related terms.
Send and receive messages with IoT Hub
2/2/2017 • 19 min to read • Edit on GitHub

Overview
IoT Hub provides the following messaging primitives to communicate with a device:
Device-to-cloud from a device to a back-end app.
Cloud-to-device from a back-end app (service or cloud).
Core properties of IoT Hub messaging functionality are the reliability and durability of messages. These
properties enable resilience to intermittent connectivity on the device side, and to load spikes in event
processing on the cloud side. IoT Hub implements at least once delivery guarantees for both device-to-cloud and
cloud-to-device messaging.
IoT Hub supports multiple device-facing protocols (such as MQTT, AMQP, and HTTP). To support seamless
interoperability across protocols, IoT Hub defines a common message format that all device-facing protocols
support.
IoT Hub exposes a built-in Event Hub-compatible endpoint to enable back-end apps to read the device-to-cloud
messages received by the hub. You can also create custom endpoints in your IoT hub by linking other services in
your subscription to the hub.
When to use
Use device-to-cloud messages for sending time series telemetry and alerts from your device app, and cloud-to-
device messages for one-way notifications to the device app.
Refer to Device-to-cloud communication guidance if in doubt between using reported properties, device-to-
cloud messages, or file upload. Refer to Cloud-to-device communication guidance if in doubt between using
desired properties, direct methods, or cloud-to-device messages.
For a comparison of the IoT Hub and Event Hubs services, see Comparison of IoT Hub and Event Hubs.

Device-to-cloud messages
You send device-to-cloud messages through a device-facing endpoint
(/devices/{deviceId}/messages/events). Routing rules then route your messages to one of the service-facing
endpoints on your IoT hub. Routing rules use the properties of the device-to-cloud messages flowing through
your hub to determine where to route them. By default, messages are routed to the built-in service-facing
endpoint (messages/events), that is compatible with Event Hubs. Therefore, you can use standard Event Hubs
integration and SDKs to receive device-to-cloud messages.
IoT Hub implements device-to-cloud messaging using a streaming messaging pattern. IoT Hub's device-to-cloud
messages are more like Event Hubs events than Service Bus messages in that there is a high volume of events
passing through the service that can be read by multiple readers.
This implementation has the following implications:
Like Event Hubs events, device-to-cloud messages are durable and retained in an IoT hub's default
messages/events endpoint for up to seven days.
Like Event Hubs events, device-to-cloud messages can be at most 256 KB, and can be grouped in batches to
optimize sends. Batches can be at most 256 KB.
There are, however, a few important distinctions between IoT Hub device-to-cloud messaging and Event Hubs:
As explained in the Control access to IoT Hub section, IoT Hub allows per-device authentication and access
control.
IoT Hub allows you to create up to 10 custom endpoints. Messages are delivered to the endpoints based on
routes configured on your IoT hub.
IoT Hub allows millions of simultaneously connected devices (see Quotas and throttling), while Event Hubs is
limited to 5000 AMQP connections per namespace.
IoT Hub does not allow arbitrary partitioning using a PartitionKey. Device-to-cloud messages are
partitioned based on their originating deviceId.
Scaling IoT Hub is slightly different than scaling Event Hubs. For more information, see Scaling IoT Hub.
For details about how to use device-to-cloud messaging, see Azure IoT SDKs.
For details about how to set up message routing, see Routing rules.

NOTE
When using HTTP to send device-to-cloud messages, property names and values can only contain ASCII alphanumeric
characters, plus {'!', '#', '$', '%, '&', "'", '*', '*', '+', '-', '.', '^', '_', '`', '|', '~'} .

Non-telemetry traffic
Often, in addition to telemetry data points, devices send messages and requests that require separate execution
and handling from the application business logic layer. For example, critical alerts that must trigger a specific
action in the back end. You can easily write a routing rule to send these types of messages to an endpoint
dedicated to their processing.
For more information about the best way to process this kind of message, see the Tutorial: How to process IoT
Hub device-to-cloud messages tutorial.
Routing rules
IoT Hub enables you to route messages to IoT Hub endpoints based on message properties. Routing rules give
you the flexibility to send messages where they need to go without the need to stand up additional services to
process messages or to write additional code. Each routing rule you configure has the following properties:
Name. The unique name that identifies the rule.
Source. The origin of the data stream to be acted upon. For example, device telemetry.
Condition. The query expression for the routing rule that is run against the message's properties and used
to determine whether it is a match for the endpoint. For more information about constructing a route
condition, see the Reference - query language for device twins and jobs.
Endpoint. The name of the endpoint where IoT Hub sends messages that match the condition. Endpoints
should be in the same region as the IoT hub, otherwise you may be charged for cross-region writes.
A single message may match the condition on multiple routing rules, in which case IoT Hub delivers the
message to the endpoint associated with each matched rule. IoT Hub also automatically deduplicates message
delivery, so if a message matches multiple rules that all have the same destination, it is only written to that
destination once.
For more information about creating custom endpoints in IoT Hub, see IoT Hub endpoints.
Built-in endpoint: messages/events
An IoT hub exposes the following properties to enable you to control the built-in messaging endpoint
messages/events.
Partition count. Set this property at creation to define the number of partitions for device-to-cloud event
ingestion.
Retention time. This property specifies the retention time for device-to-cloud messages. The default is one
day, but it can be increased to seven days.
IoT Hub also enables you to manage consumer groups on the built-in device-to-cloud receive endpoint.
By default, all messages that do not explicitly match a message routing rule are written to the built-in endpoint. If
you disable this fallback route, messages that do not explicitly match any message routing rules are dropped.
You can modify the retention time, either programmatically through the IoT Hub resource provider REST APIs, or
by using the Azure portal.
Anti-spoofing properties
To avoid device spoofing in device-to-cloud messages, IoT Hub stamps all messages with the following
properties:
ConnectionDeviceId
ConnectionDeviceGenerationId
ConnectionAuthMethod
The first two contain the deviceId and generationId of the originating device, as per Device identity properties.
The ConnectionAuthMethod property contains a JSON serialized object, with the following properties:

{
"scope": "{ hub | device}",
"type": "{ symkey | sas}",
"issuer": "iothub"
}

Cloud-to-device messages
You send cloud-to-device messages through a service-facing endpoint (/messages/devicebound). A device
receives them through a device-specific endpoint (/devices/{deviceId}/messages/devicebound).
Each cloud-to-device message is targeted at a single device by setting the to property to
/devices/{deviceId}/messages/devicebound.

IMPORTANT
Each device queue holds at most 50 cloud-to-device messages. Trying to send more messages to the same device results
in an error.

NOTE
When you send cloud-to-device messages, property names and values can only contain ASCII alphanumeric characters,
plus {'!', '#', '$', '%, '&', "'", '*', '*', '+', '-', '.', '^', '_', '`', '|', '~'} .

Message lifecycle
To guarantee at least once message delivery, IoT Hub persists cloud-to-device messages in per-device queues.
Devices must explicitly acknowledge completion for IoT Hub to remove them from the queue. This guarantees
resiliency against connectivity and device failures.
The following diagram shows the lifecycle state graph for a cloud-to-device message.
When the service sends a message, it is considered Enqueued. When a device wants to receive a message, IoT
Hub locks the message (sets the state to Invisible) allowing other threads on the same device to start receiving
other messages. When a device thread completes the processing of a message, it notifies IoT Hub by completing
the message.
A device can also:
Reject the message, which causes IoT Hub to set it to the Deadlettered state. Note: devices connecting with
MQTT cannot reject cloud-to-device messages.
Abandon the message, which causes IoT Hub to put the message back in the queue, with the state set to
Enqueued.
A thread could fail to process a message without notifying IoT Hub. In this case, messages automatically
transition from the Invisible state back to the Enqueued state after a visibility (or lock) timeout. The default
value of this timeout is one minute.
A message can transition between the Enqueued and Invisible states for, at most, the number of times
specified in the max delivery count property on IoT Hub. After that number of transitions, IoT Hub sets the
state of the message to Deadlettered. Similarly, IoT Hub sets the state of a message to Deadlettered after its
expiration time (see Time to live).
For a tutorial on cloud-to-device messages, see Tutorial: How to send cloud-to-device messages with IoT Hub.
For reference topics on how the different Azure IoT SDKs expose the cloud-to-device functionality, see Azure IoT
SDKs.

NOTE
Typically, cloud-to-device messages complete whenever the loss of the message would not affect the application logic. For
example, the message content has been successfully persisted in local storage, or an operation has been successfully
executed. The message could also be carrying transient information, whose loss would not impact the functionality of the
application. Sometimes, for long-running tasks, you can complete the cloud-to-device message after persisting the task
description in local storage. Then you can notify the solution back end with one or more device-to-cloud messages at
various stages of progress of the task.

Message expiration (time to live )

Every cloud-to-device message has an expiration time. This time is set either by the service (in the
ExpiryTimeUtc property), or by IoT Hub using the default time to live specified as an IoT Hub property. See
Cloud-to-device configuration options.
NOTE
A common way to take advantage of message expiration and avoid sending messages to disconnected devices, is to set
short time to live values. This approach achieves the same result as maintaining the device connection state, while being
more efficient. When you request message acknowledgements, IoT Hub notifies you which devices are able to receive
messages, and which devices are not online or have failed.

Message feedback
When you send a cloud-to-device message, the service can request the delivery of per-message feedback
regarding the final state of that message.
If you set the Ack property to positive, IoT Hub generates a feedback message if, and only if, the cloud-to-
device message reached the Completed state.
If you set the Ack property to negative, IoT Hub generates a feedback message, if and only if, the cloud-to-
device message reaches the Deadlettered state.
If you set the Ack property to full, IoT Hub generates a feedback message in either case.

NOTE
If Ack is full, and you don't receive a feedback message, it means that the feedback message expired. The service can't
know what happened to the original message. In practice, a service should ensure that it can process the feedback before
it expires. The maximum expiry time is two days, which allows plenty of time to get the service running again if a failure
occurs.

As explained in Endpoints, IoT Hub delivers feedback through a service-facing endpoint

(/messages/servicebound/feedback) as messages. The semantics for receiving feedback are the same as for
cloud-to-device messages, and have the same Message lifecycle. Whenever possible, message feedback is
batched in a single message, with the following format:

PROPERTY DESCRIPTION

EnqueuedTime Timestamp indicating when the message was created.

UserId {iot hub name}

ContentType application/vnd.microsoft.iothub.feedback.json

The body is a JSON-serialized array of records, each with the following properties:

PROPERTY DESCRIPTION

EnqueuedTimeUtc Timestamp indicating when the outcome of the message

happened. For example, the device completed or the
message expired.

OriginalMessageId MessageId of the cloud-to-device message to which this

feedback information pertains.
PROPERTY DESCRIPTION

StatusCode Required integer. Used in feedback messages generated by

IoT Hub.
0 = success
1 = message expired
2 = maximum delivery count exceeded
3 = message rejected

Description String values for StatusCode.

DeviceId DeviceId of the target device of the cloud-to-device

message to which this piece of feedback pertains.

DeviceGenerationId DeviceGenerationId of the target device of the cloud-to-

device message to which this piece of feedback pertains.

IMPORTANT
The service must specify a MessageId for the cloud-to-device message to be able to correlate its feedback with the
original message.

The following example shows the body of a feedback message.

[
{
"OriginalMessageId": "0987654321",
"EnqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
"StatusCode": 0
"Description": "Success",
"DeviceId": "123",
"DeviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
},
{
...
},
...
]

Cloud-to -device configuration options

Each IoT hub exposes the following configuration options for cloud-to-device messaging.

PROPERTY DESCRIPTION RANGE AND DEFAULT

defaultTtlAsIso8601 Default TTL for cloud-to-device ISO_8601 interval up to 2D (minimum

messages. 1 minute). Default: 1 hour.

maxDeliveryCount Maximum delivery count for cloud-to- 1 to 100. Default: 10.

device per-device queues.

feedback.ttlAsIso8601 Retention for service-bound feedback ISO_8601 interval up to 2D (minimum

messages. 1 minute). Default: 1 hour.

feedback.maxDeliveryCount Maximum delivery count for feedback 1 to 100. Default: 100.

queue.
For more information, see Create IoT hubs.

Read device-to-cloud messages

IoT Hub exposes the messages/events built-in endpoint for your back-end services to read the device-to-cloud
messages received by your hub. This endpoint is Event Hubs-compatible, which enables you to use any of the
mechanisms the Event Hubs service supports for reading messages.
You can also create custom endpoints in IoT Hub. IoT Hub currently supports Event Hubs, Service Bus queues,
and Service Bus topics as custom endpoints. For more information about reading from those services, see:
reading from Event Hubs, reading from Service Bus queues, reading from Service Bus topics.
Reading from the built-in endpoint
When you use the Azure Service Bus SDK for .NET or the Event Hubs - Event Processor Host, you can use any IoT
Hub connection strings with the correct permissions. Then use messages/events as the Event Hub name.
When you use SDKs (or product integrations) that are unaware of IoT Hub, you must retrieve an Event Hub-
compatible endpoint and Event Hub-compatible name from the IoT Hub settings in the Azure portal:
1. In the IoT hub blade, click Endpoints.
2. In the Built-in endpoints section, click Events. The blade contains the following values: Event Hub-
compatible endpoint, Event Hub-compatible name, Partitions, Retention time, and Consumer
groups.

NOTE
The IoT Hub SDK requires the IoT Hub endpoint name, which is messages/events as shown in the Endpoints blade.

NOTE
If the SDK you are using requires a Hostname or Namespace value, remove the scheme from the Event Hub-
compatible endpoint. For example, if your Event Hub-compatible endpoint is sb://iothub-ns-myiothub-
1234.servicebus.windows.net/, the Hostname would be iothub-ns-myiothub-1234.servicebus.windows.net, and
the Namespace would be iothub-ns-myiothub-1234.

You can then use any shared access policy that has the ServiceConnect permissions to connect to the specified
Event Hub.
If you need to build an Event Hub connection string by using the previous information, use the following pattern:
Endpoint={Event Hub-compatible endpoint};SharedAccessKeyName={iot hub policy name};SharedAccessKey={iot hub
policy key}

The following is a list of SDKs and integrations that you can use with Event Hub-compatible endpoints that IoT
Hub exposes:
Java Event Hubs client
Apache Storm spout. You can view the spout source on GitHub.
Apache Spark integration

Reference topics:
The following reference topics provide you with more information about exchanging messages with IoT Hub.

Message format
IoT Hub messages comprise:
A set of system properties. Properties that IoT Hub interprets or sets. This set is predetermined.
A set of application properties. A dictionary of string properties that the application can define and access,
without needing to deserialize the message body. IoT Hub never modifies these properties.
An opaque binary body.
For more information about how the message is encoded in different protocols, see Azure IoT SDKs.
The following table lists the set of system properties in IoT Hub messages.

PROPERTY DESCRIPTION

MessageId A user-settable identifier for the message, used for request-

reply patterns. Format: A case-sensitive string (up to 128
characters long) of ASCII 7-bit alphanumeric characters +
{'-', ':',’.', '+', '%', '_', '#', '*', '?', '!',
'(', ')', ',', '=', '@', ';', '$', '''}
.

Sequence number A number (unique per device-queue) assigned by IoT Hub to

each cloud-to-device message.

To A destination specified in Cloud-to-Device messages.

ExpiryTimeUtc Date and time of message expiration.

EnqueuedTime Date and time the message was received by IoT Hub.

CorrelationId A string property in a response message that typically

contains the MessageId of the request, in request-reply
patterns.

UserId An ID used to specify the origin of messages. When

messages are generated by IoT Hub, it is set to
{iot hub name} .
PROPERTY DESCRIPTION

Ack A feedback message generator. This property is used in

cloud-to-device messages to request IoT Hub to generate
feedback messages as a result of the consumption of the
message by the device. Possible values: none (default): no
feedback message is generated, positive: receive a feedback
message if the message was completed, negative: receive a
feedback message if the message expired (or maximum
delivery count was reached) without being completed by the
device, or full: both positive and negative. For more
information, see Message feedback.

ConnectionDeviceId An ID set by IoT Hub on device-to-cloud messages. It

contains the deviceId of the device that sent the message.

ConnectionDeviceGenerationId An ID set by IoT Hub on device-to-cloud messages. It

contains the generationId (as per Device identity
properties) of the device that sent the message.

ConnectionAuthMethod An authentication method set by IoT Hub on device-to-

cloud messages. This property contains information about
the authentication method used to authenticate the device
sending the message. For more information, see Device to
cloud anti-spoofing.

Message size
IoT Hub measures message size in a protocol-agnostic way, considering only the actual payload. The size in
bytes is calculated as the sum of the following:
The body size in bytes, plus
The size in bytes of all the values of the message system properties, plus
The size in bytes of all user property names and values.
Note that property names and values are limited to ASCII characters, so the length of the strings equals the size
in bytes.

Communication protocols
IoT Hub allows devices to use MQTT, MQTT over WebSockets, AMQP, AMQP over WebSockets, and HTTP
protocols for device-side communications. The following table provides the high-level recommendations for
your choice of protocol:

PROTOCOL WHEN YOU SHOULD CHOOSE THIS PROTOCOL

MQTT Use on all devices that do not require to connect multiple

MQTT over WebSocket devices (each with its own per-device credentials) over the
same TLS connection.

AMQP Use on field and cloud gateways to take advantage of

AMQP over WebSocket connection multiplexing across devices.

HTTP Use for devices that cannot support other protocols.

Consider the following points when you choose your protocol for device-side communications:
Cloud-to-device pattern. HTTP does not have an efficient way to implement server push. As such, when
you are using HTTP, devices poll IoT Hub for cloud-to-device messages. This approach is inefficient for both
the device and IoT Hub. Under current HTTP guidelines, each device should poll for messages every 25
minutes or more. On the other hand, MQTT and AMQP support server push when receiving cloud-to-device
messages. They enable immediate pushes of messages from IoT Hub to the device. If delivery latency is a
concern, MQTT or AMQP are the best protocols to use. For rarely connected devices, HTTP works as well.
Field gateways. When using MQTT and HTTP, you cannot connect multiple devices (each with its own per-
device credentials) using the same TLS connection. Thus, for Field gateway scenarios, these protocols are
suboptimal because they require one TLS connection between the field gateway and IoT Hub for each device
connected to the field gateway.
Low resource devices. The MQTT and HTTP libraries have a smaller footprint than the AMQP libraries. As
such, if the device has limited resources (for example, less than 1 MB RAM), these protocols might be the only
protocol implementation available.
Network traversal. The standard AMQP protocol uses port 5671, while MQTT listens on port 8883, which
could cause problems in networks that are closed to non-HTTP protocols. MQTT over WebSockets, AMQP
over WebSockets, and HTTP are available to be used in this scenario.
Payload size. MQTT and AMQP are binary protocols, which result in more compact payloads than HTTP.

NOTE
When using HTTP, each device should poll for cloud-to-device messages every 25 minutes or more. However, during
development, it is acceptable to poll more frequently than every 25 minutes.

Port numbers
Devices can communicate with IoT Hub in Azure using various protocols. Typically, the choice of protocol is
driven by the specific requirements of the solution. The following table lists the outbound ports that must be
open for a device to be able to use a specific protocol:

PROTOCOL PORT

MQTT 8883

MQTT over WebSockets 443

AMQP 5671

AMQP over WebSockets 443

HTTP 443

LWM2M (Device management) 5684

Once you have created an IoT hub in an Azure region, the IoT hub keeps the same IP address for the lifetime of
that IoT hub. However, to maintain quality of service, if Microsoft moves the IoT hub to a different scale unit then
it is assigned a new IP address.

Notes on MQTT support

IoT Hub implements the MQTT v3.1.1 protocol with the following limitations and specific behavior:
QoS 2 is not supported. When a device app publishes a message with QoS 2, IoT Hub closes the network
connection. When a device app subscribes to a topic with QoS 2, IoT Hub grants maximum QoS level 1 in the
SUBACK packet.
Retain messages do not persist. If a device app publishes a message with the RETAIN flag set to 1, IoT Hub
adds the x-opt-retain application property to the message. In this case, IoT Hub does not persist the retain
message, but instead passes it to the back-end app.
For more information, see IoT Hub MQTT support.
As a final consideration, you should review the Azure IoT protocol gateway that enables you to deploy a high-
performance custom protocol gateway that interfaces directly with IoT Hub. The Azure IoT protocol gateway
enables you to customize the device protocol to accommodate brownfield MQTT deployments or other custom
protocols. This approach does require, however, that you run and operate a custom protocol gateway.

Additional reference material

Other reference topics in the IoT Hub developer guide include:
IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and management
operations.
Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to
expect when you use the service.
Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both
device and service apps that interact with IoT Hub.
IoT Hub query language for device twins and jobs describes the IoT Hub query language you can use to
retrieve information from IoT Hub about your device twins and jobs.
IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Next steps
Now you have learned how to send and receive messages with IoT Hub, you may be interested in the following
IoT Hub developer guide topics:
Upload files from a device
Manage device identities in IoT Hub
Control access to IoT Hub
Use device twins to synchronize state and configurations
Invoke a direct method on a device
Schedule jobs on multiple devices
If you would like to try out some of the concepts described in this article, you may be interested in the following
IoT Hub tutorials:
Get started with Azure IoT Hub
How to send cloud-to-device messages with IoT Hub
How to process IoT Hub device-to-cloud messages
Device-to-cloud communications guidance
1/17/2017 • 1 min to read • Edit on GitHub

When sending information from the device app to the solution back end, IoT Hub exposes three options:
Device-to-cloud (D2C) messages, for time series telemetry and alerts;
Reported properties, for reporting device state information such as available capabilities, conditions and state
of long-running workflows (e.g. configuration and software updates);
File uploads, for media files and large telemetry batches uploaded by intermittently connected devices or
compressed to save bandwidth.
Here is a detailed comparison of the various device-to-cloud communication options.

D2C MESSAGES REPORTED PROPERTIES FILE UPLOADS

Scenario Telemetry time series and Available capabilities and Media files. Large (usually
alerts, e.g. 256KB sensor conditions, e.g. device compressed) telemetry
data batches sent every current connectivity mode batches.
5mins. (cellular or wifi).
Synchronizing long-running
workflows, such as
configuration and software
updates.

Storage and retrieval Temporarily stored by IoT Stored by IoT Hub in the Stored in user-provided
Hub, up to 7 days. Only device twin. Retrievable Azure Storage account.
sequential reading. using the IoT Hub query
language.

Size Up to 256KB messages. Maximum reported Maximum file size supported

properties size is 8KB. by Azure Blob Storage.

Frequency High. Refer to IoT Hub limits Medium. Refer to IoT Hub Low. Refer to IoT Hub limits
for more information. limits for more information. for more information.

Protocol Available on all protocols. Currently available only Available when using any
when using MQTT. protocol, but requires HTTP
on the device.

NOTE
It is possible that an application requires to both send information as a telemetry time series or alert and also to make it
available in the device twin. In those cases, the device app can both send a D2C message and report a property change, or
the solution back end can store the information in the device twin's tags when it receives the message. Since D2C messages
allow much higher throughput than device twin updates, it is sometimes desirable to avoid updating the device twin for
every D2C message.
Cloud-to-device communications guidance
2/9/2017 • 1 min to read • Edit on GitHub

IoT Hub provides three options for device apps to expose functionality to a back-end app:
Direct methods, for communications that require immediate confirmation of their result, usually interactive
control of the device, e.g. turn on a fan;
Twin's desired properties, for long-running commands intended to put the device into a certain desired state.
For example, set the telemetry send interval to 30 minutes;
Cloud-to-device (C2D) messages, for one-way notifications to the device app.
Here is a detailed comparison of the various cloud-to-device communication options.

DIRECT METHODS TWIN'S DESIRED PROPERTIES C2D MESSAGES

Scenario Commands that require Long-running commands One-way notifications to the

immediate confirmation, e.g. intended to put the device device app.
turn on a fan. into a certain desired state.
For example, set the
telemetry send interval to
30 minutes.

Data flow Two-way. The device app One-way. The device app One-way. The device app
can respond to the method receives a notification with receives the message
right away. The solution the property change.
back end receives the
outcome contextually to the
request.

Durability Disconnected devices are Property values are Messages can retained by
not contacted. Back end is preserved in the device twin. IoT Hub for up to 48 hours.
notified that the device is Device will read it at next
not connected. reconnection. Property
values are retrievable with
the IoT Hub query language.

Targets Single device using Single device using Single device by deviceId.
deviceId, or multiple deviceId, or multiple
devices using jobs. devices using jobs.

Size Up to 8KB requests and 8KB Maximum desired properties Up to 64KB messages.
responses. size is 8KB.

Frequency High. Refer to IoT Hub limits Medium. Refer to IoT Hub Low. Refer to IoT Hub limits
for more information. limits for more information. for more information.

Protocol Currently available only Currently available only Available on all protocols.
when using MQTT. when using MQTT. Device must poll when using
HTTP.

Learn how to use direct methods, desired properties, and cloud-to-device messages in the following tutorials:
Use direct methods, for direct methods;
Use desired properties to configure devices, for device twin's desired properties;
Send cloud-to-device messages, for cloud-to-device messages.
File uploads with IoT Hub
1/17/2017 • 5 min to read • Edit on GitHub

Overview
As detailed in the IoT Hub endpoints article, devices can initiate file uploads by sending a notification through a
device-facing endpoint (/devices/{deviceId}/files). When a device notifies IoT Hub of a completed upload, IoT
Hub generates file upload notifications that you can receive through a service-facing endpoint
(/messages/servicebound/filenotifications) as messages.
Instead of brokering messages through IoT Hub itself, IoT Hub instead acts as a dispatcher to an associated Azure
Storage account. A device requests a storage token from IoT Hub that is specific to the file the device wishes to
upload. The device uses the SAS URI to upload the file to storage, and when the upload is complete the device
sends a notification of completion to IoT Hub. IoT Hub verifies that the file was uploaded and then adds a file
upload notification to the new service-facing file notification messaging endpoint.
Before you upload a file to IoT Hub from a device, you must configure your hub by associating an Azure Storage
account to it.
Your device can then initialize an upload and then notify IoT hub when the upload completes. Optionally, when a
device notifies IoT Hub that the upload is complete, the service can generate a notification message.
When to use
Use file upload to send media files and large telemetry batches uploaded by intermittently connected devices or
compressed to save bandwidth.
Refer to Device-to-cloud communication guidance if in doubt between using reported properties, device-to-cloud
messages, or file upload.

Associate an Azure Storage account with IoT Hub

To use the file upload functionality, you must first link an Azure Storage account to the IoT Hub. You can complete
this task either through the Azure portal, or programmatically through the IoT Hub resource provider REST APIs.
Once you have associated an Azure Storage account with your IoT Hub, the service returns a SAS URI to a device
when the device initiates a file upload request.

NOTE
The Azure IoT SDKs automatically handle retrieving the SAS URI, uploading the file, and notifying IoT Hub of a completed
upload.

Initialize a file upload

IoT Hub has an endpoint specifically for devices to request a SAS URI for storage to upload a file. The device
initiates the file upload process by sending a POST to the IoT hub at
{iot hub}.azure-devices.net/devices/{deviceId}/files with the following JSON body:

{
"blobName": "{name of the file for which a SAS URI will be generated}"
}
IoT Hub returns the following data, which the device uses to upload the file:

{
"correlationId": "somecorrelationid",
"hostname": "contoso.azure-devices.net",
"containerName": "testcontainer",
"blobName": "test-device1/image.jpg",
"sasToken": "1234asdfSAStoken"
}

Deprecated: initialize a file upload with a GET

NOTE
This section describes deprecated functionality for how to receive a SAS URI from IoT Hub. You should use the POST method
described previously.

IoT Hub has two REST endpoints to support file upload, one to get the SAS URI for storage and the other to notify
the IoT hub of a completed upload. The device initiates the file upload process by sending a GET to the IoT hub at
{iot hub}.azure-devices.net/devices/{deviceId}/files/{filename} . The IoT hub returns a SAS URI specific to the
file to be uploaded, and a correlation ID to be used once the upload is completed.

Notify IoT Hub of a completed file upload

The device is responsible for uploading the file to storage using the Azure Storage SDKs. Once the upload is
completed, the device sends a POST to the IoT hub at
{iot hub}.azure-devices.net/devices/{deviceId}/files/notifications with the following JSON body:

{
"correlationId": "{correlation ID received from the initial request}",
"isSuccess": bool,
"statusCode": XXX,
"statusDescription": "Description of status"
}

The value of isSuccess is a Boolean representing whether the file was uploaded successfully. The status code for
statusCode is the status for the upload of the file to storage, and the statusDescription corresponds to the
statusCode .

Reference topics:
The following reference topics provide you with more information about uploading files from a device.

File upload notifications

When a device uploads a file and notifies IoT Hub of upload completion, the service optionally generates a
notification message that contains the name and storage location of the file.
As explained in Endpoints, IoT Hub delivers file upload notifications through a service-facing endpoint
(/messages/servicebound/fileuploadnotifications) as messages. The receive semantics for file upload
notifications are the same as for cloud-to-device messages and have the same message lifecycle. Each message
retrieved from the file upload notification endpoint is a JSON record with the following properties:
PROPERTY DESCRIPTION

EnqueuedTimeUtc Timestamp indicating when the notification was created.

DeviceId DeviceId of the device which uploaded the file.

BlobUri URI of the uploaded file.

BlobName Name of the uploaded file.

LastUpdatedTime Timestamp indicating when the file was last updated.

BlobSizeInBytes Size of the uploaded file.

Example. This example shows the body of a file upload notification message.

{
"deviceId":"mydevice",
"blobUri":"https://{storage account}.blob.core.windows.net/{container name}/mydevice/myfile.jpg",
"blobName":"mydevice/myfile.jpg",
"lastUpdatedTime":"2016-06-01T21:22:41+00:00",
"blobSizeInBytes":1234,
"enqueuedTimeUtc":"2016-06-01T21:22:43.7996883Z"
}

File upload notification configuration options

Each IoT hub exposes the following configuration options for file upload notifications:

PROPERTY DESCRIPTION RANGE AND DEFAULT

enableFileUploadNotifications Controls whether file upload Bool. Default: True.

notifications are written to the file
notifications endpoint.

fileNotifications.ttlAsIso8601 Default TTL for file upload notifications. ISO_8601 interval up to 48H (minimum
1 minute). Default: 1 hour.

fileNotifications.lockDuration Lock duration for the file upload 5 to 300 seconds (minimum 5 seconds).
notifications queue. Default: 60 seconds.

fileNotifications.maxDeliveryCount Maximum delivery count for the file 1 to 100. Default: 100.
upload notification queue.

Additional reference material

Other reference topics in the IoT Hub developer guide include:
IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and management
operations.
Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to
expect when you use the service.
Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both device
and service apps that interact with IoT Hub.
IoT Hub query language for device twins and jobs describes the IoT Hub query language you can use to retrieve
information from IoT Hub about your device twins and jobs.
IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Next steps
Now you have learned how to upload files from devices using IoT Hub, you may be interested in the following IoT
Hub developer guide topics:
Manage device identities in IoT Hub
Control access to IoT Hub
Use device twins to synchronize state and configurations
Invoke a direct method on a device
Schedule jobs on multiple devices
If you would like to try out some of the concepts described in this article, you may be interested in the following
IoT Hub tutorial:
How to upload files from devices to the cloud with IoT Hub
Identity registry
1/17/2017 • 7 min to read • Edit on GitHub

Overview
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. A device must also authenticate with the IoT hub based on credentials stored in the
identity registry.
At a high level, the identity registry is a REST-capable collection of device identity resources. When you add an
entry to the identity registry, IoT Hub creates a set of per-device resources in the service such as the queue that
contains in-flight cloud-to-device messages.
When to use
Use the identity registry when you need to provision devices that connect to your IoT hub and when you need
to control per-device access to your hub's device-facing endpoints.

NOTE
The identity registry does not contain any application-specific metadata.

Identity registry operations

The IoT Hub identity registry exposes the following operations:
Create device identity
Update device identity
Retrieve device identity by ID
Delete device identity
List up to 1000 identities
Export all identities to Azure blob storage
Import identities from Azure blob storage
All these operations can use optimistic concurrency, as specified in RFC7232.

IMPORTANT
The only way to retrieve all identities in an IoT hub's identity registry is to use the Export functionality.

An IoT Hub identity registry:

Does not contain any application metadata.
Can be accessed like a dictionary, by using the deviceId as the key.
Does not support expressive queries.
An IoT solution typically has a separate solution-specific store that contains application-specific metadata. For
example, the solution-specific store in a smart building solution would record the room in which a
temperature sensor is deployed.
IMPORTANT
Only use the identity registry for device management and provisioning operations. High throughput operations at run
time should not depend on performing operations in the identity registry. For example, checking the connection state of
a device before sending a command is not a supported pattern. Make sure to check the throttling rates for the identity
registry, and the device heartbeat pattern.

Disable devices
You can disable devices by updating the status property of an identity in the identity registry. Typically, you
use this property in two scenarios:
During a provisioning orchestration process. For more information, see Device Provisioning.
If, for any reason, you consider a device is compromised or has become unauthorized.

Import and export device identities

You can export device identities in bulk from an IoT hub's identity registry, by using asynchronous operations
on the IoT Hub resource provider endpoint. Exports are long-running jobs that use a customer-supplied blob
container to save device identity data read from the identity registry.
You can import device identities in bulk to an IoT hub's identity registry, by using asynchronous operations on
the IoT Hub resource provider endpoint. Imports are long-running jobs that use data in a customer-supplied
blob container to write device identity data into the identity registry.
For detailed information about the import and export APIs, see IoT Hub resource provider REST APIs.
To learn more about running import and export jobs, see Bulk management of IoT Hub device identities.

Device provisioning
The device data that a given IoT solution stores depends on the specific requirements of that solution. But, as a
minimum, a solution must store device identities and authentication keys. Azure IoT Hub includes an identity
registry that can store values for each device such as IDs, authentication keys, and status codes. A solution can
use other Azure services such as Azure table storage, Azure blob storage, or Azure DocumentDB to store any
additional device data.
Device provisioning is the process of adding the initial device data to the stores in your solution. To enable a
new device to connect to your hub, you must add a device ID and keys to the IoT Hub identity registry. As part
of the provisioning process, you might need to initialize device-specific data in other solution stores.

Device heartbeat
The IoT Hub identity registry contains a field called connectionState. Only use the connectionState field
during development and debugging. IoT solutions should not query the field at run time (for example, to check
if a device is connected in order to decide whether to send a cloud-to-device message or an SMS).
If your IoT solution needs to know if a device is connected (either at run time, or with more accuracy than the
connectionState property provides), your should implement the heartbeat pattern.
In the heartbeat pattern, the device sends device-to-cloud messages at least once every fixed amount of time
(for example, at least once every hour). Therefore, even if a device does not have any data to send, it still sends
an empty device-to-cloud message (usually with a property that identifies it as a heartbeat). On the service
side, the solution maintains a map with the last heartbeat received for each device. The solution assumes that
there is a problem with a device if it does not receive a heartbeat message within the expected time.
A more complex implementation could include the information from operations monitoring to identify devices
that are trying to connect or communicate but failing. When you implement the heartbeat pattern, make sure
to check IoT Hub Quotas and Throttles.

NOTE
If an IoT solution needs the device connection state solely to determine whether to send cloud-to-device messages, and
messages are not broadcast to large sets of devices, a much simpler pattern to consider is to use a short Expiry time.
This pattern achieves the same result as maintaining a device connection state registry using the heartbeat pattern,
while being more efficient. It is also possible, by requesting message acknowledgements, to be notified by IoT Hub of
which devices are able to receive messages and which are not online or are failed.

Reference topics:
The following reference topics provide you with more information about the identity registry.

Device identity properties

Device identities are represented as JSON documents with the following properties:

PROPERTY OPTIONS DESCRIPTION

deviceId required, read-only on updates A case-sensitive string (up to 128

characters long) of ASCII 7-bit
alphanumeric characters +
{'-', ':', '.', '+', '%', '_',
'#', '*', '?', '!', '(', ')',
',', '=', '@', ';', '$', '''}
.

generationId required, read-only An IoT hub-generated, case-sensitive

string up to 128 characters long. This
value is used to distinguish devices
with the same deviceId, when they
have been deleted and re-created.

etag required, read-only A string representing a weak etag for

the device identity, as per RFC7232.

auth optional A composite object containing

authentication information and
security materials.

auth.symkey optional A composite object containing a

primary and a secondary key, stored
in base64 format.

status required An access indicator. Can be Enabled

or Disabled. If Enabled, the device is
allowed to connect. If Disabled, this
device cannot access any device-
facing endpoint.

statusReason optional A 128 character-long string that

stores the reason for the device
identity status. All UTF-8 characters
are allowed.
PROPERTY OPTIONS DESCRIPTION

statusUpdateTime read-only A temporal indicator, showing the

date and time of the last status
update.

connectionState read-only A field indicating connection status:

either Connected or Disconnected.
This field represents the IoT Hub view
of the device connection status.
Important: This field should be used
only for development/debugging
purposes. The connection state is
updated only for devices using MQTT
or AMQP. Also, it is based on
protocol-level pings (MQTT pings, or
AMQP pings), and it can have a
maximum delay of only 5 minutes. For
these reasons, there can be false
positives, such as devices reported as
connected but that are disconnected.

connectionStateUpdatedTime read-only A temporal indicator, showing the

date and last time the connection
state was updated.

lastActivityTime read-only A temporal indicator, showing the

date and last time the device
connected, received, or sent a
message.

NOTE
Connection state can only represent the IoT Hub view of the status of the connection. Updates to this state may be
delayed, depending on network conditions and configurations.

Additional reference material

Other reference topics in the IoT Hub developer guide include:
IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and
management operations.
Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to
expect when you use the service.
Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both
device and service apps that interact with IoT Hub.
IoT Hub query language for device twins and jobs describes the IoT Hub query language you can use to
retrieve information from IoT Hub about your device twins and jobs.
IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Next steps
Now you have learned how to use the IoT Hub identity registry, you may be interested in the following IoT Hub
developer guide topics:
Control access to IoT Hub
Use device twins to synchronize state and configurations
Invoke a direct method on a device
Schedule jobs on multiple devices
If you would like to try out some of the concepts described in this article, you may be interested in the
following IoT Hub tutorial:
Get started with Azure IoT Hub
Control access to IoT Hub
2/14/2017 • 15 min to read • Edit on GitHub

Overview
This article describes the options for securing your IoT hub. IoT Hub uses permissions to grant access to each
IoT hub endpoint. Permissions limit the access to an IoT hub based on functionality.
This article describes:
The different permissions that you can grant to a device or back-end app to access your IoT hub.
The authentication process and the tokens it uses to verify permissions.
How to scope credentials to limit access to specific resources.
IoT Hub support for X.509 certificates.
Custom device authentication mechanisms that use existing device identity registries or authentication
schemes.
When to use
You must have appropriate permissions to access any of the IoT Hub endpoints. For example, a device must
include a token containing security credentials along with every message it sends to IoT Hub.

Access control and permissions

You can grant permissions in the following ways:
IoT hub-level shared access policies. Shared access policies can grant any combination of
permissions. You can define policies in the Azure portal, or programmatically by using the IoT Hub
resource provider REST APIs. A newly created IoT hub has the following default policies:
iothubowner: Policy with all permissions.
service: Policy with ServiceConnect permission.
device: Policy with DeviceConnect permission.
registryRead: Policy with RegistryRead permission.
registryReadWrite: Policy with RegistryRead and RegistryWrite permissions.
Per-device security credentials. Each IoT Hub contains an identity registry. For each device in this
identity registry, you can configure security credentials that grant DeviceConnect permissions
scoped to the corresponding device endpoints.
For example, in a typical IoT solution:
The device management component uses the registryReadWrite policy.
The event processor component uses the service policy.
The run-time device business logic component uses the service policy.
Individual devices connect using credentials stored in the IoT hub's identity registry.

Authentication
Azure IoT Hub grants access to endpoints by verifying a token against the shared access policies and identity
registry security credentials.
Security credentials, such as symmetric keys, are never sent over the wire.
NOTE
The Azure IoT Hub resource provider is secured through your Azure subscription, as are all providers in the Azure
Resource Manager.

For more information about how to construct and use security tokens, see IoT Hub security tokens.
Protocol specifics
Each supported protocol, such as MQTT, AMQP, and HTTP, transports tokens in different ways.
When using MQTT, the CONNECT packet has the deviceId as the ClientId, {iothubhostname}/{deviceId} in the
Username field, and a SAS token in the Password field. {iothubhostname} should be the full CName of the IoT
hub (for example, contoso.azure-devices.net).
When using AMQP, IoT Hub supports SASL PLAIN and AMQP Claims-Based-Security.
If you use AMQP claims-based-security, the standard specifies how to transmit these tokens.
For SASL PLAIN, the username can be:
{policyName}@sas.root.{iothubName} if using IoT hub-level tokens.
{deviceId}@sas.{iothubname} if using device-scoped tokens.

In both cases, the password field contains the token, as described in IoT Hub security tokens.
HTTP implements authentication by including a valid token in the Authorization request header.
Example
Username (DeviceId is case-sensitive): iothubname.azure-devices.net/DeviceId

Password (Generate SAS token with the device explorer tool):

SharedAccessSignature sr=iothubname.azure-
devices.net%2fdevices%2fDeviceId&sig=kPszxZZZZZZZZZZZZZZZZZAhLT%2bV7o%3d&se=1487709501

NOTE
The Azure IoT SDKs automatically generate tokens when connecting to the service. In some cases, the Azure IoT SDKs
do not support all the protocols or all the authentication methods.

Special considerations for SASL PLAIN

When using SASL PLAIN with AMQP, a client connecting to an IoT hub can use a single token for each TCP
connection. When the token expires, the TCP connection disconnects from the service and triggers a reconnect.
This behavior, while not problematic for a back-end app, is damaging for a device app for the following
reasons:
Gateways usually connect on behalf of many devices. When using SASL PLAIN, they have to create a
distinct TCP connection for each device connecting to an IoT hub. This scenario considerably increases the
consumption of power and networking resources, and increases the latency of each device connection.
Resource-constrained devices are adversely affected by the increased use of resources to reconnect after
each token expiration.

Scope IoT hub-level credentials

You can scope IoT hub-level security policies by creating tokens with a restricted resource URI. For example,
the endpoint to send device-to-cloud messages from a device is /devices/{deviceId}/messages/events. You
can also use an IoT hub-level shared access policy with DeviceConnect permissions to sign a token whose
resourceURI is /devices/{deviceId}. This approach creates a token that is only usable to send messages on
behalf of device deviceId.
This mechanism is similar to the Event Hubs publisher policy, and enables you to implement custom
authentication methods.

Security tokens
IoT Hub uses security tokens to authenticate devices and services to avoid sending keys on the wire.
Additionally, security tokens are limited in time validity and scope. Azure IoT SDKs automatically generate
tokens without requiring any special configuration. Some scenarios, however, require you to generate and use
security tokens directly. These scenarios include the direct use of the MQTT, AMQP, or HTTP surfaces, or the
implementation of the token service pattern, as explained in Custom device authentication.
IoT Hub also allows devices to authenticate with IoT Hub using X.509 certificates.
Security token structure
You use security tokens to grant time-bounded access to devices and services to specific functionality in IoT
Hub. To ensure that only authorized devices and services can connect, security tokens must be signed with
either a shared access key or a symmetric key. These keys are stored with a device identity in the identity
registry.
A token signed with a shared access key grants access to all the functionality associated with the shared access
policy permissions. On the other hand, a token signed with a device identity's symmetric key only grants the
DeviceConnect permission for the associated device identity.
The security token has the following format:

SharedAccessSignature sig={signature-string}&se={expiry}&skn={policyName}&sr={URL-encoded-resourceURI}

Here are the expected values:

VALUE DESCRIPTION

{signature} An HMAC-SHA256 signature string of the form:

{URL-encoded-resourceURI} + "\n" + expiry .
Important: The key is decoded from base64 and used as
key to perform the HMAC-SHA256 computation.

{resourceURI} URI prefix (by segment) of the endpoints that can be

accessed with this token, starting with host name of the IoT
hub (no protocol). For example,
myHub.azure-devices.net/devices/device1

{expiry} UTF8 strings for number of seconds since the epoch

00:00:00 UTC on 1 January 1970.

{URL-encoded-resourceURI} Lower case URL-encoding of the lower case resource URI

{policyName} The name of the shared access policy to which this token
refers. Absent if the token refers to device-registry
credentials.

Note on prefix: The URI prefix is computed by segment and not by character. For example /a/b is a prefix for
/a/b/c but not for /a/bc .
The following Node.js snippet shows a function called generateSasToken that computes the token from the
inputs resourceUri, signingKey, policyName, expiresInMins . The next sections detail how to initialize the
different inputs for the different token use cases.

var generateSasToken = function(resourceUri, signingKey, policyName, expiresInMins) {

resourceUri = encodeURIComponent(resourceUri);

// Set expiration in seconds

var expires = (Date.now() / 1000) + expiresInMins * 60;
expires = Math.ceil(expires);
var toSign = resourceUri + '\n' + expires;

// Use crypto
var hmac = crypto.createHmac('sha256', new Buffer(signingKey, 'base64'));
hmac.update(toSign);
var base64UriEncoded = encodeURIComponent(hmac.digest('base64'));

// Construct autorization string

var token = "SharedAccessSignature sr=" + resourceUri + "&sig="
+ base64UriEncoded + "&se=" + expires;
if (policyName) token += "&skn="+policyName;
return token;
};

As a comparison, the equivalent Python code to generate a security token is:

from base64 import b64encode, b64decode

from hashlib import sha256
from time import time
from urllib import quote_plus, urlencode
from hmac import HMAC

def generate_sas_token(uri, key, policy_name, expiry=3600):

ttl = time() + expiry
sign_key = "%s\n%d" % ((quote_plus(uri)), int(ttl))
print sign_key
signature = b64encode(HMAC(b64decode(key), sign_key, sha256).digest())

rawtoken = {
'sr' : uri,
'sig': signature,
'se' : str(int(ttl))
}

if policy_name is not None:

rawtoken['skn'] = policy_name

return 'SharedAccessSignature ' + urlencode(rawtoken)

NOTE
Since the time validity of the token is validated on IoT Hub machines, the drift on the clock of the machine that
generates the token must be minimal.

Use SAS tokens in a device app

There are two ways to obtain DeviceConnect permissions with IoT Hub with security tokens: use a symmetric
device key from the identity registry, or use a shared access key.
Remember that all functionality accessible from devices is exposed by design on endpoints with prefix
/devices/{deviceId} .
IMPORTANT
The only way that IoT Hub authenticates a specific device is using the device identity symmetric key. In cases when a
shared access policy is used to access device functionality, the solution must consider the component issuing the
security token as a trusted subcomponent.

The device-facing endpoints are (irrespective of the protocol):

ENDPOINT FUNCTIONALITY

{iot hub host Send device-to-cloud messages.

name}/devices/{deviceId}/messages/events

{iot hub host name}/devices/{deviceId}/devicebound Receive cloud-to-device messages.

Use a symmetric key in the identity registry

When using a device identity's symmetric key to generate a token, the policyName ( skn ) element of the token
is omitted.
For example, a token created to access all device functionality should have the following parameters:
resource URI: {IoT hub name}.azure-devices.net/devices/{device id} ,
signing key: any symmetric key for the {device id} identity,
no policy name,
any expiration time.
An example using the preceding Node.js function would be:

var endpoint ="myhub.azure-devices.net/devices/device1";

var deviceKey ="...";

var token = generateSasToken(endpoint, deviceKey, null, 60);

The result, which grants access to all functionality for device1, would be:

SharedAccessSignature sr=myhub.azure-
devices.net%2fdevices%2fdevice1&sig=13y8ejUk2z7PLmvtwR5RqlGBOVwiq7rQR3WZ5xZX3N4%3D&se=1456971697

NOTE
It is possible to generate a SAS token using the .NET device explorer tool or the cross-platform, node-based iothub-
explorer command-line utility.

Use a shared access policy

When creating a token from a shared access policy, the policy name field skn must be set to the name of the
policy used. It is also required that the policy grants the DeviceConnect permission.
The two main scenarios for using shared access policies to access device functionality are:
cloud protocol gateways,
token services used to implement custom authentication schemes.
Since the shared access policy can potentially grant access to connect as any device, it is important to use the
correct resource URI when creating security tokens. This is especially important for token services, which have
to scope the token to a specific device using the resource URI. This point is less relevant for protocol gateways
as they are already mediating traffic for all devices.
As an example, a token service using the pre-created shared access policy called device would create a token
with the following parameters:
resource URI: {IoT hub name}.azure-devices.net/devices/{device id} ,
signing key: one of the keys of the device policy,
policy name: device ,
any expiration time.
An example using the preceding Node.js function would be:

var endpoint ="myhub.azure-devices.net/devices/device1";

var policyName = 'device';
var policyKey = '...';

var token = generateSasToken(endpoint, policyKey, policyName, 60);

The result, which grants access to all functionality for device1, would be:

SharedAccessSignature sr=myhub.azure-
devices.net%2fdevices%2fdevice1&sig=13y8ejUk2z7PLmvtwR5RqlGBOVwiq7rQR3WZ5xZX3N4%3D&se=1456971697&skn=devic
e

A protocol gateway could use the same token for all devices simply setting the resource URI to
myhub.azure-devices.net/devices .

Use security tokens from service components

Service components can only generate security tokens using shared access policies granting the appropriate
permissions as explained previously.
Here are the service functions exposed on the endpoints:

ENDPOINT FUNCTIONALITY

{iot hub host name}/devices Create, update, retrieve, and delete device identities.

{iot hub host name}/messages/events Receive device-to-cloud messages.

{iot hub host name}/servicebound/feedback Receive feedback for cloud-to-device messages.

{iot hub host name}/devicebound Send cloud-to-device messages.

As an example, a service generating using the pre-created shared access policy called registryRead would
create a token with the following parameters:
resource URI: {IoT hub name}.azure-devices.net/devices ,
signing key: one of the keys of the registryRead policy,
policy name: registryRead ,
any expiration time.
var endpoint ="myhub.azure-devices.net/devices"; var policyName = 'device'; var policyKey = '...';
var token = generateSasToken(endpoint, policyKey, policyName, 60);
The result, which would grant access to read all device identities, would be:

SharedAccessSignature sr=myhub.azure-
devices.net%2fdevices&sig=JdyscqTpXdEJs49elIUCcohw2DlFDR3zfH5KqGJo4r4%3D&se=1456973447&skn=registryRead

Supported X.509 certificates

You can use any X.509 certificate to authenticate a device with IoT Hub. Certificates include:
An existing X.509 certificate. A device may already have an X.509 certificate associated with it. The device
can use this certificate to authenticate with IoT Hub.
A self-generated and self-signed X-509 certificate. A device manufacturer or in-house deployer can
generate these certificates and store the corresponding private key (and certificate) on the device. You can
use tools such as OpenSSL and Windows SelfSignedCertificate utility for this purpose.
CA-signed X.509 certificate. You can also use an X.509 certificate generated and signed by a Certification
Authority (CA) to identify a device and authenticate a device with IoT Hub.
A device may either use an X.509 certificate or a security token for authentication, but not both.
Register an X.509 certificate for a device
The Azure IoT Service SDK for C# (version 1.0.8+) supports registering a device that uses an X.509 certificate
for authentication. Other APIs such as import/export of devices also support X.509 certificates.
C# Support
The RegistryManager class provides a programmatic way to register a device. In particular, the
AddDeviceAsync and UpdateDeviceAsync methods enable you to register and update a device in the IoT
Hub identity registry. These two methods take a Device instance as input. The Device class includes an
Authentication property that allows you to specify primary and secondary X.509 certificate thumbprints. The
thumbprint represents a SHA-1 hash of the X.509 certificate (stored using binary DER encoding). You have the
option of specifying a primary thumbprint or a secondary thumbprint or both. Primary and secondary
thumbprints are supported to handle certificate rollover scenarios.

NOTE
IoT Hub does not require or store the entire X.509 certificate, only the thumbprint.

Here is a sample C# code snippet to register a device using an X.509 certificate:

var device = new Device(deviceId)

{
Authentication = new AuthenticationMechanism()
{
X509Thumbprint = new X509Thumbprint()
{
PrimaryThumbprint = "921BC9694ADEB8929D4F7FE4B9A3A6DE58B0790B"
}
}
};
RegistryManager registryManager =
RegistryManager.CreateFromConnectionString(deviceGatewayConnectionString);
await registryManager.AddDeviceAsync(device);

Use an X.509 certificate during run-time operations

The Azure IoT device SDK for .NET (version 1.0.11+) supports the use of X.509 certificates.
C# Support
The class DeviceAuthenticationWithX509Certificate supports the creation of DeviceClient instances
using an X.509 certificate.
Here is a sample code snippet:

var authMethod = new DeviceAuthenticationWithX509Certificate("<device id>", x509Certificate);

var deviceClient = DeviceClient.Create("<IotHub DNS HostName>", authMethod);

Custom device authentication

You can use the IoT Hub identity registry to configure per-device security credentials and access control using
tokens. However, if an IoT solution already has a significant investment in a custom identity registry and/or
authentication scheme, you can integrate this existing infrastructure with IoT Hub by creating a token service.
In this way, you can use other IoT features in your solution.
A token service is a custom cloud service. It uses an IoT Hub shared access policy with DeviceConnect
permissions to create device-scoped tokens. These tokens enable a device to connect to your IoT hub.

Here are the main steps of the token service pattern:

1. Create an IoT Hub shared access policy with DeviceConnect permissions for your IoT hub. You can create
this policy in the Azure portal or programmatically. The token service uses this policy to sign the tokens it
creates.
2. When a device needs to access your IoT hub, it requests a signed token from your token service. The device
can authenticate with your custom identity registry/authentication scheme to determine the device identity
that the token service uses to create the token.
3. The token service returns a token. The token is created by using /devices/{deviceId} as resourceURI , with
deviceId as the device being authenticated. The token service uses the shared access policy to construct
the token.
4. The device uses the token directly with the IoT hub.

NOTE
You can use the .NET class SharedAccessSignatureBuilder or the Java class IotHubServiceSasToken to create a token in
your token service.

The token service can set the token expiration as desired. When the token expires, the IoT hub severs the device
connection. Then, the device must request a new token from the token service. A short expiry time increases
the load on both the device and the token service.
For a device to connect to your hub, you must still add it to the IoT Hub identity registry — even though the
device is using a token and not a device key to connect. Therefore, you can continue to use per-device access
control by enabling or disabling device identities in the IoT Hub identity registry when the device authenticates
with a token. This approach mitigates the risks of using tokens with long expiry times.
Comparison with a custom gateway
The token service pattern is the recommended way to implement a custom identity registry/authentication
scheme with IoT Hub. It is recommended because IoT Hub continues to handle most of the solution traffic.
However, there are cases where the custom authentication scheme is so intertwined with the protocol that a
service processing all the traffic (custom gateway) is required. An example of such a scenario is usingTransport
Layer Security (TLS) and pre-shared keys (PSKs). For more information, see the protocol gateway topic.

Reference topics:
The following reference topics provide you with more information about controlling access to your IoT hub.

IoT Hub permissions

The following table lists the permissions you can use to control access to your IoT hub.

PERMISSION NOTES

RegistryRead Grants read access to the identity registry. For more

information, see Identity registry.

RegistryReadWrite Grants read and write access to the identity registry. For
more information, see Identity registry.

ServiceConnect Grants access to cloud service-facing communication and

monitoring endpoints. For example, it grants permission to
back-end cloud services to receive device-to-cloud
messages, send cloud-to-device messages, and retrieve the
corresponding delivery acknowledgments.
PERMISSION NOTES

DeviceConnect Grants access to device-facing endpoints. For example, it

grants permission to send device-to-cloud messages and
receive cloud-to-device messages. This permission is used
by devices.

Additional reference material

Other reference topics in the IoT Hub developer guide include:
IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and
management operations.
Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to
expect when you use the service.
Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both
device and service apps that interact with IoT Hub.
IoT Hub query language for device twins and jobs describes the IoT Hub query language you can use to
retrieve information from IoT Hub about your device twins and jobs.
IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Next steps
Now you have learned how to control access IoT Hub, you may be interested in the following IoT Hub
developer guide topics:
Use device twins to synchronize state and configurations
Invoke a direct method on a device
Schedule jobs on multiple devices
If you would like to try out some of the concepts described in this article, you may be interested in the
following IoT Hub tutorials:
Get started with Azure IoT Hub
How to send cloud-to-device messages with IoT Hub
How to process IoT Hub device-to-cloud messages
Device twins
1/17/2017 • 10 min to read • Edit on GitHub

Overview
Device twins are JSON documents that store device state information (metadata, configurations, and
conditions). IoT Hub persists a device twin for each device that you connect to IoT Hub. This article will
describe:
the structure of the device twin: tags, desired and reported properties, and
the operations that device apps and back ends can perform on device twins.

NOTE
At this time, device twins are accessible only from devices that connect to IoT Hub using the MQTT protocol. Please
refer to the MQTT support article for instructions on how to convert existing device app to use MQTT.

When to use
Use device twins to:
Store device specific metadata in the cloud, for example deployment location of a vending machine.
Report current state information such as available capabilities and conditions from your device app, for
example a device connecting through cellular or wifi.
Synchronize the state of long-running workflows between device app and back-end app, for example
when the solution back end specifies the new firmware version to install, and the device app reports the
various stages of the update process.
Query your device metadata, configuration, or state.
Refer to Device-to-cloud communication guidance if in doubt between using reported properties, device-to-
cloud messages, or file upload. Refer to Cloud-to-device communication guidance if in doubt between using
desired properties, direct methods, or cloud-to-device messages.

Device twins
Device twins store device-related information that:
Device and back ends can use to synchronize device conditions and configuration.
The solution back end can use to query and target long-running operations.
The lifecycle of a device twin is linked to the corresponding device identity. Device twins are implicitly created
and deleted when a new device identity is created or deleted in IoT Hub.
A device twin is a JSON document that includes:
Tags. A JSON document read and written by the solution back end. Tags are not visible to device apps.
Desired properties. Used in conjunction with reported properties to synchronize device configuration or
condition. Desired properties can only be set by the solution back end and can be read by the device app.
The device app can also be notified in real time of changes on the desired properties.
Reported properties. Used in conjunction with desired properties to synchronize device configuration or
condition. Reported properties can only be set by the device app and can be read and queried by the
solution back end.
Additionally, the root of the device twin contains the read-only properties from the corresponding identity, as
contained in the identity registry.

Here is an example of a device twin JSON document:

{
"deviceId": "devA",
"generationId": "123",
"status": "enabled",
"statusReason": "provisioned",
"connectionState": "connected",
"connectionStateUpdatedTime": "2015-02-28T16:24:48.789Z",
"lastActivityTime": "2015-02-30T16:24:48.789Z",

"tags": {
"$etag": "123",
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
}
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}

In the root object, are the system properties, and container objects for tags and both reported and desired
properties. The properties container contains some read-only elements ( $metadata , $etag , and $version )
that are described respectively in the Device twin metadata and Optimistic concurrency sections.
Reported property example
In the above example, the device twin contains a batteryLevel property that is reported by the device app.
This property makes it possible to query and operate on devices based on the last reported battery level.
Another example would have the device app report device capabilities or connectivity options.
Note how reported properties simplify scenarios where the solution back end is interested in the last known
value of a property. Use device-to-cloud messages if the solution back end needs to process device telemetry
in the form of sequences of timestamped events, such as time series.
Desired property example
In the above example, the telemetryConfig device twin desired and reported properties are used by the
solution back end and the device app to synchronize the telemetry configuration for this device. For example:
1. The solution back end sets the desired property with the desired configuration value. Here is the
portion of the document with the desired property:

...
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
...
},
...

2. The device app is notified of the change immediately if connected, or at the first reconnect. The device
app then reports the updated configuration (or an error condition using the status property). Here is
the portion of the reported properties:

...
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
}
...
}
...

3. The solution back end can keep track the results of the configuration operation across many devices, by
querying device twins.

NOTE
The above snippets are examples, optimized for readability, of a possible way to encode a device configuration and its
status. IoT Hub does not impose a specific schema for the device twin desired and reported properties in the device
twins.

In many cases twins are used to synchronize long-running operations such as firmware updates. Refer to Use
desired properties to configure devices for more information on how to use properties to synchronize and
track long running operations across devices.

Back-end operations
The solution back end operates on the device twin using the following atomic operations, exposed through
HTTP:
1. Retrieve device twin by id. This operation returns the content of the device twin's document, including
tags and desired, reported and system properties.
2. Partially update device twin. This operation enables the solution back end to partially update the
device twin's tags or desired properties. The partial update is expressed as a JSON document that adds
or updates any property mentioned. Properties set to null are removed. For example, the following
creates a new desired property with value {"newProperty": "newValue"} , overwrites the existing value
of existingProperty with "otherNewValue" , and removes completely otherOldProperty . No changes
happen to other existing desired properties or tags:

{
"properties": {
"desired": {
"newProperty": {
"nestedProperty": "newValue"
},
"existingProperty": "otherNewValue",
"otherOldProperty": null
}
}
}

3. Replace desired properties. This operation enables the solution back end to completely overwrite all
existing desired properties and substitute a new JSON document for properties/desired .
4. Replace tags. Analogously to replace desired properties, this operations allows the solution back end to
completely overwrite all existing tags and substitute a new JSON document for tags .

All the above operations support Optimistic concurrency and require the ServiceConnect permission, as
defined in the Security article.
In addition to these operations, the solution back end can query the device twins using the SQL-like IoT Hub
query language, and perform operations on large sets of device twins using jobs.

Device operations
The device app operates on the device twin using the following atomic operations:
1. Retrieve device twin. This operation returns the content of the device twin's document (including tags
and desired, reported and system properties) for the currently connected device.
2. Partially update reported properties. This operation enables the partial update of the reported
properties of the currently connected device. This uses the same JSON update format as the solution back
end facing partial update of desired properties.
3. Observe desired properties. The currently connected device can choose to be notified of updates to the
desired properties as soon as they happen. The device receives the same form of update (partial or full
replacement) executed by the solution back end.
All the above operations require the DeviceConnect permission, as defined in the Security article.
The Azure IoT device SDKs make it easy to use the above operations from many languages and platforms.
More information on the details of IoT Hub's primitives for desired properties synchronization can be found in
Device reconnection flow.
NOTE
Currently, device twins are accessible only from devices that connect to IoT Hub using the MQTT protocol.

Reference topics:
The following reference topics provide you with more information about controlling access to your IoT hub.

Tags and properties format

Tags, desired, and reported properties are JSON objects with the following restrictions:
All keys in JSON objects are case-sensitive 64 bytes UTF-8 UNICODE strings. Allowed characters exclude
UNICODE control characters (segments C0 and C1), and '.' , ' ' , and '$' .
All values in JSON objects can be of the following JSON types: boolean, number, string, object. Arrays are
not allowed.
All JSON objects in tags, desired, and reported properties can have a maximum depth of 5. For
instance, the following object is valid:

{
...
"tags": {
"one": {
"two": {
"three": {
"four": {
"five": {
"property": "value"
}
}
}
}
}
},
...
}

All string values can be at most 512 bytes in length.

Device twin size

IoT Hub enforces an 8KB size limitation on the values of tags , properties/desired , and properties/reported ,
excluding read-only elements. The size is computed by counting all characters excluding UNICODE control
characters (segments C0 and C1) and space ' ' when it appears outside of a string constant. IoT Hub will
reject with error all operations that would increase the size of those documents above the limit.

Device twin metadata

IoT Hub maintains the timestamp of the last update for each JSON object in device twin desired and reported
properties. The timestamps are in UTC and encoded in the ISO8601 format YYYY-MM-DDTHH:MM:SS.mmmZ . For
example:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
}
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
}
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}

This information is kept at every level (not just the leaves of the JSON structure) to preserve updates that
remove object keys.

Optimistic concurrency
Tags, desired and reported properties all support optimistic concurrency. Tags have an etag, as per RFC7232,
that represents the tag's JSON representation. You can use this in conditional update operations from the
solution back end to ensure consistency.
Device twin desired and reported properties do not have etags, but have a $version value that is guaranteed
to be incremental. Analogously to an etag, the version can be used by the updating party (such as a device
app for a reported property or the solution back end for a desired property) to enforce consistency of updates.
Versions are also useful when an observing agent (such as, the device app observing the desired properties)
has to reconcile races between the result of a retrieve operation and an update notification. The section Device
reconnection flow provides more information.

Device reconnection flow

IoT Hub does not preserve desired properties update notifications for disconnected devices. It follows that a
device that is connecting must retrieve the full desired properties document, in addition to subscribing for
update notifications. Given the possibility of races between update notifications and full retrieval, the
following flow must be ensured:
1. Device app connects to an IoT hub.
2. Device app subscribes for desired properties update notifications.
3. Device app retrieves the full document for desired properties.
The device app can ignore all notifications with $version less or equal than the version of the full retrieved
document. This is possible because IoT Hub guarantees that versions always increment.

NOTE
This logic is already implemented in the Azure IoT device SDKs. This description is useful only if the device app cannot
use any of Azure IoT device SDKs and must program the MQTT interface directly.

Additional reference material

Other reference topics in the IoT Hub developer guide include:
IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and
management operations.
Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to
expect when you use the service.
Azure IoT device and service SDKs lists the various language SDKs you an use when you develop both
device and service apps that interact with IoT Hub.
IoT Hub query language for device twins and jobs describes the IoT Hub query language you can use to
retrieve information from IoT Hub about your device twins and jobs.
IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Next steps
Now you have learned about device twins, you may be interested in the following IoT Hub developer guide
topics:
Invoke a direct method on a device
Schedule jobs on multiple devices
If you would like to try out some of the concepts described in this article, you may be interested in the
following IoT Hub tutorials:
How to use the device twin
How to use device twin properties
Direct methods
1/27/2017 • 4 min to read • Edit on GitHub

Overview
IoT Hub gives you ability to invoke direct methods on devices from the cloud. Direct methods represent a
request-reply interaction with a device similar to an HTTP call in that they succeed or fail immediately (after a
user-specified timeout). This is useful for scenarios where the course of immediate action is different
depending on whether the device was able to respond, such as sending an SMS wake-up to a device if a device
is offline (SMS being more expensive than a method call).
Each device method targets a single device. Jobs provide a way to invoke direct methods on multiple devices,
and schedule method invocation for disconnected devices.
Anyone with service connect permissions on IoT Hub may invoke a method on a device.
When to use
Direct methods follow a request-response pattern and are meant for communications that require immediate
confirmation of their result, usually interactive control of the device, for example to turn on a fan.
Refer to Cloud-to-device communication guidance if in doubt between using desired properties, direct
methods, or cloud-to-device messages.

Method lifecycle
Direct methods are implemented on the device and may require zero or more inputs in the method payload to
correctly instantiate. You invoke a direct method through a service-facing URI (
{iot hub}/twins/{device id}/methods/ ). A device receives direct methods through a device-specific MQTT topic
( $iothub/methods/POST/{method name}/ ). We may support direct methods on additional device-side networking
protocols in the future.

NOTE
When you invoke a direct method on a device, property names and values can only contain US-ASCII printable
alphanumeric, except any in the following set:
{'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT} .

Direct methods are synchronous and either succeed or fail after the timeout period (default: 30 seconds,
settable up to 3600 seconds). Direct methods are useful in interactive scenarios where you want a device to act
if and only if the device is online and receiving commands, such as turning on a light from a phone. In these
scenarios, you want to see an immediate success or failure so the cloud service can act on the result as soon as
possible. The device may return some message body as a result of the method, but it isn't required for the
method to do so. There is no guarantee on ordering or any concurrency semantics on method calls.
Direct method are HTTP-only from the cloud side, and MQTT-only from the device side.
The payload for method requests and reponses is a JSON document up to 8KB.

Reference topics:
The following reference topics provide you with more information about using direct methods.
Invoke a direct method from a back-end app
Method invocation
Direct method invocations on a device are HTTP calls which comprise:
The URI specific to the device ( {iot hub}/twins/{device id}/methods/ )
The POST method
Headers which contain the authorization, request ID, content type, and content encoding
A transparent JSON body in the following format:

{
"methodName": "reboot",
"responseTimeoutInSeconds": 200,
"payload": {
"input1": "someInput",
"input2": "anotherInput"
}
}

Timeout is in seconds. If timeout is not set, it defaults to 30 seconds.

Response
The back-end app receives a response which comprises:
HTTP status code, which is used for errors coming from the IoT Hub, including a 404 error for devices not
currently connected
Headers which contain the etag, request ID, content type, and content encoding
A JSON body in the following format:

{
"status" : 201,
"payload" : {...}
}

Both status and body are provided by the device and used to respond with the device's own status code
and/or description.

Handle a direct method on a device

Method invocation
Devices receive direct method requests on the MQTT topic:
$iothub/methods/POST/{method name}/?$rid={request id}

The body which the device receives is in the following format:

{
"input1": "someInput",
"input2": "anotherInput"
}

Method requests are QoS 0.

Response
The device sends responses to $iothub/methods/res/{status}/?$rid={request id} , where:
The status property is the device-supplied status of method execution.
The $rid property is the request ID from the method invocation received from IoT Hub.
The body is set by the device and can be any status.

Additional reference material

Other reference topics in the IoT Hub developer guide include:
IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and
management operations.
Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to
expect when you use the service.
Azure IoT device and service SDKs lists the various language SDKs you an use when you develop both
device and service apps that interact with IoT Hub.
IoT Hub query language for device twins and jobs describes the IoT Hub query language you can use to
retrieve information from IoT Hub about your device twins and jobs.
IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Next steps
Now you have learned how to use direct methods, you may be interested in the following IoT Hub developer
guide topic:
Schedule jobs on multiple devices
If you would like to try out some of the concepts described in this article, you may be interested in the
following IoT Hub tutorial:
Use direct methods
Schedule jobs on multiple devices
1/17/2017 • 4 min to read • Edit on GitHub

Overview
As described by previous articles, Azure IoT Hub enables a number of building blocks (device twin properties
and tags and direct methods). Typically, back-end apps enable device administrators and operators to update
and interact with IoT devices in bulk and at a scheduled time. Jobs encapsulate the execution of device twin
updates and direct methods against a set of devices at a schedule time. For example, an operator would use a
back-end app that would initiate and track a job to reboot a set of devices in building 43 and floor 3 at a time
that would not be disruptive to the operations of the building.
When to use
Consider using jobs when: a solution back end needs to schedule and track progress any of the following
activities on a set of device:
Update desired properties
Update tags
Invoke direct methods

Job lifecycle
Jobs are initiated by the solution back end and maintained by IoT Hub. You can initiate a job through a service-
facing URI ( {iot hub}/jobs/v2/{device id}/methods/<jobID>?api-version=2016-11-14 ) and query for progress on
an executing job through a service-facing URI ( {iot hub}/jobs/v2/<jobId>?api-version=2016-11-14 ). Once a job
is initiated, querying for jobs enables the back-end app to refresh the status of running jobs.

NOTE
When you initiate a job, property names and values can only contain US-ASCII printable alphanumeric, except any in the
following set:
{'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT} .

Reference topics:
The following reference topics provide you with more information about using jobs.

Jobs to execute direct methods

The following is the HTTP 1.1 request details for executing a direct method on a set of devices using a job:
```
PUT /jobs/v2/<jobId>?api-version=2016-11-14

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>

{
jobId: '<jobId>',
type: 'scheduleDirectRequest',
cloudToDeviceMethod: {
methodName: '<methodName>',
payload: <payload>,
responseTimeoutInSeconds: methodTimeoutInSeconds
},
queryCondition: '<queryOrDevices>', // query condition
startTime: <jobStartTime>, // as an ISO-8601 date string
maxExecutionTimeInSeconds: <maxExecutionTimeInSeconds>
}
```

The query condition can also be on a single device Id or on a list of device Ids as shown below
Examples

queryCondition = "deviceId = 'MyDevice1'"

queryCondition = "deviceId IN ['MyDevice1','MyDevice2']"
queryCondition = "deviceId IN ['MyDevice1']

IoT Hub Query Language covers IoT Hub query language in additional detail.

Jobs to update device twin properties

The following is the HTTP 1.1 request details for updating device twin properties using a job:

```
PUT /jobs/v2/<jobId>?api-version=2016-11-14
Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>

{
jobId: '<jobId>',
type: 'scheduleTwinUpdate',
updateTwin: <patch> // Valid JSON object
queryCondition: '<queryOrDevices>', // query condition
startTime: <jobStartTime>, // as an ISO-8601 date string
maxExecutionTimeInSeconds: <maxExecutionTimeInSeconds> // format TBD
}
```

Querying for progress on jobs

The following is the HTTP 1.1 request details for querying for jobs:
```
GET /jobs/v2/query?api-version=2016-11-14[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>]
[&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8
Request-Id: <guid>
User-Agent: <sdk-name>/<sdk-version>
```

The continuationToken is provided from the response.

Jobs Properties
The following is a list of properties and corresponding descriptions, which can be used when querying for jobs
or job results.

PROPERTY DESCRIPTION

jobId Application provided ID for the job.

startTime Application provided start time (ISO-8601) for the job.

endTime IoT Hub provided date (ISO-8601) for when the job
completed. Valid only after the job reaches the 'completed'
state.

type Types of jobs:

scheduledUpdateTwin: A job used to update a set of

desired properties or tags.

scheduledDeviceMethod: A job used to invoke a device

method on a set of device twins.

status Current state of the job. Possible values for status:

pending : Scheduled and waiting to be picked up by the job

service.

scheduled : Scheduled for a time in the future.

running : Currently active job.

cancelled : Job has been cancelled.

failed : Job failed.

completed : Job has completed.

deviceJobStatistics Statistics about the job's execution.

deviceJobStatistics properties.
PROPERTY DESCRIPTION

deviceJobStatistics.deviceCount Number of devices in the job.

deviceJobStatistics.failedCount Number of devices where the job failed.

deviceJobStatistics.succeededCount Number of devices where the job succeeded.

deviceJobStatistics.runningCount Number of devices that are currently running the job.

deviceJobStatistics.pendingCount Number of devices that are pending to run the job.

Additional reference material

Other reference topics in the IoT Hub developer guide include:
IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and management
operations.
Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to
expect when you use the service.
Azure IoT device and service SDKs lists the various language SDKs you an use when you develop both device
and service apps that interact with IoT Hub.
IoT Hub query language for device twins and jobs describes the IoT Hub query language you can use to
retrieve information from IoT Hub about your device twins and jobs.
IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Next steps
If you would like to try out some of the concepts described in this article, you may be interested in the following
IoT Hub tutorial:
Schedule and broadcast jobs
Reference - IoT Hub endpoints
1/31/2017 • 4 min to read • Edit on GitHub

List of built-in IoT Hub endpoints

Azure IoT Hub is a multi-tenant service that exposes its functionality to various actors. The following diagram
shows the various endpoints that IoT Hub exposes.

The following is a description of the endpoints:

Resource provider. The IoT Hub resource provider exposes an Azure Resource Manager interface that
enables Azure subscription owners to create and delete IoT hubs, and update IoT hub properties. IoT Hub
properties govern hub-level security policies, as opposed to device-level access control, and functional
options for cloud-to-device and device-to-cloud messaging. The IoT Hub resource provider also enables
you to export device identities.
Device identity management. Each IoT hub exposes a set of HTTP REST endpoints to manage device
identities (create, retrieve, update, and delete). Device identities are used for device authentication and
access control.
Device twin management. Each IoT hub exposes a set of service-facing HTTP REST endpoint to query and
update device twins (update tags and properties).
Jobs management. Each IoT hub exposes a set of service-facing HTTP REST endpoint to query and
manage jobs.
Device endpoints. For each device provisioned in the identity registry, IoT Hub exposes a set of
endpoints that a device can use to send and receive messages:
Send device-to-cloud messages. Use this endpoint to send device-to-cloud messages.
Receive cloud-to-device messages. A device uses this endpoint to receive targeted cloud-to-device
messages.
Initiate file uploads. A device uses this endpoint to receive an Azure Storage SAS URI from IoT Hub to
upload a file.
Retrieve and update device twin properties. A device uses this endpoint to access its device twin's
properties.
Receive direct method requests. A device uses this endpoint to listen for direct method's requests.
These endpoints are exposed using MQTT v3.1.1, HTTP 1.1, and AMQP 1.0 protocols. Note that
AMQP is also available over WebSockets on port 443.
The device twins and methods endpoints are available only using MQTT v3.1.1.
Service endpoints. Each IoT hub exposes a set of endpoints your solution back end can use to
communicate with your devices. These endpoints are currently only exposed using the AMQP protocol,
except for the method invocation endpoint that is exposed via HTTP 1.1.
Receive device-to-cloud messages. This endpoint is compatible with Azure Event Hubs. A back-end
service can use it to read the device-to-cloud messages sent by your devices. You can create custom
endpoints on your IoT hub in addition to this built-in endpoint.
Send cloud-to-device messages and receive delivery acknowledgments. These endpoints enable your
solution back end to send reliable cloud-to-device messages, and to receive the corresponding
delivery or expiration acknowledgments.
Receive file notifications. This messaging endpoint allows you to receive notifications of when your
devices successfully upload a file.
Direct method invocation. This endpoint allows a back-end service to invoke a direct method on a
device.
The Azure IoT SDKs article describes the various ways to access these endpoints.
Finally, it is important to note that all IoT Hub endpoints use the TLS protocol, and no endpoint is ever exposed
on unencrypted/unsecured channels.

Custom endpoints
You can link existing Azure services in your subscription to your IoT hub to act as endpoints for message
routing. These endpoints act as service endpoints and are used as sinks for message routes. Devices cannot
write directly to the additional endpoints. To learn more about message routes, see the developer guide entry
on sending and receiving messages with IoT hub.
IoT Hub currently supports the following Azure services as additional endpoints:
Event Hubs
Service Bus Queues
Service Bus Topics
IoT Hub needs write access to these service endpoints for message routing to work. If you configure your
endpoints through the Azure portal, the necessary permissions are added for you. Make sure you configure
your services to support the expected throughput. You may need to monitor your additional endpoints when
you first configure your IoT solution and then make any necessary adjustments for the actual load.
If a message matches multiple routes that all point to the same endpoint, IoT Hub delivers message to that
endpoint only once. Therefore, you do not need to configure deduplication on your Service Bus queue or topic.
In partitioned queues, partition affinity guarantees message ordering. Queues with sessions enabled are not
supported as endpoints. Partitioned queues and topics with deduplication enabled are also not supported.
For the limits on the number of endpoints you can add, see Quotas and throttling.

Field gateways
In an IoT solution, a field gateway sits between your devices and your IoT Hub endpoints. It is typically located
close to your devices. Your devices communicate directly with the field gateway by using a protocol supported
by the devices. The field gateway connects to an IoT Hub endpoint using a protocol that is supported by IoT
Hub. A field gateway can be highly specialized hardware or a low-power computer running software that
accomplishes the end-to-end scenario for which the gateway is intended.
You can use the Azure IoT Gateway SDK to implement a field gateway. This SDK offers specific functionality
such as the ability to multiplex the communication from multiple devices onto the same IoT Hub connection.

Next steps
Other reference topics in this IoT Hub developer guide include:
IoT Hub query language for device twins and jobs
Quotas and throttling
IoT Hub MQTT support
Reference - IoT Hub query language for device
twins and jobs
2/2/2017 • 12 min to read • Edit on GitHub

Overview
IoT Hub provides a powerful SQL-like language to retrieve information regarding device twins and jobs. This
article presents:
An introduction to the major features of the IoT Hub query language, and
The detailed description of the language.

Get started with device twin queries

Device twins can contain arbitrary JSON objects as both tags and properties. IoT Hub enables you to query
device twins as a single JSON document containing all device twin information. Assume, for instance, that
your IoT hub device twins have the following structure:

{
"deviceId": "myDeviceId",
"etag": "AAAAAAAAAAc=",
"tags": {
"location": {
"region": "US",
"plant": "Redmond43"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
"sendFrequencyInSecs": 300
},
"$metadata": {
...
},
"$version": 4
},
"reported": {
"connectivity": {
"type": "cellular"
},
"telemetryConfig": {
"configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
"sendFrequencyInSecs": 300,
"status": "Success"
},
"$metadata": {
...
},
"$version": 7
}
}
}

IoT Hub exposes the device twins as a document collection called devices. So the following query retrieves
the whole set of device twins:

SELECT * FROM devices

NOTE
Azure IoT SDKs support paging of large results.

IoT Hub allows you to retrieve device twins filtering with arbitrary conditions. For instance,

SELECT * FROM devices

WHERE tags.location.region = 'US'

retrieves the device twins with the location.region tag set to US. Boolean operators and arithmetic
comparisons are supported as well, for example

SELECT * FROM devices

WHERE tags.location.region = 'US'
AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

retrieves all device twins located in the US configured to send telemetry less often than every minute. As a
convenience, it is also possible to use array constants with the IN and NIN (not in) operators. For instance,

SELECT * FROM devices

WHERE property.reported.connectivity IN ['wired', 'wifi']

retrieves all device twins that reported wifi or wired connectivity. It is often necessary to identify all device
twins that contain a specific property. IoT Hub supports the function is_defined() for this purpose. For
instance,

SELECT * FROM devices

WHERE is_defined(property.reported.connectivity)

retrieved all device twins that define the connectivity reported property. Refer to the WHERE clause section
for the full reference of the filtering capabilities.
Grouping and aggregations are also supported. For instance,

SELECT properties.reported.telemetryConfig.status AS status,

COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status

returns the count of the devices in each telemetry configuration status.

[
{
"numberOfDevices": 3,
"status": "Success"
},
{
"numberOfDevices": 2,
"status": "Pending"
},
{
"numberOfDevices": 1,
"status": "Error"
}
]

The preceding example illustrates a situation where three devices reported successful configuration, two are
still applying the configuration, and one reported an error.
C# example
The query functionality is exposed by the C# service SDK in the RegistryManager class. Here is an example of
a simple query:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);

while (query.HasMoreResults)
{
var page = await query.GetNextAsTwinAsync();
foreach (var twin in page)
{
// do work on twin object
}
}

Note how the query object is instantiated with a page size (up to 1000), and then multiple pages can be
retrieved by calling the GetNextAsTwinAsync methods multiple times. Note that the query object exposes
multiple Next\*, depending on the deserialization option required by the query, such as device twin or job
objects, or plain JSON to be used when using projections.
Node.js example
The query functionality is exposed by the Azure IoT service SDK for Node.js in the Registry object. Here is an
example of a simple query:

var query = registry.createQuery('SELECT * FROM devices', 100);

var onResults = function(err, results) {
if (err) {
console.error('Failed to fetch the results: ' + err.message);
} else {
// Do something with the results
results.forEach(function(twin) {
console.log(twin.deviceId);
});

if (query.hasMoreResults) {
query.nextAsTwin(onResults);
}
}
};
query.nextAsTwin(onResults);

Note how the query object is instantiated with a page size (up to 1000), and then multiple pages can be
retrieved by calling the nextAsTwin methods multiple times. Note that the query object exposes multiple
next\*, depending on the deserialization option required by the query, such as device twin or job objects, or
plain JSON to be used when using projections.
Limitations
Currently, comparisons are supported only between primitive types (no objects), for instance
... WHERE properties.desired.config = properties.reported.config is supported only if those properties have
primitive values.

Get started with jobs queries

Jobs provide a way to execute operations on sets of devices. Each device twin contains the information of the
jobs of which it is part in a collection called jobs. Logically,

{
"deviceId": "myDeviceId",
"etag": "AAAAAAAAAAc=",
"tags": {
...
},
"properties": {
...
},
"jobs": [
{
"deviceId": "myDeviceId",
"jobId": "myJobId",
"jobType": "scheduleTwinUpdate",
"status": "completed",
"startTimeUtc": "2016-09-29T18:18:52.7418462",
"endTimeUtc": "2016-09-29T18:20:52.7418462",
"createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
"lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
"outcome": {
"deviceMethodResponse": null
}
},
...
]
}

Currently, this collection is queryable as devices.jobs in the IoT Hub query language.

IMPORTANT
Currently, the jobs property is never returned when querying device twins (that is, queries that contains 'FROM
devices'). It can only be accessed directly with queries using FROM devices.jobs .

For instance, to get all jobs (past and scheduled) that affect a single device, you can use the following query:

SELECT * FROM devices.jobs

WHERE devices.jobs.deviceId = 'myDeviceId'

Note how this query provides the device-specific status (and possibly the direct method response) of each job
returned. It is also possible to filter with arbitrary Boolean conditions on all object properties in the
devices.jobs collection. For instance, the following query:
SELECT * FROM devices.jobs
WHERE devices.jobs.deviceId = 'myDeviceId'
AND devices.jobs.jobType = 'scheduleTwinUpdate'
AND devices.jobs.status = 'completed'
AND devices.jobs.createdTimeUtc > '2016-09-01'

retrieves all completed device twin update jobs for device myDeviceId that were created after September
2016.
It is also possible to retrieve the per-device outcomes of a single job.

SELECT * FROM devices.jobs

WHERE devices.jobs.jobId = 'myJobId'

Limitations
Currently, queries on devices.jobs do not support:
Projections, therefore only SELECT * is possible.
Conditions that refer to the device twin in addition to job properties (see the preceding section).
Performing aggregations, such as count, avg, group by.

Get started with device-to-cloud message routes query expressions

Using device-to-cloud routes, you can configure IoT Hub to dispatch device-to-cloud messages to different
endpoints based on expressions evaluated against individual messages.
The route condition uses the same IoT Hub query language as conditions in twin and job queries. Route
conditions are evaluated on the message properties assuming the following JSON representation:

{
"$messageId": "",
"$enqueuedTime": "",
"$to": "",
"$expiryTimeUtc": "",
"$correlationId": "",
"$userId": "",
"$ack": "",
"$connectionDeviceId": "",
"$connectionDeviceGenerationId": "",
"$connectionAuthMethod": "",
"$content-type": "",
"$content-encoding": ""

"userProperty1": "",
"userProperty2": ""
}

Message system properties are prefixed with the '$' symbol. User properties are always accessed with their
name. If a user property name happens to coincide with a system property (such as $to ), the user property
will be retrieved with the $to expression. You can always access the system property using brackets {} : for
instance, you can use the expression {$to} to access the system property to . Bracketed property names
always retrieve the corresponding system property.
Remember that property names are case insensitive.
NOTE
All message properties are strings. System properties, as described in the developer guide, are currently not available to
use in queries.

For example, if you use a messageType property, you might want to route all telemetry to one endpoint, and all
alerts to another endpoint. You can write the following expression to route the telemetry:

messageType = 'telemetry'

And the following expression to route the alert messages:

messageType = 'alert'

Boolean expressions and functions are also supported. This feature enables you to distinguish between
severity level, for example:

messageType = 'alerts' AND as_number(severity) <= 2

Refer to the Expression and conditions section for the full list of supported operators and functions.

Basics of an IoT Hub query

Every IoT Hub query consists of a SELECT and FROM clauses and by optional WHERE and GROUP BY clauses.
Every query is run on a collection of JSON documents, for example device twins. The FROM clause indicates
the document collection to be iterated on (devices or devices.jobs). Then, the filter in the WHERE clause is
applied. With aggregations, the results of this step are grouped as specified in the GROUP BY clause and, for
each group, a row is generated as specified in the SELECT clause.

SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]

FROM clause
The FROM clause can assume only two values: FROM devices, to query device twins, or FROM devices.jobs,
to query job per-device details.

WHERE clause
The WHERE clause is optional. It specifies one or more conditions that the JSON documents in the FROM
collection must satisfy to be included as part of the result. Any JSON document must evaluate the specified
conditions to "true" to be included in the result.
The allowed conditions are described in section Expressions and conditions.

SELECT clause
The SELECT clause (SELECT ) is mandatory and specifies what values are retrieved from the query. It specifies
the JSON values to be used to generate new JSON objects. For each element of the filtered (and optionally
grouped) subset of the FROM collection, the projection phase generates a new JSON object, constructed with
the values specified in the SELECT clause.
Following is the grammar of the SELECT clause:

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
'*'
| <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
attribute_name
| <projection_element> '.' attribute_name
| <aggregate>

<aggregate> :==
count()
| avg(<projection_element>)
| sum(<projection_element>)
| min(<projection_element>)
| max(<projection_element>)

where attribute_name refers to any property of the JSON document in the FROM collection. Some examples
of SELECT clauses can be found in the Getting started with device twin queries section.
Currently, selection clauses different than SELECT \* are only supported in aggregate queries on device twins.

GROUP BY clause
The GROUP BY clause is an optional step that can be executed after the filter specified in the WHERE clause,
and before the projection specified in the SELECT. It groups documents based on the value of an attribute.
These groups are used to generate aggregated values as specified in the SELECT clause.
An example of a query using GROUP BY is:

SELECT properties.reported.telemetryConfig.status AS status,

COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status

The formal syntax for GROUP BY is:

GROUP BY <group_by_element>
<group_by_element> :==
attribute_name
| < group_by_element > '.' attribute_name

where attribute_name refers to any property of the JSON document in the FROM collection.
Currently, the GROUP BY clause is only supported when querying device twins.

Expressions and conditions

At a high level, an expression:
Evaluates to an instance of a JSON type (such as Boolean, number, string, array, or object), and
Is defined by manipulating data coming from the device JSON document and constants using built-in
operators and functions.
Conditions are expressions that evaluate to a Boolean. Any constant different than Boolean true is considered
as false (including null, undefined, any object or array instance, any string, and clearly the Boolean false).
The syntax for expressions is:

<expression> ::=
<constant> |
attribute_name |
<function_call> |
<expression> binary_operator <expression> |
<create_array_expression> |
'(' <expression> ')'

<function_call> ::=
<function_name> '(' expression ')'

<constant> ::=
<undefined_constant>
| <null_constant>
| <number_constant>
| <string_constant>
| <array_constant>

<undefined_constant> ::= undefined

<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

where:

SYMBOL DEFINITION

attribute_name Any property of the JSON document in the FROM

collection.

binary_operator Any binary operator listed in the Operators section.

function_name Any function listed in the Functions section.

decimal_literal A float expressed in decimal notation.

hexadecimal_literal A number expressed by the string ‘0x’ followed by a string

of hexadecimal digits.

string_literal String literals are Unicode strings represented by a

sequence of zero or more Unicode characters or escape
sequences. String literals are enclosed in single quotes
(apostrophe: ' ) or double quotes (quotation mark: ").
Allowed escapes: \' , \" , \\ , \uXXXX for Unicode
characters defined by 4 hexadecimal digits.

Operators
The following operators are supported:

FAMILY OPERATORS

Arithmetic +,-,*,/,%
FAMILY OPERATORS

Logical AND, OR, NOT

Comparison =, !=, <, >, <=, >=, <>

Functions
When querying twins and jobs the only supported function is:

FUNCTION DESCRIPTION

IS_DEFINED(property) Returns a Boolean indicating if the property has been

assigned a value (including null ).

In routes conditions, the following math functions are supported:

FUNCTION DESCRIPTION

ABS(x) Returns the absolute (positive) value of the specified

numeric expression.

EXP(x) Returns the exponential value of the specified numeric

expression (e^x).

POWER(x,y) Returns the value of the specified expression to the

specified power (x^y).

SQUARE(x) Returns the square of the specified numeric value.

CEILING(x) Returns the smallest integer value greater than, or equal to,
the specified numeric expression.

FLOOR(x) Returns the largest integer less than or equal to the

specified numeric expression.

SIGN(x) Returns the positive (+1), zero (0), or negative (-1) sign of
the specified numeric expression.

SQRT(x) Returns the square of the specified numeric value.

In routes conditions, the following type checking and casting functions are supported:

FUNCTION DESCRIPTION

AS_NUMBER Converts the input string to a number. noop if input is a

number; Undefined if string does not represent a
number.

IS_ARRAY Returns a Boolean value indicating if the type of the

specified expression is an array.

IS_BOOL Returns a Boolean value indicating if the type of the

specified expression is a Boolean.
FUNCTION DESCRIPTION

IS_DEFINED Returns a Boolean indicating if the property has been

assigned a value.

IS_NULL Returns a Boolean value indicating if the type of the

specified expression is null.

IS_NUMBER Returns a Boolean value indicating if the type of the

specified expression is a number.

IS_OBJECT Returns a Boolean value indicating if the type of the

specified expression is a JSON object.

IS_PRIMITIVE Returns a Boolean value indicating if the type of the

specified expression is a primitive (string, Boolean, numeric
or null ).

IS_STRING Returns a Boolean value indicating if the type of the

specified expression is a string.

In routes conditions, the following string functions are supported:

FUNCTION DESCRIPTION

CONCAT(x, …) Returns a string that is the result of concatenating two or

more string values.

LENGTH(x) Returns the number of characters of the specified string

expression.

LOWER(x) Returns a string expression after converting uppercase

character data to lowercase.

UPPER(x) Returns a string expression after converting lowercase

character data to uppercase.

SUBSTRING(string, start [, length]) Returns part of a string expression starting at the specified
character zero-based position and continues to the
specified length, or to the end of the string.

INDEX_OF(string, fragment) Returns the starting position of the first occurrence of the
second string expression within the first specified string
expression, or -1 if the string is not found.

STARTS_WITH(x, y) Returns a Boolean indicating whether the first string

expression starts with the second.

ENDS_WITH(x, y) Returns a Boolean indicating whether the first string

expression ends with the second.

CONTAINS(x,y) Returns a Boolean indicating whether the first string

expression contains the second.

Next steps
Learn how to execute queries in your apps using Azure IoT SDKs.
Reference - IoT Hub quotas and throttling
1/31/2017 • 2 min to read • Edit on GitHub

Quotas and throttling

Each Azure subscription can have at most 10 IoT hubs, and at most 1 Free hub.
Each IoT hub is provisioned with a certain number of units in a specific SKU (for more information, see Azure
IoT Hub Pricing). The SKU and number of units determine the maximum daily quota of messages that you can
send.
The SKU also determines the throttling limits that IoT Hub enforces on all operations.

Operation throttles
Operation throttles are rate limitations that are applied in the minute ranges, and are intended to avoid
abuse. IoT Hub tries to avoid returning errors whenever possible, but it starts returning exceptions if the
throttle is violated for too long.
The following is the list of enforced throttles. Values refer to an individual hub.

THROTTLE FREE AND S1 HUBS S2 HUBS S3 HUBS

Identity registry operations 100/min/unit 100/min/unit 5000/min/unit

(create, retrieve, list,
update, delete)

Device connections Max of 100/sec or 120/sec/unit 6000/sec/unit

12/sec/unit
For example, two S1 units
are 2*12 = 24/sec, but you
have at least 100/sec
across your units. With
nine S1 units, you have
108/sec (9*12) across your
units.

Device-to-cloud sends Max of 100/sec or 120/sec/unit 6000/sec/unit

12/sec/unit
For example, two S1 units
are 2*12 = 24/sec, but you
have at least 100/sec
across your units. With
nine S1 units, you have
108/sec (9*12) across your
units.

Cloud-to-device sends 100/min/unit 100/min/unit 5000/min/unit

Cloud-to-device receives 1000/min/unit 1000/min/unit 50000/min/unit

(only when device uses
HTTP)
THROTTLE FREE AND S1 HUBS S2 HUBS S3 HUBS

File upload 100 file upload 100 file upload 5000 file upload
notifications/min/unit notifications/min/unit notifications/min/unit

Direct methods 10/sec/unit 30/sec/unit 1500/sec/unit

Device twin reads 10/sec Maximum of 10/sec or 50/sec/unit

1/sec/unit

Device twin updates 10/sec Maximum of 10/sec or 50/sec/unit

1/sec/unit

Jobs operations 100/min/unit 100/min/unit 5000/min/unit

(create, update, list, delete)

Jobs per-device operation 10/sec Maximum of 10/sec or 50/sec/unit

throughput 1/sec/unit

It is important to clarify that the device connections throttle governs the rate at which new device connections
can be established with an IoT hub, and not the maximum number of simultaneously connected devices. The
throttle depends on the number of units that are provisioned for the IoT hub.
For example, if you buy a single S1 unit, you get a throttle of 100 connections per second. Therefore, to
connect 100,000 devices, it takes at least 1000 seconds (approximately 16 minutes). However, you can have
as many simultaneously connected devices as you have devices registered in your identity registry.
For an in-depth discussion of IoT Hub throttling behavior, see the blog post IoT Hub throttling and you.

NOTE
At any given time, it is possible to increase quotas or throttle limits by increasing the number of provisioned units in
an IoT hub.

IMPORTANT
Identity registry operations are intended for run-time use in device management and provisioning scenarios. Reading
or updating a large number of device identities is supported through import and export jobs.

Other limits
IoT Hub enforces other limits on its different functionalities.

OPERATION LIMIT

File upload URIs 10000 SAS URIs can be out for a storage account at one
time.
10 SAS URIs/device can be out at one time.

Jobs Job history is retained up to 30 days

Max concurrent jobs is 1 (for Free and S1, 5 (for S2), 10 (for
S3).
OPERATION LIMIT

Additional endpoints Paid SKU hubs may have 10 additional endpoints. Free SKU
hubs may have one additional endpoint.

Message routing rules Paid SKU hubs may have 100 routing rules. Free SKU hubs
may have five routing rules.

Next steps
Other reference topics in this IoT Hub developer guide include:
IoT Hub endpoints
IoT Hub query language for device twins and jobs
IoT Hub MQTT support
Azure IoT Hub pricing information
1/17/2017 • 3 min to read • Edit on GitHub

Azure IoT Hub pricing provides the general information on different SKUs and pricing for IoT Hub. This article
contains additional details on how the various IoT Hub functionalities are metered as messages by IoT Hub.

Charges per operation

OPERATION BILLING INFORMATION

Identity registry operations Not charged.

(create, retrieve, list, update, delete)

Device-to-cloud messages Successfully sent messages are charged in 4KB chunks on

ingress into IoT Hub, for example a 6KB message is charged 2
messages.

Cloud-to-device messages Successfully sent messages are charged in 4KB chunks, for
example a 6KB message is charged 2 messages.

File uploads File transfer to Azure Storage is not metered by IoT Hub. File
transfer initiation and completion messages are charged as
messaged metered in 4KB increments. For instance,
transferring a 10MB file is charged two messages in addition
to the Azure Storage cost.

Direct methods Successful method requests are charged in 4KB chunks,

responses with non-empty bodies are charged in 4KB as
additional messages. Requests to disconnected devices are
charged as messages in 4KB chunks. For instance, a method
with a 6KB body that results in a response with no body from
the device, is charged as two messages; a method with a 6KB
body that results in a 1KB response from the device is charged
as two messages for the request plus another message for the
response.

Device twin reads Device twin reads from the device and from the solution back
end are charged as messages in 512 bytes chunks. For
instance, reading a 6KB device twin is charged as 12 messages.

Device twin updates (tags and properties) Device twin updates from the device and the device are
charged as messages in 512 bytes chunks. For instance,
reading a 6KB device twin is charged as 12 messages.

Device twin queries Queries are charged as messages depending on the result size
in 512 bytes chunks.

Jobs operations Not charged.

(create, update, list, delete)
OPERATION BILLING INFORMATION

Jobs per-device operations Jobs operations (such as device twin updates, and methods)
are charged as normal. For instance, a job resulting in 1000
method calls with 1KB requests and empty-body responses is
charged 1000 messages.

NOTE
All sizes are computed considering the payload size in bytes (protocol framing is ignored). In case of messages (which have
properties and body) the size is computed in a protocol-agnostic way, as described in the IoT Hub messaging developer's
guide.

Example #1
A device sends one 1KB device-to-cloud message per minute to IoT Hub, which is then read by Azure Stream
Analytics. The solution back end invokes a method (with 512 bytes payload) on the device every ten minutes to
trigger a specific action. The device responds to the method with a result of 200 bytes.
The device consumes 1 message * 60 minutes * 24 hours = 1440 messages per day for the device-to-cloud
messages, and 2 request plus response * 6 times per hour * 24 hours = 288 messages for the methods, for a total
of 1728 messages per day.

Example #2
A device sends one 100KB device-to-cloud message every hour. It also updates its device twin with 1KB payloads
every 4 hours. The solution back end, once per day, reads the 14KB device twin and updates it with 512 bytes
payloads to change configurations.
The device consumes 25 (100KB / 4KB) messages * 24 hours for device-to-cloud messages, plus 1 message * 6
times per day for device twin updates, for a total of 156 messages per day. The solution back end consumes 28
messages (14KB / 0.5KB) to read the device twin, plus 1 message to update it, for a total of 29 messages.
In total, the device and the solution back end consume 185 messages per day.
Azure IoT SDKs
2/13/2017 • 1 min to read • Edit on GitHub

Azure IoT device SDK

The Microsoft Azure IoT device SDKs contain code that facilitates building devices and applications that
connect to and are managed by Azure IoT Hub services.
The following Azure IoT device SDKs are available to download from GitHub:
Azure IoT device SDK for C written in ANSI C (C99) for portability and broad platform compatibility.
Azure IoT device SDK for .NET
Azure IoT device SDK for Java
Azure IoT device SDK for Node.js
Azure IoT device SDK for Python

NOTE
See the readme files in the GitHub repositories for information about using language and platform-specific package
managers to install binaries and dependencies on your development machine.

OS platform and hardware compatibility

For more information about SDK compatibility with specific hardware devices, see the Azure Certified for
IoT device catalog.

Azure IoT service SDK

The Azure IoT service SDKs contain code to facilitate building applications that interact directly with IoT
Hub to manage devices and security.
The following Azure IoT service SDKs are available to download from GitHub:
Azure IoT service SDK for .NET
Azure IoT service SDK for Node.js
Azure IoT service SDK for Java
Azure IoT service SDK for Python

NOTE
See the readme files in the GitHub repositories for information about using language and platform-specific package
managers to install binaries and dependencies on your development machine.

Azure IoT Gateway SDK

This Azure IoT Gateway SDK contains the infrastructure and modules to create IoT gateway solutions. You
can extend the SDK to create gateways tailored to any end-to-end scenario.
You can download the Azure IoT Gateway SDK from GitHub.
Online API reference documentation
The following list contains links to online API reference documentation for Azure IoT device, service, and
gateway libraries:
Internet of Things (IoT) .NET
IoT Hub REST
Azure IoT device SDK for C
Azure IoT device SDK for Java
Azure IoT service SDK for Java
Azure IoT device SDK for Node.js
Azure IoT service SDK for Node.js
Azure IoT gateway SDK

Next steps
Other reference topics in this IoT Hub developer guide include:
IoT Hub endpoints
IoT Hub query language for device twins and jobs
Quotas and throttling
IoT Hub MQTT support
IoT Hub MQTT support
2/10/2017 • 8 min to read • Edit on GitHub

IoT Hub enables devices to communicate with the IoT Hub device endpoints using the MQTT v3.1.1 protocol on
port 8883 or MQTT v3.1.1 over WebSocket protocol on port 443. IoT Hub requires all device communication to
be secured using TLS/SSL (hence, IoT Hub doesn’t support non-secure connections over port 1883).

Connecting to IoT Hub

A device can use the MQTT protocol to connect to an IoT hub either by using the libraries in the Azure IoT SDKs
or by using the MQTT protocol directly.

Using the device SDKs

Device SDKs that support the MQTT protocol are available for Java, Node.js, C, C#, and Python. The device SDKs
use the standard IoT Hub connection string to establish a connection to an IoT hub. To use the MQTT protocol,
the client protocol parameter must be set to MQTT. By default, the device SDKs connect to an IoT Hub with the
CleanSession flag set to 0 and use QoS 1 for message exchange with the IoT hub.
When a device is connected to an IoT hub, the device SDKs provide methods that enable the device to send
messages to and receive messages from an IoT hub.
The following table contains links to code samples for each supported language and specifies the parameter to
use to establish a connection to IoT Hub using the MQTT protocol.

LANGUAGE PROTOCOL PARAMETER

Node.js azure-iot-device-mqtt

Java IotHubClientProtocol.MQTT

C MQTT_Protocol

C# TransportType.Mqtt

Python IoTHubTransportProvider.MQTT

Migrating a device app from AMQP to MQTT

If you are using the device SDKs, switching from using AMQP to MQTT requires changing the protocol
parameter in the client initialization as stated above.
When doing so, make sure to check the following items:
AMQP returns errors for many conditions, while MQTT terminates the connection. As a result your exception
handling logic might require some changes.
MQTT does not support the reject operations when receiving cloud-to-device messages. If your back-end
app needs to receive a response from the device app, consider using direct methods.

Using the MQTT protocol directly

If a device cannot use the device SDKs, it can still connect to the public device endpoints using the MQTT
protocol. In the CONNECT packet the device should use the following values:
For the ClientId field, use the deviceId.
For the Username field, use {iothubhostname}/{device_id}/api-version=2016-11-14 , where
{iothubhostname} is the full CName of the IoT hub.
For example, if the name of your IoT hub is contoso.azure-devices.net and if the name of your device
is MyDevice01, the full Username field should contain
contoso.azure-devices.net/MyDevice01/api-version=2016-11-14 .

For the Password field, use a SAS token. The format of the SAS token is the same as for both the HTTP
and AMQP protocols:
SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI} .

For more information about how to generate SAS tokens, see the device section of Using IoT Hub
security tokens.
When testing, you can also use the device explorer tool to quickly generate a SAS token that you can
copy and paste into your own code:
1. Go to the Management tab in Device Explorer.
2. Click SAS Token (top right).
3. On SASTokenForm, select your device in the DeviceID drop down. Set your TTL.
4. Click Generate to create your token.
The SAS token that's generated has this structure:
HostName={your hub name}.azure-
devices.net;DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={your hub
name}.azure-devices.net%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-
14&sig=vSgHBMUG.....Ntg%3d&se=1456481802
.
The part of this token to use as the Password field to connect using MQTT is:
SharedAccessSignature sr={your hub name}.azure-devices.net%2Fdevices%2FMyDevice01%2Fapi-
version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802
.
For MQTT connect and disconnect packets, IoT Hub issues an event on the Operations Monitoring channel
with additional information that can help you to troubleshoot connectivity issues.
Sending device -to -cloud messages
After making a successful connection, a device can send messages to IoT Hub using
devices/{device_id}/messages/events/ or devices/{device_id}/messages/events/{property_bag} as a Topic
Name. The {property_bag} element enables the device to send messages with additional properties in a url-
encoded format. For example:

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC

2396-encoded(<PropertyValue2>)…

NOTE
This {property_bag} element uses the same encoding as for query strings in the HTTP protocol.

The device app can also use devices/{device_id}/messages/events/{property_bag} as the Will topic name to
define Will messages to be forwarded as a telemetry message.
IoT Hub does not support QoS 2 messages. If a device app publishes a message with QoS 2, IoT Hub closes
the network connection.
IoT Hub does not persist Retain messages. If a device sends a message with the RETAIN flag set to 1, IoT
Hub adds the x-opt-retain application property to the message. In this case, instead of persisting the retain
message, IoT Hub passes it to the backend app.
IoT Hub only supports one active MQTT connection per device. Any new MQTT connection on behalf of the
same device ID causes IoT Hub to drop the existing connection.
Refer to Messaging developer's guide for more information.
Receiving cloud-to -device messages
To receive messages from IoT Hub, a device should subscribe using
devices/{device_id}/messages/devicebound/# as a Topic Filter. The multi-level wildcard # in the Topic Filter is
used only to allow the device to receive additional properties in the topic name. IoT Hub does not allow the
usage of the # or ? wildcards for filtering of sub-topics. Since IoT Hub is not a general purpose pub-sub
messaging broker, it only supports the documented topic names and topic filters.
Please note, that the device will not receive any messages from IoT Hub, before it has successfully subscribed to
its device specific endpoint, represented by the devices/{device_id}/messages/devicebound/# topic filter. After
successful subscription has been established, the device will start receiving only cloud-to-device messages that
have been sent to it after the time of the subscription. If the device connects with CleanSession flag set to 0,
the subscription will be persisted across different sessions. In this case, the next time it connects with
CleanSession 0 the device will receive outstanding messages that have been sent to it while it was
disconnected. If the device uses CleanSession flag set to 1 though, it will not receive any messages from IoT
Hub until it subscribes to its device-endpoint.
IoT Hub delivers messages with the Topic Name devices/{device_id}/messages/devicebound/ , or
devices/{device_id}/messages/devicebound/{property_bag} if there are any message properties. {property_bag}
contains url-encoded key/value pairs of message properties. Only application properties and user-settable
system properties (such as messageId or correlationId) are included in the property bag. System property
names have the prefix $, application properties use the original property name with no prefix.
When a device app subscribes to a topic with QoS 2, IoT Hub grants maximum QoS level 1 in the SUBACK
packet. After that, IoT Hub will deliver messages to the device using QoS 1.
Retrieving a device twin's properties
First, a device subscribes to $iothub/twin/res/# , to receive the operation's responses. Then, it sends an empty
message to topic $iothub/twin/GET/?$rid={request id} , with a populated value for request id. The service will
then send a response message contaning the device twin data on topic
$iothub/twin/res/{status}/?$rid={request id} , using the same request id as the request.

Request id can be any valid value for a message property value, as per IoT Hub messaging develper's guide,
and status is validated as an integer. The reponse body will contain the properties section of the device twin:
The body of the identity registry entry limited to the “properties” member, e.g.
{
"properties": {
"desired": {
"telemetrySendFrequency": "5m",
"$version": 12
},
"reported": {
"telemetrySendFrequency": "5m",
"batteryLevel": 55,
"$version": 123
}
}
}

The possible status codes are:

STATUS DESCRIPTION

200 Success

429 Too many requests (throttled), as per IoT Hub throttling

5** Server errors

Refer to the Device twins developer's guide for more information.

Update device twin's reported properties
The following sequence describes how a device updates the reported properties in the device twin in IoT Hub:
1. A device must first subscribe to the $iothub/twin/res/# topic to receive the operation's responses from
IoT Hub.
2. A device sends a message that contains the device twin update to the
$iothub/twin/PATCH/properties/reported/?$rid={request id} topic. This message includes a request id
value.
3. The service then sends a response message that contains the new ETag value for the reported properties
collection on topic $iothub/twin/res/{status}/?$rid={request id} . This response message uses the same
request id as the request.
The request message body contains a JSON document which provides new values for reported properties (no
other property or metadata can be modified). Each member in the JSON document updates or add the
corresponding member in the device twin’s document. A member set to null , deletes the member from the
containing object. For example:

{
"telemetrySendFrequency": "35m",
"batteryLevel": 60
}

The possible status codes are:

STATUS DESCRIPTION

200 Success
STATUS DESCRIPTION

400 Bad Request. Malformed JSON

429 Too many requests (throttled), as per IoT Hub throttling

5** Server errors

Refer to the Device twins developer's guide for more information.

Receiving desired properties update notifications
When a device is connected, IoT Hub sends notifications to the topic
$iothub/twin/PATCH/properties/desired/?$version={new version} , which contain the content of the update
performed by the solution back end. For example:

{
"telemetrySendFrequency": "5m",
"route": null
}

As for property updates, null values means that the JSON object member is being deleted.

IMPORTANT
IoT Hub generates change notifications only when devices are connected, make sure to implement the device
reconnection flow to keep the desired properties synchronized between IoT Hub and the device app.

Refer to the Device twins developer's guide for more information.

Respond to a direct method
First, a device has to subscribe to $iothub/methods/POST/# . IoT Hub sends method requests to the topic
$iothub/methods/POST/{method name}/?$rid={request id} , with either a valid JSON or an empty body.

To respond, the device will send a message with a valid JSON or empty body to the topic
$iothub/methods/res/{status}/?$rid={request id} , where request id has to match the one in the request
message, and status has to be an integer.
Refer to the Direct method developer's guide for more information.
Additional considerations
As a final consideration, if you need to customize the MQTT protocol behavior on the cloud side, you should
review the Azure IoT protocol gateway that enables you to deploy a high-performance custom protocol
gateway that interfaces directly with IoT Hub. The Azure IoT protocol gateway enables you to customize the
device protocol to accommodate brownfield MQTT deployments or other custom protocols. This approach does
require, however, that you run and operate a custom protocol gateway.

Next steps
For more information, see Notes on MQTT support in the IoT Hub developer guide.
To learn more about the MQTT protocol, see the MQTT documentation.
To learn more about planning your IoT Hub deployment, see:
Azure Certified for IoT device catalog
Support additional protocols
Compare with Event Hubs
Scaling, HA, and DR
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
Glossary of IoT Hub terms
2/8/2017 • 15 min to read • Edit on GitHub

This article lists some of the common terms used in the IoT Hub articles.

Advanced Message Queueing Protocol

Advanced Message Queueing Protocol (AMQP) is one of the messaging protocols that IoT Hub supports for
communicating with devices. For more information about the messaging protocols that IoT Hub supports, see Send
and receive messages with IoT Hub.

Azure CLI
The Azure CLI is a cross-platform, open-source, shell-based, command tool for creating and managing resources in
Microsoft Azure. This version of the CLI is implemented using Node.js.

Azure CLI 2.0 (Preview)

The Azure CLI 2.0 (Preview) is a cross-platform, open-source, shell-based, command tool for creating and
managing resources in Microsoft Azure. This preview version of the CLI is implemented using Python.

Azure IoT device SDKs

There are device SDKs available for multiple languages that enable you to create device apps that interact with an
IoT hub. The IoT Hub tutorials show you how to use these device SDKs. You can find the source code and further
information about the device SDKs in this GitHub repository.

Azure IoT Gateway SDK

This SDK enables you to write applications that enable gateway-connected devices to communicate with IoT Hub.
The IoT Hub gateway tutorials show you how to use this SDK. You can find the source code and further information
about the Azure IoT Gateway SDK in this GitHub repository.

Azure IoT service SDKs

There are service SDKs available for multiple languages that enable you to create back-end apps that interact with
an IoT hub. The IoT Hub tutorials show you how to use these service SDKs. You can find the source code and further
information about the service SDKs in this GitHub repository.

Azure portal
The Microsoft Azure portal is a central place where you can provision and manage your Azure resources. It
organizes its content using blades. In some of the IoT Hub tutorials, you may be asked to use the Azure classic
portal.

Azure PowerShell
Azure PowerShell is a collection of cmdlets you can use to manage Azure with Windows PowerShell. You can use
the cmdlets to create, test, deploy, and manage solutions and services delivered through the Azure platform.
Azure Resource Manager
Azure Resource Manager enables you to work with the resources in your solution as a group. You can deploy,
update, or delete the resources for your solution in a single, coordinated operation.

Azure Service Bus

Service Bus provides cloud-enabled communication with enterprise messaging and relayed communication that
helps you connect on-premises solutions with the cloud. Some IoT Hub tutorials make use Service Bus queues.

Azure Storage
Azure Storage is a cloud storage solution. It includes the Blob Storage service that you can use to store
unstructured object data. Some IoT Hub tutorials use blob storage.

Back-end app
In the context of IoT Hub, a back-end app is an app that connects to one of the service-facing endpoints on an IoT
hub. For example, a back-end app might retrieve device-to-cloudmessages or manage the identity registry.
Typically, a back-end app runs in the cloud, but in many of the tutorials the back-end apps are console apps
running on your local development machine.

Built-in endpoints
Every IoT hub includes a built-in endpoint that is Event Hubs-compatible. You can use any mechanism that works
with Event Hubs to read device-to-cloud messages from this endpoint.

Cloud gateway
A cloud gateway enables connectivity for devices that cannot connect directly to IoT Hub. A cloud gateway is hosted
in the cloud in contrast to a field gateway that runs local to your devices. A typical use case for a cloud gateway is to
implement protocol translation for your devices.

Cloud-to-device
Refers to messages sent from an IoT hub to a connected device. Often, these messages are commands that instruct
the device to take an action. For more information, see Send and receive messages with IoT Hub.

Connection string
You use connection strings in your app code to encapsulate the information required to connect to an endpoint. A
connection string typically includes the address of the endpoint and security information, but connection string
formats vary across services. There are two types of connection string associated with the IoT Hub service:
Device connection strings enable devices to connect to the device-facing endpoints on an IoT hub.
IoT Hub connection strings enable back-end apps to connect to the service-facing endpoints on an IoT hub.

Custom endpoints
You can create custom endpoints on an IoT hub to deliver messages dispatched by a routing rule. Custom
endpoints connect directly to an Event hub, a Service Bus queue, or a Service Bus topic.

Custom gateway
A gateway enables connectivity for devices that cannot connect directly to IoT Hub. You can use the Azure IoT
Gateway SDK to build custom gateways that implement custom logic to handle messages and custom protocol
conversions.

Data-point message
A data-point message is a device-to-cloud message that contains telemetry data such as wind speed or
temperature.

Desired configuration
In the context of a device twin, desired configuration refers to the complete set of properties and metadata in the
device twin that should be synchronized with the device.

Desired properties
In the context of a device twin, desired properties is a subsection of the device twin that is used with reported
properties to synchronize device configuration or condition. Desired properties can only be set by a back-end app
and are observed by the device app.

Device-to-cloud
Refers to messages sent from a connected device to IoT Hub. These messages may be data-point or interactive
messages. For more information, see Send and receive messages with IoT Hub.

Device
In the context of IoT, a device is typically a small-scale, standalone computing device that may collect data or control
other devices. For example, a device might be an environmental monitoring device, or a controller for the watering
and ventilation systems in a greenhouse. The device catalog provides a list of hardware devices certified to work
with IoT Hub.

Device app
A device app runs on your device and handles the communication with your IoT hub. Typically, you use one of the
Azure IoT device SDKs when you implement a device app. In many of the IoT tutorials, you use a simulated device
for convenience.

Device condition
Refers to device state information, such as the connectivity method currently in use, as reported by a device app.
Device apps can also report their capabilities. You can query for condition and capability information using device
twins.

Device data
Device data refers to the per-device data stored in the IoT Hub identity registry. It is possible to import and export
this data.

Device explorer
The device explorer is a tool that runs on Windows and enables you to manage your devices in the identity registry,
and send and receive messages to your devices.
Device Identities REST API
The Device Identities REST API enables you to manage your devices registered in the identity registry using a REST
API. Typically, you should use one of the higher-level service SDKs as shown in the IoT Hub tutorials.

Device identity
The device identity is the unique identifier assigned to every device registered in the identity registry.

Device management
Device management encompasses the full lifecycle associated with managing the devices in your IoT solution
including planning, provisioning, configuring, monitoring, and retiring

Device management patterns

IoT hub enables common device management patterns including rebooting, performing factory resets, and
performing firmware updates on your devices.

Device Messaging REST API

You can use the Device Messaging REST API from a device to send device-to-cloud messages to an IoT hub, and
receive cloud-to-device messages from an IoT hub. Typically, you should use one of the higher-level device SDKs as
shown in the IoT Hub tutorials.

Device provisioning
Device provisioning is the process of adding the initial device data to the stores in your solution. To enable a new
device to connect to your hub, you must add a device ID and keys to the IoT Hub identity registry. As part of the
provisioning process, you might need to initialize device-specific data in other solution stores.

Device twin
A device twin is JSON document that stores device state information such as metadata, configurations, and
conditions. IoT Hub persists a device twin for each device that you provision in your IoT hub. Device twins enable
you to synchronize device conditions and configurations between the device and the solution back end. You can
query device twins to locate specific devices and query the status of long-running operations.

Device twin queries

Device twin queries use the SQL-like IoT Hub query language to retrieve information from your device twins. You
can use the same IoT Hub query language to retrieve information about jobs running in your IoT hub.

Device Twin REST API

You can use the Device Twin REST API from the solution back end to manage your device twins. The API enables
you to retrieve and update device twin properties and invoke direct methods. Typically, you should use one of the
higher-level service SDKs as shown in the IoT Hub tutorials.

Device twin synchronization

Device twin synchronization uses the desired properties in your device twins to configure your devices and retrieve
reported properties from your devices to store in the device twin.
Direct method
A direct method is a way for you to trigger a method to execute on a device by invoking an API on your IoT hub.

Endpoint
An IoT hub exposes multiple endpoints that enable your apps to connect to the IoT hub. There are device-facing
endpoints that enable devices to perform operations such as sending device-to-cloud messages and receiving
cloud-to-device messages. There are service-facing management endpoints that enable back-end apps to perform
operations such as device identity management and device twin management. There are service-facing built-in
endpoints for reading device-to-cloud messages. You can create custom endpoints to receive device-to-cloud
messages dispatched by a routing rule.

Event Hubs service

Event Hubs is a highly scalable data ingress service that can ingest millions of events per second. The service
enables you to process and analyze the massive amounts of data produced by your connected devices and
applications. For a comparison with the IoT Hub service, see Comparison of Azure IoT Hub and Azure Event Hubs.

Event Hub-compatible endpoint

To read device-to-cloud messages sent to your IoT hub, you can connect to an endpoint on your hub and use any
Event Hub-compatible method to read those messages. Event Hub-compatible methods include using the Event
Hubs SDKs and Azure Stream Analytics.

Field gateway
A field gateway enables connectivity for devices that cannot connect directly to IoT Hub and is typically deployed
locally with your devices. For more information, see What is Azure IoT Hub?

Free account
You can create a free Azure account to complete the IoT Hub tutorials and experiment with the IoT Hub service (and
other Azure services).

Gateway
A gateway enables connectivity for devices that cannot connect directly to IoT Hub. See also Field Gateway, Cloud
Gateway, and Custom Gateway.

Identity registry
The identity registry is the built-in component of an IoT hub that stores information about the individual devices
permitted to connect to an IoT hub.

Interactive message
An interactive message is a cloud-to-device message that triggers an immediate action in the solution back end. For
example, a device might send an alarm about a failure that should be automatically logged in to a CRM system.

IoT Hub
IoT Hub is a fully managed Azure service that enables reliable and secure bidirectional communications between
millions of devices and a solution back end. For more information, see What is Azure IoT Hub? Using your Azure
subscription, you can create IoT hubs to handle your IoT messaging workloads.

IoT Hub metrics

IoT Hub metrics give you data about the state of the IoT hubs in your Azure subscription. IoT Hub metrics enable
you to assess the overall health of the service and the devices connected to it. IoT Hub metrics can help you see
what is going on with your IoT hub and investigate root-cause issues without needing to contact Azure support.

IoT Hub query language

The IoT Hub query language is a SQL-like language that enables you to query your jobs and device twins.

IoT Hub Resource Provider REST API

You can use the IoT Hub Resource Provider REST API to manage the IoT hubs in your Azure subscription
performing operations such as creating, updating, and deleting hubs.

IoT Suite
Azure IoT Suite packages together multiple Azure services with preconfigured solutions. These preconfigured
solutions enable you to get started quickly with end-to-end implementations of common IoT scenarios. For more
information, see What is Azure IoT Suite?

iothub-explorer
The iothub-explorer is a cross-platform, command-line tool. The tool enables you to manage your devices in the
identity registry, send and receive messages and files from your devices, and monitor your IoT hub operations.

Job
Your solution back end can use jobs to schedule and track activities on a set of devices registered with your IoT hub.
Activities include updating device twin desired properties, updating device twin tags, and invoking direct methods.
IoT Hub also uses jobs to import to and export from the identity registry.

Jobs REST API

The Jobs REST API enables you manage jobs running in your IoT hub.

Module
In the Azure IoT Gateway SDK, a module is a component that performs a specific task. Tasks might include ingesting
a message from a device, transforming a message, or sending a message to an IoT hub. A broker is responsible for
forwarding messages between modules. The Azure IoT Gateway SDK includes a set of sample modules. You can
also create your own custom modules.

MQTT
MQTT is one of the messaging protocols that IoT Hub supports for communicating with devices. For more
information about the messaging protocols that IoT Hub supports, see Send and receive messages with IoT Hub.

Operations monitoring
IoT Hub operations monitoring enables you to monitor the status of operations on your IoT hub in real time. IoT
Hub tracks events across several categories of operations. You can opt into sending events from one or more
categories to an IoT Hub endpoint for processing. You can monitor the data for errors or set up more complex
processing based on data patterns.

Physical device
A physical device is a real device such as a Raspberry Pi that connects to an IoT hub. For convenience, many of the
IoT Hub tutorials use simulated devices to enable you to run samples on your local machine.

Primary and secondary keys

When you connect to a device-facing or service-facing endpoint on an IoT hub, your connection string includes key
to grant you access. When you add a device to the identity registry or add a shared access policy to your hub, the
service generates a primary and secondary key. Having two keys enables you to roll over from one key to another
when you update a key without losing access to the IoT hub.

Protocol gateway
A protocol gateway is typically deployed in the cloud and provides protocol translation services for devices
connecting to IoT Hub. For more information, see What is Azure IoT Hub?

Quotas and throttling

There are various quotas that apply to your use of IoT Hub, many of the quotas vary based on the tier of the IoT
hub. IoT Hub also applies throttles to your use of the service at run time.

Reported configuration
In the context of a device twin, reported configuration refers to the complete set of properties and metadata in the
device twin that should be reported to the solution back end.

Reported properties
In the context of a device twin, reported properties is a subsection of the device twin used with desired properties to
synchronize device configuration or condition. Reported properties can only be set by the device app and can be
read and queried by a back-end app.

Resource group
Azure Resource Manager uses resource groups to group related resources together. You can use a resource group
to perform operations on all the resources on the group simultaneously.

Retry policy
You use a retry policy to handle transient errors when you connect to a cloud service.

Routing rules
You configure routing rules in your IoT hub to route device-to-cloud messages to a built-in endpoint or to custom
endpoints for processing by your solution back end.

SASL PLAIN
SASL PLAIN is a protocol that the AMQP protocol uses to transfer security tokens.
Shared access signature
Shared Access Signatures (SAS) are an authentication mechanism based on SHA-256 secure hashes or URIs. SAS
authentication has two components: a Shared Access Policy and a Shared Access Signature (often called a token). A
device uses SAS to authenticate with an IoT hub. Back-end apps also use SAS to authenticate with the service-facing
endpoints on an IoT hub. Typically, you include the SAS token in the connection string that an app uses to establish
a connection to an IoT hub.

Shared access policy

A shared access policy defines the permissions granted to anyone who has a valid primary or secondary key
associated with that policy. You can manage the shared access policies and keys for your hub in the portal.

Simulated device
For convenience, many of the IoT Hub tutorials use simulated devices to enable you to run samples on your local
machine. In contrast, a physical device is a real device such as a Raspberry Pi that connects to an IoT hub.

Solution
A solution can refer to a Visual Studio solution that includes one or more projects. A solution might also refer to an
IoT solution that includes elements such as devices, device apps, an IoT hub, other Azure services, and back-end
apps.

Subscription
An Azure subscription is where billing takes place. Each Azure resource you create or Azure service you use is
associated with a single subscription. Many quotas also apply at the level of a subscription.

System properties
In the context of a device twin, system properties are read-only and include information regarding the device usage
such as last activity time and connection state.

Tags
In the context of a device twin, tags are device metadata stored and retrieved by the solution back end in the form
of a JSON document. Tags are not visible to apps on a device.

Telemetry
Devices collect telemetry data, such as wind speed or temperature, and use data-point messages to send the
telemetry to an IoT hub.

Token service
You can use a token service to implement an authentication mechanism for your devices. It uses an IoT Hub shared
access policy with DeviceConnect permissions to create device-scoped tokens. These tokens enable a device to
connect to your IoT hub. A device uses a custom authentication mechanism to authenticate with the token service.
IF the device authenticates successfully, the token service issues a SAS token for the device to use to access your IoT
hub.

X.509 client certificate

A device can use an X.509 certificate to authenticate with IoT Hub. Using an X.509 certificate is an alternative to
using a SAS token.
Process IoT Hub device-to-cloud messages using
routes (.NET)
2/2/2017 • 5 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications
between millions of devices and a solution back end. Other tutorials (Get started with IoT Hub and Send cloud-
to-device messages with IoT Hub) show you how to use the basic device-to-cloud and cloud-to-device
messaging functionality of IoT Hub.
This tutorial builds on the Get started with IoT Hub tutorial, and shows you how to use routing rules to dispatch
device-to-cloud messages in an easy, configuration-based way. The tutorial illustrates how to isolate messages
that require immediate action from the solution back end for further processing. For example, a device might
send an alarm message that triggers inserting a ticket into a CRM system. By contrast, data-point messages
simply feed into an analytics engine. For example, temperature telemetry from a device that is to be stored for
later analysis is a data-point message.
At the end of this tutorial, you run three .NET console apps:
SimulatedDevice, a modified version of the app created in the Get started with IoT Hub tutorial, sends
data-point device-to-cloud messages every second, and interactive device-to-cloud messages every 10
seconds. This app uses the AMQP protocol to communicate with IoT Hub.
ReadDeviceToCloudMessages that displays the non-critical telemetry sent by your simulated device app.
ReadCriticalQueue de-queues the critical messages sent by your simulated device app from the Service
Bus queue attached to the IoT hub.

NOTE
IoT Hub has SDK support for many device platforms and languages, including C, Java, and JavaScript. To learn how to
replace the simulated device in this tutorial with a physical device, and how to connect devices to an IoT Hub, see the
Azure IoT Developer Center.

To complete this tutorial, you need the following:

Microsoft Visual Studio 2015.
An active Azure account.
If you don't have an account, you can create a free account in just a couple of minutes.
You should have some basic knowledge of Azure Storage and Azure Service Bus.

Send interactive messages from a simulated device app

In this section, you modify the simulated device app you created in the Get started with IoT Hub tutorial to
occasionally send messages that require immediate processing.
In Visual Studio, in the SimulatedDevice project, replace the SendDeviceToCloudMessagesAsync method with the
following code:
private static async void SendDeviceToCloudMessagesAsync()
{
double avgWindSpeed = 10; // m/s
Random rand = new Random();

while (true)
{
double currentWindSpeed = avgWindSpeed + rand.NextDouble() * 4 - 2;

var telemetryDataPoint = new

{
deviceId = "myFirstDevice",
windSpeed = currentWindSpeed
};
var messageString = JsonConvert.SerializeObject(telemetryDataPoint);
string levelValue;

if (rand.NextDouble() > 0.7)

{
messageString = "This is a critical message";
levelValue = "critical";
}
else
{
levelValue = "normal";
}

var message = new Message(Encoding.ASCII.GetBytes(messageString));

message.Properties.Add("level", levelValue);

await deviceClient.SendEventAsync(message);
Console.WriteLine("{0} > Sent message: {1}", DateTime.Now, messageString);

await Task.Delay(1000);
}
}

This method randomly adds the property "level": "critical" to messages sent by the device, which simulates
a message that requires immediate action by the solution back-end. The device app passes this information in
the message properties, instead of in the message body, so that IoT Hub can route the message to the proper
message destination.

NOTE
You can use message properties to route messages for various scenarios including cold-path processing, in addition to
the hot-path example shown here.

NOTE
For the sake of simplicity, this tutorial does not implement any retry policy. In production code, you should implement a
retry policy such as exponential backoff, as suggested in the MSDN article Transient Fault Handling.

Add a queue to your IoT hub and route messages to it

In this section, you:
Create a Service Bus queue.
Connect it to your IoT hub.
Configure your IoT hub to send messages to the queue based on the presence of a property on the message.
For more information about how to process messages from Service Bus queues, see Get started with queues.
1. Create a Service Bus queue as described in Get started with queues. The queue must be in the same
subscription and region as your IoT hub. Make a note of the namespace and queue name.
2. In the Azure portal, open your IoT hub and click Endpoints.

3. In the Endpoints blade, click Add at the top to add your queue to your IoT hub. Name the endpoint
CriticalQueue and use the drop-downs to select Service Bus queue, the Service Bus namespace in
which your queue resides, and the name of your queue. When you are done, click Save at the bottom.
4. Now click Routes in your IoT Hub. Click Add at the top of the blade to create a routing rule that routes
messages to the queue you just added. Select DeviceTelemetry as the source of data. Enter
level="critical" as the condition, and choose the queue you just added as a custom endpoint as the
routing rule endpoint. When you are done, click Save at the bottom.

Make sure the fallback route is set to ON. This value is the default configuration for an IoT hub.
Read from the queue endpoint
In this section, you read the messages from the queue endpoint.
1. In the current Visual Studio solution, create a Visual C# Windows project by using the Console
Application project template. Name the project ReadCriticalQueue.
2. In Solution Explorer, right-click the ReadCriticalQueue project, and then click Manage NuGet
Packages. This operation displays the NuGet Package Manager window.
3. Search for WindowsAzure.ServiceBus, click Install, and accept the terms of use. This operation
downloads, installs, and adds a reference to the Azure Service Bus, with all its dependencies.
4. Add the following using statements at the top of the Program.cs file:

using System.IO;
using Microsoft.ServiceBus.Messaging;

5. Finally, add the following lines to the Main method. Substitute the connection string with Listen
permissions for the queue:

Console.WriteLine("Receive critical messages. Ctrl-C to exit.\n");

var connectionString = "{service bus listen string}";
var queueName = "{queue name}";

var client = QueueClient.CreateFromConnectionString(connectionString, queueName);

client.OnMessage(message =>
{
Stream stream = message.GetBody<Stream>();
StreamReader reader = new StreamReader(stream, Encoding.ASCII);
string s = reader.ReadToEnd();
Console.WriteLine(String.Format("Message body: {0}", s));
});

Console.ReadLine();

Run the applications

Now you are ready to run the applications.
1. In Visual Studio, in Solution Explorer, right-click your solution and select Set StartUp Projects. Select
Multiple startup projects, then select Start as the action for the ReadDeviceToCloudMessages,
SimulatedDevice, and ReadCriticalQueue projects.
2. Press F5 to start the three console apps. The ReadDeviceToCloudMessages app has only non-critical
messages sent from the SimulatedDevice application, and the ReadCriticalQueue app has only critical
messages.
Next steps
In this tutorial, you learned how to reliably dispatch device-to-cloud messages by using the message routing
functionality of IoT Hub.
The How to send cloud-to-device messages with IoT Hub shows you how to send messages to your devices
from your solution back end.
To see examples of complete end-to-end solutions that use IoT Hub, see Azure IoT Suite.
To learn more about developing solutions with IoT Hub, see the IoT Hub developer guide.
To learn more about message routing in IoT Hub, see Send and receive messages with IoT Hub.
Process IoT Hub device-to-cloud messages (Java)
1/31/2017 • 5 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications between
millions of devices and a solution back end. Other tutorials (Get started with IoT Hub and Send cloud-to-device
messages with IoT Hub) show you how to use the basic device-to-cloud and cloud-to-device messaging
functionality of IoT Hub.
This tutorial builds on the code shown in the Get started with IoT Hub tutorial, and shows you how to use message
routing to process device-to-cloud messages in a scalable way. The tutorial illustrates how to process messages
that require immediate action from the solution back end. For example, a device might send an alarm message that
triggers inserting a ticket into a CRM system. By contrast, data-point messages simply feed into an analytics
engine. For example, temperature telemetry from a device that is to be stored for later analysis is a data-point
message.
At the end of this tutorial, you run three Java console apps:
simulated-device, a modified version of the app created in the Get started with IoT Hub tutorial, sends data-
point device-to-cloud messages every second, and interactive device-to-cloud messages every 10 seconds. This
app uses the AMQP protocol to communicate with IoT Hub.
read-d2c-messages displays the telemetry sent by your simulated device app.
read-critical-queue de-queues the critical messages from the Service Bus queue attached to the IoT hub.

NOTE
IoT Hub has SDK support for many device platforms and languages, including C, Java, and JavaScript. For instructions on
how to replace the simulated device in this tutorial with a physical device, and how to connect devices to an IoT Hub, see the
Azure IoT Developer Center.

To complete this tutorial, you need the following:

A complete working version of the Get started with IoT Hub tutorial.
Java SE 8.
Prepare your development environment describes how to install Java for this tutorial on either Windows or
Linux.
Maven 3.
Prepare your development environment describes how to install Maven for this tutorial on either Windows or
Linux.
An active Azure account.
If you don't have an account, you can create a free account in just a couple of minutes.
You should have some basic knowledge of Azure Storage and Azure Service Bus.

Send interactive messages from a simulated device app

In this section, you modify the simulated device app you created in the Get started with IoT Hub tutorial to
occasionally send messages that require immediate processing.
1. Use a text editor to open the simulated-device\src\main\java\com\mycompany\app\App.java file. This file
contains the code for the simulated-device app you created in the Get started with IoT Hub tutorial.
2. Replace the MessageSender class with the following code:

private static class MessageSender implements Runnable {

public volatile boolean stopThread = false;

public void run() {

try {
double avgWindSpeed = 10; // m/s
Random rand = new Random();

while (!stopThread) {
double currentWindSpeed = avgWindSpeed + rand.nextDouble() * 4 - 2;
TelemetryDataPoint telemetryDataPoint = new TelemetryDataPoint();
telemetryDataPoint.deviceId = deviceId;
telemetryDataPoint.windSpeed = currentWindSpeed;

String msgStr = telemetryDataPoint.serialize();

if (new Random() > 0.7) {
Message msg = new Message("This is a critical message.");
msg.setProperty("level", "critical");
} else {
Message msg = new Message(msgStr);
}

System.out.println("Sending: " + msgStr);

Object lockobj = new Object();

EventCallback callback = new EventCallback();
client.sendEventAsync(msg, callback, lockobj);

synchronized (lockobj) {
lockobj.wait();
}
Thread.sleep(1000);
}
} catch (InterruptedException e) {
System.out.println("Finished.");
}
}
}

This method randomly adds the property "level": "critical" to messages sent by the simulated device,
which simulates a message that requires immediate action by the application back-end. The application
passes this information in the message properties, instead of in the message body, so that IoT Hub can route
the message to the proper message destination.

NOTE
You can use message properties to route messages for various scenarios including cold-path processing, in addition
to the hot path example shown here.

3. Save and close the simulated-device\src\main\java\com\mycompany\app\App.java file.

NOTE
For the sake of simplicity, this tutorial does not implement any retry policy. In production code, you should
implement a retry policy such as exponential backoff, as suggested in the MSDN article Transient Fault Handling.

4. To build the simulated-device app using Maven, execute the following command at the command prompt
in the simulated-device folder:

mvn clean package -DskipTests

Add a queue to your IoT hub and route messages to it

In this section, you create a Service Bus queue, connect it to your IoT hub, and configure your IoT hub to send
messages to the queue based on the presence of a property on the message. For more information about how to
process messages from Service Bus queues, see Get started with queues.
1. Create a Service Bus queue as described in Get started with queues. Make a note of the namespace and
queue name.
2. In the Azure portal, open your IoT hub and click Endpoints.

3. In the Endpoints blade, click Add at the top to add your queue to your IoT hub. Name the endpoint
CriticalQueue and use the drop-downs to select Service Bus queue, the Service Bus namespace in which
your queue resides, and the name of your queue. When you are done, click Save at the bottom.
4. Now click Routes in your IoT Hub. Click Add at the top of the blade to create a routing rule that routes
messages to the queue you just added. Select DeviceTelemetry as the source of data. Enter
level="critical" as the condition, and choose the queue you just added as a custom endpoint as the
routing rule endpoint. When you are done, click Save at the bottom.

Make sure the fallback route is set to ON. This setting is the default configuration of an IoT hub.
(Optional) Read from the queue endpoint
You can optionally read the messages from the queue endpoint by following the instructions in Get started with
queues. Name the app read-critical-queue.

Run the applications

Now you are ready to run the three applications.
1. To run the read-d2c-messages application, in a command prompt or shell navigate to the read-d2c folder
and execute the following command:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

2. To run the read-critical-queue application, in a command prompt or shell navigate to the read-critical-
queue folder and execute the following command:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

3. To run the simulated-device app, in a command prompt or shell navigate to the simulated-device folder
and execute the following command:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

Next steps
In this tutorial, you learned how to reliably dispatch device-to-cloud messages by using the message routing
functionality of IoT Hub.
The How to send cloud-to-device messages with IoT Hub shows you how to send messages to your devices from
your solution back end.
To see examples of complete end-to-end solutions that use IoT Hub, see Azure IoT Suite.
To learn more about developing solutions with IoT Hub, see the IoT Hub developer guide.
To learn more about message routing in IoT Hub, see Send and receive messages with IoT Hub.
Send cloud-to-device messages with IoT Hub (.NET)
1/17/2017 • 6 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that helps enable reliable and secure bi-directional communications
between millions of devices and a solution back end. The Get started with IoT Hub tutorial shows how to create an
IoT hub, provision a device identity in it, and code a simulated device app that sends device-to-cloud messages.
This tutorial builds on Get started with IoT Hub. It shows you how to:
From your solution back end, send cloud-to-device messages to a single device through IoT Hub.
Receive cloud-to-device messages on a device.
From your solution back end, request delivery acknowledgement (feedback) for messages sent to a device
from IoT Hub.
You can find more information on cloud-to-device messages in the IoT Hub developer guide.
At the end of this tutorial, you run two .NET console apps:
SimulatedDevice, a modified version of the app created in Get started with IoT Hub, which connects to your
IoT hub and receives cloud-to-device messages.
SendCloudToDevice, which sends a cloud-to-device message to the simulated device app through IoT Hub,
and then receives its delivery acknowledgement.

NOTE
IoT Hub has SDK support for many device platforms and languages (including C, Java, and Javascript) through Azure IoT
device SDKs. For step-by-step instructions on how to connect your device to this tutorial's code, and generally to Azure IoT
Hub, see the Azure IoT Developer Center.

To complete this tutorial, you need the following:

Microsoft Visual Studio 2015
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Receive messages in the simulated device app

In this section, you'll modify the simulated device app you created in Get started with IoT Hub to receive cloud-to-
device messages from the IoT hub.
1. In Visual Studio, in the SimulatedDevice project, add the following method to the Program class.
private static async void ReceiveC2dAsync()
{
Console.WriteLine("\nReceiving cloud to device messages from service");
while (true)
{
Message receivedMessage = await deviceClient.ReceiveAsync();
if (receivedMessage == null) continue;

Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine("Received message: {0}",
Encoding.ASCII.GetString(receivedMessage.GetBytes()));
Console.ResetColor();

await deviceClient.CompleteAsync(receivedMessage);
}
}

The ReceiveAsync method asynchronously returns the received message at the time that it is received by
the device. It returns null after a specifiable timeout period (in this case, the default of one minute is used).
When the app recieves a null, it should continue to wait for new messages. This requirement is the reason
for the if (receivedMessage == null) continue line.
The call to CompleteAsync() notifies IoT Hub that the message has been successfully processed. The
message can be safely removed from the device queue. If something happened that prevented the device
app from completing the processing of the message, IoT Hub delivers it again. It is then important that
message processing logic in the device app be idempotent, so that receiving the same message multiple
times produces the same result. An application can also temporarily abandon a message, which results in
IoT hub retaining the message in the queue for future consumption. Or, the application can reject a
message, which permanently removes the message from the queue. For more information about the
cloud-to-device message lifecycle, see the IoT Hub developer guide.

NOTE
When using HTTP instead of MQTT or AMQP as a transport, the ReceiveAsync method returns immediately. The
supported pattern for cloud-to-device messages with HTTP is intermittently connected devices that check for
messages infrequently (less than every 25 minutes). Issuing more HTTP receives results in IoT Hub throttling the
requests. For more information about the differences between MQTT, AMQP and HTTP support, and IoT Hub
throttling, see the IoT Hub developer guide.

2. Add the following method in the Main method, right before the Console.ReadLine() line:

ReceiveC2dAsync();

NOTE
For simplicity's sake, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Send a cloud-to-device message

In this section, you write a .NET console app that sends cloud-to-device messages to the simulated device app.
1. In the current Visual Studio solution, create a Visual C# Desktop App project by using the Console
Application project template. Name the project SendCloudToDevice.
2. In Solution Explorer, right-click the solution, and then click Manage NuGet Packages for Solution....
This action opens the Manage NuGet Packages window.
3. Search for Microsoft Azure Devices , click Install, and accept the terms of use.
This downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package.
4. Add the following using statement at the top of the Program.cs file:

using Microsoft.Azure.Devices;

5. Add the following fields to the Program class. Substitute the placeholder value with the IoT hub
connection string from Get started with IoT Hub:

static ServiceClient serviceClient;

static string connectionString = "{iot hub connection string}";

6. Add the following method to the Program class:

private async static Task SendCloudToDeviceMessageAsync()

{
var commandMessage = new Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync("myFirstDevice", commandMessage);
}

This method sends a new cloud-to-device message to the device with the ID, myFirstDevice . Change this
parameter accordingly, in case you modified it from the one used in Get started with IoT Hub.
7. Finally, add the following lines to the Main method:
Console.WriteLine("Send Cloud-to-Device message\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Console.WriteLine("Press any key to send a C2D message.");

Console.ReadLine();
SendCloudToDeviceMessageAsync().Wait();
Console.ReadLine();

8. From within Visual Studio, right-click your solution, and select Set StartUp projects.... Select Multiple
startup projects, then select the Start action for ProcessDeviceToCloudMessages, SimulatedDevice, and
SendCloudToDevice.
9. Press F5. All three applications should start. Select the SendCloudToDevice windows, and press Enter.
You should see the message being received by the simulated device app.

Receive delivery feedback

It is possible to request delivery (or expiration) acknowledgements from IoT Hub for each cloud-to-device
message. This option enables the solution back end to easily inform retry or compensation logic. For more
information about cloud-to-device feedback, see the IoT Hub developer guide.
In this section, you modify the SendCloudToDevice app to request feedback, and receive it from IoT Hub.
1. In Visual Studio, in the SendCloudToDevice project, add the following method to the Program class.

private async static void ReceiveFeedbackAsync()

{
var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Console.WriteLine("\nReceiving c2d feedback from service");

while (true)
{
var feedbackBatch = await feedbackReceiver.ReceiveAsync();
if (feedbackBatch == null) continue;

Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine("Received feedback: {0}", string.Join(", ", feedbackBatch.Records.Select(f
=> f.StatusCode)));
Console.ResetColor();

await feedbackReceiver.CompleteAsync(feedbackBatch);
}
}

Note that the receive pattern is the same one used to receive cloud-to-device messages from the device
app.
2. Add the following method in the Main method, right after the
serviceClient = ServiceClient.CreateFromConnectionString(connectionString) line:

ReceiveFeedbackAsync();

3. To request feedback for the delivery of your cloud-to-device message, you have to specify a property in the
SendCloudToDeviceMessageAsync method. Add the following line, right after the
var commandMessage = new Message(...); line:

commandMessage.Ack = DeliveryAcknowledgement.Full;

4. Run the apps by pressing F5. You should see all three applications start. Select the SendCloudToDevice
windows, and press Enter. You should see the message being received by the simulated device app, and
after a few seconds, the feedback message being received by your SendCloudToDevice application.

NOTE
For simplicity's sake, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Next steps
In this tutorial, you learned how to send and receive cloud-to-device messages.
To see examples of complete end-to-end solutions that use IoT Hub, see Azure IoT Suite.
To learn more about developing solutions with IoT Hub, see the IoT Hub developer guide.
Send cloud-to-device messages with IoT Hub (Java)
1/17/2017 • 4 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that helps enable reliable and secure bi-directional communications
between millions of devices and a solution back end. The Get started with IoT Hub tutorial shows how to create an
IoT hub, provision a device identity in it, and code a simulated device app that sends device-to-cloud messages.
This tutorial builds on Get started with IoT Hub. It shows you how to:
From your solution back end, send cloud-to-device messages to a single device through IoT Hub.
Receive cloud-to-device messages on a device.
From your solution back end, request delivery acknowledgement (feedback) for messages sent to a device from
IoT Hub.
You can find more information on cloud-to-device messages in the IoT Hub developer guide.
At the end of this tutorial, you run two Java console apps:
simulated-device, a modified version of the app created in Get started with IoT Hub, which connects to your
IoT hub and receives cloud-to-device messages.
send-c2d-messages, which sends a cloud-to-device message to the simulated device app through IoT Hub,
and then receives its delivery acknowledgement.

NOTE
IoT Hub has SDK support for many device platforms and languages (including C, Java, and Javascript) through Azure IoT
device SDKs. For step-by-step instructions on how to connect your device to this tutorial's code, and generally to Azure IoT
Hub, see the Azure IoT Developer Center.

To complete this tutorial, you need the following:

Java SE 8.
Prepare your development environment describes how to install Java for this tutorial on either Windows or
Linux.
Maven 3.
Prepare your development environment describes how to install Maven for this tutorial on either Windows or
Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Receive messages in the simulated device app

In this section, you modify the simulated device app you created in Get started with IoT Hub to receive cloud-to-
device messages from the IoT hub.
1. Using a text editor, open the simulated-device\src\main\java\com\mycompany\app\App.java file.
2. Add the following MessageCallback class as a nested class inside the App class. The execute method is
invoked when the device receives a message from IoT Hub. In this example, the device always notifies the
IoT hub that it has completed the message:
private static class MessageCallback implements
com.microsoft.azure.iothub.MessageCallback {
public IotHubMessageResult execute(Message msg, Object context) {
System.out.println("Received message from hub: "
+ new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));

return IotHubMessageResult.COMPLETE;
}
}

3. Modify the main method to create a MessageCallback instance and call the setMessageCallback method
before it opens the client as follows:

client = new DeviceClient(connString, protocol);

MessageCallback callback = new MessageCallback();

client.setMessageCallback(callback, null);
client.open();

NOTE
If you use HTTP instead of MQTT or AMQP as the transport, the DeviceClient instance checks for messages from IoT
Hub infrequently (less than every 25 minutes). For more information about the differences between MQTT, AMQP
and HTTP support, and IoT Hub throttling, see the IoT Hub developer guide.

Send a cloud-to-device message

In this section, you create a Java console app that sends cloud-to-device messages to the simulated device app. You
need the device ID of the device you added in the Get started with IoT Hub tutorial. You also need the IoT Hub
connection string for your hub that you can find in the Azure portal.
1. Create a Maven project called send-c2d-messages using the following command at your command
prompt. Note this is a single, long command:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=send-c2d-messages -

DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

2. At your command prompt, navigate to the new send-c2d-messages folder.

3. Using a text editor, open the pom.xml file in the send-c2d-messages folder and add the following
dependency to the dependencies node. Adding the dependency enables you to use the iothub-java-
service-client package in your application to communicate with your IoT hub service:

<dependency>
<groupId>com.microsoft.azure.iothub-java-client</groupId>
<artifactId>iothub-java-service-client</artifactId>
<version>1.0.10</version>
</dependency>

4. Save and close the pom.xml file.

5. Using a text editor, open the send-c2d-messages\src\main\java\com\mycompany\app\App.java file.
6. Add the following import statements to the file:
import com.microsoft.azure.iot.service.sdk.*;
import java.io.IOException;
import java.net.URISyntaxException;

7. Add the following class-level variables to the App class, replacing {yourhubconnectionstring} and
{yourdeviceid} with the values your noted earlier:

private static final String connectionString = "{yourhubconnectionstring}";

private static final String deviceId = "{yourdeviceid}";
private static final IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQP;

8. Replace the main method with the following code that connects to your IoT hub, sends a message to your
device, and then waits for an acknowledgment that the device received and processed the message:

public static void main(String[] args) throws IOException,

URISyntaxException, Exception {
ServiceClient serviceClient = ServiceClient.createFromConnectionString(
connectionString, protocol);

if (serviceClient != null) {
serviceClient.open();
FeedbackReceiver feedbackReceiver = serviceClient
.getFeedbackReceiver(deviceId);
if (feedbackReceiver != null) feedbackReceiver.open();

Message messageToSend = new Message("Cloud to device message.");

messageToSend.setDeliveryAcknowledgement(DeliveryAcknowledgement.Full);

serviceClient.send(deviceId, messageToSend);
System.out.println("Message sent to device");

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);

if (feedbackBatch != null) {
System.out.println("Message feedback received, feedback time: "
+ feedbackBatch.getEnqueuedTimeUtc().toString());
}

if (feedbackReceiver != null) feedbackReceiver.close();

serviceClient.close();
}
}

NOTE
For simplicity's sake, this tutorial does not implement any retry policy. In production code, you should implement
retry policies (such as exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Run the applications

You are now ready to run the applications.
1. At a command prompt in the simulated-device folder, run the following command to begin sending
telemetry to your IoT hub and to listen for cloud-to-device messages sent from your hub:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

2. At a command prompt in the send-c2d-messages folder, run the following command to send a cloud-to-
device message and wait for a feedback acknowledgment:

mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

Next steps
In this tutorial, you learned how to send and receive cloud-to-device messages.
To see examples of complete end-to-end solutions that use IoT Hub, see Azure IoT Suite.
To learn more about developing solutions with IoT Hub, see the IoT Hub developer guide.
Send cloud-to-device messages with IoT Hub (Node)
1/17/2017 • 4 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that helps enable reliable and secure bi-directional communications
between millions of devices and a solution back end. The Get started with IoT Hub tutorial shows how to create an
IoT hub, provision a device identity in it, and code a simulated device app that sends device-to-cloud messages.
This tutorial builds on Get started with IoT Hub. It shows you how to:
From your solution back end, send cloud-to-device messages to a single device through IoT Hub.
Receive cloud-to-device messages on a device.
From your solution back end, request delivery acknowledgement (feedback) for messages sent to a device from
IoT Hub.
You can find more information on cloud-to-device messages in the IoT Hub developer guide.
At the end of this tutorial, you run two Node.js console apps:
SimulatedDevice, a modified version of the app created in Get started with IoT Hub, which connects to your
IoT hub and receives cloud-to-device messages.
SendCloudToDeviceMessage, which sends a cloud-to-device message to the simulated device app through
IoT Hub, and then receives its delivery acknowledgement.

NOTE
IoT Hub has SDK support for many device platforms and languages (including C, Java, and Javascript) through Azure IoT
device SDKs. For step-by-step instructions on how to connect your device to this tutorial's code, and generally to Azure IoT
Hub, see the Azure IoT Developer Center.

To complete this tutorial, you need the following:

Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Receive messages in the simulated device app

In this section, you modify the simulated device app you created in Get started with IoT Hub to receive cloud-to-
device messages from the IoT hub.
1. Using a text editor, open the SimulatedDevice.js file.
2. Modify the connectCallback function to handle messages sent from IoT Hub. In this example, the device
always invokes the complete function to notify IoT Hub that it has processed the message. Your new
version of the connectCallback function looks like the following snippet:
var connectCallback = function (err) {
if (err) {
console.log('Could not connect: ' + err);
} else {
console.log('Client connected');
client.on('message', function (msg) {
console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
client.complete(msg, printResultFor('completed'));
});
// Create a message and send it to the IoT Hub every second
setInterval(function(){
var windSpeed = 10 + (Math.random() * 4);
var data = JSON.stringify({ deviceId: 'myFirstNodeDevice', windSpeed: windSpeed });
var message = new Message(data);
console.log("Sending message: " + message.getData());
client.sendEvent(message, printResultFor('send'));
}, 1000);
}
};

NOTE
If you use HTTP instead of MQTT or AMQP as the transport, the DeviceClient instance checks for messages from
IoT Hub infrequently (less than every 25 minutes). For more information about the differences between MQTT,
AMQP and HTTP support, and IoT Hub throttling, see the IoT Hub developer guide.

Send a cloud-to-device message

In this section, you create a Node.js console app that sends cloud-to-device messages to the simulated device app.
You need the device ID of the device you added in the Get started with IoT Hub tutorial. You also need the IoT Hub
connection string for your hub that you can find in the Azure portal.
1. Create an empty folder called sendcloudtodevicemessage. In the sendcloudtodevicemessage folder,
create a package.json file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the sendcloudtodevicemessage folder, run the following command to
install the azure-iothub package:

npm install azure-iothub --save

3. Using a text editor, create a SendCloudToDeviceMessage.js file in the sendcloudtodevicemessage folder.

4. Add the following require statements at the start of the SendCloudToDeviceMessage.js file:

'use strict';

var Client = require('azure-iothub').Client;

var Message = require('azure-iot-common').Message;

5. Add the following code to SendCloudToDeviceMessage.js file. Replace the iot hub connection string
placeholder value with the IoT Hub connection string for the hub you created in the Get started with IoT Hub
tutorial. Replace the target device placeholder with the device ID of the device you added in the Get started
with IoT Hub tutorial:
var connectionString = '{iot hub connection string}';
var targetDevice = '{device id}';

var serviceClient = Client.fromConnectionString(connectionString);

6. Add the following function to print operation results to the console:

function printResultFor(op) {
return function printResult(err, res) {
if (err) console.log(op + ' error: ' + err.toString());
if (res) console.log(op + ' status: ' + res.constructor.name);
};
}

7. Add the following function to print delivery feedback messages to the console:

function receiveFeedback(err, receiver){

receiver.on('message', function (msg) {
console.log('Feedback message:')
console.log(msg.getData().toString('utf-8'));
});
}

8. Add the following code to send a message to your device and handle the feedback message when the
device acknowledges the cloud-to-device message:

serviceClient.open(function (err) {
if (err) {
console.error('Could not connect: ' + err.message);
} else {
console.log('Service client connected');
serviceClient.getFeedbackReceiver(receiveFeedback);
var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";
console.log('Sending message: ' + message.getData());
serviceClient.send(targetDevice, message, printResultFor('send'));
}
});

9. Save and close SendCloudToDeviceMessage.js file.

Run the applications

You are now ready to run the applications.
1. At the command prompt in the simulateddevice folder, run the following command to send telemetry to
IoT Hub and to listen for cloud-to-device messages:

node SimulatedDevice.js
2. At a command prompt in the sendcloudtodevicemessage folder, run the following command to send a
cloud-to-device message and wait for the acknowledgment feedback:

node SendCloudToDeviceMessage.js

NOTE
For simplicity's sake, this tutorial does not implement any retry policy. In production code, you should implement
retry policies (such as exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Next steps
In this tutorial, you learned how to send and receive cloud-to-device messages.
To see examples of complete end-to-end solutions that use IoT Hub, see Azure IoT Suite.
To learn more about developing solutions with IoT Hub, see the IoT Hub developer guide.
Upload files from devices to the cloud with IoT Hub
1/17/2017 • 5 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications between
millions of devices and a solution back end. Previous tutorials (Get started with IoT Hub and Send Cloud-to-Device
messages with IoT Hub) illustrate the basic device-to-cloud and cloud-to-device messaging functionality of IoT
Hub, and the Process Device-to-Cloud messages tutorial describes a way to reliably store device-to-cloud
messages in Azure blob storage. However, in some scenarios you cannot easily map the data your devices send
into the relatively small device-to-cloud messages that IoT Hub accepts. Examples include large files that contain
images, videos, vibration data sampled at high frequency, or that contain some form of preprocessed data. These
files are typically batch processed in the cloud using tools such as Azure Data Factory or the Hadoop stack. When
file uploads from a device are preferred to sending events, you can still use IoT Hub security and reliability
functionality.
This tutorial builds on the code in the Send Cloud-to-Device messages with IoT Hub tutorial to show you how to
use the file upload capabilities of IoT Hub. It shows you how to:
Securely provide a device with an Azure blob URI for uploading a file.
Use the IoT Hub file upload notifications to trigger processing the file in your app back end.
At the end of this tutorial you run two .NET console apps:
SimulatedDevice, a modified version of the app created in the Send Cloud-to-Device messages with IoT Hub
tutorial. This app uploads a file to storage using a SAS URI provided by your IoT hub.
ReadFileUploadNotification, which receives file upload notifications from your IoT hub.

NOTE
IoT Hub supports many device platforms and languages (including C, Java, and Javascript) through Azure IoT device SDKs.
Refer to the Azure IoT Developer Center for step-by-step instructions on how to connect your device to Azure IoT Hub.

To complete this tutorial, you need the following:

Microsoft Visual Studio 2015,
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Associate an Azure Storage account to IoT Hub

Because the simulated device app uploads a file to a blob, you must have an Azure Storage account associated to
IoT Hub. When you associate an Azure Storage account with an IoT hub, the IoT hub can generate a SAS URI that a
device can use to securely upload a file to a blob container. The IoT Hub service and the device SDKs coordinate the
process that generates the SAS URI and makes it available to a device to use to upload a file.
Follow the instructions in Configure file uploads using the Azure portal to associate an Azure Storage account to
your IoT hub.

Upload a file from a simulated device app

In this section, you modify the simulated device app you created in Send Cloud-to-Device messages with IoT Hub
to receive cloud-to-device messages from the IoT hub.
1. In Visual Studio, right-click the SimulatedDevice project, click Add, and then click Existing Item. Navigate to
an image file and include it in your project. This tutorial assumes the image is named image.jpg .
2. Right-click on the image, and then click Properties. Make sure that Copy to Output Directory is set to
Copy always.

3. In the Program.cs file, add the following statements at the top of the file:

using System.IO;

4. Add the following method to the Program class:

private static async void SendToBlobAsync()

{
string fileName = "image.jpg";
Console.WriteLine("Uploading file: {0}", fileName);
var watch = System.Diagnostics.Stopwatch.StartNew();

using (var sourceData = new FileStream(@"image.jpg", FileMode.Open))

{
await deviceClient.UploadToBlobAsync(fileName, sourceData);
}

watch.Stop();
Console.WriteLine("Time to upload file: {0}ms\n", watch.ElapsedMilliseconds);
}

The UploadToBlobAsync method takes in the file name and stream source of the file to be uploaded and
handles the upload to storage. The console app displays the time it takes to upload the file.
5. Add the following method in the Main method, right before the Console.ReadLine() line:

SendToBlobAsync();

NOTE
For simplicity's sake, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Receive a file upload notification

In this section, you write a .NET console app that receives file upload notification messages from IoT Hub.
1. In the current Visual Studio solution, create a Visual C# Windows project by using the Console Application
project template. Name the project ReadFileUploadNotification.
2. In Solution Explorer, right-click the ReadFileUploadNotification project, and then click Manage NuGet
Packages.
This action displays the Manage NuGet Packages window.
3. Search for Microsoft.Azure.Devices , click Install, and accept the terms of use.
This action downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package in the
ReadFileUploadNotification project.
4. In the Program.cs file, add the following statements at the top of the file:

using Microsoft.Azure.Devices;

5. Add the following fields to the Program class. Substitute the placeholder value with the IoT hub connection
string from Get started with IoT Hub:

static ServiceClient serviceClient;

static string connectionString = "{iot hub connection string}";

6. Add the following method to the Program class:

private async static Task ReceiveFileUploadNotificationAsync()
{
var notificationReceiver = serviceClient.GetFileNotificationReceiver();

Console.WriteLine("\nReceiving file upload notification from service");

while (true)
{
var fileUploadNotification = await notificationReceiver.ReceiveAsync();
if (fileUploadNotification == null) continue;

Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine("Received file upload noticiation: {0}", string.Join(", ",
fileUploadNotification.BlobName));
Console.ResetColor();

await notificationReceiver.CompleteAsync(fileUploadNotification);
}
}

Note that the receive pattern is the same one used to receive cloud-to-device messages from the device app.
7. Finally, add the following lines to the Main method:

Console.WriteLine("Receive file upload notifications\n");

serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
ReceiveFileUploadNotificationAsync().Wait();
Console.ReadLine();

Run the applications

Now you are ready to run the applications.
1. In Visual Studio, right-click your solution, and select Set StartUp projects. Select Multiple startup projects,
then select the Start action for ReadFileUploadNotification and SimulatedDevice.
2. Press F5. Both applications should start. You should see the upload completed in one console app and the
upload notification message being received by the other console app. You can use the Azure portal or Visual
Studio Server Explorer to check for the presence of the uploaded file in your Azure Storage account.
Next steps
In this tutorial, you learned how to leverage the file upload capabilities of IoT Hub to simplify file uploads from
devices. You can continue to explore IoT hub features and scenarios with the following articles:
Create an IoT hub programmatically
Introduction to C SDK
Azure IoT SDKs
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Get started with device twins (Node)
1/17/2017 • 9 min to read • Edit on GitHub

Introduction
Device twins are JSON documents that store device state information (metadata, configurations, and conditions).
IoT Hub persists a device twin for each device that you connect to IoT Hub.
Use device twins to:
Store device metadata from your solution back end.
Report current state information such as available capabilities and conditions (for example, the connectivity
method used) from your device app.
Synchronize the state of long-running workflows (such as firmware and configuration updates) between a
device app and a back-end app.
Query your device metadata, configuration, or state.

NOTE
Device twins are designed for synchronization and for querying device configurations and conditions. More informations on
when to use device twins can be found in Understand device twins.

Device twins are stored in an IoT hub and contain:

tags, device metadata accessible only by the solution back end;
desired properties, JSON objects modifiable by the solution back end and observable by the device app; and
reported properties, JSON objects modifiable by the device app and readable by the solution back end. Tags
and properties cannot contain arrays, but objects can be nested.

Additionally, the solution back end can query device twins based on all the above data. Refer to Understand device
twins for more information about device twins and to the IoT Hub query language reference for querying.
NOTE
At this time, device twins are accessible only from devices that connect to IoT Hub using the MQTT protocol. Please refer to
the MQTT support article for instructions on how to convert existing device app to use MQTT.

This tutorial shows you how to:

Create a back-end app that adds tags to a device twin, and a simulated device app that reports its connectivity
channel as a reported property on the device twin.
Query devices from your back-end app using filters on the tags and properties previously created.
At the end of this tutorial, you will have two Node.js console apps:
AddTagsAndQuery.js, a Node.js back-end app, which adds tags and queries device twins.
TwinSimulatedDevice.js, a Node.js app which simulates a device that connects to your IoT hub with the
device identity created earlier, and reports its connectivity condition.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both device and back-
end apps.

To complete this tutorial you need the following:

Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device
app to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create the service app

In this section, you create a Node.js console app that adds location metadata to the device twin associated with
myDeviceId. It then queries the device twins stored in the IoT hub selecting the devices located in the US, and
then the ones that reporting a cellular connection.
1. Create a new empty folder called addtagsandqueryapp. In the addtagsandqueryapp folder, create a
new package.json file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the addtagsandqueryapp folder, run the following command to install the
azure-iothub package:

npm install azure-iothub --save

3. Using a text editor, create a new AddTagsAndQuery.js file in the addtagsandqueryapp folder.
4. Add the following code to the AddTagsAndQuery.js file, and substitute the {iot hub connection string}
placeholder with the IoT Hub connection string you copied when you created your hub:
'use strict';
var iothub = require('azure-iothub');
var connectionString = '{iot hub connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

registry.getTwin('myDeviceId', function(err, twin){

if (err) {
console.error(err.constructor.name + ': ' + err.message);
} else {
var patch = {
tags: {
location: {
region: 'US',
plant: 'Redmond43'
}
}
};

twin.update(patch, function(err) {
if (err) {
console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
} else {
console.log(twin.deviceId + ' twin updated successfully');
queryTwins();
}
});
}
});

The Registry object exposes all the methods required to interact with device twins from the service. The
previous code first initializes the Registry object, then retrieves the device twin for myDeviceId, and
finally updates its tags with the desired location information.
After the updating the tags it calls the queryTwins function.
5. Add the following code at the end of AddTagsAndQuery.js to implement the queryTwins function:

var queryTwins = function() {

var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'",
100);
query.nextAsTwin(function(err, results) {
if (err) {
console.error('Failed to fetch the results: ' + err.message);
} else {
console.log("Devices in Redmond43: " + results.map(function(twin) {return
twin.deviceId}).join(','));
}
});

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND

properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
if (err) {
console.error('Failed to fetch the results: ' + err.message);
} else {
console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin)
{return twin.deviceId}).join(','));
}
});
};

The previous code executes two queries: the first selects only the device twins of devices located in the
Redmond43 plant, and the second refines the query to select only the devices that are also connected
through cellular network.
Note that the previous code, when it creates the query object, specifies a maximum number of returned
documents. The query object contains a hasMoreResults boolean property that you can use to invoke the
nextAsTwin methods multiple times to retrieve all results. A method called next is available for results
that are not device twins for example, results of aggregation queries.
6. Run the application with:

node AddTagsAndQuery.js

You should see one device in the results for the query asking for all devices located in Redmond43 and
none for the query that restricts the results to devices that use a cellular network.

In the next section you create a device app that reports the connectivity information and changes the result of the
query in the previous section.

Create the device app

In this section, you create a Node.js console app that connects to your hub as myDeviceId, and then updates its
device twin's reported properties to contain the information that it is connected using a cellular network.

NOTE
At this time, device twins are accessible only from devices that connect to IoT Hub using the MQTT protocol. Please refer to
the MQTT support article for instructions on how to convert existing device app to use MQTT.

1. Create a new empty folder called reportconnectivity. In the reportconnectivity folder, create a new
package.json file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the reportconnectivity folder, run the following command to install the
azure-iot-device, and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new ReportConnectivity.js file in the reportconnectivity folder.
4. Add the following code to the ReportConnectivity.js file, and substitute the {device connection string}
placeholder with the device connection string you copied when you created the myDeviceId device
identity:
'use strict';
var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').Mqtt;

var connectionString = '{device connection string}';

var client = Client.fromConnectionString(connectionString, Protocol);

client.open(function(err) {
if (err) {
console.error('could not open IotHub client');
} else {
console.log('client opened');

client.getTwin(function(err, twin) {
if (err) {
console.error('could not get twin');
} else {
var patch = {
connectivity: {
type: 'cellular'
}
};

twin.properties.reported.update(patch, function(err) {
if (err) {
console.error('could not update twin');
} else {
console.log('twin state reported');
process.exit();
}
});
}
});
}
});

The Client object exposes all the methods you require to interact with device twins from the device. The
previous code, after it initializes the Client object, retrieves the device twin for myDeviceId and updates its
reported property with the connectivity information.
5. Run the device app

node ReportConnectivity.js

You should see the message twin state reported .

6. Now that the device reported its connectivity information, it should appear in both queries. Go back in the
addtagsandqueryapp folder and run the queries again:

node AddTagsAndQuery.js

This time myDeviceId should appear in both query results.

Next steps
In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT
hub's identity registry. You added device metadata as tags from a back-end app, and wrote a simulated device app
to report device connectivity information in the device twin. You also learned how to query this information using
the SQL-like IoT Hub query language.
Use the following resources to learn how to:
send telemetry from devices with the Get started with IoT Hub tutorial,
configure devices using device twin's desired properties with the Use desired properties to configure devices
tutorial,
control devices interactively (such as turning on a fan from a user-controlled app), with the Use direct methods
tutorial.
Get started with device twins (.NET/Node)
1/17/2017 • 9 min to read • Edit on GitHub

Introduction
Device twins are JSON documents that store device state information (metadata, configurations, and conditions).
IoT Hub persists a device twin for each device that you connect to IoT Hub.
Use device twins to:
Store device metadata from your solution back end.
Report current state information such as available capabilities and conditions (for example, the connectivity
method used) from your device app.
Synchronize the state of long-running workflows (such as firmware and configuration updates) between a
device app and a back-end app.
Query your device metadata, configuration, or state.

NOTE
Device twins are designed for synchronization and for querying device configurations and conditions. More informations on
when to use device twins can be found in Understand device twins.

Device twins are stored in an IoT hub and contain:

tags, device metadata accessible only by the solution back end;
desired properties, JSON objects modifiable by the solution back end and observable by the device app; and
reported properties, JSON objects modifiable by the device app and readable by the solution back end. Tags and
properties cannot contain arrays, but objects can be nested.

Additionally, the solution back end can query device twins based on all the above data. Refer to Understand device
twins for more information about device twins and to the IoT Hub query language reference for querying.
NOTE
At this time, device twins are accessible only from devices that connect to IoT Hub using the MQTT protocol. Please refer to
the MQTT support article for instructions on how to convert existing device app to use MQTT.

This tutorial shows you how to:

Create a back-end app that adds tags to a device twin, and a simulated device app that reports its connectivity
channel as a reported property on the device twin.
Query devices from your back-end app using filters on the tags and properties previously created.
At the end of this tutorial, you will have a .NET and a Node.js console app:
AddTagsAndQuery.sln, a .NET back-end app, which adds tags and queries device twins.
TwinSimulatedDevice.js, a Node.js app which simulates a device that connects to your IoT hub with the device
identity created earlier, and reports its connectivity condition.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both device and back-
end apps.

To complete this tutorial you need the following:

Microsoft Visual Studio 2015.
Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free F1
tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure
to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the IoT
Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT Hub
developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device app
to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create the service app

In this section, you create a Node.js console app that adds location metadata to the device twin associated with
myDeviceId. It then queries the device twins stored in the IoT hub selecting the devices located in the US, and then
the ones that reporting a cellular connection.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the
Console Application project template. Name the project AddTagsAndQuery.

2. In Solution Explorer, right-click the AddTagsAndQuery project, and then click Manage NuGet Packages.
3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select
Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure
downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.
4. Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices;

5. Add the following fields to the Program class. Replace the placeholder value with the IoT Hub connection
string for the hub that you created in the previous section.

static RegistryManager registryManager;

static string connectionString = "{iot hub connection string}";

6. Add the following method to the Program class:

public static async Task AddTagsAndQuery()

{
var twin = await registryManager.GetTwinAsync("myDeviceId");
var patch =
@"{
tags: {
location: {
region: 'US',
plant: 'Redmond43'
}
}
}";
await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

var query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant =

'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", string.Join(", ", twinsInRedmond43.Select(t =>
t.DeviceId)));

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'

AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", string.Join(", ",
twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}

The RegistryManager class exposes all the methods required to interact with device twins from the service.
The previous code first initializes the registryManager object, then retrieves the device twin for
myDeviceId, and finally updates its tags with the desired location information.
After the updating, it executes two queries: the first selects only the device twins of devices located in the
Redmond43 plant, and the second refines the query to select only the devices that are also connected
through cellular network.
Note that the previous code, when it creates the query object, specifies a maximum number of returned
documents. The query object contains a HasMoreResults boolean property that you can use to invoke the
GetNextAsTwinAsync methods multiple times to retrieve all results. A method called GetNextAsJson is
available for results that are not device twins for example, results of aggregation queries.
7. Finally, add the following lines to the Main method:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

8. Run this application, and you should see one device in the results for the query asking for all devices located
in Redmond43 and none for the query that restricts the results to devices that use a cellular network.

In the next section you create a device app that reports the connectivity information and changes the result of the
query in the previous section.

Create the device app

In this section, you create a Node.js console app that connects to your hub as myDeviceId, and then updates its
reported properties to contain the information that it is connected using a cellular network.
1. Create a new empty folder called reportconnectivity. In the reportconnectivity folder, create a new
package.json file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the reportconnectivity folder, run the following command to install the
azure-iot-device, and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new ReportConnectivity.js file in the reportconnectivity folder.
4. Add the following code to the ReportConnectivity.js file, and substitute the {device connection string}
placeholder with the device connection string you copied when you created the myDeviceId device identity:
'use strict';
var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').Mqtt;

var connectionString = '{device connection string}';

var client = Client.fromConnectionString(connectionString, Protocol);

client.open(function(err) {
if (err) {
console.error('could not open IotHub client');
} else {
console.log('client opened');

client.getTwin(function(err, twin) {
if (err) {
console.error('could not get twin');
} else {
var patch = {
connectivity: {
type: 'cellular'
}
};

twin.properties.reported.update(patch, function(err) {
if (err) {
console.error('could not update twin');
} else {
console.log('twin state reported');
process.exit();
}
});
}
});
}
});

The Client object exposes all the methods you require to interact with device twins from the device. The
previous code, after it initializes the Client object, retrieves the device twin for myDeviceId and updates its
reported property with the connectivity information.
5. Run the device app

node ReportConnectivity.js

You should see the message twin state reported .

6. Now that the device reported its connectivity information, it should appear in both queries. Run the .NET
AddTagsAndQuery app to run the queries again. This time myDeviceId should appear in both query
results.

Next steps
In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT hub's
identity registry. You added device metadata as tags from a back-end app, and wrote a simulated device app to
report device connectivity information in the device twin. You also learned how to query this information using the
SQL-like IoT Hub query language.
Use the following resources to learn how to:
send telemetry from devices with the Get started with IoT Hub tutorial,
configure devices using device twin's desired properties with the Use desired properties to configure devices
tutorial,
control devices interactively (such as turning on a fan from a user-controlled app) with the Use direct methods
tutorial.
Use direct methods (Node)
1/17/2017 • 7 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications between
millions of devices and a solution back end. Previous tutorials (Get started with IoT Hub and Send Cloud-to-
Device messages with IoT Hub) illustrate the basic device-to-cloud and cloud-to-device messaging functionality
of IoT Hub. IoT Hub also gives you the ability to invoke non-durable methods on devices from the cloud. Methods
represent a request-reply interaction with a device similar to an HTTP call in that they succeed or fail immediately
(after a user-specified timeout) to let the user know the status of the call. Invoke a direct method on a device
describes methods in more detail and offers guidance about when to use methods versus cloud-to-device
messages.
This tutorial shows you how to:
Use the Azure portal to create an IoT hub and create a device identity in your IoT hub.
Create a simulated device app that has a direct method which can be called by the cloud.
Create a console app that calls a direct method in the simulated device app through your IoT hub.

NOTE
At this time, direct methods are accessible only from devices that connect to IoT Hub using the MQTT protocol. Please refer
to the MQTT support article for instructions on how to convert existing device app to use MQTT.

At the end of this tutorial, you have two Node.js console apps:
CallMethodOnDevice.js, which calls a method in the simulated device app and displays the response.
SimulatedDevice.js, which connects to your IoT hub with the device identity created earlier, and responds to
the method called by the cloud.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both applications to
run on devices and your solution back end.

To complete this tutorial, you need the following:

Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete
this task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device
app to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create a simulated device app

In this section, you create a Node.js console app that responds to a method called by the cloud.
1. Create a new empty folder called simulateddevice. In the simulateddevice folder, create a package.json
file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the simulateddevice folder, run the following command to install the
azure-iot-device Device SDK package and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new SimulatedDevice.js file in the simulateddevice folder.
4. Add the following require statements at the start of the SimulatedDevice.js file:

'use strict';

var Mqtt = require('azure-iot-device-mqtt').Mqtt;

var DeviceClient = require('azure-iot-device').Client;

5. Add a connectionString variable and use it to create a DeviceClient instance. Replace {device
connection string} with the device connection string you generated in the Create a device identity
section:

var connectionString = '{device connection string}';

var client = DeviceClient.fromConnectionString(connectionString, Mqtt);

6. Add the following function to implement the method on the device:

function onWriteLine(request, response) {
console.log(request.payload);

response.send(200, 'Input was written to log.', function(err) {

if(err) {
console.error('An error ocurred when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.' );
}
});
}

7. Open the connection to your IoT hub and start initialize the method listener:

client.open(function(err) {
if (err) {
console.error('could not open IotHub client');
} else {
console.log('client opened');
client.onDeviceMethod('writeLine', onWriteLine);
}
});

8. Save and close the SimulatedDevice.js file.

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as connection retry), as suggested in the MSDN article Transient Fault Handling.

Call a method on a device

In this section, you create a Node.js console app that calls a method in the simulated device app and then displays
the response.
1. Create a new empty folder called callmethodondevice. In the callmethodondevice folder, create a
package.json file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the callmethodondevice folder, run the following command to install the
azure-iothub package:

npm install azure-iothub --save

3. Using a text editor, create a CallMethodOnDevice.js file in the callmethodondevice folder.

4. Add the following require statements at the start of the CallMethodOnDevice.js file:

'use strict';

var Client = require('azure-iothub').Client;

5. Add the following variable declaration and replace the placeholder value with the IoT Hub connection
string for your hub:
var connectionString = '{iothub connection string}';
var methodName = 'writeLine';
var deviceId = 'myDeviceId';

6. Create the client to open the connection to your IoT hub.

var client = Client.fromConnectionString(connectionString);

7. Add the following function to invoke the device method and print the device response to the console:

var methodParams = {
methodName: methodName,
payload: 'a line to be written',
timeoutInSeconds: 30
};

client.invokeDeviceMethod(deviceId, methodParams, function (err, result) {

if (err) {
console.error('Failed to invoke method \'' + methodName + '\': ' + err.message);
} else {
console.log(methodName + ' on ' + deviceId + ':');
console.log(JSON.stringify(result, null, 2));
}
});

8. Save and close the CallMethodOnDevice.js file.

Run the apps

You are now ready to run the apps.
1. At a command prompt in the simulateddevice folder, run the following command to start listening for
method calls from your IoT Hub:

node SimulatedDevice.js

2. At a command prompt in the callmethodondevice folder, run the following command to begin
monitoring your IoT hub:

node CallMethodOnDevice.js
3. You will see the device react to the method by printing out the message and the application which called
the method display the response from the device:

Next steps
In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT
hub's identity registry. You used this device identity to enable the simulated device app to react to methods
invoked by the cloud. You also created an app that invokes methods on the device and displays the response
from the device.
To continue getting started with IoT Hub and to explore other IoT scenarios, see:
Get started with IoT Hub
Schedule jobs on multiple devices
To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and
broadcast jobs tutorial.
Use direct methods (.NET/Node)
1/17/2017 • 7 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications between
millions of devices and a solution back end. Previous tutorials (Get started with IoT Hub and Send Cloud-to-Device
messages with IoT Hub) illustrate the basic device-to-cloud and cloud-to-device messaging functionality of IoT Hub.
IoT Hub also gives you the ability to invoke non-durable methods on devices from the cloud. Methods represent a
request-reply interaction with a device similar to an HTTP call in that they succeed or fail immediately (after a user-
specified timeout) to let the user know the status of the call. Invoke a direct method on a device describes methods
in more detail and offers guidance about when to use methods versus cloud-to-device messages.
This tutorial shows you how to:
Use the Azure portal to create an IoT hub and create a device identity in your IoT hub.
Create a simulated device app that has a direct method which can be called by the cloud.
Create a console app that calls a direct method in the simulated device app through your IoT hub.

NOTE
At this time, direct methods are accessible only from devices that connect to IoT Hub using the MQTT protocol. Please refer
to the MQTT support article for instructions on how to convert existing device app to use MQTT.

At the end of this tutorial, you will have a .NET and a Node.js console app:
CallMethodOnDevice.sln, a .NET back-end app, which calls a method in the simulated device app and displays
the response.
SimulatedDevice.js, a Node.js app which simulates a device that connects to your IoT hub with the device
identity created earlier, and responds to the method called by the cloud.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both applications to run
on devices and your solution back end.

To complete this tutorial you need the following:

Microsoft Visual Studio 2015.
Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free F1
tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure
to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the IoT
Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT Hub
developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device app
to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create a simulated device app

In this section, you create a Node.js console app that responds to a method called by the solution back end.
1. Create a new empty folder called simulateddevice. In the simulateddevice folder, create a package.json
file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the simulateddevice folder, run the following command to install the azure-
iot-device and azure-iot-device-mqtt packages:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new SimulatedDevice.js file in the simulateddevice folder.
4. Add the following require statements at the start of the SimulatedDevice.js file:

'use strict';

var Mqtt = require('azure-iot-device-mqtt').Mqtt;

var DeviceClient = require('azure-iot-device').Client;

5. Add a connectionString variable and use it to create a DeviceClient instance. Replace {device
connection string} with the device connection string you generated in the Create a device identity section:

var connectionString = '{device connection string}';

var client = DeviceClient.fromConnectionString(connectionString, Mqtt);

6. Add the following function to implement the direct method on the device:
function onWriteLine(request, response) {
console.log(request.payload);

response.send(200, 'Input was written to log.', function(err) {

if(err) {
console.error('An error ocurred when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.' );
}
});
}

7. Open the connection to your IoT hub and initialize the method listener:

client.open(function(err) {
if (err) {
console.error('could not open IotHub client');
} else {
console.log('client opened');
client.onDeviceMethod('writeLine', onWriteLine);
}
});

8. Save and close the SimulatedDevice.js file.

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as connection retry), as suggested in the MSDN article Transient Fault Handling.

Call a direct method on a device

In this section, you create a .NET console app that calls a method in the simulated device app and then displays the
response.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the
Console Application project template. Make sure the .NET Framework version is 4.5.1 or later. Name the
project CallMethodOnDevice.
2. In Solution Explorer, right-click the CallMethodOnDevice project, and then click Manage NuGet Packages.
3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select
Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure
downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.

4. Add the following using statements at the top of the Program.cs file:

using System.Threading.Tasks;
using Microsoft.Azure.Devices;

5. Add the following fields to the Program class. Replace the placeholder value with the IoT Hub connection
string for the hub that you created in the previous section.

static ServiceClient serviceClient;

static string connectionString = "{iot hub connection string}";

6. Add the following method to the Program class:

private static async Task InvokeMethod()
{
var methodInvocation = new CloudToDeviceMethod("writeLine") { ResponseTimeout =
TimeSpan.FromSeconds(30) };
methodInvocation.SetPayloadJson("'a line to be written'");

var response = await serviceClient.InvokeDeviceMethodAsync("myDeviceId", methodInvocation);

Console.WriteLine("Response status: {0}, payload:", response.Status);

Console.WriteLine(response.GetPayloadAsJson());
}

This method invokes a direct method with name writeLine on the myDeviceId device. Then, it writes the
response provided by the device on the console. Note how it is possible to specify a timeout value for the
device to respond.
7. Finally, add the following lines to the Main method:

serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
InvokeMethod().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Run the applications

You are now ready to run the applications.
1. At a command prompt in the simulateddevice folder, run the following command to start listening for
method calls from your IoT Hub:

node SimulatedDevice.js

2. Now that the device is connected and waiting for method invocations, run the .NET CallMethodOnDevice
app to invoke the method in the simulated device app. You should see the device response written in the
console.
3. You will see the device react to the method by printing out the message and the application which called the
method display the response from the device:

Next steps
In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT hub's
identity registry. You used this device identity to enable the simulated device app to react to methods invoked by
the cloud. You also created an app that invokes methods on the device and displays the response from the device.
To continue getting started with IoT Hub and to explore other IoT scenarios, see:
Get started with IoT Hub
Schedule jobs on multiple devices
To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and
broadcast jobs tutorial.
Get started with device management (Node)
1/17/2017 • 9 min to read • Edit on GitHub

Introduction
IoT cloud applications can use primitives in Azure IoT Hub, namely the device twin and direct methods, to
remotely start and monitor device management actions on devices. This article provides guidance and code for
how an IoT cloud application and a device work together to initiate and monitor a remote device reboot using IoT
Hub.
To remotely start and monitor device management actions on your devices from a cloud-based, back-end app,
use Azure IoT Hub primitives such as device twin and direct methods. This tutorial shows you how a back-end app
and a device can work together to enable you initiate and monitor remote device reboot from IoT Hub.
You use a direct method to initiate device management actions (such as reboot, factory reset, and firmware
update) from a back-end app in the cloud. The device is responsible for:
Handling the method request sent from IoT Hub.
Initiating the corresponding device specific action on the device.
Providing status updates through the reported properties to IoT Hub.
You can use a back-end app in the cloud to run device twin queries to report on the progress of your device
management actions.
This tutorial shows you how to:
Use the Azure portal to create an IoT Hub and create a device identity in your IoT hub.
Create a simulated device app that has a direct method which enables reboot which can be called by the cloud.
Create a Node.js console app that calls the reboot direct method in the simulated device app through your IoT
hub.
At the end of this tutorial, you have two Node.js console apps:
dmpatterns_getstarted_device.js, which connects to your IoT hub with the device identity created earlier,
receives a reboot direct method, simulates a physical reboot, and reports the time for the last reboot.
dmpatterns_getstarted_service.js, which calls a direct method in the simulated device app, displays the
response, and displays the updated reported properties.
To complete this tutorial, you need the following:
Node.js version 0.12.x or later,
Prepare your development environment describes how to install Node.js for this tutorial on either Windows or
Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete
this task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.

3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device
app to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create a simulated device app

In this section, you will
Create a Node.js console app that responds to a direct method called by the cloud
Trigger a simulated device reboot
Use the reported properties to enable device twin queries to identify devices and when they last rebooted
1. Create a new empty folder called manageddevice. In the manageddevice folder, create a package.json
file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the manageddevice folder, run the following command to install the azure-
iot-device Device SDK package and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new dmpatterns_getstarted_device.js file in the manageddevice folder.
4. Add the following 'require' statements at the start of the dmpatterns_getstarted_device.js file:

'use strict';

var Client = require('azure-iot-device').Client;

var Protocol = require('azure-iot-device-mqtt').Mqtt;

5. Add a connectionString variable and use it to create a Client instance. Replace the connection string with
your device connection string.

var connectionString = 'HostName={youriothostname};DeviceId=myDeviceId;SharedAccessKey=

{yourdevicekey}';
var client = Client.fromConnectionString(connectionString, Protocol);

6. Add the following function to implement the direct method on the device
var onReboot = function(request, response) {

// Respond the cloud app for the direct method

response.send(200, 'Reboot started', function(err) {
if (!err) {
console.error('An error occured when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.');
}
});

// Report the reboot before the physical restart

var date = new Date();
var patch = {
iothubDM : {
reboot : {
lastReboot : date.toISOString(),
}
}
};

// Get device Twin

client.getTwin(function(err, twin) {
if (err) {
console.error('could not get twin');
} else {
console.log('twin acquired');
twin.properties.reported.update(patch, function(err) {
if (err) throw err;
console.log('Device reboot twin state reported')
});
}
});

// Add your device's reboot API for physical restart.

console.log('Rebooting!');
};

7. Open the connection to your IoT hub and start the direct method listener:

client.open(function(err) {
if (err) {
console.error('Could not open IotHub client');
} else {
console.log('Client opened. Waiting for reboot method.');
client.onDeviceMethod('reboot', onReboot);
}
});

8. Save and close the dmpatterns_getstarted_device.js file.

[AZURE.NOTE] To keep things simple, this tutorial does not implement any retry policy. In production code,
you should implement retry policies (such as an exponential backoff), as suggested in the MSDN article
Transient Fault Handling.

Trigger a remote reboot on the device using a direct method

In this section, you create a Node.js console app that initiates a remote reboot on a device using a direct method
and uses device twin queries to find the last reboot time for that device.
1. Create a new empty folder called triggerrebootondevice. In the triggerrebootondevice folder, create a
package.json file using the following command at your command prompt. Accept all the defaults:
npm init

2. At your command prompt in the triggerrebootondevice folder, run the following command to install the
azure-iothub Device SDK package and azure-iot-device-mqtt package:

npm install azure-iothub --save

3. Using a text editor, create a new dmpatterns_getstarted_service.js file in the triggerrebootondevice

folder.
4. Add the following 'require' statements at the start of the dmpatterns_getstarted_service.js file:

'use strict';

var Registry = require('azure-iothub').Registry;

var Client = require('azure-iothub').Client;

5. Add the following variable declarations and replace the placeholder values:

var connectionString = '{iothubconnectionstring}';

var registry = Registry.fromConnectionString(connectionString);
var client = Client.fromConnectionString(connectionString);
var deviceToReboot = 'myDeviceId';

6. Add the following function to invoke the device method to reboot the target device:

var startRebootDevice = function(twin) {

var methodName = "reboot";

var methodParams = {
methodName: methodName,
payload: null,
timeoutInSeconds: 30
};

client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {

if (err) {
console.error("Direct method error: "+err.message);
} else {
console.log("Successfully invoked the device to reboot.");
}
});
};

7. Add the following function to query for the device and get the last reboot time:
var queryTwinLastReboot = function() {

registry.getTwin(deviceToReboot, function(err, twin){

if (twin.properties.reported.iothubDM != null)
{
if (err) {
console.error('Could not query twins: ' + err.constructor.name + ': ' + err.message);
} else {
var lastRebootTime = twin.properties.reported.iothubDM.reboot.lastReboot;
console.log('Last reboot time: ' + JSON.stringify(lastRebootTime, null, 2));
}
} else
console.log('Waiting for device to report last reboot time.');
});
};

8. Add the following code to call the functions that will trigger the reboot direct method and query for the last
reboot time:

startRebootDevice();
setInterval(queryTwinLastReboot, 2000);

9. Save and close the dmpatterns_getstarted_service.js file.

Run the apps

You are now ready to run the apps.
1. At the command prompt in the manageddevice folder, run the following command to begin listening for
the reboot direct method.

node dmpatterns_getstarted_device.js

2. At the command prompt in the triggerrebootondevice folder, run the following command to trigger the
remote reboot and query for the device twin to find the last reboot time.

node dmpatterns_getstarted_service.js

3. You see the device response to the direct method in the console.

Customize and extend the device management actions

Your IoT solutions can expand the defined set of device management patterns or enable custom patterns through
the use of the device twin and direct method primitives. Other examples of device management actions include
factory reset, firmware update, software update, power management, network and connectivity management, and
data encryption.

Device maintenance windows

Typically, you configure devices to perform actions at a time that minimizes interruptions and downtime. Device
maintenance windows are a commonly used pattern to define the time when a device should update its
configuration. Your back-end solutions can use the desired properties of the device twin to define and activate a
policy on your device that enables a maintenance window. When a device receives the maintenance window
policy, it can use the reported property of the device twin to report the status of the policy. The back-end app can
then use device twin queries to attest to compliance of devices and each policy.

Next steps
In this tutorial, you used a direct method to trigger a remote reboot on a device, used the reported properties to
report the last reboot time from the device, and queried for the device twin to discover the last reboot time of the
device from the cloud.
To continue getting started with IoT Hub and device management patterns such as remote over the air firmware
update, see:
Tutorial: How to do a firmware update
To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and
broadcast jobs tutorial.
To continue getting started with IoT Hub, see Getting started with the IoT Gateway SDK.
Get started with device management (.NET/Node)
1/17/2017 • 9 min to read • Edit on GitHub

Introduction
Back-end apps can use primitives in Azure IoT Hub, namely the device twin and direct methods, to remotely start
and monitor device management actions on devices. This article provides guidance and code for how back-end
apps and devices work together to initiate and monitor a remote device reboot using IoT Hub.
To remotely start and monitor device management actions on your devices from a cloud-based, back-end app, use
IoT Hub primitives such as device twin and direct methods. This tutorial shows you how a back-end app and a
device can work together to enable you initiate and monitor remote device reboot from IoT Hub.
You use a direct method to initiate device management actions (such as reboot, factory reset, and firmware update)
from a back-end app in the cloud. The device is responsible for:
Handling the method request sent from IoT Hub.
Initiating the corresponding device specific action on the device.
Providing status updates through the reported properties to IoT Hub.
You can use a back-end app in the cloud to run device twin queries to report on the progress of your device
management actions.
This tutorial shows you how to:
Use the Azure portal to create an IoT Hub and create a device identity in your IoT hub.
Create a simulated device app that has a direct method which enables reboot which can be called by the cloud.
Create a .NET console app that calls the reboot direct method in the simulated device app through your IoT hub.
At the end of this tutorial, you have a Node.js console device app and a .NET (C#) console back-end app:
dmpatterns_getstarted_device.js, which connects to your IoT hub with the device identity created earlier,
receives a reboot direct method, simulates a physical reboot, and reports the time for the last reboot.
TriggerReboot, which calls a direct method in the simulated device app, displays the response, and displays the
updated reported properties.
To complete this tutorial, you need the following:
Microsoft Visual Studio 2015.
Node.js version 0.12.x or later,
Prepare your development environment describes how to install Node.js for this tutorial on either Windows or
Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free F1
tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure
to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the IoT
Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT Hub
developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device app
to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Trigger a remote reboot on the device using a direct method

In this section, you create a .NET console app (using C#) that initiates a remote reboot on a device using a direct
method and uses device twin queries to find the last reboot time for that device.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the
Console Application project template. Name the project TriggerReboot.

2. In Solution Explorer, right-click the TriggerReboot project, and then click Manage NuGet Packages.
3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select
Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure
downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.
4. Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices;

5. Add the following fields to the Program class. Replace the placeholder value with the IoT Hub connection
string for the hub that you created in the previous section and the target device.

static RegistryManager registryManager;

static string connString = "{iot hub connection string}";
static ServiceClient client;
static JobClient jobClient;
static string targetDevice = "{deviceIdForTargetDevice}";

6. Add the following method to the Program class. This code gets the device twin for the rebooting device and
outputs the reported properties.

public static async Task QueryTwinRebootReported()

{
Twin twin = await registryManager.GetTwinAsync(targetDevice);
Console.WriteLine(twin.Properties.Reported.ToJson());
}

7. Add the following method to the Program class. This code initiates the reboot on the device using a direct
method.

public static async Task StartReboot()

{
client = ServiceClient.CreateFromConnectionString(connString);
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult result = await client.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

}

8. Finally, add the following lines to the Main method:

registryManager = RegistryManager.CreateFromConnectionString(connString);
StartReboot().Wait();
QueryTwinRebootReported().Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

9. Build the solution.

Create a simulated device app

In this section, you will
Create a Node.js console app that responds to a direct method called by the cloud
Trigger a simulated device reboot
Use the reported properties to enable device twin queries to identify devices and when they last rebooted
1. Create a new empty folder called manageddevice. In the manageddevice folder, create a package.json file
using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the manageddevice folder, run the following command to install the azure-
iot-device Device SDK package and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new dmpatterns_getstarted_device.js file in the manageddevice folder.
4. Add the following 'require' statements at the start of the dmpatterns_getstarted_device.js file:

'use strict';

var Client = require('azure-iot-device').Client;

var Protocol = require('azure-iot-device-mqtt').Mqtt;

5. Add a connectionString variable and use it to create a Client instance. Replace the connection string with
your device connection string.

var connectionString = 'HostName={youriothostname};DeviceId=myDeviceId;SharedAccessKey=

{yourdevicekey}';
var client = Client.fromConnectionString(connectionString, Protocol);

6. Add the following function to implement the direct method on the device
var onReboot = function(request, response) {

// Respond the cloud app for the direct method

response.send(200, 'Reboot started', function(err) {
if (!err) {
console.error('An error occured when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.');
}
});

// Report the reboot before the physical restart

var date = new Date();
var patch = {
iothubDM : {
reboot : {
lastReboot : date.toISOString(),
}
}
};

// Get device Twin

client.getTwin(function(err, twin) {
if (err) {
console.error('could not get twin');
} else {
console.log('twin acquired');
twin.properties.reported.update(patch, function(err) {
if (err) throw err;
console.log('Device reboot twin state reported')
});
}
});

// Add your device's reboot API for physical restart.

console.log('Rebooting!');
};

7. Add the following code to open the connection to your IoT hub and start the direct method listener:

client.open(function(err) {
if (err) {
console.error('Could not open IotHub client');
} else {
console.log('Client opened. Waiting for reboot method.');
client.onDeviceMethod('reboot', onReboot);
}
});

8. Save and close the dmpatterns_getstarted_device.js file.

[AZURE.NOTE] To keep things simple, this tutorial does not implement any retry policy. In production code,
you should implement retry policies (such as an exponential backoff), as suggested in the MSDN article
Transient Fault Handling.

Run the apps

You are now ready to run the apps.
1. At the command prompt in the manageddevice folder, run the following command to begin listening for
the reboot direct method.
node dmpatterns_getstarted_device.js

2. Run the C# console app TriggerReboot- right click on the TriggerReboot project, select Debug and Start
new instance.
3. You see the device response to the direct method in the console.

Customize and extend the device management actions

Your IoT solutions can expand the defined set of device management patterns or enable custom patterns through
the use of the device twin and cloud-to-device method primitives. Other examples of device management actions
include factory reset, firmware update, software update, power management, network and connectivity
management, and data encryption.

Device maintenance windows

Typically, you configure devices to perform actions at a time that minimizes interruptions and downtime. Device
maintenance windows are a commonly used pattern to define the time when a device should update its
configuration. Your back-end solutions can use the desired properties of the device twin to define and activate a
policy on your device that enables a maintenance window. When a device receives the maintenance window policy,
it can use the reported property of the device twin to report the status of the policy. The back-end app can then use
device twin queries to attest to compliance of devices and each policy.

Next steps
In this tutorial, you used a direct method to trigger a remote reboot on a device, used the reported properties to
report the last reboot time from the device, and queried for the device twin to discover the last reboot time of the
device from the cloud.
To continue getting started with IoT Hub and device management patterns such as remote over the air firmware
update, see:
Tutorial: How to do a firmware update
To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and
broadcast jobs tutorial.
To continue getting started with IoT Hub, see Getting started with the IoT Gateway SDK.
Use desired properties to configure devices (Node)
1/17/2017 • 12 min to read • Edit on GitHub

Introduction
In Get started with IoT Hub device twins, you learned how to set device metadata from your solution back end
using tags, report device conditions from a device app using reported properties, and query this information
using a SQL-like language.
In this tutorial, you will learn how to use the the device twin's desired properties in conjunction with reported
properties, to remotely configure device apps. More specifically, this tutorial shows how a device twin's reported
and desired properties enable a multi-step configuration of a device application setting, and provide the visibility
to the solution back end of the status of this operation across all devices. You can find more information
regarding the role of device configurations in Overview of device management with IoT Hub.
At a high level, using device twins enable the solution back end to specify the desired configuration for the
managed devices, instead of sending specific commands. This puts the device in charge of establishing the best
way to update its configuration (very important in IoT scenarios where specific device conditions affect the ability
to immediately carry out specific commands), while continually reporting to the solution back end the current
state and potential error conditions of the update process. This pattern is instrumental to the management of
large sets of devices, as it enables the solution back end to have full visibility of the state of the configuration
process across all devices.

NOTE
In scenarios where devices are controlled in a more interactive fashion (turn on a fan from a user-controlled app), consider
using direct methods.

In this tutorial, the solution back end changes the telemetry configuration of a target device and, as a result of
that, the device app follows a multi-step process to apply a configuration update (for example requiring a
software module restart), which this tutorial simulates with a simple delay).
The solution back end stores the configuration in the device twin's desired properties in the following way:

{
...
"properties": {
...
"desired": {
"telemetryConfig": {
"configId": "{id of the configuration}",
"sendFrequency": "{config}"
}
}
...
}
...
}
NOTE
Since configurations can be complex objects, they are usually assigned unique ids (hashes or GUIDs) to simplify their
comparisons.

The device app reports its current configuration mirroring the desired property telemetryConfig in the
reported properties:

{
"properties": {
...
"reported": {
"telemetryConfig": {
"changeId": "{id of the current configuration}",
"sendFrequency": "{current configuration}",
"status": "Success",
}
}
...
}
}

Note how the reported telemetryConfig has an additional property status, used to report the state of the
configuration update process.
When a new desired configuration is received, the device app reports a pending configuration by changing the
information:

{
"properties": {
...
"reported": {
"telemetryConfig": {
"changeId": "{id of the current configuration}",
"sendFrequency": "{current configuration}",
"status": "Pending",
"pendingConfig": {
"changeId": "{id of the pending configuration}",
"sendFrequency": "{pending configuration}"
}
}
}
...
}
}

Then, at some later time, the device app will report the success or failure of this operation by updating the above
property. Note how the solution back end is able, at any time, to query the status of the configuration process
across all the devices.
This tutorial shows you how to:
Create a simulated device app that receives configuration updates from the solution back end and reports
multiple updates as reported properties on the configuration update process.
Create a back-end app that updates the desired configuration of a device, and then queries the configuration
update process.
At the end of this tutorial, you will have two Node.js console apps:
SimulateDeviceConfiguration.js, a simulated device app that waits for a desired configuration update and
reports the status of a simulated configuration update process.
SetDesiredConfigurationAndQuery.js, a Node.js back-end app, which sets the desired configuration on a
device and queries the configuration update process.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both device and back-
end apps.

To complete this tutorial you need the following:

Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)
If you followed the Get started with device twins tutorial, you already have an IoT hub and a device identity called
myDeviceId; and you can skip to the Create the simulated device app section.

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete
this task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.

3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check
mark appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information,
see Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in
the Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access
policies.

6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device
app to connect to your IoT Hub as a device.

Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create the simulated device app

In this section, you create a Node.js console app that connects to your hub as myDeviceId, waits for a desired
configuration update and then reports updates on the simulated configuration update process.
1. Create a new empty folder called simulatedeviceconfiguration. In the simulatedeviceconfiguration
folder, create a new package.json file using the following command at your command prompt. Accept all
the defaults:

npm init

2. At your command prompt in the simulatedeviceconfiguration folder, run the following command to
install the azure-iot-device, and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new SimulateDeviceConfiguration.js file in the

simulatedeviceconfiguration folder.
4. Add the following code to the SimulateDeviceConfiguration.js file, and substitute the {device
connection string} placeholder with the device connection string you copied when you created the
myDeviceId device identity:
'use strict';
var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').Mqtt;

var connectionString = '{device connection string}';

var client = Client.fromConnectionString(connectionString, Protocol);

client.open(function(err) {
if (err) {
console.error('could not open IotHub client');
} else {
client.getTwin(function(err, twin) {
if (err) {
console.error('could not get twin');
} else {
console.log('retrieved device twin');
twin.properties.reported.telemetryConfig = {
configId: "0",
sendFrequency: "24h"
}
twin.on('properties.desired', function(desiredChange) {
console.log("received change: "+JSON.stringify(desiredChange));
var currentTelemetryConfig = twin.properties.reported.telemetryConfig;
if (desiredChange.telemetryConfig &&desiredChange.telemetryConfig.configId !==
currentTelemetryConfig.configId) {
initConfigChange(twin);
}
});
}
});
}
});

The Client object exposes all the methods required to interact with device twins from the device. The
previous code, after it initializes the Client object, retrieves the device twin for myDeviceId, and attaches
a handler for the update on desired properties. The handler verifies that there is an actual configuration
change request by comparing the configIds, then invokes a method that starts the configuration change.
Note that for the sake of simplicity, the previous code uses a hard-coded default for the inital
configuration. A real app would probably load that configuration from a local storage.

IMPORTANT
Desired property change events are always emitted once at device connection, make sure to check that there is an
actual change in the desired properties before performing any action.

5. Add the following methods before the client.open() invocation:

var initConfigChange = function(twin) {
var currentTelemetryConfig = twin.properties.reported.telemetryConfig;
currentTelemetryConfig.pendingConfig = twin.properties.desired.telemetryConfig;
currentTelemetryConfig.status = "Pending";

var patch = {
telemetryConfig: currentTelemetryConfig
};
twin.properties.reported.update(patch, function(err) {
if (err) {
console.log('Could not report properties');
} else {
console.log('Reported pending config change: ' + JSON.stringify(patch));
setTimeout(function() {completeConfigChange(twin);}, 60000);
}
});
}

var completeConfigChange = function(twin) {

var currentTelemetryConfig = twin.properties.reported.telemetryConfig;
currentTelemetryConfig.configId = currentTelemetryConfig.pendingConfig.configId;
currentTelemetryConfig.sendFrequency = currentTelemetryConfig.pendingConfig.sendFrequency;
currentTelemetryConfig.status = "Success";
delete currentTelemetryConfig.pendingConfig;

var patch = {
telemetryConfig: currentTelemetryConfig
};
patch.telemetryConfig.pendingConfig = null;

twin.properties.reported.update(patch, function(err) {
if (err) {
console.error('Error reporting properties: ' + err);
} else {
console.log('Reported completed config change: ' + JSON.stringify(patch));
}
});
};

The initConfigChange method updates reported properties on the local device twin object with the
configuration update request and sets the status to Pending, then updates the device twin on the service.
After successfully updating the device twin, it simulates a long running process that terminates in the
execution of completeConfigChange. This method updates the local device twin's reported properties
setting the status to Success and removing the pendingConfig object. It then updates the device twin on
the service.
Note that, to save bandwidth, reported properties are updated by specifying only the properties to be
modified (named patch in the above code), instead of replacing the whole document.

NOTE
This tutorial does not simulate any behavior for concurrent configuration updates. Some configuration update
processes might be able to accommodate changes of target configuration while the update is running, others
might have to queue them, and others could reject them with an error condition. Make sure to consider the
desired behavior for your specific configuration process, and add the appropriate logic before initiating the
configuration change.

6. Run the device app:

node SimulateDeviceConfiguration.js
You should see the message retrieved device twin . Keep the app running.

Create the service app

In this section, you will create a Node.js console app that updates the desired properties on the device twin
associated with myDeviceId with a new telemetry configuration object. It then queries the device twins stored in
the IoT hub and shows the difference between the desired and reported configurations of the device.
1. Create a new empty folder called setdesiredandqueryapp. In the setdesiredandqueryapp folder,
create a new package.json file using the following command at your command prompt. Accept all the
defaults:

npm init

2. At your command prompt in the setdesiredandqueryapp folder, run the following command to install
the azure-iothub package:

npm install azure-iothub node-uuid --save

3. Using a text editor, create a new SetDesiredAndQuery.js file in the addtagsandqueryapp folder.
4. Add the following code to the SetDesiredAndQuery.js file, and substitute the {iot hub connection
string} placeholder with the IoT Hub connection string you copied when you created your hub:

'use strict';
var iothub = require('azure-iothub');
var uuid = require('node-uuid');
var connectionString = '{iot hub connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

registry.getTwin('myDeviceId', function(err, twin){

if (err) {
console.error(err.constructor.name + ': ' + err.message);
} else {
var newConfigId = uuid.v4();
var newFrequency = process.argv[2] || "5m";
var patch = {
properties: {
desired: {
telemetryConfig: {
configId: newConfigId,
sendFrequency: newFrequency
}
}
}
}
twin.update(patch, function(err) {
if (err) {
console.error('Could not update twin: ' + err.constructor.name + ': ' +
err.message);
} else {
console.log(twin.deviceId + ' twin updated successfully');
}
});
setInterval(queryTwins, 10000);
}
});

The Registry object exposes all the methods required to interact with device twins from the service. The
previous code, after it initializes the Registry object, retrieves the device twin for myDeviceId, and
updates its desired properties with a new telemetry configuration object. After that, it calls the
queryTwins function event 10 seconds.

IMPORTANT
This application queries IoT Hub every 10 seconds for illustrative purposes. Use queries to generate user-facing
reports across many devices, and not to detect changes. If your solution requires real-time notifications of device
events use device-to-cloud messages.
.

5. Add the following code right before the registry.getDeviceTwin() invocation to implement the
queryTwins function:

var queryTwins = function() {

var query = registry.createQuery("SELECT * FROM devices WHERE deviceId = 'myDeviceId'", 100);
query.nextAsTwin(function(err, results) {
if (err) {
console.error('Failed to fetch the results: ' + err.message);
} else {
console.log();
results.forEach(function(twin) {
var desiredConfig = twin.properties.desired.telemetryConfig;
var reportedConfig = twin.properties.reported.telemetryConfig;
console.log("Config report for: " + twin.deviceId);
console.log("Desired: ");
console.log(JSON.stringify(desiredConfig, null, 2));
console.log("Reported: ");
console.log(JSON.stringify(reportedConfig, null, 2));
});
}
});
};

The previous code queries the device twins stored in the IoT hub and prints the desired and reported
telemetry configurations. Refer to the IoT Hub query language to learn how to generate rich reports
across all your devices.
6. With SimulateDeviceConfiguration.js running, run the application with:

node SetDesiredAndQuery.js 5m

You should see the reported configuration change from Success to Pending to Success again with the
new active send frequency of five minutes instead of 24 hours.

IMPORTANT
There is a delay of up to a minute between the device report operation and the query result. This is to enable the
query infrastructure to work at very high scale. To retrieve consistent views of a single device twin use the
getDeviceTwin method in the Registry class.

Next steps
In this tutorial, you set a desired configuration as desired properties from a back-end app, and wrote a simulated
device app to detect that change and simulate a multi-step update process reporting its status as reported
properties to the device twin.
Use the following resources to learn how to:
send telemetry from devices with the Get started with IoT Hub tutorial,
schedule or perform operations on large sets of devices see the Schedule and broadcast jobs tutorial.
control devices interactively (such as turning on a fan from a user-controlled app), with the Use direct
methods tutorial.
Use desired properties to configure devices
1/17/2017 • 12 min to read • Edit on GitHub

Introduction
In Get started with IoT Hub device twins, you learned how to set device metadata from your solution back end
using tags, report device conditions from a device app using reported properties, and query this information using
a SQL-like language.
In this tutorial, you will learn how to use the the device twin's desired properties in conjunction with reported
properties, to remotely configure device apps. More specifically, this tutorial shows how a device twin's reported
and desired properties enable a multi-step configuration of a device application setting, and provide the visibility to
the solution back end of the status of this operation across all devices. You can find more information regarding
the role of device configurations in Overview of device management with IoT Hub.
At a high level, using device twins enable the solution back end to specify the desired configuration for the
managed devices, instead of sending specific commands. This puts the device in charge of establishing the best
way to update its configuration (very important in IoT scenarios where specific device conditions affect the ability
to immediately carry out specific commands), while continually reporting to the solution back end the current state
and potential error conditions of the update process. This pattern is instrumental to the management of large sets
of devices, as it enables the solution back end to have full visibility of the state of the configuration process across
all devices.

NOTE
In scenarios where devices are controlled in a more interactive fashion (turn on a fan from a user-controlled app), consider
using direct methods.

In this tutorial, the solution back end changes the telemetry configuration of a target device and, as a result of that,
the device app follows a multi-step process to apply a configuration update (for example requiring a software
module restart), which this tutorial simulates with a simple delay).
The solution back end stores the configuration in the device twin's desired properties in the following way:

{
...
"properties": {
...
"desired": {
"telemetryConfig": {
"configId": "{id of the configuration}",
"sendFrequency": "{config}"
}
}
...
}
...
}
NOTE
Since configurations can be complex objects, they are usually assigned unique ids (hashes or GUIDs) to simplify their
comparisons.

The device app reports its current configuration mirroring the desired property telemetryConfig in the reported
properties:

{
"properties": {
...
"reported": {
"telemetryConfig": {
"changeId": "{id of the current configuration}",
"sendFrequency": "{current configuration}",
"status": "Success",
}
}
...
}
}

Note how the reported telemetryConfig has an additional property status, used to report the state of the
configuration update process.
When a new desired configuration is received, the device app reports a pending configuration by changing the
information:

{
"properties": {
...
"reported": {
"telemetryConfig": {
"changeId": "{id of the current configuration}",
"sendFrequency": "{current configuration}",
"status": "Pending",
"pendingConfig": {
"changeId": "{id of the pending configuration}",
"sendFrequency": "{pending configuration}"
}
}
}
...
}
}

Then, at some later time, the device app will report the success or failure of this operation by updating the above
property. Note how the solution back end is able, at any time, to query the status of the configuration process
across all the devices.
This tutorial shows you how to:
Create a simulated device app that receives configuration updates from the solution back end and reports
multiple updates as reported properties on the configuration update process.
Create a back-end app that updates the desired configuration of a device, and then queries the configuration
update process.
At the end of this tutorial, you will have two Node.js console apps:
SimulateDeviceConfiguration.js, a simulated device app that waits for a desired configuration update and
reports the status of a simulated configuration update process.
SetDesiredConfigurationAndQuery, a .NET back-end app, which sets the desired configuration on a device
and queries the configuration update process.

NOTE
The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both device and back-
end apps.

To complete this tutorial you need the following:

Microsoft Visual Studio 2015.
Node.js version 0.10.x or later.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)
If you followed the Get started with device twins tutorial, you already have an IoT hub and a device identity called
myDeviceId; and you can skip to the Create the simulated device app section.

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.

3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free F1
tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure
to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the IoT
Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT Hub
developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device app
to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create the simulated device app

In this section, you create a Node.js console app that connects to your hub as myDeviceId, waits for a desired
configuration update and then reports updates on the simulated configuration update process.
1. Create a new empty folder called simulatedeviceconfiguration. In the simulatedeviceconfiguration
folder, create a new package.json file using the following command at your command prompt. Accept all the
defaults:

npm init

2. At your command prompt in the simulatedeviceconfiguration folder, run the following command to
install the azure-iot-device, and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new SimulateDeviceConfiguration.js file in the simulatedeviceconfiguration

folder.
4. Add the following code to the SimulateDeviceConfiguration.js file, and substitute the {device
connection string} placeholder with the device connection string you copied when you created the
myDeviceId device identity:
'use strict';
var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').Mqtt;

var connectionString = '{device connection string}';

var client = Client.fromConnectionString(connectionString, Protocol);

client.open(function(err) {
if (err) {
console.error('could not open IotHub client');
} else {
client.getTwin(function(err, twin) {
if (err) {
console.error('could not get twin');
} else {
console.log('retrieved device twin');
twin.properties.reported.telemetryConfig = {
configId: "0",
sendFrequency: "24h"
}
twin.on('properties.desired', function(desiredChange) {
console.log("received change: "+JSON.stringify(desiredChange));
var currentTelemetryConfig = twin.properties.reported.telemetryConfig;
if (desiredChange.telemetryConfig &&desiredChange.telemetryConfig.configId !==
currentTelemetryConfig.configId) {
initConfigChange(twin);
}
});
}
});
}
});

The Client object exposes all the methods required to interact with device twins from the device. The
previous code, after it initializes the Client object, retrieves the device twin for myDeviceId, and attaches a
handler for the update on desired properties. The handler verifies that there is an actual configuration
change request by comparing the configIds, then invokes a method that starts the configuration change.
Note that for the sake of simplicity, the previous code uses a hard-coded default for the inital configuration.
A real app would probably load that configuration from a local storage.

IMPORTANT
Desired property change events are always emitted once at device connection, make sure to check that there is an
actual change in the desired properties before performing any action.

5. Add the following methods before the client.open() invocation:

var initConfigChange = function(twin) {
var currentTelemetryConfig = twin.properties.reported.telemetryConfig;
currentTelemetryConfig.pendingConfig = twin.properties.desired.telemetryConfig;
currentTelemetryConfig.status = "Pending";

var patch = {
telemetryConfig: currentTelemetryConfig
};
twin.properties.reported.update(patch, function(err) {
if (err) {
console.log('Could not report properties');
} else {
console.log('Reported pending config change: ' + JSON.stringify(patch));
setTimeout(function() {completeConfigChange(twin);}, 60000);
}
});
}

var completeConfigChange = function(twin) {

var currentTelemetryConfig = twin.properties.reported.telemetryConfig;
currentTelemetryConfig.configId = currentTelemetryConfig.pendingConfig.configId;
currentTelemetryConfig.sendFrequency = currentTelemetryConfig.pendingConfig.sendFrequency;
currentTelemetryConfig.status = "Success";
delete currentTelemetryConfig.pendingConfig;

var patch = {
telemetryConfig: currentTelemetryConfig
};
patch.telemetryConfig.pendingConfig = null;

twin.properties.reported.update(patch, function(err) {
if (err) {
console.error('Error reporting properties: ' + err);
} else {
console.log('Reported completed config change: ' + JSON.stringify(patch));
}
});
};

The initConfigChange method updates the reported properties on the local device twin object with the
configuration update request and sets the status to Pending, then updates the device twin on the service.
After successfully updating the device twin, it simulates a long running process that terminates in the
execution of completeConfigChange. This method updates the local reported properties setting the status
to Success and removing the pendingConfig object. It then updates the device twin on the service.
Note that, to save bandwidth, reported properties are updated by specifying only the properties to be
modified (named patch in the above code), instead of replacing the whole document.

NOTE
This tutorial does not simulate any behavior for concurrent configuration updates. Some configuration update
processes might be able to accommodate changes of target configuration while the update is running, others might
have to queue them, and others could reject them with an error condition. Make sure to consider the desired
behavior for your specific configuration process, and add the appropriate logic before initiating the configuration
change.

6. Run the device app:

node SimulateDeviceConfiguration.js
You should see the message retrieved device twin . Keep the app running.

Create the service app

In this section, you will create a .NET console app that updates the desired properties on the device twin associated
with myDeviceId with a new telemetry configuration object. It then queries the device twins stored in the IoT hub
and shows the difference between the desired and reported configurations of the device.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the
Console Application project template. Name the project SetDesiredConfigurationAndQuery.

2. In Solution Explorer, right-click the SetDesiredConfigurationAndQuery project, and then click Manage
NuGet Packages.
3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select
Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure
downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.

4. Add the following using statements at the top of the Program.cs file:
using Microsoft.Azure.Devices;
using System.Threading;
using Newtonsoft.Json;

5. Add the following fields to the Program class. Replace the placeholder value with the IoT Hub connection
string for the hub that you created in the previous section.

static RegistryManager registryManager;

static string connectionString = "{iot hub connection string}";

6. Add the following method to the Program class:

static private async Task SetDesiredConfigurationAndQuery()

{
var twin = await registryManager.GetTwinAsync("myDeviceId");
var patch = new {
properties = new {
desired = new {
telemetryConfig = new {
configId = Guid.NewGuid().ToString(),
sendFrequency = "5m"
}
}
}
};

await registryManager.UpdateTwinAsync(twin.DeviceId, JsonConvert.SerializeObject(patch),

twin.ETag);
Console.WriteLine("Updated desired configuration");

while (true)
{
var query = registryManager.CreateQuery("SELECT * FROM devices WHERE deviceId = 'myDeviceId'");
var results = await query.GetNextAsTwinAsync();
foreach (var result in results)
{
Console.WriteLine("Config report for: {0}", result.DeviceId);
Console.WriteLine("Desired telemetryConfig: {0}",
JsonConvert.SerializeObject(result.Properties.Desired["telemetryConfig"], Formatting.Indented));
Console.WriteLine("Reported telemetryConfig: {0}",
JsonConvert.SerializeObject(result.Properties.Reported["telemetryConfig"], Formatting.Indented));
Console.WriteLine();
}
Thread.Sleep(10000);
}
}

The Registry object exposes all the methods required to interact with device twins from the service. The
previous code, after it initializes the Registry object, retrieves the device twin for myDeviceId, and updates
its desired properties with a new telemetry configuration object. After that, every 10 seconds, it queries the
device twins stored in the IoT hub and prints the desired and reported telemetry configurations. Refer to the
IoT Hub query language to learn how to generate rich reports across all your devices.

IMPORTANT
This application queries IoT Hub every 10 seconds for illustrative purposes. Use queries to generate user-facing
reports across many devices, and not to detect changes. If your solution requires real-time notifications of device
events use device-to-cloud messages.
7. Finally, add the following lines to the Main method:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
SetDesiredConfigurationAndQuery();
Console.WriteLine("Press any key to quit.");
Console.ReadLine();

8. With SimulateDeviceConfiguration.js running, run the .NET application from Visual Studio using F5 and
you should see the reported configuration change from Success to Pending to Success again with the new
active send frequency of five minutes instead of 24 hours.

IMPORTANT
There is a delay of up to a minute between the device report operation and the query result. This is to enable the
query infrastructure to work at very high scale. To retrieve consistent views of a single device twin use the
getDeviceTwin method in the Registry class.

Next steps
In this tutorial, you set a desired configuration as desired properties from the solution back end, and wrote a device
app to detect that change and simulate a multi-step update process reporting its status through the reported
properties.
Use the following resources to learn how to:
send telemetry from devices with the Get started with IoT Hub tutorial,
schedule or perform operations on large sets of devices see the Schedule and broadcast jobs tutorial.
control devices interactively (such as turning on a fan from a user-controlled app), with the Use direct methods
tutorial.
Use device management to initiate a device firmware
update (Node/Node)
2/6/2017 • 9 min to read • Edit on GitHub

Introduction
In the Get started with device management tutorial, you saw how to use the device twin and direct methods
primitives to remotely reboot a device. This tutorial uses the same IoT Hub primitives and provides guidance and
shows you how to do an end-to-end simulated firmware update. This pattern is used in the firmware update
implementation for the Intel Edison device sample.
This tutorial shows you how to:
Create a Node.js console app that calls the firmwareUpdate direct method in the simulated device app through
your IoT hub.
Create a simulated device app that implements a firmwareUpdate direct method. This method initiates a
multi-stage process that waits to download the firmware image, downloads the firmware image, and finally
applies the firmware image. During each stage of the update, the device uses the reported properties to report
on progress.
At the end of this tutorial, you have two Node.js console apps:
dmpatterns_fwupdate_service.js, which calls a direct method in the simulated device app, displays the response,
and periodically (every 500ms) displays the updated reported properties.
dmpatterns_fwupdate_device.js, which connects to your IoT hub with the device identity created earlier,
receives a firmwareUpdate direct method, runs through a multi-state process to simulate a firmware update
including: waiting for the image download, downloading the new image, and finally applying the image.
To complete this tutorial, you need the following:
Node.js version 0.12.x or later,
Prepare your development environment describes how to install Node.js for this tutorial on either Windows or
Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)
Follow the Get started with device management article to create your IoT hub and get your IoT Hub connection
string.

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure
to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device
app to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Trigger a remote firmware update on the device using a direct method

In this section, you create a Node.js console app that initiates a remote firmware update on a device. The app uses
a direct method to initiate the update and uses device twin queries to periodically get the status of the active
firmware update.
1. Create an empty folder called triggerfwupdateondevice. In the triggerfwupdateondevice folder, create
a package.json file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the triggerfwupdateondevice folder, run the following command to install
the azure-iot-hub and azure-iot-device-mqtt Device SDK packages:

npm install azure-iot-hub --save

3. Using a text editor, create a dmpatterns_getstarted_service.js file in the triggerfwupdateondevice folder.

4. Add the following 'require' statements at the start of the dmpatterns_getstarted_service.js file:

'use strict';

var Registry = require('azure-iothub').Registry;

var Client = require('azure-iothub').Client;

5. Add the following variable declarations and replace the placeholder values:

var connectionString = '{device_connectionstring}';

var registry = Registry.fromConnectionString(connectionString);
var client = Client.fromConnectionString(connectionString);
var deviceToUpdate = 'myDeviceId';

6. Add the following function to find and display the value of the firmwareUpdate reported property.
var queryTwinFWUpdateReported = function() {
registry.getTwin(deviceToUpdate, function(err, twin){
if (err) {
console.error('Could not query twins: ' + err.constructor.name + ': ' + err.message);
} else {
console.log((JSON.stringify(twin.properties.reported.iothubDM.firmwareUpdate)) + "\n");
}
});
};

7. Add the following function to invoke the firmwareUpdate method to reboot the target device:

var startFirmwareUpdateDevice = function() {

var params = {
fwPackageUri: 'https://secureurl'
};

var methodName = "firmwareUpdate";

var payloadData = JSON.stringify(params);

var methodParams = {
methodName: methodName,
payload: payloadData,
timeoutInSeconds: 30
};

client.invokeDeviceMethod(deviceToUpdate, methodParams, function(err, result) {

if (err) {
console.error('Could not start the firmware update on the device: ' + err.message)
}
});
};

8. Finally, Add the following function to code to start the firmware update sequence and start periodically
showing the reported properties:

startFirmwareUpdateDevice();
setInterval(queryTwinFWUpdateReported, 500);

9. Save and close the dmpatterns_fwupdate_service.js file.

Create a simulated device app

In this section, you:
Create a Node.js console app that responds to a direct method called by the cloud
Trigger a simulated firmware update
Use the reported properties to enable device twin queries to identify devices and when they last completed a
firmware update
1. Create an empty folder called manageddevice. In the manageddevice folder, create a package.json file
using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the manageddevice folder, run the following command to install the azure-
iot-device and azure-iot-device-mqtt Device SDK packages:
npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a dmpatterns_fwupdate_device.js file in the manageddevice folder.

4. Add the following 'require' statements at the start of the dmpatterns_fwupdate_device.js file:

'use strict';

var Client = require('azure-iot-device').Client;

var Protocol = require('azure-iot-device-mqtt').Mqtt;

5. Add a connectionString variable and use it to create a Client instance. Replace the
{yourdeviceconnectionstring} placeholder with the connection string you previously made a note of in the
"Create a device identity" section previously:

var connectionString = '{yourdeviceconnectionstring}';

var client = Client.fromConnectionString(connectionString, Protocol);

6. Add the following function that is used to update reported properties:

var reportFWUpdateThroughTwin = function(twin, firmwareUpdateValue) {

var patch = {
iothubDM : {
firmwareUpdate : firmwareUpdateValue
}
};

twin.properties.reported.update(patch, function(err) {
if (err) throw err;
console.log('twin state reported: ' + firmwareUpdateValue.status);
});
};

7. Add the following functions that simulate downloading and applying the firmware image:

var simulateDownloadImage = function(imageUrl, callback) {

var error = null;
var image = "[fake image data]";

console.log("Downloading image from " + imageUrl);

callback(error, image);
}

var simulateApplyImage = function(imageData, callback) {

var error = null;

if (!imageData) {
error = {message: 'Apply image failed because of missing image data.'};
}

callback(error);
}

8. Add the following function that updates the firmware update status through the reported properties to
waiting. Typically, devices are informed of an available update and an administrator defined policy causes
the device to start downloading and applying the update. This function is where the logic to enable that
policy should run. For simplicity, the sample deplays for four seconds before proceeding to download the
firmware image:

var waitToDownload = function(twin, fwPackageUriVal, callback) {

var now = new Date();

reportFWUpdateThroughTwin(twin, {
fwPackageUri: fwPackageUriVal,
status: 'waiting',
error : null,
startedWaitingTime : now.toISOString()
});
setTimeout(callback, 4000);
};

9. Add the following function that updates the firmware update status through the reported properties to
downloading. The function then simulates a firmware download and finally updates the firmware update
status to either downloadFailed or downloadComplete:

var downloadImage = function(twin, fwPackageUriVal, callback) {

var now = new Date();

reportFWUpdateThroughTwin(twin, {
status: 'downloading',
});

setTimeout(function() {
// Simulate download
simulateDownloadImage(fwPackageUriVal, function(err, image) {

if (err)
{
reportFWUpdateThroughTwin(twin, {
status: 'downloadfailed',
error: {
code: error_code,
message: error_message,
}
});
}
else {
reportFWUpdateThroughTwin(twin, {
status: 'downloadComplete',
downloadCompleteTime: now.toISOString(),
});

setTimeout(function() { callback(image); }, 4000);

}
});

}, 4000);
}

10. Add the following function that updates the firmware update status through the reported properties to
applying. The function then simulates applying the firmware image and finally updates the firmware
update status to either applyFailed or applyComplete:
var applyImage = function(twin, imageData, callback) {
var now = new Date();

reportFWUpdateThroughTwin(twin, {
status: 'applying',
startedApplyingImage : now.toISOString()
});

setTimeout(function() {

// Simulate apply firmware image

simulateApplyImage(imageData, function(err) {
if (err) {
reportFWUpdateThroughTwin(twin, {
status: 'applyFailed',
error: {
code: err.error_code,
message: err.error_message,
}
});
} else {
reportFWUpdateThroughTwin(twin, {
status: 'applyComplete',
lastFirmwareUpdate: now.toISOString()
});

}
});

setTimeout(callback, 4000);

}, 4000);
}

11. Add the following function that handles the firmwareUpdate direct method and initiates the multi-stage
firmware update process:
var onFirmwareUpdate = function(request, response) {

// Respond the cloud app for the direct method

response.send(200, 'FirmwareUpdate started', function(err) {
if (!err) {
console.error('An error occured when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.');
}
});

// Get the parameter from the body of the method request

var fwPackageUri = request.payload.fwPackageUri;

// Obtain the device twin

client.getTwin(function(err, twin) {
if (err) {
console.error('Could not get device twin.');
} else {
console.log('Device twin acquired.');

// Start the multi-stage firmware update

waitToDownload(twin, fwPackageUri, function() {
downloadImage(twin, fwPackageUri, function(imageData) {
applyImage(twin, imageData, function() {});
});
});

}
});
}

12. Finally, add the following code that connects to your IoT hub:

client.open(function(err) {
if (err) {
console.error('Could not connect to IotHub client');
} else {
console.log('Client connected to IoT Hub. Waiting for firmwareUpdate direct method.');
}

client.onDeviceMethod('firmwareUpdate', onFirmwareUpdate);
});

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as an exponential backoff), as suggested in the MSDN article [Transient Fault Handling][lnk-transient-faults].

Run the apps

You are now ready to run the apps.
1. At the command prompt in the manageddevice folder, run the following command to begin listening for
the reboot direct method.

node dmpatterns_fwupdate_device.js

2. At the command prompt in the triggerfwupdateondevice folder, run the following command to trigger
the remote reboot and query for the device twin to find the last reboot time.

node dmpatterns_fwupdate_service.js

3. You see the device response to the direct method in the console.

Next steps
In this tutorial, you used a direct method to trigger a remote firmware update on a device and used the reported
properties to follow the progress of the firmware update.
To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and
broadcast jobs tutorial.
Use device management to initiate a device firmware
update (.NET/Node)
2/6/2017 • 9 min to read • Edit on GitHub

Introduction
In the Get started with device management tutorial, you saw how to use the device twin and direct methods
primitives to remotely reboot a device. This tutorial uses the same IoT Hub primitives and shows you how to do an
end-to-end simulated firmware update. This pattern is used in the firmware update implementation for the
Raspberry Pi device implementation sample.
This tutorial shows you how to:
Create a .NET console app that calls the firmwareUpdate direct method in the simulated device app through
your IoT hub.
Create a simulated device app that implements a firmwareUpdate direct method. This method initiates a
multi-stage process that waits to download the firmware image, downloads the firmware image, and finally
applies the firmware image. During each stage of the update, the device uses the reported properties to report
on progress.
At the end of this tutorial, you have a Node.js console device app and a .NET (C#) console back-end app:
dmpatterns_fwupdate_service.js, which calls a direct method in the simulated device app, displays the response,
and periodically (every 500ms) displays the updated reported properties.
TriggerFWUpdate, which connects to your IoT hub with the device identity created earlier, receives a
firmwareUpdate direct method, runs through a multi-state process to simulate a firmware update including:
waiting for the image download, downloading the new image, and finally applying the image.
To complete this tutorial, you need the following:
Microsoft Visual Studio 2015.
Node.js version 0.12.x or later,
Prepare your development environment describes how to install Node.js for this tutorial on either Windows or
Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of minutes.)
Follow the Get started with device management article to create your IoT hub and get your IoT Hub connection
string.

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free F1
tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure
to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the IoT
Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT Hub
developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device app
to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Trigger a remote firmware update on the device using a direct method

In this section, you create a .NET console app (using C#) that initiates a remote firmware update on a device. The
app uses a direct method to initiate the update and uses device twin queries to periodically get the status of the
active firmware update.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the
Console Application project template. Name the project TriggerFWUpdate.

2. In Solution Explorer, right-click the TriggerFWUpdate project, and then click Manage NuGet Packages.
3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select
Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure
downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.
4. Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

5. Add the following fields to the Program class. Replace the multiple placeholder values with the IoT Hub
connection string for the hub that you created in the previous section and the Id of your device.

static RegistryManager registryManager;

static string connString = "{iot hub connection string}";
static ServiceClient client;
static JobClient jobClient;
static string targetDevice = "{deviceIdForTargetDevice}";

6. Add the following method to the Program class:

public static async Task QueryTwinFWUpdateReported()

{
Twin twin = await registryManager.GetTwinAsync(targetDevice);
Console.WriteLine(twin.Properties.Reported.ToJson());
}

7. Add the following method to the Program class:

public static async Task StartFirmwareUpdate()

{
client = ServiceClient.CreateFromConnectionString(connString);
CloudToDeviceMethod method = new CloudToDeviceMethod("firmwareUpdate");
method.ResponseTimeout = TimeSpan.FromSeconds(30);
method.SetPayloadJson(
@"{
fwPackageUri : 'https://someurl'
}");

CloudToDeviceMethodResult result = await client.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

}
8. Finally, add the following lines to the Main method:

registryManager = RegistryManager.CreateFromConnectionString(connString);
StartFirmwareUpdate().Wait();
QueryTwinFWUpdateReported().Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

9. Build the solution.

Create a simulated device app

In this section, you:
Create a Node.js console app that responds to a direct method called by the cloud
Trigger a simulated firmware update
Use the reported properties to enable device twin queries to identify devices and when they last completed a
firmware update
1. Create an empty folder called manageddevice. In the manageddevice folder, create a package.json file
using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the manageddevice folder, run the following command to install the azure-
iot-device and azure-iot-device-mqtt Device SDK packages:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a dmpatterns_fwupdate_device.js file in the manageddevice folder.

4. Add the following 'require' statements at the start of the dmpatterns_fwupdate_device.js file:

'use strict';

var Client = require('azure-iot-device').Client;

var Protocol = require('azure-iot-device-mqtt').Mqtt;

5. Add a connectionString variable and use it to create a Client instance. Replace the
{yourdeviceconnectionstring} placeholder with the connection string you previously made a note of in the
"Create a device identity" section previously:

var connectionString = '{yourdeviceconnectionstring}';

var client = Client.fromConnectionString(connectionString, Protocol);

6. Add the following function that is used to update reported properties:

var reportFWUpdateThroughTwin = function(twin, firmwareUpdateValue) {
var patch = {
iothubDM : {
firmwareUpdate : firmwareUpdateValue
}
};

twin.properties.reported.update(patch, function(err) {
if (err) throw err;
console.log('twin state reported: ' + firmwareUpdateValue.status);
});
};

7. Add the following functions that simulate downloading and applying the firmware image:

var simulateDownloadImage = function(imageUrl, callback) {

var error = null;
var image = "[fake image data]";

console.log("Downloading image from " + imageUrl);

callback(error, image);
}

var simulateApplyImage = function(imageData, callback) {

var error = null;

if (!imageData) {
error = {message: 'Apply image failed because of missing image data.'};
}

callback(error);
}

8. Add the following function that updates the firmware update status through the reported properties to
waiting. Typically, devices are informed of an available update and an administrator defined policy causes
the device to start downloading and applying the update. This function is where the logic to enable that
policy should run. For simplicity, the sample deplays for four seconds before proceeding to download the
firmware image:

var waitToDownload = function(twin, fwPackageUriVal, callback) {

var now = new Date();

reportFWUpdateThroughTwin(twin, {
fwPackageUri: fwPackageUriVal,
status: 'waiting',
error : null,
startedWaitingTime : now.toISOString()
});
setTimeout(callback, 4000);
};

9. Add the following function that updates the firmware update status through the reported properties to
downloading. The function then simulates a firmware download and finally updates the firmware update
status to either downloadFailed or downloadComplete:
var downloadImage = function(twin, fwPackageUriVal, callback) {
var now = new Date();

reportFWUpdateThroughTwin(twin, {
status: 'downloading',
});

setTimeout(function() {
// Simulate download
simulateDownloadImage(fwPackageUriVal, function(err, image) {

if (err)
{
reportFWUpdateThroughTwin(twin, {
status: 'downloadfailed',
error: {
code: error_code,
message: error_message,
}
});
}
else {
reportFWUpdateThroughTwin(twin, {
status: 'downloadComplete',
downloadCompleteTime: now.toISOString(),
});

setTimeout(function() { callback(image); }, 4000);

}
});

}, 4000);
}

10. Add the following function that updates the firmware update status through the reported properties to
applying. The function then simulates applying the firmware image and finally updates the firmware
update status to either applyFailed or applyComplete:
var applyImage = function(twin, imageData, callback) {
var now = new Date();

reportFWUpdateThroughTwin(twin, {
status: 'applying',
startedApplyingImage : now.toISOString()
});

setTimeout(function() {

// Simulate apply firmware image

simulateApplyImage(imageData, function(err) {
if (err) {
reportFWUpdateThroughTwin(twin, {
status: 'applyFailed',
error: {
code: err.error_code,
message: err.error_message,
}
});
} else {
reportFWUpdateThroughTwin(twin, {
status: 'applyComplete',
lastFirmwareUpdate: now.toISOString()
});

}
});

setTimeout(callback, 4000);

}, 4000);
}

11. Add the following function that handles the firmwareUpdate direct method and initiates the multi-stage
firmware update process:
var onFirmwareUpdate = function(request, response) {

// Respond the cloud app for the direct method

response.send(200, 'FirmwareUpdate started', function(err) {
if (!err) {
console.error('An error occured when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.');
}
});

// Get the parameter from the body of the method request

var fwPackageUri = request.payload.fwPackageUri;

// Obtain the device twin

client.getTwin(function(err, twin) {
if (err) {
console.error('Could not get device twin.');
} else {
console.log('Device twin acquired.');

// Start the multi-stage firmware update

waitToDownload(twin, fwPackageUri, function() {
downloadImage(twin, fwPackageUri, function(imageData) {
applyImage(twin, imageData, function() {});
});
});

}
});
}

12. Finally, add the following code that connects to your IoT hub:

client.open(function(err) {
if (err) {
console.error('Could not connect to IotHub client');
} else {
console.log('Client connected to IoT Hub. Waiting for firmwareUpdate direct method.');
}

client.onDeviceMethod('firmwareUpdate', onFirmwareUpdate);
});

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as an exponential backoff), as suggested in the MSDN article [Transient Fault Handling][lnk-transient-faults].

Run the apps

You are now ready to run the apps.
1. At the command prompt in the manageddevice folder, run the following command to begin listening for
the reboot direct method.

node dmpatterns_fwupdate_device.js

2. In Visual Studio, right-click on the TriggerFWUpdate projectRun to the C# console app, select Debug and
Start new instance.
3. You see the device response to the direct method in the console.

Next steps
In this tutorial, you used a direct method to trigger a remote firmware update on a device and used the reported
properties to follow the progress of the firmware update.
To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and
broadcast jobs tutorial.
Schedule and broadcast jobs (Node)
1/17/2017 • 8 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables a back-end app to create and track jobs that schedule and
update millions of devices. Jobs can be used for the following actions:
Update desired properties
Update tags
Invoke direct methods
Conceptually, a job wraps one of these actions and tracks the progress of execution against a set of devices,
which is defined by a device twin query. For example, a back-end app can use a job to invoke a reboot method on
10,000 devices, specified by a device twin query and scheduled at a future time. That application can then track
progress as each of those devices receive and execute the reboot method.
Learn more about each of these capabilities in these articles:
Device twin and properties: Get started with device twins and Tutorial: How to use device twin properties
direct methods: IoT Hub developer guide - direct methods and Tutorial: direct methods
This tutorial shows you how to:
Create a simulated device app that has a direct method which enables lockDoor which can be called by the
solution back end.
Create a Node.js console app that calls the lockDoor direct method in the simulated device app using a job
and updates the desired properties using a device job.
At the end of this tutorial, you have two Node.js console apps:
simDevice.js, which connects to your IoT hub with the device identity and receives a lockDoor direct method.
scheduleJobService.js, which calls a direct method in the simulated device app and update the device twin's
desired properties using a job.
To complete this tutorial, you need the following:
Node.js version 0.12.x or later,
Prepare your development environment describes how to install Node.js for this tutorial on either Windows
or Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of
minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete
this task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check
mark appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free
F1 tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for
Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in
the Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access
policies.

6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the
IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT
Hub developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device
app to connect to your IoT Hub as a device.

Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Create a simulated device app

In this section, you create a Node.js console app that responds to a direct method called by the cloud, which
triggers a simulated device reboot and uses the reported properties to enable device twin queries to identify
devices and when they last rebooted.
1. Create a new empty folder called simDevice. In the simDevice folder, create a package.json file using the
following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the simDevice folder, run the following command to install the azure-iot-
device Device SDK package and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new simDevice.js file in the simDevice folder.
4. Add the following 'require' statements at the start of the simDevice.js file:

'use strict';

var Client = require('azure-iot-device').Client;

var Protocol = require('azure-iot-device-mqtt').Mqtt;

5. Add a connectionString variable and use it to create a Client instance.

var connectionString = 'HostName={youriothostname};DeviceId={yourdeviceid};SharedAccessKey=

{yourdevicekey}';
var client = Client.fromConnectionString(connectionString, Protocol);

6. Add the following function to handle the lockDoor method.

var onLockDoor = function(request, response) {

// Respond the cloud app for the direct method

response.send(200, function(err) {
if (!err) {
console.error('An error occured when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.');
}
});

console.log('Locking Door!');
};

7. Add the following code to register the handler for the lockDoor method.

client.open(function(err) {
if (err) {
console.error('Could not connect to IotHub client.');
} else {
console.log('Client connected to IoT Hub. Register handler for lockDoor direct method.');
client.onDeviceMethod('lockDoor', onLockDoor);
}
});

8. Save and close the simDevice.js file.

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as an exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Schedule jobs for calling a direct method and updating a device twin's
properties
In this section, you create a Node.js console app that initiates a remote lockDoor on a device using a direct
method and update the device twin's properties.
1. Create a new empty folder called scheduleJobService. In the scheduleJobService folder, create a
package.json file using the following command at your command prompt. Accept all the defaults:

npm init

2. At your command prompt in the scheduleJobService folder, run the following command to install the
azure-iothub Device SDK package and azure-iot-device-mqtt package:

npm install azure-iothub uuid --save

3. Using a text editor, create a new scheduleJobService.js file in the scheduleJobService folder.
4. Add the following 'require' statements at the start of the
dmpatterns_gscheduleJobServiceetstarted_service.js file:
'use strict';

var uuid = require('uuid');

var JobClient = require('azure-iothub').JobClient;

5. Add the following variable declarations and replace the placeholder values:

var connectionString = '{iothubconnectionstring}';

var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds = 3600;
var jobClient = JobClient.fromConnectionString(connectionString);

6. Add the following function that will be used to monitor the execution of the job:

function monitorJob (jobId, callback) {

var jobMonitorInterval = setInterval(function() {
jobClient.getJob(jobId, function(err, result) {
if (err) {
console.error('Could not get job status: ' + err.message);
} else {
console.log('Job: ' + jobId + ' - status: ' + result.status);
if (result.status === 'completed' || result.status === 'failed' || result.status ===
'cancelled') {
clearInterval(jobMonitorInterval);
callback(null, result);
}
}
});
}, 5000);
}

7. Add the following code to schedule the job that calls the device method:

var methodParams = {
methodName: 'lockDoor',
payload: null,
responseTimeoutInSeconds: 15 // Timeout after 15 seconds if device is unable to process method
};

var methodJobId = uuid.v4();

console.log('scheduling Device Method job with id: ' + methodJobId);
jobClient.scheduleDeviceMethod(methodJobId,
queryCondition,
methodParams,
startTime,
maxExecutionTimeInSeconds,
function(err) {
if (err) {
console.error('Could not schedule device method job: ' + err.message);
} else {
monitorJob(methodJobId, function(err, result) {
if (err) {
console.error('Could not monitor device method job: ' + err.message);
} else {
console.log(JSON.stringify(result, null, 2));
}
});
}
});
8. Add the following code to schedule the job to update the device twin:

var twinPatch = {
etag: '*',
desired: {
building: '43',
floor: 3
}
};

var twinJobId = uuid.v4();

console.log('scheduling Twin Update job with id: ' + twinJobId);

jobClient.scheduleTwinUpdate(twinJobId,
queryCondition,
twinPatch,
startTime,
maxExecutionTimeInSeconds,
function(err) {
if (err) {
console.error('Could not schedule twin update job: ' + err.message);
} else {
monitorJob(twinJobId, function(err, result) {
if (err) {
console.error('Could not monitor twin update job: ' + err.message);
} else {
console.log(JSON.stringify(result, null, 2));
}
});
}
});

9. Save and close the scheduleJobService.js file.

Run the applications

You are now ready to run the applications.
1. At the command prompt in the simDevice folder, run the following command to begin listening for the
reboot direct method.

node simDevice.js

2. At the command prompt in the scheduleJobService folder, run the following command to trigger the
jobs to lock the door and update the twin

node scheduleJobService.js

3. You see the device response to the direct method in the console.

Next steps
In this tutorial, you used a job to schedule a direct method to a device and the update of the device twin's
properties.
To continue getting started with IoT Hub and device management patterns such as remote over the air firmware
update, see:
Tutorial: How to do a firmware update
To continue getting started with IoT Hub, see Getting started with the IoT Gateway SDK.
Schedule and broadcast jobs
1/17/2017 • 7 min to read • Edit on GitHub

Introduction
Azure IoT Hub is a fully managed service that enables an back-end app to create and track jobs that schedule and
update millions of devices. Jobs can be used for the following actions:
Update desired properties
Update tags
Invoke direct methods
Conceptually, a job wraps one of these actions and tracks the progress of execution against a set of devices, which
is defined by a device twin query. For example, using a job an back-end app can invoke a reboot method on 10,000
devices, specified by a device twin query and scheduled at a future time. That application can then track progress as
each of those devices receive and execute the reboot method.
Learn more about each of these capabilities in these articles:
Device twin and properties: Get started with device twins and Tutorial: How to use device twin properties
direct methods: IoT Hub developer guide - direct methods and Tutorial: Use direct methods
This tutorial shows you how to:
Create a simulated device app that has a direct method which enables lockDoor which can be called by the
back-end app.
Create a .NET console app that calls the lockDoor direct method in the simulated device app using a job and
updates the desired properties using a device job.
At the end of this tutorial, you have a Node.js console device app and a .NET (C#) console back-end app:
simDevice.js, which connects to your IoT hub with the device identity and receives a lockDoor direct method.
ScheduleJob, which calls a direct method in the simulated device app and updates the device twin's desired
properties using a job.
To complete this tutorial, you need the following:
Microsoft Visual Studio 2015.
Node.js version 0.12.x or later,
Prepare your development environment describes how to install Node.js for this tutorial on either Windows or
Linux.
An active Azure account. (If you don't have an account, you can create a free account in just a couple of minutes.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this
task by using the Azure portal.
1. Sign in to the Azure portal.
2. In the Jumpbar, click New > Internet of Things > IoT Hub.
3. In the IoT hub blade, choose the configuration for your IoT hub.
In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark
appears in the Name box.
Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free F1
tier.
In Resource group, either create a resource group, or select an existing one. For more information, see
Using resource groups to manage your Azure resources.
In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure
to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the
Notifications panel.

5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to
open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.
6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the IoT
Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT Hub
developer guide."

Create a device identity

In this section, you use a Node.js tool called IoT Hub Explorer to create a device identity for this tutorial.
1. Run the following in your command-line environment:
npm install -g iothub-explorer@latest
2. Then, run the following command to login to your hub, remembering to substitute
{iot hub connection string} with the IoT Hub connection string you previously copied:

iothub-explorer login "{iot hub connection string}"

3. Finally, create a new device identity called myDeviceId with the command:
iothub-explorer create myDeviceId --connection-string
Make a note of the device connection string from the result. This device connection string is used by the device app
to connect to your IoT Hub as a device.
Refer to Getting started with IoT Hub for a way to create device identities programmatically.

Schedule jobs for calling a direct method and updating a device twin's
properties
In this section, you create a .NET console app (using C#) that initiates a remote lockDoor on a device using a direct
method and update the device twin's properties.
1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the
Console Application project template. Name the project ScheduleJob.

2. In Solution Explorer, right-click the ScheduleJob project, and then click Manage NuGet Packages.
3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select
Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure
downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.
4. Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices;

5. Add the following fields to the Program class. Replace the placeholder with the IoT Hub connection string
for the hub that you created in the previous section.

static string connString = "{iot hub connection string}";

static ServiceClient client;
static JobClient jobClient;

6. Add the following method to the Program class:

public static async Task MonitorJob(string jobId)

{
JobResponse result;
do
{
result = await jobClient.GetJobAsync(jobId);
Console.WriteLine("Job Status : " + result.Status.ToString());
Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));
}

7. Add the following method to the Program class:

public static async Task StartMethodJob(string jobId)
{
CloudToDeviceMethod directMethod = new CloudToDeviceMethod("lockDoor", TimeSpan.FromSeconds(5),
TimeSpan.FromSeconds(5));

JobResponse result = await jobClient.ScheduleDeviceMethodAsync(jobId,

"SELECT * from DEVICES",
directMethod,
DateTime.Now,
10);

Console.WriteLine("Started Method Job");

}

8. Add the following method to the Program class:

public static async Task StartTwinUpdateJob(string jobId)

{
var twin = new Twin();
twin.Properties.Desired["Building"] = "43";
twin.Properties.Desired["Floor"] = "3";
twin.ETag = "*";

JobResponse result = await jobClient.ScheduleTwinUpdateAsync(jobId,

"SELECT * from DEVICES",
twin,
DateTime.Now,
10);

Console.WriteLine("Started Twin Update Job");

}

9. Finally, add the following lines to the Main method:

jobClient = JobClient.CreateFromConnectionString(connString);

string methodJobId = Guid.NewGuid().ToString();

StartMethodJob(methodJobId);
MonitorJob(methodJobId).Wait();
Console.WriteLine("Press ENTER to run the next job.");
Console.ReadLine();

string twinUpdateJobId = Guid.NewGuid().ToString();

StartTwinUpdateJob(twinUpdateJobId);
MonitorJob(twinUpdateJobId).Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

10. Build the solution.

Create a simulated device app

In this section, you create a Node.js console app that responds to a direct method called by the cloud, which triggers
a simulated device reboot and uses the reported properties to enable device twin queries to identify devices and
when they last rebooted.
1. Create a new empty folder called simDevice. In the simDevice folder, create a package.json file using the
following command at your command prompt. Accept all the defaults:
npm init

2. At your command prompt in the simDevice folder, run the following command to install the azure-iot-
device Device SDK package and azure-iot-device-mqtt package:

npm install azure-iot-device azure-iot-device-mqtt --save

3. Using a text editor, create a new simDevice.js file in the simDevice folder.
4. Add the following 'require' statements at the start of the simDevice.js file:

'use strict';

var Client = require('azure-iot-device').Client;

var Protocol = require('azure-iot-device-mqtt').Mqtt;

5. Add a connectionString variable and use it to create a Client instance.

var connectionString = 'HostName={youriothostname};DeviceId={yourdeviceid};SharedAccessKey=

{yourdevicekey}';
var client = Client.fromConnectionString(connectionString, Protocol);

6. Add the following function to handle the lockDoor method.

var onLockDoor = function(request, response) {

// Respond the cloud app for the direct method

response.send(200, function(err) {
if (!err) {
console.error('An error occured when sending a method response:\n' + err.toString());
} else {
console.log('Response to method \'' + request.methodName + '\' sent successfully.');
}
});

console.log('Locking Door!');
};

7. Add the following code to register the handler for the lockDoor method.

client.open(function(err) {
if (err) {
console.error('Could not connect to IotHub client.');
} else {
console.log('Client connected to IoT Hub. Waiting for lockDoor direct method.');
client.onDeviceMethod('lockDoor', onLockDoor);
}
});

8. Save and close the simDevice.js file.

NOTE
To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry
policies (such as an exponential backoff), as suggested in the MSDN article Transient Fault Handling.
Run the apps
You are now ready to run the apps.
1. At the command prompt in the simDevice folder, run the following command to begin listening for the
reboot direct method.

node simDevice.js

2. Run the C# console app ScheduleJob- right click on the ScheduleJob project, select Debug and Start new
instance.
3. You see the output from both device and back-end apps.

Next steps
In this tutorial, you used a job to schedule a direct method to a device and the update of the device twin's
properties.
To continue getting started with IoT Hub and device management patterns such as remote over the air firmware
update, see:
Tutorial: How to do a firmware update
To continue getting started with IoT Hub, see Getting started with the IoT Gateway SDK.
Create an IoT hub using the Azure portal
1/31/2017 • 7 min to read • Edit on GitHub

Introduction
This article describes how to find the IoT Hub service in the Azure portal, and how to create and manage IoT hubs.

Where to find IoT hubs

There are various places where you can find IoT hubs.
1. + New: Azure IoT Hub is an IoT service, and can be found in the category Internet of Things, under + New,
similar to other services.
2. IoT hubs can also be accessed through the Marketplace as the hero service under Internet of Things.

Create an IoT hub

You can create an IoT hub using the following methods:
Creating an IoT hub through the + New option leads to the blade shown in the next screen shot. The steps for
creating the IoT hub through this method and through the marketplace are identical.
Creating an IoT hub through the Marketplace: Clicking Create opens a blade that is identical to the previous
blade for the +New experience. The next sections list the several steps involved in creating an IoT hub.
Choose the name of the IoT hub
To create an IoT hub, you must name the IoT hub. This name must be unique across the IoT hubs. No duplication
of hubs is allowed on the solution back end, so it is recommended that this hub is named as uniquely as possible.
Choose the pricing tier
You can choose from four tiers: Free, Standard 1 and Standard 2, and Standard S3. The free tier allows only
500 devices to be connected to the IoT hub and up to 8,000 messages per day.
Standard S1: IoT Hubs S1 edition is designed for IoT solutions that have a large number of devices generating
relatively small amounts of data per device. Each unit of the S1 edition allows up to 400,000 messages per day
across all connected devices.
Standard S2: IoT Hub S2 edition is designed for IoT solutions in which devices generate large amounts of data.
Each unit of the S2 edition allows up to 6 million messages per day between all connected devices.
Standard S3: IoT Hub S3 edition is designed for IoT solutions that generate large amounts of data. Each unit of
the S3 edition allows up to 300 million messages per day between all connected devices.
NOTE
IoT Hub only allows one free hub per Azure subscription.

IoT hub units

The number of messages allowed per unit per day depends on your hub's pricing tier. For example, if you want
the IoT hub to support ingress of 700,000 messages, you choose two S1 tier units.
Device to cloud partitions and resource group
You can change the number of partitions for an IoT hub. Default partitions are set to 4; however, you can choose a
different number of partitions from a drop-down list.
For resource groups, you do not need to explicitly create an empty resource group. When creating a resource, you
can choose to either create a new resource group or use an existing resource group.
Choose subscriptions
Azure IoT Hub automatically shows the list of Azure subscriptions to which the user account is linked. You can
choose one of the options here to associate the IoT hub with that Azure subscription.
Choose the location
The location option provides a list of the regions in which IoT Hub is offered. IoT Hub is available to deploy in the
following locations: Australia East, Australia Southeast, Asia East, Asia Southeast, Europe North, Europe West,
Japan East, Japan West, US East, US West.
Create the IoT hub
When all previous steps are complete, the IoT hub is ready to be created. Click Create to start the back-end
process of creating this IoT hub with the specific options, and to deploy it to the location specified.
It can take a few minutes for the IoT hub to be created as it takes time for the back-end deployment to occur in the
appropriate location servers.

Change the settings of the IoT hub

You can change the settings of an existing IoT hub after it is created from the IoT Hub blade.

Shared access policies: These policies define the permissions for devices and services to connect to IoT Hub. You
can access these policies by clicking Shared access policies under General. In this blade, you can either modify
existing policies or add a new policy.
Create a policy
Click Add to open a blade. Here you can enter the new policy name and the permissions that you want to
associate with this policy, as shown in the following figure:
There are several permissions that can be associated with these shared policies. The first two policies,
Registry read and Registry write, grant read and write access rights to the device identity store or the
identity registry. Choosing the write option automatically chooses the read option as well.
The Service connect policy grants permission to access the cloud-side endpoints such as the consumer
group for services connecting to the IoT hub. The Device connect policy grants permissions for sending
and receiving messages on the device-side endpoints of the IoT hub.
Click Create to add this newly created policy to the existing list.

Endpoints
Click Endpoints to display a list of endpoints for the IoT hub that you are modifying. There are two types of
endpoints: endpoints that are built into the IoT hub, and endpoints that you add to the IoT hub after its creation.

Built-in endpoints
There are two built-in endpoints: Cloud to device feedback and Events.
Cloud to device feedback settings: This setting has two subsettings: Cloud to Device TTL (time-to-live) and
Retention time (in hours) for the messages. When your first create an IoT hub, both these settings have the
default value of one hour. To adjust these settings, use the sliders or type the values.
Events settings: This setting has several subsettings, some of which are read-only. The following list
describes these settings:
Partitions: A default value is set when the IoT hub is created. You can change the number of
partitions through this setting.
Event Hub-compatible name and endpoint: When the IoT hub is created, an Event Hub is
created internally that you may need access to under certain circumstances. You cannot customize
the Event Hub-compatible name and endpoint values but you can copy them by clicking Copy.
Retention Time: Set to one day by default but you can change it using the drop-down list. This
value is in days for the device-to-cloud setting.
Consumer Groups: Consumer groups are a setting similar to other messaging systems that can be
used to pull data in specific ways to connect other applications or services to IoT Hub. Every IoT hub
is created with a default consumer group. However, you can add or delete consumer groups to your
IoT hubs using this setting.

NOTE
The default consumer group cannot be edited or deleted.

Custom endpoints
You can add custom endpoints on your IoT hub using the portal. From the Endpoints blade, click Add at the top
to open the Add endpoint blade. Enter the required information, then click OK. Your custom endpoint is now
listed in the main Endpoints blade.
You can read more about custom endpoints in Reference - IoT hub endpoints.

Routes
Click Routes to manage how IoT Hub dispatches your device-to-cloud messages.
You can add routes to your IoT hub by clicking Add at the top of the Routes* blade, entering the required
information, and clicking OK. Your route is then listed in the main Routes blade. You can edit a route by clicking it
in the list of routes. To enable a route, click it in the list of routes and set the Enabled toggle to Off. Click OK at
the bottom of the blade to save the change.

Pricing and scale

The pricing of an existing IoT hub can be changed through the Pricing settings, with the following exceptions:
In the current implementation, an IoT hub with a free SKU cannot change tiers to one of the paid SKUs, or vice
versa.
There can only be one free tier IoT hub in the Azure subscription.
Moving from a higher tier (S2 or S3) to lower tier (S1 or S2) is allowed only when the number of messages sent
for that day are not in conflict. For example, if the number of messages per day exceeds 400,000, then the tier for
the IoT hub can be changed. However, if you change to the S1 tier then the IoT hub is throttled for that day.

Delete the IoT hub

You can browse to the IoT hub you want to delete by clicking Browse, and then choosing the appropriate hub to
delete. Click the Delete button below the IoT hub name to delete the IoT hub.

Next steps
Follow these links to learn more about managing Azure IoT Hub:
Bulk manage IoT devices
IoT Hub metrics
Operations monitoring
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
Secure your IoT solution from the ground up
Create an IoT hub using the Azure CLI 2.0 (Preview)
1/17/2017 • 2 min to read • Edit on GitHub

Introduction
You can use Azure CLI 2.0 (Preview) (az.py) to create and manage Azure IoT hubs programmatically. This article
shows you how to use the Azure CLI 2.0 (Preview) (az.py) to create an IoT hub.
You can complete the task using one of the following CLI versions:
Azure CLI (azure.js) – the CLI for the classic and resource management deployment models.
Azure CLI 2.0 (Preview) (az.py) - the next generation CLI for the resource management deployment model as
described in this article.
To complete this tutorial, you need the following:
An active Azure account. If you don't have an account, you can create a free account in just a couple of minutes.
Azure CLI 2.0 (Preview).

Sign in and set your Azure account

Sign in to your Azure account and configure the Azure CLI to work with IoT Hub resources.
1. At the command prompt, run the login command:

az login

Follow the instructions to authenticate using the code and sign in to your Azure account through a web
browser.
2. If you have multiple Azure subscriptions, signing in to Azure grants you access to all the Azure accounts
associated with your credentials. Use the following command to list the Azure accounts available for you to
use:

az account list

Use the following command to select subscription that you want to use to run the commands to create your
IoT hub. You can use either the subscription name or ID from the output of the previous command:

az account set --subscription {your subscription name or id}

3. Install the Azure CLI iot component. Run the following command to add the iot component:

az component update --add iot

4. Register the IoT provider before you can deploy IoT resources. Run the following command to register the
IoT provider:
az provider register -namespace Microsoft.Devices

Create an IoT Hub

Use the Azure CLI to create a resource group and then add an IoT hub.
1. When you create an IoT hub, you must create it in a resource group. Either use an existing resource group,
or run the following command to create a resource group:

az group create --name {your resource group name} --location westus

TIP
The previous example creates the resource group in the West US location. You can view a list of available locations
by running the command az account list-locations -o table .

2. Run the following command to create an IoT hub in your resource group:

az iot hub create --name {your iot hub name} --resource-group {your resource group name} --sku S1

NOTE
The name of your IoT hub must be globally unique. The previous command creates an IoT hub in the S1 pricing tier for
which you are billed. For more information, see Azure IoT Hub pricing.

Remove an IoT Hub

You can use the Azure CLI to delete an individual resource, such as an IoT hub, or delete a resource group and all
its resources, including any IoT hubs.
To delete an IoT hub, run the following command:

az resource delete --name {your iot hub name} --resource-group {your resource group name} --resource-type
Microsoft.Devices/IotHubs

To delete a resource group and all its resources, run the following command:

az group delete --name {your resource group name}

Next steps
To learn more about developing for IoT Hub, see the following articles:
IoT Hub developer guide
To further explore the capabilities of IoT Hub, see:
Using the Azure portal to manage IoT Hub
Create an IoT hub using the Azure CLI
1/17/2017 • 2 min to read • Edit on GitHub

Introduction
You can use Azure CLI (azure.js) to create and manage Azure IoT hubs programmatically. This article shows you
how to use the Azure CLI (azure.js) to create an IoT hub.
You can complete the task using one of the following CLI versions:
Azure CLI (azure.js) – the CLI for the classic and resource management deployment models as described in this
article.
Azure CLI 2.0 (Preview) (az.py) - the next generation CLI for the resource management deployment model.
To complete this tutorial, you need the following:
An active Azure account. If you don't have an account, you can create a free account in just a couple of minutes.
Azure CLI 0.10.4 or later. If you already have the Azure CLI installed, you can validate the current version at the
command prompt with the following command: azure --version

NOTE
Azure has two different deployment models for creating and working with resources: Azure Resource Manager and classic.
The Azure CLI must be in Azure Resource Manager mode:

azure config mode arm

Set your Azure account and subscription

1. At the command prompt, login by typing the following command:

azure login

Use the suggested web browser and code to authenticate.

2. If you have multiple Azure subscriptions, connecting to Azure grants you access to all the Azure
subscriptions associated with your credentials. You can view the Azure subscriptions, and identify which
one is the default, using the command:

azure account list

To set the subscription context under which you want to run the rest of the commands use:

azure account set <subscription name>

3. If you do not have a resource group, you can create one named exampleResourceGroup:
azure group create -n exampleResourceGroup -l westus

TIP
The article Use the Azure CLI to manage Azure resources and resource groups provides more information about how to use
the Azure CLI to manage Azure resources.

Create an IoT Hub

Required parameters:

azure iothub create -g <resource-group> -n <name> -l <location> -s <sku-name> -u <units>

- <resourceGroup> The resource group name (case insensitive alphanumeric, underscore and hyphen, 1-64
length)
- <name> (The name of the IoT hub to be created. The format is case insensitive alphanumeric, underscore
and hyphen, 3-50 length )
- <location> (The location (azure region/datacenter) where the IoT hub will be provisioned.
- <sku-name> (The name of the sku, one of: [F1, S1, S2, S3] etc. For the latest full list refer to the
pricing page for IoT Hub.
- <units> (The number of provisioned units. Range : F1 [1-1] : S1, S2 [1-200] : S3 [1-10]. IoT Hub units
are based on your total message count and the number of devices you want to connect.)

To see all the parameters available for creation, you can use the help command in command prompt:

azure iothub create -h

Quick example:
To create an IoT Hub called exampleIoTHubName in the resource group exampleResourceGroup, run the
following command:

azure iothub create -g exampleResourceGroup -n exampleIoTHubName -l westus -k s1 -u 1

NOTE
This Azure CLI command creates an S1 Standard IoT Hub for which you are billed. You can delete the IoT hub
exampleIoTHubName using following command:

azure iothub delete -g exampleResourceGroup -n exampleIoTHubName

Next steps
To learn more about developing for IoT Hub, see the following:
IoT SDKs
To further explore the capabilities of IoT Hub, see:
Using the Azure portal to manage IoT Hub
Create an IoT hub using the resource provider REST
API (.NET)
2/9/2017 • 6 min to read • Edit on GitHub

Introduction
You can use the IoT Hub resource provider REST API to create and manage Azure IoT hubs programmatically. This
tutorial shows you how to use the IoT Hub resource provider REST API to create an IoT hub from a C# program.

NOTE
Azure has two different deployment models for creating and working with resources: Azure Resource Manager and classic.
This article covers using the Azure Resource Manager deployment model.

To complete this tutorial, you need the following:

Microsoft Visual Studio 2015.
An active Azure account.
If you don't have an account, you can create a free account in just a couple of minutes.
Azure PowerShell 1.0 or later.

Prepare to authenticate Azure Resource Manager requests

You must authenticate all the operations that you perform on resources using the Azure Resource Manager with
Azure Active Directory (AD). The easiest way to configure this is to use PowerShell or Azure CLI.
You should install Azure PowerShell 1.0 or later before you continue.
The following steps show how to set up password authentication for an AD application using PowerShell. You can
run these commands in a standard PowerShell session.
1. Log in to your Azure subscription using the following command:

Login-AzureRmAccount

2. Make a note of your TenantId and SubscriptionId. You will need them later.
3. Create a new Azure Active Directory application using the following command, replacing the place holders:
{Display name}: a display name for your application such as MySampleApp
{Home page URL}: the URL of the home page of your app such as http://mysampleapp/home. This
URL does not need to point to a real application.
{Application identifier}: A unique identifier such as http://mysampleapp. This URL does not need to
point to a real application.
{Password}: A password that you will use to authenticate with your app.

New-AzureRmADApplication -DisplayName {Display name} -HomePage {Home page URL} -IdentifierUris

{Application identifier} -Password {Password}

4. Make a note of the ApplicationId of the application you created. You will need this later.
5. Create a new service principal using the following command, replacing {MyApplicationId} with the
ApplicationId from the previous step:

New-AzureRmADServicePrincipal -ApplicationId {MyApplicationId}

6. Setup a role assignment using the following command, replacing {MyApplicationId} with your
ApplicationId.

New-AzureRmRoleAssignment -RoleDefinitionName Owner -ServicePrincipalName {MyApplicationId}

You have now finished creating the Azure AD application that will enable you to authenticate from your custom C#
application. You will need the following values later in this tutorial:
TenantId
SubscriptionId
ApplicationId
Password

Prepare your Visual Studio project

1. In Visual Studio, create a Visual C# Windows project using the Console Application project template. Name
the project CreateIoTHubREST.
2. In Solution Explorer, right-click on your project and then click Manage NuGet Packages.
3. In NuGet Package Manager, check Include prerelease, and search for
Microsoft.Azure.Management.ResourceManager. Click Install, in Review Changes click OK, then click I
Accept to accept the licenses.
4. In NuGet Package Manager, search for Microsoft.IdentityModel.Clients.ActiveDirectory. Click Install, in
Review Changes click OK, then click I Accept to accept the license.
5. In Program.cs, replace the existing using statements with the following code:

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Microsoft.Azure.Management.ResourceManager;
using Microsoft.Azure.Management.ResourceManager.Models;
using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Newtonsoft.Json;
using Microsoft.Rest;
using System.Linq;
using System.Threading;

6. In Program.cs, add the following static variables replacing the placeholder values. You made a note of
ApplicationId, SubscriptionId, TenantId, and Password earlier in this tutorial. Resource group name is
the name of the resource group you use when you create the IoT hub, it can be a pre-existing resource
group or a new one. IoT Hub name is the name of the IoT Hub you create, such as MyIoTHub (this name
must be globally unique, so it should include your name or initials). Deployment name is a name for the
deployment, such as Deployment_01.
static string applicationId = "{Your ApplicationId}";
static string subscriptionId = "{Your SubscriptionId}";
static string tenantId = "{Your TenantId}";
static string password = "{Your application Password}";

static string rgName = "{Resource group name}";

static string iotHubName = "{IoT Hub name including your initials}";

Obtain an Azure Resource Manager token

Azure Active Directory must authenticate all the tasks that you perform on resources using the Azure Resource
Manager. The example shown here uses password authentication, for other approaches see Authenticating Azure
Resource Manager requests.
1. Add the following code to the Main method in Program.cs to retrieve a token from Azure AD using the
application id and password.

var authContext = new AuthenticationContext(string.Format

("https://login.windows.net/{0}", tenantId));
var credential = new ClientCredential(applicationId, password);
AuthenticationResult token = authContext.AcquireTokenAsync
("https://management.core.windows.net/", credential).Result;

if (token == null)
{
Console.WriteLine("Failed to obtain the token");
return;
}

2. Create a ResourceManagementClient object that uses the token by adding the following code to the end
of the Main method:

var creds = new TokenCredentials(token.AccessToken);

var client = new ResourceManagementClient(creds);
client.SubscriptionId = subscriptionId;

3. Create, or obtain a reference to, the resource group you are using:

var rgResponse = client.ResourceGroups.CreateOrUpdate(rgName,

new ResourceGroup("East US"));
if (rgResponse.Properties.ProvisioningState != "Succeeded")
{
Console.WriteLine("Problem creating resource group");
return;
}

Use the resource provider REST API to create an IoT hub

Use the IoT Hub resource provider REST API to create an IoT hub in your resource group. You can also use the
resource provider REST API to make changes to an existing IoT hub.
1. Add the following method to Program.cs:
static void CreateIoTHub(string token)
{

2. Add the following code to the CreateIoTHub method. This code creates an HttpClient object with the
authentication token in the headers:

HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

3. Add the following code to the CreateIoTHub method. This code describes the IoT hub to create and
generates a JSON representation. For the current list of locations that support IoT Hub see Azure Status:

var description = new

{
name = iotHubName,
location = "East US",
sku = new
{
name = "S1",
tier = "Standard",
capacity = 1
}
};

var json = JsonConvert.SerializeObject(description, Formatting.Indented);

4. Add the following code to the CreateIoTHub method. This code submits the REST request to Azure, checks
the response, and retrieves the URL you can use to monitor the state of the deployment task:

var content = new StringContent(JsonConvert.SerializeObject(description), Encoding.UTF8,

"application/json");
var requestUri =
string.Format("https://management.azure.com/subscriptions/{0}/resourcegroups/{1}/providers/Microsoft.de
vices/IotHubs/{2}?api-version=2016-02-03", subscriptionId, rgName, iotHubName);
var result = client.PutAsync(requestUri, content).Result;

if (!result.IsSuccessStatusCode)
{
Console.WriteLine("Failed {0}", result.Content.ReadAsStringAsync().Result);
return;
}

var asyncStatusUri = result.Headers.GetValues("Azure-AsyncOperation").First();

5. Add the following code to the end of the CreateIoTHub method. This code uses the asyncStatusUri
address retrieved in the previous step to wait for the deployment to complete:

string body;
do
{
Thread.Sleep(10000);
HttpResponseMessage deploymentstatus = client.GetAsync(asyncStatusUri).Result;
body = deploymentstatus.Content.ReadAsStringAsync().Result;
} while (body == "{\"status\":\"Running\"}");

6. Add the following code to the end of the CreateIoTHub method. This code retrieves the keys of the IoT hub
you created and prints them to the console:

var listKeysUri =
string.Format("https://management.azure.com/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.De
vices/IotHubs/{2}/IoTHubKeys/listkeys?api-version=2016-02-03", subscriptionId, rgName, iotHubName);
var keysresults = client.PostAsync(listKeysUri, null).Result;

Console.WriteLine("Keys: {0}", keysresults.Content.ReadAsStringAsync().Result);

Complete and run the application

You can now complete the application by calling the CreateIoTHub method before you build and run it.
1. Add the following code to the end of the Main method:

CreateIoTHub(token.AccessToken);
Console.ReadLine();

2. Click Build and then Build Solution. Correct any errors.

3. Click Debug and then Start Debugging to run the application. It may take several minutes for the deployment
to run.
4. You can verify that your application added the new IoT hub by visiting the Azure portal and viewing your list of
resources, or by using the Get-AzureRmResource PowerShell cmdlet.

NOTE
This example application adds an S1 Standard IoT Hub for which you are billed. When you are finished, you can delete the
IoT hub through the Azure portal or by using the Remove-AzureRmResource PowerShell cmdlet when you are finished.

Next steps
Now you have deployed an IoT hub using the resource provider REST API, you may want to explore further:
Read about the capabilities of the IoT Hub resource provider REST API.
Read Azure Resource Manager overview to learn more about the capabilities of Azure Resource Manager.
To learn more about developing for IoT Hub, see the following articles:
Introduction to C SDK
Azure IoT SDKs
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Create an IoT hub using Azure Resource Manager
template (PowerShell)
1/17/2017 • 3 min to read • Edit on GitHub

Introduction
You can use Azure Resource Manager to create and manage Azure IoT hubs programmatically. This tutorial shows
you how to use an Azure Resource Manager template to create an IoT hub with PowerShell.

NOTE
Azure has two different deployment models for creating and working with resources: Azure Resource Manager and classic.
This article covers using the Azure Resource Manager deployment model.

To complete this tutorial, you need the following:

An active Azure account.
If you don't have an account, you can create a free account in just a couple of minutes.
Azure PowerShell 1.0 or later.

TIP
The article Using Azure PowerShell with Azure Resource Manager provides more information about how to use PowerShell
scripts and Azure Resource Manager templates to create Azure resources.

Connect to your Azure subscription

In a PowerShell command prompt, enter the following command to sign in to your Azure subscription:

Login-AzureRmAccount

You can use the following commands to discover where you can deploy an IoT hub and the currently supported
API versions:

((Get-AzureRmResourceProvider -ProviderNamespace Microsoft.Devices).ResourceTypes | Where-Object

ResourceTypeName -eq IoTHubs).Locations
((Get-AzureRmResourceProvider -ProviderNamespace Microsoft.Devices).ResourceTypes | Where-Object
ResourceTypeName -eq IoTHubs).ApiVersions

Create a resource group to contain your IoT hub using the following command in one of the supported locations
for IoT Hub. This example creates a resource group called MyIoTRG1:

New-AzureRmResourceGroup -Name MyIoTRG1 -Location "East US"

Submit an Azure Resource Manager template to create an IoT hub

Use a JSON template to create an IoT hub in your resource group. You can also use an Azure Resource Manager
template to make changes to an existing IoT hub.
1. Use a text editor to create an Azure Resource Manager template called template.json with the following
resource definition to create a new standard IoT hub. This example adds the IoT Hub in the East US region,
creates two consumer groups (cg1 and cg2) on the Event Hub-compatible endpoint, and uses the 2016-
02-03 API version. This template also expects you to pass in the IoT hub name as a parameter called
hubName. For the current list of locations that support IoT Hub see Azure Status.

{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"hubName": {
"type": "string"
}
},
"resources": [
{
"apiVersion": "2016-02-03",
"type": "Microsoft.Devices/IotHubs",
"name": "[parameters('hubName')]",
"location": "East US",
"sku": {
"name": "S1",
"tier": "Standard",
"capacity": 1
},
"properties": {
"location": "East US"
}
},
{
"apiVersion": "2016-02-03",
"type": "Microsoft.Devices/IotHubs/eventhubEndpoints/ConsumerGroups",
"name": "[concat(parameters('hubName'), '/events/cg1')]",
"dependsOn": [
"[concat('Microsoft.Devices/Iothubs/', parameters('hubName'))]"
]
},
{
"apiVersion": "2016-02-03",
"type": "Microsoft.Devices/IotHubs/eventhubEndpoints/ConsumerGroups",
"name": "[concat(parameters('hubName'), '/events/cg2')]",
"dependsOn": [
"[concat('Microsoft.Devices/Iothubs/', parameters('hubName'))]"
]
}
],
"outputs": {
"hubKeys": {
"value": "[listKeys(resourceId('Microsoft.Devices/IotHubs', parameters('hubName')), '2016-02-
03')]",
"type": "object"
}
}
}

2. Save the Azure Resource Manager template file on your local machine. This example assumes you save it in a
folder called c:\templates.
3. Run the following command to deploy your new IoT hub, passing the name of your IoT hub as a parameter.
In this example, the name of the IoT hub is abcmyiothub (note that this name must be globally unique so
it should include your name or initials):
New-AzureRmResourceGroupDeployment -ResourceGroupName MyIoTRG1 -TemplateFile
C:\templates\template.json -hubName abcmyiothub

4. The output displays the keys for the IoT hub you created.
5. You can verify that your application added the new IoT hub by visiting the Azure portal and viewing your list of
resources, or by using the Get-AzureRmResource PowerShell cmdlet.

NOTE
This example application adds an S1 Standard IoT Hub for which you are billed. You can delete the IoT hub through the
Azure portal or by using the Remove-AzureRmResource PowerShell cmdlet when you are finished.

Next steps
Now you have deployed an IoT hub using an Azure Resource Manager template with PowerShell, you may want
to explore further:
Read about the capabilities of the IoT Hub resource provider REST API.
Read Azure Resource Manager overview to learn more about the capabilities of Azure Resource Manager.
To learn more about developing for IoT Hub, see the following:
Introduction to C SDK
Azure IoT SDKs
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Create an IoT hub using Azure Resource Manager
template (.NET)
2/9/2017 • 7 min to read • Edit on GitHub

Introduction
You can use Azure Resource Manager to create and manage Azure IoT hubs programmatically. This tutorial shows
you how to use an Azure Resource Manager template to create an IoT hub from a C# program.

NOTE
Azure has two different deployment models for creating and working with resources: Azure Resource Manager and classic.
This article covers using the Azure Resource Manager deployment model.

To complete this tutorial, you need the following:

Microsoft Visual Studio 2015.
An active Azure account.
If you don't have an account, you can create a free account in just a couple of minutes.
An Azure Storage account where you can store your Azure Resource Manager template files.
Azure PowerShell 1.0 or later.

Prepare to authenticate Azure Resource Manager requests

You must authenticate all the operations that you perform on resources using the Azure Resource Manager with
Azure Active Directory (AD). The easiest way to configure this is to use PowerShell or Azure CLI.
You should install Azure PowerShell 1.0 or later before you continue.
The following steps show how to set up password authentication for an AD application using PowerShell. You can
run these commands in a standard PowerShell session.
1. Log in to your Azure subscription using the following command:

Login-AzureRmAccount

2. Make a note of your TenantId and SubscriptionId. You will need them later.
3. Create a new Azure Active Directory application using the following command, replacing the place holders:
{Display name}: a display name for your application such as MySampleApp
{Home page URL}: the URL of the home page of your app such as http://mysampleapp/home. This
URL does not need to point to a real application.
{Application identifier}: A unique identifier such as http://mysampleapp. This URL does not need to
point to a real application.
{Password}: A password that you will use to authenticate with your app.

New-AzureRmADApplication -DisplayName {Display name} -HomePage {Home page URL} -IdentifierUris

{Application identifier} -Password {Password}
4. Make a note of the ApplicationId of the application you created. You will need this later.
5. Create a new service principal using the following command, replacing {MyApplicationId} with the
ApplicationId from the previous step:

New-AzureRmADServicePrincipal -ApplicationId {MyApplicationId}

6. Setup a role assignment using the following command, replacing {MyApplicationId} with your
ApplicationId.

New-AzureRmRoleAssignment -RoleDefinitionName Owner -ServicePrincipalName {MyApplicationId}

You have now finished creating the Azure AD application that will enable you to authenticate from your custom
C# application. You will need the following values later in this tutorial:
TenantId
SubscriptionId
ApplicationId
Password

Prepare your Visual Studio project

1. In Visual Studio, create a Visual C# Windows project using the Console Application project template. Name
the project CreateIoTHub.
2. In Solution Explorer, right-click on your project and then click Manage NuGet Packages.
3. In NuGet Package Manager, check Include prerelease, and search for
Microsoft.Azure.Management.ResourceManager. Click Install, in Review Changes click OK, then click I
Accept to accept the licenses.
4. In NuGet Package Manager, search for Microsoft.IdentityModel.Clients.ActiveDirectory. Click Install, in
Review Changes click OK, then click I Accept to accept the license.
5. In Program.cs, replace the existing using statements with the following code:

using System;
using Microsoft.Azure.Management.ResourceManager;
using Microsoft.Azure.Management.ResourceManager.Models;
using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;

6. In Program.cs, add the following static variables replacing the placeholder values. You made a note of
ApplicationId, SubscriptionId, TenantId, and Password earlier in this tutorial. Your Azure Storage
account name is the name of the Azure Storage account where you store your Azure Resource Manager
template files. Resource group name is the name of the resource group you use when you create the IoT
Hub, it can be a pre-existing resource group or a new one. Deployment name is a name for the
deployment, such as Deployment_01.

static string applicationId = "{Your ApplicationId}";

static string subscriptionId = "{Your SubscriptionId}";
static string tenantId = "{Your TenantId}";
static string password = "{Your application Password}";
static string storageAddress = "https://{Your storage account name}.blob.core.windows.net";
static string rgName = "{Resource group name}";
static string deploymentName = "{Deployment name}";
Obtain an Azure Resource Manager token
Azure Active Directory must authenticate all the tasks that you perform on resources using the Azure Resource
Manager. The example shown here uses password authentication, for other approaches see Authenticating Azure
Resource Manager requests.
1. Add the following code to the Main method in Program.cs to retrieve a token from Azure AD using the
application id and password.

var authContext = new AuthenticationContext(string.Format

("https://login.windows.net/{0}", tenantId));
var credential = new ClientCredential(applicationId, password);
AuthenticationResult token = authContext.AcquireTokenAsync
("https://management.core.windows.net/", credential).Result;

if (token == null)
{
Console.WriteLine("Failed to obtain the token");
return;
}

2. Create a ResourceManagementClient object that uses the token by adding the following code to the end
of the Main method:

var creds = new TokenCredentials(token.AccessToken);

var client = new ResourceManagementClient(creds);
client.SubscriptionId = subscriptionId;

3. Create, or obtain a reference to, the resource group you are using:

var rgResponse = client.ResourceGroups.CreateOrUpdate(rgName,

new ResourceGroup("East US"));
if (rgResponse.Properties.ProvisioningState != "Succeeded")
{
Console.WriteLine("Problem creating resource group");
return;
}

Submit an Azure Resource Manager template to create an IoT hub

Use a JSON template and parameter file to create an IoT hub in your resource group. You can also use an Azure
Resource Manager template to make changes to an existing IoT hub.
1. In Solution Explorer, right-click on your project, click Add, and then click New Item. Add a JSON file called
template.json to your project.
2. Replace the contents of template.json with the following resource definition to add a standard IoT hub to
the East US region. For the current list of regions that support IoT Hub see Azure Status:
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"hubName": {
"type": "string"
}
},
"resources": [
{
"apiVersion": "2016-02-03",
"type": "Microsoft.Devices/IotHubs",
"name": "[parameters('hubName')]",
"location": "East US",
"sku": {
"name": "S1",
"tier": "Standard",
"capacity": 1
},
"properties": {
"location": "East US"
}
}
],
"outputs": {
"hubKeys": {
"value": "[listKeys(resourceId('Microsoft.Devices/IotHubs', parameters('hubName')), '2016-02-
03')]",
"type": "object"
}
}
}

3. In Solution Explorer, right-click on your project, click Add, and then click New Item. Add a JSON file called
parameters.json to your project.
4. Replace the contents of parameters.json with the following parameter information that sets a name for
the new IoT hub such as {your initials}mynewiothub. The IoT hub name must be globally unique so it
should include your name or initials:

{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"hubName": { "value": "mynewiothub" }
}
}

5. In Server Explorer, connect to your Azure subscription, and in your Azure Storage account create a container
called templates. In the Properties panel, set the Public Read Access permissions for the templates
container to Blob.
6. In Server Explorer, right-click on the templates container and then click View Blob Container. Click the
Upload Blob button, select the two files, parameters.json and templates.json, and then click Open to
upload the JSON files to the templates container. The URLs of the blobs containing the JSON data are:

https://{Your storage account name}.blob.core.windows.net/templates/parameters.json

https://{Your storage account name}.blob.core.windows.net/templates/template.json

7. Add the following method to Program.cs:

static void CreateIoTHub(ResourceManagementClient client)
{

8. Add the following code to the CreateIoTHub method to submit the template and parameter files to the
Azure Resource Manager:

var createResponse = client.Deployments.CreateOrUpdate(

rgName,
deploymentName,
new Deployment()
{
Properties = new DeploymentProperties
{
Mode = DeploymentMode.Incremental,
TemplateLink = new TemplateLink
{
Uri = storageAddress + "/templates/template.json"
},
ParametersLink = new ParametersLink
{
Uri = storageAddress + "/templates/parameters.json"
}
}
});

9. Add the following code to the CreateIoTHub method that displays the status and the keys for the new IoT
hub:

string state = createResponse.Properties.ProvisioningState;

Console.WriteLine("Deployment state: {0}", state);

if (state != "Succeeded")
{
Console.WriteLine("Failed to create iothub");
}
Console.WriteLine(createResponse.Properties.Outputs);

Complete and run the application

You can now complete the application by calling the CreateIoTHub method before you build and run it.
1. Add the following code to the end of the Main method:

CreateIoTHub(client);
Console.ReadLine();

2. Click Build and then Build Solution. Correct any errors.

3. Click Debug and then Start Debugging to run the application. It may take several minutes for the
deployment to run.
4. You can verify that your application added the new IoT hub by visiting the Azure portal and viewing your list of
resources, or by using the Get-AzureRmResource PowerShell cmdlet.
NOTE
This example application adds an S1 Standard IoT Hub for which you are billed. You can delete the IoT hub through the
Azure portal or by using the Remove-AzureRmResource PowerShell cmdlet when you are finished.

Next steps
Now you have deployed an IoT hub using an Azure Resource Manager template with a C# program, you may
want to explore further:
Read about the capabilities of the IoT Hub resource provider REST API.
Read Azure Resource Manager overview to learn more about the capabilities of Azure Resource Manager.
To learn more about developing for IoT Hub, see the following articles:
Introduction to C SDK
Azure IoT SDKs
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Configure IoT Hub file uploads using the Azure
portal
1/17/2017 • 1 min to read • Edit on GitHub

File upload
To use the file upload functionality in IoT Hub, you must first associate an Azure Storage account with your hub.
Select the File upload settings to display a list of file upload properties for the IoT hub that is being modified.
Storage container: Use the Azure portal to select a blob container in an Azure Storage account in your current
Azure subscription to associate with your IoT Hub. If necessary, you can create an Azure Storage account on the
Storage accounts blade and blob container on the Containers blade. IoT Hub automatically generates SAS URIs
with write permissions to this blob container for devices to use when they upload files.
Receive notifications for uploaded files: Enable or disable file upload notifications via the toggle.
SAS TTL: This setting is the time-to-live of the SAS URIs returned to the device by IoT Hub. Set to one hour by
default but can be customized to other values using the slider.
File notification settings default TTL: The time-to-live of a file upload notification before it is expired. Set to one
day by default but can be customized to other values using the slider.
File notification maximum delivery count: The number of times the IoT Hub attempts to deliver a file upload
notification. Set to 10 by default but can be customized to other values using the slider.
Next steps
For more information about the file upload capabilities of IoT Hub, see Upload files from a device in the IoT Hub
developer guide.
Follow these links to learn more about managing Azure IoT Hub:
Bulk manage IoT devices
IoT Hub metrics
Operations monitoring
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
Secure your IoT solution from the ground up
Manage your IoT Hub device identities in bulk
1/17/2017 • 9 min to read • Edit on GitHub

Each IoT hub has an identity registry you can use to create per-device resources in the service, such as a queue
that contains in-flight cloud-to-device messages. The identity registry also enables you to control access to the
device-facing endpoints. This article describes how to import and export device identities in bulk to and from an
identity registry.
Import and export operations take place in the context of Jobs that enable you to execute bulk service operations
against an IoT hub.
The RegistryManager class includes the ExportDevicesAsync and ImportDevicesAsync methods that use the
Job framework. These methods enable you to export, import, and synchronize the entirety of an IoT hub identity
registry.

What are Jobs?

Identity registry operations use the Job system when the operation:
Has a potentially long execution time compared to standard run-time operations, or
Returns a large amount of data to the user.
In these cases, instead of a single API call waiting or blocking on the result of the operation, the operation
asynchronously creates a Job for that IoT hub. The operation then immediately returns a JobProperties object.
The following C# code snippet shows how to create an export job:

// Call an export job on the IoT Hub to retrieve all devices

JobProperties exportJob = await registryManager.ExportDevicesAsync(containerSasUri, false);

Then you can use the RegistryManager class to query the state of the Job using the returned JobProperties
metadata.
The following C# code snippet shows how to poll every five seconds to see if the job has finished executing:

// Wait until job is finished

while(true)
{
exportJob = await registryManager.GetJobAsync(exportJob.JobId);
if (exportJob.Status == JobStatus.Completed ||
exportJob.Status == JobStatus.Failed ||
exportJob.Status == JobStatus.Cancelled)
{
// Job has finished executing
break;
}

await Task.Delay(TimeSpan.FromSeconds(5));
}

Export devices
Use the ExportDevicesAsync method to export the entirety of an IoT hub identity registry to an Azure Storage
blob container using a Shared Access Signature.
This method enables you to create reliable backups of your device information in a blob container that you
control.
The ExportDevicesAsync method requires two parameters:
A string that contains a URI of a blob container. This URI must contain a SAS token that grants write access
to the container. The job creates a block blob in this container to store the serialized export device data. The
SAS token must include these permissions:

SharedAccessBlobPermissions.Write | SharedAccessBlobPermissions.Read |
SharedAccessBlobPermissions.Delete

A boolean that indicates if you want to exclude authentication keys from your export data. If false,
authentication keys are included in export output. Otherwise, keys are exported as null.
The following C# code snippet shows how to initiate an export job that includes device authentication keys in the
export data and then poll for completion:

// Call an export job on the IoT Hub to retrieve all devices

JobProperties exportJob = await registryManager.ExportDevicesAsync(containerSasUri, false);

// Wait until job is finished

while(true)
{
exportJob = await registryManager.GetJobAsync(exportJob.JobId);
if (exportJob.Status == JobStatus.Completed ||
exportJob.Status == JobStatus.Failed ||
exportJob.Status == JobStatus.Cancelled)
{
// Job has finished executing
break;
}

await Task.Delay(TimeSpan.FromSeconds(5));
}

The job stores its output in the provided blob container as a block blob with the name devices.txt. The output
data consists of JSON serialized device data, with one device per line.
The following example shows the output data:

{"id":"Device1","eTag":"MA==","status":"enabled","authentication":{"symmetricKey":
{"primaryKey":"abc=","secondaryKey":"def="}}}
{"id":"Device2","eTag":"MA==","status":"enabled","authentication":{"symmetricKey":
{"primaryKey":"abc=","secondaryKey":"def="}}}
{"id":"Device3","eTag":"MA==","status":"disabled","authentication":{"symmetricKey":
{"primaryKey":"abc=","secondaryKey":"def="}}}
{"id":"Device4","eTag":"MA==","status":"disabled","authentication":{"symmetricKey":
{"primaryKey":"abc=","secondaryKey":"def="}}}
{"id":"Device5","eTag":"MA==","status":"enabled","authentication":{"symmetricKey":
{"primaryKey":"abc=","secondaryKey":"def="}}}

If you need access to this data in code, you can easily deserialize this data using the ExportImportDevice class.
The following C# code snippet shows how to read device information that was previously exported to a block blob:
var exportedDevices = new List<ExportImportDevice>();

using (var streamReader = new StreamReader(await

blob.OpenReadAsync(AccessCondition.GenerateIfExistsCondition(), RequestOptions, null), Encoding.UTF8))
{
while (streamReader.Peek() != -1)
{
string line = await streamReader.ReadLineAsync();
var device = JsonConvert.DeserializeObject<ExportImportDevice>(line);
exportedDevices.Add(device);
}
}

NOTE
You can also use the GetDevicesAsync method of the RegistryManager class to fetch a list of your devices. However, this
approach has a hard cap of 1000 on the number of device objects that are returned. The expected use case for the
GetDevicesAsync method is for development scenarios to aid debugging and is not recommended for production
workloads.

Import devices
The ImportDevicesAsync method in the RegistryManager class enables you to perform bulk import and
synchronization operations in an IoT hub identity registry. Like the ExportDevicesAsync method, the
ImportDevicesAsync method uses the Job framework.
Take care using the ImportDevicesAsync method because in addition to provisioning new devices in your
identity registry, it can also update and delete existing devices.

WARNING
An import operation cannot be undone. Always back up your existing data using the ExportDevicesAsync method to
another blob container before you make bulk changes to your identity registry.

The ImportDevicesAsync method takes two parameters:

A string that contains a URI of an Azure Storage blob container to use as input to the job. This URI must
contain a SAS token that grants read access to the container. This container must contain a blob with the
name devices.txt that contains the serialized device data to import into your identity registry. The import
data must contain device information in the same JSON format that the ExportImportDevice job uses
when it creates a devices.txt blob. The SAS token must include these permissions:

SharedAccessBlobPermissions.Read

A string that contains a URI of an Azure Storage blob container to use as output from the job. The job
creates a block blob in this container to store any error information from the completed import Job. The
SAS token must include these permissions:

SharedAccessBlobPermissions.Write | SharedAccessBlobPermissions.Read |
SharedAccessBlobPermissions.Delete
NOTE
The two parameters can point to the same blob container. The separate parameters simply enable more control over your
data as the output container requires additional permissions.

The following C# code snippet shows how to initiate an import job:

JobProperties importJob = await registryManager.ImportDevicesAsync(containerSasUri, containerSasUri);

Import behavior
You can use the ImportDevicesAsync method to perform the following bulk operations in your identity registry:
Bulk registration of new devices
Bulk deletions of existing devices
Bulk status changes (enable or disable devices)
Bulk assignment of new device authentication keys
Bulk auto-regeneration of device authentication keys
You can perform any combination of the preceding operations within a single ImportDevicesAsync call. For
example, you can register new devices and delete or update existing devices at the same time. When used along
with the ExportDevicesAsync method, you can completely migrate all your devices from one IoT hub to another.
Use the optional importMode property in the import serialization data for each device to control the import
process per-device. The importMode property has the following options:

IMPORTMODE DESCRIPTION

createOrUpdate If a device does not exist with the specified id, it is newly
registered.
If the device already exists, existing information is overwritten
with the provided input data without regard to the ETag
value.

create If a device does not exist with the specified id, it is newly
registered.
If the device already exists, an error is written to the log file.

update If a device already exists with the specified id, existing

information is overwritten with the provided input data
without regard to the ETag value.
If the device does not exist, an error is written to the log file.

updateIfMatchETag If a device already exists with the specified id, existing

information is overwritten with the provided input data only if
there is an ETag match.
If the device does not exist, an error is written to the log file.
If there is an ETag mismatch, an error is written to the log file.

createOrUpdateIfMatchETag If a device does not exist with the specified id, it is newly
registered.
If the device already exists, existing information is overwritten
with the provided input data only if there is an ETag match.
If there is an ETag mismatch, an error is written to the log file.
IMPORTMODE DESCRIPTION

delete If a device already exists with the specified id, it is deleted

without regard to the ETag value.
If the device does not exist, an error is written to the log file.

deleteIfMatchETag If a device already exists with the specified id, it is deleted only
if there is an ETag match. If the device does not exist, an error
is written to the log file.
If there is an ETag mismatch, an error is written to the log file.

NOTE
If the serialization data does not explicitly define an importMode flag for a device, it defaults to createOrUpdate during
the import operation.

Import devices example – bulk device provisioning

The following C# code sample illustrates how to generate multiple device identities that:
Include authentication keys.
Write that device information to a block blob.
Import the devices into the identity registry.
// Provision 1,000 more devices
var serializedDevices = new List<string>();

for (var i = 0; i < 1000; i++)

{
// Create a new ExportImportDevice
var deviceToAdd = new ExportImportDevice()
{
Id = Guid.NewGuid().ToString(),
Status = DeviceStatus.Enabled,
Authentication = new AuthenticationMechanism()
{
SymmetricKey = new SymmetricKey()
{
PrimaryKey = CryptoKeyGenerator.GenerateKey(32),
SecondaryKey = CryptoKeyGenerator.GenerateKey(32)
}
},
ImportMode = ImportMode.Create
};

// Add device to existing list

serializedDevices.Add(JsonConvert.SerializeObject(deviceToAdd));
}

// Write this list to the blob

var sb = new StringBuilder();
serializedDevices.ForEach(serializedDevice => sb.AppendLine(serializedDevice));
await blob.DeleteIfExistsAsync();

using (CloudBlobStream stream = await blob.OpenWriteAsync())

{
byte[] bytes = Encoding.UTF8.GetBytes(sb.ToString());
for (var i = 0; i < bytes.Length; i += 500)
{
int length = Math.Min(bytes.Length - i, 500);
await stream.WriteAsync(bytes, i, length);
}
}

// Call import using the same blob to add new devices!

// This normally takes 1 minute per 100 devices the normal way
JobProperties importJob = await registryManager.ImportDevicesAsync(containerSasUri, containerSasUri);

// Wait until job is finished

while(true)
{
importJob = await registryManager.GetJobAsync(importJob.JobId);
if (importJob.Status == JobStatus.Completed ||
importJob.Status == JobStatus.Failed ||
importJob.Status == JobStatus.Cancelled)
{
// Job has finished executing
break;
}

await Task.Delay(TimeSpan.FromSeconds(5));
}

Import devices example – bulk deletion

The following code sample shows you how to delete the devices you added using the previous code sample:
// Step 1: Update each device's ImportMode to be Delete
sb = new StringBuilder();
serializedDevices.ForEach(serializedDevice =>
{
// Deserialize back to an ExportImportDevice
var device = JsonConvert.DeserializeObject<ExportImportDevice>(serializedDevice);

// Update property
device.ImportMode = ImportMode.Delete;

// Re-serialize
sb.AppendLine(JsonConvert.SerializeObject(device));
});

// Step 2: Write the new import data back to the block blob
await blob.DeleteIfExistsAsync();
using (CloudBlobStream stream = await blob.OpenWriteAsync())
{
byte[] bytes = Encoding.UTF8.GetBytes(sb.ToString());
for (var i = 0; i < bytes.Length; i += 500)
{
int length = Math.Min(bytes.Length - i, 500);
await stream.WriteAsync(bytes, i, length);
}
}

// Step 3: Call import using the same blob to delete all devices!
importJob = await registryManager.ImportDevicesAsync(containerSasUri, containerSasUri);

// Wait until job is finished

while(true)
{
importJob = await registryManager.GetJobAsync(importJob.JobId);
if (importJob.Status == JobStatus.Completed ||
importJob.Status == JobStatus.Failed ||
importJob.Status == JobStatus.Cancelled)
{
// Job has finished executing
break;
}

await Task.Delay(TimeSpan.FromSeconds(5));
}

Getting the container SAS URI

The following code sample shows you how to generate a SAS URI with read, write, and delete permissions for a
blob container:
static string GetContainerSasUri(CloudBlobContainer container)
{
// Set the expiry time and permissions for the container.
// In this case no start time is specified, so the
// shared access signature becomes valid immediately.
var sasConstraints = new SharedAccessBlobPolicy();
sasConstraints.SharedAccessExpiryTime = DateTime.UtcNow.AddHours(24);
sasConstraints.Permissions =
SharedAccessBlobPermissions.Write |
SharedAccessBlobPermissions.Read |
SharedAccessBlobPermissions.Delete;

// Generate the shared access signature on the container,

// setting the constraints directly on the signature.
string sasContainerToken = container.GetSharedAccessSignature(sasConstraints);

// Return the URI string for the container,

// including the SAS token.
return container.Uri + sasContainerToken;
}

Next steps
In this article, you learned how to perform bulk operations against the identity registry in an IoT hub. Follow these
links to learn more about managing Azure IoT Hub:
IoT Hub metrics
Operations monitoring
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
IoT Hub metrics
1/24/2017 • 3 min to read • Edit on GitHub

IoT Hub metrics give you better data about the state of the Azure IoT resources in your Azure subscription. IoT Hub
metrics enable you to assess the overall health of the IoT Hub service and the devices connected to it. User-facing
statistics are important because they help you see what is going on with your IoT hub and help root-cause issues
without needing to contact Azure support.
Metrics are enabled by default. You can view IoT Hub metrics from the Azure portal.

How to view IoT Hub metrics

1. Create an IoT hub. You can find instructions on how to create an IoT hub in the Get Started guide.
2. Open the blade of your IoT hub. From there, click Metrics.

3. From the metrics blade, you can view the metrics for your IoT hub and create custom views of your metrics.
You can choose to send your metrics data to an Event Hubs endpoint or an Azure Storage account by
clicking Diagnostics settings.
IoT Hub metrics and how to use them
IoT Hub provides several metrics to give you an overview of the health of your hub and the total number of
connected devices. You can combine information from multiple metrics to paint a bigger picture of the state of the
IoT hub. The following table describes the metrics each IoT hub tracks, and how each metric relates to the overall
status of the IoT hub.

METRIC METRIC DESCRIPTION WHAT THE METRIC IS USED FOR

d2c.telemetry.ingress.allProtocol The count of messages sent across all Overview data on message sends
devices

d2c.telemetry.ingress.success The count of all successful messages Overview of successful message ingress
into the hub into the hub

d2c.telemetry.egress.success The count of all successful writes to an Overview of message fan-out based on
endpoint a user's routes

d2c.telemetry.egress.invalid The count of messages not delivered Overview of how many failures there
due to incompatibility with the are writing to the user's set of
endpoint endpoints. High values may indicate
improperly configured endpoints.

d2c.telemetry.egress.dropped The count of messages dropped Overview of how many messages have
because an endpoint was unhealthy been dropped given the current
configuration of the IoT hub

d2c.telemetry.egress.fallback The count of messages matching the For users who pipe all messages to
fallback route other endpoints than the built-in
endpoint, this metric shows gaps in the
routing setup
METRIC METRIC DESCRIPTION WHAT THE METRIC IS USED FOR

d2c.telemetry.egress.orphaned The count of messages not matching Overview of how many messages are
any routes including the fallback route orphaned given the current
configuration of the IoT Hub

d2c.endpoints.latency.eventHubs The average latency between message The spread helps users identify poor
ingress to the IoT hub and message endpoint configuration
ingress into an Event Hub endpoint, in
milliseconds

d2c.endpoints.latency.serviceBusQueue The average latency between message The spread helps users identify poor
s ingress to the IoT hub and message endpoint configuration
ingress into a Service Bus Queue
endpoint, in milliseconds

d2c.endpoints.latency.serviceBusTopic The average latency between message The spread helps users identify poor
ingress to the IoT hub and message endpoint configuration
ingress into a Service Bus Topic
endpoint, in milliseconds

d2c.endpoints.latency.builtIn.events The average latency between message The spread helps users identify poor
ingress to the IoT hub and message endpoint configuration
ingress into the built-in endpoint
(messages/events), in milliseconds

c2d.commands.egress.complete.success The count of all command messages Together with the metrics on abandon
completed by the receiving device and reject, gives an overview of overall
across all devices cloud-to-device command success rate

c2d.commands.egress.abandon.success The count of all messages successfully Highlights potential issues if messages
abandoned by the receiving device are getting abandoned more often than
across all devices expected

c2d.commands.egress.reject.success The count of all messages successfully Highlights potential issues if messages
rejected by the receiving device across are getting rejected more often than
all devices expected

devices.totalDevices The count of the number of devices The number of devices registered to the
registered to the IoT hub hub

devices.connectedDevices.allProtocol The count of the number of Overview of the number of devices

simultaneous connected devices connected to the hub

Next steps
Now that you’ve seen an overview of IoT Hub metrics, follow this link to learn more about managing Azure IoT
Hub:
Operations monitoring
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
IoT Hub operations monitoring
2/8/2017 • 4 min to read • Edit on GitHub

IoT Hub operations monitoring enables you to monitor the status of operations on your IoT hub in real time. IoT
Hub tracks events across several categories of operations. You can opt into sending events from one or more
categories to an endpoint of your IoT hub for processing. You can monitor the data for errors or set up more
complex processing based on data patterns.
IoT Hub monitors six categories of events:
Device identity operations
Device telemetry
Cloud-to-device messages
Connections
File uploads
Message routing

How to enable operations monitoring

1. Create an IoT hub. You can find instructions on how to create an IoT hub in the Get Started guide.
2. Open the blade of your IoT hub. From there, click Operations monitoring.

3. Select the monitoring categories you wish you monitor, and then click Save. The events are available for
reading from the Event Hub-compatible endpoint listed in Monitoring settings. The IoT Hub endpoint is
called messages/operationsmonitoringevents .

NOTE
Selecting Verbose monitoring for the Connections category causes IoT Hub to generate additional diagnostics messages.
For all other categories, the Verbose setting changes the quantity of information IoT Hub includes in each error message.

Event categories and how to use them

Each operations monitoring category tracks a different type of interaction with IoT Hub, and each monitoring
category has a schema that defines how events in that category are structured.
Device identity operations
The device identity operations category tracks errors that occur when you attempt to create, update, or delete an
entry in your IoT hub's identity registry. Tracking this category is useful for provisioning scenarios.

{
"time": "UTC timestamp",
"operationName": "create",
"category": "DeviceIdentityOperations",
"level": "Error",
"statusCode": 4XX,
"statusDescription": "MessageDescription",
"deviceId": "device-ID",
"durationMs": 1234,
"userAgent": "userAgent",
"sharedAccessPolicy": "accessPolicy"
}

Device telemetry
The device telemetry category tracks errors that occur at the IoT hub and are related to the telemetry pipeline.
This category includes errors that occur when sending telemetry events (such as throttling) and receiving
telemetry events (such as unauthorized reader). Note that this category cannot catch errors caused by code
running on the device itself.

{
"messageSizeInBytes": 1234,
"batching": 0,
"protocol": "Amqp",
"authType": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
"time": "UTC timestamp",
"operationName": "ingress",
"category": "DeviceTelemetry",
"level": "Error",
"statusCode": 4XX,
"statusType": 4XX001,
"statusDescription": "MessageDescription",
"deviceId": "device-ID",
"EventProcessedUtcTime": "UTC timestamp",
"PartitionId": 1,
"EventEnqueuedUtcTime": "UTC timestamp"
}

Cloud-to -device commands

The cloud-to-device commands category tracks errors that occur at the IoT hub and are related to the cloud-to-
device message pipeline. This category includes errors that occur when sending cloud-to-device messages (such
as unauthorized sender), receiving cloud-to-device messages (such as delivery count exceeded), and receiving
cloud-to-device message feedback (such as feedback expired). This category does not catch errors from a device
that improperly handles a cloud-to-device message if the cloud-to-device message was delivered successfully.
{
"messageSizeInBytes": 1234,
"authType": "{\"scope\":\"hub\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
"deliveryAcknowledgement": 0,
"protocol": "Amqp",
"time": " UTC timestamp",
"operationName": "ingress",
"category": "C2DCommands",
"level": "Error",
"statusCode": 4XX,
"statusType": 4XX001,
"statusDescription": "MessageDescription",
"deviceId": "device-ID",
"EventProcessedUtcTime": "UTC timestamp",
"PartitionId": 1,
"EventEnqueuedUtcTime": “UTC timestamp"
}

Connections
The connections category tracks errors that occur when devices connect or disconnect from an IoT hub. Tracking
this category is useful for identifying unauthorized connection attempts and for tracking when a connection is lost
for devices in areas of poor connectivity.

{
"durationMs": 1234,
"authType": "{\"scope\":\"hub\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
"protocol": "Amqp",
"time": " UTC timestamp",
"operationName": "deviceConnect",
"category": "Connections",
"level": "Error",
"statusCode": 4XX,
"statusType": 4XX001,
"statusDescription": "MessageDescription",
"deviceId": "device-ID"
}

File uploads
The file upload category tracks errors that occur at the IoT hub and are related to file upload functionality. This
category includes:
Errors that occur with the SAS URI, such as when it expires before a device notifies the hub of a completed
upload.
Failed uploads reported by the device.
Errors that occur when a file is not found in storage during IoT Hub notification message creation.
Note that this category cannot catch errors that directly occur while the device is uploading a file to storage.
{
"authType": "{\"scope\":\"hub\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
"protocol": "HTTP",
"time": " UTC timestamp",
"operationName": "ingress",
"category": "fileUpload",
"level": "Error",
"statusCode": 4XX,
"statusType": 4XX001,
"statusDescription": "MessageDescription",
"deviceId": "device-ID",
"blobUri": "http//bloburi.com",
"durationMs": 1234
}

Message routing
The message routing category tracks errors that occur during message route evaluation and endpoint health as
perceived by IoT Hub. This category includes events such as when a rule evaluates to "undefined", when IoT Hub
marks an endpoint as dead, and any other errors received from an endpoint. Note that this category does not
include specific errors about the messages themselves (such as device throttling errors), which are reported
under the "device telemetry" category.

{
"messageSizeInBytes": 1234,
"time": "UTC timestamp",
"operationName": "ingress",
"category": "routes",
"level": "Error",
"deviceId": "device-ID",
"messageId": "ID of message",
"routeName": "myroute",
"endpointName": "myendpoint",
"details": "ExternalEndpointDisabled"
}

Next steps
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Simulating a device with the IoT Gateway SDK
Use IP filters
1/27/2017 • 2 min to read • Edit on GitHub

Security is an important aspect of any IoT solution based on Azure IoT Hub. Sometimes you need to blacklist or
whitelist certain IP addresses as part of your security configuration. The IP filter feature enables you to configure
rules for rejecting or accepting traffic from specific IPv4 addresses.

When to use
There are two specific use-cases when it is useful to block the IoT Hub endpoints for certain IP addresses:
When your IoT hub should receive traffic only from a specified range of IP addresses and reject everything else.
For example, when you are using your IoT hub with Azure Express Route to create private connections between
an IoT hub and your on-premises infrastructure.
When you need to reject traffic from IP addresses that have been identified as suspicious by the IoT hub
administrator.

How filter rules are applied

The IP filter rules are applied at the IoT Hub service level. Therefore the IP filter rules apply to all connections from
devices and back-end apps using any supported protocol.
Any connection attempt from an IP address that matches a rejecting IP rule in your IoT hub receives an
unauthorized 401 status code and description. The response message does not mention the IP rule.

Default setting
By default, the IP Filter grid in the portal for an IoT hub is empty. This default setting means that your hub accepts
connections any IP address. This default setting is equivalent to a rule that accepts the 0.0.0.0/0 IP address range.
Add or edit an IP filter rule
When you add an IP filter rule, you are prompted for the following values:
An IP filter rule name that must be a unique, case-insensitive, alphanumeric string up to 128 characters long.
Only the ASCII 7-bit alphanumeric characters plus
{'-', ':', '/', '\', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '''} are accepted.
Select a reject or accept as the action for the IP filter rule.
Provide a single IPv4 address or a block of IP addesses in CIDR notation. For example, in CIDR notation
192.168.100.0/22 represents the 1024 IPv4 addresses from 192.168.100.0 to 192.168.103.255.

After you save the rule, you see an alert notifying you that the update is in progress.

The Add option is disabled when you reach the maximum of ten IP filter rules.
You can edit an existing rule by double-clicking the row that contains the rule.
NOTE
Rejecting IP addresses can prevent other Azure Services (such as Azure Stream Analytics, Azure Virtual Machines, or the
Device Explorer in the portal) from interacting with the IoT hub.

Delete an IP filter rule

To delete an IP filter rule, select one or more rules in the grid and click Delete.

IP filter rule evaluation

IP filter rules are applied in order and the first rule that matches the IP address determines the accept or reject
action.
For example, if you want to accept addresses in the range 192.168.100.0/22 and reject everything else, the first rule
in the grid should accept the address range 192.168.100.0/22. The next rule should reject all addresses by using the
range 0.0.0.0/0.
You can change the order of your IP filter rules in the grid by clicking on the three vertical dots at the start of a row
and using drag and drop.
To save your new IP filter rule order, click Save.
Next steps
To further explore the capabilities of IoT Hub, see:
Operations monitoring
IoT Hub metrics
Internet of Things security from the ground up
1/17/2017 • 12 min to read • Edit on GitHub

The Internet of Things (IoT) poses unique security, privacy, and compliance challenges to businesses worldwide.
Unlike traditional cyber technology where these issues revolve around software and how it is implemented, IoT
concerns what happens when the cyber and the physical worlds converge. Protecting IoT solutions requires
ensuring secure provisioning of devices, secure connectivity between these devices and the cloud, and secure data
protection in the cloud during processing and storage. Working against such functionality, however, are resource-
constrained devices, geographic distribution of deployments, and a large number of devices within a solution.
This article explores how the Microsoft Azure IoT Suite provides a secure and private Internet of Things cloud
solution. The Azure IoT Suite delivers a complete end-to-end solution, with security built into every stage from the
ground up. At Microsoft, developing secure software is part of the software engineering practice, rooted in our
decades long experience of developing secure software. To ensure this, Security Development Lifecycle (SDL) is the
foundational development methodology, coupled with a host of infrastructure-level security services such as
Operational Security Assurance (OSA) and the Microsoft Digital Crimes Unit, Microsoft Security Response Center,
and Microsoft Malware Protection Center.
The Azure IoT Suite offers unique features which make provisioning, connecting to, and storing data from IoT
devices easy and transparent and, most of all, secure. In this paper we examine the Azure IoT Suite security
features and deployment strategies to ensure security, privacy, and compliance challenges are addressed.

Introduction
The Internet of Things (IoT) is the wave of the future, offering businesses immediate and real-world opportunities
to reduce costs, increase revenue, and transform their business. Many businesses, however, are hesitant to deploy
IoT in their organizations due to concerns about security, privacy, and compliance. A major point of concern comes
from the uniqueness of the IoT infrastructure, which merges the cyber and physical worlds together, compounding
individual risks inherent in these two worlds. Security of IoT pertains to ensuring the integrity of code running on
devices, providing device and user authentication, defining clear ownership of devices (as well as data generated
by those devices), and being resilient to cyber and physical attacks.
Then, there’s the issue of privacy. Companies want transparency concerning data collection, as in what’s being
collected and why, who can see it, who controls access, and so on. Finally, there are general safety issues of the
equipment along with the people operating them, and issues of maintaining industry standards of compliance.
Given the security, privacy, transparency, and compliance concerns, choosing the right IoT solution provider
remains a challenge. Stitching together individual pieces of IoT software and services provided by a variety of
vendors introduces gaps in security, privacy, transparency, and compliance which may be hard to detect, let alone
fix. The choice of the right IoT software and service provider is based on finding providers which have extensive
experience running services which span across verticals and geographies, but are also able to scale in a secure and
transparent fashion. Similarly, it helps for the selected provider to have decades of experience with developing
secure software running on billions of machines worldwide, and have the ability to appreciate the threat landscape
posed by this new world of the Internet of Things.

Secure infrastructure from the ground up

The Microsoft Cloud infrastructure supports more than one billion customers in 127 countries. Drawing on our
decades-long experience building enterprise software and running some of the largest online services in the
world, we provide higher levels of enhanced security, privacy, compliance, and threat mitigation practices than
most customers could achieve on their own.
Our Security Development Lifecycle (SDL) provides a mandatory company-wide development process that
embeds security requirements into the entire software lifecycle. To help ensure that operational activities follow
the same level of security practices, we use rigorous security guidelines laid out in our Operational Security
Assurance (OSA) process. We also work with third-party audit firms for ongoing verification that we meet our
compliance obligations, and we engage in broad security efforts through the creation of centers of excellence,
including the Microsoft Digital Crimes Unit, Microsoft Security Response Center, and Microsoft Malware Protection
Center.

Microsoft Azure - secure IoT infrastructure for your business

Microsoft Azure offers a complete cloud solution, one that combines a constantly growing collection of integrated
cloud services—analytics, machine learning, storage, security, networking, and web—with an industry-leading
commitment to the protection and privacy of your data. Our assume breach strategy uses a dedicated “red team”
of software security experts who simulate attacks, testing the ability of Azure to detect, protect against emerging
threats, and recover from breaches. Our global incident response team works around the clock to mitigate the
effects of attacks and malicious activity. The team follows established procedures for incident management,
communication, and recovery, and uses discoverable and predictable interfaces with internal and external partners.
Our systems provide continuous intrusion detection and prevention, service attack prevention, regular penetration
testing, and forensic tools that help identify and mitigate threats. Multi-factor authentication provides an extra
layer of security for end users to access the network. And for the application and the host provider, we offer access
control, monitoring, anti-malware, vulnerability scanning, patches, and configuration management.
The Microsoft Azure IoT Suite takes advantage of the security and privacy built into the Azure platform along with
our SDL and OSA processes for secure development and operation of all Microsoft software. These procedures
provide infrastructure protection, network protection, and identity and management features fundamental to the
security of any solution.
The Azure IoT Hub within the IoT Suite offers a fully-managed service that enables reliable and secure bi-
directional communication between IoT devices and Azure services such as Azure Machine Learning and Azure
Stream Analytics by using per-device security credentials and access control.
To best communicate security and privacy features built into the Azure IoT Suite, we’ve broken down the suite into
the three primary security areas.

Secure device provisioning and authentication

The Azure IoT Suite secures devices while they are out in the field by providing a unique identity key for each
device, which can be used by the IoT infrastructure to communicate with the device while it is in operation. The
process is quick and easy to setup. The generated key with a user-selected device ID forms the basis of a token
used in all communication between the device and the Azure IoT Hub.
Device IDs can be associated with a device during manufacturing (i.e. flashed in a hardware trust module) or can
use an existing fixed identity as a proxy (for example CPU serial numbers). Since changing this identifying
information in the device is not simple, it is important to introduce logical device IDs in case the underlying device
hardware changes but the logical device remains the same. In some cases, the association of a device identity can
happen at device deployment time (i.e. an authenticated field engineer physically configures a new device while
communicating with the solution backend). The Azure IoT Hub identity registry provides secure storage of device
identities and security keys for a solution. Individual or groups of device identities can be added to an allow list, or
a block list, enabling complete control over device access.
Azure IoT Hub access control policies in the cloud enable activation and disabling any device identity, providing a
way to disassociate a device from an IoT deployment when required. This association and disassociation of devices
is based on each device identity.
Additional device security features include the following:
Devices do not accept unsolicited network connections. They establish all connections and routes in an
outbound-only fashion. For a device to receive a command from the backend, the device must initiate a
connection to check for any pending commands to process. Once a connection between the device and IoT Hub
is securely established, messaging from the cloud to the device and device to the cloud can be sent
transparently.
Devices only connect to or establish routes to well-known services with which they are peered, such as an
Azure IoT Hub.
System-level authorization and authentication use per-device identities, making access credentials and
permissions near-instantly revocable.
Secure connectivity
Durability of messaging is an important feature of any IoT solution. The need to durably deliver commands and/or
receive data from devices is underlined by the fact that IoT devices are connected over the Internet, or other similar
networks which can be unreliable. Azure IoT Hub offers durability of messaging between cloud and devices
through a system of acknowledgments in response to messages. Additional durability for messaging is achieved
by caching messages in the IoT Hub for up to seven days for telemetry and two days for commands.
Efficiency is important to ensure conservation of resources and operation in a resource-constrained environment.
HTTPS (HTTP Secure), the industry-standard secure version of the popular http protocol, is supported by Azure IoT
Hub, enabling efficient communication. Advanced Message Queuing Protocol (AMQP) and Message Queuing
Telemetry Transport (MQTT), supported by Azure IoT Hub, are designed not only for efficiency in terms of resource
use but also reliable message delivery.
Scalability requires the ability to securely interoperate with a wide range of devices. Azure IoT hub enables secure
connection to both IP-enabled and non-IP-enabled devices. IP-enabled devices are able to directly connect and
communicate with the IoT Hub over a secure connection. Non-IP-enabled devices are resource-constrained and
connect only over short distance communication protocols, such as Zwave, ZigBee, and Bluetooth. A field gateway
is used to aggregate these devices and performs protocol translation to enable secure bi-directional
communication with the cloud.
Additional connection security features include the following:
The communication path between devices and Azure IoT Hub, or between gateways and Azure IoT Hub, is
secured using industry-standard Transport Layer Security (TLS) with Azure IoT Hub authenticated using X.509
protocol.
In order to protect devices from unsolicited inbound connections, Azure IoT Hub does not open any connection
to the device. The device initiates all connections.
Azure IoT Hub durably stores messages for devices and waits for the device to connect. These commands are
stored for two days, enabling devices connecting sporadically, due to power or connectivity concerns, to receive
these commands. Azure IoT Hub maintains a per-device queue for each device.
Secure processing and storage in the cloud
From encrypted communications to processing data in the cloud, the Azure IoT Suite helps keep data secure. It
provides flexibility to implement additional encryption and management of security keys. Using Azure Active
Directory (AAD) for user authentication and authorization, Azure IoT Suite can provide a policy-based
authorization model for data in the cloud, enabling easy access management that can be audited and reviewed.
This model also enables near-instant revocation of access to data in the cloud, and of devices connected to the
Azure IoT Suite.
Once data is in the cloud, it can be processed and stored in any user-defined workflow. Access to each part of the
data is controlled with Azure Active Directory, depending on the storage service used.
All keys used by the IoT infrastructure are stored in the cloud in secure storage, with the ability to roll over in case
keys need to be re-provisioned. Data can be stored in DocumentDB or in SQL databases, enabling definition of the
level of security desired. Additionally, Azure provides a way to monitor and audit all access to your data to alert
you of any intrusion or unauthorized access.

Conclusion
The Internet of Things starts with your things—the things that matter most to businesses. IoT can deliver amazing
value to a business by reducing costs, increasing revenue, and transforming business. Success of this
transformation largely depends on choosing the right IoT software and service provider. That means finding a
provider that not only catalyzes this transformation by understanding business needs and requirements, but also
provides services and software built with security, privacy, transparency, and compliance as major design
considerations. Microsoft has extensive experience with developing and deploying secure software and services
and continues to be a leader in this new age of Internet of Things.
The Microsoft Azure IoT Suite builds in security measures by design, enabling secure monitoring of assets to
improve efficiencies, drive operational performance to enable innovation, and employ advanced data analytics to
transform businesses. With its layered approach towards security, multiple security features, and design patterns,
Azure IoT Suite helps deploy an infrastructure which can be trusted to transform any business.

Additional information
Each Azure IoT Suite pre-configured solution creates instances of Azure services, such as the following:
Azure IoT Hub: Your gateway that connects the cloud to “things”. You can scale to millions of connections per
hub and process massive volumes of data with per-device authentication support helping you secure your
solution.
Azure DocumentDB: A scalable, fully-indexed database service for semi-structured data that manages
metadata for the devices you provision, such as attributes, configuration, and security properties. DocumentDB
offers high-performance and high-throughput processing, schema-agnostic indexing of data, and a rich SQL
query interface.
Azure Stream Analytics: Real-time stream processing in the cloud that enables you to rapidly develop and
deploy a low-cost analytics solution to uncover real-time insights from devices, sensors, infrastructure, and
applications. The data from this fully-managed service can scale to any volume while still achieving high
throughput, low latency, and resiliency.
Azure App Services: A cloud platform to build powerful web and mobile apps that connect to data anywhere;
in the cloud or on-premises. Build engaging mobile apps for iOS, Android, and Windows. Integrate with your
Software as a Service (SaaS) and enterprise applications with out-of-the-box connectivity to dozens of cloud-
based services and enterprise applications. Code in your favorite language and IDE—.NET, Node.js, PHP,
Python, or Java—to build web apps and APIs faster than ever.
Logic Apps: The Logic Apps feature of Azure App Service helps integrate your IoT solution to your existing line
of business systems and automate workflow processes. Logic Apps enables developers to design workflows
that starts from a trigger and then execute a series of steps—rules and actions that use powerful connectors to
integrate with your business processes. Logic Apps offers out-of-the-box connectivity to a vast ecosystem of
SaaS, cloud-based, and on-premises applications.
Azure blob storage: Reliable, economical cloud storage for the data that your devices send to the cloud.

See also
To learn more about securing your IoT solution, see:
IoT Security Best Practices
IoT Security Architecture
Secure your IoT deployment
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Internet of Things security best practices
1/17/2017 • 6 min to read • Edit on GitHub

To secure an Internet of Things (IoT) infrastructure requires a rigorous security-in-depth strategy. This strategy
requires you to secure data in the cloud, protect data integrity while in transit over the public internet, and securely
provision devices. Each layer builds greater security assurance in the overall infrastructure.

Secure an IoT infrastructure

This security-in-depth strategy can be developed and executed with active participation of various players involved
with the manufacturing, development, and deployment of IoT devices and infrastructure. Following is a high-level
description of these players.
IoT hardware manufacturer/integrator: Typically, these are the manufacturers of IoT hardware being
deployed, integrators assembling hardware from various manufacturers, or suppliers providing hardware for an
IoT deployment manufactured or integrated by other suppliers.
IoT solution developer: The development of an IoT solution is typically done by a solution developer. This
developer may part of an in-house team or a system integrator (SI) specializing in this activity. The IoT solution
developer can develop various components of the IoT solution from scratch, integrate various off-the-shelf or
open-source components, or adopt preconfigured solutions with minor adaptation.
IoT solution deployer: After an IoT solution is developed, it needs to be deployed in the field. This involves
deployment of hardware, interconnection of devices, and deployment of solutions in hardware devices or the
cloud.
IoT solution operator: After the IoT solution is deployed, it requires long-term operations, monitoring,
upgrades, and maintenance. This can be done by an in-house team that comprises information technology
specialists, hardware operations and maintenance teams, and domain specialists who monitor the correct
behavior of overall IoT infrastructure.
The sections that follow provide best practices for each of these players to help develop, deploy, and operate a
secure IoT infrastructure.

IoT hardware manufacturer/integrator

The following are the best practices for IoT hardware manufacturers and hardware integrators.
Scope hardware to minimum requirements: The hardware design should include the minimum features
required for operation of the hardware, and nothing more. An example is to include USB ports only if necessary
for the operation of the device. These additional features open the device for unwanted attack vectors that
should be avoided.
Make hardware tamper proof: Build in mechanisms to detect physical tampering, such as opening of the
device cover or removing a part of the device. These tamper signals may be part of the data stream uploaded to
the cloud, which could alert operators of these events.
Build around secure hardware: If COGS permits, build security features such as secure and encrypted storage,
or boot functionality based on Trusted Platform Module (TPM). These features make devices more secure and
help protect the overall IoT infrastructure.
Make upgrades secure: Firmware upgrades during the lifetime of the device are inevitable. Building devices
with secure paths for upgrades and cryptographic assurance of firmware versions will allow the device to be
secure during and after upgrades.
IoT solution developer
The following are the best practices for IoT solution developers:
Follow secure software development methodology: Development of secure software requires ground-up
thinking about security, from the inception of the project all the way to its implementation, testing, and
deployment. The choices of platforms, languages, and tools are all influenced with this methodology. The
Microsoft Security Development Lifecycle provides a step-by-step approach to building secure software.
Choose open-source software with care: Open-source software provides an opportunity to quickly develop
solutions. When you're choosing open-source software, consider the activity level of the community for each
open-source component. An active community ensures that software is supported and that issues are
discovered and addressed. Alternatively, an obscure and inactive open-source software might not be supported
and issues will probably not be discovered.
Integrate with care: Many software security flaws exist at the boundary of libraries and APIs. Functionality that
may not be required for the current deployment might still be available via an API layer. To ensure overall
security, make sure to check all interfaces of components being integrated for security flaws.

IoT solution deployer

The following are best practices for IoT solution deployers:
Deploy hardware securely: IoT deployments may require hardware to be deployed in unsecure locations,
such as in public spaces or unsupervised locales. In such situations, ensure that hardware deployment is
tamper-proof to the maximum extent. If USB or other ports are available on the hardware, ensure that they are
covered securely. Many attack vectors can use these as entry points.
Keep authentication keys safe: During deployment, each device requires device IDs and associated
authentication keys generated by the cloud service. Keep these keys physically safe even after the deployment.
Any compromised key can be used by a malicious device to masquerade as an existing device.

IoT solution operator

The following are the best practices for IoT solution operators:
Keep the system up to date: Ensure that device operating systems and all device drivers are upgraded to the
latest versions. If you turn on automatic updates in Windows 10 (IoT or other SKUs), Microsoft keeps it up to
date, providing a secure operating system for IoT devices. Keeping other operating systems (such as Linux) up
to date helps ensure that they are also protected against malicious attacks.
Protect against malicious activity: If the operating system permits, install the latest antivirus and
antimalware capabilities on each device operating system. This can help mitigate most external threats. You can
protect most modern operating systems against threats by taking appropriate steps.
Audit frequently: Auditing IoT infrastructure for security-related issues is key when responding to security
incidents. Most operating systems provide built-in event logging that should be reviewed frequently to make
sure no security breach has occurred. Audit information can be sent as a separate telemetry stream to the cloud
service where it can be analyzed.
Physically protect the IoT infrastructure: The worst security attacks against IoT infrastructure are launched
using physical access to devices. One important safety practice is to protect against malicious use of USB ports
and other physical access. One key to uncovering breaches that might have occurred is logging of physical
access, such as USB port use. Again, Windows 10 (IoT and other SKUs) enables detailed logging of these events.
Protect cloud credentials: Cloud authentication credentials used for configuring and operating an IoT
deployment are possibly the easiest way to gain access and compromise an IoT system. Protect the credentials
by changing the password frequently, and refrain from using these credentials on public machines.
Capabilities of different IoT devices vary. Some devices might be computers running common desktop operating
systems, and some devices might be running very light-weight operating systems. The security best practices
described previously might be applicable to these devices in varying degrees. If provided, additional security and
deployment best practices from the manufacturers of these devices should be followed.
Some legacy and constrained devices might not have been designed specifically for IoT deployment. These devices
might lack the capability to encrypt data, connect with the Internet, or provide advanced auditing. In these cases, a
modern and secure field gateway can aggregate data from legacy devices and provide the security required for
connecting these devices over the Internet. Field gateways can provide secure authentication, negotiation of
encrypted sessions, receipt of commands from the cloud, and many other security features.

See also
To learn more about securing your IoT solution, see:
IoT Security Architecture
Secure your IoT deployment
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Internet of Things security architecture
1/17/2017 • 24 min to read • Edit on GitHub

When designing a system, it is important to understand the potential threats to that system, and add appropriate
defenses accordingly, as the system is designed and architected. It is particularly important to design the product
from the start with security in mind because understanding how an attacker might be able to compromise a
system helps make sure appropriate mitigations are in place from the beginning.

Security starts with a threat model

Microsoft has long used threat models for its products and has made the company’s threat modeling process
publically available. The company experience demonstrates that the modelling has unexpected benefits beyond the
immediate understanding of what threats are the most concerning. For example, it also creates an avenue for an
open discussion with others outside the development team, which can lead to new ideas and improvements in the
product.
The objective of threat modeling is to understand how an attacker might be able to compromise a system and then
make sure appropriate mitigations are in place. Threat modeling forces the design team to consider mitigations as
the system is designed rather than after a system is deployed. This fact is critically important, because retrofitting
security defenses to a myriad of devices in the field is infeasible, error prone and will leave customers at risk.
Many development teams do an excellent job capturing the functional requirements for the system that benefit
customers. However, identifying non-obvious ways that someone might misuse the system is more challenging.
Threat modeling can help development teams understand what an attacker might do and why. Threat modeling is
a structured process that creates a discussion about the security design decisions in the system, as well as changes
to the design that are made along the way that impact security. While a threat model is simply a document, this
documentation also represents an ideal way to ensure continuity of knowledge, retention of lessons learned, and
help new team onboard rapidly. Finally, an outcome of threat modeling is to enable you to consider other aspects
of security, such as what security commitments you wish to provide to your customers. These commitments in
conjunction with threat modeling will inform and drive testing of your Internet of Things (IoT) solution.
When to threat model
Threat modeling offers the greatest value if it is incorporated into the design phase. When you are designing, you
have the greatest flexibility to make changes to eliminate threats. Eliminating threats by design is the desired
outcome. It is much easier than adding mitigations, testing them, and ensuring they remain current and moreover,
such elimination is not always possible. It becomes harder to eliminate threats as a product becomes more mature,
and in turn will ultimately require more work and a lot harder tradeoffs than threat modeling early on in the
development.
What to threat model
You should thread model the solution as a whole and also focus in the following areas:
The security and privacy features
The features whose failures are security relevant
The features that touch a trust boundary
Who threat models
Threat modeling is a process like any other. It is a good idea to treat the threat model document like any other
component of the solution and validate it. Many development teams do an excellent job capturing the functional
requirements for the system that benefit customers. However, identifying non-obvious ways that someone might
misuse the system is more challenging. Threat modeling can help development teams understand what an attacker
might do and why.
How to threat model
The threat modeling process is composed of four steps; the steps are:
Model the application
Enumerate Threats
Mitigate threats
Validate the mitigations
The process steps
Three rules of thumb to keep in mind when building a threat model:
1. Create a diagram out of reference architecture.
2. Start breadth-first. Get an overview, and understand the system as a whole, before deep-diving. This helps
ensure that you deep-dive in the right places.
3. Drive the process, don’t let the process drive you. If you find an issue in the modeling phase and want to
explore it, go for it! Don’t feel you need to follow these steps slavishly.
Threats
The four core elements of a threat model are:
Processes (web services, Win32 services, *nix daemons, etc. Note that some complex entities (for example field
gateways and sensors) can be abstracted as a process when a technical drill down in these areas is not possible.
Data stores (anywhere data is stored, such as a configuration file or database)
Data flow (where data moves between other elements in the application)
External Entities (anything that interacts with the system, but is not under the control of the application,
examples include users and satellite feeds)
All elements in the architectural diagram are subject to various threats; we will use the STRIDE mnemonic. Read
Threat Modeling Again, STRIDE to know more about the STRIDE elements.
Different elements of the application diagram are subject to certain STRIDE threats:
Processes are subject to STRIDE
Data flows are subject to TID
Data stores are subject to TID, and sometimes R, if the data stores are log files.
External entities are subject to SRD

Security in IoT
Connected special-purpose devices have a significant number of potential interaction surface areas and interaction
patterns, all of which must be considered to provide a framework for securing digital access to those devices. The
term “digital access” is used here to distinguish from any operations that are carried out through direct device
interaction where access security is provided through physical access control. For example, putting the device into
a room with a lock on the door. While physical access cannot be denied using software and hardware, measures
can be taken to prevent physical access from leading to system interference.
As we explore the interaction patterns, we will look at “device control” and “device data” with the same level of
attention. “Device control” can be classified as any information that is provided to a device by any party with the
goal of changing or influencing its behavior towards its state or the state of its environment. “Device data” can be
classified as any information that a device emits to any other party about its state and the observed state of its
environment.
In order to optimize security best practices, it is recommended that a typical IoT architecture be divided into several
component/zones as part of the threat modeling exercise. These zones are described fully throughout this section
and include:
Device,
Field Gateway,
Cloud gateways, and
Services.
Zones are broad way to segment a solution; each zone often has its own data and authentication and authorization
requirements. Zones can also be used to isolation damage and restrict the impact of low trust zones on higher
trust zones.
Each zone is separated by a Trust Boundary, which is noted as the dotted red line in the diagram below. It
represents a transition of data/information from one source to another. During this transition, the
data/information could be subject to Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service
and Elevation of Privilege (STRIDE).

The components depicted within each boundary are also subjected to STRIDE, enabling a full 360 threat modeling
view of the solution. The sections below elaborate on each of the components and specific security concerns and
solutions that should be put into place.
The sections that follows will discuss standard components typically found in these zones.
The Device Zone
The device environment is the immediate physical space around the device where physical access and/or “local
network” peer-to-peer digital access to the device is feasible. A “local network” is assumed to be a network that is
distinct and insulated from – but potentially bridged to – the public Internet, and includes any short-range wireless
radio technology that permits peer-to-peer communication of devices. It does not include any network
virtualization technology creating the illusion of such a local network and it does also not include public operator
networks that require any two devices to communicate across public network space if they were to enter a peer-to-
peer communication relationship.
The Field Gateway Zone
Field gateway is a device/appliance or some general-purpose server computer software that acts as
communication enabler and, potentially, as a device control system and device data processing hub. The field
gateway zone includes the field gateway itself and all devices that are attached to it. As the name implies, field
gateways act outside dedicated data processing facilities, are usually location bound, are potentially subject to
physical intrusion, and will have limited operational redundancy. All to say that a field gateway is commonly a
thing one can touch and sabotage while knowing what its function is.
A field gateway is different from a mere traffic router in that it has had an active role in managing access and
information flow, meaning it is an application addressed entity and network connection or session terminal. An
NAT device or firewall, in contrast, do not qualify as field gateways since they are not explicit connection or session
terminals, but rather a route (or block) connections or sessions made through them. The field gateway has two
distinct surface areas. One faces the devices that are attached to it and represents the inside of the zone, and the
other faces all external parties and is the edge of the zone.
The cloud gateway zone
Cloud gateway is a system that enables remote communication from and to devices or field gateways from several
different sites across public network space, typically towards a cloud-based control and data analysis system, a
federation of such systems. In some cases, a cloud gateway may immediately facilitate access to special-purpose
devices from terminals such as tablets or phones. In the context discussed here, “cloud” is meant to refer to a
dedicated data processing system that is not bound to the same site as the attached devices or field gateways. Also
in a Cloud Zone, operational measures prevent targeted physical access and is not necessarily exposed to a “public
cloud” infrastructure.
A cloud gateway may potentially be mapped into a network virtualization overlay to insulate the cloud gateway
and all of its attached devices or field gateways from any other network traffic. The cloud gateway itself is neither a
device control system nor a processing or storage facility for device data; those facilities interface with the cloud
gateway. The cloud gateway zone includes the cloud gateway itself along with all field gateways and devices
directly or indirectly attached to it. The edge of the zone is a distinct surface area where all external parties
communicate through.
The services zone
A “service” is defined for this context as any software component or module that is interfacing with devices
through a field- or cloud gateway for data collection and analysis, as well as for command and control. Services are
mediators. They act under their identity towards gateways and other subsystems, store and analyze data,
autonomously issue commands to devices based on data insights or schedules and expose information and
control capabilities to authorized end-users.
Information-devices vs. special-purpose devices
PCs, phones, and tablets are primarily interactive information devices. Phones and tablets are explicitly optimized
around maximizing battery lifetime. They preferably turn off partially when not immediately interacting with a
person, or when not providing services like playing music or guiding their owner to a particular location. From a
systems perspective, these information technology devices are mainly acting as proxies towards people. They are
“people actuators” suggesting actions and “people sensors” collecting input.
Special-purpose devices, from simple temperature sensors to complex factory production lines with thousands of
components inside them, are different. These devices are much more scoped in purpose and even if they provide
some user interface, they are largely scoped to interfacing with or be integrated into assets in the physical world.
They measure and report environmental circumstances, turn valves, control servos, sound alarms, switch lights,
and do many other tasks. They help to do work for which an information device is either too generic, too
expensive, too big, or too brittle. The concrete purpose immediately dictates their technical design as well the
available monetary budget for their production and scheduled lifetime operation. The combination of these two
key factors constrains the available operational energy budget, physical footprint, and thus available storage,
compute, and security capabilities.
If something “goes wrong” with automated or remote controllable devices, for example, physical defects or control
logic defects to willful unauthorized intrusion and manipulation. The production lots may be destroyed, buildings
may be looted or burned down, and people may be injured or even die. This is, of course, a whole different class of
damage than someone maxing out a stolen credit card's limit. The security bar for devices that make things move,
and also for sensor data that eventually results in commands that cause things to move, must be higher than in
any e-commerce or banking scenario.
Device control and device data interactions
Connected special-purpose devices have a significant number of potential interaction surface areas and interaction
patterns, all of which must be considered to provide a framework for securing digital access to those devices. The
term “digital access” is used here to distinguish from any operations that are carried out through direct device
interaction where access security is provided through physical access control. For example, putting the device into
a room with a lock on the door. While physical access cannot be denied using software and hardware, measures
can be taken to prevent physical access from leading to system interference.
As we explore the interaction patterns, we will look at “device control” and “device data” with the same level of
attention while threat modeling. “Device control” can be classified as any information that is provided to a device
by any party with the goal of changing or influencing its behavior towards its state or the state of its environment.
“Device data” can be classified as any information that a device emits to any other party about its state and the
observed state of its environment.

Threat modeling the Azure IoT reference architecture

Microsoft uses the framework outlined above to do threat modelling for Azure IoT. In the section below we
therefore use the concrete example of Azure IoT Reference Architecture to demonstrate how to think about threat
modelling for IoT and how to address the threats identified. In our case we identified four main areas of focus:
Devices and Data Sources,
Data Transport,
Device and Event Processing, and
Presentation

The diagram below provides a simplified view of Microsoft’s IoT Architecture using a Data Flow Diagram model
that is used by the Microsoft Threat Modeling Tool:
It is important to note that the architecture separates the device and gateway capabilities. This allows the user to
leverage gateway devices that are more secure: they are capable of communicating with the cloud gateway using
secure protocols, which typically requires greater processing overhead that a native device - such as a thermostat -
could provide on its own. In the Azure services zone, we assume that the Cloud Gateway is represented by the
Azure IoT Hub service.
Device and data sources/data transport
This section explores the architecture outlined above through the lens of threat modeling and gives an overview of
how we are addressing some of the inherent concerns. We will focus on the core elements of a threat model:
Processes (those under our control and external items)
Communication (also called data flows)
Storage (also called data stores)
Processes
In each of the categories outlined in the Azure IoT architecture, we try to mitigate a number of different threats
across the different stages data/information exists in: process, communication, and storage. Below we give an
overview of the most common ones for the “process” category, followed by an overview of how these could be
best mitigated:
Spoofing (S): An attacker may extract cryptographic key material from a device, either at the software or
hardware level, and subsequently access the system with a different physical or virtual device under the identity of
the device the key material has been taken from. A good illustration is remote controls that can turn any TV and
that are popular prankster tools.
Denial of Service (D): A device can be rendered incapable of functioning or communicating by interfering with
radio frequencies or cutting wires. For example, a surveillance camera that had its power or network connection
intentionally knocked out will not report data, at all.
Tampering (T): An attacker may partially or wholly replace the software running on the device, potentially
allowing the replaced software to leverage the genuine identity of the device if the key material or the
cryptographic facilities holding key materials were available to the illicit program. For example, an attacker may
leverage extracted key material to intercept and suppress data from the device on the communication path and
replace it with false data that is authenticated with the stolen key material.
Information Disclosure (I): If the device is running manipulated software, such manipulated software could
potentially leak data to unauthorized parties. For example, an attacker may leverage extracted key material to inject
itself into the communication path between the device and a controller or field gateway or cloud gateway to
siphon off information.
Elevation of Privilege (E): A device that does specific function can be forced to do something else. For example, a
valve that is programmed to open half way can be tricked to open all the way.
COMPONENT THREAT MITIGATION RISK IMPLEMENTATION

Device S Assigning identity to Replacing device or Authenticating the

the device and part of the device device, using
authenticating the with some other Transport Layer
device device. How do we Security (TLS) or
know we are talking IPSec. Infrastructure
to the right device? should support using
pre-shared key (PSK)
on those devices that
cannot handle full
asymmetric
cryptography.
Leverage Azure AD,
OAuth

TRID Apply tamperproof The risk is if someone The most effective

mechanisms to the is tampering the mitigation is a trusted
device for example by device (physical platform module
making it very hard interference). How are (TPM) capability that
to impossible to we sure, that device allows storing keys in
extract keys and has not tampered special on-chip
other cryptographic with. circuitry from which
material from the the keys cannot be
device. read, but can only be
used for
cryptographic
operations that use
the key but never
disclose the key.
Memory encryption
of the device. Key
management for the
device. Signing the
code.

E Having access control If the device allows for Having authorization

of the device. individual actions to scheme for the device
Authorization be performed based
scheme. on commands from
an outside source, or
even compromised
sensors, it will allow
the attack to perform
operations not
otherwise accessible.

Field Gateway S Authenticating the If someone can spoof TLS RSA/PSK, IPSec,
Field gateway to Field Gateway, then it RFC 4279. All the
Cloud Gateway (cert can present itself as same key storage and
based, PSK, Claim any device. attestation concerns
based,..) of devices in general –
best case is use TPM.
6LowPAN extension
for IPSec to support
Wireless Sensor
Networks (WSN).
COMPONENT THREAT MITIGATION RISK IMPLEMENTATION

TRID Protect the Field Spoofing attacks that Memory encryption,

Gateway against trick the cloud TPM’s, authentication.
tampering (TPM?) gateway thinking it is
talking to field
gateway could result
in information
disclosure and data
tampering

E Access control
mechanism for Field
Gateway

Here are some examples of threats in this category:

Spoofing: An attacker may extract cryptographic key material from a device, either at the software or hardware
level, and subsequently access the system with a different physical or virtual device under the identity of the device
the key material has been taken from.
Denial of Service: A device can be rendered incapable of functioning or communicating by interfering with radio
frequencies or cutting wires. For example, a surveillance camera that had its power or network connection
intentionally knocked out will not report data, at all.
Tampering: An attacker may partially or wholly replace the software running on the device, potentially allowing
the replaced software to leverage the genuine identity of the device if the key material or the cryptographic
facilities holding key materials were available to the illicit program.
Tampering: A surveillance camera that’s showing a visible-spectrum picture of an empty hallway could be aimed
at a photograph of such a hallway. A smoke or fire sensor could be reporting someone holding a lighter under it. In
either case, the device may be technically fully trustworthy towards the system, but it will report manipulated
information.
Tampering: An attacker may leverage extracted key material to intercept and suppress data from the device on
the communication path and replace it with false data that is authenticated with the stolen key material.
Tampering: An attacker may partially or completely replace the software running on the device, potentially
allowing the replaced software to leverage the genuine identity of the device if the key material or the
cryptographic facilities holding key materials were available to the illicit program.
Information Disclosure: If the device is running manipulated software, such manipulated software could
potentially leak data to unauthorized parties.
Information Disclosure: An attacker may leverage extracted key material to inject itself into the communication
path between the device and a controller or field gateway or cloud gateway to siphon off information.
Denial of Service: The device can be turned off or turned into a mode where communication is not possible
(which is intentional in many industrial machines).
Tampering: The device can be reconfigured to operate in a state unknown to the control system (outside of
known calibration parameters) and thus provide data that can be misinterpreted
Elevation of Privilege: A device that does specific function can be forced to do something else. For example, a
valve that is programmed to open half way can be tricked to open all the way.
Denial of Service: The device can be turned into a state where communication is not possible.
Tampering: The device can be reconfigured to operate in a state unknown to the control system (outside of
known calibration parameters) and thus provide data that can be misinterpreted.
Spoofing/Tampering/Repudiation: If not secured (which is rarely the case with consumer remote controls) an
attacker can manipulate the state of a device anonymously. A good illustration is remote controls that can turn any
TV and that are popular prankster tools.
Communication
Threats around communication path between devices, devices and field gateways and device and cloud gateway.
The table below has some guidance around open sockets on the device/VPN:

COMPONENT THREAT MITIGATION RISK IMPLEMENTATION

Device IoT Hub TID (D)TLS (PSK/RSA) to Eavesdropping or Security on the

encrypt the traffic interfering the protocol level. With
communication custom protocols, we
between the device need to figure out
and the gateway how to protect them.
In most cases, the
communication takes
place from the device
to the IoT Hub (device
initiates the
connection).

Device Device TID (D)TLS (PSK/RSA) to Reading data in Security on the

encrypt the traffic. transit between protocol level
devices. Tampering (MQTT/AMQP/HTTP/
with the data. CoAP. With custom
Overloading the protocols, we need to
device with new figure out how to
connections protect them. The
mitigation for the DoS
threat is to peer
devices through a
cloud or field gateway
and have them only
act as clients towards
the network. The
peering may result in
a direct connection
between the peers
after having been
brokered by the
gateway

External Entity Device TID Strong pairing of the Eavesdropping the Securely pairing the
external entity to the connection to the external entity to the
device device. Interfering the device NFC/Bluetooth
communication with LE. Controlling the
the device operational panel of
the device (Physical)

Field Gateway Cloud TID TLS (PSK/RSA) to Eavesdropping or Security on the

Gateway encrypt the traffic. interfering the protocol level
communication (MQTT/AMQP/HTTP/
between the device CoAP). With custom
and the gateway protocols, we need to
figure out how to
protect them.
COMPONENT THREAT MITIGATION RISK IMPLEMENTATION

Device Cloud TID TLS (PSK/RSA) to Eavesdropping or Security on the

Gateway encrypt the traffic. interfering the protocol level
communication (MQTT/AMQP/HTTP/
between the device CoAP). With custom
and the gateway protocols, we need to
figure out how to
protect them.

Here are some examples of threats in this category:

Denial of Service: Constrained devices are generally under DoS threat when they actively listen for inbound
connections or unsolicited datagrams on a network, because an attacker can open many connections in parallel
and not service them or service them very slowly, or the device can be flooded with unsolicited traffic. In both
cases, the device can effectively be rendered inoperable on the network.
Spoofing, Information Disclosure: Constrained devices and special-purpose devices often have one-for-all
security facilities like password or PIN protection, or they wholly rely on trusting the network, meaning they will
grant access to information when a device is on the same network, and that network is often only protected by a
shared key. That means that when the shared secret to device or network is disclosed, it is possible to control the
device or observe data emitted from the device.
Spoofing: an attacker may intercept or partially override the broadcast and spoof the originator (man in the
middle)
Tampering: an attacker may intercept or partially override the broadcast and send false information
Information Disclosure: an attacker may eavesdrop on a broadcast and obtain information without authorization
Denial of Service: an attacker may jam the broadcast signal and deny information distribution
Storage
Every device and field gateway has some form of storage (temporary for queuing the data, operating system (OS)
image storage).

COMPONENT THREAT MITIGATION RISK IMPLEMENTATION

Device storage TRID Storage encryption, Reading data from Encryption, message
signing the logs the storage (PII data), authentication code
tampering with (MAC) or digital
telemetry data. signature. Where
Tampering with possible, strong
queued or cached access control
command control through resource
data. Tampering with access control lists
configuration or (ACLs) or permissions.
firmware update
packages while
cached or queued
locally can lead to OS
and/or system
components being
compromised

Device OS image TRID Tampering with OS Read-only OS

/replacing the OS partition, signed OS
components image, Encryption
COMPONENT THREAT MITIGATION RISK IMPLEMENTATION

Field Gateway storage TRID Storage encryption, Reading data from BitLocker
(queuing the data) signing the logs the storage (PII data),
tampering with
telemetry data,
tampering with
queued or cached
command control
data. Tampering with
configuration or
firmware update
packages (destined
for devices or field
gateway) while cached
or queued locally can
lead to OS and/or
system components
being compromised

Field Gateway OS TRID Tampering with OS Read-only OS

image /replacing the OS partition, signed OS
components image, Encryption

Device and event processing/cloud gateway zone

A cloud gateway is system that enables remote communication from and to devices or field gateways from several
different sites across public network space, typically towards a cloud-based control and data analysis system, a
federation of such systems. In some cases, a cloud gateway may immediately facilitate access to special-purpose
devices from terminals such as tablets or phones. In the context discussed here, “cloud” is meant to refer to a
dedicated data processing system that is not bound to the same site as the attached devices or field gateways, and
where operational measures prevent targeted physical access but is not necessarily to a “public cloud”
infrastructure. A cloud gateway may potentially be mapped into a network virtualization overlay to insulate the
cloud gateway and all of its attached devices or field gateways from any other network traffic. The cloud gateway
itself is neither a device control system nor a processing or storage facility for device data; those facilities interface
with the cloud gateway. The cloud gateway zone includes the cloud gateway itself along with all field gateways and
devices directly or indirectly attached to it.
Cloud gateway is mostly custom built piece of software running as a service with exposed endpoints to which field
gateway and devices connect. As such it must be designed with security in mind. Please follow SDL process for
designing and building this service.
Services zone
A control system (or controller) is a software solution that interfaces with a device, or a field gateway, or cloud
gateway for the purpose of controlling one or multiple devices and/or to collect and/or store and/or analyze device
data for presentation, or subsequent control purposes. Control systems are the only entities in the scope of this
discussion that may immediately facilitate interaction with people. The exception are intermediate physical control
surfaces on devices, like a switch that allows a person to turn the device off or change other properties, and for
which there is no functional equivalent that can be accessed digitally.
Intermediate physical control surfaces are those where any sort of governing logic constrains the function of the
physical control surface such that an equivalent function can be initiated remotely or input conflicts with remote
input can be avoided – such intermediated control surfaces are conceptually attached to a local control system that
leverages the same underlying functionality as any other remote control system that the device may be attached to
in parallel. Top threats to the cloud computing can be read at Cloud Security Alliance (CSA) page.

Additional resources
Refer to the following articles for additional information:
SDL Threat Modeling Tool
Microsoft Azure IoT reference architecture

See also
To learn more about securing your IoT solution see, Secure your IoT deployment
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Secure your IoT deployment
1/17/2017 • 7 min to read • Edit on GitHub

This article provides the next level of detail for securing the Azure IoT-based Internet of Things (IoT) infrastructure.
It links to implementation level details for configuring and deploying each component. It also provides
comparisons and choices between various competing methods.
Securing the Azure IoT deployment can be divided into the following three security areas:
Device Security: Securing the IoT device while it is deployed in the wild.
Connection Security: Ensuring all data transmitted between the IoT device and IoT Hub is confidential and
tamper-proof.
Cloud Security: Providing a means to secure data while it moves through, and is stored in the cloud.

Secure device provisioning and authentication

The Azure IoT Suite secures IoT devices by the following two methods:
By providing a unique identity key (security tokens) for each device, which can be used by the device to
communicate with the IoT Hub.
By using an on-device X.509 certificate and private key as a means to authenticate the device to the IoT Hub.
This authentication method ensures that the private key on the device is not known outside the device at any
time, providing a higher level of security.
The security token method provides authentication for each call made by the device to IoT Hub by associating the
symmetric key to each call. X.509-based authentication allows authentication of an IoT device at the physical layer
as part of the TLS connection establishment. The security-token-based method can be used without the X.509
authentication which is a less secure pattern. The choice between the two methods is primarily dictated by how
secure the device authentication needs to be, and availability of secure storage on the device (to store the private
key securely).

IoT Hub security tokens

IoT Hub uses security tokens to authenticate devices and services to avoid sending keys on the network.
Additionally, security tokens are limited in time validity and scope. Azure IoT SDKs automatically generate tokens
without requiring any special configuration. Some scenarios, however, require the user to generate and use
security tokens directly. These include the direct use of the MQTT, AMQP, or HTTP surfaces, or the implementation
of the token service pattern.
More details on the structure of the security token and its usage can be found in the following articles:
Security token structure
Using SAS tokens as a device
Each IoT Hub has an identity registry that can be used to create per-device resources in the service, such as a
queue that contains in-flight cloud-to-device messages, and to allow access to the device-facing endpoints. The IoT
Hub identity registry provides secure storage of device identities and security keys for a solution. Individual or
groups of device identities can be added to an allow list, or a block list, enabling complete control over device
access. The following articles provide more details on the structure of the identity registry and supported
operations.
IoT Hub supports protocols such as MQTT, AMQP, and HTTP. Each of these protocols use security tokens from the
IoT device to IoT Hub differently:
AMQP: SASL PLAIN and AMQP Claims-based security ({policyName}@sas.root.{iothubName} in the case of IoT
hub-level tokens; {deviceId} in case of device-scoped tokens).
MQTT: CONNECT packet uses {deviceId} as the {ClientId}, {IoThubhostname}/{deviceId} in the Username field
and a SAS token in the Password field.
HTTP: Valid token is in the authorization request header.
IoT Hub identity registry can be used to configure per-device security credentials and access control. However, if
an IoT solution already has a significant investment in a custom device identity registry and/or authentication
scheme, it can be integrated into an existing infrastructure with IoT Hub by creating a token service.
X.509 certificate -based device authentication
The use of a device-based X.509 certificate and its associated private and public key pair allows additional
authentication at the physical layer. The private key is stored securely in the device and is not discoverable outside
the device. The X.509 certificate contains information about the device, such as device ID, and other organizational
details. A signature of the certificate is generated by using the private key.
High-level device provisioning flow:
Associate an identifier to a physical device – device identity and/or X.509 certificate associated to the device
during device manufacturing or commissioning.
Create a corresponding identity entry in IoT Hub – device identity and associated device information in the IoT
Hub identity registry.
Securely store X.509 certificate thumbprint in IoT Hub identity registry.
Root certificate on device
While establishing a secure TLS connection with IoT Hub, the IoT device authenticates IoT Hub using a root
certificate which is part of the device SDK. For the C client SDK the certificate is located under the folder "\c\certs"
under the root of the repo. Though these root certificates are long-lived, they still may expire or be revoked. If
there is no way of updating the certificate on the device, the device may not be able to subsequently connect to the
IoT Hub (or any other cloud service). Having a means to update the root certificate once the IoT device is deployed
will effectively mitigate this risk.

Securing the connection

Internet connection between the IoT device and IoT Hub is secured using the Transport Layer Security (TLS)
standard. Azure IoT supports TLS 1.2, TLS 1.1 and TLS 1.0, in this order. Support for TLS 1.0 is provided for
backward compatibility only. It is recommended to use TLS 1.2 since it provides the most security.
Azure IoT Suite supports the following Cipher Suites, in this order.

CIPHER SUITE LENGTH

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (0xc028) 256

ECDH secp384r1 (eq. 7680 bits RSA) FS

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xc027) 128

ECDH secp256r1 (eq. 3072 bits RSA) FS

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (0xc014) ECDH 256

secp384r1 (eq. 7680 bits RSA) FS

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (0xc013) ECDH 128

secp256r1 (eq. 3072 bits RSA) FS

TLS_RSA_WITH_AES_256_GCM_SHA384 (0x9d) 256

TLS_RSA_WITH_AES_128_GCM_SHA256 (0x9c) 128

TLS_RSA_WITH_AES_256_CBC_SHA256 (0x3d) 256

TLS_RSA_WITH_AES_128_CBC_SHA256 (0x3c) 128

TLS_RSA_WITH_AES_256_CBC_SHA (0x35) 256

TLS_RSA_WITH_AES_128_CBC_SHA (0x2f) 128

TLS_RSA_WITH_3DES_EDE_CBC_SHA (0xa) 112

Securing the cloud

Azure IoT Hub allows definition of access control policies for each security key. It uses the following set of
permissions to grant access to each of IoT Hub's endpoints. Permissions limit the access to an IoT Hub based on
functionality.
RegistryRead. Grants read access to the identity registry. For more information, see identity registry.
RegistryReadWrite. Grants read and write access to the identity registry. For more information, see identity
registry.
ServiceConnect. Grants access to cloud service-facing communication and monitoring endpoints. For
example, it grants permission to back-end cloud services to receive device-to-cloud messages, send cloud-to-
device messages, and retrieve the corresponding delivery acknowledgments.
DeviceConnect. Grants access to device-facing endpoints. For example, it grants permission to send device-to-
cloud messages and receive cloud-to-device messages. This permission is used by devices.
There are two ways to obtain DeviceConnect permissions with IoT Hub with security tokens: using a device
identity key, or a shared access key. Moreover, it is important to note that all functionality accessible from devices
is exposed by design on endpoints with prefix /devices/{deviceId} .
Service components can only generate security tokens using shared access policies granting the appropriate
permissions.
Azure IoT Hub and other services which may be part of the solution allow management of users using the Azure
Active Directory.
Data ingested by Azure IoT Hub can be consumed by a variety of services such as Azure Stream Analytics and
Azure blob storage. These services allow management access. Read more about these services and available
options below:
Azure DocumentDB: A scalable, fully-indexed database service for semi-structured data that manages metadata
for the devices you provision, such as attributes, configuration, and security properties. DocumentDB offers
high-performance and high-throughput processing, schema-agnostic indexing of data, and a rich SQL query
interface.
Azure Stream Analytics: Real-time stream processing in the cloud that enables you to rapidly develop and
deploy a low-cost analytics solution to uncover real-time insights from devices, sensors, infrastructure, and
applications. The data from this fully-managed service can scale to any volume while still achieving high
throughput, low latency, and resiliency.
Azure App Services: A cloud platform to build powerful web and mobile apps that connect to data anywhere; in
the cloud or on-premises. Build engaging mobile apps for iOS, Android, and Windows. Integrate with your
Software as a Service (SaaS) and enterprise applications with out-of-the-box connectivity to dozens of cloud-
based services and enterprise applications. Code in your favorite language and IDE (.NET, Node.js, PHP, Python,
or Java) to build web apps and APIs faster than ever.
Logic Apps: The Logic Apps feature of Azure App Service helps integrate your IoT solution to your existing line-
of-business systems and automate workflow processes. Logic Apps enables developers to design workflows
that start from a trigger and then execute a series of steps—rules and actions that use powerful connectors to
integrate with your business processes. Logic Apps offers out-of-the-box connectivity to a vast ecosystem of
SaaS, cloud-based, and on-premises applications.
Azure blob storage: Reliable, economical cloud storage for the data that your devices send to the cloud.

Conclusion
This article provides overview of implementation level details for designing and deploying an IoT infrastructure
using Azure IoT. Configuring each component to be secure is key in securing the overall IoT infrastructure. The
design choices available in Azure IoT provide some level of flexibility and choice; however, each choice may have
security implications. It is recommended that each of these choices be evaluated through a risk/cost assessment.

See also
To further explore the capabilities of IoT Hub, see:
Simulating a device with the IoT Gateway SDK
Use the Azure IoT Gateway SDK to send device-
to-cloud messages with a simulated device (Linux)
2/6/2017 • 6 min to read • Edit on GitHub

This walkthrough of the Simulated Device Cloud Upload sample shows how to use the Azure IoT Gateway
SDK to send device-to-cloud telemetry to IoT Hub from simulated devices.
This walkthrough covers:
1. Architecture: important architectural information about the Simulated Device Cloud Upload sample.
2. Build and run: the steps required to build and run the sample.

Architecture
The Simulated Device Cloud Upload sample shows how to use the SDK to create a gateway which sends
telemetry from simulated devices to an IoT hub. The simulated devices cannot connect directly to IoT Hub
because:
The devices do not use a communications protocol understood by IoT Hub.
The devices are not smart enough to remember the identity assigned to them by IoT Hub.
The gateway solves these problems for the simulated devices in the following ways:
The gateway understands the protocol used by the simulated devices, receives device-to-cloud telemetry
from the devices, and forwards those messages to IoT Hub using a protocol understood by the IoT hub.
The gateway stores IoT Hub identities on behalf of the simulated devices and acts as a proxy when the
simulated devices send messages to IoT Hub.
The following diagram shows the main components of the sample, including the gateway modules:

NOTE
The modules do not pass messages directly to each other. The modules publish messages to an internal broker that
delivers the messages to the other modules using a subscription mechanism as shown in the diagram below. For more
information, see Get started with the IoT Gateway SDK.

Protocol ingestion module

This module is the starting point for getting data from devices, through the gateway, and into the cloud. In the
sample, the module performs four tasks:
1. It creates simulated temperature data. Note that if you use real devices, the module reads data from those
physical devices.
2. It places the simulated temperature data into the contents of a message.
3. It adds a property with a fake MAC address to the message that contains the simulated temperature data.
4. It makes the message available to the next module in the chain.

NOTE
The module called Protocol X ingestion in the diagram above is called Simulated device in the source code.

MAC <-> IoT Hub ID module

This module scans for messages that include a property that contains the MAC address, added by the protocol
ingestion module, of the simulated device app. If the module finds such a property, it adds another property
with an IoT Hub device key to the message and then makes the message available to the next module in the
chain. This is how the sample associates IoT Hub device identities with simulated devices. The developer sets
up the mapping between MAC addresses and IoT Hub identities manually as part of the module
configuration.

NOTE
This sample uses a MAC address as a unique device identifier and correlates it with an IoT Hub device identity.
However, you can write your own module that uses a different unique identifier. For example, you may have devices
with unique serial numbers or telemetry data that has a unique device name embedded in it that you could use to
determine the IoT Hub device identity.

IoT Hub communication module

This module takes messages with an IoT Hub device identity assigned by the previous module and sends the
message content to IoT Hub using HTTP. HTTP is one of the three protocols understood by IoT Hub.
Instead of opening a connection to IoT Hub for each simulated device app, this module opens a single HTTP
connection from the gateway to the IoT hub and multiplexes connections from all the simulated devices over
that connection. This enables a single gateway to connect many more devices, simulated or otherwise, than
would be possible if it opened a unique connection for every device.

Build and run the sample

Before you get started, you must:
Set up your development environment for working with the SDK on Linux.
Create an IoT hub in your Azure subscription, you will need the name of your hub to complete this
walkthrough. If you don't have an account, you can create a free account in just a couple of minutes.
Add two devices to your IoT hub and make a note of their ids and device keys. You can use the device
explorer or iothub-explorer tool to add your devices to the IoT hub you created in the previous step and
retrieve their keys.
To build the sample:
1. Open a shell.
2. Navigate to the root folder in your local copy of the azure-iot-gateway-sdk repository.
3. Run the tools/build.sh script. This script uses the cmake utility to create a folder called build in the root
folder of your local copy of the azure-iot-gateway-sdk repository and generate a makefile. The script
then builds the solution, skipping unit tests and end to end tests. Add the --run-unittests parameter if you
want to build and run the unit tests. Add the --run-e2e-tests if you want to build and run the end to end
tests.

NOTE
Every time you run the build.sh script, it deletes and then recreates the build folder in the root folder of your local
copy of the azure-iot-gateway-sdk repository.

To run the sample:

In a text editor, open the file
samples/simulated_device_cloud_upload/src/simulated_device_cloud_upload_lin.json in your local
copy of the azure-iot-gateway-sdk repository. This file configures the modules in the sample gateway:
The IoTHub module connects to your IoT hub. You must configure it to send data to your IoT hub.
Specifically, set the IoTHubName value to the name of your IoT hub and set the IoTHubSuffix value to
azure-devices.net. Set the Transport value to one of: "HTTP", "AMQP", or "MQTT". Note that currently,
only "HTTP" will share one TCP connection for all device messages. If you set the value to "AMQP", or
"MQTT", the gateway will maintain a separate TCP connection to IoT Hub for each device.
The mapping module maps the MAC addresses of your simulated devices to your IoT Hub device ids.
Make sure that deviceId values match the ids of the two devices you added to your IoT hub, and that the
deviceKey values contain the keys of your two devices.
The BLE1 and BLE2 modules are the simulated devices. Note how their MAC addresses match those in the
mapping module.
The Logger module logs your gateway activity to a file.
The module path values shown below assume that you will run the sample from the root of your local
copy of the azure-iot-gateway-sdk repository.
The links array at the bottom of the JSON file connects the BLE1 and BLE2 modules to the mapping
module, and the mapping module to the IoTHub module. It also ensures that all messages are logged by
the Logger module.

{
"modules": [
{
"name": "IotHub",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/iothub/libiothub.so"
}
},
"args": {
"IoTHubName": "<<insert here IoTHubName>>",
"IoTHubSuffix": "<<insert here IoTHubSuffix>>",
"Transport": "HTTP"
}
},
{
"name": "mapping",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/identitymap/libidentity_map.so"
}
},
"args": [
{
"macAddress": "01:01:01:01:01:01",
"deviceId": "<<insert here deviceId>>",
"deviceKey": "<<insert here deviceKey>>"
},
{
"macAddress": "02:02:02:02:02:02",
"deviceId": "<<insert here deviceId>>",
"deviceKey": "<<insert here deviceKey>>"
}
]
},
{
"name": "BLE1",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/simulated_device/libsimulated_device.so"
}
},
"args": {
"macAddress": "01:01:01:01:01:01"
}
},
{
"name": "BLE2",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/simulated_device/libsimulated_device.so"
}
},
"args": {
"macAddress": "02:02:02:02:02:02"
}
},
{
"name": "Logger",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "./modules/logger/liblogger.so"
}
},
"args": {
"filename": "deviceCloudUploadGatewaylog.log"
}
}
],
"links": [
{
"source": "*",
"sink": "Logger"
},
{
"source": "BLE1",
"sink": "mapping"
},
{
"source": "BLE2",
"sink": "mapping"
},
{
"source": "mapping",
"sink": "IotHub"
}
]
}

Save any changes you made to the configuration file.

To run the sample:
1. In your shell, navigate to the azure-iot-gateway-sdk/build folder.
2. Run the following command:

./samples/simulated_device_cloud_upload/simulated_device_cloud_upload_sample
./../samples/simulated_device_cloud_upload/src/simulated_device_cloud_upload_lin.json

3. You can use the device explorer or iothub-explorer tool to monitor the messages that IoT hub receives
from the gateway.

Next steps
If you want to gain a more advanced understanding of the IoT Gateway SDK and experiment with some code
examples, visit the following developer tutorials and resources:
Send device-to-cloud messages from a physical device with the IoT Gateway SDK
Azure IoT Gateway SDK
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
Secure your IoT solution from the ground up
Use the Azure IoT Gateway SDK to send device-to-
cloud messages with a simulated device (Windows)
2/6/2017 • 6 min to read • Edit on GitHub

This walkthrough of the Simulated Device Cloud Upload sample shows how to use the Azure IoT Gateway SDK to
send device-to-cloud telemetry to IoT Hub from simulated devices.
This walkthrough covers:
1. Architecture: important architectural information about the Simulated Device Cloud Upload sample.
2. Build and run: the steps required to build and run the sample.

Architecture
The Simulated Device Cloud Upload sample shows how to use the SDK to create a gateway which sends telemetry
from simulated devices to an IoT hub. The simulated devices cannot connect directly to IoT Hub because:
The devices do not use a communications protocol understood by IoT Hub.
The devices are not smart enough to remember the identity assigned to them by IoT Hub.
The gateway solves these problems for the simulated devices in the following ways:
The gateway understands the protocol used by the simulated devices, receives device-to-cloud telemetry from
the devices, and forwards those messages to IoT Hub using a protocol understood by the IoT hub.
The gateway stores IoT Hub identities on behalf of the simulated devices and acts as a proxy when the simulated
devices send messages to IoT Hub.
The following diagram shows the main components of the sample, including the gateway modules:

NOTE
The modules do not pass messages directly to each other. The modules publish messages to an internal broker that delivers
the messages to the other modules using a subscription mechanism as shown in the diagram below. For more information,
see Get started with the IoT Gateway SDK.

Protocol ingestion module

This module is the starting point for getting data from devices, through the gateway, and into the cloud. In the
sample, the module performs four tasks:
1. It creates simulated temperature data. Note that if you use real devices, the module reads data from those
physical devices.
2. It places the simulated temperature data into the contents of a message.
3. It adds a property with a fake MAC address to the message that contains the simulated temperature data.
4. It makes the message available to the next module in the chain.

NOTE
The module called Protocol X ingestion in the diagram above is called Simulated device in the source code.

MAC <-> IoT Hub ID module

This module scans for messages that include a property that contains the MAC address, added by the protocol
ingestion module, of the simulated device app. If the module finds such a property, it adds another property with
an IoT Hub device key to the message and then makes the message available to the next module in the chain. This
is how the sample associates IoT Hub device identities with simulated devices. The developer sets up the mapping
between MAC addresses and IoT Hub identities manually as part of the module configuration.

NOTE
This sample uses a MAC address as a unique device identifier and correlates it with an IoT Hub device identity. However, you
can write your own module that uses a different unique identifier. For example, you may have devices with unique serial
numbers or telemetry data that has a unique device name embedded in it that you could use to determine the IoT Hub
device identity.

IoT Hub communication module

This module takes messages with an IoT Hub device identity assigned by the previous module and sends the
message content to IoT Hub using HTTP. HTTP is one of the three protocols understood by IoT Hub.
Instead of opening a connection to IoT Hub for each simulated device app, this module opens a single HTTP
connection from the gateway to the IoT hub and multiplexes connections from all the simulated devices over that
connection. This enables a single gateway to connect many more devices, simulated or otherwise, than would be
possible if it opened a unique connection for every device.

Build and run the sample

Before you get started, you must:
Set up your development environment for working with the SDK on Windows.
Create an IoT hub in your Azure subscription, you will need the name of your hub to complete this walkthrough.
If you don't have an account, you can create a free account in just a couple of minutes.
Add two devices to your IoT hub and make a note of their ids and device keys. You can use the device explorer
or iothub-explorer tool to add your devices to the IoT hub you created in the previous step and retrieve their
keys.
To build the sample:
1. Open a Developer Command Prompt for VS2015 command prompt.
2. Navigate to the root folder in your local copy of the azure-iot-gateway-sdk repository.
3. Run the tools\build.cmd script. This script creates a Visual Studio solution file and builds the solution. You can
find the Visual Studio solution in the build folder in your local copy of the azure-iot-gateway-sdk repository.
Additional parameters can be given to the script to build and run unit and end to end tests. These paramaters
are --run-unittests and --run-e2e-tests respectively.
To run the sample:
In a text editor, open the file
samples\simulated_device_cloud_upload\src\simulated_device_cloud_upload_win.json in your local copy
of the azure-iot-gateway-sdk repository. This file configures the modules in the sample gateway:
The IoTHub module connects to your IoT hub. You must configure it to send data to your IoT hub. Specifically,
set the IoTHubName value to the name of your IoT hub and set the IoTHubSuffix value to azure-
devices.net. Set the Transport value to one of: "HTTP", "AMQP", or "MQTT". Note that currently, only "HTTP"
will share one TCP connection for all device messages. If you set the value to "AMQP", or "MQTT", the gateway
will maintain a separate TCP connection to IoT Hub for each device.
The mapping module maps the MAC addresses of your simulated devices to your IoT Hub device ids. Make
sure that deviceId values match the ids of the two devices you added to your IoT hub, and that the deviceKey
values contain the keys of your two devices.
The BLE1 and BLE2 modules are the simulated devices. Note how their MAC addresses match those in the
mapping module.
The Logger module logs your gateway activity to a file.
The module path values shown below assume that you cloned the IoT Gateway SDK repository to the root of
your C: drive. If you downloaded it to another location, you need to adjust the module path values accordingly.
The links array at the bottom of the JSON file connects the BLE1 and BLE2 modules to the mapping module,
and the mapping module to the IoTHub module. It also ensures that all messages are logged by the Logger
module.

{
"modules" :
[
{
"name": "IotHub",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "..\\..\\..\\modules\\iothub\\Debug\\iothub.dll"
}
},
"args": {
"IoTHubName": "<<insert here IoTHubName>>",
"IoTHubSuffix": "<<insert here IoTHubSuffix>>",
"Transport": "HTTP"
}
},
{
"name": "mapping",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "..\\..\\..\\modules\\identitymap\\Debug\\identity_map.dll"
}
},
"args": [
{
"macAddress": "01:01:01:01:01:01",
"deviceId": "<<insert here deviceId>>",
"deviceKey": "<<insert here deviceKey>>"
},
{
"macAddress": "02:02:02:02:02:02",
"deviceId": "<<insert here deviceId>>",
"deviceKey": "<<insert here deviceKey>>"
}
]
},
{
"name": "BLE1",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "..\\..\\..\\modules\\simulated_device\\Debug\\simulated_device.dll"
}
},
"args": {
"macAddress": "01:01:01:01:01:01"
}
},
{
"name": "BLE2",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "..\\..\\..\\modules\\simulated_device\\Debug\\simulated_device.dll"
}
},
"args": {
"macAddress": "02:02:02:02:02:02"
}
},
{
"name": "Logger",
"loader": {
"name": "native",
"entrypoint": {
"module.path": "..\\..\\..\\modules\\logger\\Debug\\logger.dll"
}
},
"args": {
"filename": "deviceCloudUploadGatewaylog.log"
}
}
],
"links" : [
{ "source" : "*", "sink" : "Logger" },
{ "source" : "BLE1", "sink" : "mapping" },
{ "source" : "BLE2", "sink" : "mapping" },
{ "source" : "mapping", "sink" : "IotHub" }
]
}

Save any changes you made to the configuration file.

To run the sample:
1. At a command prompt, navigate to the root folder of your local copy of the azure-iot-gateway-sdk repository.
2. Run the following command:

build\samples\simulated_device_cloud_upload\Debug\simulated_device_cloud_upload_sample.exe
samples\simulated_device_cloud_upload\src\simulated_device_cloud_upload_win.json

3. You can use the device explorer or iothub-explorer tool to monitor the messages that IoT hub receives from the
gateway.

Next steps
If you want to gain a more advanced understanding of the IoT Gateway SDK and experiment with some code
examples, visit the following developer tutorials and resources:
Send device-to-cloud messages from a physical device with the IoT Gateway SDK
Azure IoT Gateway SDK
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide
[Secure your IoT solution from the ground up][lnk-securing]
Use the Azure IoT Gateway SDK to send device-to-
cloud messages with a physical device (Linux)
1/18/2017 • 11 min to read • Edit on GitHub

This walkthrough of the Bluetooth low energy sample shows you how to use the Azure IoT Gateway SDK to
forward device-to-cloud telemetry to IoT Hub from a physical device and how to route commands from IoT Hub to
a physical device.
This walkthrough covers:
Architecture: important architectural information about the Bluetooth low energy sample.
Build and run: the steps required to build and run the sample.

Architecture
The walkthrough shows you how to build and run an IoT Gateway on a Raspberry Pi 3 that runs Raspbian Linux.
The gateway is built using the IoT Gateway SDK. The sample uses a Texas Instruments SensorTag Bluetooth Low
Energy (BLE) device to collect temperature data.
When you run the gateway it:
Connects to a SensorTag device using the Bluetooth Low Energy (BLE) protocol.
Connects to IoT Hub using the HTTP protocol.
Forwards telemetry from the SensorTag device to IoT Hub.
Routes commands from IoT Hub to the SensorTag device.
The gateway contains the following modules:
A BLE module that interfaces with a BLE device to receive temperature data from the device and send
commands to the device.
A BLE Cloud to Device module that translates the JSON messages coming from the cloud into BLE instructions
for the BLE module.
A logger module that logs all gateway messages to a local file.
An identity mapping module that translates between BLE device MAC addresses and Azure IoT Hub device
identities.
An IoT Hub module that uploads telemetry data to an IoT hub and receives device commands from an IoT hub.
A BLE printer module that interprets telemetry from the BLE device and prints formatted data to the console to
enable troubleshooting and debugging.
How data flows through the Gateway
The following block diagram illustrates the telemetry upload data flow pipeline:
The steps that an item of telemetry takes traveling from a BLE device to IoT Hub are:
1. The BLE device generates a temperature sample and sends it over Bluetooth to the BLE module in the gateway.
2. The BLE module receives the sample and publishes it to the broker along with the MAC address of the device.
3. The identity mapping module picks up this message and uses an internal table to translate the MAC address of
the device into an IoT Hub device identity (a device ID and device key). It then publishes a new message that
contains the temperature sample data, the MAC address of the device, the device ID, and the device key.
4. The IoT Hub module receives this new message (generated by the identity mapping module) and publishes it to
IoT Hub.
5. The logger module logs all messages from the broker to a local file.
The following block diagram illustrates the device command data flow pipeline:

1. The IoT Hub module periodically polls the IoT hub for new command messages.
2. When the IoT Hub module receives a new command message, it publishes it to the broker.
3. The identity mapping module picks up the command message and uses an internal table to translate the IoT
Hub device ID to a device MAC address. It then publishes a new message that includes the MAC address of the
target device in the properties map of the message.
4. The BLE Cloud-to-Device module picks up this message and translates it into the proper BLE instruction for the
BLE module. It then publishes a new message.
5. The BLE module picks up this message and executes the I/O instruction by communicating with the BLE device.
6. The logger module logs all messages from the broker to a disk file.

Prepare your hardware

This tutorial assumes you are using a Texas Instruments SensorTag device connected to a Raspberry Pi 3 running
Raspbian.
Install Raspbian
You can use either of the following options to install Raspbian on your Raspberry Pi 3 device.
Use NOOBS, a graphical user interface, to install the latest version of Raspbian.
Manually download and write the latest image of the Raspbian operating system to a SD card.
Install BlueZ 5.37
The BLE modules talk to the Bluetooth hardware via the BlueZ stack. You need version 5.37 of BlueZ for the
modules to work correctly. These instructions make sure the correct version of BlueZ is installed.
1. Stop the current bluetooth daemon:

sudo systemctl stop bluetooth

2. Install the BlueZ dependencies.

sudo apt-get update

sudo apt-get install bluetooth bluez-tools build-essential autoconf glib2.0 libglib2.0-dev libdbus-1-
dev libudev-dev libical-dev libreadline-dev

3. Download the BlueZ source code from bluez.org.

wget http://www.kernel.org/pub/linux/bluetooth/bluez-5.37.tar.xz

4. Unzip the source code.

tar -xvf bluez-5.37.tar.xz

5. Change directories to the newly created folder.

cd bluez-5.37

6. Configure the BlueZ code to be built.

./configure --disable-udev --disable-systemd --enable-experimental

7. Build BlueZ.

make

8. Install BlueZ once it is done building.

sudo make install

9. Change systemd service configuration for bluetooth so it points to the new bluetooth daemon in the file
/lib/systemd/system/bluetooth.service . Replace the 'ExecStart' line with the following text:
ExecStart=/usr/local/libexec/bluetooth/bluetoothd -E

Enable connectivity to the SensorTag device from your Raspberry Pi 3 device

Before running the sample, you need to verify that your Raspberry Pi 3 can connect to the SensorTag device.
1. Ensure the rfkill utility is installed.

sudo apt-get install rfkill

2. Unblock bluetooth on the Raspberry Pi 3 and check that the version number is 5.37.

sudo rfkill unblock bluetooth

bluetoothctl --version

3. Start the bluetooth service and execute the bluetoothctl command to enter an interactive bluetooth shell.

sudo systemctl start bluetooth

bluetoothctl

4. Enter the command power on to power up the bluetooth controller. You should see output similar to:

[NEW] Controller 98:4F:EE:04:1F:DF C3 raspberrypi [default]

5. While still in the interactive bluetooth shell, enter the command scan on to scan for bluetooth devices. You
should see output similar to:

Discovery started
[CHG] Controller 98:4F:EE:04:1F:DF Discovering: yes

6. Make the SensorTag device discoverable by pressing the small button (the green LED should flash). The
Raspberry Pi 3 should discover the SensorTag device:

[NEW] Device A0:E6:F8:B5:F6:00 CC2650 SensorTag

[CHG] Device A0:E6:F8:B5:F6:00 TxPower: 0
[CHG] Device A0:E6:F8:B5:F6:00 RSSI: -43

In this example, you can see that the MAC address of the SensorTag device is A0:E6:F8:B5:F6:00.
7. Turn off scanning by entering the scan off command.

[CHG] Controller 98:4F:EE:04:1F:DF Discovering: no

Discovery stopped

8. Connect to your SensorTag device using its MAC address by entering connect <MAC address>. Note that
the sample output below is abbreviated:
Attempting to connect to A0:E6:F8:B5:F6:00
[CHG] Device A0:E6:F8:B5:F6:00 Connected: yes
Connection successful
[CHG] Device A0:E6:F8:B5:F6:00 UUIDs: 00001800-0000-1000-8000-00805f9b34fb
...
[NEW] Primary Service
/org/bluez/hci0/dev_A0_E6_F8_B5_F6_00/service000c
Device Information
...
[CHG] Device A0:E6:F8:B5:F6:00 GattServices: /org/bluez/hci0/dev_A0_E6_F8_B5_F6_00/service000c
...
[CHG] Device A0:E6:F8:B5:F6:00 Name: SensorTag 2.0
[CHG] Device A0:E6:F8:B5:F6:00 Alias: SensorTag 2.0
[CHG] Device A0:E6:F8:B5:F6:00 Modalias: bluetooth:v000Dp0000d0110

Note that you can list the GATT characteristics of the device again using the list-attributes command.

9. You can now disconnect from the device using the disconnect command and then exit from the bluetooth
shell using the quit command:

Attempting to disconnect from A0:E6:F8:B5:F6:00

Successful disconnected
[CHG] Device A0:E6:F8:B5:F6:00 Connected: no

You're now ready to run the BLE Gateway sample on your Raspberry Pi 3.

Run the BLE Gateway sample

To run the BLE sample, you need to complete three tasks:
Configure two sample devices in your IoT Hub.
Build the IoT Gateway SDK on your Raspberry Pi 3 device.
Configure and run the BLE sample on your Raspberry Pi 3 device.
At the time of writing, the IoT Gateway SDK only supports gateways that use BLE modules on Linux.
Configure two sample devices in your IoT Hub
Create an IoT hub in your Azure subscription, you will need the name of your hub to complete this walkthrough.
If you don't have an account, you can create a free account in just a couple of minutes.
Add one device called SensorTag_01 to your IoT hub and make a note of its id and device key. You can use the
device explorer or iothub-explorer tools to add this device to the IoT hub you created in the previous step and
to retrieve its key. You will map this device to the SensorTag device when you configure the gateway.
Build the Azure IoT Gateway SDK on your Raspberry Pi 3
Install dependencies for the Azure IoT Gateway SDK.

sudo apt-get install cmake uuid-dev curl libcurl4-openssl-dev libssl-dev

Use the following commands to clone the IoT Gateway SDK and all its submodules to your home directory:

cd ~
git clone --recursive https://github.com/Azure/azure-iot-gateway-sdk.git
cd azure-iot-gateway-sdk
git submodule update --init --recursive
When you have a complete copy of the IoT Gateway SDK repository on your Raspberry Pi 3, you can build it using
the following command from the folder that contains the SDK

./tools/build.sh

Configure and run the BLE sample on your Raspberry Pi 3

To bootstrap and run the sample, you need to configure each module that participates in the gateway. This
configuration is provided in a JSON file and you need to configure all five participating modules. There is a sample
JSON file provided in the repository called gateway_sample.json which you can use as the starting point for
building your own configuration file. This file is in the samples/ble_gateway/src folder in local copy of the IoT
Gateway SDK repository.
The following sections describe how to edit this configuration file for the BLE sample and assume that the IoT
Gateway SDK repository is in the /home/pi/azure-iot-gateway-sdk/ folder on your Raspberry Pi 3. If the
repository is elsewhere, you should adjust the paths accordingly:
Logger configuration
Assuming the gateway repository is located in the folder /home/pi/azure-iot-gateway-sdk/, configure the
logger module as follows:

{
"name": "Logger",
"loader": {
"name" : "native",
"entrypoint" : {
"module.path" : "build/modules/logger/liblogger.so"
}
},
"args":
{
"filename": "<</path/to/log-file.log>>"
}
}

BLE module configuration

The sample configuration for the BLE device assumes a Texas Instruments SensorTag device. Any standard BLE
device that can operate as a GATT peripheral should work but you will need to update the GATT characteristic IDs
and data (for write instructions). Add the MAC address of your SensorTag device:
{
"name": "SensorTag",
"loader": {
"name" : "native",
"entrypoint" : {
"module.path": "build/modules/ble/libble.so"
}
},
"args": {
"controller_index": 0,
"device_mac_address": "<<AA:BB:CC:DD:EE:FF>>",
"instructions": [
{
"type": "read_once",
"characteristic_uuid": "00002A24-0000-1000-8000-00805F9B34FB"
},
{
"type": "read_once",
"characteristic_uuid": "00002A25-0000-1000-8000-00805F9B34FB"
},
{
"type": "read_once",
"characteristic_uuid": "00002A26-0000-1000-8000-00805F9B34FB"
},
{
"type": "read_once",
"characteristic_uuid": "00002A27-0000-1000-8000-00805F9B34FB"
},
{
"type": "read_once",
"characteristic_uuid": "00002A28-0000-1000-8000-00805F9B34FB"
},
{
"type": "read_once",
"characteristic_uuid": "00002A29-0000-1000-8000-00805F9B34FB"
},
{
"type": "write_at_init",
"characteristic_uuid": "F000AA02-0451-4000-B000-000000000000",
"data": "AQ=="
},
{
"type": "read_periodic",
"characteristic_uuid": "F000AA01-0451-4000-B000-000000000000",
"interval_in_ms": 1000
},
{
"type": "write_at_exit",
"characteristic_uuid": "F000AA02-0451-4000-B000-000000000000",
"data": "AA=="
}
]
}
}

IoT Hub module

Add the name of your IoT Hub. The suffix value is typically azure-devices.net:
{
"name": "IoTHub",
"loader": {
"name" : "native",
"entrypoint" : {
"module.path": "build/modules/iothub/libiothub.so"
}
},
"args": {
"IoTHubName": "<<Azure IoT Hub Name>>",
"IoTHubSuffix": "<<Azure IoT Hub Suffix>>",
"Transport" : "amqp"
}
}

Identity mapping module configuration

Add the MAC address of your SensorTag device and the device ID and key of the SensorTag_01 device you added
to your IoT Hub:

{
"name": "mapping",
"loader": {
"name" : "native",
"entrypoint" : {
"module.path": "build/modules/identitymap/libidentity_map.so"
}
},
"args": [
{
"macAddress": "AA:BB:CC:DD:EE:FF",
"deviceId": "<<Azure IoT Hub Device ID>>",
"deviceKey": "<<Azure IoT Hub Device Key>>"
}
]
}

BLE Printer module configuration

{
"name": "BLE Printer",
"loader": {
"name" : "native",
"entrypoint" : {
"module.path": "build/samples/ble_gateway/ble_printer/libble_printer.so"
}
},
"args": null
}

BLEC2D Module Configuration

{
"name": "BLEC2D",
"loader": {
"name" : "native",
"entrypoint" : {
"module.path": "build/modules/ble/libble_c2d.so"
}
},
"args": null
}
Routing Configuration
The following configuration ensures the following:
The Logger module receives and logs all messages.
The SensorTag module sends messages to both the mapping and BLE Printer modules.
The mapping module sends messages to the IoTHub module to be sent up to your IoT Hub.
The IoTHub module sends messages back to the mapping module.
The mapping module sends messages to the BLEC2D module.
The BLEC2D module sends messages back to the Sensor Tag module.

"links" : [
{"source" : "*", "sink" : "Logger" },
{"source" : "SensorTag", "sink" : "mapping" },
{"source" : "SensorTag", "sink" : "BLE Printer" },
{"source" : "mapping", "sink" : "IoTHub" },
{"source" : "IoTHub", "sink" : "mapping" },
{"source" : "mapping", "sink" : "BLEC2D" },
{"source" : "BLEC2D", "sink" : "SensorTag"}
]

To run the sample, pass the path to the JSON configuration file to the ble_gateway binary. If you used the
gateway_sample.json file, the command is below. Execute this command from the azure-iot-gateway-sdk
directory

./build/samples/ble_gateway/ble_gateway ./samples/ble_gateway/src/gateway_sample.json

You may need to press the small button on the SensorTag device to make it discoverable before you run the
sample.
When you run the sample, you can use the device explorer or iothub-explorer tool to monitor the messages the
gateway forwards from the SensorTag device.

Send cloud-to-device messages

The BLE module also supports sending instructions from Azure IoT Hub to the device. You can use the device
explorer or the iothub-explorer tool to send JSON messages that the BLE gateway module passes on to the BLE
device. If you are using the Texas Instruments SensorTag device then you can turn on the red LED, green LED, or
buzzer by sending commands from IoT Hub. To do this, first send the following two JSON messages in order. Then
you can send any of the commands to turn on the lights or buzzer.
1. Reset all LEDs and the buzzer (turn them off):

{
"type": "write_once",
"characteristic_uuid": "F000AA65-0451-4000-B000-000000000000",
"data": "AA=="
}

2. Configure I/O as 'remote':

{
"type": "write_once",
"characteristic_uuid": "F000AA66-0451-4000-B000-000000000000",
"data": "AQ=="
}
Then you can send any of the following commands to turn on the lights or buzzer.
Turn on the red LED:

{
"type": "write_once",
"characteristic_uuid": "F000AA65-0451-4000-B000-000000000000",
"data": "AQ=="
}

Turn on the green LED:

{
"type": "write_once",
"characteristic_uuid": "F000AA65-0451-4000-B000-000000000000",
"data": "Ag=="
}

Turn on the buzzer:

{
"type": "write_once",
"characteristic_uuid": "F000AA65-0451-4000-B000-000000000000",
"data": "BA=="
}

Next Steps
If you want to gain a more advanced understanding of the IoT Gateway SDK and experiment with some code
examples, visit the following developer tutorials and resources:
Azure IoT Gateway SDK
To further explore the capabilities of IoT Hub, see:
IoT Hub developer guide