Table of Contents

Overview
IoT architecture concepts
Compare Azure IoT options
Preconfigured solutions overview
Get started
Remote monitoring
Deploy the preconfigured solution
Operate the preconfigured solution
Remote monitoring (previous version)
What are the preconfigured solutions?
FAQ
Get Started
How-to guides
Predictive maintenance
Predictive maintenance solution overview
Predictive maintenance solution walkthrough
Connected factory
Connected factory solution overview
Connected factory solution walkthrough
Device simulation
Deploy device simulation
Explore device simulation
How-to guides
Remote monitoring
Perform advanced monitoring
Use rules to detect issues
Manage your devices
Troubleshoot device issues
Use simulated devices
 Customize the solution
Deploy using the CLI
Connect a physical device
Concepts
Connected factory
Deploy a gateway for connected factory
Customize connected factory
Use the OPC publisher for connected factory
Configure connected factory
Permissions on azureiotsuite.com
Reference
Developer Reference Guide
Developer Troubleshooting Guide
Security architecture
Security best practices
Secure your IoT deployment
Security from the ground up
Related
Stream Analytics
Event Hubs
IoT Hub
Microsoft IoT Central
Machine Learning
Resources
Azure Roadmap
FAQ
Connected factory FAQ
IoT Suite learning path
 Azure and the Internet of Things
11/10/2017 • 4 min to read • Edit Online

Welcome to Microsoft Azure and the Internet of Things (IoT). This article describes the common characteristics of
an IoT solution in the cloud. IoT solutions require secure, bidirectional communication between devices, possibly
numbering in the millions, and a solution back end. For example, a solution might use automated, predictive
analytics to uncover insights from your device-to-cloud event stream.

IoT solution architecture

The following diagram shows the key elements of a typical IoT solution architecture. The diagram is agnostic of the
specific implementation details such as the Azure services used, and device operating systems. 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. These back-end services can deliver data to:
Other line-of-business applications.
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 an IoT solution architecture, devices typically send telemetry to the cloud for storage and processing. For
example, 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. In the same example, 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.
This procedure makes sure the maintenance engineer could get started as soon as she arrives.
Connecting devices securely and reliably is often the biggest challenge in IoT solutions. This is because IoT devices
have different characteristics as compared to other clients such as browsers and mobile apps. Specifically, IoT
devices:
Are often embedded systems with no human operator (unlike a phone).
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 previous constraints, any IoT solution must also be scalable, secure, and reliable.
Depending on the communication protocol and network availability, a device can either communicate directly, or
through an intermediate gateway, with the cloud. IoT architectures often have a mix of these two communication
patterns.
Data processing and analytics
In modern IoT solutions, data processing can occur in the cloud or on the device side. Device-side processing is
referred as Edge computing. The choice of where to process data depends on factors such as:
Network constraints. If bandwidth between the devices and the cloud is limited, there is an incentive to do
more edge processing.
Response time. If there is a requirement to act on a device in near real time, it may be better to process the
response in the device itself. For example, a robot arm that needs to be stopped in an emergency.
Regulatory environment. Some data cannot be sent to the cloud.
In general, data processing both in the edge and in the cloud are a combination of the following capabilities:
Receiving telemetry at scale from your devices and determining how to process and store that data.
Analyzing the telemetry to provide insights, whether they are in real time or after the fact.
Sending commands from the cloud or a gateway device to a specific device.
Additionally, an IoT cloud back end should provide:
Device registration capabilities that enable you to:
Provision devices.
Control which devices are permitted to connect to your infrastructure.
Device management to control the state of your devices and monitor their activities.
For example, in a predictive maintenance scenario, the cloud back-end stores historical telemetry data. The
solution uses this data to identify potential anomalous behavior on specific pumps before they cause a real
problem. Using data analytics, it can identify that the preventative solution is to send a command back to the
device to take a corrective action. This process generates an automated feedback loop between the device and the
cloud that greatly increases the solution efficiency.
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, a predictive maintenance solution can integrate with a scheduling system to
book an engineer to visit a pumping station when it identifies a pump in need of maintenance.

Next steps
Now that you have learned about the typical IoT Architecture, explore the different implementation options using
Microsoft Azure IoT products in Microsoft Azure IoT options.
To find out more about the individual Azure IoT services, see:
What is Azure IoT Suite?
What is Microsoft IoT Central?
What is Azure IoT Hub?
 Compare Azure IoT options
1/17/2018 • 2 min to read • Edit Online

The article Azure and the Internet of Things describes a typical IoT solution architecture with the following layers:
Device connectivity and management
Data processing and analytics
Presentation and business integration
To implement this architecture, Azure IoT offers several options, each appropriate for different sets of customer
requirements:
Azure IoT Suite is an enterprise-grade collection of preconfigured solutions built on Azure Platform-as-a-
Service (PaaS) that enable you to accelerate the development of custom IoT solutions.
Microsoft IoT Central is a Software-as-a-Service (SaaS) solution that uses a model-based approach to
enable you to build enterprise-grade IoT solutions without requiring cloud solution development expertise.

Azure IoT Hub

Azure IoT Hub is the core Azure PaaS that both Microsoft IoT Central and Azure IoT Suite use. IoT Hub enables
reliable and securely bidirectional communications between millions of IoT devices and a cloud solution. IoT Hub
helps you meet IoT implementation challenges such as:
High-volume device connectivity and management.
High-volume telemetry ingestion.
Command and control of devices.
Device security enforcement.

Compare Azure IoT Suite and Microsoft IoT Central

Choosing your Azure IoT product is a critical part of planning your IoT solution. IoT Hub is an individual Azure
service that doesn't, by itself, provide an end-to-end IoT solution. IoT Hub can be used as a starting point for any
IoT solution, and you don’t need to use Azure IoT Suite or Microsoft IoT Central to use it. Both Azure IoT Suite and
Microsoft IoT Central use IoT Hub along with other Azure services. The following table summarizes the key
differences between Azure IoT Suite and Microsoft IoT Central to help you choose the correct one for your
requirements:

Primary usage To accelerate development of a custom To accelerate time to market for

IoT solution that needs maximum straightforward IoT solutions that don’t
flexibility. require deep service customization.

Access to underlying PaaS services You have access to the underlying SaaS. Fully managed solution, the
Azure services to manage them, or underlying services aren't exposed.
replace them as needed.
 Flexibility High. The code for the microservices is Medium. You can use the built-in
open source and you can modify it in browser-based user experience to
any way you see fit. Additionally, you customize the solution model and
can customize the deployment aspects of the UI. The infrastructure is
infrastructure. not customizable because the different
components are not exposed.

Skill level Medium-High. You need Java or .NET Low. You need modeling skills to
skills to customize the solution back customize the solution. No coding skills
end. You need JavaScript skills to are required.
customize the visualization.

Get started experience Preconfigured solutions implement Application templates and device
common IoT scenarios. Can be templates provide pre-built models.
deployed in minutes. Can be deployed in minutes.

Pricing You can fine-tune the services to Simple, predictable pricing structure.
control the cost.

The decision of which product to use to build your IoT solution is ultimately determined by:
Your business requirements.
The type of solution you want to build
Your organization's skill set for building and maintaining the solution in the long term.

Next steps
Based on your chosen product and approach, the suggested next steps are:
: What are the Azure IoT preconfigured solutions?
: Microsoft IoT Central.
: Overview of the Azure IoT Hub service.
 What is Azure IoT Suite?
1/17/2018 • 5 min to read • Edit Online

Azure IoT Suite is a set of preconfigured solutions that:

Deploy in minutes
Help you get started quickly
You can customize to meet your specific requirements
The IoT Suite preconfigured solutions are all designed according to the same principles and goals.
The following video presents an overview of the remote monitoring preconfigured solution:

Preconfigured solutions overview

A preconfigured solution is open source implementation of a common IoT solution patterns that you can deploy
to Azure using your subscription. Each preconfigured solution combines custom code and Azure services to
implement a specific IoT scenario or scenarios. You can customize any of the scenarios to meet your specific
requirements. These scenarios include:
Visualize data on a rich dashboard for deep insights and solution status.
Configure rules and alarms over live IoT device telemetry.
Schedule device management jobs, such as updates to software and configuration.
Provision your own custom physical or simulated devices.
Troubleshoot and remediate issues within your IoT device groups.
Each preconfigured solution is a complete, end-to-end implementation that can use simulated or physical devices
to generate telemetry. You can use the preconfigured solutions as solution accelerators to:
Provide a starting point for your own IoT solutions.
Learn about common patterns in IoT solution design and development.
Three preconfigured solutions are available today:
Remote monitoring
Predictive maintenance
Connected factory
The following table shows how the solutions map to specific IoT features:
 Remote Yes Yes Yes - Yes Yes -
monitoring

Predictive Yes Yes - - Yes Yes Yes

maintenanc
e

Connected Yes - - Yes Yes Yes -

factory

Data ingestion: Ingress of data at scale to the cloud.

Device identity: Manage unique device identities and control device access to the solution.
Device management: Manage device metadata and perform operations such as device reboots and firmware
upgrades.
Command and control: To cause the device to take an action, send messages to a device from the cloud.
Rules and actions: To act on specific device-to-cloud data, the solution back end uses rules.
Predictive analytics: The solution back end analyzes device-to-cloud data to predict when specific actions
should take place. For example, analyzing aircraft engine telemetry to determine when engine maintenance is
due.

NOTE
To deploy a preconfigured solution and learn more about how to customize them, visit Microsoft Azure IoT Suite.

Azure services
When you deploy a preconfigured solution, the provisioning process configures a number of Azure services. The
following table shows the services used in the preconfigured solutions:

IoT Hub Yes Yes

Event Hubs Yes

Time Series Insights Yes

Container Services Yes

Stream Analytics Yes

Web Apps Yes Yes Yes

Cosmos DB Yes Yes

Azure Storage Yes Yes

 NOTE
For more information about the resources deployed in the remote monitoring preconfigured solution, see this article on
GitHub.

Azure IoT Hub. This service provides the device-to-cloud and cloud-to-device messaging capabilities and acts
as the gateway to the cloud and the other key IoT Suite services. The service enables you to receive messages
from your devices at scale, and send commands to your devices. The service also enables you to manage your
devices. For example, you can configure, reboot, or perform a factory reset on one or more devices connected
to the hub.
Azure Event Hubs. This service provides high-volume event ingestion to the cloud. See Comparison of Azure
IoT Hub and Azure Event Hubs.
Azure Time Series Insights. The preconfigured solutions use this service to analyze and display the telemetry
data from your devices.
Azure Container Service. This service hosts and manages the microservices in the preconfigured solutions.
Azure Cosmos DB and Azure Storage for data storage.
Azure Stream Analytics. The predictive maintenance preconfigured solution uses this service to process
incoming telemetry, perform aggregation, and detect events. This preconfigured solution also uses stream
analytics to process informational messages that contain data such as metadata or command responses from
devices.
Azure Web Apps to host the custom application code in the preconfigured solutions.
For an overview of the architecture of a typical IoT solution, see Microsoft Azure and the Internet of Things (IoT).

What's new in preconfigured solutions?

Microsoft is updating the preconfigured solutions to a new microservices-based architecture. The following table
shows the current status of the preconfigured solutions:

Remote monitoring Microservices Java and .NET

Predictive maintenance MVC .NET

Connected factory MVC .NET

The following sections describe what's new in the microservices-based preconfigured solutions:
Microservices
The new version of the remote monitoring preconfigured solution uses a microservices architecture. This
preconfigured solution is composed of multiple microservices such as an IoT Hub manager and a Storage
manager. Both Java and .NET versions of each microservice are available to download, along with related
developer documentation. For more information about the microservices, see Remote monitoring architecture.
This microservices architecture is a proven pattern for cloud solutions that:
Is scalable.
Enables extensibility.
Is easy to understand.
Enables individual services to be swapped out for alternatives.
 TIP
To learn more about microservice architectures, see .NET Application Architecture and Microservices: An application
revolution powered by the cloud.

When you deploy the new version of remote monitoring, you must select one of the following deployment
options:
Reduced cost version for a demonstration or to test a deployment. All the microservices deploy to a
single Azure virtual machine.
Expanded infrastructure deployment for developing a production deployment. The Azure Container
Service deploys the microservices to multiple Azure virtual machines. Kubernetes orchestrates the Docker
containers that host the individual microservices.
Language choices: Java and .NET
Implementations of each of the microservices are available in both Java and .NET. Like the .NET code, the Java
source code is open source and available for you to customize to your specific requirements:
Remote monitoring .NET GitHub repository
Remote monitoring Java GitHub repository
If you'd like to see other language implementations, add a request to Azure IoT user voice.
React user interface framework
The UI is built using the React javascript library. The source code is open source and available for you to
download and customize.

Next steps
Now that you have an overview of the IoT Suite preconfigured solutions, here are suggested next steps for each
of the preconfigured solutions:
Explore the Azure IoT Suite remote monitoring solution Resource Manager deployment model.
Predictive maintenance preconfigured solution overview.
Get started with the connected factory preconfigured solution.
For more information about IoT solution architectures, see Microsoft Azure IoT services: Reference Architecture.
 Deploy the remote monitoring preconfigured
solution
12/13/2017 • 1 min to read • Edit Online

This tutorial shows you how to provision the remote monitoring preconfigured solution. You deploy the solution
from azureiotsuite.com. You can also deploy the solution using the CLI, to learn about this option see Deploy a
preconfigured solution from the command line.
In this tutorial, you learn how to:
Configure the preconfigured solution
Deploy the preconfigured solution
Sign in to the preconfigured solution

Prerequisites
To complete this tutorial, you need an active Azure subscription.
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure
Free Trial.

Deploy the preconfigured solution

Before you deploy the preconfigured solution to your Azure subscription, you must choose some configuration
options:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a new solution:

2. Click on the tile.

3. On the page, enter a for your remote monitoring
preconfigured solution.
4. Select a or deployment. If you are deploying the solution to learn how it works or to run a
demonstration, choose the option to minimize costs.
5. Choose either or as the language. All the microservices are available as either Java or .NET
implementations.
6. Review the panel for more information about your configuration choices.
7. Select the and you want to use to provision the solution.
8. Click to begin the provisioning process. This process typically takes several minutes to
run:
For troubleshooting information, see What to do when a deployment fails in the GitHub repository.

Sign in to the preconfigured solution

When the provisioning process is complete, you can sign in to your remote monitoring preconfigured solution.
1. On the page, choose your new remote monitoring solution:
2. You can view information about your remote monitoring solution in the panel that appears. Choose
to connect to your remote monitoring solution.

NOTE
You can delete your remote monitoring solution from this panel when you are finished with it.
3. The remote monitoring solution dashboard displays in your browser.

Next steps
In this tutorial, you learned how to:
Configure the preconfigured solution
Deploy the preconfigured solution
Sign in to the preconfigured solution
Now that you have deployed the remote monitoring solution, the next step is to explore the capabilities of the
solution dashboard.
 Explore the capabilities of the remote monitoring
preconfigured solution
12/13/2017 • 8 min to read • Edit Online

This tutorial shows you the key capabilities of the remote monitoring solution. To introduce these capabilities, the
tutorial showcases common customer scenarios using a simulated IoT application for a company called Contoso.
The tutorial helps you understand the typical IoT scenarios the remote monitoring solution provides out-of-the-
box.
In this tutorial, you learn how to:
Visualize and filter devices on the dashboard
Respond to an alarm
Update the firmware in your devices
Organize your assets

Prerequisites
To complete this tutorial, you need a deployed instance of the remote monitoring solution in your Azure
subscription.
If you haven't deployed the remote monitoring solution yet, you should complete the Deploy the remote
monitoring preconfigured solution tutorial.

The Contoso sample IoT deployment

You can use the Contoso sample IoT deployment to understand the basic scenarios the remote monitoring
solution provides out-of-the-box. These scenarios are based on real-life IoT deployments. Most likely, you will
choose to customize the remote monitoring solution to meet your specific requirements, but the Contoso sample
helps you learn the basics.

NOTE
If you used the CLI to deploy the preconfigured solution, the file
contains information about deployment such as the URL to access the deployed sample.

The Contoso sample provisions a set of simulated devices and rules to act on them. Once you understand the
basic scenarios, you can continue exploring more of the solution features in Perform advanced device monitoring
using the remote monitoring solution.
Contoso is a company that manages a variety of assets in different environments. Contoso plans to use the power
of cloud-based IoT applications to remotely monitor and manage multiple assets from a centralized application.
The following sections provide a summary of the initial configuration of the Contoso sample:
 NOTE
The Contoso demo is only one way to provision simulated devices and create rules. Other provisioning options include the
creation of your own custom devices. To learn more about how to create your own devices and rules, see Manage and
configure your devices and Detect issues using threshold-based rules.

Contoso devices
Contoso uses different types of smart devices. These devices fulfill different roles for the company, sending
various telemetry streams. Additionally, each device type has different device properties and supported methods.
The following table shows a summary of the provisioned device types:

Chiller Temperature, Type, Firmware Location, Floor, Reboot, Firmware

Humidity, Pressure version, Model Campus Update, Emergency
Valve Release,
Increase Pressure

Prototyping device Temperature, Type, Firmware Location, Mode Reboot, Firmware

Pressure, Geo- version, Model Update, Move device,
location Stop device,
Temperature release,
Temperature increase

Engine Tank fuel level, Type, Firmware Location, Floor, Restart, Firmware
Coolant sensor, version, Model Campus Update, Empty tank,
Vibration Fill tank

Truck Geo-location, Speed, Type, Firmware Location, Load Lower cargo

Cargo temperature version, Model temperature, Increase
cargo temperature,
Firmware update

Elevator Floor, Vibration, Type, Firmware Location, Campus Stop elevator, Start
Temperature version, Model, Geo- elevator, Firmware
location update

NOTE
The Contoso demo sample provisions two devices per type. For each type, one functions correctly within the boundaries
defined as normal by Contoso, and the one has some kind of malfunctioning. In the next section, you learn about the rules
that Contoso defines for the devices. These rules define the boundaries of correct behavior.

Contoso rules
Operators at Contoso know the thresholds that determine whether a device is working correctly. For example, a
chiller is not working correctly if the pressure that it reports is greater than 250 PSI. The following table shows
threshold-based rules Contoso defines for each device type:

Chiller pressure too Alerts if chillers reach P>250 psi Critical Chillers
high higher than normal
pressure levels
 Prototyping device Alerts if prototyping T>80° F Critical Prototyping devices
temp too high devices reach higher
than normal
temperature levels

Engine tank empty Alerts if engine fuel F<5 gallons Info Engines
tank goes empty

Higher than normal Alerts if truck's cargo T<45° F Warning Trucks

cargo temperature temperature is higher
than normal

Elevator vibration Alerts if elevator V<0.1 mm Warning Elevators

stopped stops completely
(based on vibration
level)

Operate the Contoso sample deployment

You have now seen the initial setup in the Contoso sample. The following sections describe three scenarios in the
Contoso sample that illustrate how an operator might use the preconfigured solution.

Respond to a pressure alarm

This scenario shows you how to identify and respond to an alarm that's triggered by a chiller device. The chiller is
located in Redmond, in building 43, floor 2.
As an operator, you see in the dashboard that there's an alarm related to the pressure of a chiller. You can pan
and zoom on the map to see more detail.
1. On the page, in the grid, you can see the alarm.
The chiller is also highlighted on the map:

2. To view the device details and telemetry, click the highlighted chiller on the map. The telemetry shows a
pressure spike:
3. Close .
4. To navigate to the page, choose on the navigation menu.
On the page, you can view the details of the rule that triggered the chiller pressure alarm.
1. The list of notifications shows the number of times the alarm has triggered, acknowledgments, and open
and closed alarms:

2. The first alarm in the list is the most recent one. Click the alarm to view the associated
devices and telemetry. The telemetry shows a pressure spike for the chiller:
You have now identified the issue that triggered the alarm and the associated device. As an operator, the next
steps are to acknowledge the alarm and mitigate the issue.
1. To indicate that you are now working on the alarm, change the to :

2. To act on the chiller, select it and then choose . Select , add a job name
 , and choose . These settings create a job that executes immediately:

3. To view the job status, return to the page and view the list of jobs in the view. You can
see the job has run to release the valve pressure on the chiller:

Finally, confirm that the telemetry values from the chiller are back to normal.
1. To view the alarms grid, navigate to the page.
2. To view the device telemetry, select the device for the original alarm on the map, and confirm that is back
to normal.
3. To close the incident, navigate to the page, select the alarm, and set the status to :
Update device firmware
Contoso is testing a new type of device in the field. As part of the testing cycle, you need to ensure that device
firmware updates work correctly. The following steps show you how to use the remote monitoring solution to
update the firmware on multiple devices.
To perform the necessary device management tasks, use the page. Start by filtering for all prototyping
devices:
1. Navigate to the page. Choose the filter in the drop-down:
 TIP
Click to manage the available filters.

2. Select one of the prototyping devices:

3. Click the button and then choose . Enter values for and
. Choose to schedule the job to run now:

NOTE
With the simulated devices you can use any URL you like as the value. The simulated devices do not
access the URL.
4. Note how many devices the job affects and choose :

You can use the page to track the job as it runs.

1. To view the list of jobs, navigate to the page and click .
2. Locate the event related to the job you created. Verify that the firmware update process was initiated
correctly.
You can create a filter to verify the firmware version updated correctly.
1. To create a filter, navigate to the page and select :

2. Create a filter that includes only devices with the new firmware version:
3. Return to the page and verify that the device has the new firmware version.

Organize your assets

Contoso has two different teams for field service activities:
The Smart Building team manages chillers, elevators, and engines.
The Smart Vehicle team manages trucks and prototyping devices.
To make it easier as an operator to organize and manage your devices, you want to tag them with the appropriate
team name.
You can create tag names to use with devices.
1. To display all the devices, navigate to the page and choose the filter:

2. Select the and devices. Then choose :

3. Choose and then create a new text tag called with a value . Choose a
name for the job. Then click :

4. Select the , , and devices. Then choose :

5. Choose and then create a new text tag called with a value . Choose a
name for the job. Then click :

You can use the tag values to create filters.

1. On the page, choose :
2. Create a new filter that uses the tag name and value . Save the filter as
.
3. Create a new filter that uses the tag name and value . Save the filter as
.
Now the Contoso operator can query devices based on the operating team without the need to change anything
on the devices.

Next steps
In this tutorial, you learned to:
Visualize and filter devices on the dashboard
Respond to an alarm
Update the firmware in your devices
Organize your assets
Now that you have explored the remote monitoring solution, the suggested next steps are to learn about the
advanced features of the remote monitoring solution:
Monitor your devices.
Manage your devices.
Automate your solution with rules.
Maintain your solution.
 What are the Azure IoT Suite preconfigured
solutions?
11/6/2017 • 7 min to read • Edit Online

The Azure IoT Suite preconfigured solutions are implementations of common IoT solution patterns that you can
deploy to Azure using your subscription. You can use the preconfigured solutions:
As a starting point for your own IoT solutions.
To learn about common patterns in IoT solution design and development.
Each preconfigured solution is a complete, end-to-end implementation that uses simulated devices to generate
telemetry.
You can download the complete source code to customize and extend the solution to meet your specific IoT
requirements.

NOTE
To deploy one of the preconfigured solutions, visit Microsoft Azure IoT Suite. The article Get started with the IoT
preconfigured solutions provides more information about how to deploy and run one of the solutions.

The following table shows how the solutions map to specific IoT features:

Remote Yes Yes Yes Yes Yes -

monitoring

Predictive Yes Yes - Yes Yes Yes

maintenance

Connected Yes Yes Yes Yes Yes -

factory

Data ingestion: Ingress of data at scale to the cloud.

Device identity: Manage unique device identities and control device access to the solution.
Device management: Manage device metadata and perform operations such as device reboots and firmware
upgrades.
Command and control: To cause the device to take an action, send messages to a device from the cloud.
Rules and actions: To act on specific device-to-cloud data, the solution back end uses rules.
Predictive analytics: The solution back end analyzes device-to-cloud data to predict when specific actions
should take place. For example, analyzing aircraft engine telemetry to determine when engine maintenance is
due.

Remote Monitoring preconfigured solution overview

We have chosen to discuss the remote monitoring preconfigured solution in this article because it illustrates many
common design elements that the other solutions share.
The following diagram illustrates the key elements of the remote monitoring solution. The following sections
provide more information about these elements.

Devices
When you deploy the remote monitoring preconfigured solution, four simulated devices are pre-provisioned in
the solution that simulate a cooling device. These simulated devices have a built-in temperature and humidity
model that emits telemetry. These simulated devices are included to:
Illustrate the end-to-end flow of data through the solution.
Provide a convenient source of telemetry.
Provide a target for methods or commands if you are a back-end developer using the solution as a starting
point for a custom implementation.
The simulated devices in the solution can respond to the following cloud-to-device communications:
Methods (direct methods): A two-way communication method where a connected device is expected to respond
immediately.
Commands (cloud-to-device messages): A one-way communication method where a device retrieves the
command from a durable queue.
For a comparison of these different approaches, see Cloud-to-device communications guidance.
When a device first connects to IoT Hub in the preconfigured solution, it sends a device information message to
the hub. This message enumerates the methods the device can respond to. In the remote monitoring
preconfigured solution, simulated devices support these methods:
Initiate Firmware Update: this method initiates an asynchronous task on the device to perform a firmware
update. The asynchronous task uses reported properties to deliver status updates to the solution dashboard.
Reboot: this method causes the simulated device to reboot.
FactoryReset: this method triggers a factory reset on the simulated device.
When a device first connects to IoT Hub in the preconfigured solution, it sends a device information message to
the hub. This message enumerates the commands the device can respond to. In the remote monitoring
preconfigured solution, simulated devices support these commands:
Ping Device: The device responds to this command with an acknowledgement. This command is useful for
checking that the device is still active and listening.
Start Telemetry: Instructs the device to start sending telemetry.
Stop Telemetry: Instructs the device to stop sending telemetry.
Change Set Point Temperature: Controls the simulated temperature telemetry values the device sends. This
command is useful for testing back-end logic.
 Diagnostic Telemetry: Controls if the device should send the external temperature as telemetry.
Change Device State: Sets the device state metadata property that the device reports. This command is useful
for testing back-end logic.
You can add more simulated devices to the solution that emit the same telemetry and respond to the same
methods and commands.
In addition to responding to commands and methods, the solution uses device twins. Devices use device twins to
report property values to the solution back end. The solution dashboard uses device twins to set to new desired
property values on devices. For example, during the firmware update process the simulated device reports the
status of the update using reported properties.

IoT Hub
In this preconfigured solution, the IoT Hub instance corresponds to the Cloud Gateway in a typical IoT solution
architecture.
An IoT hub receives telemetry from the devices at a single endpoint. An IoT hub also maintains device-specific
endpoints where each device can retrieve the commands that are sent to it.
The IoT hub makes the received telemetry available through the service-side telemetry read endpoint.
The device management capability of IoT Hub enables you to manage your device properties from the solution
portal and schedule jobs that perform operations such as:
Rebooting devices
Changing device states
Firmware updates

Azure Stream Analytics

The preconfigured solution uses three Azure Stream Analytics (ASA) jobs to filter the telemetry stream from the
devices:
DeviceInfo job - outputs data to an Event hub that routes device registration-specific messages to the solution
device registry. This device registry is an Azure Cosmos DB database. These messages are sent when a device
first connects or in response to a command.
Telemetry job - sends all raw telemetry to Azure blob storage for cold storage and calculates telemetry
aggregations that display in the solution dashboard.
Rules job - filters the telemetry stream for values that exceed any rule thresholds and outputs the data to an
Event hub. When a rule fires, the solution portal dashboard view displays this event as a new row in the alarm
history table. These rules can also trigger an action based on the settings defined on the and
views in the solution portal.
In this preconfigured solution, the ASA jobs form part of to the in a typical IoT solution
architecture.

Event processor
In this preconfigured solution, the event processor forms part of the in a typical IoT
solution architecture.
The and ASA jobs send their output to Event hubs for delivery to other back-end services. The
solution uses an EventProcessorHost instance, running in a WebJob, to read the messages from these Event hubs.
The uses:
 The data to update the device data in the Cosmos DB database.
The data to invoke the Logic app and update the alerts display in the solution portal.

Device identity registry, device twin, and Cosmos DB

Every IoT hub includes a device identity registry that stores device keys. IoT Hub uses this information authenticate
devices - a device must be registered and have a valid key before it can connect to the hub.
A device twin is a JSON document managed by the IoT Hub. A device twin for a device contains:
Reported properties sent by the device to the hub. You can view these properties in the solution portal.
Desired properties that you want to send to the device. You can set these properties in the solution portal.
Tags that exist only in the device twin and not on the device. You can use these tags to filter lists of devices in
the solution portal.
This solution uses device twins to manage device metadata. The solution also uses a Cosmos DB database to store
additional solution-specific device data such as the commands supported by each device and the command
history.
The solution must also keep the information in the device identity registry synchronized with the contents of the
Cosmos DB database. The uses the data from stream analytics job to manage
the synchronization.

Solution portal

The solution portal is a web-based UI that is deployed to the cloud as part of the preconfigured solution. It enables
you to:
View telemetry and alarm history in a dashboard.
Provision new devices.
Manage and monitor devices.
Send commands to specific devices.
Invoke methods on specific devices.
 Manage rules and actions.
Schedule jobs to run on one or more devices.
In this preconfigured solution, the solution portal forms part of the and part of the
in the typical IoT solution architecture.

Next steps
For more information about IoT solution architectures, see Microsoft Azure IoT services: Reference Architecture.
Now you know what a preconfigured solution is, you can get started by deploying the remote monitoring
preconfigured solution: Get started with the preconfigured solutions.
 Frequently asked questions for IoT Suite
1/5/2018 • 4 min to read • Edit Online

See also, the connected factory specific FAQ.

Where can I find the source code for the preconfigured solutions?
The source code is stored in the following GitHub repositories:
Remote monitoring preconfigured solution
Predictive maintenance preconfigured solution
Connected factory preconfigured solution
How do I update to the latest version of the remote monitoring preconfigured solution that uses the IoT Hub
device management features?
If you deploy a preconfigured solution from the https://www.azureiotsuite.com/ site, it always deploys a new
instance of the latest version of the solution.
If you deploy a preconfigured solution using the command line, you can update an existing deployment with
new code. See Cloud deployment in the GitHub repository.
How can I add support for a new device method to the remote monitoring preconfigured solution?
See the section Add support for a new method to the simulator in the Customize a preconfigured solution article.
The simulated device is ignoring my desired property changes, why?
In the remote monitoring preconfigured solution, the simulated device code only uses the
and desired properties to
update the reported properties. All other desired property change requests are ignored.
My device does not appear in the list of devices in the solution dashboard, why?
The list of devices in the solution dashboard uses a query to return the list of devices. Currently, a query cannot
return more than 10K devices. Try making the search criteria for your query more restrictive.
What's the difference between deleting a resource group in the Azure portal and clicking delete on a
preconfigured solution in azureiotsuite.com?
If you delete the preconfigured solution in azureiotsuite.com, you delete all the resources that were
provisioned when you created the preconfigured solution. If you added additional resources to the resource
group, these resources are also deleted.
If you delete the resource group in the Azure portal, you only delete the resources in that resource group. You
also need to delete the Azure Active Directory application associated with the preconfigured solution in the
Azure portal.
How many IoT Hub instances can I provision in a subscription?
By default you can provision 10 IoT hubs per subscription. You can create an Azure support ticket to raise this
limit. As a result, since every preconfigured solution provisions a new IoT Hub, you can only provision up to 10
preconfigured solutions in a given subscription.
How many Azure Cosmos DB instances can I provision in a subscription?
Fifty. You can create an Azure support ticket to raise this limit, but by default, you can only provision 50 Cosmos
DB instances per subscription.
How many Free Bing Maps APIs can I provision in a subscription?
Two. You can create only two Internal Transactions Level 1 Bing Maps for Enterprise plans in an Azure
subscription. The remote monitoring solution is provisioned by default with the Internal Transactions Level 1
plan. As a result, you can only provision up to two remote monitoring solutions in a subscription with no
modifications.
I have a remote monitoring solution deployment with a static map, how do I add an interactive Bing map?
1. Get your Bing Maps API for Enterprise QueryKey from Azure portal:
a. Navigate to the Resource Group where your Bing Maps API for Enterprise is in the Azure portal.
b. Click , then .
c. You can see two keys: and . Copy the value for .

NOTE
Don't have a Bing Maps API for Enterprise account? Create one in the Azure portal by clicking + New,
searching for Bing Maps API for Enterprise and follow prompts to create.

2. Pull down the latest code from the Azure-IoT-Remote-Monitoring.

3. Run a local or cloud deployment following the command-line deployment guidance in the /docs/ folder in the
repository.
4. After you've run a local or cloud deployment, look in your root folder for the *.user.config file created during
deployment. Open this file in a text editor.
5. Change the following line to include the value you copied from your :

Can I create a preconfigured solution if I have Microsoft Azure for DreamSpark?

NOTE
Microsoft Azure for DreamSpark is now known as Microsoft Imagine for students.

Currently, you cannot create a preconfigured solution with a Microsoft Azure for DreamSpark account. However,
you can create a free trial account for Azure in just a couple of minutes that enables you create a preconfigured
solution.
Can I create a preconfigured solution if I have Cloud Solution Provider (CSP) subscription?
Currently, you cannot create a preconfigured solution with a Cloud Solution Provider (CSP) subscription.
However, you can create a free trial account for Azure in just a couple of minutes that enables you create a
preconfigured solution.
How do I delete an Azure AD tenant?
See Eric Golpe's blog post Walkthrough of Deleting an Azure AD Tenant.
Next steps
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Connected factory preconfigured solution overview
IoT security from the ground up
 Get started with the preconfigured solutions
11/6/2017 • 14 min to read • Edit Online

Azure IoT Suite preconfigured solutions combine multiple Azure IoT services to deliver end-to-end solutions that
implement common IoT business scenarios. The remote monitoring preconfigured solution connects to and
monitors your devices. You can use the solution to analyze the stream of data from your devices and to improve
business outcomes by making processes respond automatically to that stream of data.
This tutorial shows you how to provision the remote monitoring preconfigured solution. It also walks you through
the basic features of the preconfigured solution. You can access many of these features from the solution
dashboard that deploys as part of the preconfigured solution:

To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Provision the solution

If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User Voice.

Scenario overview
When you deploy the remote monitoring preconfigured solution, it is prepopulated with resources that enable you
to step through a common remote monitoring scenario. In this scenario, several devices connected to the solution
are reporting unexpected temperature values. The following sections show you how to:
Identify the devices sending unexpected temperature values.
Configure these devices to send more detailed telemetry.
Fix the problem by updating the firmware on these devices.
Verify that your action has resolved the issue.
A key feature of this scenario is that you can perform all these actions remotely from the solution dashboard. You
do not need physical access to the devices.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. For example, you can view telemetry, add
devices, and configure rules.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your remote monitoring solution portal in a new tab.
2. By default, the solution portal shows the dashboard. You can navigate to other areas of the solution portal
using the menu on the left-hand side of the page.

The dashboard displays the following information:

A map that displays the location of each device connected to the solution. When you first run the solution, there
are 25 simulated devices. The simulated devices are implemented as Azure WebJobs, and the solution uses the
Bing Maps API to plot information on the map. See the FAQ to learn how to make the map dynamic.
A panel that plots humidity and temperature telemetry from a selected device in near real
 time and displays aggregate data such as maximum, minimum, and average humidity.
An panel that shows recent alarm events when a telemetry value has exceeded a threshold. You
can define your own alarms in addition to the examples created by the preconfigured solution.
A panel that displays information about scheduled jobs. You can schedule your own jobs on
page.

View alarms
The alarm history panel shows you that five devices are reporting higher than expected telemetry values.

NOTE
These alarms are generated by a rule that is included in the preconfigured solution. This rule generates an alert when the
temperature value sent by a device exceeds 60. You can define your own rules and actions by choosing Rules and Actions in
the left-hand menu.

