Quickstart: Deploy your first IoT Edge module to a virtual Windows device

Try out Azure IoT Edge in this quickstart by deploying containerized code to a virtual Windows IoT Edge device. IoT Edge allows you to remotely manage code on your devices so that you can send more of your workloads to the edge. For this quickstart, we recommend using an Azure virtual machine for your IoT Edge device. Using a virtual machine allows you to quickly create a test machine, install the prerequisites, and then delete it when you're finished.

In this quickstart you learn how to:

  • Create an IoT hub.
  • Register an IoT Edge device to your IoT hub.
  • Install and start the IoT Edge runtime on your virtual device.
  • Remotely deploy a module to an IoT Edge device and send telemetry to IoT Hub.

Diagram - Quickstart architecture for device and cloud

This quickstart walks you through creating a Windows virtual machine and configuring it to be an IoT Edge device. Then, you deploy a module from the Azure portal to your device. The module used 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 additional modules that analyze the simulated data for business insights.

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

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

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

Add the Azure IoT extension to the Cloud Shell instance.

az extension add --name azure-iot


This article uses the newest version of the Azure IoT extension, called azure-iot. The legacy version is called azure-cli-iot-ext.You should only have one version installed at a time. You can use the command az extension list to validate the currently installed extensions.

Use az extension remove --name azure-cli-iot-ext to remove the legacy version of the extension.

Use az extension add --name azure-iot to add the new version of the extension.

To see what extensions you have installed, use az extension list.


Cloud resources:

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

    az group create --name IoTEdgeResources --location westus2

IoT Edge device:

  • A Windows virtual machine to act as your IoT Edge device. You can create this virtual machine using the following command, replacing {password} with a secure password:

    az vm create --resource-group IoTEdgeResources --name EdgeVM --image MicrosoftWindowsDesktop:Windows-10:rs5-pro:latest --admin-username azureuser --admin-password {password} --size Standard_DS1_v2

    It may take a few minutes to create and start the new virtual machine. You can then download an RDP file for use when connecting to your virtual machine:

    1. Navigate to your new Windows virtual machine in the Azure portal.
    2. Select Connect.
    3. On the RDP tab, select Download RDP File.

    Open this file with Remote Desktop Connection to connect to your Windows virtual machine using the administrator name and password you specified with the az vm create command.


This quickstart uses a Windows desktop virtual machine for simplicity. For information about which Windows operating systems are generally available for production scenarios, see Azure IoT Edge supported systems.

If you're ready to configure your own Windows device for IoT Edge, including devices running IoT Core, follow the steps in Install the Azure IoT Edge runtime on Windows.

Create an IoT hub

Start the quickstart by creating an 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 hub created, you can use that 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. It might take a few minutes to create an IoT Hub.

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

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 --edge-enabled --hub-name {hub_name}

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

  2. View the connection string for your device, which links your physical device with its identity in IoT Hub. It contains the name of your IoT hub, the name of your device, and then a shared key that authenticates connections between the two.

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

    Retrieve connection string from CLI output

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 IoT Edge device boots and bootstraps the device by starting the IoT Edge agent. The IoT Edge agent manages deployment and monitoring of modules on the IoT Edge device, including the IoT Edge hub. The IoT Edge hub handles communications between modules on the IoT Edge device, and between the device and IoT Hub.

The installation script also includes a container engine called Moby that manages the container images on your IoT Edge device.

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.

Connect to your IoT Edge device

The steps in this section all take place on your IoT Edge device, so you want to connect to that virtual machine now via remote desktop.

