Quickstart: Deploy your first IoT Edge module from the Azure portal to a Windows device - preview

In this quickstart, use the Azure IoT Edge cloud interface to deploy prebuilt code remotely to an IoT Edge device. To accomplish this task, first use your Windows device to simulate an IoT Edge device, then you can deploy a module to it.

In this quickstart you learn how to:

  1. Create an IoT Hub.
  2. Register an IoT Edge device to your IoT hub.
  3. Install and start the IoT Edge runtime on your device.
  4. Remotely deploy a module to an IoT Edge device and send telemetry to IoT Hub.

Diagram - Quickstart architecture for device and cloud

The module that you deploy in this quickstart is a simulated sensor that generates temperature, humidity, and pressure data. The other Azure IoT Edge tutorials build upon the work you do here by deploying modules that analyze the simulated data for business insights.


The IoT Edge runtime on Windows is in public preview.

If you don't have an active Azure subscription, create a free account before you begin.

Open Azure Cloud Shell

Azure Cloud Shell is a free, interactive shell that you can use to run the steps in this article. Common Azure tools are preinstalled and configured in Cloud Shell for you to use with your account. Just select the Copy button to copy the code, paste it in Cloud Shell, and then press Enter to run it. There are a few ways to open Cloud Shell:

Select Try It in the upper-right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser. https://shell.azure.com/bash
Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal. Cloud Shell in the portal

You use the Azure CLI to complete many of the steps in this quickstart, and Azure IoT has an extension to enable additional functionality.

Add the Azure IoT extension to the cloud shell instance.

az extension add --name azure-cli-iot-ext


Cloud resources:

  • A resource group to manage all the resources you use in this quickstart.

    az group create --name IoTEdgeResources --location westus

IoT Edge device:

  • A Windows computer or virtual machine to act as your IoT Edge device. Use a supported Windows version:
    • Windows 10 or newer
    • Windows Server 2016 or newer
  • If it's a Windows computer, check that it meets the system requirements for Hyper-V.
  • If it's a virtual machine, enable nested virtualization and allocate at least 2 GB memory.
  • Install Docker for Windows and make sure it's running.


There is an option during Docker setup to use Windows containers or Linux containers. This quickstart describes how to configure the IoT Edge runtime for use with Linux containers.

Create an IoT hub

Start the quickstart by creating your IoT hub with Azure CLI.

Diagram - Create an IoT hub in the cloud

The free level of IoT Hub works for this quickstart. If you've used IoT Hub in the past and already have a free hub created, you can use that IoT hub. Each subscription can only have one free IoT hub.

The following code creates a free F1 hub in the resource group IoTEdgeResources. Replace {hub_name} with a unique name for your IoT hub.

az iot hub create --resource-group IoTEdgeResources --name {hub_name} --sku F1

If you get an error because there's already one free hub in your subscription, change the SKU to S1. If you get an error that the IoT Hub name isn't available, it means that someone else already has a hub with that name. Try a new name.

Register an IoT Edge device

Register an IoT Edge device with your newly created IoT Hub. Diagram - Register a device with an IoT Hub identity

Create a device identity for your simulated device so that it can communicate with your IoT hub. The device identity lives in the cloud, and you use a unique device connection string to associate a physical device to a device identity.

Since IoT Edge devices behave and can be managed differently than typical IoT devices, declare this identity to be for an IoT Edge device with the --edge-enabled flag.

  1. In the Azure cloud shell, enter the following command to create a device named myEdgeDevice in your hub.

    az iot hub device-identity create --device-id myEdgeDevice --hub-name {hub_name} --edge-enabled

    If you get an error about iothubowner policy keys, make sure that your cloud shell is running the latest version of the azure-cli-iot-ext extension.

  2. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub.

    az iot hub device-identity show-connection-string --device-id myEdgeDevice --hub-name {hub_name}
  3. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section.

Install and start the IoT Edge runtime

Install the Azure IoT Edge runtime on your IoT Edge device and configure it with a device connection string. Diagram - Start the runtime on device

The IoT Edge runtime is deployed on all IoT Edge devices. It has three components. The IoT Edge security daemon starts each time an Edge device boots and bootstraps the device by starting the IoT Edge agent. The IoT Edge agent facilitates deployment and monitoring of modules on the IoT Edge device, including the IoT Edge hub. The IoT Edge hub manages communications between modules on the IoT Edge device, and between the device and IoT Hub.

During the runtime installation, you're asked for a device connection string. Use the string that you retrieved from the Azure CLI. This string associates your physical device with the IoT Edge device identity in Azure.

The instructions in this section configure the IoT Edge runtime with Linux containers. If you want to use Windows containers, see Install Azure IoT Edge runtime on Windows to use with Windows containers.

Connect to your IoT Edge device

The steps in this section all take place on your IoT Edge device. If you're using your own machine as the IoT Edge device, you can skip this part. If you're using a virtual machine or secondary hardware, you want to connect to that machine now.

Download and install the IoT Edge service