View devices
The devices list shows all the registered devices in the solution. From the device list you can view and edit device
metadata, add or remove devices, and invoke methods on devices. You can filter and sort the list of devices in the
device list. You can also customize the columns shown in the device list.
1. Choose to show the device list for this solution.
2. The device list initially shows 25 simulated devices created by the provisioning process. You can add
additional simulated and physical devices to the solution.
3. To view the details of a device, choose a device in the device list.

The panel contains six sections:

 A collection of links that enable you to customize the device icon, disable the device, add a rule, invoke a
method, or send a command. For a comparison of commands (device-to-cloud messages) and methods (direct
methods), see Cloud-to-device communications guidance.
The section enables you to edit tag values for the device. You can display tag values in the
device list and use tag values to filter the device list.
The section enables you to set property values to be sent to the device.
The section shows property values sent from the device.
The section shows information from the identity registry such as the device id and
authentication keys.
The section shows information about any jobs that have recently targeted this device.

Filter the device list

You can use a filter to display only those devices that are sending unexpected temperature values. The remote
monitoring preconfigured solution includes the filter to show devices with a mean
temperature value greater than 60. You can also create your own filters.
1. Choose to display a list of available filters. Then choose to apply the
filter:

2. The device list now shows only devices with a mean temperature value greater than 60.

Update desired properties

You have now identified a set of devices that may need remediation. However, you decide that the data frequency
of 15 seconds is not sufficient for a clear diagnosis of the issue. Changing the telemetry frequency to five seconds
to provide you with more data points to better diagnose the issue. You can push this configuration change to your
remote devices from the solution portal. You can make the change once, evaluate the impact, and then act on the
results.
Follow these steps to run a job that changes the desired property for the affected devices.
When the devices receive the new property value, they change their configuration to send
telemetry every five seconds instead of every 15 seconds:
1. While you are showing the list of unhealthy devices in the device list, choose , then
.
2. Call the job .
3. Change the value of the name to five seconds.
4. Choose .

5. You can monitor the progress of the job on the page in the portal.

NOTE
If you want to change a desired property value for an individual device, use the section in the
panel instead of running a job.

This job sets the value of the desired property in the device twin for all the devices selected by
the filter. The devices retrieve this value from the device twin and update their behavior. When a device retrieves
and processes a desired property from a device twin, it sets the corresponding reported value property.

Invoke methods
While the job runs, you notice in the list of unhealthy devices that all these devices have old (less than version 1.6)
firmware versions.

This firmware version may be the root cause of the unexpected temperature values because you know that other
healthy devices were recently updated to version 2.0. You can use the built-in filter to
identify any devices with old firmware versions. From the portal, you can then remotely update all the devices still
running old firmware versions:
1. Choose to display a list of available filters. Then choose to apply
the filter:

2. The device list now shows only devices with old firmware versions. This list includes the five devices
identified by the filter and three additional devices:

3. Choose , then .
4. Set to .
5. Choose as the .
6. Set the parameter to .
7. Choose . The default is for the job to run now.

NOTE
If you want to invoke a method on an individual device, choose in the panel instead of running a
job.

This job invokes the direct method on all the devices selected by the filter. Devices
respond immediately to IoT Hub and then initiate the firmware update process asynchronously. The devices
provide status information about the firmware update process through reported property values, as shown in the
following screenshots. Choose the icon to update the information in the device and job lists:
 NOTE
In a production environment, you can schedule jobs to run during a designated maintenance window.

Scenario review
In this scenario, you identified a potential issue with some of your remote devices using the alarm history on the
dashboard and a filter. You then used the filter and a job to remotely configure the devices to provide more
information to help diagnose the issue. Finally, you used a filter and a job to schedule maintenance on the affected
devices. If you return to the dashboard, you can check that there are no longer any alarms coming from devices in
your solution. You can use a filter to verify that the firmware is up-to-date on all the devices in your solution and
that there are no more unhealthy devices:

Other features
The following sections describe some additional features of the remote monitoring preconfigured solution that are
not described as part of the previous scenario.
Customize columns
You can customize the information shown in the device list by choosing . You can add and remove
columns that display reported property and tag values. You can also reorder and rename columns:

Customize the device icon

You can customize the device icon displayed in the device list from the panel as follows:
1. Choose the pencil icon to open the panel for a device:
2. Either upload a new image or use one of the existing images and then choose :

3. The image you selected now displays in the column for the device.

NOTE
The image is stored in blob storage. A tag in the device twin contains a link to the image in blob storage.

Add a device
When you deploy the preconfigured solution, you automatically provision 25 sample devices that you can see in
the device list. These devices are simulated devices running in an Azure WebJob. Simulated devices make it easy
for you to experiment with the preconfigured solution without the need to deploy real, physical devices. If you do
want to connect a real device to the solution, see the Connect your device to the remote monitoring preconfigured
solution tutorial.
The following steps show you how to add a simulated device to the solution:
1. Navigate back to the device list.
2. To add a device, choose in the bottom left corner.

3. Choose on the tile.

 In addition to creating a new simulated device, you can also add a physical device if you choose to create a
. To learn more about connecting physical devices to the solution, see Connect your device
to the IoT Suite remote monitoring preconfigured solution.
4. Select , and enter a unique device ID name such as .
5. Choose .
6. In step 3 of , choose to return to the device list.
7. You can view your device in the device list.

8. You can also view the simulated telemetry from your new device on the dashboard:
Disable and delete a device
You can disable a device, and after it is disabled you can remove it:

Add a rule
There are no rules for the new device you just added. In this section, you add a rule that triggers an alarm when the
temperature reported by the new device exceeds 47 degrees. Before you start, notice that the telemetry history for
the new device on the dashboard shows the device temperature never exceeds 45 degrees.
1. Navigate back to the device list.
2. To add a rule for the device, select your new device in the , and then choose .
3. Create a rule that uses as the data field and uses as the output when the
temperature exceeds 47 degrees:
4. To save your changes, choose .
5. Choose in the device details pane for the new device.

6. Select from the command list and set to 45. Then choose
:
7. Navigate back to the dashboard. After a short time, you will see a new entry in the pane
when the temperature reported by your new device exceeds the 47-degree threshold:

8. You can review and edit all your rules on the page of the dashboard:
9. You can review and edit all the actions that can be taken in response to a rule on the page of the
dashboard:

NOTE
It is possible to define actions that can send an email message or SMS in response to a rule or integrate with a line-of-
business system through a Logic App. For more information, see the Connect Logic App to your Azure IoT Suite Remote
Monitoring preconfigured solution.

Manage filters
In the device list, you can create, save, and reload filters to display a customized list of devices connected to your
hub. To create a filter:
1. Choose the edit filter icon above the list of devices:
2. In the , add the fields, operators, and values to filter the device list. You can add multiple
clauses to refine your filter. Choose to apply the filter:

3. In this example, the list is filtered by manufacturer and model number:

4. To save your filter with a custom name, choose the icon:

5. To reapply a filter you saved previously, choose the icon:

You can create filters based on device id, device state, desired properties, reported properties, and tags. You add
your own custom tags to a device in the section of the panel, or run a job to update tags on
multiple devices.

NOTE
In the , you can use the to edit the query text directly.

Commands
From the panel, you can send commands to the device. When a device first starts, it sends
information about the commands it supports to the solution. For a discussion of the differences between
commands and methods, see Azure IoT Hub cloud-to-device options.
1. Choose in the panel for the selected device:
2. Select from the command list.
3. Choose .
4. You can see the status of the command in the command history.

The solution tracks the status of each command it sends. Initially the result is . When the device reports
that it has executed the command, the result is set to .

Behind the scenes

When you deploy a preconfigured solution, the deployment process creates multiple resources in the Azure
subscription you selected. You can view these resources in the Azure portal. The deployment process creates a
with a name based on the name you choose for your preconfigured solution:
You can view the settings of each resource by selecting it in the list of resources in the resource group.
You can also view the source code for the preconfigured solution. The remote monitoring preconfigured solution
source code is in the azure-iot-remote-monitoring GitHub repository:
The folder contains the source code for the dashboard.
The folder contains the source code for the simulated device.
The folder contains the source code for the back-end process that handles the incoming
telemetry.
When you are done, you can delete the preconfigured solution from your Azure subscription on the
azureiotsuite.com site. This site enables you to easily delete all the resources that were provisioned when you
created the preconfigured solution.

NOTE
To ensure that you delete everything related to the preconfigured solution, delete it on the azureiotsuite.com site and do
not delete the resource group in the portal.

Next Steps
Now that you’ve deployed a working preconfigured solution, you can continue getting started with IoT Suite by
reading the following articles:
Remote monitoring preconfigured solution walkthrough
Connect your device to the remote monitoring preconfigured solution
Permissions on the azureiotsuite.com site
 Permissions on the azureiotsuite.com site
12/18/2017 • 6 min to read • Edit Online

What happens when you sign in

The first time you sign in at azureiotsuite.com, the site determines the permission levels you have based on the
currently selected Azure Active Directory (AAD) tenant and Azure subscription.
1. First, to populate the list of tenants seen next to your username, the site finds out from Azure which AAD
tenants you belong to. Currently, the site can only obtain user tokens for one tenant at a time. Therefore,
when you switch tenants using the dropdown in the top right corner, the site logs you in to that tenant to
obtain the tokens for that tenant.
2. Next, the site finds out from Azure which subscriptions you have associated with the selected tenant. You
see the available subscriptions when you create a new preconfigured solution.
3. Finally, the site retrieves all the resources in the subscriptions and resource groups tagged as
preconfigured solutions and populates the tiles on the home page.
The following sections describe the roles that control access to the preconfigured solutions.

AAD roles
The AAD roles control the ability provision preconfigured solutions and manage users in a preconfigured
solution.
You can find more information about administrator roles in AAD in Assigning administrator roles in Azure AD.
The current article focuses on the and the directory roles as used by the
preconfigured solutions.
Global administrator
There can be many global administrators per AAD tenant:
When you create an AAD tenant, you are by default the global administrator of that tenant.
The global administrator can provision a preconfigured solution and is assigned an role for the
application inside their AAD tenant.
If another user in the same AAD tenant creates an application, the default role granted to the global
administrator is .
A global administrator can assign users to roles for applications using the Azure portal.
Domain user
There can be many domain users per AAD tenant:
A domain user can provision a preconfigured solution through the azureiotsuite.com site. By default, the
domain user is granted the role in the provisioned application.
A domain user can create an application using the build.cmd script in the azure-iot-remote-monitoring, azure-
iot-predictive-maintenance, or azure-iot-connected-factory repository. However, the default role granted to
the domain user is , because a domain user does not have permission to assign roles.
If another user in the AAD tenant creates an application, the domain user is assigned the role by
default for that application.
A domain user cannot assign roles for applications; therefore a domain user cannot add users or roles for
users for an application even if they provisioned it.
Guest User
There can be many guest users per AAD tenant. Guest users have a limited set of rights in the AAD tenant. As a
result, guest users cannot provision a preconfigured solution in the AAD tenant.
For more information about users and roles in AAD, see the following resources:
Create users in Azure AD
Assign users to apps

Azure subscription administrator roles

The Azure admin roles control the ability to map an Azure subscription to an AD tenant.
Find out more about the Azure admin roles in the article How to add or change Azure Co-Administrator, Service
Administrator, and Account Administrator.

Application roles
The application roles control access to devices in your preconfigured solution.
There are two defined roles and one implicit role defined in a provisioned application:
Has full control to add, manage, remove devices, and modify settings.
Can view devices, rules, actions, jobs, and telemetry.
You can find the permissions assigned to each role in the RolePermissions.cs source file.
Changing application roles for a user
You can use the following procedure to make a user in your Active Directory an administrator of your
preconfigured solution.
You must be an AAD global administrator to change roles for a user:
1. Go to the Azure portal.
2. Select .
3. Make sure you are using the directory you chose on azureiotsuite.com when you provisioned your solution. If
you have multiple directories associated with your subscription, you can switch between them if you click
your account name at the top-right of the portal.
4. Click , then .
5. Show with status. Then search for an application with name of your preconfigured
solution.
6. Click the name of the application that matches your preconfigured solution name.
7. Click .
8. Select the user you want to switch roles.
9. Click and select the role (such as ) you'd like to assign to the user, click the check mark.

FAQ
I'm a service administrator and I'd like to change the directory mapping between my subscription and a
specific AAD tenant. How do I complete this task?
See To add an existing subscription to your Azure AD directory
I'm a domain user/member on the AAD tenant and I've created a preconfigured solution. How do I get
assigned a role for my application?
Ask a global administrator to make you a global administrator on the AAD tenant and then assign roles to users
yourself. Alternatively, ask a global administrator to assign you a role directly. If you'd like to change the AAD
tenant your preconfigured solution has been deployed to, see the next question.
How do I switch the AAD tenant my remote monitoring preconfigured solution and application are assigned
to?
You can run a cloud deployment from https://github.com/Azure/azure-iot-remote-monitoring and redeploy with
a newly created AAD tenant. Because you are, by default, a global administrator when you create an AAD tenant,
you have permissions to add users and assign roles to those users.
1. Create an AAD directory in the Azure portal.
2. Go to https://github.com/Azure/azure-iot-remote-monitoring.
3. Run (For
example, )
4. When prompted, set the to be your newly created tenant instead of your previous tenant.
I want to change a Service Administrator or Co-Administrator when logged in with an organisational account
See the support article Changing Service Administrator and Co-Administrator when logged in with an
organisational account.
Why am I seeing this error? "Your account does not have the proper permissions to create a solution. Please
check with your account administrator or try with a different account."
Look at the following diagram for guidance:
 NOTE
If you continue to see the error after validating you are a global administrator on the AAD tenant and a co-administrator
on the subscription, have your account administrator remove the user and reassign necessary permissions in this order.
First, add the user as a global administrator and then add user as a co-administrator on the Azure subscription. If issues
persist, contact Help & Support.

Why am I seeing this error when I have an Azure subscription? "An Azure subscription is required to create
pre-configured solutions. You can create a free trial account in just a couple of minutes."
If you're certain you have an Azure subscription, validate the tenant mapping for your subscription and ensure
the correct tenant is selected in the dropdown. If you’ve validated the desired tenant is correct, follow the
preceding diagram and validate the mapping of your subscription and this AAD tenant.

Next steps
To continue learning about IoT Suite, see how you can customize a preconfigured solution.
 Remote monitoring preconfigured solution
walkthrough
11/6/2017 • 9 min to read • Edit Online

The IoT Suite remote monitoring preconfigured solution is an implementation of an end-to-end monitoring
solution for multiple machines running in remote locations. The solution combines key Azure services to provide a
generic implementation of the business scenario. You can use the solution as a starting point for your own
implementation and customize it to meet your own specific business requirements.
This article walks you through some of the key elements of the remote monitoring solution to enable you to
understand how it works. This knowledge helps you to:
Troubleshoot issues in the solution.
Plan how to customize to the solution to meet your own specific requirements.
Design your own IoT solution that uses Azure services.

Logical architecture
The following diagram outlines the logical components of the preconfigured solution:

Simulated devices
In the preconfigured solution, the simulated device represents a cooling device (such as a building air conditioner
or facility air handling unit). When you deploy the preconfigured solution, you also automatically provision four
simulated devices that run in an Azure WebJob. The simulated devices make it easy for you to explore the behavior
of the solution without the need to deploy any physical devices. To deploy a real physical device, see the Connect
your device to the remote monitoring preconfigured solution tutorial.
Device-to-cloud messages
Each simulated device can send the following message types to IoT Hub:

Startup When the device starts, it sends a message

containing information about itself to the back end. This data
includes the device id and a list of the commands and
methods the device supports.

Presence A device periodically sends a message to report

whether the device can sense the presence of a sensor.

Telemetry A device periodically sends a message that reports

simulated values for the temperature and humidity collected
from the device's simulated sensors.

NOTE
The solution stores the list of commands supported by the device in a Cosmos DB database and not in the device twin.

Properties and device twins

The simulated devices send the following device properties to the twin in the IoT hub as reported properties. The
device sends reported properties at startup and in response to a command or method.

Config.TelemetryInterval Frequency (seconds) the device sends telemetry

Config.TemperatureMeanValue Specifies the mean value for the simulated temperature

telemetry

Device.DeviceID Id that is either provided or assigned when a device is created

in the solution

Device.DeviceState State reported by the device

Device.CreatedTime Time the device was created in the solution

Device.StartupTime Time the device was started

Device.LastDesiredPropertyChange The version number of the last desired property change

Device.Location.Latitude Latitude location of the device

Device.Location.Longitude Longitude location of the device

System.Manufacturer Device manufacturer

System.ModelNumber Model number of the device

System.SerialNumber Serial number of the device

 System.FirmwareVersion Current version of firmware on the device

System.Platform Platform architecture of the device

System.Processor Processor running the device

System.InstalledRAM Amount of RAM installed on the device

The simulator seeds these properties in simulated devices with sample values. Each time the simulator initializes a
simulated device, the device reports the pre-defined metadata to IoT Hub as reported properties. Reported
properties can only be updated by the device. To change a reported property, you set a desired property in
solution portal. It is the responsibility of the device to:
1. Periodically retrieve desired properties from the IoT hub.
2. Update its configuration with the desired property value.
3. Send the new value back to the hub as a reported property.
From the solution dashboard, you can use desired properties to set properties on a device by using the device twin.
Typically, a device reads a desired property value from the hub to update its internal state and report the change
back as a reported property.

NOTE
The simulated device code only uses the and
desired properties to update the reported properties sent back to IoT Hub. All other
desired property change requests are ignored in the simulated device.

Methods
The simulated devices can handle the following methods (direct methods) invoked from the solution portal
through the IoT hub:

InitiateFirmwareUpdate Instructs the device to perform a firmware update

Reboot Instructs the device to reboot

FactoryReset Instructs the device to perform a factory reset

Some methods use reported properties to report on progress. For example, the method
simulates running the update asynchronously on the device. The method returns immediately on the device, while
the asynchronous task continues to send status updates back to the solution dashboard using reported properties.
Commands
The simulated devices can handle the following commands (cloud-to-device messages) sent from the solution
portal through the IoT hub:

PingDevice Sends a ping to the device to check it is alive

 StartTelemetry Starts the device sending telemetry

StopTelemetry Stops the device from sending telemetry

ChangeSetPointTemp Changes the set point value around which the random data is
generated

DiagnosticTelemetry Triggers the device simulator to send an additional telemetry

value (externalTemp)

ChangeDeviceState Changes an extended state property for the device and sends
the device info message from the device

NOTE
For a comparison of these commands (cloud-to-device messages) and methods (direct methods), see Cloud-to-device
communications guidance.

IoT Hub
The IoT hub ingests data sent from the devices into the cloud and makes it available to the Azure Stream Analytics
(ASA) jobs. Each stream ASA job uses a separate IoT Hub consumer group to read the stream of messages from
your devices.
The IoT hub in the solution also:
Maintains an identity registry that stores the ids and authentication keys of all the devices permitted to connect
to the portal. You can enable and disable devices through the identity registry.
Sends commands to your devices on behalf of the solution portal.
Invokes methods on your devices on behalf of the solution portal.
Maintains device twins for all registered devices. A device twin stores the property values reported by a device.
A device twin also stores desired properties, set in the solution portal, for the device to retrieve when it next
connects.
Schedules jobs to set properties for multiple devices or invoke methods on multiple devices.

Azure Stream Analytics

In the remote monitoring solution, Azure Stream Analytics (ASA) dispatches device messages received by the IoT
hub to other back-end components for processing or storage. Different ASA jobs perform specific functions based
on the content of the messages.
filters device information messages from the incoming message stream and sends them to an
Event Hub endpoint. A device sends device information messages at startup and in response to a
command. This job uses the following query definition to identify messages:

This job sends its output to an Event Hub for further processing.
evaluates incoming temperature and humidity telemetry values against per-device thresholds.
Threshold values are set in the rules editor available in the solution portal. Each device/value pair is stored by
timestamp in a blob which Stream Analytics reads in as . The job compares any non-empty value
against the set threshold for the device. If it exceeds the '>' condition, the job outputs an event that indicates
that the threshold is exceeded and provides the device, value, and timestamp values. This job uses the following
query definition to identify telemetry messages that should trigger an alarm:

The job sends its output to an Event Hub for further processing and saves details of each alert to blob storage from
where the solution portal can read the alert information.
operates on the incoming device telemetry stream in two ways. The first sends all telemetry
messages from the devices to persistent blob storage for long-term storage. The second computes average,
minimum, and maximum humidity values over a five-minute sliding window and sends this data to blob storage.
The solution portal reads the telemetry data from blob storage to populate the charts. This job uses the following
query definition:
Event Hubs
The and ASA jobs output their data to Event Hubs to reliably forward on to the
running in the WebJob.

Azure storage
The solution uses Azure blob storage to persist all the raw and summarized telemetry data from the devices in the
solution. The portal reads the telemetry data from blob storage to populate the charts. To display alerts, the
solution portal reads the data from blob storage that records when telemetry values exceeded the configured
threshold values. The solution also uses blob storage to record the threshold values you set in the solution portal.

WebJobs
In addition to hosting the device simulators, the WebJobs in the solution also host the running in
an Azure WebJob that handles command responses. It uses command response messages to update the device
command history (stored in the Cosmos DB database).

Cosmos DB
The solution uses a Cosmos DB database to store information about the devices connected to the solution. This
information includes the history of commands sent to devices from the solution portal and of methods invoked
from the solution portal.

Solution portal
The solution portal is a web app deployed as part of the preconfigured solution. The key pages in the solution
portal are the dashboard and the device list.
Dashboard
This page in the web app uses PowerBI javascript controls (See PowerBI-visuals repo) to visualize the telemetry
data from the devices. The solution uses the ASA telemetry job to write the telemetry data to blob storage.
Device list
From this page in the solution portal you can:
Provision a new device. This action sets the unique device id and generates the authentication key. It writes
information about the device to both the IoT Hub identity registry and the solution-specific Cosmos DB
database.
Manage device properties. This action includes viewing existing properties and updating with new properties.
Send commands to a device.
View the command history for a device.
Enable and disable devices.

Next steps
The following TechNet blog posts provide more detail about the remote monitoring preconfigured solution:
IoT Suite - Under The Hood - Remote Monitoring
IoT Suite - Remote Monitoring - Adding Live and Simulated Devices
You can continue getting started with IoT Suite by reading the following articles:
Connect your device to the remote monitoring preconfigured solution
Permissions on the azureiotsuite.com site
 Connect your Microsoft Azure IoT Raspberry Pi 3
Starter Kit to the remote monitoring solution
11/6/2017 • 1 min to read • Edit Online

The tutorials in this section help you learn how to connect a Raspberry Pi 3 device to the remote monitoring
solution. Choose the tutorial appropriate to your preferred programming language and the whether you have the
sensor hardware available to use with your Raspberry Pi.

The tutorials

Simulated telemetry (Basic) Simulates sensor data. Uses a C, Node.js

standalone Raspberry Pi.

Real sensor (Intermediate) Uses data from a BME280 sensor C, Node.js

connected to your Raspberry Pi.

Implement firmware update (Advanced) Uses data from a BME280 sensor C, Node.js
connected to your Raspberry Pi. Enables
remote firmware updates on your
Raspberry Pi.

Next steps
Visit the Azure IoT Dev Center for more samples and documentation on Azure IoT.
 Connect your Raspberry Pi 3 to the remote
monitoring solution and send simulated telemetry
using C
11/6/2017 • 8 min to read • Edit Online

This tutorial shows you how to use the Raspberry Pi 3 to simulate temperature and humidity data to send to the
cloud. The tutorial uses:
Raspbian OS, the C programming language, and the Microsoft Azure IoT SDK for C to implement a sample
device.
The IoT Suite remote monitoring preconfigured solution as the cloud-based back end.

Overview
In this tutorial, you complete the following steps:
Deploy an instance of the remote monitoring preconfigured solution to your Azure subscription. This step
automatically deploys and configures multiple Azure services.
Set up your device to communicate with your computer and the remote monitoring solution.
Update the sample device code to connect to the remote monitoring solution, and send simulated telemetry
that you can view on the solution dashboard.

Prerequisites
To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Required software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
Provision the solution
If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User Voice.

WARNING
The remote monitoring solution provisions a set of Azure services in your Azure subscription. The deployment reflects a real
enterprise architecture. To avoid unnecessary Azure consumption charges, delete your instance of the preconfigured solution
at azureiotsuite.com when you have finished with it. If you need the preconfigured solution again, you can easily recreate it.
For more information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT
Suite preconfigured solutions for demo purposes.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. For example, you can view telemetry, add
devices, and invoke methods.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your remote monitoring solution portal in a new tab.
2. By default, the solution portal shows the dashboard. You can navigate to other areas of the solution portal
using the menu on the left-hand side of the page.

Add a device
For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
If you haven't already done so, add a custom device to your remote monitoring solution. Complete the following
steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .

2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify you

haven't already used the name in your solution, and then click to provision the device.
4. Make a note the device credentials ( , , and ). Your client
application on the Raspberry Pi needs these values to connect to the remote monitoring solution. Then click
.

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now
receive telemetry from your device and invoke methods on the device.

Prepare your Raspberry Pi

Install Raspbian
If this is the first time you are using your Raspberry Pi, you need to install the Raspbian operating system using
NOOBS on the SD card included in the kit. The Raspberry Pi Software Guide describes how to install an operating
system on your Raspberry Pi. This tutorial assumes you have installed the Raspbian operating system on your
Raspberry Pi.

NOTE
The SD card included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 already has NOOBS installed. You can boot the
Raspberry Pi from this card and choose to install the Raspbian OS.

To complete the hardware setup, you need to:

Connect your Raspberry Pi to the power supply included in the kit.
Connect your Raspberry Pi to your network using the Ethernet cable included in your kit. Alternatively, you can
set up Wireless Connectivity for your Raspberry Pi.
You have now completed the hardware setup of your Raspberry Pi.
Sign in and access the terminal
You have two options to access a terminal environment on your Raspberry Pi:
If you have a keyboard and monitor connected to your Raspberry Pi, you can use the Raspbian GUI to
access a terminal window.
Access the command line on your Raspberry Pi using SSH from your desktop machine.
Use a terminal Window in the GUI
The default credentials for Raspbian are username and password . In the task bar in the GUI, you can
launch the utility using the icon that looks like a monitor.
Sign in with SSH
You can use SSH for command-line access to your Raspberry Pi. The article SSH (Secure Shell) describes how to
configure SSH on your Raspberry Pi, and how to connect from Windows or Linux & Mac OS.
Sign in with username and password .
Optional: Share a folder on your Raspberry Pi
Optionally, you may want to share a folder on your Raspberry Pi with your desktop environment. Sharing a folder
enables you to use your preferred desktop text editor (such as Visual Studio Code or Sublime Text) to edit files on
your Raspberry Pi instead of using or .
To share a folder with Windows, configure a Samba server on the Raspberry Pi. Alternatively, use the built-in SFTP
server with an SFTP client on your desktop.

Download and configure the sample

You can now download and configure the remote monitoring client application on your Raspberry Pi.
Clone the repositories
If you haven't already done so, clone the required repositories by running the following commands in a terminal
on your Pi:

Update the device connection string

Open the sample source file in the editor using the following command:
Locate the following lines:

Replace the placeholder values with the device and IoT Hub information you created and saved at the start of this
tutorial. Save your changes ( , ) and exit the editor ( ).

Build the sample

Install the prerequisite packages for the Microsoft Azure IoT Device SDK for C by running the following commands
in a terminal on the Raspberry Pi:

You can now build the updated sample solution on the Raspberry Pi:

You can now run the sample program on the Raspberry Pi. Enter the command:

The following sample output is an example of the output you see at the command prompt on the Raspberry Pi:

Press to exit the program at any time.

View the telemetry
The Raspberry Pi is now sending telemetry to the remote monitoring solution. You can view the telemetry on the
solution dashboard. You can also send messages to your Raspberry Pi from the solution dashboard.
Navigate to the solution dashboard.
Select your device in the dropdown.
The telemetry from the Raspberry Pi displays on the dashboard.

Act on the device

From the solution dashboard, you can invoke methods on your Raspberry Pi. When the Raspberry Pi connects to
the remote monitoring solution, it sends information about the methods it supports.
In the solution dashboard, click to visit the page. Select your Raspberry Pi in the
. Then choose :
 On the page, choose in the dropdown.
Choose . The simulator prints a message in the console on the Raspberry Pi. The app on the
Raspberry Pi sends an acknowledgment back to the solution dashboard:

You can switch the LED on and off using the method with a set to
for on or for off.

WARNING
If you leave the remote monitoring solution running in your Azure account, you are billed for the time it runs. For more
information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT Suite
preconfigured solutions for demo purposes. Delete the preconfigured solution from your Azure account when you have
finished using it.

Next steps
Visit the Azure IoT Dev Center for more samples and documentation on Azure IoT.
 Connect your Raspberry Pi 3 to the remote
monitoring solution and send telemetry from a real
sensor using C
11/6/2017 • 9 min to read • Edit Online

This tutorial shows you how to use the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to develop a temperature
and humidity reader that can communicate with the cloud. The tutorial uses:
Raspbian OS, the C programming language, and the Microsoft Azure IoT SDK for C to implement a sample
device.
The IoT Suite remote monitoring preconfigured solution as the cloud-based back end.

Overview
In this tutorial, you complete the following steps:
Deploy an instance of the remote monitoring preconfigured solution to your Azure subscription. This step
automatically deploys and configures multiple Azure services.
Set up your device and sensors to communicate with your computer and the remote monitoring solution.
Update the sample device code to connect to the remote monitoring solution, and send telemetry that you can
view on the solution dashboard.

Prerequisites
To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Required software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
 BME280 sensor
Breadboard
Jumper wires
Resistors
LEDs

Provision the solution

If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User Voice.

WARNING
The remote monitoring solution provisions a set of Azure services in your Azure subscription. The deployment reflects a real
enterprise architecture. To avoid unnecessary Azure consumption charges, delete your instance of the preconfigured solution
at azureiotsuite.com when you have finished with it. If you need the preconfigured solution again, you can easily recreate it.
For more information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT
Suite preconfigured solutions for demo purposes.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. For example, you can view telemetry, add
devices, and invoke methods.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your remote monitoring solution portal in a new tab.
2. By default, the solution portal shows the dashboard. You can navigate to other areas of the solution portal
using the menu on the left-hand side of the page.

Add a device
For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
If you haven't already done so, add a custom device to your remote monitoring solution. Complete the following
steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .

2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify you

haven't already used the name in your solution, and then click to provision the device.
4. Make a note the device credentials ( , , and ). Your client
application on the Raspberry Pi needs these values to connect to the remote monitoring solution. Then click
.

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now
receive telemetry from your device and invoke methods on the device.

Prepare your Raspberry Pi

Install Raspbian
If this is the first time you are using your Raspberry Pi, you need to install the Raspbian operating system using
NOOBS on the SD card included in the kit. The Raspberry Pi Software Guide describes how to install an operating
system on your Raspberry Pi. This tutorial assumes you have installed the Raspbian operating system on your
Raspberry Pi.

NOTE
The SD card included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 already has NOOBS installed. You can boot the
Raspberry Pi from this card and choose to install the Raspbian OS.

Set up the hardware

This tutorial uses the BME280 sensor included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to generate
telemetry data. It uses an LED to indicate when the Raspberry Pi processes a method invocation from the solution
dashboard.
The components on the bread board are:
Red LED
220-Ohm resistor (red, red, brown)
BME280 sensor
The following diagram shows how to connect your hardware:

The following table summarizes the connections from the Raspberry Pi to the components on the breadboard:

GND (Pin 14) LED -ve pin (18A) Purple

GPCLK0 (Pin 7) Resistor (25A) Orange

 SPI_CE0 (Pin 24) CS (39A) Blue

SPI_SCLK (Pin 23) SCK (36A) Yellow

SPI_MISO (Pin 21) SDO (37A) White

SPI_MOSI (Pin 19) SDI (38A) Green

GND (Pin 6) GND (35A) Black

3.3 V (Pin 1) 3Vo (34A) Red

To complete the hardware setup, you need to:

Connect your Raspberry Pi to the power supply included in the kit.
Connect your Raspberry Pi to your network using the Ethernet cable included in your kit. Alternatively, you can
set up Wireless Connectivity for your Raspberry Pi.
You have now completed the hardware setup of your Raspberry Pi.
Sign in and access the terminal
You have two options to access a terminal environment on your Raspberry Pi:
If you have a keyboard and monitor connected to your Raspberry Pi, you can use the Raspbian GUI to
access a terminal window.
Access the command line on your Raspberry Pi using SSH from your desktop machine.
Use a terminal Window in the GUI
The default credentials for Raspbian are username and password . In the task bar in the GUI, you can
launch the utility using the icon that looks like a monitor.
Sign in with SSH
You can use SSH for command-line access to your Raspberry Pi. The article SSH (Secure Shell) describes how to
configure SSH on your Raspberry Pi, and how to connect from Windows or Linux & Mac OS.
Sign in with username and password .
Optional: Share a folder on your Raspberry Pi
Optionally, you may want to share a folder on your Raspberry Pi with your desktop environment. Sharing a folder
enables you to use your preferred desktop text editor (such as Visual Studio Code or Sublime Text) to edit files on
your Raspberry Pi instead of using or .
To share a folder with Windows, configure a Samba server on the Raspberry Pi. Alternatively, use the built-in SFTP
server with an SFTP client on your desktop.
Enable SPI
Before you can run the sample application, you must enable the Serial Peripheral Interface (SPI) bus on the
Raspberry Pi. The Raspberry Pi communicates with the BME280 sensor device over the SPI bus. Use the following
command to edit the configuration file:

Find the line:

 To uncomment the line, delete the at the start.
Save your changes ( , ) and exit the editor ( ).
To enable SPI, reboot the Raspberry Pi. Rebooting disconnects the terminal, you need to sign in again when
the Raspberry Pi restarts:

Download and configure the sample

You can now download and configure the remote monitoring client application on your Raspberry Pi.
Clone the repositories
If you haven't already done so, clone the required repositories by running the following commands in a terminal
on your Pi:

Update the device connection string

Open the sample source file in the editor using the following command:

Locate the following lines:

Replace the placeholder values with the device and IoT Hub information you created and saved at the start of this
tutorial. Save your changes ( , ) and exit the editor ( ).

Build the sample

Install the prerequisite packages for the Microsoft Azure IoT Device SDK for C by running the following commands
in a terminal on the Raspberry Pi:

You can now build the updated sample solution on the Raspberry Pi:

You can now run the sample program on the Raspberry Pi. Enter the command:
The following sample output is an example of the output you see at the command prompt on the Raspberry Pi:

Press to exit the program at any time.

View the telemetry

The Raspberry Pi is now sending telemetry to the remote monitoring solution. You can view the telemetry on the
solution dashboard. You can also send messages to your Raspberry Pi from the solution dashboard.
Navigate to the solution dashboard.
Select your device in the dropdown.
The telemetry from the Raspberry Pi displays on the dashboard.
Act on the device
From the solution dashboard, you can invoke methods on your Raspberry Pi. When the Raspberry Pi connects to
the remote monitoring solution, it sends information about the methods it supports.
In the solution dashboard, click to visit the page. Select your Raspberry Pi in the
. Then choose :

On the page, choose in the dropdown.

Choose . The LED connected to the Raspberry Pi flashes several times. The app on the
Raspberry Pi sends an acknowledgment back to the solution dashboard:
 You can switch the LED on and off using the method with a set to
for on or for off.

WARNING
If you leave the remote monitoring solution running in your Azure account, you are billed for the time it runs. For more
information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT Suite
preconfigured solutions for demo purposes. Delete the preconfigured solution from your Azure account when you have
finished using it.

Next steps
Visit the Azure IoT Dev Center for more samples and documentation on Azure IoT.
 Connect your Raspberry Pi 3 to the remote
