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.

Tutorial architecture

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.

Note

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

Prerequisites

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 virtual machine, enable nested virtualization and allocate at least 2GB memory.
  • Install Docker for Windows and make sure it's running.

Create an IoT hub

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

Create IoT Hub

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.

Register an IoT Edge device

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

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, you declare this to be an IoT Edge device from the beginning.

  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
    
  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. Register a 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.

Complete the following steps in the Windows machine or VM that you prepared to function as an IoT Edge device.

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. Register a 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, you deploy a module that generates telemetry for your simulated device.

  1. In the Azure portal, navigate to your IoT hub.
  2. Go to IoT Edge and select your IoT Edge device.
  3. Select Set Modules.
  4. In the Deployment Modules section of the page, click Add then select IoT Edge Module.
  5. In the Name field, enter tempSensor.
  6. In the Image URI field, enter mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0.
  7. Leave the other settings unchanged, and select Save.

    Save IoT Edge module after entering name and image URI

  8. Back in the Add modules step, select Next.

  9. In the Specify routes step, you should have a default route that sends all messages from all modules to IoT Hub. If not, add the following code then select Next.

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

  11. 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 tempSensor module listed.

    View tempSensor 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 view the messages that are received by 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. If there's anything in that resource group that you want to keep, then just delete the individual resources that you want to clean up.

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; `
Uninstall-SecurityDaemon

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.