Use PowerShell to download and install the IoT Edge runtime. Use the device connection string that you retrieved from IoT Hub to configure your device.

  1. On your IoT Edge device, run PowerShell as an administrator.

  2. Download and install the IoT Edge service on your device.

    . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; `
    Install-SecurityDaemon -Manual -ContainerOs Linux
  3. When prompted for a DeviceConnectionString, provide the string that you copied in the previous section. Don't include quotes around the connection string.

View the IoT Edge runtime status

Verify that the runtime was successfully installed and configured.

  1. Check the status of the IoT Edge service.

    Get-Service iotedge
  2. If you need to troubleshoot the service, retrieve the service logs.

    # Displays logs from today, newest at the bottom.
    Get-WinEvent -ea SilentlyContinue `
     -FilterHashtable @{ProviderName= "iotedged";
       LogName = "application"; StartTime = [datetime]::Today} |
     select TimeCreated, Message |
     sort-object @{Expression="TimeCreated";Descending=$false} |
     format-table -autosize -wrap
  3. View all the modules running on your IoT Edge device. Since the service just started for the first time, you should only see the edgeAgent module running. The edgeAgent module runs by default, and helps to install and start any additional modules that you deploy to your device.

    iotedge list

    View one module on your device

Your IoT Edge device is now configured. It's ready to run cloud-deployed modules.

Deploy a module

Manage your Azure IoT Edge device from the cloud to deploy a module that will send telemetry data to IoT Hub. Diagram - deploy module from cloud to device

One of the key capabilities of Azure IoT Edge is being able to deploy modules to your IoT Edge devices from the cloud. An IoT Edge module is an executable package implemented as a container. In this section, we'll be deploying a pre-built module from the IoT Edge Modules section of the Azure Marketplace. This module generates telemetry for your simulated device.

  1. In the Azure portal, enter Simulated Temperature Sensor into the search and open the Marketplace result.

    Simulated Temperature Sensor in Azure portal search

  2. In the Subscription field, select the subscription with the IoT Hub you're using, if it's not already.

  3. In the IoT Hub field, select the name of the IoT Hub you're using, if it's not already.

  4. Click on Find Device, select your IoT Edge device (named myEdgeDevice), then select Create.

  5. In the Add Modules step of the wizard, click on the SimulatedTemperatureSensor module to verify its configuration settings, click Save and select Next.

  6. In the Specify Routes step of the wizard, verify the routes are properly set up with the default route that sends all messages from all modules to IoT Hub ($upstream). If not, add the following code then select Next.

     "routes": {
         "route": "FROM /messages/* INTO $upstream"
  7. In the Review Deployment step of the wizard, select Submit.

  8. Return to the device details page and select Refresh. In addition to the edgeAgent module that was created when you first started the service, you should see another runtime module called edgeHub and the SimulatedTemperatureSensor module listed.

    It may take a few minutes for the new modules to show up. The IoT Edge device has to retrieve its new deployment information from the cloud, start the containers, and then report its new status back to IoT Hub.

    View SimulatedTemperatureSensor in list of deployed modules

View generated data

In this quickstart, you created a new IoT Edge device and installed the IoT Edge runtime on it. Then, you used the Azure portal to push an IoT Edge module to run on the device without having to make changes to the device itself. In this case, the module that you pushed creates environmental data that you can use for the tutorials.

Confirm that the module deployed from the cloud is running on your IoT Edge device.

iotedge list

View three modules on your device

View the messages being sent from the tempSensor module to the cloud.

iotedge logs tempSensor -f

View the data from your module

You can also watch the messages arrive at your IoT hub by using the Azure IoT Toolkit extension for Visual Studio Code.

Clean up resources

If you want to continue on to the IoT Edge tutorials, you can use the device that you registered and set up in this quickstart. Otherwise, you can delete the Azure resources that you created and remove the IoT Edge runtime from your device.

Delete Azure resources

If you created your virtual machine and IoT hub in a new resource group, you can delete that group and all the associated resources. Double check the contents of the resource group to make sure that there's nothing you want to keep. If you don't want to delete the whole group, you can delete individual resources instead.

Remove the IoTEdgeResources group.

az group delete --name IoTEdgeResources

Remove the IoT Edge runtime

If you plan on using the IoT Edge device for future testing, but want to stop the tempSensor module from sending data to your IoT hub while not in use, use the following command to stop the IoT Edge service.

Stop-Service iotedge -NoWait

You can restart the service when you're ready to start testing again

Start-Service iotedge

If you want to remove the installations from your device, use the following commands.

Remove the IoT Edge runtime.

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; `

When the IoT Edge runtime is removed, the containers that it created are stopped, but still exist on your device. View all containers.

docker ps -a

Delete the containers that were created on your device by the IoT Edge runtime. Change the name of the tempSensor container if you called it something different.

docker rm -f tempSensor
docker rm -f edgeHub
docker rm -f edgeAgent

Next steps

In this quickstart, you created a new IoT Edge device and used the Azure IoT Edge cloud interface to deploy code onto the device. Now, you have a test device generating raw data about its environment.

You are ready to continue on to any of the other tutorials to learn how Azure IoT Edge can help you turn this data into business insights at the edge.