monitoring solution and enable remote firmware
updates using C
11/6/2017 • 10 min to read • Edit Online

This tutorial shows you how to use the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to:
Develop a temperature and humidity reader that can communicate with the cloud.
Enable and perform a remote firmware update to update the client application on the Raspberry Pi.
The tutorial uses:
Raspbian OS, the C programming language, and the Microsoft Azure IoT SDK for C to implement a sample
device.
The IoT Suite remote monitoring preconfigured solution as the cloud-based back end.

Overview
In this tutorial, you complete the following steps:
Deploy an instance of the remote monitoring preconfigured solution to your Azure subscription. This step
automatically deploys and configures multiple Azure services.
Set up your device and sensors to communicate with your computer and the remote monitoring solution.
Update the sample device code to connect to the remote monitoring solution, and send telemetry that you can
view on the solution dashboard.
Use the sample device code to update the client application.

Prerequisites
To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Required software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
 Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
BME280 sensor
Breadboard
Jumper wires
Resistors
LEDs

Provision the solution

If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User Voice.

WARNING
The remote monitoring solution provisions a set of Azure services in your Azure subscription. The deployment reflects a real
enterprise architecture. To avoid unnecessary Azure consumption charges, delete your instance of the preconfigured
solution at azureiotsuite.com when you have finished with it. If you need the preconfigured solution again, you can easily
recreate it. For more information about reducing consumption while the remote monitoring solution runs, see Configuring
Azure IoT Suite preconfigured solutions for demo purposes.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. For example, you can view telemetry, add
devices, and invoke methods.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your remote monitoring solution portal in a new tab.
2. By default, the solution portal shows the dashboard. You can navigate to other areas of the solution portal
using the menu on the left-hand side of the page.

Add a device
For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
If you haven't already done so, add a custom device to your remote monitoring solution. Complete the following
steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .

2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify you

haven't already used the name in your solution, and then click to provision the device.
4. Make a note the device credentials ( , , and ). Your client
application on the Raspberry Pi needs these values to connect to the remote monitoring solution. Then click
.

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now
receive telemetry from your device and invoke methods on the device.

Prepare your Raspberry Pi

Install Raspbian
If this is the first time you are using your Raspberry Pi, you need to install the Raspbian operating system using
NOOBS on the SD card included in the kit. The Raspberry Pi Software Guide describes how to install an operating
system on your Raspberry Pi. This tutorial assumes you have installed the Raspbian operating system on your
Raspberry Pi.

NOTE
The SD card included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 already has NOOBS installed. You can boot the
Raspberry Pi from this card and choose to install the Raspbian OS.

Set up the hardware

This tutorial uses the BME280 sensor included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to generate
telemetry data. It uses an LED to indicate when the Raspberry Pi processes a method invocation from the solution
dashboard.
The components on the bread board are:
Red LED
220-Ohm resistor (red, red, brown)
BME280 sensor
The following diagram shows how to connect your hardware:

The following table summarizes the connections from the Raspberry Pi to the components on the breadboard:

GND (Pin 14) LED -ve pin (18A) Purple

GPCLK0 (Pin 7) Resistor (25A) Orange

 SPI_CE0 (Pin 24) CS (39A) Blue

SPI_SCLK (Pin 23) SCK (36A) Yellow

SPI_MISO (Pin 21) SDO (37A) White

SPI_MOSI (Pin 19) SDI (38A) Green

GND (Pin 6) GND (35A) Black

3.3 V (Pin 1) 3Vo (34A) Red

To complete the hardware setup, you need to:

Connect your Raspberry Pi to the power supply included in the kit.
Connect your Raspberry Pi to your network using the Ethernet cable included in your kit. Alternatively, you can
set up Wireless Connectivity for your Raspberry Pi.
You have now completed the hardware setup of your Raspberry Pi.
Sign in and access the terminal
You have two options to access a terminal environment on your Raspberry Pi:
If you have a keyboard and monitor connected to your Raspberry Pi, you can use the Raspbian GUI to
access a terminal window.
Access the command line on your Raspberry Pi using SSH from your desktop machine.
Use a terminal Window in the GUI
The default credentials for Raspbian are username and password . In the task bar in the GUI, you can
launch the utility using the icon that looks like a monitor.
Sign in with SSH
You can use SSH for command-line access to your Raspberry Pi. The article SSH (Secure Shell) describes how to
configure SSH on your Raspberry Pi, and how to connect from Windows or Linux & Mac OS.
Sign in with username and password .
Optional: Share a folder on your Raspberry Pi
Optionally, you may want to share a folder on your Raspberry Pi with your desktop environment. Sharing a folder
enables you to use your preferred desktop text editor (such as Visual Studio Code or Sublime Text) to edit files on
your Raspberry Pi instead of using or .
To share a folder with Windows, configure a Samba server on the Raspberry Pi. Alternatively, use the built-in SFTP
server with an SFTP client on your desktop.
Enable SPI
Before you can run the sample application, you must enable the Serial Peripheral Interface (SPI) bus on the
Raspberry Pi. The Raspberry Pi communicates with the BME280 sensor device over the SPI bus. Use the following
command to edit the configuration file:

Find the line:

 To uncomment the line, delete the at the start.
Save your changes ( , ) and exit the editor ( ).
To enable SPI, reboot the Raspberry Pi. Rebooting disconnects the terminal, you need to sign in again when
the Raspberry Pi restarts:

Download and configure the sample

You can now download and configure the remote monitoring client application on your Raspberry Pi.
Clone the repositories
If you haven't done so already, clone the required repositories by running the following commands on your Pi:

Update the device connection string

Open the sample configuration file in the editor using the following command:

Replace the placeholder values with the device ID and IoT Hub information you created and saved at the start of
this tutorial.
When you are done, the contents of the deviceinfo file should look like the following example:

Save your changes ( , ) and exit the editor ( ).

Build the sample

If you have not already done so, install the prerequisite packages for the Microsoft Azure IoT Device SDK for C by
running the following commands in a terminal on the Raspberry Pi:

You can now build the sample solution on the Raspberry Pi:

You can now run the sample program on the Raspberry Pi. Enter the command:
The following sample output is an example of the output you see at the command prompt on the Raspberry Pi:

Press to exit the program at any time.

View the telemetry

The Raspberry Pi is now sending telemetry to the remote monitoring solution. You can view the telemetry on the
solution dashboard. You can also send messages to your Raspberry Pi from the solution dashboard.
Navigate to the solution dashboard.
Select your device in the dropdown.
The telemetry from the Raspberry Pi displays on the dashboard.
Initiate the firmware update
The firmware update process downloads and installs an updated version of the device client application on the
Raspberry Pi. For more information about the firmware update process, see the description of the firmware
update pattern in Overview of device management with IoT Hub.
You initiate the firmware update process by invoking a method on the device. This method is asynchronous, and
returns as soon as the update process begins. The device uses reported properties to notify the solution about the
progress of the update.
You invoke methods on your Raspberry Pi from the solution dashboard. When the Raspberry Pi first connects to
the remote monitoring solution, it sends information about the methods it supports.
1. In the solution dashboard, click to visit the page. Select your Raspberry Pi in the
. Then choose :

2. On the page, choose in the dropdown.

3. In the field, enter
. This archive
file contains the implementation of version 2.0 of the firmware.
4. Choose . The app on the Raspberry Pi sends an acknowledgment back to the solution
dashboard. It then starts the firmware update process by downloading the new version of the firmware:

Observe the firmware update process

You can observe the firmware update process as it runs on the device and by viewing the reported properties in
the solution dashboard:
1. You can view the progress in of the update process on the Raspberry Pi:

NOTE
The remote monitoring app restarts silently when the update completes. Use the command to verify it is
running. If you want to terminate the process, use the command with the process id.

2. You can view the status of the firmware update, as reported by the device, in the solution portal. The
following screenshot shows the status and duration of each stage of the update process, and the new
firmware version:
If you navigate back to the dashboard, you can verify the device is still sending telemetry following the
firmware update.
 WARNING
If you leave the remote monitoring solution running in your Azure account, you are billed for the time it runs. For more
information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT Suite
preconfigured solutions for demo purposes. Delete the preconfigured solution from your Azure account when you have
finished using it.

Next steps
Visit the Azure IoT Dev Center for more samples and documentation on Azure IoT.
 Connect your Raspberry Pi 3 to the remote
monitoring solution and send simulated telemetry
using Node.js
11/6/2017 • 8 min to read • Edit Online

This tutorial shows you how to use the Raspberry Pi 3 to simulate temperature and humidity data to send to the
cloud. The tutorial uses:
Raspbian OS, the Node.js programming language, and the Microsoft Azure IoT SDK for Node.js to implement a
sample device.
The IoT Suite remote monitoring preconfigured solution as the cloud-based back end.

Overview
In this tutorial, you complete the following steps:
Deploy an instance of the remote monitoring preconfigured solution to your Azure subscription. This step
automatically deploys and configures multiple Azure services.
Set up your device to communicate with your computer and the remote monitoring solution.
Update the sample device code to connect to the remote monitoring solution, and send simulated telemetry
that you can view on the solution dashboard.

Prerequisites
To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Required software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
Provision the solution
If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User
Voice.

WARNING
The remote monitoring solution provisions a set of Azure services in your Azure subscription. The deployment reflects a real
enterprise architecture. To avoid unnecessary Azure consumption charges, delete your instance of the preconfigured
solution at azureiotsuite.com when you have finished with it. If you need the preconfigured solution again, you can easily
recreate it. For more information about reducing consumption while the remote monitoring solution runs, see Configuring
Azure IoT Suite preconfigured solutions for demo purposes.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. For example, you can view telemetry, add
devices, and invoke methods.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your remote monitoring solution portal in a new tab.
2. By default, the solution portal shows the dashboard. You can navigate to other areas of the solution portal
using the menu on the left-hand side of the page.

Add a device
For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
If you haven't already done so, add a custom device to your remote monitoring solution. Complete the following
steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .

2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify you

haven't already used the name in your solution, and then click to provision the device.
4. Make a note the device credentials ( , , and ). Your client
application on the Raspberry Pi needs these values to connect to the remote monitoring solution. Then click
.

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now
receive telemetry from your device and invoke methods on the device.

Prepare your Raspberry Pi

Install Raspbian
If this is the first time you are using your Raspberry Pi, you need to install the Raspbian operating system using
NOOBS on the SD card included in the kit. The Raspberry Pi Software Guide describes how to install an operating
system on your Raspberry Pi. This tutorial assumes you have installed the Raspbian operating system on your
Raspberry Pi.

NOTE
The SD card included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 already has NOOBS installed. You can boot
the Raspberry Pi from this card and choose to install the Raspbian OS.

To complete the hardware setup, you need to:

Connect your Raspberry Pi to the power supply included in the kit.
Connect your Raspberry Pi to your network using the Ethernet cable included in your kit. Alternatively, you can
set up Wireless Connectivity for your Raspberry Pi.
You have now completed the hardware setup of your Raspberry Pi.
Sign in and access the terminal
You have two options to access a terminal environment on your Raspberry Pi:
If you have a keyboard and monitor connected to your Raspberry Pi, you can use the Raspbian GUI to
access a terminal window.
Access the command line on your Raspberry Pi using SSH from your desktop machine.
Use a terminal Window in the GUI
The default credentials for Raspbian are username and password . In the task bar in the GUI, you can
launch the utility using the icon that looks like a monitor.
Sign in with SSH
You can use SSH for command-line access to your Raspberry Pi. The article SSH (Secure Shell) describes how to
configure SSH on your Raspberry Pi, and how to connect from Windows or Linux & Mac OS.
Sign in with username and password .
Optional: Share a folder on your Raspberry Pi
Optionally, you may want to share a folder on your Raspberry Pi with your desktop environment. Sharing a folder
enables you to use your preferred desktop text editor (such as Visual Studio Code or Sublime Text) to edit files on
your Raspberry Pi instead of using or .
To share a folder with Windows, configure a Samba server on the Raspberry Pi. Alternatively, use the built-in SFTP
server with an SFTP client on your desktop.

Download and configure the sample

You can now download and configure the remote monitoring client application on your Raspberry Pi.
Install Node.js
If you haven't done so already, install Node.js on your Raspberry Pi. The IoT SDK for Node.js requires version
0.11.5 of Node.js or later. The following steps show you how to install Node.js v6.10.2 on your Raspberry Pi:
1. Use the following command to update your Raspberry Pi:

2. Use the following command to download the Node.js binaries to your Raspberry Pi:
3. Use the following command to install the binaries:

4. Use the following command to verify you have installed Node.js v6.10.2 successfully:

Clone the repositories

If you haven't already done so, clone the required repositories by running the following commands in a terminal
on your Pi:

Update the device connection string

Open the sample source file in the editor using the following command:

Find the line:

Replace the placeholder values with the device and IoT Hub information you created and saved at the start of this
tutorial. Save your changes ( , ) and exit the editor ( ).

Run the sample

Run the following commands to install the prerequisite packages for the sample:

You can now run the sample program on the Raspberry Pi. Enter the command:

The following sample output is an example of the output you see at the command prompt on the Raspberry Pi:
Press to exit the program at any time.

View the telemetry

The Raspberry Pi is now sending telemetry to the remote monitoring solution. You can view the telemetry on the
solution dashboard. You can also send messages to your Raspberry Pi from the solution dashboard.
Navigate to the solution dashboard.
Select your device in the dropdown.
The telemetry from the Raspberry Pi displays on the dashboard.
Act on the device
From the solution dashboard, you can invoke methods on your Raspberry Pi. When the Raspberry Pi connects to
the remote monitoring solution, it sends information about the methods it supports.
In the solution dashboard, click to visit the page. Select your Raspberry Pi in the
. Then choose :

On the page, choose in the dropdown.

Choose . The simulator prints a message in the console on the Raspberry Pi. The app on the
Raspberry Pi sends an acknowledgment back to the solution dashboard:
 You can switch the LED on and off using the method with a set to
for on or for off.

WARNING
If you leave the remote monitoring solution running in your Azure account, you are billed for the time it runs. For more
information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT Suite
preconfigured solutions for demo purposes. Delete the preconfigured solution from your Azure account when you have
finished using it.

Next steps
Visit the Azure IoT Dev Center for more samples and documentation on Azure IoT.
 Connect your Raspberry Pi 3 to the remote
monitoring solution and send telemetry from a real
sensor using Node.js
11/6/2017 • 9 min to read • Edit Online

This tutorial shows you how to use the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to develop a temperature
and humidity reader that can communicate with the cloud. The tutorial uses:
Raspbian OS, the Node.js programming language, and the Microsoft Azure IoT SDK for Node.js to implement a
sample device.
The IoT Suite remote monitoring preconfigured solution as the cloud-based back end.

Overview
In this tutorial, you complete the following steps:
Deploy an instance of the remote monitoring preconfigured solution to your Azure subscription. This step
automatically deploys and configures multiple Azure services.
Set up your device and sensors to communicate with your computer and the remote monitoring solution.
Update the sample device code to connect to the remote monitoring solution, and send telemetry that you can
view on the solution dashboard.

Prerequisites
To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Required software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
 BME280 sensor
Breadboard
Jumper wires
Resistors
LEDs

Provision the solution

If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User
Voice.

WARNING
The remote monitoring solution provisions a set of Azure services in your Azure subscription. The deployment reflects a real
enterprise architecture. To avoid unnecessary Azure consumption charges, delete your instance of the preconfigured
solution at azureiotsuite.com when you have finished with it. If you need the preconfigured solution again, you can easily
recreate it. For more information about reducing consumption while the remote monitoring solution runs, see Configuring
Azure IoT Suite preconfigured solutions for demo purposes.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. For example, you can view telemetry, add
devices, and invoke methods.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your remote monitoring solution portal in a new tab.
2. By default, the solution portal shows the dashboard. You can navigate to other areas of the solution portal
using the menu on the left-hand side of the page.

Add a device
For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
If you haven't already done so, add a custom device to your remote monitoring solution. Complete the following
steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .

2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify you

haven't already used the name in your solution, and then click to provision the device.
4. Make a note the device credentials ( , , and ). Your client
application on the Raspberry Pi needs these values to connect to the remote monitoring solution. Then click
.

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now
receive telemetry from your device and invoke methods on the device.

Prepare your Raspberry Pi

Install Raspbian
If this is the first time you are using your Raspberry Pi, you need to install the Raspbian operating system using
NOOBS on the SD card included in the kit. The Raspberry Pi Software Guide describes how to install an operating
system on your Raspberry Pi. This tutorial assumes you have installed the Raspbian operating system on your
Raspberry Pi.

NOTE
The SD card included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 already has NOOBS installed. You can boot
the Raspberry Pi from this card and choose to install the Raspbian OS.

Set up the hardware

This tutorial uses the BME280 sensor included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to generate
telemetry data. It uses an LED to indicate when the Raspberry Pi processes a method invocation from the solution
dashboard.
The components on the bread board are:
Red LED
220-Ohm resistor (red, red, brown)
BME280 sensor
The following diagram shows how to connect your hardware:

The following table summarizes the connections from the Raspberry Pi to the components on the breadboard:

GND (Pin 14) LED -ve pin (18A) Purple

GPCLK0 (Pin 7) Resistor (25A) Orange

SPI_CE0 (Pin 24) CS (39A) Blue

 SPI_SCLK (Pin 23) SCK (36A) Yellow

SPI_MISO (Pin 21) SDO (37A) White

SPI_MOSI (Pin 19) SDI (38A) Green

GND (Pin 6) GND (35A) Black

3.3 V (Pin 1) 3Vo (34A) Red

To complete the hardware setup, you need to:

Connect your Raspberry Pi to the power supply included in the kit.
Connect your Raspberry Pi to your network using the Ethernet cable included in your kit. Alternatively, you can
set up Wireless Connectivity for your Raspberry Pi.
You have now completed the hardware setup of your Raspberry Pi.
Sign in and access the terminal
You have two options to access a terminal environment on your Raspberry Pi:
If you have a keyboard and monitor connected to your Raspberry Pi, you can use the Raspbian GUI to
access a terminal window.
Access the command line on your Raspberry Pi using SSH from your desktop machine.
Use a terminal Window in the GUI
The default credentials for Raspbian are username and password . In the task bar in the GUI, you can
launch the utility using the icon that looks like a monitor.
Sign in with SSH
You can use SSH for command-line access to your Raspberry Pi. The article SSH (Secure Shell) describes how to
configure SSH on your Raspberry Pi, and how to connect from Windows or Linux & Mac OS.
Sign in with username and password .
Optional: Share a folder on your Raspberry Pi
Optionally, you may want to share a folder on your Raspberry Pi with your desktop environment. Sharing a folder
enables you to use your preferred desktop text editor (such as Visual Studio Code or Sublime Text) to edit files on
your Raspberry Pi instead of using or .
To share a folder with Windows, configure a Samba server on the Raspberry Pi. Alternatively, use the built-in SFTP
server with an SFTP client on your desktop.
Enable SPI
Before you can run the sample application, you must enable the Serial Peripheral Interface (SPI) bus on the
Raspberry Pi. The Raspberry Pi communicates with the BME280 sensor device over the SPI bus. Use the following
command to edit the configuration file:

Find the line:

 To uncomment the line, delete the at the start.
Save your changes ( , ) and exit the editor ( ).
To enable SPI, reboot the Raspberry Pi. Rebooting disconnects the terminal, you need to sign in again when
the Raspberry Pi restarts:

Download and configure the sample

You can now download and configure the remote monitoring client application on your Raspberry Pi.
Install Node.js
Install Node.js on your Raspberry Pi. The IoT SDK for Node.js requires version 0.11.5 of Node.js or later. The
following steps show you how to install Node.js v6.10.2 on your Raspberry Pi:
1. Use the following command to update your Raspberry Pi:

2. Use the following command to download the Node.js binaries to your Raspberry Pi:

3. Use the following command to install the binaries:

4. Use the following command to verify you have installed Node.js v6.10.2 successfully:

Clone the repositories

If you haven't already done so, clone the required repositories by running the following commands on your Pi:

Update the device connection string

Open the sample source file in the editor using the following command:

Find the line:

Replace the placeholder values with the device and IoT Hub information you created and saved at the start of this
tutorial. Save your changes ( , ) and exit the editor ( ).

Run the sample

Run the following commands to install the prerequisite packages for the sample:

You can now run the sample program on the Raspberry Pi. Enter the command:

The following sample output is an example of the output you see at the command prompt on the Raspberry Pi:

Press to exit the program at any time.

View the telemetry

The Raspberry Pi is now sending telemetry to the remote monitoring solution. You can view the telemetry on the
solution dashboard. You can also send messages to your Raspberry Pi from the solution dashboard.
Navigate to the solution dashboard.
Select your device in the dropdown.
The telemetry from the Raspberry Pi displays on the dashboard.
Act on the device
From the solution dashboard, you can invoke methods on your Raspberry Pi. When the Raspberry Pi connects to
the remote monitoring solution, it sends information about the methods it supports.
In the solution dashboard, click to visit the page. Select your Raspberry Pi in the
. Then choose :

On the page, choose in the dropdown.

Choose . The LED connected to the Raspberry Pi flashes several times. The app on the
Raspberry Pi sends an acknowledgment back to the solution dashboard:
 You can switch the LED on and off using the method with a set to
for on or for off.

WARNING
If you leave the remote monitoring solution running in your Azure account, you are billed for the time it runs. For more
information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT Suite
preconfigured solutions for demo purposes. Delete the preconfigured solution from your Azure account when you have
finished using it.

Next steps
Visit the Azure IoT Dev Center for more samples and documentation on Azure IoT.
 Connect your Raspberry Pi 3 to the remote
monitoring solution and enable remote firmware
updates using Node.js
11/6/2017 • 11 min to read • Edit Online

This tutorial shows you how to use the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to:
Develop a temperature and humidity reader that can communicate with the cloud.
Enable and perform a remote firmware update to update the client application on the Raspberry Pi.
The tutorial uses:
Raspbian OS, the Node.js programming language, and the Microsoft Azure IoT SDK for Node.js to implement a
sample device.
The IoT Suite remote monitoring preconfigured solution as the cloud-based back end.

Overview
In this tutorial, you complete the following steps:
Deploy an instance of the remote monitoring preconfigured solution to your Azure subscription. This step
automatically deploys and configures multiple Azure services.
Set up your device and sensors to communicate with your computer and the remote monitoring solution.
Update the sample device code to connect to the remote monitoring solution, and send telemetry that you can
view on the solution dashboard.
Use the sample device code to update the client application.

Prerequisites
To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Required software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
 Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
BME280 sensor
Breadboard
Jumper wires
Resistors
LEDs

Provision the solution

If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User
Voice.

WARNING
The remote monitoring solution provisions a set of Azure services in your Azure subscription. The deployment reflects a real
enterprise architecture. To avoid unnecessary Azure consumption charges, delete your instance of the preconfigured
solution at azureiotsuite.com when you have finished with it. If you need the preconfigured solution again, you can easily
recreate it. For more information about reducing consumption while the remote monitoring solution runs, see Configuring
Azure IoT Suite preconfigured solutions for demo purposes.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. For example, you can view telemetry, add
devices, and invoke methods.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your remote monitoring solution portal in a new tab.
2. By default, the solution portal shows the dashboard. You can navigate to other areas of the solution portal
using the menu on the left-hand side of the page.

Add a device
For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
If you haven't already done so, add a custom device to your remote monitoring solution. Complete the following
steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .

2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify you

haven't already used the name in your solution, and then click to provision the device.
4. Make a note the device credentials ( , , and ). Your client
application on the Raspberry Pi needs these values to connect to the remote monitoring solution. Then
click .

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now
receive telemetry from your device and invoke methods on the device.

Prepare your Raspberry Pi

Install Raspbian
If this is the first time you are using your Raspberry Pi, you need to install the Raspbian operating system using
NOOBS on the SD card included in the kit. The Raspberry Pi Software Guide describes how to install an operating
system on your Raspberry Pi. This tutorial assumes you have installed the Raspbian operating system on your
Raspberry Pi.

NOTE
The SD card included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 already has NOOBS installed. You can boot
the Raspberry Pi from this card and choose to install the Raspbian OS.

Set up the hardware

This tutorial uses the BME280 sensor included in the Microsoft Azure IoT Starter Kit for Raspberry Pi 3 to generate
telemetry data. It uses an LED to indicate when the Raspberry Pi processes a method invocation from the solution
dashboard.
The components on the bread board are:
Red LED
220-Ohm resistor (red, red, brown)
BME280 sensor
The following diagram shows how to connect your hardware:

The following table summarizes the connections from the Raspberry Pi to the components on the breadboard:

GND (Pin 14) LED -ve pin (18A) Purple

GPCLK0 (Pin 7) Resistor (25A) Orange

SPI_CE0 (Pin 24) CS (39A) Blue

 SPI_SCLK (Pin 23) SCK (36A) Yellow

SPI_MISO (Pin 21) SDO (37A) White

SPI_MOSI (Pin 19) SDI (38A) Green

GND (Pin 6) GND (35A) Black

3.3 V (Pin 1) 3Vo (34A) Red

To complete the hardware setup, you need to:

Connect your Raspberry Pi to the power supply included in the kit.
Connect your Raspberry Pi to your network using the Ethernet cable included in your kit. Alternatively, you can
set up Wireless Connectivity for your Raspberry Pi.
You have now completed the hardware setup of your Raspberry Pi.
Sign in and access the terminal
You have two options to access a terminal environment on your Raspberry Pi:
If you have a keyboard and monitor connected to your Raspberry Pi, you can use the Raspbian GUI to
access a terminal window.
Access the command line on your Raspberry Pi using SSH from your desktop machine.
Use a terminal Window in the GUI
The default credentials for Raspbian are username and password . In the task bar in the GUI, you can
launch the utility using the icon that looks like a monitor.
Sign in with SSH
You can use SSH for command-line access to your Raspberry Pi. The article SSH (Secure Shell) describes how to
configure SSH on your Raspberry Pi, and how to connect from Windows or Linux & Mac OS.
Sign in with username and password .
Optional: Share a folder on your Raspberry Pi
Optionally, you may want to share a folder on your Raspberry Pi with your desktop environment. Sharing a folder
enables you to use your preferred desktop text editor (such as Visual Studio Code or Sublime Text) to edit files on
your Raspberry Pi instead of using or .
To share a folder with Windows, configure a Samba server on the Raspberry Pi. Alternatively, use the built-in SFTP
server with an SFTP client on your desktop.
Enable SPI
Before you can run the sample application, you must enable the Serial Peripheral Interface (SPI) bus on the
Raspberry Pi. The Raspberry Pi communicates with the BME280 sensor device over the SPI bus. Use the following
command to edit the configuration file:

Find the line:

 To uncomment the line, delete the at the start.
Save your changes ( , ) and exit the editor ( ).
To enable SPI, reboot the Raspberry Pi. Rebooting disconnects the terminal, you need to sign in again when
the Raspberry Pi restarts:

Download and configure the sample

You can now download and configure the remote monitoring client application on your Raspberry Pi.
Install Node.js
If you haven't done so already, install Node.js on your Raspberry Pi. The IoT SDK for Node.js requires version
0.11.5 of Node.js or later. The following steps show you how to install Node.js v6.10.2 on your Raspberry Pi:
1. Use the following command to update your Raspberry Pi:

2. Use the following command to download the Node.js binaries to your Raspberry Pi:

3. Use the following command to install the binaries:

4. Use the following command to verify you have installed Node.js v6.10.2 successfully:

Clone the repositories

If you haven't done so already, clone the required repositories by running the following commands on your Pi:

Update the device connection string

Open the sample configuration file in the editor using the following command:

Replace the placeholder values with the device id and IoT Hub information you created and saved at the start of
this tutorial.
When you are done, the contents of the deviceinfo file should look like the following example:
Save your changes ( , ) and exit the editor ( ).

Run the sample

Run the following commands to install the prerequisite packages for the sample:

You can now run the sample program on the Raspberry Pi. Enter the command:

The following sample output is an example of the output you see at the command prompt on the Raspberry Pi:

Press to exit the program at any time.

View the telemetry

The Raspberry Pi is now sending telemetry to the remote monitoring solution. You can view the telemetry on the
solution dashboard. You can also send messages to your Raspberry Pi from the solution dashboard.
Navigate to the solution dashboard.
Select your device in the dropdown.
The telemetry from the Raspberry Pi displays on the dashboard.
Initiate the firmware update
The firmware update process downloads and installs an updated version of the device client application on the
Raspberry Pi. For more information about the firmware update process, see the description of the firmware
update pattern in Overview of device management with IoT Hub.
You initiate the firmware update process by invoking a method on the device. This method is asynchronous, and
returns as soon as the update process begins. The device uses reported properties to notify the solution about the
progress of the update.
You invoke methods on your Raspberry Pi from the solution dashboard. When the Raspberry Pi first connects to
the remote monitoring solution, it sends information about the methods it supports.
1. In the solution dashboard, click to visit the page. Select your Raspberry Pi in the
. Then choose :

2. On the page, choose in the dropdown.

3. In the field, enter
. This file contains
the implementation of version 2.0 of the firmware.
4. Choose . The app on the Raspberry Pi sends an acknowledgment back to the solution
dashboard. It then starts the firmware update process by downloading the new version of the firmware:

Observe the firmware update process

You can observe the firmware update process as it runs on the device and by viewing the reported properties in
the solution dashboard:
1. You can view the progress in of the update process on the Raspberry Pi:

NOTE
The remote monitoring app restarts silently when the update completes. Use the command to verify it is
running. If you want to terminate the process, use the command with the process id.

2. You can view the status of the firmware update, as reported by the device, in the solution portal. The
following screenshot shows the status and duration of each stage of the update process, and the new
firmware version:
 If you navigate back to the dashboard, you can verify the device is still sending telemetry following the
firmware update.

WARNING
If you leave the remote monitoring solution running in your Azure account, you are billed for the time it runs. For more
information about reducing consumption while the remote monitoring solution runs, see Configuring Azure IoT Suite
preconfigured solutions for demo purposes. Delete the preconfigured solution from your Azure account when you have
finished using it.
Next steps
Visit the Azure IoT Dev Center for more samples and documentation on Azure IoT.
 Connect your device to the remote monitoring
preconfigured solution (Windows)
11/6/2017 • 11 min to read • Edit Online

Scenario overview
In this scenario, you create a device that sends the following telemetry to the remote monitoring preconfigured
solution:
External temperature
Internal temperature
Humidity
For simplicity, the code on the device generates sample values, but we encourage you to extend the sample by
connecting real sensors to your device and sending real telemetry.
The device is also able to respond to methods invoked from the solution dashboard and desired property values
set in the solution dashboard.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free
trial account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution
and provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured solution. If
you haven't already provisioned the remote monitoring preconfigured solution in your Azure account, use the
following steps:
1. On the https://www.azureiotsuite.com/ page, click to create a solution.
2. Click on the panel to create your solution.
3. On the page, enter a of your choice, select the
you want to deploy to, and select the Azure subscription to want to use. Then click .
4. Wait until the provisioning process completes.

WARNING
The preconfigured solutions use billable Azure services. Be sure to remove the preconfigured solution from your
subscription when you are done with it to avoid any unnecessary charges. You can completely remove a preconfigured
solution from your subscription by visiting the https://www.azureiotsuite.com/ page.

When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need to know the device credentials
when you create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .
2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify

that name isn't already in use, and then click to provision the device.
4. Make a note the device credentials (Device ID, IoT Hub Hostname, and Device Key). Your client application
needs these values to connect to the remote monitoring solution. Then click .

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now receive telemetry
from your device and invoke methods on the device.

Create a C sample solution on Windows

The following steps show you how to create a client application that communicates with the remote monitoring
preconfigured solution. This application is written in C and built and run on Windows.
Create a starter project in Visual Studio 2015 or Visual Studio 2017 and add the IoT Hub device client NuGet
packages:
1. In Visual Studio, create a C console application using the Visual C++ template.
Name the project .
2. On the page in the , ensure that is
selected, and uncheck and .
3. In , delete the files stdafx.h, targetver.h, and stdafx.cpp.
4. In , rename the file RMDevice.cpp to RMDevice.c.
5. In , right-click on the project and then click .
Click , then search for and install the following NuGet packages:
Microsoft.Azure.IoTHub.Serializer
Microsoft.Azure.IoTHub.IoTHubClient
Microsoft.Azure.IoTHub.MqttTransport
6. In , right-click on the project and then click to open the project's
dialog box. For details, see Setting Visual C++ Project Properties.
7. Click the folder, then click the property page.
8. Add to the property. Click and then again to save the project
property values.
Add the Parson JSON library to the project and add the required statements:
1. In a suitable folder on your computer, clone the Parson GitHub repository using the following command:

2. Copy the parson.h and parson.c files from the local copy of the Parson repository to your
project folder.
3. In Visual Studio, right-click the project, click , and then click .
4. In the dialog, select the parson.h and parson.c files in the project folder.
Then click to add these two files to your project.
5. In Visual Studio, open the RMDevice.c file. Replace the existing statements with the following
code:

NOTE
Now you can verify that your project has the correct dependencies set up by building it.

Specify the behavior of the IoT device

The IoT Hub serializer client library uses a model to specify the format of the messages the device exchanges with
IoT Hub.
1. Add the following variable declarations after the statements. Replace the placeholder values
[Device ID] and [Device Key] with values you noted for your device in the remote monitoring solution
dashboard. Use the IoT Hub Hostname from the solution dashboard to replace [IoTHub Name]. For
example, if your IoT Hub Hostname is , replace [IoTHub Name] with :
2. Add the following code to define the model that enables the device to communicate with IoT Hub. This
model specifies that the device:
Can send temperature, external temperature, humidity, and a device ID as telemetry.
Can send metadata about the device to IoT Hub. The device sends basic metadata in a
object at startup.
Can send reported properties, to the device twin in IoT Hub. These reported properties are grouped into
configuration, device, and system properties.
Can receive and act on desired properties set in the device twin in IoT Hub.
Can respond to the and direct methods invoked through the
solution portal. The device sends information about the direct methods it supports using reported
properties.
Implement the behavior of the device
Now add code that implements the behavior defined in the model.
1. Add the following functions that handle the desired properties set in the solution dashboard. These desired
properties are defined in the model:

2. Add the following functions that handle the direct methods invoked through the IoT hub. These direct
methods are defined in the model:

3. Add the following function that sends a message to the preconfigured solution:
4. Add the following callback handler that runs when the device has sent new reported property values to the
preconfigured solution:

5. Add the following function to connect your device to the preconfigured solution in the cloud, and exchange
data. This function performs the following steps:
Initializes the platform.
Registers the Contoso namespace with the serialization library.
Initializes the client with the device connection string.
Create an instance of the model.
Creates and sends reported property values.
Sends a object.
Creates a loop to send telemetry every second.
Deinitializes all resources.
 For reference, here is a sample message sent to the preconfigured solution:

Build and run the sample

Add code to invoke the function and then build and run the device application.
1. Replace the function with following code to invoke the function:

2. Click and then to build the device application.

3. In , right-click the project, click , and then click
to run the sample. The console displays messages as the application sends sample telemetry to the
preconfigured solution, receives desired property values set in the solution dashboard, and responds to
 methods invoked from the solution dashboard.

View device telemetry in the dashboard

The dashboard in the remote monitoring solution enables you to view the telemetry your devices send to IoT Hub.
1. In your browser, return to the remote monitoring solution dashboard, click in the left-hand panel to
navigate to the .
2. In the , you should see that the status of your device is . If not, click in
the panel.

3. Click to return to the dashboard, select your device in the drop-down to view
its telemetry. The telemetry from the sample application is 50 units for internal temperature, 55 units for
external temperature, and 50 units for humidity.
Invoke a method on your device
The dashboard in the remote monitoring solution enables you to invoke methods on your devices through IoT
Hub. For example, in the remote monitoring solution you can invoke a method to simulate rebooting a device.
1. In the remote monitoring solution dashboard, click in the left-hand panel to navigate to the
.
2. Click for your device in the .
3. In the panel, click .