Install and configure 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. If you haven't already, follow the steps in Register a new Azure IoT Edge device to register your device and retrieve the device connection string.

  2. In the virtual machine, run PowerShell as an administrator.


    Use an AMD64 session of PowerShell to install IoT Edge, not PowerShell (x86). If you're not sure which session type you're using, run the following command:

    (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
  3. The Deploy-IoTEdge command checks that your Windows machine is on a supported version, turns on the containers feature, downloads the Moby runtime, and then downloads the IoT Edge runtime.

    . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; `
    Deploy-IoTEdge -ContainerOs Windows
  4. Your machine may restart automatically. If you are prompted by the Deploy-IoTEdge command to reboot, do so now.

  5. Run PowerShell as an administrator again.

  6. The Initialize-IoTEdge command configures the IoT Edge runtime on your machine. The command defaults to manual provisioning with Windows containers.

    . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; `
    Initialize-IoTEdge -ContainerOs Windows
  7. 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. It may take a few minutes for the installation to complete and the IoT Edge agent module to start.

  1. Check the status of the IoT Edge service.

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

    . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog
  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 sends 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 code to your IoT Edge devices from the cloud. IoT Edge modules are executable packages implemented as containers. In this section, you deploy a pre-built module from the IoT Edge Modules section of the Azure Marketplace directly from your Azure IoT Hub.

The module that you deploy in this section simulates a sensor and sends generated data. This module is a useful piece of code when you're getting started with IoT Edge because you can use the simulated data for development and testing. If you want to see exactly what this module does, you can view the simulated temperature sensor source code.

To deploy your first module from the Azure Marketplace, use the following steps:

  1. Sign in to the Azure portal and navigate to your IoT hub.

  2. From the menu on the left pane, under Automatic Device Management, select IoT Edge.

  3. Click on the device ID of the target device from the list of devices.

  4. On the upper bar, select Set Modules.

    Select Set Modules from the device details page

  5. In the IoT Edge Modules section of the page, click Add and select Marketplace Module from the drop-down menu.

    Add marketplace module

  6. In the IoT Edge Module Marketplace, search for "Simulated Temperature Sensor" and select that module.

  7. Notice that the SimulatedTemperatureSensor module is added to the IoT Edge Modules section, with the desired status running.

    Select Next: Routes to continue to the next step of the wizard.

    Move to the next step once the temperature sensor module is listed

  8. On the Routes tab of the wizard, you can define how messages are passed between modules and the IoT Hub. Routes are constructed using name/value pairs. You should see two routes on this page. The default route called route sends all messages to IoT Hub (which is called $upstream). A second route called SimulatedTemperatureSensorToIoTHub was created automatically when you added the module from the Marketplace. This route sends all messages specifically from the simulated temperature module to IoT Hub. You can delete the default route because it's redundant in this case.

    Select Next: Review + create to continue to the next step of the wizard.

    Delete the default route then move to the next step

  9. On the Review + create tab of the wizard, you can preview the JSON file that defines all the modules that get deployed to your IoT Edge device. Notice that the SimulatedTemperatureSensor module is included as well as the two runtime modules, edgeAgent and edgeHub. Select Create when you're done reviewing.

    When you submit a new deployment to an IoT Edge device, nothing is pushed to your device. Instead, the device queries IoT Hub regularly for any new instructions. If the device finds an updated deployment manifest, it uses the information about the new deployment to pull the module images from the cloud then starts running the modules locally. This process may take a few minutes.

  10. After you create the module deployment details, the wizard returns you to the device details page. On the device details page, view the deployment status in the Modules tab. Three modules should be listed: $edgeAgent, $edgeHub, and SimulatedTemperatureSensor. If one or more of the modules are listed as specified in deployment but not reported by device, your IoT Edge device is still starting them. Wait a few moments and select Refresh at the top of the page.

    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 deploy 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 generates sample environment data that you can use for testing later. The simulated sensor is monitoring both a machine and the environment around the machine. For example, this sensor might be in a server room, on a factory floor, or on a wind turbine. The message includes ambient temperature and humidity, machine temperature and pressure, and a timestamp. The IoT Edge tutorials use the data created by this module as test data for analytics.

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 temperature sensor module to the cloud.

iotedge logs SimulatedTemperatureSensor -f


IoT Edge commands are case-sensitive when referring to module names.

View the data from your module

You can also watch the messages arrive at your IoT hub by using the Azure IoT Hub 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 to avoid charges.

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.


Deleting a resource group is irreversible.

Remove the IoTEdgeResources group. It might take a few minutes to delete a resource group.

az group delete --name IoTEdgeResources

You can confirm the resource group is removed by viewing the list of resource groups.

az group list

Next steps

In this quickstart, you created an 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.

The next step is to set up your local development environment so that you can start creating IoT Edge modules that run your business logic.