4. In the drop-down, select , and then in enter a dummy

URL. Click to call the method on the device.

5. You see a message in the console running your device code when the device handles the method. The
results of the method are added to the history in the solution portal:
Next steps
The article Customizing preconfigured solutions describes some ways you can extend this sample. Possible
extensions include using real sensors and implementing additional commands.
You can learn more about the permissions on the azureiotsuite.com site.
 Connect your device to the remote monitoring
preconfigured solution (Linux)
11/6/2017 • 11 min to read • Edit Online

Scenario overview
In this scenario, you create a device that sends the following telemetry to the remote monitoring preconfigured
solution:
External temperature
Internal temperature
Humidity
For simplicity, the code on the device generates sample values, but we encourage you to extend the sample by
connecting real sensors to your device and sending real telemetry.
The device is also able to respond to methods invoked from the solution dashboard and desired property values
set in the solution dashboard.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free trial
account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution and
provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured solution. If
you haven't already provisioned the remote monitoring preconfigured solution in your Azure account, use the
following steps:
1. On the https://www.azureiotsuite.com/ page, click to create a solution.
2. Click on the panel to create your solution.
3. On the page, enter a of your choice, select the
you want to deploy to, and select the Azure subscription to want to use. Then click .
4. Wait until the provisioning process completes.

WARNING
The preconfigured solutions use billable Azure services. Be sure to remove the preconfigured solution from your subscription
when you are done with it to avoid any unnecessary charges. You can completely remove a preconfigured solution from your
subscription by visiting the https://www.azureiotsuite.com/ page.

When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need to know the device credentials
when you create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .
2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify

that name isn't already in use, and then click to provision the device.
4. Make a note the device credentials (Device ID, IoT Hub Hostname, and Device Key). Your client application
needs these values to connect to the remote monitoring solution. Then click .

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now receive telemetry
from your device and invoke methods on the device.

Build and run a sample C client Linux

The following steps show you how to create a client application that communicates with the remote monitoring
preconfigured solution. This application is written in C and built and run on Ubuntu Linux.
To complete these steps, you need a device running Ubuntu version 15.04 or 15.10. Before proceeding, install the
prerequisite packages on your Ubuntu device using the following command:

Install the client libraries on your device

The Azure IoT Hub client libraries are available as a package you can install on your Ubuntu device using the
command. Complete the following steps to install the package that contains the IoT Hub client library and
header files on your Ubuntu computer:
1. In a shell, add the AzureIoT repository to your computer:

2. Install the azure-iot-sdk-c-dev package

Install the Parson JSON parser

The IoT Hub client libraries use the Parson JSON parser to parse message payloads. In a suitable folder on your
computer, clone the Parson GitHub repository using the following command:

Prepare your project

On your Ubuntu machine, create a folder called . In the folder:
Create the four files , , , and .
Create folder called .
Copy the files and from your local copy of the Parson repository into the
folder.
In a text editor, open the file. Add the following statements:

Specify the behavior of the IoT device

The IoT Hub serializer client library uses a model to specify the format of the messages the device exchanges with
IoT Hub.
1. Add the following variable declarations after the statements. Replace the placeholder values
[Device ID] and [Device Key] with values you noted for your device in the remote monitoring solution
dashboard. Use the IoT Hub Hostname from the solution dashboard to replace [IoTHub Name]. For example,
if your IoT Hub Hostname is , replace [IoTHub Name] with :
2. Add the following code to define the model that enables the device to communicate with IoT Hub. This
model specifies that the device:
Can send temperature, external temperature, humidity, and a device ID as telemetry.
Can send metadata about the device to IoT Hub. The device sends basic metadata in a object
at startup.
Can send reported properties, to the device twin in IoT Hub. These reported properties are grouped into
configuration, device, and system properties.
Can receive and act on desired properties set in the device twin in IoT Hub.
Can respond to the and direct methods invoked through the
solution portal. The device sends information about the direct methods it supports using reported
properties.
Implement the behavior of the device
Now add code that implements the behavior defined in the model.
1. Add the following functions that handle the desired properties set in the solution dashboard. These desired
properties are defined in the model:

2. Add the following functions that handle the direct methods invoked through the IoT hub. These direct
methods are defined in the model:

3. Add the following function that sends a message to the preconfigured solution:
4. Add the following callback handler that runs when the device has sent new reported property values to the
preconfigured solution:

5. Add the following function to connect your device to the preconfigured solution in the cloud, and exchange
data. This function performs the following steps:
Initializes the platform.
Registers the Contoso namespace with the serialization library.
Initializes the client with the device connection string.
Create an instance of the model.
Creates and sends reported property values.
Sends a object.
Creates a loop to send telemetry every second.
Deinitializes all resources.
 For reference, here is a sample message sent to the preconfigured solution:

Call the remote_monitoring_run function

In a text editor, open the file. Add the following code:

In a text editor, open the file. Add the following code:

Build and run the application
The following steps describe how to use CMake to build your client application.
1. In a text editor, open the file in the folder.
2. Add the following instructions to define how to build your client application:

3. In the folder, create a folder to store the make files that CMake generates and then
run the and commands as follows:

4. Run the client application and send telemetry to IoT Hub:

View device telemetry in the dashboard
The dashboard in the remote monitoring solution enables you to view the telemetry your devices send to IoT Hub.
1. In your browser, return to the remote monitoring solution dashboard, click in the left-hand panel to
navigate to the .
2. In the , you should see that the status of your device is . If not, click in
the panel.

3. Click to return to the dashboard, select your device in the drop-down to view
its telemetry. The telemetry from the sample application is 50 units for internal temperature, 55 units for
external temperature, and 50 units for humidity.
Invoke a method on your device
The dashboard in the remote monitoring solution enables you to invoke methods on your devices through IoT
Hub. For example, in the remote monitoring solution you can invoke a method to simulate rebooting a device.
1. In the remote monitoring solution dashboard, click in the left-hand panel to navigate to the
.
2. Click for your device in the .
3. In the panel, click .

4. In the drop-down, select , and then in enter a dummy

URL. Click to call the method on the device.

5. You see a message in the console running your device code when the device handles the method. The
results of the method are added to the history in the solution portal:
Next steps
The article Customizing preconfigured solutions describes some ways you can extend this sample. Possible
extensions include using real sensors and implementing additional commands.
You can learn more about the permissions on the azureiotsuite.com site.
 Connect your device to the remote monitoring
preconfigured solution (Node.js)
11/6/2017 • 7 min to read • Edit Online

Scenario overview
In this scenario, you create a device that sends the following telemetry to the remote monitoring preconfigured
solution:
External temperature
Internal temperature
Humidity
For simplicity, the code on the device generates sample values, but we encourage you to extend the sample by
connecting real sensors to your device and sending real telemetry.
The device is also able to respond to methods invoked from the solution dashboard and desired property values
set in the solution dashboard.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free trial
account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution and
provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured solution. If
you haven't already provisioned the remote monitoring preconfigured solution in your Azure account, use the
following steps:
1. On the https://www.azureiotsuite.com/ page, click to create a solution.
2. Click on the panel to create your solution.
3. On the page, enter a of your choice, select the
you want to deploy to, and select the Azure subscription to want to use. Then click .
4. Wait until the provisioning process completes.

WARNING
The preconfigured solutions use billable Azure services. Be sure to remove the preconfigured solution from your subscription
when you are done with it to avoid any unnecessary charges. You can completely remove a preconfigured solution from your
subscription by visiting the https://www.azureiotsuite.com/ page.

When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need to know the device credentials
when you create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution dashboard. You include the device credentials in your client
application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps in the solution dashboard:
1. In the lower left-hand corner of the dashboard, click .
2. In the panel, click .

3. Choose . Enter a Device ID such as , click to verify

that name isn't already in use, and then click to provision the device.
4. Make a note the device credentials (Device ID, IoT Hub Hostname, and Device Key). Your client application
needs these values to connect to the remote monitoring solution. Then click .

5. Select your device in the device list in the solution dashboard. Then, in the panel, click
. The status of your device is now . The remote monitoring solution can now receive telemetry
from your device and invoke methods on the device.

Create a node.js sample solution

Ensure that Node.js version 0.11.5 or later is installed on your development machine. You can run
at the command line to check the version.
1. Create a folder called on your development machine. Navigate to this folder in your
command-line environment.
2. Run the following commands to download and install the packages you need to complete the sample app:
 3. In the folder, create a file called . Open this file in a text editor.
4. In the file, add the following statements:

5. Add the following variable declarations after the statements. Replace the placeholder values
[Device Id] and [Device Key] with values you noted for your device in the remote monitoring solution
dashboard. Use the IoT Hub Hostname from the solution dashboard to replace [IoTHub Name]. For example,
if your IoT Hub Hostname is , replace [IoTHub Name] with :

6. Add the following variables to define some base telemetry data:

7. Add the following helper function to print operation results:

8. Add the following helper function to use to randomize the telemetry values:

9. Add the following definition for the object the device sends on startup:

10. Add the following definition for the device twin reported values. This definition includes descriptions of the
direct methods the device supports:
11. Add the following function to handle the direct method call:

12. Add the following function to handle the direct method call. This direct method
uses a parameter to specify the location of the firmware image to download, and initiates the firmware
update on the device asynchronously:
13. Add the following code to create a client instance:

14. Add the following code to:

Open the connection.
Send the object.
Set up a handler for desired properties.
Send reported properties.
Register handlers for the direct methods.
Start sending telemetry.
15. Save the changes to the file.
16. Run the following command at a command prompt to launch the sample application:
View device telemetry in the dashboard
The dashboard in the remote monitoring solution enables you to view the telemetry your devices send to IoT Hub.
1. In your browser, return to the remote monitoring solution dashboard, click in the left-hand panel to
navigate to the .
2. In the , you should see that the status of your device is . If not, click in
the panel.

3. Click to return to the dashboard, select your device in the drop-down to view
its telemetry. The telemetry from the sample application is 50 units for internal temperature, 55 units for
external temperature, and 50 units for humidity.

Invoke a method on your device

The dashboard in the remote monitoring solution enables you to invoke methods on your devices through IoT
Hub. For example, in the remote monitoring solution you can invoke a method to simulate rebooting a device.
1. In the remote monitoring solution dashboard, click in the left-hand panel to navigate to the
.
2. Click for your device in the .
3. In the panel, click .

4. In the drop-down, select , and then in enter a dummy

URL. Click to call the method on the device.

5. You see a message in the console running your device code when the device handles the method. The
results of the method are added to the history in the solution portal:
Next steps
The article Customizing preconfigured solutions describes some ways you can extend this sample. Possible
extensions include using real sensors and implementing additional commands.
You can learn more about the permissions on the azureiotsuite.com site.
 Tutorial: Connect Logic App to your Azure IoT Suite
Remote Monitoring preconfigured solution
11/20/2017 • 5 min to read • Edit Online

The Microsoft Azure IoT Suite remote monitoring preconfigured solution is a great way to get started quickly with
an end-to-end feature set that exemplifies an IoT solution. This tutorial walks you through how to add Logic App to
your Microsoft Azure IoT Suite remote monitoring preconfigured solution. These steps demonstrate how you can
take your IoT solution even further by connecting it to a business process.
If you’re looking for a walkthrough on how to provision a remote monitoring preconfigured solution, see Tutorial:
Get started with the IoT preconfigured solutions.
Before you start this tutorial, you should:
Provision the remote monitoring preconfigured solution in your Azure subscription.
Create a SendGrid account to enable you to send an email that triggers your business process. You can sign up
for a free trial account at SendGrid by clicking . After you have registered for your free trial account,
you need to create an API key in SendGrid that grants permissions to send mail. You need this API key later in
the tutorial.
To complete this tutorial, you need Visual Studio 2015 or Visual Studio 2017 to modify the actions in the
preconfigured solution back end.
Assuming you’ve already provisioned your remote monitoring preconfigured solution, navigate to the resource
group for that solution in the Azure portal. The resource group has the same name as the solution name you chose
when you provisioned your remote monitoring solution. In the resource group, you can see all the provisioned
Azure resources for your solution. The following screenshot shows an example blade for a
remote monitoring preconfigured solution:
To begin, set up the logic app to use with the preconfigured solution.

Set up the Logic App

1. Click at the top of your resource group blade in the Azure portal.
2. Search for , select it and then click .
3. Fill out the and use the same and that you used when you
provisioned your remote monitoring solution. Click .
4. When your deployment completes, you can see the Logic App is listed as a resource in your resource group.
5. Click the Logic App to navigate to the Logic App blade, select the template to open the
.
6. Select . This action specifies that an incoming HTTP request with a specific JSON formatted payload
acts as a trigger.
7. Paste the following code into the Request Body JSON Schema:

NOTE
You can copy the URL for the HTTP post after you save the logic app, but first you must add an action.

8. Click under your manual trigger. Then click .

 9. Search for and click it.

10. Enter a name for the connection, such as , enter the you created
when you set up your SendGrid account, and click .
11. Add email addresses you own to both the and fields. Add
to the field. In the field, add
You can add , , and
by clicking in the section.
12. Click in the top menu.
13. Click the trigger and copy the value. You need this URL later in this tutorial.

NOTE
Logic Apps enable you to run many different types of action including actions in Office 365.

Set up the EventProcessor Web Job

In this section, you connect your preconfigured solution to the Logic App you created. To complete this task, you
add the URL to trigger the Logic App to the action that fires when a device sensor value exceeds a threshold.
1. Use your git client to clone the latest version of the azure-iot-remote-monitoring github repository. For
example:

2. In Visual Studio, open the from the local copy of the repository.
3. Open the file in the folder.
4. Update the dictionary with the you noted from your Logic App as follows:
5. Save the changes in solution and exit Visual Studio.

Deploy from the command line

In this section, you deploy your updated version of the remote monitoring solution to replace the version currently
running in Azure.
1. Following the dev set-up instructions to set up your environment for deployment.
2. To deploy locally, follow the local deployment instructions.
3. To deploy to the cloud and update your existing cloud deployment, follow the cloud deployment
instructions. Use the name of your original deployment as the deployment name. For example if the original
deployment was called , use the following command:

When the build script runs, be sure to use the same Azure account, subscription, region, and Active Directory
instance you used when you provisioned the solution.

See your Logic App in action

The remote monitoring preconfigured solution has two rules set up by default when you provision a solution. Both
rules are on the device:
Temperature > 38.00
Humidity > 48.00
The temperature rule triggers the action and the Humidity rule triggers the action.
Assuming you used the same URL for both actions the class, your logic app triggers for either
rule. Both rules use SendGrid to send an email to the address with details of the alert.

NOTE
The Logic App continues to trigger every time the threshold is met. To avoid unnecessary emails, you can either disable the
rules in your solution portal or disable the Logic App in the Azure portal.

In addition to receiving emails, you can also see when the Logic App runs in the portal:
Next steps
Now that you've used a Logic App to connect the preconfigured solution to a business process, you can learn more
about the options for customizing the preconfigured solutions:
Use dynamic telemetry with the remote monitoring preconfigured solution
Device information metadata in the remote monitoring preconfigured solution
 Customize a preconfigured solution
11/20/2017 • 7 min to read • Edit Online

The preconfigured solutions provided with the Azure IoT Suite demonstrate the services within the suite working
together to deliver an end-to-end solution. From this starting point, there are various places in which you can
extend and customize the solution for specific scenarios. The following sections describe these common
customization points.

Find the source code

The source code for the preconfigured solutions is available on GitHub in the following repositories:
Remote Monitoring: https://www.github.com/Azure/azure-iot-remote-monitoring
Predictive Maintenance: https://github.com/Azure/azure-iot-predictive-maintenance
Connected factory: https://github.com/Azure/azure-iot-connected-factory
The source code for the preconfigured solutions is provided to demonstrate the patterns and practices used to
implement the end-to-end functionality of an IoT solution using Azure IoT Suite. You can find more information
about how to build and deploy the solutions in the GitHub repositories.

Change the preconfigured rules

The remote monitoring solution includes three Azure Stream Analytics jobs to handle device information,
telemetry, and rules logic in the solution.
The three stream analytics jobs and their syntax are described in depth in the Remote monitoring preconfigured
solution walkthrough.
You can edit these jobs directly to alter the logic, or add logic specific to your scenario. You can find the Stream
Analytics jobs as follows:
1. Go to Azure portal.
2. Navigate to the resource group with the same name as your IoT solution.
3. Select the Azure Stream Analytics job you'd like to modify.
4. Stop the job by selecting in the set of commands.
5. Edit the inputs, query, and outputs.
A simple modification is to change the query for the job to use a instead of a . The solution
portal still shows when you edit a rule, but notice how the behavior is flipped due to the change in the
underlying job.
6. Start the job

NOTE
The remote monitoring dashboard depends on specific data, so altering the jobs can cause the dashboard to fail.

Add your own rules

In addition to changing the preconfigured Azure Stream Analytics jobs, you can use the Azure portal to add new
jobs or add new queries to existing jobs.
Customize devices
One of the most common extension activities is working with devices specific to your scenario. There are several
methods for working with devices. These methods include altering a simulated device to match your scenario, or
using the IoT Device SDK to connect your physical device to the solution.
For a step-by-step guide to adding devices, see the Iot Suite Connecting Devices article and the remote
monitoring C SDK Sample. This sample is designed to work with the remote monitoring preconfigured solution.
Create your own simulated device
Included in the remote monitoring solution source code, is a .NET simulator. This simulator is the one provisioned
as part of the solution and you can alter it to send different metadata, telemetry, and respond to different
commands and methods.
The preconfigured simulator in the remote monitoring preconfigured solution simulates a cooler device that
emits temperature and humidity telemetry. You can modify the simulator in the Simulator.WebJob project when
you've forked the GitHub repository.
Available locations for simulated devices
The default set of locations is in Seattle/Redmond, Washington, United States of America. You can change these
locations in SampleDeviceFactory.cs.
Add a desired property update handler to the simulator
You can set a value for a desired property for a device in the solution portal. It is the responsibility of the device to
handle the property change request when the device retrieves the desired property value. To add support for a
property value change through a desired property, you need to add a handler to the simulator.
The simulator contains handlers for the and properties that you can update
by setting desired values in the solution portal.
The following example shows the handler for the desired property in the class:

This method updates the telemetry point temperature and then reports the change back to IoT Hub by setting a
reported property.
You can add your own handlers for your own properties by following the pattern in the preceding example.
You must also bind the desired property to the handler as shown in the following example from the
constructor:

Note that is a constant defined as "Config.SetPointTemp".

Add support for a new method to the simulator
You can customize the simulator to add support for a new method (direct method). There are two key steps
required:
The simulator must notify the IoT hub in the preconfigured solution with details of the method.
 The simulator must include code to handle the method call when you invoke it from the panel
in the solution explorer or through a job.
The remote monitoring preconfigured solution uses reported properties to send details of supported methods to
IoT hub. The solution back end maintains a list of all the methods supported by each device along with a history of
method invocations. You can view this information about devices and invoke methods in the solution portal.
To notify the IoT hub that a device supports a method, the device must add details of the method to the
node in the reported properties:

The method signature has the following format:

. For
example, to specify the method expects a string parameter named ,
use the following method signature:

For a list of supported parameter types, see the class in the Infrastructure project.
To delete a method, set the method signature to in the reported properties.

NOTE
The solution back end only updates information about supported methods when it receives a device information message
from the device.

The following code sample from the class in the Common project shows how to add a
method to the list of in the reported properties sent by the device:

This code snippet adds details of the method including text to display in the solution
portal and details of the required method parameters.
The simulator sends reported properties, including the list of supported methods, to IoT Hub when the simulator
starts.
Add a handler to the simulator code for each method it supports. You can see the existing handlers in the
class in the Simulator.WebJob project. The following example shows the handler for
method:
Method handler names must start with followed by the name of the method. The
parameter contains any parameters passed with the method invocation from the solution back end. The return
value must be of type . The utility method helps you create
the return value.
Inside the method handler, you could:
Start an asynchronous task.
Retrieve desired properties from the device twin in IoT Hub.
Update a single reported property using the method in the class.
Update multiple reported properties by creating a instance and calling the
method.
The preceding firmware update example performs the following steps:
Checks the device is able to accept the firmware update request.
Asynchronously initiates the firmware update operation and resets the telemetry when the operation is
complete.
Immediately returns the "FirmwareUpdate accepted" message to indicate the request was accepted by the
device.
Build and use your own (physical) device
The Azure IoT SDKs provide libraries for connecting numerous device types (languages and operating systems)
into IoT solutions.

Modify dashboard limits

Number of devices displayed in dashboard dropdown
The default is 200. You can change this number in DashboardController.cs.
Number of pins to display in Bing Map control
The default is 200. You can change this number in TelemetryApiController.cs.
Time period of telemetry graph
The default is 10 minutes. You can change this value in TelmetryApiController.cs.

Feedback
Do you have a customization you'd like to see covered in this document? Add feature suggestions to User Voice,
or comment on this article.

Next steps
To learn more about the options for customizing the preconfigured solutions, see:
Connect Logic App to your Azure IoT Suite Remote Monitoring preconfigured solution
Use dynamic telemetry with the remote monitoring preconfigured solution
Device information metadata in the remote monitoring preconfigured solution
Customize how the connected factory solution displays data from your OPC UA servers
 Use dynamic telemetry with the remote monitoring
preconfigured solution
11/6/2017 • 6 min to read • Edit Online

Dynamic telemetry enables you to visualize any telemetry sent to the remote monitoring preconfigured solution.
The simulated devices that deploy with the preconfigured solution send temperature and humidity telemetry,
which you can visualize on the dashboard. If you customize existing simulated devices, create new simulated
devices, or connect physical devices to the preconfigured solution you can send other telemetry values such as the
external temperature, RPM, or windspeed. You can then visualize this additional telemetry on the dashboard.
This tutorial uses a simple Node.js simulated device that you can easily modify to experiment with dynamic
telemetry.
To complete this tutorial, you’ll need:
An active Azure subscription. If you don’t have an account, you can create a free trial account in just a couple of
minutes. For details, see Azure Free Trial.
Node.js version 0.12.x or later.
You can complete this tutorial on any operating system, such as Windows or Linux, where you can install Node.js.

Provision the solution

If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User Voice.

Configure the Node.js simulated device

1. On the remote monitoring dashboard, click and then add a custom device. Make a note of the
IoT Hub hostname, device id, and device key. You need them later in this tutorial when you prepare the
remote_monitoring.js device client application.
2. Ensure that Node.js version 0.12.x or later is installed on your development machine. Run at a
command prompt or in a shell to check the version. For information about using a package manager to install
Node.js on Linux, see Installing Node.js via package manager.
3. When you have installed Node.js, clone the latest version of the azure-iot-sdk-node repository to your
development machine. Always use the branch for the latest version of the libraries and samples.
4. From your local copy of the azure-iot-sdk-node repository, copy the following two files from the
node/device/samples folder to an empty folder on your development machine:
packages.json
remote_monitoring.js
5. Open the remote_monitoring.js file and look for the following variable definition:

6. Replace with your device connection string. Use the values for your
IoT Hub hostname, device id, and device key that you made a note of in step 1. A device connection string
has the following format:

If your IoT Hub hostname is and your device id is , your connection string looks like the
following snippet:

7. Save the file. Run the following commands in a shell or command prompt in the folder that contains these
files to install the necessary packages and then run the sample application:

Observe dynamic telemetry in action

The dashboard shows the temperature and humidity telemetry from the existing simulated devices:
If you select the Node.js simulated device you ran in the previous section, you see temperature, humidity, and
external temperature telemetry:
The remote monitoring solution automatically detects the additional external temperature telemetry type and adds
it to the chart on the dashboard.

Add a telemetry type

The next step is to replace the telemetry generated by the Node.js simulated device with a new set of values:
1. Stop the Node.js simulated device by typing in your command prompt or shell.
2. In the remote_monitoring.js file, you can see the base data values for the existing temperature, humidity,
 and external temperature telemetry. Add a base data value for as follows:

3. The Node.js simulated device uses the function in the remote_monitoring.js

file to add a random increment to the base data values. Randomize the value by adding a line of code
after the existing randomizations as follows:

4. Add the new rpm value to the JSON payload the device sends to IoT Hub:

5. Run the Node.js simulated device using the following command:

6. Observe the new RPM telemetry type that displays on the chart in the dashboard:
 NOTE
You may need to disable and then enable the Node.js device on the page in the dashboard to see the change
immediately.

Customize the dashboard display

The message can include metadata about the telemetry the device can send to IoT Hub. This metadata
can specify the telemetry types the device sends. Modify the value in the remote_monitoring.js
file to include a definition following the definition. The following code snippet shows the
definition (be sure to add a after the definition):

NOTE
The remote monitoring solution uses a case-insensitive match to compare the metadata definition with data in the telemetry
stream.

Adding a definition as shown in the preceding code snippet does not change the behavior of the
dashboard. However, the metadata can also include a attribute to customize the display in the
dashboard. Update the metadata definition as shown in the following snippet:

The following screenshot shows how this change modifies the chart legend on the dashboard:
 NOTE
You may need to disable and then enable the Node.js device on the page in the dashboard to see the change
immediately.

Filter the telemetry types

By default, the chart on the dashboard shows every data series in the telemetry stream. You can use the
 metadata to suppress the display of specific telemetry types on the chart.
To make the chart show only Temperature and Humidity telemetry, omit from the
metadata as follows:

The no longer displays on the chart:

This change only affects the chart display. The data values are still stored and made
available for any backend processing.

NOTE
You may need to disable and then enable the Node.js device on the page in the dashboard to see the change
immediately.
Handle errors
For a data stream to display on the chart, its in the metadata must match the data type of the
telemetry values. For example, if the metadata specifies that the of humidity data is and a is
found in the telemetry stream then the humidity telemetry does not display on the chart. However, the
values are still stored and made available for any back-end processing.

Next steps
Now that you've seen how to use dynamic telemetry, you can learn more about how the preconfigured solutions
use device information: Device information metadata in the remote monitoring preconfigured solution.
 Create a custom rule in the remote monitoring
preconfigured solution
11/6/2017 • 8 min to read • Edit Online

Introduction
In the preconfigured solutions, you can configure rules that trigger when a telemetry value for a device reaches a
specific threshold. Use dynamic telemetry with the remote monitoring preconfigured solution describes how you
can add custom telemetry values, such as ExternalTemperature to your solution. This article shows you how to
create custom rule for dynamic telemetry types in your solution.
This tutorial uses a simple Node.js simulated device to generate dynamic telemetry to send to the preconfigured
solution back end. You then add custom rules in the Visual Studio solution and deploy this
customized back end to your Azure subscription.
To complete this tutorial, you need:
An active Azure subscription. If you don’t have an account, you can create a free trial account in just a couple of
minutes. For details, see Azure Free Trial.
Node.js version 0.12.x or later to create a simulated device.
Visual Studio 2015 or Visual Studio 2017 to modify the preconfigured solution back end with your new rules.

Provision the solution

If you haven't already provisioned the remote monitoring preconfigured solution in your account:
1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click on the tile.
3. Enter a for your remote monitoring preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you are encountering issues deploying the pre-configured solution, review Permissions on the azureiotsuite.com site and
the FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Give us feature suggestions on User Voice.
Make a note of the solution name you chose for your deployment. You need this solution name later in this tutorial.

Configure the Node.js simulated device

1. On the remote monitoring dashboard, click and then add a custom device. Make a note of the
IoT Hub hostname, device id, and device key. You need them later in this tutorial when you prepare the
remote_monitoring.js device client application.
2. Ensure that Node.js version 0.12.x or later is installed on your development machine. Run at a
command prompt or in a shell to check the version. For information about using a package manager to install
Node.js on Linux, see Installing Node.js via package manager.
3. When you have installed Node.js, clone the latest version of the azure-iot-sdk-node repository to your
development machine. Always use the branch for the latest version of the libraries and samples.
4. From your local copy of the azure-iot-sdk-node repository, copy the following two files from the
node/device/samples folder to an empty folder on your development machine:
packages.json
remote_monitoring.js
5. Open the remote_monitoring.js file and look for the following variable definition:

6. Replace with your device connection string. Use the values for your
IoT Hub hostname, device id, and device key that you made a note of in step 1. A device connection string
has the following format:

If your IoT Hub hostname is and your device id is , your connection string looks like the
following snippet:

7. Save the file. Run the following commands in a shell or command prompt in the folder that contains these
files to install the necessary packages and then run the sample application:

Observe dynamic telemetry in action

The dashboard shows the temperature and humidity telemetry from the existing simulated devices:
If you select the Node.js simulated device you ran in the previous section, you see temperature, humidity, and
external temperature telemetry:
The remote monitoring solution automatically detects the additional external temperature telemetry type and adds
it to the chart on the dashboard.
You can stop the Node.js console app when you have verified that it is sending telemetry to
the preconfigured solution. Keep the console window open because you run this Node.js console app again after
you add the custom rule to the solution.

Rule storage locations

Information about rules is persisted in two locations:
table – This table stores a normalized reference to the rules defined by the
solution portal. When the solution portal displays device rules, it queries this table for the rule definitions.
blob – This blob stores all the rules defined for all registered devices and is defined as a reference
input to the Azure Stream Analytics jobs.
When you update an existing rule or define a new rule in the solution portal, both the table and blob are updated to
reflect the changes. The rule definition displayed in the portal comes from the table store, and the rule definition
referenced by the Stream Analytics jobs comes from the blob.

Update the RemoteMonitoring Visual Studio solution

The following steps show you how to modify the RemoteMonitoring Visual Studio solution to include a new rule
that uses the telemetry sent from the simulated device:
1. If you have not already done so, clone the repository to a suitable location
on your local machine using the following Git command:

2. In Visual Studio, open the RemoteMonitoring.sln file from your local copy of the
repository.
3. Open the file Infrastructure\Models\DeviceRuleBlobEntity.cs and add an property as
follows:

4. In the same file, add an property as follows:

5. Open the file Infrastructure\Models\DeviceRuleDataFields.cs and add the following

property after the existing property:

6. In the same file, update the method to include as follows:

7. Open the file Infrastructure\Repository\DeviceRulesRepository.cs and modify the

method as follows:
Rebuild and redeploy the solution.
You can now deploy the updated solution to your Azure subscription.
1. Open an elevated command prompt and navigate to the root of your local copy of the azure-iot-remote-
monitoring repository.
2. To deploy your updated solution, run the following command substituting with the
name of your preconfigured solution deployment that you noted previously:

Update the Stream Analytics job

When the deployment is complete, you can update the Stream Analytics job to use the new rule definitions.
1. In the Azure portal, navigate to the resource group that contains your preconfigured solution resources. This
resource group has the same name you specified for the solution during the deployment.
2. Navigate to the {deployment name}-Rules Stream Analytics job.
3. Click to stop the Stream Analytics job from running. (You must wait for the streaming job to stop
before you can edit the query).
4. Click . Edit the query to include the statement for . The following
sample shows the complete query with the new statement:
5. Click to change the updated rule query.
6. Click to start the Stream Analytics job running again.

Add your new rule in the dashboard

You can now add the rule to a device in the solution dashboard.
1. Navigate to the solution portal.
2. Navigate to the panel.
3. Locate the custom device you created that sends telemetry and on the
panel, click .
4. Select in .
5. Set to 56. Then click .
6. Return to the dashboard to view the alarm history.
7. In the console window you left open, start the Node.js console app to begin sending
telemetry data.
8. Notice that the table shows new alarms when the new rule is triggered.

Additional information
Changing the operator is more complex and goes beyond the steps outlined in this tutorial. While you can change
the Stream Analytics job to use whatever operator you like, reflecting that operator in the solution portal is a more
complex task.

Next steps
Now that you've seen how to create custom rules, you can learn more about the preconfigured solutions:
Connect Logic App to your Azure IoT Suite Remote Monitoring preconfigured solution
Device information metadata in the remote monitoring preconfigured solution.
 Device information metadata in the remote
monitoring preconfigured solution
11/6/2017 • 5 min to read • Edit Online

The Azure IoT Suite remote monitoring preconfigured solution demonstrates an approach for managing device
metadata. This article outlines the approach this solution takes to enable you to understand:
What device metadata the solution stores.
How the solution manages the device metadata.

Context
The remote monitoring preconfigured solution uses Azure IoT Hub to enable your devices to send data to the
cloud. The solution stores information about devices in three different locations:

Identity registry Device id, authentication keys, enabled Built in to IoT Hub
state

Device twins Metadata: reported properties, desired Built in to IoT Hub

properties, tags

Cosmos DB Command and method history Custom for solution

IoT Hub includes a device identity registry to manage access to an IoT hub and uses device twins to manage device
metadata. There is also a remote monitoring solution-specific device registry that stores command and method
history. The remote monitoring solution uses a Cosmos DB database to implement a custom store for command
and method history.

NOTE
The remote monitoring preconfigured solution keeps the device identity registry in sync with the information in the Cosmos
DB database. Both use the same device id to uniquely identify each device connected to your IoT hub.

Device metadata
IoT Hub maintains a device twin for each simulated and physical device connected to a remote monitoring
solution. The solution uses device twins to manage the metadata associated with devices. A device twin is a JSON
document maintained by IoT Hub, and the solution uses the IoT Hub API to interact with device twins.
A device twin stores three types of metadata:
Reported properties are sent to an IoT hub by a device. In the remote monitoring solution, simulated devices
send reported properties at start-up and in response to commands and methods. You
can view reported properties in the and in the solution portal. Reported properties
are read only.
Desired properties are retrieved from the IoT hub by devices. It is the responsibility of the device to make any
necessary configuration change on the device. It is also the responsibility of the device to report the change
 back to the hub as a reported property. You can set a desired property value through the solution portal.
Tags only exist in the device twin and are never synchronized with a device. You can set tag values in the
solution portal and use them when you filter the list of devices. The solution also uses a tag to identify the icon
to display for a device in the solution portal.
Example reported properties from the simulated devices include manufacturer, model number, latitude, and
longitude. Simulated devices also return the list of supported methods as a reported property.

NOTE
The simulated device code only uses the and
desired properties to update the reported properties sent back to IoT Hub. All other
desired property change requests are ignored.

A device information metadata JSON document stored in the device registry Cosmos DB database has the
following structure:

NOTE
Device information can also include metadata to describe the telemetry the device sends to IoT Hub. The remote monitoring
solution uses this telemetry metadata to customize how the dashboard displays dynamic telemetry.

Lifecycle
When you first create a device in the solution portal, the solution creates an entry in the Cosmos DB database to
store command and method history. At this point, the solution also creates an entry for the device in the device
identity registry, which generates the keys the device uses to authenticate with IoT Hub. It also creates a device
twin.
When a device first connects to the solution, it sends reported properties and a device information message. The
reported property values are automatically saved in the device twin. The reported properties include the device
manufacturer, model number, serial number, and a list of supported methods. The device information message
includes the list of the commands the device supports including information about any command parameters.
When the solution receives this message, it updates the device information in the Cosmos DB database.
View and edit device information in the solution portal
The device list in the solution portal displays the following device properties as columns by default: ,
, , , , , , , and
 . You can customize the columns by clicking . The device properties and
drive the location in the Bing Map on the dashboard.

In the pane in the solution portal, you can edit desired properties and tags (reported properties
are read only).

You can use the solution portal to remove a device from your solution. When you remove a device, the solution
removes the device entry from identity registry and then deletes the device twin. The solution also removes
information related to the device from the Cosmos DB database. Before you can remove a device, you must
disable it.
Device information message processing
Device information messages sent by a device are distinct from telemetry messages. Device information messages
include the commands a device can respond to, and any command history. IoT Hub itself has no knowledge of the
metadata contained in a device information message and processes the message in the same way it processes any
device-to-cloud message. In the remote monitoring solution, an Azure Stream Analytics (ASA) job reads the
messages from IoT Hub. The stream analytics job filters for messages that contain
and forwards them to the host instance that runs in a web job. Logic in the
instance uses the device ID to find the Cosmos DB record for the specific device and update
the record.

NOTE
A device information message is a standard device-to-cloud message. The solution distinguishes between device information
messages and telemetry messages by using ASA queries.

Next steps
Now you've finished learning how you can customize the preconfigured solutions, you can explore some of the
other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Frequently asked questions for IoT Suite
IoT security from the ground up
 Predictive maintenance preconfigured solution
overview
11/14/2017 • 6 min to read • Edit Online

The predictive maintenance preconfigured solution is one of the Microsoft Azure IoT Suite preconfigured
solutions. This solution integrates real-time device telemetry collection with a predictive model created using
Azure Machine Learning.
With Azure IoT Suite, you can quickly and easily connect to and monitor assets, and analyze telemetry in real time
in dashboards and visualizations. In the predictive maintenance solution, the dashboards and visualizations
provide you with new intelligence that can drive efficiencies and enhance revenue streams.

The Scenario
Fabrikam is a regional airline that focuses on great customer experience at competitive prices. One cause of flight
delays is maintenance issues and aircraft engine maintenance is particularly challenging. Fabrikam must avoid
engine failure during flight at all costs, so it inspects its engines regularly and schedules maintenance according
to a plan. However, aircraft engines don’t always wear the same. Some unnecessary maintenance is performed
on engines. More importantly, issues arise which can ground an aircraft until maintenance is performed. If an
aircraft is at a location where the right technicians or spare parts are not available, these issues can be especially
costly.
The engines of Fabrikam’s aircraft are instrumented with sensors that monitor engine conditions during flight.
Fabrikam uses the predictive maintenance solution to collect the sensor data collected during the flight. After
accumulating years of engine operational and failure data, Fabrikam’s data scientists have modeled a way to
predict the Remaining Useful Life (RUL) of an aircraft engine. The model uses a correlation between data from
four of the engine sensors and engine wear that leads to eventual failure. While Fabrikam continues to perform
regular inspections to ensure safety, it can now use the models to compute the RUL for each engine after every
flight. The model uses the telemetry collected from the engines during the flight. Fabrikam can now predict future
points of failure and plan for maintenance and repair in advance.

NOTE
The solution model uses actual engine wear data.

By predicting the point when maintenance is required, Fabrikam can optimize its operations to reduce costs.
Maintenance coordinators work with schedulers to:
Plan maintenance to coincide with an aircraft stopping at a particular location.
Ensure sufficient time is available for the aircraft to be out of service without causing schedule disruption.
To schedule technicians to ensure that aircraft are serviced efficiently without wait time.
Inventory control managers receive maintenance plans, so they can optimize their ordering process and spare
parts inventory.
These activities enable Fabrikam to minimize aircraft ground time and reduce operating costs while ensuring the
safety of passengers and crew.
To understand how Azure IoT Suite provides the capabilities customers need to realize the potential of predictive
maintenance, review this infographic.

How the predictive maintenance solution is built

The solution uses an existing Azure Machine Learning model available as a template to show these capabilities
working from device telemetry collected through IoT Suite services. Microsoft has built a regression model of an
aircraft engine based on publically available data[1], and step-by-step guidance on how to use the model.
The Azure IoT predictive maintenance solution uses the regression model created from this template. The model
is deployed into your Azure subscription and exposed through an automatically generated API. The solution
includes a subset of the testing data representing 4 (of 100 total) engines and the 4 (of 21 total) sensor data
streams. This data is sufficient to provide an accurate result from the trained model.
[1] A. Saxena and K. Goebel (2008). "Turbofan Engine Degradation Simulation Data Set", NASA Ames Prognostics
Data Repository (http://ti.arc.nasa.gov/tech/dash/pcoe/prognostic-data-repository/), NASA Ames Research
Center, Moffett Field, CA

Get started with predictive maintenance

This tutorial shows you how to provision the predictive maintenance solution. It also walks you through the basic
features of the predictive maintenance solution. You can access many of these features through the solution
dashboard that deploys along with the preconfigured solution.
To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

1. Log on to azureiotsuite.com using your Azure account credentials, and click to create a solution.
2. Click the tile.
3. Enter a for your predictive maintenance preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
Wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane. From this pane, you can launch the
solution dashboard and access the Machine Learning workspace.

NOTE
If you encounter issues deploying the preconfigured solution, review Permissions on the azureiotsuite.com site and the
FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Make feature suggestions on User Voice.

View the solution

This section guides you through the solution UI.
Predictive Maintenance Dashboard
This page in the web application uses PowerBI JavaScript controls (see the PowerBI-visuals repository) to
visualize:
The output data from the Stream Analytics jobs in blob storage.
The RUL and cycle count per aircraft engine.
Observing the behavior of the cloud solution
In the Azure portal, navigate to the resource group with the solution name you chose to view your provisioned
resources.

When you provision the preconfigured solution, you receive an email with a link to the Machine Learning
workspace. You can also navigate to the Machine Learning workspace from the azureiotsuite.com page for your
provisioned solution. A tile is available on this page when the solution is in the state.
In the solution portal, you can see that the sample is provisioned with four simulated devices to represent two
aircraft with two engines per aircraft, each with four sensors. When you first navigate to the solution portal, the
simulation is stopped.

Click to begin the simulation. The sensor history, RUL, Cycles, and RUL history populate the
dashboard.
When RUL is less than 160 (an arbitrary threshold chosen for demonstration purposes), the solution portal
displays a warning symbol next to the RUL display. The solution portal also highlights the aircraft engine in
yellow. Notice how the RUL values have a general downward trend overall, but tend to bounce up and down. This
behavior results from the varying cycle lengths and the model accuracy.

The full simulation takes around 35 minutes to complete 148 cycles. The 160 RUL threshold is met for the first
time at around 5 minutes and both engines hit the threshold at around 8 minutes.
The simulation runs through the complete dataset for 148 cycles and settles on final RUL and cycle values.
You can stop the simulation at any point, but clicking replays the simulation from the start of
the dataset.

Next steps
To learn more about how Azure IoT enables predictive maintenance scenarios, read Capture value from the
Internet of Things.
Take a walkthrough of the predictive maintenance solution.
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Frequently asked questions for IoT Suite
IoT security from the ground up
 Predictive maintenance preconfigured solution
walkthrough
11/14/2017 • 3 min to read • Edit Online

The predictive maintenance preconfigured solution is an end-to-end solution for a business scenario that predicts
the point at which a failure is likely to occur. You can use this preconfigured solution proactively for activities such
as optimizing maintenance. The solution combines key Azure IoT Suite services, such as IoT Hub, Stream analytics,
and an Azure Machine Learning workspace. This workspace contains a model, based on a public sample data set, to
predict the Remaining Useful Life (RUL) of an aircraft engine. The solution fully implements the IoT business
scenario as a starting point for you to plan and implement a solution that meets your own specific business
requirements.

Logical architecture
The following diagram outlines the logical components of the preconfigured solution:

The blue items are Azure services provisioned in the region where you deployed the preconfigured solution. The
list of regions where you can deploy the preconfigured solution displays on the provisioning page.
The green item is a simulated device that represents an aircraft engine. You can learn more about these simulated
devices in the Simulated devices section.
The gray items represent components that implement device management capabilities. The current release of the
predictive maintenance preconfigured solution does not provision these resources. To learn more about device
management, refer to the remote monitoring pre-configured solution.

Simulated devices
In the preconfigured solution, a simulated device represents an aircraft engine. The solution is provisioned with two
engines that map to a single aircraft. Each engine emits four types of telemetry: Sensor 9, Sensor 11, Sensor 14,
and Sensor 15 provide the data necessary for the Machine Learning model to calculate the RUL for the engine.
Each simulated device sends the following telemetry messages to IoT Hub:
Cycle count. A cycle represents a completed flight with a duration between two and ten hours. During the flight,
telemetry data is captured every half hour.
Telemetry. There are four sensors that represent engine attributes. The sensors are generically labeled Sensor 9,
Sensor 11, Sensor 14, and Sensor 15. These four sensors represent telemetry sufficient to obtain useful results
from the RUL model. The model used in the preconfigured solution is created from a public data set that includes
real engine sensor data. For more information on how the model was created from the original data set, see the
Cortana Intelligence Gallery Predictive Maintenance Template.
The simulated devices can handle the following commands sent from the IoT hub in the solution:

StartTelemetry Controls the state of the simulation.

Starts the device sending telemetry

StopTelemetry Controls the state of the simulation.

Stops the device sending telemetry

IoT Hub provides device command acknowledgment.

Azure Stream Analytics job

operates on the incoming device telemetry stream using two statements:
The first selects all telemetry from the devices and sends this data to blob storage. From here, it is visualized in
the web app.
The second computes average sensor values over a two-minute sliding window and sends this data through the
Event hub to an .

Event processor
The runs in an Azure Web Job. The takes the average sensor values for a
completed cycle. It then passes those values to an API that exposes trained model to calculate the RUL for an
engine. The API is exposed by a Machine Learning workspace that is provisioned as part of the solution.

Machine Learning
The Machine Learning component uses a model derived from data collected from real aircraft engines. You can
navigate to the Machine Learning workspace from your solution's tile on the azureiotsuite.com page. The tile is
available when the solution is in the state.

Next steps
Now you've seen the key components of the predictive maintenance preconfigured solution, you may want to
customize it. See Guidance on customizing preconfigured solutions.
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Frequently asked questions for IoT Suite
IoT security from the ground up
 Get started with the Connected factory
preconfigured solution
12/12/2017 • 11 min to read • Edit Online

Azure IoT Suite preconfigured solutions combine multiple Azure IoT services to deliver end-to-end solutions that
implement common IoT business scenarios. The Connected factory preconfigured solution connects to and
monitors your industrial devices. You can use the solution to analyze the stream of data from your devices and to
drive operational productivity and profitability.
This tutorial shows you how to provision the Connected factory preconfigured solution. It also walks you through
the basic features of the preconfigured solution. You can access many of these features from the solution
dashboard that deploys as part of the preconfigured solution:

To complete this tutorial, you need an active Azure subscription.

NOTE
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Provision the solution

1. Log on to azureiotsuite.com using your Azure account credentials, and click " " to create a solution.
2. Click on the tile.
3. Enter a for your Connected factory preconfigured solution.
4. Select the and you want to use to provision the solution.
5. Click to begin the provisioning process. This process typically takes several minutes to run.
While you wait for the provisioning process to complete
1. Click the tile for your solution with status.
2. Notice the as Azure services are deployed in your Azure subscription.
3. Once provisioning completes, the status changes to .
4. Click the tile to see the details of your solution in the right-hand pane.

NOTE
If you encounter issues deploying the preconfigured solution, review Permissions on the azureiotsuite.com site and the
Connected factory FAQ. If the issues persist, create a service ticket on the portal.

Are there details you'd expect to see that aren't listed for your solution? Make feature suggestions on User Voice.

Scenario overview
When you deploy the Connected factory preconfigured solution, it is prepopulated with resources that enable you
to step through a common industrial scenario. In this scenario, several factories connected to the solution report
the data values required to compute overall equipment efficiency (OEE) and key performance indicators (KPIs).
The following sections show you how to:
Monitor factory, production lines, station OEE, and KPI values
Analyze the telemetry data generated from these devices using Azure Time Series Insights
Act on alarms to fix issues
A key feature of this scenario is that you can perform all these actions remotely from the solution dashboard. You
do not need physical access to the devices.

View the solution dashboard

The solution dashboard enables you to manage the deployed solution. It is a hierarchical representation of a
global factory configuration. For example, you can view OEE and KPIs, publish new nodes for telemetry and action
alarms.
1. When the provisioning is complete and the tile for your preconfigured solution indicates , choose
to open your Connected factory solution portal in a new tab.
2. By default, the solution portal shows the dashboard. To navigate to other areas of the portal, use the menu
on the left-hand side of the page.

The dashboard displays the following information:

A panel that shows the status, location, and current production configuration in the
solution. When you first run the solution, there are a number of simulated devices. The production line
simulation is composed of three real OPC UA servers per production line that perform simulated tasks and
share data. For more information about OPC UA, see the Connected factory FAQ.
A that displays the location of each device connected to the solution. The solution can use the Bing Maps
API to plot information on the map. If your subscription is enabled for Bing Maps Enterprise API, then this
feature is used automatically. If not, see the FAQ to learn how to make the map dynamic.
An panel that displays alarms generated when a telemetry or OEE/KPI value exceeds a specific
 threshold.
An panel that shows the OEE values for the whole enterprise, or the
factory/production line/station you are viewing. This value is aggregated from the station view to the
enterprise level. The OEE figure and its constituent elements can be further analyzed.
panel that displays the number of units produced and energy used by the
whole enterprise or the factory/production line/station you are viewing. These values are aggregated from a
station view to the enterprise level.

View factories
The Factory Locations panel shows you the geographical location of all the factories in the solution, their status,
and current production configuration. From the locations list, you can navigate to the other levels in the solution
hierarchy. The rows in the list are hyperlinks that link details of the production lines at that location. It is then
possible to drill into the production line details and down to the station level view. You can also apply a filter to
the list.

1. The shows the factory list for this solution.

2. The factory list initially shows six factories created by the provisioning process. You can add additional
simulated and physical devices to the solution.
3. To view the details of a factory, click the row in the factory list.
4. To view the details of a production line, click the row in the list.
5. To view the published OPC UA nodes of a station on the production line, click the row in the list.
6. To view details on a specific node in the station, click the row in the list. This action launches the context
panel with Time Series Insights visualizations. Click these graphs to do further analysis in the Time Series
Insights explorer environment.

View map
If your subscription has access to the Bing Maps API, the Factories map shows you the geographical location and
status of all the factories in the solution. To drill into the location details, click the locations displayed on the map.

View alarms
The panel shows you alarms generated due to a reported value or a calculated OEE/KPI value exceeding
its configured threshold. This panel displays alarms at each level of the hierarchy, from the station level view to
the global view. The alarms contain a description of the alarm, date, time, location, and number of occurrences.
You can gain insights in to the data that caused the alarm using the Time Series Insights data. The Time Series
Insights data is visualized in the alarms where applicable. If you are an Administrator, you can take default actions
on the alarms such as:
Close the alarm.
Acknowledge the alarm.
Optionally, you can take more complex actions. For example, for the Pressure OPC UA Node of the Assembly you
could:
Show supporting information in a web page in a new browser window.
Mitigate the cause of the alarm by calling an OPC UA method on the device.
Suppress the availability of the default actions.
 NOTE
These alarms are generated by rules that are specified in a configuration file in the preconfigured solution. These rules can
generate alarms when the OEE or KPI figures or OPC UA Node values are exceeding their configured threshold.

1. The shows the alarms generated in this solution.

2. To view the details of an alarm, click the alarm in the alarms panel.
3. To further analyze the alarm data, click the graph in the alarm panel to open the Time Series Insights
explorer environment.
4. To address the alarm, several actions are available in the alarm panel. Choose the appropriate option for
you and click the execute action command button.

View overall equipment efficiency

OEE rates the efficiency of the manufacturing process using a key production-related operational parameters. OEE
is an industry standard measure calculated by multiplying the availability rate, performance rate, and quality rate:
OEE = availability x performance x quality.
1. To view OEE for any level in the hierarchy, navigate to the specific view you require. The OEE for that view
displays in the panel along with each of the elements that make up the OEE percentage.
2. To further analyze the OEE for any level in the hierarchy data, click either the OEE, availability, performance,
or quality percentage. A context panel appears with Time Series Insights powered visualizations that shows
data from the last hour, last 24 hours, and last 7 days.

3. To further analyze the alarm data, click the graph in the alarm panel. This action opens the Time Series
Insights explorer environment.
View Key Performance Indicators
The solution provides two key performance indicators, units per hour and energy used in kWh.

1. To view units per hour or energy used for any level in the hierarchy, navigate to the specific view you
require. The units per hour and energy used display in the panel.
2. To analyze units per hour or energy used for any level in the hierarchy, click the gauge in the
panel. A context panel appears with Time Series Insights powered visualizations
enabling you to view data from the last hour, the last 24 hours, and last 7 days.

Scenario review
In this scenario, you monitored your factories OEE and KPIs values, in the dashboard. You then used Time Series
Insights to provide more information to help drill further into the telemetry data for OEE and KPIs to help with
detecting anomalies. You also used the alarm panel to view issues with your factories and you used the actions
available to you to resolve the alarm.
Other features
The following sections describe some additional features of the Connected factory solution that are not described
in the previous scenario.

Apply filters
1. Click the icon to display a list of available filters in either the factory locations panel or the alarms
panel.
2. The filters panel is displayed for you.

3. Choose the filter that you require. It is also possible to type free text into the filter fields.
4. The filter is then applied for you. The filter state is also shown in the dashboard via a funnel that displays in
the factories and alarms tables.
 NOTE
An active filter does not affect the displayed OEE and KPI values, it only filters the list contents.

5. To clear a filter, click the funnel and click filter in the filter context panel. The text is displayed in the
factories and alarms tables.

Browse an OPC UA server

When you deploy the preconfigured solution, you automatically provision simulated OPC UA servers that you can
browse via the solution browser. These servers are simulated OPC UA servers. Simulated servers make it easy for
you to experiment with the preconfigured solution without the need to deploy real, physical servers. If you do
want to connect a real OPC UA server to the solution, see the Connect your OPC UA device to the Connected
factory preconfigured solution tutorial.
1. Click the in the dashboard navigation bar.
2. Choose one of the servers from the preconfigured list. This list shows the servers that are deployed for you
in the preconfigured solution.

3. Click , a security dialog displays. For the simulation, it is safe to click

4. To expand any of the nodes in the server tree, click it. Nodes that are publishing telemetry have a tick mark
beside them.
5. Right-click an item to read, write, publish, or call that node. The actions available to you depend on your
permissions and the attributes of the node. The read option displays a context panel showing the value of
the specific node. The write option displays a context panel where you can enter a new value. The call
option displays a node where you can enter the parameters for the call.

Publish a node
When you browse a simulated OPC UA server, you can also choose to publish new nodes. You can analyze the
telemetry from these nodes in the solution. These simulated OPC UA servers make it easy to experiment with the
preconfigured solution without deploying real, physical devices.
1. Browse to a node in the OPC UA server browser tree that you wish to publish.
2. Right-click the node.
3. Choose .
4. A context panel appears which tells you that the publish has succeeded. The node appears in the station
level view with a check mark beside it.

Command and control

The Connected factory allows you command and control your industry devices directly from the cloud. You can
use this feature to respond to alarms generated by the device. For example, you could send a command to the
device from the cloud. You can find the available commands in the node in the OPC UA
servers browser tree. In this scenario, you open a pressure release valve on the assembly station of a production
line in Munich. To use the command and control functionality, you must be in the role for the
preconfigured solution deployment.
1. Browse to the node in the OPC UA server browser tree.
2. Choose the command that you wish use.
3. Right-click the node.
4. Choose .

5. A context panel appears informing you which method you are about to call and any parameter details is
applicable.
6. Choose .

7. The context panel is updated to inform you that the method call succeeded. You can verify the call
 succeeded by reading the value of the pressure node that updated as a result of the call.

Behind the scenes

When you deploy a preconfigured solution, the deployment process creates multiple resources in the Azure
subscription you selected. You can view these resources in the Azure portal. The deployment process creates a
with a name based on the name you choose for your preconfigured solution:

You can view the settings of each resource by selecting it in the list of resources in the resource group.
You can also view the source code for the preconfigured solution. The Connected factory preconfigured solution
source code is in the azure-iot-connected-factory GitHub repository:
When you are done, you can delete the preconfigured solution from your Azure subscription on the
azureiotsuite.com site. This site enables you to easily delete all the resources that were provisioned when you
created the preconfigured solution.

NOTE
To ensure that you delete everything related to the preconfigured solution, delete it on the azureiotsuite.com site. Do not
delete the resource group in the portal.

Next Steps
Now that you’ve deployed a working preconfigured solution, you can continue getting started with IoT Suite by
reading the following articles:
Connected factory preconfigured solution walkthrough
Connect your device to the Connected factory preconfigured solution
Permissions on the azureiotsuite.com site
 Connected factory preconfigured solution
walkthrough
12/12/2017 • 8 min to read • Edit Online

The IoT Suite Connected factory preconfigured solution is an implementation of an end-to-end industrial solution
that:
Connects to both simulated industrial devices running OPC UA servers in simulated factory production lines,
and real OPC UA server devices. For more information about OPC UA, see the Connected factory FAQ.
Shows operational KPIs and OEE of those devices and production lines.
Demonstrates how a cloud-based application could be used to interact with OPC UA server systems.
Enables you to connect your own OPC UA server devices.
Enables you to browse and modify the OPC UA server data.
Integrates with the Azure Time Series Insights (TSI) service to provide customized views of the data from your
OPC UA servers.
You can use the solution as a starting point for your own implementation and customize it to meet your own
specific business requirements.
This article walks you through some of the key elements of the Connected factory solution to enable you to
understand how it works. The article also describes how data flows through the solution. This knowledge helps you
to:
Troubleshoot issues in the solution.
Plan how to customize to the solution to meet your own specific requirements.
Design your own IoT solution that uses Azure services.
For more information, see the Connected factory FAQ.

Logical architecture
The following diagram outlines the logical components of the preconfigured solution:
Communication patterns
The solution uses the OPC UA Pub/Sub specification to send OPC UA telemetry data to IoT Hub in JSON format.
The solution uses the OPC Publisher IoT Edge module for this purpose.
The solution also has an OPC UA client integrated into a web application that can establish connections with on-
premises OPC UA servers. The client uses a reverse-proxy and receives help from IoT Hub to make the connection
without requiring open ports in the on-premises firewall. This communication pattern is called service-assisted
communication. The solution uses the OPC Proxy IoT Edge module for this purpose.

Simulation
The simulated stations and the simulated manufacturing execution systems (MES) make up a factory production
line. The simulated devices and the OPC Publisher Module are based on the OPC UA .NET Standard published by
the OPC Foundation.
The OPC Proxy and OPC Publisher are implemented as modules based on Azure IoT Edge. Each simulated
production line has a designated gateway attached.
All simulation components run in Docker containers hosted in an Azure Linux VM. The simulation is configured to
run eight simulated production lines by default.

Simulated production line

A production line manufactures parts. It is composed of different stations: an assembly station, a test station, and a
packaging station.
The simulation runs and updates the data that is exposed through the OPC UA nodes. All simulated production line
stations are orchestrated by the MES through OPC UA.

Simulated manufacturing execution system

The MES monitors each station in the production line through OPC UA to detect station status changes. It calls OPC
UA methods to control the stations and passes a product from one station to the next until it is complete.
Gateway OPC publisher module
OPC Publisher Module connects to the station OPC UA servers and subscribes to the OPC nodes to be published.
The module converts the node data into JSON format, encrypts it, and sends it to IoT Hub as OPC UA Pub/Sub
messages.
The OPC Publisher module only requires an outbound https port (443) and can work with existing enterprise
infrastructure.

Gateway OPC proxy module

The Gateway OPC UA Proxy Module tunnels binary OPC UA command and control messages and only requires an
outbound https port (443). It can work with existing enterprise infrastructure, including Web Proxies.
It uses IoT Hub Device methods to transfer packetized TCP/IP data at the application layer and thus ensures
endpoint trust, data encryption, and integrity using SSL/TLS.
The OPC UA binary protocol relayed through the proxy itself uses UA authentication and encryption.

Azure Time Series Insights

The Gateway OPC Publisher Module subscribes to OPC UA server nodes to detect change in the data values. If a
data change is detected in one of the nodes, this module then sends messages to Azure IoT Hub.
IoT Hub provides an event source to Azure TSI. TSI stores data for 30 days based on timestamps attached to the
messages. This data includes:
OPC UA ApplicationUri
OPC UA NodeId
Value of the node
Source timestamp
OPC UA DisplayName
Currently, TSI does not allow customers to customize how long they wish to keep the data for.
TSI queries against node data using a ( , ) and aggregates by
or or .
To retrieve the data for the OEE and KPI gauges, and the time series charts, data is aggregated by count of events,
Sum, Avg, Min, and Max.
The time series are built using a different process. OEE and KPIs are calculated from station base data and bubbled
up for the topology (production lines, factories, enterprise) in the application.
Additionally, time series for OEE and KPI topology is calculated in the app, whenever a displayed timespan is ready.
For example, the day view is updated every full hour.
The time series view of node data comes directly from TSI using an aggregation for timespan.

IoT Hub
The IoT hub receives data sent from the OPC Publisher Module into the cloud and makes it available to the Azure
TSI service.
The IoT Hub in the solution also:
Maintains an identity registry that stores the IDs for all OPC Publisher Module and all OPC Proxy Modules.
Is used as transport channel for bidirectional communication of the OPC Proxy Module.
Azure Storage
The solution uses Azure blob storage as disk storage for the VM and to store deployment data.

Web app
The web app deployed as part of the preconfigured solution comprises of an integrated OPC UA client, alerts
processing and telemetry visualization.

Telemetry data flow

Flow steps
1. OPC Publisher reads the required OPC UA X509 certificates and IoT Hub security credentials from the local
certificate store.
If necessary, OPC Publisher creates and stores any missing certificates or credentials in the certificate
store.
2. OPC Publisher registers itself with IoT Hub.
Uses the configured protocol. Can use any IoT Hub client SDK supported protocol. The default is MQTT.
Protocol communication is secured by TLS.
3. OPC Publisher reads configuration file.
4. OPC Publisher creates an OPC Session with each configured OPC UA Server.
Uses TCP connection.
OPC Publisher and OPC UA Server authenticate each other using X509 certificates.
All further OPC UA traffic is encrypted by the configured OPC UA encryption mechanism.
OPC Publisher creates, in the OPC Session for each configured publishing interval, an OPC Subscription.
Creates OPC Monitored items for the OPC Nodes to publish in the OPC Subscription.
5. If a monitored OPC Node value changes, OPC UA Server sends updates to OPC Publisher.
6. OPC Publisher transcodes the new value.
 Batches multiple changes if batching is enabled.
Creates an IoT Hub message.
7. OPC Publisher sends a message to IoT Hub.
Use the configured protocol.
Communication is secured by TLS.
8. Time Series Insights (TSI) reads the messages from IoT Hub.
Uses AMQP over TCP/TLS.
This step is internal to the datacenter.
9. Data at rest in TSI.
10. Connected factory WebApp in Azure AppService queries required data from TSI.
Uses TCP/TLS secured communication.
This step is internal to the datacenter.
11. Web browser connects to the Connected factory WebApp.
Renders the Connected factory dashboard.
Connects over HTTPS.
Access to the Connected factory App requires authentication of the user via Azure Active Directory.
Any WebApi calls into Connected factory app are secured by Anti-Forgery-Tokens.
12. On data updates, the Connected factory WebApp sends updated data to the web browser.
Uses the SignalR protocol.
Secured by TCP/TLS.

Browsing data flow

Flow steps
1. OPC Proxy (server component) starts up.
Reads the shared access keys from a local store.
If necessary, stores missing access keys in the store.
2. OPC Proxy (server component) registers itself with IoT Hub.
Reads all it's known devices from IoT Hub.
Uses MQTT over TLS over Socket or Secure Websocket.
 3. Web browser connects to the Connected factory WebApp and renders the Connected factory dashboard.
Uses HTTPS.
A user selects an OPC UA server to connect to.
4. Connected factory WebApp establishes an OPC UA Session to the selected OPC UA server.
Uses OPC UA stack.
5. OPC Proxy transport receives a request from the OPC UA stack to establish a TCP socket connection to OPC
UA server.
It just retrieves the TCP payload and uses it unchanged.
This step is internal to the Connected factory WebApp.
6. OPC Proxy (client component) looks up OPC Proxy (server component) device in the IoT Hub device registry.
Then calls a device method of the OPC Proxy (server component) device in IoT Hub.
Uses HTTPS over TCP/TLS to look up OPC Proxy.
Uses using HTTPS over TCP/TLS to establish a TCP socket connection to the OPC UA server.
This step is internal to the datacenter.
7. IoT Hub calls a device method in the OPC Proxy (server component) device.
Uses an established MQTT over TLS over Socket or Secure Websocket connection to establish a TCP
socket connection to the OPC UA server.
8. OPC Proxy (server component) sends the TCP payload on to the shopfloor network.
9. The OPC UA server processes the payload and sends back the response.
10. The response is received by the socket of the OPC Proxy (server component).
OPC Proxy sends the data as return value of the device method to IoT Hub and the OPC Proxy (client
component).
This data is delivered to the OPC UA stack in the Connected factory app.
11. Connected factory WebApp returns OPC Browser UX enriched with the OPC UA-specific information it
received from the OPC UA server to the Web Browser to render it.
While browsing through the OPC address-space and applying functions to nodes in the OPC address-
space, the OPC Browser UX client part uses AJAX calls over HTTPS secured with Anti-Forgery Tokens to
get data from the Connected factory WebApp.
If necessary, the client uses the communication explained in steps 4 through to 10 to exchange
information with the OPC UA server.

NOTE
The OPC Proxy (server component) and OPC Proxy (client) component complete steps #4 through #10 for all TCP traffic
related to the OPC UA communication.

NOTE
For the OPC UA server and the OPC UA stack within the Connected factory WebApp, the OPC Proxy communication is
transparent and all OPC UA security features for authentication and encryption apply.

Next steps
You can continue getting started with IoT Suite by reading the following articles:
Permissions on the azureiotsuite.com site
Deploy a gateway on Windows or Linux for the Connected factory preconfigured solution
OPC Publisher reference implementation.
 Deploy the Azure IoT Device Simulation solution
12/20/2017 • 1 min to read • Edit Online

This tutorial shows you how to provision a Device Simulation solution. You deploy the solution from
azureiotsuite.com.
In this tutorial, you learn how to:
Configure the Device Simulation solution
Deploy the Device Simulation solution
Sign in to the Device Simulation solution

Prerequisites
To complete this tutorial, you need an active Azure subscription.
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure
Free Trial.

Deploy the solution

Before you deploy the solution to your Azure subscription, you must choose some configuration options:
1. Sign in to azureiotsuite.com using your Azure account credentials, and click to create a new solution:

2. Click on the tile:

3. On the page, enter a for your Device Simulation
solution.
4. Select the and you want to use to provision the solution.
5. Specify if you want a new IoT Hub deployed with your Device Simulation solution. If you check this box, a
new IoT Hub is deployed into your subscription. Regardless of choice, you can always point your simulation
at any IoT Hub.
6. Click to begin the provisioning process. This process typically takes several minutes to run:
Sign in to the solution
When the provisioning process is complete, you can sign in to your Device Simulation solution.
1. On the page, click under your new Device Simulation solution:

2. You can view information about your Device Simulation solution in the panel that appears. Choose
 to connect to your Device Simulation solution.

NOTE
You can delete your Device Simulation solution from this panel when you are finished with it.

3. The Device Simulation solution dashboard displays in your browser.

Next steps
In this tutorial, you learned how to:
Configure the solution
Deploy the solution
Sign in to the solution
Now that you have deployed the Device Simulation solution, the next step is to explore the capabilities of the
Device Simulation solution.
 Device Simulation walkthrough
12/20/2017 • 4 min to read • Edit Online

Azure IoT Device Simulation is a tool that can be used to assist in the development and testing of an IoT solution.
Device Simulation is a standalone offering that you can use in conjunction with other preconfigured solutions or
with your own custom solutions.
This tutorial walks you through some of the features of Device Simulation. It shows you how it works, and enables
you to use it to test your own IoT solutions.
In this tutorial, you learn how to:
Configure a simulation
Starting and stopping a simulation
View telemetry metrics

Prerequisites
To complete this tutorial, you need a deployed instance of Azure IoT Device Simulation in your Azure subscription.
If you haven't deployed Device Simulation yet, you should complete the Deploy Azure IoT Device Simulation
tutorial.

Configuring Device Simulation

You can configure and run Device Simulation completely from within the dashboard. Open the dashboard from the
IoT Suite Provisioned solutions page. Click under your new Device Simulation deployment.
Target IoT Hub
You can use Device Simulation with a pre-provisioned IoT hub or with any other IoT hub:
 NOTE
The option to use a pre-provisioned IoT Hub is only available if you chose to create a new IoT Hub when you deployed
Device Simulation. If you don't have an IoT hub, you can always create a new one from the Azure portal.

To target a specific IoT hub, provide the connection string. You can get this connection string from
the Azure portal:
1. On the IoT Hub configuration page in the Azure portal, click .
2. Click .
3. Copy either the primary or secondary key.
4. Paste this value into the text box under Target IoT Hub.
Device model
The device model enables you to choose the type of device to simulate. You can choose one of the pre-configured
device models or define a list of sensors for a custom device model:
Pre-Configured device models
Device Simulation provides three pre-configured device models. Device models for Chillers, Elevators, and Trucks
are available.
Pre-configured device models include multiple sensors with a pre-determined telemetry frequency. You cannot
customize the telemetry frequency for these devices.
The following table shows a list of the configurations for each pre-configured device model:

Chiller humidity % 5 seconds

pressure psig 5 seconds

temperature F 5 seconds

Elevator Floor 5 seconds

Vibration mm 5 seconds

Temperature F 5 seconds
 Truck Latitude 3 seconds

Longitude 3 seconds

speed mph 5 seconds

cargotemperature F 5 seconds

Custom device model

Custom device models enable you to model sensors that more closely represent your own devices. A custom
device can have up to 10 custom sensors.
When you select the custom device model type, you can add new sensors by clicking .

Custom sensors have the following properties:

Sensor Name A friendly name for the sensor such as or

.
 Behavior Behaviors enable telemetry data to vary from one message to
the next to simulate real-world data. increases the
value by one in each message sent starting at the minimum
value. Once the maximum value is met, then it starts over
again at the minimum value. behaves in the same
way as but counts down. The behavior
generates a random value between the minimum value and
maximum values.

Min Value The lowest number representing your acceptable range.

Max Value The largest number representing your acceptable range.

Unit The unit of measurement for the sensor such as °F or MPH.

Number of devices
Device Simulation currently enables you to simulate up to 1,000 devices.

Telemetry frequency
Telemetry frequency enables you to specify how often your simulated devices should send data to the IoT hub. You
can send data as frequently as every 10 seconds or as infrequently every as 99 hours, 59 minutes, and 59 seconds.
 NOTE
If you are using an IoT hub other than the pre-provisioned IoT hub, then you should consider message limits for your target
IoT hub. For example, if you have 1,000 simulated devices sending telemetry every 10 seconds to an S1 hub you reach the
telemetry limit for the hub in just over an hour.

Simulation duration
You can choose to run your simulation for a specific length of time or to run until you explicitly stop it. When you
choose a specific length of time, you can choose any duration from 10 minutes up to 99 hours, 59 minutes, and 59
seconds.
Start and stop the simulation
When you have added all the necessary configuration data to the form, the button is enabled. To
start the simulation, click this button.
If you specified a specific duration for your simulation, then it stops automatically when the time has been reached.
You can always stop the simulation early by clicking
If you chose to run your simulation indefinitely, then it runs until you click . You can close your
browser and come back to the Device Simulation page to stop your simulation at any time.
NOTE
Only one simulation can be run at a time. You must stop the currently running simulation before you start a new simulation.
 Perform advanced monitoring using the remote
monitoring solution
12/13/2017 • 2 min to read • Edit Online

This tutorial shows the capabilities of the remote monitoring dashboard. To introduce these capabilities, the
tutorial uses a scenario in the Contoso IoT application.
In this tutorial, you use two simulated Contoso truck devices to learn how to monitor your devices from the
preconfigured solution dashboard. As a Contoso operator, you need to monitor the location and behavior of your
trucks in the field.
In this tutorial, you learn how to:
Filter the devices in the dashboard
View real-time telemetry
View device details
View alarms from your devices
View the system KPIs

Prerequisites
To follow this tutorial, you need a deployed instance of the remote monitoring solution in your Azure subscription.
If you haven't deployed the remote monitoring solution yet, you should complete the Deploy the remote
monitoring preconfigured solution tutorial.

Choose the devices to display

To select which devices display on the page, use filters. To display only the devices, choose the
built-in filter in the filter drop-down:
When you apply a filter, only those devices that match the filter conditions display in the map on the
page:

The filter also determines which devices you see in the chart:

To create, edit, and delete filters, choose .

View real-time telemetry

The preconfigured solution plots detailed real-time telemetry data in the chart on the page. The
telemetry chart shows telemetry information for the devices selected by the current filter:
To select the telemetry values to view, choose the telemetry type at the top of the chart:

To pause the live telemetry display, choose . To re-enable the live display, choose :
Use the map
The map displays information about the simulated trucks selected by the current filter. You can zoom and pan the
map to display locations in more or less detail. The device icons on the map indicate any or that
are active for the device. A summary of the number of and displays to the left of the map.
To view the device details, pan and zoom the map to locate the devices, then click the device on the map. The
details include:
Recent telemetry values
Methods the device supports
Device properties

View alarms from your devices

The map highlights the devices in the current filter with and . The panel displays
detailed information about the most recent alarms from your devices:

You can use the filter to adjust the time span for recent alarms. By default, the panel displays
alarms from the last hour:

View the system KPIs

The page displays system KPIs:
You can use the filter to adjust the time span for the KPI aggregation. By default, the panel displays
KPIs aggregated over the last hour.

Next steps
This tutorial showed you how to use the page to filter and monitor the simulated trucks provisioned in
your remote monitoring solution:
Filter the devices in the dashboard
View real-time telemetry
View device details
View alarms from your devices
View the system KPIs
Now that you have learned how to monitor your devices, the suggested next steps are to learn how to:
Detect issues using threshold-based rules.
Manage and configure your devices.
Troubleshoot and remediate device issues.
Test your solution with simulated devices.
 Detect issues using threshold-based rules
12/13/2017 • 2 min to read • Edit Online

This tutorial shows the capabilities of the rules engine in the remote monitoring solution. To introduce these
capabilities, the tutorial uses a scenario in the Contoso IoT application.
Contoso has a rule that generates a critical alert when the pressure reported by a device exceeds 250 PSI.
As an operator, you want to identify devices that may have problematic sensors by looking for initial
pressure spikes. To identify these devices, you create a rule to generate a warning when the pressure exceeds 150
PSI.
In this tutorial, you learn how to:
View the rules in your solution
Create a new rule
Edit an existing rule
Delete a rule

Prerequisites
To follow this tutorial, you need a deployed instance of the remote monitoring solution in your Azure subscription.
If you haven't deployed the remote monitoring solution yet, you should complete the Deploy the remote
monitoring preconfigured solution tutorial.

View the rules in your solution

The page in the solution displays a list of all the current rules:

To view only the rules that apply to devices, apply a filter:

You can view more information about a rule and edit it when you select it in the list:

To disable, enable, or delete one or more rules, select multiple rules in the list:
Create a new rule
To add a new rule that generates a warning when the pressure in a device exceeds 150 PSI, choose
:

Use the following values to create the rule:

Name Chiller warning

Source device group

Trigger field pressure

 Trigger operator Greater than

Trigger value 150

Severity level Warning

Description Chiller pressure has exceeded 150 PSI

To save the new rule, choose .

You can view when the rule is triggered on the page or on the page.

Edit an existing rule

To make a change to an existing rule, select it in the list of rules. Then, in the panel choose .

Disable a rule
To temporarily switch off a rule, you can disable it in the list of rules. Choose the rule to disable, and then choose
. The of the rule in the list changes to indicate the rule is now disabled. You can re-enable a rule
that you previously disabled using the same procedure.
You can enable and disable multiple rules at the same time if you select multiple rules in the list.

Delete a rule
To permanently delete a rule, choose the rule in the list of rules and then choose .
You can delete multiple rules at the same time if you select multiple rules in the list.

Next steps
This tutorial showed you how to:
View the rules in your solution
Create a new rule
Edit an existing rule
Delete a rule
Now that you have learned how to detect issues using threshold-based rules, the suggested next steps are to learn
how to:
Manage and configure your devices.
Troubleshoot and remediate device issues.
Test your solution with simulated devices.
 Manage and configure your devices
12/13/2017 • 3 min to read • Edit Online

This tutorial shows the device management capabilities of the remote monitoring solution. To introduce these
capabilities, the tutorial uses a scenario in the Contoso IoT application.
Contoso has ordered new machinery to expand one of their facilities to increase output. While you wait for the
new machinery to be delivered, you want to run a simulation to verify the behavior of your solution. As an
operator, you want to manage and configure the devices in the remote monitoring solution.
To provide an extensible way to manage and configure devices, the remote monitoring solution uses IoT Hub
features such as jobs and direct methods. To learn how a device developer implements methods on a physical
device, see Customize the remote monitoring preconfigured solution.
In this tutorial, you learn how to:
Provision a simulated device.
Test the simulated device.
Call device methods from the solution.
Reconfigure a device.

Prerequisites
To follow this tutorial, you need a deployed instance of the remote monitoring solution in your Azure subscription.
If you haven't deployed the remote monitoring solution yet, you should complete the Deploy the remote
monitoring preconfigured solution tutorial.

Add a simulated device

Navigate to the page in the solution and then choose . In the panel, choose
:
Leave the number of devices to provision set to . Choose as the , and then choose
to create the simulated device:

To learn how to provision a physical device, see Connect your device to the remote monitoring preconfigured
solution.

Test the simulated device

To view details of your new simulated device, select it in the list of devices on the page. Information about
your device displays in the panel:

In , verify your new device is sending telemetry. To view the different telemetry streams from your
device, choose a telemetry name such as :
The panel displays other information about the device such as tag values, the methods it supports,
and the properties reported by the device.
To view detailed diagnostics, scroll down to view .

Act on a device
To act on one or more devices, select them in the list of devices and then choose . The device
model specifies four methods a device must support:

Choose , set the job name to , and then choose :

To track the status of the job on the page, choose :

Methods in other devices

When you explore the different simulated device types, you see that other device types support different methods.
In a deployment with physical devices, the device model specifies the methods the device should support.
Typically, the device developer is responsible for developing the code that makes the device act in response to a
method call.
To schedule a method to run on multiple devices, you can select multiple devices in the list on the page.
The panel shows the types of method common to all the selected devices.

Reconfigure a device
To change the configuration of a device, select it in the device list on the page and then choose
. The reconfigure panel shows the property values for the selected device that you can change:
To make a change, add a name for the job, update the property values, and choose :

To track the status of the job on the page, choose .

Next steps
This tutorial showed you how to:
Provision a simulated device.
Test the simulated device.
Call device methods from the solution.
Reconfigure a device.
Now that you have learned how to manage your devices, the suggested next steps are to learn how to:
Troubleshoot and remediate device issues.
Test your solution with simulated devices.
Connect your device to the remote monitoring preconfigured solution.
 Troubleshoot and remediate device issues
12/13/2017 • 2 min to read • Edit Online

This tutorial shows you how to use the page in the solution to troubleshoot and remediate device
issues. To introduce these capabilities, the tutorial uses a scenario in the Contoso IoT application.
Contoso is testing a new device in the field. As a Contoso operator, you notice during testing that the
device is unexpectedly triggering a temperature alarm on the dashboard. You must now investigate
the behavior of this faulty device.
In this tutorial, you learn how to:
Use the page to investigate the alarm
Call a device method to remediate the issue

Prerequisites
To follow this tutorial, you need a deployed instance of the remote monitoring solution in your Azure subscription.
If you haven't deployed the remote monitoring solution yet, you should complete the Deploy the remote
monitoring preconfigured solution tutorial.

Use the maintenance dashboard

On the page you notice there are unexpected temperature alarms coming from the rule associated
with the devices:

To investigate the issue further, choose the option next to the alarm:
The detail view of the alarm shows:
When the alarm was triggered
Status information about the devices associated with the alarm
Telemetry from the devices associated with the alarm

To acknowledge the alarm, select the and choose . This action enables other
operators to see that you have seen the alarm and are working on it.
In the list, you can see the device responsible for firing the temperature alarm:

Remediate the issue

To remediate the issue with the device, you need to call the method on the
device.
To act on a device, select it in the list of devices and then choose . The device model specifies
four methods a device must support:
Choose and set the job name to . Then choose :

To track the status of the job on the page, choose . Use the view to track all the jobs and
method calls in the solution:
To view the details of a specific job or method call, choose it in the list in the view:

Next steps
In this tutorial, we showed you how to:
Use the page to investigate the alarm
Call a device method to remediate the issue
Now you have learned how to manage device issues, the suggested next step is to learn how to Test your solution
with simulated devices.
 Test your solution with simulated devices
1/24/2018 • 16 min to read • Edit Online

This tutorial shows you how to customize the device simulator microservice in the remote monitoring
preconfigured solution. To show the capabilities of the device simulator, this tutorial uses two scenarios in the
Contoso IoT application.
In the first scenario, Contoso wants to test a new smart lightbulb device. To perform the tests, you create a new
simulated device with the following characteristics:
Properties

Color White, Red, Blue

Brightness 0 to 100

Estimated remaining life Countdown from 10,000 hours

Telemetry
The following table shows the data the lightbulb reports to the cloud as a data stream:

Status "on", "off"

Temperature Degrees F

online true, false

NOTE
The telemetry value is mandatory for all simulated types.

Methods
The following table shows the actions the new device supports:

Switch on

Switch off

Initial state
The following table shows the initial status of the device:
 Initial color White

Initial brightness 75

Initial remaining life 10,000

Initial telemetry status "on"

Initial telemetry temperature 200

In the second scenario, you add a new telemetry type to Contoso's existing device.
This tutorial shows you how to use the device simulator with the remote monitoring preconfigured solution:
In this tutorial, you learn how to:
Create a new device type
Simulate custom device behavior
Add a new device type to the dashboard
Send custom telemetry from an existing device type

Prerequisites
To follow this tutorial, you need:
A deployed instance of the remote monitoring solution in your Azure subscription. If you haven't deployed
the remote monitoring solution yet, you should complete the Deploy the remote monitoring preconfigured
solution tutorial.
Visual Studio 2017. If you don't have Visual Studio 2017 installed, you can download the free Visual Studio
Community edition.
Cloud Explorer for Visual Studio 2017 Visual Studio extension.
An account on Docker Hub. You can sign up for free to get started.
Git installed on your desktop machine.

Prepare your development environment

Complete the following tasks to prepare your development environment for adding a new simulated device to
your remote monitoring solution:
Configure SSH access to the solution virtual machine in Azure
When you created your remote monitoring solution at www.azureiotsuite.com, you chose a solution name. The
solution name becomes the name of the Azure resource group that contains the various deployed resources that
the solution uses. The following commands use a resource group named , you should replace
with the name of your resource group.
The following commands use the command from Azure CLI 2.0. You can install the Azure CLI 2.0 on your
development machine, or use the Cloud Shell in the Azure portal. The Azure CLI 2.0 is pre-installed in the Cloud
Shell.
1. To verify the name of the resource group that contains your remote monitoring resources, run the
following command:
 This command lists all the resource groups in your subscription. The list should include a resource group
with the same name as your remote monitoring solution.
2. To make your resource group the default group for subsequent commands, run the following command
using your resource group name in place of :

3. To list the resources in your resource group, run the following command:

Make a note of the names of your virtual machine and your network security group. You use these values
in later steps.
4. To enable SSH access your virtual machine, run the following command using the name of your network
security group from the previous step:

To view the list of inbound rules for your network, run the following command:

5. To change the virtual machine password to a password you know, run the following command. Use the
name of the virtual machine you noted previously and a password of your choice:

6. To find the IP address of your virtual machine, use the following command and make a note of the public IP
address:

7. You can now use SSH to connect to your virtual machine. The command is pre-installed in the Cloud
Shell. Use the public IP address from the previous step and, when prompted, the password you configured
for the virtual machine:

You now have access to the shell in the virtual machine that runs the Docker containers in the remote
monitoring solution. To view the running containers, use the following command:
Find the service connection strings
In the tutorial, you work with Visual Studio solution that connects to the solution's Cosmos DB and IoT Hub
services. The following steps show you one way to find the connection string values you need:
1. To find the Cosmos DB connection string, run the following command in the SSH session connected to the
virtual machine:

Make a note of the connection string. You use this value later in the tutorial.
2. To find the IoT Hub connection string, run the following command in the SSH session connected to the
virtual machine:

Make a note of the connection string. You use this value later in the tutorial.

NOTE
You can also find these connection strings in the Azure portal or by using the command.

Stop the device simulation service in the virtual machine

When you modify the device simulation service, you can run it locally to test your changes. Before you run the
device simulation service locally, you must stop the instance running in the virtual machine as follows:
1. To find the of the service, run the following command in the SSH
session connected to the virtual machine:

Make a note of the container ID of the service.

2. To stop the container, run the following command:

Clone the GitHub repositories

In this tutorial, you work with the and Visual Studio projects. You can clone
the source code repositories from GitHub. Perform this step on your local development machine where you have
Visual Studio installed:
1. Open a command prompt and navigate to the folder where you want to save your copy of the
and GitHub repositories.
2. To clone the .NET version of the repository, run the following command:

The device simulation service in the remote monitoring solution enables you to make changes to the built-
in simulated device types and to create new simulated device types. You can use custom device types to
test the behavior of the remote monitoring solution before you connect your physical devices.
3. To clone the .NET version of the repository, run the following command:

The device simulation service uses the storage adapter service to connect to the Cosmos DB service in
Azure. The remote monitoring solution stores the simulated device configuration data in a Cosmos DB
database.
Run the storage adapter service locally
The device simulation service uses the storage adapter service to connect to the solution's Cosmos DB database. If
you run the device simulation service locally, you must also run the storage adapter service locally. The following
steps show you how to run the storage adapter service from Visual Studio:
1. In Visual Studio, open the solution file in your local clone of the
repository.
2. In Solution Explorer, right-click the project, choose , and then choose .
3. In the section, edit the value of the
variable to be the Cosmos DB connection
string you noted previously. Then save your changes.
4. In Solution Explorer, right-click the project, choose , and then choose
.
5. The service starts running locally and opens in your default browser.
Verify that the value is "OK: Alive and well."
6. Leave the storage adapter service running locally until you have completed the tutorial.
You now have everything in place, and you are ready to start adding a new simulated device type to your remote
monitoring solution.

Create a simulated device type

The easiest way to create a new device type in the device simulation service is to copy and modify an existing type.
The following steps show you how to copy the built-in device to create a new device:
1. In Visual Studio, open the solution file in your local clone of the
repository.
2. In Solution Explorer, right-click the project, choose , and then choose .
3. In the section, edit the value of the variable to be
the IoT Hub connection string you noted previously. Then save your changes.
4. In Solution Explorer, right-click the solution and choose . Choose
and select . Then click .
5. Each device type has a JSON model file and associated scripts in the folder.
In Solution Explorer, copy the files to create the files as shown in the following table:

chiller-01.json lightbulb-01.json

scripts/chiller-01-state.js scripts/lightbulb-01-state.js
 scripts/reboot-method.js scripts/SwitchOn-method.js

Define the characteristics of the new device type

The file defines the characteristics of the type, such as the telemetry it generates and the
methods it supports. The following steps update the file to define the device:
1. In the file, update the device metadata as shown in the following snippet:

2. In the file, update the simulation definition as shown in the following snippet:

3. In the file, update the device type properties as shown in the following snippet:

4. In the file, update the device type telemetry definitions as shown in the following
snippet:
5. In the file, update the device type methods as shown in the following snippet:

6. Save the file.

Simulate custom device behavior
The file defines the simulation behavior of the type. The following steps
update the file to define the behavior of the device:
1. Edit the state definition in the file as shown in the following snippet:

2. Add a function after the function with the following definition:

3. Edit the function to implement the behavior as shown in the following snippet:
4. Save the file.
The file implements the method in a device. The following
steps update the file:
1. Edit the state definition in the file as shown in the following snippet:

2. To switch on the lightbulb, edit the function as follows:

3. Save the file.

4. Make a copy the file called .
5. To switch off the lightbulb, edit the function in the file as follows:

6. Save the file.

7. In Solution Explorer, select each of your four new files in turn. In the window for each file, verify
that is set to .
Configure the device simulation service
To limit the number of simulated devices that connect to the solution during testing, configure the service to run a
single chiller and a single lightbulb device. The configuration data is stored in the Cosmos DB instance in the
solution's resource group. To edit the configuration data, use the view in Visual Studio:
1. To open the view in Visual Studio, choose and then .
2. To find the simulation configuration document, in enter .
3. Double-click the document to open it for editing.
4. In the value for , locate the array that looks like the following snippet:

5. To define a single chiller and a single lightbulb simulated device, replace the array with the
following code:

Save the change to the document.

NOTE
You can also use the Cosmos DB Data Explorer in the Azure portal to edit the document.

Test the Lightbulb device type locally

You are now ready to test your new simulated lightbulb type by running the device simulation project locally.
1. In Solution Explorer, right-click , choose and then choose .
2. To check that the two simulated devices are connected to your IoT Hub, open the Azure portal in your
browser.
3. Navigate to the IoT hub in the resource group that contains your remote monitoring solution.
4. In the section, choose . Then verify that the number of is two:

5. In your browser, navigate to the for your remote monitoring solution. In the telemetry panel
 on the , select . The temperature for your two simulated devices displays on the
chart:

You now have the lightbulb device simulation running locally. The next step is to deploy your updated simulator
code to the virtual machine that runs the remote monitoring microservices in Azure.
Before you continue, you can stop debugging both the device simulation and storage adapter projects in Visual
Studio.
Deploy the updated simulator to the cloud
The microservices in the remote monitoring solution run in docker containers. The containers are hosted in the
solution's virtual machine in Azure. In this section, you:
Create a new device simulation docker image.
Upload the image to your docker hub repository.
Import the image into your solution's virtual machine.
The following steps assume that you have a repository called in your Docker Hub account.
1. In Visual Studio, in the project, open the file .
2. Edit the line that sets the environment variable to your Docker Hub repository name:

Save the change.

3. In Visual Studio, in the project, open the file .
4. Edit the line that sets the environment variable to your Docker Hub repository name:

Save the change.

5. Open a command prompt as an administrator. Then navigate to the folder in your clone of
 the GitHub repository.
6. To build the docker image, run the following command:

7. To sign in to your Docker Hub account, run the following command:

8. To upload your new image to your Docker Hub account, run the following command:

9. To verify the upload, navigate to https://hub.docker.com/. Locate your repository and choose
. Then choose :

The scripts added the tag to the image.

10. Use SSH to connect to your solution's virtual machine in Azure. Then navigate to the folder and edit
the file:

11. Edit the entry for the device simulation service to use your docker image:

Save your changes.

12. To restart all the services with the new settings, run the following command:
13. To check the log file from your new device simulation container, run the following command to find the
container ID:

Then run the following command using the container ID:

You have now completed the steps to deploy an updated version of the device simulation service to your remote
monitoring solution.
In your browser, navigate to the for your remote monitoring solution. In the telemetry panel on the
, select . The temperature for your two simulated devices displays on the chart:

On the page, you can provision instances of your new type:

You can view the telemetry from the simulated device:

You can call the and methods on your device:

Add a new telemetry type
This section describes how to modify an existing simulated device type to support a new telemetry type.
Locate the Chiller device type files
The following steps show you how to find the files that define the built-in device:
1. If you have not already done so, use the following command to clone the GitHub
repository to your local machine:

2. Each device type has a JSON model file and associated scripts in the folder. The files
that define the simulated device type are:

Specify the new telemetry type

The following steps show you how to add a new type to the device type:
1. Open the file.
2. Update the value as follows:

3. In the section, add the follwing two definitions:

4. In the array, add the following definition:

5. Save the file.
6. Open the file.
7. Add the following fields to the variable:

8. Add the following line to the function:

9. Save the file.

Test the Chiller device type
To test the updated device type, first run a local copy of the service to test your device
type behaves as expected. When you have tested and debugged your updated device type locally, you can rebuild
the container and redeploy the service to Azure.
When you run the service locally, it sends telemetry to your remote monitoring solution. On
the page, you can provision instances of your updated type.
To test and debug your changes locally, see the previous section Test the Lightbulb device type locally.
To deploy your updated device simulation service to the solution's virtual machine in Azure, see the previous
section Deploy the updated simulator to the cloud.
On the page, you can provision instances of your updated type:
You can view the new telemetry from the simulated device.

Next steps
This tutorial, showed you how to:
Create a new device type
Simulate custom device behavior
Add a new device type to the dashboard
Send custom telemetry from an existing device type
Now you have learned how to customize the device simulation service. The suggested next step is to learn how to
connect a physical device to your remote monitoring solution.
For more developer information about the remote monitoring solution, see:
Developer Reference Guide
Developer Troubleshooting Guide
 Customize the remote monitoring preconfigured
solution
1/17/2018 • 6 min to read • Edit Online

This article provides information about how you can access the source code and customize the remote monitoring
preconfigured solution. The article describes:
The GitHub repositories that contain the source code and resources for the microservices that make up the
preconfigured solution.
Common customization scenarios such as adding a new device type.
The following video presents an overview of the options for customizing the remote monitoring preconfigured
solution:

Project overview
Implementations
The remote monitoring solution has both .NET and Java implementations. Both implementations provide similar
functionality and rely on the same underlying Azure services. You can find the top-level GitHub repositories here:
.NET solution
Java solution
Microservices
If you are interested in a specific feature of the solution, you can access the GitHub repositories for each individual
microservice. Each microservice implements a different part of the solution functionality. To learn more about the
overall architecture, see Remote monitoring preconfigured solution architecture.
This table summarizes the current availability of each microservice for each language:

Web UI Web app for remote N/A(React.js) N/A(React.js)

monitoring solution.
Implements UI using
React.js framework.

IoT Hub Manager Handles communication Available Available

with the IoT Hub.

Authentication Manages Azure Active Not yet available Available

Directory integration.
 Device simulation Manages a pool of Not yet available Available
simulated devices.

Telemetry Makes device telemetry Available Available

available to the UI.

Telemetry Agent Analyzes the telemetry Available Available

stream, stores messages
from Azure IoT Hub, and
generates alerts according
to defined rules.

UI Config Manages configuration data Available Available

from the UI.

Storage adapter Manages interactions with Available Available

storage service.

Reverse proxy Exposes private resources in Not yet available Available

a managed way through a
unique endpoint.

The Java solution currently uses the .NET authentication, simulation, and reverse proxy microservices. These
microservices will be replaced by Java versions as soon as they become available.

Presentation and visualization

The following sections describe options to customize the presentation and visualizations layer in the remote
monitoring solution:
Change the logo in the UI
The default deployment uses the Contoso company name and logo in the UI. To change these UI elements to
display your company name and logo:
1. Use the following command to clone the Web UI repository:

2. To change the company name, open the file in a text editor.

3. Locate the following line in the file:

4. Replace with the name of your company. For example:

5. Save the file.

6. To update the logo, add a new SVG file to the folder. The existing logo is the
file.
 7. Open the file in a text editor.
8. Locate the following line in the file:

9. Replace with the name of your logo file. For example:

10. Locate the following line in the file:

11. Replace with your text. For example:

12. Save the file.

13. To test the changes, you can run the updated on your local machine. To learn how to build and run
the solution locally, see Build, run and test locally in the GitHub repository readme file.
14. To deploy your changes, see the Developer Reference Guide.
Customize the map
See the Customize map page in GitHub for details of the map components in the solution.
Other customization options
To further modify the presentation and visualizations layer in the remote monitoring solution, you can edit the
code. The relevant GitHub repositories are:
UIConfig (.NET)
UIConfig (Java)
Azure PCS Remote Monitoring WebUI

Device connectivity and streaming

The following sections describe options to customize the device connectivity and streaming layer in the remote
monitoring solution. Device models describe the device types and telemetry in the solution. You use device
models for both simulated and physical devices.
For an example of a physical device implementation, see Connect your device to the remote monitoring
preconfigured solution.
If you are using a physical device, you must provide the client application with a device model that contains the
device metadata and telemetry specification.
The following sections discuss using device models with simulated devices:
Add a telemetry type
The device types in the Contoso demo solution specify the telemetry that each device type sends. To specify the
additional telemetry types, a device can send telemetry definitions as metadata to the solution. If you use this
format, the dashboard consumes your device telemetry and available methods dynamically and you don't need to
modify the UI. Alternatively, you can modify the device type definition in the solution.
To learn how to add custom telemetry in the device simulator microservice, see Test your solution with simulated
devices.
Add a device type
The Contoso demo solution defines some sample device types. The solution enables you to define custom device
types to meet your specific application requirements. For example, your company may use an industrial gateway
as the primary device connected to the solution.
To create an accurate representation of your device, you need to modify the application that runs on your device
to match the device requirements.
To learn how to add a new device type in the device simulator microservice, see Test your solution with simulated
devices.
Define custom methods for simulated devices
To learn how to define custom methods for simulated devices in the remote monitoring solution, see Device
Models in the GitHub repository.
Using a physical device
To implement methods and jobs on your physical devices, see the following IoT Hub articles:
Understand and invoke direct methods from IoT Hub.
Schedule jobs on multiple devices.
Other customization options
To further modify the device connectivity and streaming layer in the remote monitoring solution, you can edit the
code. The relevant GitHub repositories are:
Device Telemetry (.NET)
Device Telemetry (Java)
Telemetry Agent (.NET)
Telemetry Agent (Java)

Data processing and analytics

To modify the data processing and analytics layer in the remote monitoring solution, you can edit the code. The
relevant GitHub repositories are:
Telemetry Agent (.NET)
Telemetry Agent (Java)

Infrastructure
To modify the infrastructure in the remote monitoring solution, you can edit the code. The relevant GitHub
repositories are:
IoTHub Manager (.NET)
IoTHub Manager (Java)
Storage Adapter (.NET)
Storage Adapter (Java)

Next steps
In this article, you learned about the resources available to help you customize the preconfigured solution.
For more conceptual information about the remote monitoring preconfigured solution, see Remote monitoring
architecture
For more information about customizing the remote monitoring solution, see:
Developer Reference Guide
Developer Troubleshooting Guide
 Deploy the remote monitoring preconfigured solution
using the CLI
12/13/2017 • 2 min to read • Edit Online

This tutorial shows you how to provision the remote monitoring preconfigured solution. You deploy the solution
using the CLI. You can also deploy the solution using the web-based UI at azureiotsuite.com, to learn about this
option see Deploy the remote monitoring preconfigured solution.

Prerequisites
To deploy the remote monitoring preconfigured solution, you need an active Azure subscription.
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure
Free Trial.
To run the CLI, you need Node.js installed on your local machine.

Install the CLI

To install the CLI, run the following command in your command-line environment:

Sign in to the CLI

Before you can deploy the preconfigured solution, you must sign in to your Azure subscription using the CLI as
follows:

Follow the on-screen instructions to complete the sign-in process.

Deployment options
When you deploy the preconfigured solution, there are several options that configure the deployment process:

SKU , A basic deployment is intended for test

and demonstrations, it deploys all the
microservices to a single virtual
machine. A standard deployment is
intended for production, it deploys the
microservices to multiple virtual
machines.

Runtime , Selects the language implementation of

the microservices.
Deploy the preconfigured solution
Example: deploy .NET version
The following example shows how to deploy the basic, .NET version of the remote monitoring preconfigured
solution:

Example: deploy Java version

The following example shows how to deploy the standard, Java version of the remote monitoring preconfigured
solution:

pcs command options

When you run the command to deploy a solution, you are asked for:
A name for your solution. This name must be unique.
The Azure subscription to use.
A location.
Credentials for the virtual machines that host the microservices. You can use these credentials to access the
virtual machines for troubleshooting.
When the command finishes, it displays the URL of your new preconfigured solution deployment. The
command also creates a file with additional information such as the name of the IoT
Hub that was provisioned for you.
For more information about the command-line parameters, run:

For more information about the CLI, see How to use the CLI.

Next steps
In this tutorial, you learned how to:
Configure the preconfigured solution
Deploy the preconfigured solution
Sign in to the preconfigured solution
Now that you have deployed the remote monitoring solution, the next step is to explore the capabilities of the
solution dashboard.
 Connect your device to the remote monitoring
preconfigured solution (Windows)
12/13/2017 • 11 min to read • Edit Online

In this tutorial, you implement a device that sends the following telemetry to the remote monitoring
preconfigured solution:
Temperature
Pressure
Humidity
For simplicity, the code generates sample telemetry values for the . You could extend the sample by
connecting real sensors to your device and sending real telemetry.
The sample device also:
Sends metadata to the solution to describe its capabilities.
Responds to actions triggered from the page in the solution.
Responds to configuration changes send from the page in the solution.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free trial
account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution and
provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured
solution. If you haven't already provisioned the remote monitoring preconfigured solution in your Azure account,
see Deploy the remote monitoring preconfigured solution
When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need the device credentials when you
create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution page. You include the device credentials in your client
application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps on the page in the
solution:
1. Choose , and then choose as the :

2. Enter as the Device ID. Choose the and options:

To locate the credentials your device must use to connect to the preconfigured solution, navigate to the Azure
portal in your browser. Sign in to your subscription.
1. Locate the resource group that contains the Azure services your remote monitoring solution uses. The
resource group has the same name as the remote monitoring solution you provisioned.
2. Navigate to the IoT hub in this resource group. Then choose :

3. Choose the you created on the page in the remote monitoring solution.
4. Make a note of the and values. You use these values when you add code to connect
your device to the solution.
You have now provisioned a physical device in the remote monitoring preconfigured solution. In the following
sections, you implement the client application that uses the device credentials to connect to your solution.
The client application implements the built-in device model. A preconfigured solution device model
specifies the following about a device:
 The properties the device reports to the solution. For example, a device reports information about its
firmware and location.
The types of telemetry the device sends to the solution. For example, a device sends temperature,
humidity, and pressure values.
The methods you can schedule from the solution to run on the device. For example, a device must
implement , , , and methods.
This tutorial shows you how to connect a physical device to the remote monitoring preconfigured solution.

Create a C client solution on Windows

As with most embedded applications that run on constrained devices, the client code for the device application is
written in C. In this tutorial, you build the application on a machine running Windows.
Create the starter project
Create a starter project in Visual Studio 2017 and add the IoT Hub device client NuGet packages:
1. In Visual Studio, create a C console application using the Visual C++
template. Name the project .

2. In , delete the files , , and .

3. In , rename the file to .
4. In , right-click the project and then click . Choose
, then search for and install the following NuGet packages:
Microsoft.Azure.IoTHub.Serializer
Microsoft.Azure.IoTHub.IoTHubClient
Microsoft.Azure.IoTHub.MqttTransport

5. In , right-click on the project and then choose to open the

project's dialog box. For details, see Setting Visual C++ Project Properties.
6. Choose the folder, then choose the property page.
7. Set to . Then choose .
8. Choose the folder, then choose the property page.
9. Add to the property. To save the project property values, choose
and then again.

Add the Parson JSON library

Add the Parson JSON library to the project and add the required statements:
1. In a suitable folder on your computer, clone the Parson GitHub repository using the following command:
2. Copy the and files from the local copy of the Parson repository to your
project folder.
3. In Visual Studio, right-click the project, choose , and then choose .
4. In the dialog, select the and files in the project folder.
To add these two files to your project, choose .

5. In Visual Studio, open the file. Replace the existing statements with the following
code:

NOTE
Now you can verify that your project has the correct dependencies set up by building the solution.

Specify the behavior of the IoT device

The IoT Hub serializer client library uses a model to specify the format of the messages the device exchanges with
IoT Hub.
1. Add the following variable declarations after the statements. Replace the placeholder values
and with the values you noted for your device in the remote monitoring
solution dashboard. Use the IoT Hub Hostname from the solution dashboard to replace . For
example, if your IoT Hub Hostname is , replace [IoTHub Name] with :

2. Add the following code to define the model that enables the device to communicate with IoT Hub. This
model specifies that the device:
Can send temperature, pressure, and humidity as telemetry.
Can send reported properties, to the device twin in IoT Hub. These reported properties include
information about the telemetry schema and supported methods.
Can receive and act on desired properties set in the device twin in IoT Hub.
Can respond to the , , , and
direct methods invoked from the UI. The device sends information about the direct methods it
supports using reported properties.
Implement the behavior of the device
Now add code that implements the behavior defined in the model.
1. Add the following functions that handle the desired properties set in the solution dashboard. These desired
properties are defined in the model:
2. Add the following functions that handle the direct methods invoked through the IoT hub. These direct
methods are defined in the model:

3. Add the following function that adds a property to a device-to-cloud message:

4. Add the following function that sends a message with properties to the preconfigured solution:
5. Add the following callback handler that runs when the device has sent new reported property values to the
preconfigured solution:

6. Add the following function to connect your device to the preconfigured solution in the cloud, and exchange
data. This function performs the following steps:
Initializes the platform.
Registers the Contoso namespace with the serialization library.
Initializes the client with the device connection string.
Create an instance of the model.
Creates and sends reported property values.
Creates a loop to send telemetry every five seconds.
Deinitializes all resources.
For reference, here is a sample message sent to the preconfigured solution:
Build and run the sample
Add code to invoke the function, then build and run the device application:
1. To invoke the function, replace the function with following code:

2. Choose and then to build the device application. Ignore the warning about the
function.
3. In , right-click the project, choose , and then choose
to run the sample. The console displays messages as:
The application sends sample telemetry to the preconfigured solution.
Receives desired property values set in the solution dashboard.
Responds to methods invoked from the solution dashboard.

View device telemetry

You can view the telemetry sent from your device on the page in the solution.
1. Select the device you provisioned in the list of devices on the page. A panel displays information
about your device including a plot of the device telemetry:

2. Choose to change the telemetry display:

3. To view diagnostic information about your device, scroll down to :

Act on your device

To invoke methods on your devices, use the page in the remote monitoring solution. For example, in the
remote monitoring solution devices implement a method.
1. Choose to navigate to the page in the solution.
2. Select the device you provisioned in the list of devices on the page:
3. To display a list of the methods you can call on your device, choose . To schedule a method to run
on multiple devices, you can select multiple devices in the list. The panel shows the types of
method common to all the devices you selected.
4. Choose , set the job name to , and choose :

5. A message displays in the console running your device code when the device handles the method.

NOTE
To track the status of the job in the solution, choose .

Next steps
The article Customize the remote monitoring preconfigured solution describes some ways to customize the
preconfigured solution.
 Connect your device to the remote monitoring
preconfigured solution (Linux)
12/13/2017 • 11 min to read • Edit Online

In this tutorial, you implement a device that sends the following telemetry to the remote monitoring
preconfigured solution:
Temperature
Pressure
Humidity
For simplicity, the code generates sample telemetry values for the . You could extend the sample by
connecting real sensors to your device and sending real telemetry.
The sample device also:
Sends metadata to the solution to describe its capabilities.
Responds to actions triggered from the page in the solution.
Responds to configuration changes send from the page in the solution.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free trial
account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution and
provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured
solution. If you haven't already provisioned the remote monitoring preconfigured solution in your Azure account,
see Deploy the remote monitoring preconfigured solution
When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need the device credentials when you
create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution page. You include the device credentials in your
client application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps on the page in the
solution:
1. Choose , and then choose as the :

2. Enter as the Device ID. Choose the and options:

To locate the credentials your device must use to connect to the preconfigured solution, navigate to the Azure
portal in your browser. Sign in to your subscription.
1. Locate the resource group that contains the Azure services your remote monitoring solution uses. The
resource group has the same name as the remote monitoring solution you provisioned.
2. Navigate to the IoT hub in this resource group. Then choose :

3. Choose the you created on the page in the remote monitoring solution.
4. Make a note of the and values. You use these values when you add code to connect
your device to the solution.
You have now provisioned a physical device in the remote monitoring preconfigured solution. In the following
sections, you implement the client application that uses the device credentials to connect to your solution.
The client application implements the built-in device model. A preconfigured solution device model
specifies the following about a device:
 The properties the device reports to the solution. For example, a device reports information about its
firmware and location.
The types of telemetry the device sends to the solution. For example, a device sends temperature,
humidity, and pressure values.
The methods you can schedule from the solution to run on the device. For example, a device must
implement , , , and methods.
This tutorial shows you how to connect a physical device to the remote monitoring preconfigured solution.

Create a C client project on Linux

As with most embedded applications that run on constrained devices, the client code for the device application is
written in C. In this tutorial, you build the application on a machine running Ubuntu (Linux).
To complete these steps, you need a device running Ubuntu version 15.04 or later. Before proceeding, install the
prerequisite packages on your Ubuntu device using the following command:

Install the client libraries on your device

The Azure IoT Hub client libraries are available as a package you can install on your Ubuntu device using the
command. Complete the following steps to install the package that contains the IoT Hub client library and
header files on your Ubuntu computer:
1. In a shell, add the AzureIoT repository to your computer:

2. Install the azure-iot-sdk-c-dev package

Install the Parson JSON parser

The IoT Hub client libraries use the Parson JSON parser to parse message payloads. In a suitable folder on your
computer, clone the Parson GitHub repository using the following command:

Prepare your project

On your Ubuntu machine, create a folder called . In the folder:
Create the four files , , , and .
Create folder called .
Copy the files and from your local copy of the Parson repository into the
folder.
In a text editor, open the file. Add the following statements:
Specify the behavior of the IoT device
The IoT Hub serializer client library uses a model to specify the format of the messages the device exchanges with
IoT Hub.
1. Add the following variable declarations after the statements. Replace the placeholder values
and with the values you noted for your device in the remote monitoring
solution dashboard. Use the IoT Hub Hostname from the solution dashboard to replace . For
example, if your IoT Hub Hostname is , replace [IoTHub Name] with :

2. Add the following code to define the model that enables the device to communicate with IoT Hub. This
model specifies that the device:
Can send temperature, pressure, and humidity as telemetry.
Can send reported properties, to the device twin in IoT Hub. These reported properties include
information about the telemetry schema and supported methods.
Can receive and act on desired properties set in the device twin in IoT Hub.
Can respond to the , , , and
direct methods invoked from the UI. The device sends information about the direct methods it
supports using reported properties.
Implement the behavior of the device
Now add code that implements the behavior defined in the model.
1. Add the following functions that handle the desired properties set in the solution dashboard. These desired
properties are defined in the model:
2. Add the following functions that handle the direct methods invoked through the IoT hub. These direct
methods are defined in the model:

3. Add the following function that adds a property to a device-to-cloud message:

4. Add the following function that sends a message with properties to the preconfigured solution:
5. Add the following callback handler that runs when the device has sent new reported property values to the
preconfigured solution:

6. Add the following function to connect your device to the preconfigured solution in the cloud, and exchange
data. This function performs the following steps:
Initializes the platform.
Registers the Contoso namespace with the serialization library.
Initializes the client with the device connection string.
Create an instance of the model.
Creates and sends reported property values.
Creates a loop to send telemetry every five seconds.
Deinitializes all resources.
For reference, here is a sample message sent to the preconfigured solution:
Add code to run the app
In a text editor, open the file. Add the following code:

In a text editor, open the file. Add the following code:

Build and run the application

The following steps describe how to use CMake to build your client application.
1. In a text editor, open the file in the folder.
2. Add the following instructions to define how to build your client application:
3. In the folder, create a folder to store the make files that CMake generates. Then run the
and commands as follows:

4. Run the client application and send telemetry to IoT Hub:

View device telemetry

You can view the telemetry sent from your device on the page in the solution.
1. Select the device you provisioned in the list of devices on the page. A panel displays information
about your device including a plot of the device telemetry:

2. Choose to change the telemetry display:

3. To view diagnostic information about your device, scroll down to :

Act on your device
To invoke methods on your devices, use the page in the remote monitoring solution. For example, in the
remote monitoring solution devices implement a method.
1. Choose to navigate to the page in the solution.
2. Select the device you provisioned in the list of devices on the page:

3. To display a list of the methods you can call on your device, choose . To schedule a method to run
on multiple devices, you can select multiple devices in the list. The panel shows the types of
method common to all the devices you selected.
4. Choose , set the job name to , and choose :

5. A message displays in the console running your device code when the device handles the method.

NOTE
To track the status of the job in the solution, choose .

Next steps
The article Customize the remote monitoring preconfigured solution describes some ways to customize the
preconfigured solution.
 Connect your device to the remote monitoring
preconfigured solution (Node.js)
12/13/2017 • 8 min to read • Edit Online

In this tutorial, you implement a device that sends the following telemetry to the remote monitoring
preconfigured solution:
Temperature
Pressure
Humidity
For simplicity, the code generates sample telemetry values for the . You could extend the sample by
connecting real sensors to your device and sending real telemetry.
The sample device also:
Sends metadata to the solution to describe its capabilities.
Responds to actions triggered from the page in the solution.
Responds to configuration changes send from the page in the solution.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free
trial account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution
and provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured
solution. If you haven't already provisioned the remote monitoring preconfigured solution in your Azure account,
see Deploy the remote monitoring preconfigured solution
When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need the device credentials when you
create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution page. You include the device credentials in your
client application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps on the page in the
solution:
1. Choose , and then choose as the :

2. Enter as the Device ID. Choose the and options:

To locate the credentials your device must use to connect to the preconfigured solution, navigate to the Azure
portal in your browser. Sign in to your subscription.
1. Locate the resource group that contains the Azure services your remote monitoring solution uses. The
resource group has the same name as the remote monitoring solution you provisioned.
2. Navigate to the IoT hub in this resource group. Then choose :

3. Choose the you created on the page in the remote monitoring solution.
4. Make a note of the and values. You use these values when you add code to
connect your device to the solution.
You have now provisioned a physical device in the remote monitoring preconfigured solution. In the following
sections, you implement the client application that uses the device credentials to connect to your solution.
The client application implements the built-in device model. A preconfigured solution device model
specifies the following about a device:
 The properties the device reports to the solution. For example, a device reports information about its
firmware and location.
The types of telemetry the device sends to the solution. For example, a device sends temperature,
humidity, and pressure values.
The methods you can schedule from the solution to run on the device. For example, a device must
implement , , , and methods.
This tutorial shows you how to connect a physical device to the remote monitoring preconfigured solution. In this
tutorial, you use Node.js, which is a good option for environments with minimal resource constraints.

Create a Node.js solution

Ensure that Node.js version 4.0.0 or later is installed on your development machine. You can run
at the command line to check the version.
1. Create a folder called on your development machine. Navigate to this folder in your
command-line environment.
2. To download and install the packages you need to complete the sample app, run the following commands:

3. In the folder, create a file called . Open this file in a text editor.
4. In the file, add the following statements:

5. Add the following variable declarations after the statements. Replace the placeholder values
and with values you noted for the device you provisioned in the remote
monitoring solution. Use the IoT Hub Hostname from the solution to replace . For example,
if your IoT Hub Hostname is , replace with :

6. To define some base telemetry data, add the following variables:

7. To define some property values, add the following variables:

8. Add the following variable to define the reported properties to send to the solution. These properties
include metadata to describe the methods and telemetry the device uses:
 9. To print operation results, add the following helper function:

10. Add the following helper function to use to randomize the telemetry values:

11. Add the following function to handle direct method calls from the solution. The solution uses direct
methods to act on devices:

12. Add the following code to send telemetry data to the solution. The client app adds properties to the
message to identify the message schema:

13. Add the following code to create a client instance:

14. Add the following code to:

Open the connection.
Set up a handler for desired properties.
Send reported properties.
Register handlers for the direct methods.
Start sending telemetry.
15. Save the changes to the file.
16. To launch the sample application, run the following command at a command prompt:

View device telemetry

You can view the telemetry sent from your device on the page in the solution.
1. Select the device you provisioned in the list of devices on the page. A panel displays information
about your device including a plot of the device telemetry:

2. Choose to change the telemetry display:

3. To view diagnostic information about your device, scroll down to :

Act on your device
To invoke methods on your devices, use the page in the remote monitoring solution. For example, in the
remote monitoring solution devices implement a method.
1. Choose to navigate to the page in the solution.
2. Select the device you provisioned in the list of devices on the page:

3. To display a list of the methods you can call on your device, choose . To schedule a method to
run on multiple devices, you can select multiple devices in the list. The panel shows the types of
method common to all the devices you selected.
4. Choose , set the job name to , and choose :
5. A message displays in the console running your device code when the device handles the method.

NOTE
To track the status of the job in the solution, choose .

Next steps
The article Customize the remote monitoring preconfigured solution describes some ways to customize the
preconfigured solution.
 Connect your Raspberry Pi device to the remote
monitoring preconfigured solution (Node.js)
12/13/2017 • 9 min to read • Edit Online

In this tutorial, you implement a device that sends the following telemetry to the remote monitoring
preconfigured solution:
Temperature
Pressure
Humidity
For simplicity, the code generates sample telemetry values for the . You could extend the sample by
connecting real sensors to your device and sending real telemetry.
The sample device also:
Sends metadata to the solution to describe its capabilities.
Responds to actions triggered from the page in the solution.
Responds to configuration changes send from the page in the solution.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free trial
account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution
and provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured
solution. If you haven't already provisioned the remote monitoring preconfigured solution in your Azure account,
see Deploy the remote monitoring preconfigured solution
When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need the device credentials when you
create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution page. You include the device credentials in your
client application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps on the page in the
solution:
1. Choose , and then choose as the :

2. Enter as the Device ID. Choose the and options:

To locate the credentials your device must use to connect to the preconfigured solution, navigate to the Azure
portal in your browser. Sign in to your subscription.
1. Locate the resource group that contains the Azure services your remote monitoring solution uses. The
resource group has the same name as the remote monitoring solution you provisioned.
2. Navigate to the IoT hub in this resource group. Then choose :

3. Choose the you created on the page in the remote monitoring solution.
4. Make a note of the and values. You use these values when you add code to
connect your device to the solution.
You have now provisioned a physical device in the remote monitoring preconfigured solution. In the following
sections, you implement the client application that uses the device credentials to connect to your solution.
The client application implements the built-in device model. A preconfigured solution device model
specifies the following about a device:
 The properties the device reports to the solution. For example, a device reports information about its
firmware and location.
The types of telemetry the device sends to the solution. For example, a device sends temperature,
humidity, and pressure values.
The methods you can schedule from the solution to run on the device. For example, a device must
implement , , , and methods.
This tutorial shows you how to connect a physical device to the remote monitoring preconfigured solution. In this
tutorial, you use Node.js, which is a good option for environments with minimal resource constraints.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
Required desktop software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required Raspberry Pi software
If you haven't done so already, install Node.js version 4.0.0 or later on your Raspberry Pi. The following steps show
you how to install Node.js v6.11.4 on your Raspberry Pi:
1. Connect to your Raspberry Pi using . For more information, see SSH (Secure Shell) on the Raspberry Pi
website.
2. Use the following command to update your Raspberry Pi:

3. Use the following command to download the Node.js binaries to your Raspberry Pi:

4. Use the following command to install the binaries:

5. Use the following command to verify you have installed Node.js v6.11.4 successfully:
Create a Node.js solution
Complete the following steps using the connection to your Raspberry Pi:
1. Create a folder called in your home folder on the Raspberry Pi. Navigate to this folder in
your command line:

2. To download and install the packages you need to complete the sample app, run the following commands:

3. In the folder, create a file called . Open this file in a text editor. On
the Raspberry Pi, you can use the or text editors.
4. In the file, add the following statements:

5. Add the following variable declarations after the statements. Replace the placeholder values
and with values you noted for the device you provisioned in the remote
monitoring solution. Use the IoT Hub Hostname from the solution to replace . For example, if
your IoT Hub Hostname is , replace with :

6. To define some base telemetry data, add the following variables:

7. To define some property values, add the following variables:

8. Add the following variable to define the reported properties to send to the solution. These properties
include metadata to describe the methods and telemetry the device uses:
 9. To print operation results, add the following helper function:

10. Add the following helper function to use to randomize the telemetry values:

11. Add the following function to handle direct method calls from the solution. The solution uses direct
methods to act on devices:

12. Add the following code to send telemetry data to the solution. The client app adds properties to the
message to identify the message schema:

13. Add the following code to create a client instance:

14. Add the following code to:

Open the connection.
Set up a handler for desired properties.
Send reported properties.
Register handlers for the direct methods.
Start sending telemetry.
15. Save the changes to the file.
16. To launch the sample application, run the following command at your command prompt on the Raspberry
Pi:

View device telemetry

You can view the telemetry sent from your device on the page in the solution.
1. Select the device you provisioned in the list of devices on the page. A panel displays information
about your device including a plot of the device telemetry:

2. Choose to change the telemetry display:

3. To view diagnostic information about your device, scroll down to :

Act on your device
To invoke methods on your devices, use the page in the remote monitoring solution. For example, in the
remote monitoring solution devices implement a method.
1. Choose to navigate to the page in the solution.
2. Select the device you provisioned in the list of devices on the page:

3. To display a list of the methods you can call on your device, choose . To schedule a method to run
on multiple devices, you can select multiple devices in the list. The panel shows the types of
method common to all the devices you selected.
4. Choose , set the job name to , and choose :
5. A message displays in the console running your device code when the device handles the method.

NOTE
To track the status of the job in the solution, choose .

Next steps
The article Customize the remote monitoring preconfigured solution describes some ways to customize the
preconfigured solution.
 Connect your Raspberry Pi device to the remote
monitoring preconfigured solution (C)
1/3/2018 • 12 min to read • Edit Online

In this tutorial, you implement a device that sends the following telemetry to the remote monitoring
preconfigured solution:
Temperature
Pressure
Humidity
For simplicity, the code generates sample telemetry values for the . You could extend the sample by
connecting real sensors to your device and sending real telemetry.
The sample device also:
Sends metadata to the solution to describe its capabilities.
Responds to actions triggered from the page in the solution.
Responds to configuration changes send from the page in the solution.
To complete this tutorial, you need an active Azure account. If you don't have an account, you can create a free trial
account in just a couple of minutes. For details, see Azure Free Trial.

Before you start

Before you write any code for your device, you must provision your remote monitoring preconfigured solution
and provision a new custom device in that solution.
Provision your remote monitoring preconfigured solution
The device you create in this tutorial sends data to an instance of the remote monitoring preconfigured
solution. If you haven't already provisioned the remote monitoring preconfigured solution in your Azure account,
see Deploy the remote monitoring preconfigured solution
When the provisioning process for the remote monitoring solution finishes, click to open the solution
dashboard in your browser.
Provision your device in the remote monitoring solution

NOTE
If you have already provisioned a device in your solution, you can skip this step. You need the device credentials when you
create the client application.

For a device to connect to the preconfigured solution, it must identify itself to IoT Hub using valid credentials. You
can retrieve the device credentials from the solution page. You include the device credentials in your
client application later in this tutorial.
To add a device to your remote monitoring solution, complete the following steps on the page in the
solution:
1. Choose , and then choose as the :

2. Enter as the Device ID. Choose the and options:

To locate the credentials your device must use to connect to the preconfigured solution, navigate to the Azure
portal in your browser. Sign in to your subscription.
1. Locate the resource group that contains the Azure services your remote monitoring solution uses. The
resource group has the same name as the remote monitoring solution you provisioned.
2. Navigate to the IoT hub in this resource group. Then choose :

3. Choose the you created on the page in the remote monitoring solution.
4. Make a note of the and values. You use these values when you add code to
connect your device to the solution.
You have now provisioned a physical device in the remote monitoring preconfigured solution. In the following
sections, you implement the client application that uses the device credentials to connect to your solution.
The client application implements the built-in device model. A preconfigured solution device model
specifies the following about a device:
 The properties the device reports to the solution. For example, a device reports information about its
firmware and location.
The types of telemetry the device sends to the solution. For example, a device sends temperature,
humidity, and pressure values.
The methods you can schedule from the solution to run on the device. For example, a device must
implement , , , and methods.
This tutorial shows you how to connect a physical device to the remote monitoring preconfigured solution. As with
most embedded applications that run on constrained devices, the client code for the Raspberry Pi device
application is written in C. In this tutorial, you build the application on a Raspberry Pi running the Raspbian OS.
Required hardware
A desktop computer to enable you to connect remotely to the command line on the Raspberry Pi.
Microsoft IoT Starter Kit for Raspberry Pi 3 or equivalent components. This tutorial uses the following items from
the kit:
Raspberry Pi 3
MicroSD Card (with NOOBS)
A USB Mini cable
An Ethernet cable
Required desktop software
You need SSH client on your desktop machine to enable you to remotely access the command line on the
Raspberry Pi.
Windows does not include an SSH client. We recommend using PuTTY.
Most Linux distributions and Mac OS include the command-line SSH utility. For more information, see SSH
Using Linux or Mac OS.
Required Raspberry Pi software
This article assumes you have installed the latest version of the Raspbian OS on your Raspberry Pi.
The following steps show you how to prepare your Raspberry Pi for building a C application that connects to the
preconfigured solution:
1. Connect to your Raspberry Pi using . For more information, see SSH (Secure Shell) on the Raspberry Pi
website.
2. Use the following command to update your Raspberry Pi:

3. Use the following command to add the required development tools and libraries to your Raspberry Pi:

4. Use the following commands to download, build, and install the IoT Hub client libraries on your Raspberry
Pi:
Create a project
Complete the following steps using the connection to your Raspberry Pi:
1. Create a folder called in your home folder on the Raspberry Pi. Navigate to this folder in
your shell:

2. Create the four files , , , and in the

folder.
3. In a text editor, open the file. On the Raspberry Pi, you can use either the or
text editor. Add the following statements:

Specify the behavior of the IoT device

The IoT Hub serializer client library uses a model to specify the format of the messages the device exchanges with
IoT Hub.
1. Add the following variable declarations after the statements. Replace the placeholder values
and with the values you noted for your device in the remote monitoring
solution dashboard. Use the IoT Hub Hostname from the solution dashboard to replace . For
example, if your IoT Hub Hostname is , replace [IoTHub Name] with :

2. Add the following code to define the model that enables the device to communicate with IoT Hub. This
model specifies that the device:
Can send temperature, pressure, and humidity as telemetry.
Can send reported properties, to the device twin in IoT Hub. These reported properties include
information about the telemetry schema and supported methods.
 Can receive and act on desired properties set in the device twin in IoT Hub.
Can respond to the , , , and
direct methods invoked from the UI. The device sends information about the direct methods it
supports using reported properties.

Implement the behavior of the device

Now add code that implements the behavior defined in the model.
1. Add the following functions that handle the desired properties set in the solution dashboard. These desired
properties are defined in the model:
2. Add the following functions that handle the direct methods invoked through the IoT hub. These direct
methods are defined in the model:

3. Add the following function that adds a property to a device-to-cloud message:

4. Add the following function that sends a message with properties to the preconfigured solution:
5. Add the following callback handler that runs when the device has sent new reported property values to the
preconfigured solution:

6. Add the following function to connect your device to the preconfigured solution in the cloud, and exchange
data. This function performs the following steps:
Initializes the platform.
Registers the Contoso namespace with the serialization library.
Initializes the client with the device connection string.
Create an instance of the model.
Creates and sends reported property values.
Creates a loop to send telemetry every five seconds.
Deinitializes all resources.
For reference, here is a sample message sent to the preconfigured solution:
Save the file and exit the editor.

Add code to run the app

In a text editor, open the file. Add the following code:

Save the file and exit the editor.

In a text editor, open the file. Add the following code:

Save the file and exit the editor.

Build and run the application

The following steps describe how to use CMake to build your client application.
1. In a text editor, open the file in the folder.
2. Add the following instructions to define how to build your client application:
3. Save the file and exit the editor.
4. In the folder, create a folder to store the make files that CMake generates. Then run the
and commands as follows:

5. Run the client application and send telemetry to IoT Hub:

View device telemetry

You can view the telemetry sent from your device on the page in the solution.
1. Select the device you provisioned in the list of devices on the page. A panel displays information
about your device including a plot of the device telemetry:

2. Choose to change the telemetry display:

3. To view diagnostic information about your device, scroll down to :

Act on your device
To invoke methods on your devices, use the page in the remote monitoring solution. For example, in the
remote monitoring solution devices implement a method.
1. Choose to navigate to the page in the solution.
2. Select the device you provisioned in the list of devices on the page:

3. To display a list of the methods you can call on your device, choose . To schedule a method to run
on multiple devices, you can select multiple devices in the list. The panel shows the types of
method common to all the devices you selected.
4. Choose , set the job name to , and choose :

5. A message displays in the console running your device code when the device handles the method.

NOTE
To track the status of the job in the solution, choose .

Next steps
The article Customize the remote monitoring preconfigured solution describes some ways to customize the
preconfigured solution.
 Remote monitoring preconfigured solution
architecture
11/10/2017 • 4 min to read • Edit Online

The IoT Suite remote monitoring preconfigured solution implements an end-to-end monitoring solution for
multiple machines in remote locations. The solution combines key Azure services to provide a generic
implementation of the business scenario. You can use the solution as a starting point for your own implementation
and customize it to meet your own specific business requirements.
This article walks you through some of the key elements of the remote monitoring solution to enable you to
understand how it works. This knowledge helps you to:
Troubleshoot issues in the solution.
Plan how to customize to the solution to meet your own specific requirements.
Design your own IoT solution that uses Azure services.

Logical architecture
The following diagram outlines the logical components of the remote monitoring preconfigured solution overlaid
on the IoT architecture:

Why microservices?
Cloud architecture has evolved since Microsoft released the first preconfigured solutions. Microservices have
emerged as a proven practice to achieve scale and flexibility without sacrificing development speed. Several
Microsoft services use this architectural pattern internally with great reliability and scalability results. The updated
preconfigured solutions put these learnings into practice so you can also benefit from them.

TIP
To learn more about microservice architectures, see .NET Application Architecture and Microservices: An application
revolution powered by the cloud.

Device connectivity
The solution includes the following components in the device connectivity part of the logical architecture:
Simulated devices
The solution includes a microservice that enables you to manage a pool of simulated devices to test the end-to-end
flow in the solution. The simulated devices:
Generate device-to-cloud telemetry.
Respond to cloud-to-device method calls from IoT Hub.
The microservice provides a RESTful endpoint for you to create, start, and stop simulations. Each simulation
consists of a set of virtual devices of different types, that send telemetry and respond to method calls.
You can provision simulated devices from the dashboard in the solution portal.
Physical devices
You can connect physical devices to the solution. You can implement the behavior of your simulated devices using
the Azure IoT device SDKs.
You can provision physical devices from the dashboard in the solution portal.
IoT Hub and the IoT manager microservice
The IoT hub ingests data sent from the devices into the cloud and makes it available to the
microservice.
The IoT hub in the solution also:
Maintains an identity registry that stores the IDs and authentication keys of all the devices permitted to connect
to the portal. You can enable and disable devices through the identity registry.
Invokes methods on your devices on behalf of the solution portal.
Maintains device twins for all registered devices. A device twin stores the property values reported by a device.
A device twin also stores desired properties, set in the solution portal, for the device to retrieve when it next
connects.
Schedules jobs to set properties for multiple devices or invoke methods on multiple devices.
The solution includes the microservice to handle interactions with your IoT hub such as:
Creating and managing IoT devices.
Managing device twins.
Invoking methods on devices.
Managing IoT credentials.
This service also runs IoT Hub queries to retrieve devices belonging to user-defined groups.
The microservice provides a RESTful endpoint to manage devices and device twins, invoke methods, and run IoT
Hub queries.
Data processing and analytics
The solution includes the following components in the data processing and analytics part of the logical
architecture:
Device telemetry
The solution includes two microservices to handle device telemetry.
The telemetry-agent microservice:
Stores telemetry in Cosmos DB.
Analyzes the telemetry stream from devices.
Generates alarms according to defined rules.
The alarms are stored in Cosmos DB.
The microservice enables the solution portal to read the telemetry sent from the devices. The
solution portal also uses this service to:
Define monitoring rules such as the thresholds that trigger alarms
Retrieve the list of past alarms.
Use the RESTful endpoint provided by this microservice to manage telemetry, rules, and alarms.
Storage
The storage-adapter microservice is an adapter in front of the main storage service used for the preconfigured
solution. It provides simple collection and key-value storage.
The standard deployment of the preconfigured solution uses Cosmos DB as its main storage service.
The Cosmos DB database stores data in the preconfigured solution. The microservice acts as an
adapter for the other microservices in the solution to access storage services.

Presentation
The solution includes the following components in the presentation part of the logical architecture:
The web user interface is a React Javascript application. The application:
Uses Javascript React only and runs entirely in the browser.
Is styled with CSS.
Interacts with public facing microservices through AJAX calls.
The user interface presents all the preconfigured solution functionality, and interacts with other services such as:
The authentication microservice to protect user data.
The iothub-manager microservice to list and manage the IoT devices.
The ui-config microservice enables the user interface to store and retrieve configuration settings.

Next steps
If you want to explore the source code and developer documentation, start with one the two main GitHub
repositories:
Preconfigured solution for remote monitoring with Azure IoT (.NET).
Preconfigured solution for remote monitoring with Azure IoT (Java).
Preconfigured solution for remote monitoring architecture).
For more conceptual information about the remote monitoring preconfigured solution, see Customize the
preconfigured solution.
 Deploy an edge gateway for the Connected factory
preconfigured solution on Windows or Linux
1/17/2018 • 8 min to read • Edit Online

You need two software components to deploy an edge gateway for the Connected factory preconfigured solution:
The OPC Proxy establishes a connection to Connected factory. The OPC Proxy then waits for command and
control messages from the integrated OPC Browser that runs in the Connected factory solution portal.
The OPC Publisher connects to existing on-premises OPC UA servers and forwards telemetry messages
from them to Connected factory. You can connect an OPC classic device using the OPC classic adapter for
OPC UA.
Both components are open-source and are available as source on GitHub and as Docker containers on
DockerHub:

OPC Publisher OPC Publisher

OPC Proxy OPC Proxy

You do not need a public-facing IP address or open inbound ports in the gateway firewall for either component.
The OPC Proxy and OPC Publisher components only use outbound port 443.
The steps in this article show you how to deploy an edge gateway using Docker on either Windows or Linux. The
gateway enables connectivity to the Connected factory preconfigured solution. You can also use the components
without Connected factory.

NOTE
Both components can be used as modules in Azure IoT Edge.

Choose a gateway device

If you don't yet have a gateway device, Microsoft recommends you buy a commercial gateway from one of their
partners. For a list of gateway devices compatible with the Connected factory solution, visit the Azure IoT device
catalog. Follow the instructions that come with the device to set up the gateway.
Alternatively, use the following instructions to manually configure an existing gateway device.

Install and configure Docker

Install Docker for Windows on your Windows-based gateway device or use a package manager to install docker
on your Linux-based gateway device.
During Docker for Windows setup, select a drive on your host machine to share with Docker. The following
screenshot shows sharing the drive on your Windows system to allow access to the host drive from inside a
docker container:
 NOTE
You can also perform this step after installing docker from the dialog. Right-click on the icon in the
Windows system tray and choose . If major Windows updates have been deployed to the system, such as the
Windows Fall Creators update, unshare the drives and share them again to refresh the access rights.

If you are using Linux, no additional configuration is required to enable access to the file system.
On Windows, create a folder on the drive you shared with Docker, on Linux create a folder under the root
filesystem. This walkthrough refers to this folder as .
When you refer to the in a Docker command, be sure to use the correct syntax for your operating
system. Here are two examples, one for Windows and one for Linux:
If your are using the folder on Windows as your , the Docker command syntax
is .
If your are using the folder on Linux as your , the Docker command syntax is
.
For more information see the Use volumes docker engine reference.

Configure the OPC components

Before you install the OPC components, complete the following steps to prepare your environment:
1. To complete the gateway deployment, you need the connection string of the IoT Hub in your
Connected factory deployment. In the Azure portal, navigate to your IoT Hub in the resource group created
when you deployed the Connected factory solution. Click to access the
connection string:
 Copy the value.
2. To allow communication between docker containers, you need a user-defined bridge network. To create a
bridge network for your containers, run the following commands at a command prompt:

To verify the bridge network was created, run the following command:

Your bridge network is included in the list of networks.

To run the OPC Publisher, run the following command at a command prompt:

The OPC Publisher GitHub and the docker run reference provide more information about:
The docker command line options specified before the container name (
).
The meaning of the OPC Publisher command line parameters specified after the container name (
).
The is the shared access policy connection string from the
Azure portal. You copied this connection string in a previous step. You only need this connection string for
the first run of OPC Publisher. On subsequent runs you should omit it because it poses a security risk.
The you use and its syntax is described in the section Install and configure Docker. OPC
Publisher uses the to read and write to the OPC Publisher configuration file, write to the
log file, and make both these files available outside of the container.
 OPC Publisher reads its configuration from the file, which is read from and written
to the folder. This configuration file defines which OPC UA node data on a given
OPC UA server the OPC Publisher should subscribe to. The full syntax of the file is
described on the OPC Publisher page on GitHub. When you add a gateway, put an empty
into the folder:

Whenever the OPC UA server notifies OPC Publisher of a data change, the new value is sent to IoT Hub.
Depending on the batching settings, the OPC Publisher may first accumulate the data before it sends the
data to IoT Hub in a batch.
Docker does not support NetBIOS name resolution, only DNS name resolution. If you don't have a DNS
server on the network, you can use the workaround shown in the previous command line example. The
previous command line example uses the parameter to add an entry into the containers hosts
file. This entry enables hostname lookup for the given , resolving to the given IP
address .
OPC UA uses X.509 certificates for authentication and encryption. You need to place the OPC Publisher
certificate on the OPC UA server you are connecting to, to ensure it trusts OPC Publisher. The OPC
Publisher certificate store is located in the folder. You can find the OPC
Publisher certificate in the folder in the folder.
The steps to configure the OPC UA server depend on the device you are using. these steps are typically
documented in the OPC UA server's user manual.
To install the OPC Proxy, run the following command at a command prompt:

You only need to run the installation once on a system.

Use the following command to run the OPC Proxy:

OPC Proxy saves the connection string during the installation. On subsequent runs you should omit the
connection string because it poses a security risk.

Enable your gateway

Complete the following steps to enable your gateway in the Connected factory preconfigured solution:
1. When both components are running, browse to the page in the
Connected factory solution portal. This page is only available to Administrators in the solution. Enter the
publisher endpoint URL (opc.tcp://publisher:62222) and click .
2. Establish a trust relationship between the Connected factory portal and OPC Publisher. When you see a
certificate warning, click . Next, you see an error that the OPC Publisher doesn’t trust the UA Web
client. To resolve this error, copy the certificate from the
folder to the
 folder on the gateway. You do not need to restart the
gateway.
You can now connect to the gateway from the cloud, and you are ready to add OPC UA servers to the solution.

Add your own OPC UA servers

To add your own OPC UA servers to the Connected factory preconfigured solution:
1. Browse to the page in the Connected factory solution portal.
a. Start the OPC UA server you want to connect to. Ensure that your OPC UA server can be reached from
OPC Publisher and OPC Proxy running in the container (see the previous comments about name
resolution).
b. Enter the endpoint URL of your OPC UA server ( ) and click .
c. As part of the connection setup, a trust relationship between the Connected factory portal (OPC UA
client) and the OPC UA server you are trying to connect is established. In the Connected factory
dashboard you get a warning.
When you see a certificate warning, click .
d. More difficult to setup is the certificate configuration of the OPC UA server you are trying to connect
to. For PC based OPC UA servers, you may just get a warning dialog in the dashboard that you can
acknowledge. For embedded OPC UA server systems, consult the documentation of your OPC UA
server to look up how this task is done. To complete this task, you may need the certificate of the
Connected factory portal's OPC UA client. An Administrator can download this certificate on the
page:

2. Browse the OPC UA nodes tree of your OPC UA server, right-click the OPC nodes you want to send values
to Connected factory, and select .
3. Telemetry now flows from the gateway device. You can view the telemetry in the view
of the Connected factory portal under .

Next steps
To learn more about the architecture of the Connected factory preconfigured solution, see Connected factory
preconfigured solution walkthrough.
Learn about the OPC Publisher reference implementation.
 Customize how the Connected factory solution
displays data from your OPC UA servers
12/14/2017 • 2 min to read • Edit Online

The Connected factory solution aggregates and displays data from the OPC UA servers connected to the solution.
You can browse and send commands to the OPC UA servers in your solution. For more information about OPC UA,
see the Connected factory FAQ.
Examples of aggregated data in the solution include the Overall Equipment Efficiency (OEE) and Key Performance
Indicators (KPIs) that you can view in the dashboard at the factory, line, and station levels. The following screenshot
shows the OEE and KPI values for the station, on , in the factory:

The solution enables you to view detailed information from specific data items from the OPC UA servers, called
stations. The following screenshot shows plots of the number of manufactured items from a specific station:

If you click one of the graphs, you can explore the data further using Time Series Insights (TSI):
This article describes:
How the data is made available to the various views in the solution.
How you can customize the way the solution displays the data.

Data sources
The Connected factory solution displays data from the OPC UA servers connected to the solution. The default
installation includes several OPC UA servers running a factory simulation. You can add your own OPC UA servers
that connect through a gateway to your solution.
You can browse the data items that a connected OPC UA server can send to your solution in the dashboard:
1. Choose to navigate to the view:
2. Select a server and click . Click when the security warning appears.

NOTE
This warning only appears once for each server and establishes a trust relationship between the solution dashboard
and the server.

3. You can now browse the data items that the server can send to the solution. Items that are being sent to the
solution have a check mark:

4. If you are an Administrator in the solution, you can choose to publish a data item to make it available in the
Connected factory solution. As an Administrator, you can also change the value of data items and call
methods in the OPC UA server.

Map the data

The Connected factory solution maps and aggregates the published data items from the OPC UA server to the
various views in the solution. The Connected factory solution deploys to your Azure account when you provision
the solution. A JSON file in the Visual Studio Connected factory solution stores this mapping information. You can
view and modify this JSON configuration file in the Connected factory Visual Studio solution. You can redeploy the
solution after you make a change.
You can use the configuration file to:
Edit the existing simulated factories, production lines, and stations.
Map data from real OPC UA servers that you connect to the solution.
For more information about mapping and aggregating the data to meet your specific requirements, see How to
configure the Connected factory preconfigured solution .

Deploy the changes

When you have finished making changes to the file, you must redeploy the
Connected factory solution to your Azure account.
The repository includes a PowerShell script you can use to rebuild and
deploy the solution.

Next Steps
Learn more about the Connected factory preconfigured solution by reading the following articles:
Connected factory preconfigured solution walkthrough
Deploy a gateway for Connected factory
Permissions on the azureiotsuite.com site
Connected factory FAQ
FAQ
 OPC Publisher for Azure IoT Edge
11/14/2017 • 12 min to read • Edit Online

This article describes how to use the OPC Publisher reference implementation. The reference implementation
demonstrates how to use Azure IoT Edge to:
Connect to existing OPC UA servers.
Publish JSON encoded telemetry data from these servers in OPC UA Pub/Sub format, using a JSON payload, to
Azure IoT Hub. You can use any of the transport protocols that Azure IoT Edge supports.
This reference application includes:
An OPC UA client for connecting to existing OPC UA servers on your network.
An OPC UA server listening on port 62222 that you can use to manage what is published.
The application is implemented using .NET Core and can run on the platforms supported by .NET Core.
The publisher implements retry logic when it establishes connections to endpoints. The publisher expects
endpoints to respond within a specified number of keep alive requests. This retry logic enables the publisher to
detect conditions such as a power outage for an OPC UA server.
For each distinct publishing interval to an OPC UA server, it creates a separate subscription over which all nodes
with this publishing interval are updated.
To reduce network load, the publisher supports batching of data sent to IoT Hub. A batch is sent to IoT Hub only
when the configured package size is reached.
This application uses the OPC Foundations's OPC UA reference stack and therefore licensing restrictions apply.
Visit http://opcfoundation.github.io/UA-.NETStandardLibrary/ for OPC UA documentation and licensing terms.
You can find the OPC Publisher source code in the OPC Publisher for Azure IoT Edge GitHub repository.

Prerequisites
To build the application, you need the .NET Core SDK 1.1. for your operating system.

Build the application

As native Windows application
Open the project with Visual Studio 2017 and build the solution by hitting F7.
As Docker container
To build the application as a Windows Docker container, use the configuration file.
To build the application as a Linux Docker container, use the configuration file.
From the root of the repository on your development machine, type the following command in a console window:

The option for is optional and the default is to use the configuration file.
Docker also enables you to build directly from a git repository. You can build a Linux Docker container with the
following command:
Configure the OPC UA nodes to publish
To configure which OPC UA nodes should have their values published to Azure IoT Hub, create a JSON formatted
configuration file. The default name for this configuration file is . The application updates and
saves this configuration file when it uses the OPC UA server methods or .
The syntax of the configuration file is as follows:
Run the application
Command-line options
To see the complete usage of the application, use the command-line option. The following example shows
the structure of a command:

is the OPC UA application name to use. This parameter is required. The application name is also
used to register the publisher in the IoT Hub device registry.
is the IoT Hub owner connection string. This parameter is optional.
The following options are supported:
You can use the following environment variables to control the application:
: sets the IoT Hub owner connection string
: sets the filename of the log file to use
: sets the path to store certificates of trusted stations
: sets the filename of the publishing configuration file

Command-line arguments overrule environment variable settings.

Typically, you specify the IoT Hub owner connection string only on the first start of the application. The connection
string is encrypted and stored in the platform's certificate store.
On subsequent calls, the connection string is read from platform's certificate store and reused. If you specify the
connection string on each start, the device in the IoT Hub device registry is removed and recreated each time.
Native on Windows
To run the application natively on Windows, open the project with Visual Studio 2017, build the
solution, and publish it. You can start the application in the you have published to with:

Use a self-built container

To run the application in a self-built container, build and then start your own container:

Use a container from hub.docker.com

There is a prebuilt container available on DockerHub. To start it, run the following command:

Important when using a container

Access to the Publisher OPC UA server
The Publisher OPC UA server by default listens on port 62222. To expose this inbound port in a container, you need
to use the option :

Enable intercontainer name resolution

To enable name resolution from within the container to other containers, you must:
Create a user-defined docker bridge network.
Connect the container to the network using the option.
Assign the container a name using the option.
The following example shows these configuration options:

The container can now be reached by other containers over the network using the name .
Assign a hostname
Publisher uses the hostname of the machine it is running on for certificate and endpoint generation. Docker
chooses a random hostname unless you set one with the option. Here an example to set the internal hostname
of the container to :

Using bind mounts (shared filesystem )

In some scenarios, you want to read configuration information from, or write log files to, locations on the host
instead of using the container file system. To configure this behavior, use the option of in the bind
mount mode. For example:

Store for X509 certificates

Storing X509 certificates does not work with bind mounts, because the permissions of the path to the store need to
be for the owner. Instead you need to use the option of in the volume mode.

Debug the application

Native on Windows
Open the project with Visual Studio 2017 and start debugging the app by hitting F5.
In a docker container
Visual Studio 2017 supports debugging applications in a Docker container by using . However, this
method does not allow you to pass command-line parameters.
An alternative debugging option that VS2017 supports is to debug over . You can use the docker build
configuration file in the root of the repository to create an SSH enabled container:

You can now start the container to debug the publisher:

In the container, you must start the daemon manually:

At this point, you can create an session as user with password .

To prepare to debug the application in the container, complete the following additional steps:
1. On the host-side, create a file:
2. Build your project and publish it to a directory of your choice.
3. Use a tool such as to copy the published files into the directory in the container. If
you choose to use a different directory, update the property in the file.

Now you can start debugging using the following command in Visual Studio's Command Window:

Next steps
A suggested next step is to learn how to Deploy a gateway on Windows or Linux for the connected factory
preconfigured solution.
 Configure the Connected factory preconfigured
solution
1/2/2018 • 9 min to read • Edit Online

The Connected factory preconfigured solution shows a simulated dashboard for a fictional company Contoso. This
company has factories in numerous global locations globally.
This article uses Contoso as an example to describe how to configure the topology of a Connected factory solution.

Simulated factories configuration

Each Contoso factory has production lines that consist of three stations each. Each station is a real OPC UA server
with a specific role:
Assembly station
Test station
Packaging station
These OPC UA servers have OPC UA nodes and OPC Publisher sends the values of these nodes to Connected
factory. This includes:
Current operational status such as current power consumption.
Production information such as the number of products produced.
You can use the dashboard to drill into the Contoso factory topology from a global view down to a station level
view. The Connected factory dashboard enables:
The visualization of OEE and KPI figures for each layer in the topology.
The visualization of current values of OPC UA nodes in the stations.
The aggregation of the OEE and KPI figures from the station level to the global level.
The visualization of alerts and actions to perform if values reach specific thresholds.

Connected factory topology

The topology of factories, production lines, and stations is hierarchical:
The global level has factory nodes as children.
The factories have production line nodes as children.
The production lines have station nodes as children.
The stations (OPC UA servers) have OPC UA nodes as children.
Every node in the topology has a common set of properties that define:
A unique identifier for the topology node.
A name.
A description.
An image.
The children of the topology node.
Minimum, target, and maximum values for OEE and KPI figures and the alert actions to execute.
Topology configuration file
To configure the properties listed in the previous section, the Connected factory solution uses a configuration file
called ContosoTopologyDescription.json.
You can find this file in the solution source code in the folder.
The following snippet shows an outline of the configuration file:

The common properties of , , ,

and are:
(type string)
Defines a descriptive name, which should be only one word for the topology node to show in the
dashboard.
(type string)
Describes the topology node in more detail.
(type string)
The path to an image in the WebApp solution to show when information about the topology node is shown
in the dashboard.
, , , , , (type
)
These properties define minimal, target, and maximal values of the operational figure used to generate
alerts. These properties also define the actions to execute if an alert is detected.
The and items have a property:
(type string)
Uniquely identifies the topology node.
has a property:
(type )
Specifies where the factory is located.
has properties:
 (type string)
This property must be set to the OPC UA Application URI of the OPC UA server. Because it must be globally
unique by OPC UA specification, this property is used to identify the station topology node.
, which are an array of OPC UA nodes (type )
has properties:
(type string)
Name of city closest to the location
(type string)
Country of the location
(type double)
Latitude of the location
(type double)
Longitude of the location
has properties:
(type double)
Lower threshold the value can reach. If the current value is below this threshold, an alert is generated.
(type double)
Ideal target value.
(type double)
Upper threshold the value can reach. If the current value is above this threshold, an alert is generated.
(type )
Defines the set of actions, which can be taken as response to a minimum alert.
(type )
Defines the set of actions, which can be taken as response to a maximum alert.
> has properties:
(type string)
Type of the alert action. The following types are known:
: the status of the alert should change to acknowledged.
: all older alerts of the same type should no longer be shown in the dashboard.
: an OPC UA method should be called.
: a browser window should be opened showing additional contextual information.
(type string)
Description of the action shown in the dashboard.
(type string)
Parameters required to execute the action. The value depends on the action type.
 : no parameter required.
: no parameter required.
: the node information and parameters of the OPC UA method to call in the format
"NodeId of parent node, NodeId of method to call, URI of the OPC UA server."
: the URL to show in the browser window.
contains information about OPC UA nodes in a station (OPC UA server). Nodes that
represent no existing OPC UA nodes, but are used as storage in the computation logic of Connected factory are
also valid. It has the following properties:
(type string)
Address of the OPC UA node in the station’s (OPC UA server’s) address space. Syntax must be as specified in
the OPC UA specification for a NodeId.
(type string)
Name to be shown in the dashboard when the value of this OPC UA node is shown.
(array of type string)
Indicates for which computation of OEE or KPI the OPC UA node value is relevant. Each array element can be
one of the following values:
: the value is relevant for calculation of OEE Availability.
: the value is relevant for calculation of OEE Availability.
: the value is relevant for calculation of OEE Performance and is typically a
constant value.
: the value is relevant for calculation of OEE Performance.
: the value is relevant for calculation of OEE Quality.
: the value is relevant for calculation of OEE Quality.
: the value is relevant for calculation of KPI1.
: the value is relevant for calculation of KPI2.
(type string)
Indicates how the value of the OPC UA node is handled in Time Series Insight queries and OEE/KPI
calculations. Each Time Series Insight query targets a specific timespan, which is a parameter of the query
and delivers a result. The OpCode controls how the result is computed and can be one of the following
values:
: difference between the last and the first value in the timespan.
: the average of all values in the timespan.
: the sum of all values in the timespan.
: currently not used.
: the number of values in the timespan.
: the maximal value in the timespan.
: the minimal value in the timespan.
: the result is the value specified by property ConstValue.
: the difference between the maximal and the minimal value.
: the timespan.
(type string)
Defines a unit of the value for display in the dashboard.
 (type boolean)
Controls if the value should be shown in the dashboard.
(type double)
If the is , then this property is the value of the node.
(type double)
If the current value falls below this value, then a minimum alert is generated.
(type double)
If the current value raises above this value, then a maximum alert is generated.
(type )
Defines the set of actions, which can be taken as response to a minimum alert.
(type )
Defines the set of actions, which can be taken as response to a maximum alert.
At the station level, you also see objects. These objects are only used to configure the Connected
factory simulation and should not be used to configure a real topology.

How the configuration data is used at runtime

All the properties used in the configuration file can be grouped into different categories depending on how they
are used. Those categories are:
Visual appearance
Properties in this category define the visual appearance of the Connected factory dashboard. Examples include:
Name
Description
Image
Location
Units
Visible
Internal topology tree addressing
The WebApp maintains an internal data dictionary containing information of all topology nodes. The properties
and are used as keys to access this dictionary and need to be unique.
OEE/KPI computation
The OEE/KPI figures for the Connected factory simulation are parameterized by:
The OPC UA node values to be included in the calculation.
How the figure is computed from the telemetry values.
Connected factory uses the OEE formulas as published by the http://oeeindustrystandard.oeefoundation.org.
OPC UA node objects in stations enable tagging for usage in OEE/KPI calculation. The property
indicates for which OEE/KPI figure the OPC UA node value should be used. The property defines how the
value is included in the computation.
Alert handling
Connected factory supports a simple minimum/maximum threshold-based alert generation mechanism. There are
a number of predefined actions you can configure in response to those alerts. The following properties control this
mechanism:
Maximum
Minimum
MaximumAlertActions
MinimumAlertActions

Correlating to telemetry data

For certain operations, such as visualizing the last value or creating Time Series Insight queries, the WebApp needs
an addressing scheme for the ingested telemetry data. The telemetry sent to Connected factory also needs to be
stored in internal data structures. The two properties enabling these operations are at station (OPC UA server) and
OPC UA node level:

Identifies (globally unique) the OPC UA server the telemetry comes from. In the ingested messages, this
property is sent as .

Identifies the node value in the OPC UA server. The format of the property must be as specified in the OPC
UA specification. In the ingested messages, this property is sent as .
Check this GitHub page for more information on how the telemetry data is ingested to Connected factory using the
OPC Publisher.

Example: How KPI1 is calculated

The configuration in the file controls how OEE/KPI figures are calculated. The
following example shows how properties in this file control the computation of KPI1.
In Connected factory KPI1 is used to measure the number of successfully manufactured products in the last hour.
Each station (OPC UA server) in the Connected factory simulation provides an OPC UA node (
), which provides the telemetry to compute this KPI.
The configuration for this OPC UA node looks like the following snippet:

This configuration enables querying of the telemetry values of this node using Time Series Insights. The Time
Series Insights query retrieves:
The number of values.
The minimal value.
The maximal value.
The average of all values.
The sum of all values for all unique ( ), pairs in a given timespan.
One characteristic of the node value is that it only increases. To calculate
the number of products manufactured in the timespan, Connected factory uses the . The
calculation retrieves the minimum value at the start of the timespan and the maximum value at the end of the
timespan.
The in the configuration configures the computation logic to calculate the result of the difference of
maximum and minimum value. Those results are then accumulated bottom up to the root (global) level and shown
in the dashboard.

Next steps
A suggested next step is to learn how to Deploy a gateway on Windows or Linux for the connected factory
preconfigured solution.
 Permissions on the azureiotsuite.com site
12/18/2017 • 3 min to read • Edit Online

What happens when you sign in

The first time you sign in at azureiotsuite.com, the site determines the permission levels you have based on the
currently selected Azure Active Directory (AAD) tenant and Azure subscription.
1. First, to populate the list of tenants seen next to your username, the site finds out from Azure which AAD
tenants you belong to. Currently, the site can only obtain user tokens for one tenant at a time. Therefore,
when you switch tenants using the dropdown in the top right corner, the site logs you in to that tenant to
obtain the tokens for that tenant.
2. Next, the site finds out from Azure which subscriptions you have associated with the selected tenant. You see
the available subscriptions when you create a new preconfigured solution.
3. Finally, the site retrieves all the resources in the subscriptions and resource groups tagged as preconfigured
solutions and populates the tiles on the home page.
The following sections describe the roles that control access to the preconfigured solutions.

AAD roles
The AAD roles control the ability provision preconfigured solutions and manage users in a preconfigured solution.
You can find more information about administrator roles in AAD in Assigning administrator roles in Azure AD. The
current article focuses on the and the directory roles as used by the preconfigured
solutions.
Global administrator
There can be many global administrators per AAD tenant:
When you create an AAD tenant, you are by default the global administrator of that tenant.
The global administrator can provision a basic and standard preconfigured solutions.
Domain user
There can be many domain users per AAD tenant:
A domain user can provision a basic preconfigured solution through the azureiotsuite.com site.
A domain user can create a basic preconfigured solution using the CLI.
Guest User
There can be many guest users per AAD tenant. Guest users have a limited set of rights in the AAD tenant. As a
result, guest users cannot provision a preconfigured solution in the AAD tenant.
For more information about users and roles in AAD, see the following resources:
Create users in Azure AD
Assign users to apps

Azure subscription administrator roles

The Azure admin roles control the ability to map an Azure subscription to an AD tenant.
Find out more about the Azure admin roles in the article How to add or change Azure Co-Administrator, Service
Administrator, and Account Administrator.

FAQ
I'm a service administrator and I'd like to change the directory mapping between my subscription and a specific
AAD tenant. How do I complete this task?
See To add an existing subscription to your Azure AD directory
I want to change a Service Administrator or Co-Administrator when logged in with an organisational account
See the support article Changing Service Administrator and Co-Administrator when logged in with an
organisational account.
Why am I seeing this error? "Your account does not have the proper permissions to create a solution. Please
check with your account administrator or try with a different account."
Look at the following diagram for guidance:
 NOTE
If you continue to see the error after validating you are a global administrator on the AAD tenant and a co-administrator on
the subscription, have your account administrator remove the user and reassign necessary permissions in this order. First,
add the user as a global administrator and then add user as a co-administrator on the Azure subscription. If issues persist,
contact Help & Support.

Why am I seeing this error when I have an Azure subscription? "An Azure subscription is required to create pre-
configured solutions. You can create a free trial account in just a couple of minutes."
If you're certain you have an Azure subscription, validate the tenant mapping for your subscription and ensure the
correct tenant is selected in the dropdown. If you’ve validated the desired tenant is correct, follow the preceding
diagram and validate the mapping of your subscription and this AAD tenant.

Next steps
To continue learning about IoT Suite, see how you can customize a preconfigured solution.
 Internet of Things security architecture
1/17/2018 • 24 min to read • Edit Online

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 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 modeling 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 leaves 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 inform and drive testing of your Internet of Things (IoT) solution.
When to threat model
Threat modeling offers the greatest value when you incorporate it 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 ultimately requires more work and a lot harder tradeoffs than threat modeling early on in the
development.
What to threat model
You should threat 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 approach
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 such as web services, Win32 services, and *nix daemons. 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; this article 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, when 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 you explore the interaction patterns, 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 is 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 following diagram. 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 following sections elaborate on each of the components and specific security concerns
and solutions that should be put into place.
The following sections 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 has 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, does 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 are 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 not a
device control system or 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 versus 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 large, 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 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 you explore the interaction patterns, 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 previously to do threat modeling for Azure IoT. The following section uses
the concrete example of Azure IoT Reference Architecture to demonstrate how to think about threat modeling for
IoT and how to address the threats identified. This example identifies four main areas of focus:
Devices and Data Sources,
Data Transport,
Device and Event Processing, and
Presentation

The following diagram 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 approach enables
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, 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 previously through the lens of threat modeling and gives an
overview of how to address some of the inherent concerns. This example focuses on the core elements of a threat
model:
Processes (both under your 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, this example tries to mitigate a number of different
threats across the different stages data/information exists in: process, communication, and storage. Following is an
overview of the most common ones for the “process” category, followed by an overview of how these threats could
be best mitigated:
: 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.
: 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 cannot report data, at all.
: 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.
: 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.
: 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.
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 you Security (TLS) or
know you 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, device (physical platform module
by making it hard to interference). How are (TPM) capability that
impossible to extract you sure, that device allows storing keys in
keys and other has not been special on-chip
cryptographic tampered 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 scheme. be performed based
on commands from
an outside source, or
even compromised
sensors, it allows 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 (such can present itself as same key storage and
as cert based, PSK, or any device. attestation concerns
Claim based.) of devices in general –
best case is use TPM.
6LowPAN extension
for IPSec to support
Wireless Sensor
Networks (WSN).
 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.
: 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 cannot report data, at all.
: 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.
: 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 reports manipulated
information.
: 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.
: 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.
: If the device is running manipulated software, such manipulated software could
potentially leak data to unauthorized parties.
: 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.
: The device can be turned off or turned into a mode where communication is not possible
(which is intentional in many industrial machines).
: 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
: 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.
: The device can be turned into a state where communication is not possible.
: 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.
: 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 following table has some guidance around open sockets on the device/VPN:

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, you
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, you need
device with new to 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, you need
to figure out how to
protect them.
 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, you need
to figure out how to
protect them.

Here are some examples of threats in this category:

: 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 slowly, or the device can be flooded with unsolicited traffic. In both cases, the
device can effectively be rendered inoperable on the network.
: 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 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.
: an attacker may intercept or partially override the broadcast and spoof the originator (man in the
middle)
: an attacker may intercept or partially override the broadcast and send false information
an attacker may eavesdrop on a broadcast and obtain information without authorization
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).

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
 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 not a device control system or 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. 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 exceptions are intermediate physical control
surfaces on devices, like a switch that allows a person to turn off the device or change other properties, and for
which there is no functional equivalent that can be accessed digitally.
Intermediate physical control surfaces are those where 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
For more information, see the following articles:
SDL Threat Modeling Tool
Microsoft Azure IoT reference architecture

See also
To learn more about securing your IoT solution, see Secure your IoT deployment.
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Frequently asked questions for IoT Suite
You can read about IoT Hub security in Control access to IoT Hub in the IoT Hub developer guide.
 Internet of Things security best practices
1/17/2018 • 6 min to read • Edit Online

Securing 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.
: Typically, these players 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.
: 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.
: After an IoT solution is developed, it needs to be deployed in the field. This process
involves deployment of hardware, interconnection of devices, and deployment of solutions in hardware devices
or the cloud.
: After the IoT solution is deployed, it requires long-term operations, monitoring,
upgrades, and maintenance. These tasks 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.
: 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.
: 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.
: 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.
: 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:
: 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.
: 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 project might not be
supported and issues are not likely be discovered.
: 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:
: 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.
: 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:
: 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.
: If the operating system permits, install the latest antivirus and
antimalware capabilities on each device operating system. This practice can help mitigate most external threats.
You can protect most modern operating systems against threats by taking appropriate steps.
: 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.
: 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.
: 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
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Frequently asked questions for Azure IoT Suite
You can read about IoT Hub security in Control access to IoT Hub in the IoT Hub developer guide.
 Secure your IoT deployment
1/17/2018 • 7 min to read • Edit Online

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:
: Securing the IoT device while it is deployed in the wild.
: Ensuring all data transmitted between the IoT device and IoT Hub is confidential and
tamper-proof.
: 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 scenarios 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 uses security tokens from the
IoT device to IoT Hub differently:
AMQP: SASL PLAIN and AMQP Claims-based security ( with IoT hub-level
tokens; with device-scoped tokens).
MQTT: CONNECT packet uses as the , in the
field and a SAS token in the 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 that 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
effectively mitigates 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. If possible, use TLS 1.2 as it provides the most security.

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.
. Grants read access to the identity registry. For more information, see identity registry.
. Grants read and write access to the identity registry. For more information, see identity
registry.
. 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.
. 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 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 .
Service components can only generate security tokens using shared access policies granting the appropriate
permissions.
Azure IoT Hub and other services that 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:
Azure Cosmos DB: 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. Azure Cosmos DB 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.

IoT Suite Cipher Suites

Azure IoT Suite supports the following Cipher Suites, in this order.

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

See also
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Frequently asked questions for IoT Suite
You can read about IoT Hub security in Control access to IoT Hub in the IoT Hub developer guide.
 Internet of Things security from the ground up
1/17/2018 • 12 min to read • Edit Online

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
Microsoft's 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 that make provisioning, connecting to, and storing data from IoT
devices easy and transparent and, most of all, secure. This article examines 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 that 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
Microsoft's decades-long experience building enterprise software and running some of the largest online services
in the world, the Microsoft Cloud provides higher levels of enhanced security, privacy, compliance, and threat
mitigation practices than most customers could achieve on their own.
The 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, SDL uses rigorous security guidelines laid out in Microsoft's Operational
Security Assurance (OSA) process. Microsoft also works with third-party audit firms for ongoing verification that it
meets its compliance obligations, and Microsoft engages 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. Microsoft's 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. Microsoft's 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.
Microsoft's 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,
Microsoft offers 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
the 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, this article breaks 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 set up. 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 (that is, 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 (for example, 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:
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 that 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 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 reprovisioned. Data can be stored in Azure Cosmos DB 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 that can be trusted to transform any business.

Additional information
Each Azure IoT Suite pre-configured solution creates instances of Azure services, such as:
: Your gateway that connects the cloud to devices. 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.
: 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. Azure Cosmos DB
offers high-performance and high-throughput processing, schema-agnostic indexing of data, and a rich SQL
query interface.
: 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.
: 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.
: 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.
: Reliable, economical cloud storage for the data that your devices send to the cloud.

Next steps
To learn more about securing your IoT solution, see:
IoT Security Best Practices
IoT Security Architecture
Secure your IoT deployment
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Frequently asked questions for IoT Suite
You can read about IoT Hub security in Control access to IoT Hub in the IoT Hub developer guide.
 Frequently asked questions for IoT Suite
1/5/2018 • 4 min to read • Edit Online

See also, the connected factory-specific FAQ.

Where can I find the source code for the preconfigured solutions?
The source code is stored in the following GitHub repositories:
Remote monitoring preconfigured solution (.NET)
Remote monitoring preconfigured solution (Java)
Predictive maintenance preconfigured solution
Connected factory preconfigured solution
How much does it cost to provision the new remote monitoring solution?
The new preconfigured solution offers two deployment options:
A basic option designed for developers looking for lower development cost or customers looking to build a
demo or proof of concept.
A standard option designed for enterprises wanting to deploy a production-ready infrastructure.
How can I ensure I keep my costs down while I develop my solution?
In addition to providing two differentiated deployments, the new remote monitoring solution has a setting to
enable or disable all the simulated devices on demand. Disabling the simulation reduces the data ingested in the
solution and, thus, the overall cost.
Is the new microservices architecture available for all the three preconfigured solutions?
Currently, only the remote monitoring solution uses the microservices architecture as it covers the broadest
scenario.
What advantages does the new open-sourced microservices-based architecture provide in the new update?
Over the last two years, cloud architecture has greatly evolved. Micro services have emerged as a great pattern to
achieve scale and flexibility, without sacrificing development speed. This architectural pattern is used in several
Microsoft services internally with great reliability and scalability results. We are putting these learning in practice
so that our customers benefit from them.
Is the new preconfigured solution available in the same geographic region as the existing solution?
Yes, the new remote monitoring is available in the same geographic regions.
What is the difference between the basic and standard deployment options? How do I decide between the two
deployment options?
Each deployment option responds to different needs. The basic deployment is designed to get started and develop
PoC and small pilots. It provides a streamlined architecture with the minimum necessary resources and a lower
cost. The standard deployment is designed to build and customize a production-ready solution, and provides a
deployment with the necessary elements to realize that. For reliability and scale, application microservices are built
as Docker containers and deployed using an orchestrator (Kubernetes by default). The orchestrator is responsible
for deployment, scaling, and management of the application. You should choose an option based on your current
needs. You might use one, the other, or a combination of both depending on your project stage.
Can I continue to leverage my existing investments in Azure IoT Suite?
Yes. Any solution that exists today continues to work in your Azure subscription and the source code remains
available in GitHub.
What's the difference between deleting a resource group in the Azure portal and clicking delete on a
preconfigured solution in azureiotsuite.com?
If you delete the preconfigured solution in azureiotsuite.com, you delete all the resources that were provisioned
when you created the preconfigured solution. If you added additional resources to the resource group, these
resources are also deleted.
If you delete the resource group in the Azure portal, you only delete the resources in that resource group. You
also need to delete the Azure Active Directory application associated with the preconfigured solution.
How many IoT Hub instances can I provision in a subscription?
By default you can provision 10 IoT hubs per subscription. You can create an Azure support ticket to raise this limit.
As a result, since every preconfigured solution provisions a new IoT Hub, you can only provision up to 10
preconfigured solutions in a given subscription.
How many Azure Cosmos DB instances can I provision in a subscription?
Fifty. You can create an Azure support ticket to raise this limit, but by default, you can only provision 50 Cosmos DB
instances per subscription.
How many Free Bing Maps APIs can I provision in a subscription?
Two. You can create only two Internal Transactions Level 1 Bing Maps for Enterprise plans in an Azure subscription.
The remote monitoring solution is provisioned by default with the Internal Transactions Level 1 plan. As a result,
you can only provision up to two remote monitoring solutions in a subscription with no modifications.
Can I create a preconfigured solution if I have Microsoft Azure for DreamSpark?

NOTE
Microsoft Azure for DreamSpark is now known as Microsoft Imagine for students.

Currently, you cannot create a preconfigured solution with a Microsoft Azure for DreamSpark account. However,
you can create a free trial account for Azure in just a couple of minutes that enables you create a preconfigured
solution.
Can I create a preconfigured solution if I have Cloud Solution Provider (CSP) subscription?
Currently, you cannot create a preconfigured solution with a Cloud Solution Provider (CSP) subscription. However,
you can create a free trial account for Azure in just a couple of minutes that enables you create a preconfigured
solution.
How do I delete an AAD tenant?
See Eric Golpe's blog post Walkthrough of Deleting an Azure AD Tenant.
Next steps
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Connected factory preconfigured solution overview
IoT security from the ground up
 Frequently asked questions for IoT Suite connected
factory preconfigured solution
1/17/2018 • 9 min to read • Edit Online

See also, the general FAQ for IoT Suite.

Where can I find the source code for the preconfigured solution?
The source code is stored in the following GitHub repository:
Connected factory preconfigured solution
What is OPC UA?
OPC Unified Architecture (UA), released in 2008, is a platform-independent, service-oriented interoperability
standard. OPC UA is used by various industrial systems and devices such as industry PCs, PLCs, and sensors. OPC
UA integrates the functionality of the OPC Classic specifications into one extensible framework with built-in
security. It is a standard that is driven by the OPC Foundation. The OPC Foundation is a not-for-profit
organization with more than 440 members. The goal of the organization is to use OPC specifications to facilitate
multi-vendor, multi-platform, secure and reliable interoperability through:
Infrastructure
Specifications
Technology
Processes
Why did Microsoft choose OPC UA for the connected factory preconfigured solution?
Microsoft chose OPC UA because it is an open, non-proprietary, platform independent, industry-recognized, and
proven standard. It is a requirement for Industrie 4.0 (RAMI4.0) reference architecture solutions ensuring
interoperability between a broad set of manufacturing processes and equipment. Microsoft sees demand from its
customers to build Industrie 4.0 solutions. Support for OPC UA helps lower the barrier for customers to achieve
their goals and provides immediate business value to them.
How do I add a public IP address to the simulation VM?
You have two options to add the IP address:
Use the PowerShell script in the repository. Pass in your
deployment name as a parameter. For a local deployment, use . The
script prints out the IP address of the VM.
In the Azure portal, locate the resource group of your deployment. Except for a local deployment, the
resource group has the name you specified as solution or deployment name. For a local deployment using
the build script, the name of the resource group is . Now add a new
resource to the resource group.

NOTE
In either case, ensure you install the latest patches by following the instructions on the Ubuntu website. Keep the
installation up to date for as long as your VM is accessible through a public IP address.

How do I remove the public IP address to the simulation VM?

You have two options to remove the IP address:
 Use the PowerShell script Simulation/Factory/Remove-SimulationPublicIp.ps1 of the repository. Pass in
your deployment name as a parameter. For a local deployment, use . The
script prints out the IP address of the VM.
In the Azure portal, locate the resource group of your deployment. Except for a local deployment, the
resource group has the name you specified as solution or deployment name. For a local deployment using
the build script, the name of the resource group is . Now remove the
resource from the resource group.
How do I sign in to the simulation VM?
Signing in to the simulation VM is only supported if you have deployed your solution using the PowerShell script
in the repository.
If you deployed the solution from www.azureiotsuite.com, you cannot sign in to the VM. You cannot sign in,
because the password is generated randomly and you cannot reset it.
1. Add a public IP address to the VM. See How do I add a public IP address to the simulation VM?
2. Create an SSH session to your VM using the IP address of the VM.
3. The username to use is: .
4. The password to use depends on the version you used to deploy:
For solutions deployed using the build.ps1 script before 1 June 2017, the password is: .
For solutions deployed using the build.ps1 script after 1 June 2017, you can find the password in the
file. The password is stored in the setting.
The password is generated randomly at deployment time unless you specify it using the
script parameter
How do I stop and start all docker processes in the simulation VM?
1. Sign in to the simulation VM. See How do I sign in to the simulation VM?
2. To check which containers are active, run: .
3. To stop all simulation containers, run: .
4. To start all simulation containers:
Export a shell variable with the name . Use the value of the
setting in the file. For
example:

Run .
How do I update the simulation in the VM?
If you have made any changes to the simulation, you can use the PowerShell script in the repository
using the command. This script builds all the simulation components, stops the simulation in
the VM, uploads, installs, and starts them.
How do I find out the connection string of the IoT hub used by my solution?
If you deployed your solution with the script in the repository, the connection string is the value of
in the file.
You can also find the connection string using the Azure portal. In the IoT Hub resource in the resource group of
your deployment, locate the connection string settings.
Which IoT Hub devices does the Connected factory simulation use?
The simulation self registers the following devices:
proxy.beijing.corp.contoso
proxy.capetown.corp.contoso
proxy.mumbai.corp.contoso
proxy.munich0.corp.contoso
proxy.rio.corp.contoso
proxy.seattle.corp.contoso
publisher.beijing.corp.contoso
publisher.capetown.corp.contoso
publisher.mumbai.corp.contoso
publisher.munich0.corp.contoso
publisher.rio.corp.contoso
publisher.seattle.corp.contoso
Using the DeviceExplorer or the IoT extension for Azure CLI 2.0 tool, you can check which devices are registered
with the IoT hub your solution is using. To use device explorer, you need the connection string for the IoT hub in
your deployment. To use the IoT extension for Azure CLI 2.0, you need your IoT Hub name.
How can I get log data from the simulation components?
All components in the simulation log information in to log files. These files can be found in the VM in the folder
. To retrieve the logs, you can use the PowerShell script
in the repository.
This script needs to sign in to the VM. You may need to provide credentials for the sign-in. See How do I sign in
to the simulation VM? to find the credentials.
The script adds/removes a public IP address to the VM, if it does not yet have one and removes it. The script puts
all log files in an archive and downloads the archive to your development workstation.
Alternatively log in to the VM via SSH and inspect the log files at runtime.
How can I check if the simulation is sending data to the cloud?
With the DeviceExplorer or the iothub-explorer tool, you can inspect the data sent to IoT Hub from certain
devices. To use these tools, you need to know the connection string for the IoT hub in your deployment. See How
do I find out the connection string of the IoT hub used by my solution?
Inspect the data sent by one of the publisher devices:
publisher.beijing.corp.contoso
publisher.capetown.corp.contoso
publisher.mumbai.corp.contoso
publisher.munich0.corp.contoso
publisher.rio.corp.contoso
publisher.seattle.corp.contoso
If you see no data sent to IoT Hub, then there is an issue with the simulation. As a first analysis step you should
analyze the log files of the simulation components. See How can I get log data from the simulation components?
Next, try to stop and start the simulation and if there's still no data sent, update the simulation completely. See
How do I update the simulation in the VM?
How do I enable an interactive map in my Connected factory solution?
To enable an interactive map in your Connected factory solution, you must have an existing Bing Maps API for
Enterprise plan.
When deploying from www.azureiotsuite.com, the deployment process verifies that your subscription has an
enabled Bing Maps API for Enterprise plan and automatically deploys an interactive map into Connected factory.
If this is not the case, you can still enable an interactive map in your deployment as follows:
When you deploy using the script in the Connected factory GitHub repository and you have a Bing
Maps API for Enterprise plan, set the environment variable in the build window to the query
key of your plan. The interactive map is then enabled automatically.
If you don't have a Bing Maps API for Enterprise plan, deploy the Connected factory solution from
www.azureiotsuite.com or using the script. Then add a Bing Maps API for Enterprise plan to your
subscription as explained in How do I create a Bing Maps API for Enterprise account?. Look up the query key of
this account as explained in How to obtain your Bing Maps API for Enterprise QueryKey and save this key.
Navigate to the Azure portal and access the App Service resource in your Connected factory deployment.
Navigate to , where you find a section . Set the to the
query key you obtained. Save the settings and then navigate to and restart the App Service.
How do I create a Bing Maps API for Enterprise account
You can get a free Internal Transactions Level 1 Bing Maps for Enterprise plan. However, you can only add two of
these plans to an Azure subscription. If you don't have a Bing Maps API for Enterprise account, create one in the
Azure portal by clicking . Then search for and follow the
prompts to create it.

How to obtain your Bing Maps API for Enterprise QueryKey

Once you have created your Bing Maps API for Enterprise plan, add a Bing Maps for Enterprise resource to the
resource group of your Connected factory solution in the Azure portal.
1. In the Azure portal, navigate to the resource group that contains your Bing Maps API for Enterprise plan.
2. Click , then .
3. There are two keys: and . Copy the value.
4. To have the key picked up by the script, set the environment variable in
 your PowerShell environment to the of your plan. The build script then automatically adds the
value to the settings of the App Service.
5. Run a local or cloud deployment using the script.
How do enable the interactive map while debugging locally?
To enable the interactive map while you are debugging locally, set the value of the setting in the
files and in the root of your deployment to the value of the
you copied previously.
How do I use a different image at the home page of my dashboard?
To change the static image shown io the home page of the dashboard, replace the image
. Then rebuild and redeploy the WebApp.
How do I use non OPC UA devices with Connected factory?
To send telemetry data from non OPC UA devices to Connected factory:
1. Configure a new station in the Connected factory topology in the file.
2. Ingest the telemetry data in Connected factory compatible JSON format:

3. The format of is:

4. Restart the Connected factory App Service.
Next steps
You can also explore some of the other features and capabilities of the IoT Suite preconfigured solutions:
Predictive maintenance preconfigured solution overview
Connected factory preconfigured solution overview
IoT security from the ground up