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

Artikkeli
07/08/2024

Applies to: IoT Edge 1.5 IoT Edge 1.4

Important

IoT Edge 1.5 LTS and IoT Edge 1.4 LTS are supported releases. IoT Edge 1.4 LTS is end of life on November 12, 2024. If you are on an earlier release, see Update IoT Edge.

Try out Azure IoT Edge in this quickstart by deploying containerized code to a Linux on 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 your own Windows Client device to see how easy it is to use Azure IoT Edge for Linux on Windows. If you wish to use Windows Server or an Azure VM to create your deployment, follow the steps in the how-to guide on installing and provisioning Azure IoT Edge for Linux on a Windows device.

In this quickstart, you'll learn how to:

Create an IoT hub.
Register an IoT Edge device to your IoT hub.
Install and start the IoT Edge for Linux on Windows runtime on your device.
Remotely deploy a module to an IoT Edge device and send telemetry.

Diagram that shows the architecture of this quickstart for your device and cloud.

This quickstart walks you through how to set up your Azure IoT Edge for Linux on Windows device. Then, you'll deploy a module from the Azure portal to your device. The module you'll use is a simulated sensor that generates temperature, humidity, and pressure data. Other Azure IoT Edge tutorials build on the work you do here by deploying 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.

Prerequisites

Prepare your environment for the Azure CLI.

Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
- If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
- When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
- Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Create a cloud resource group to manage all the resources you'll use in this quickstart.

az group create --name IoTEdgeResources --location westus2

Make sure your IoT Edge device meets the following requirements:

System Requirements
- Windows 10¹/11 (Pro, Enterprise, IoT Enterprise) _{¹ Windows 10 minimum build 17763 with all current cumulative updates installed.}
Hardware requirements
- Minimum Free Memory: 1 GB
- Minimum Free Disk Space: 10 GB

Create an IoT hub

Start by creating an IoT hub with the Azure CLI.

Diagram that shows the step to create an I o T hub.

The free level of Azure 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 you already have one free hub in your subscription, change the SKU to S1. If you get an error that the IoT hub name isn't available, someone else already has a hub with that name. Try a new name.

Register an IoT Edge device

Diagram that shows the step to register a device with an I o T 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.

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

In 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 Cloud Shell is running the latest version of the Azure IoT extension.
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 a shared key that authenticates connections between the two.
```
az iot hub device-identity connection-string show --device-id myEdgeDevice --hub-name {hub_name}
```
Copy the value of the connectionString key from the JSON output and save it. This value is the device connection string. You'll use it to configure the IoT Edge runtime in the next section.

For example, your connection string should look similar to HostName=contoso-hub.azure-devices.net;DeviceId=myEdgeDevice;SharedAccessKey=<DEVICE_SHARED_ACCESS_KEY>.

Install and start the IoT Edge runtime

Install IoT Edge for Linux on Windows on your device, and configure it with the device connection string.

Diagram that shows the step to start the I o T Edge runtime.

Run the following PowerShell commands on the target device where you want to deploy Azure IoT Edge for Linux on Windows. To deploy to a remote target device using PowerShell, use Remote PowerShell to establish a connection to a remote device and run these commands remotely on that device.

In an elevated PowerShell session, run the following command to enable Hyper-V. For more information, check Hyper-V on Windows 10.
```
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
```

In an elevated PowerShell session, run each of the following commands to download IoT Edge for Linux on Windows.

X64/AMD64

$msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_X64" -OutFile $msiPath

ARM64

$msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_ARM64" -OutFile $msiPath

Install IoT Edge for Linux on Windows on your device.

Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn"

Set the execution policy on the target device to AllSigned if it is not already. You can check the current execution policy in an elevated PowerShell prompt using:
```
Get-ExecutionPolicy -List
```
If the execution policy of local machine is not AllSigned, you can set the execution policy using:
```
Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force
```
Create the IoT Edge for Linux on Windows deployment.
```
Deploy-Eflow
```
Enter 'Y' to accept the license terms.
Enter 'O' or 'R' to toggle Optional diagnostic data on or off, depending on your preference. A successful deployment is pictured below.
Provision your device using the device connection string that you retrieved in the previous section. Replace the placeholder text with your own value.
```
Provision-EflowVm -provisioningType ManualConnectionString -devConnString "<CONNECTION_STRING_HERE>"
```

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 that shows the step to deploy a module.

One of the key capabilities of Azure IoT Edge is deploying code to your IoT Edge devices from the cloud. IoT Edge modules are executable packages implemented as containers. In this section, you'll deploy a pre-built module from the IoT Edge Modules section of Microsoft Artifact Registry.

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.

Follow these steps to deploy your first module.

Sign in to the Azure portal and go to your IoT Hub.
From the menu on the left, select Devices under the Device management menu.
Select the device ID of the target device from the list of devices.

Note

When you create a new IoT Edge device, it will display the status code 417 -- The device's deployment configuration is not set in the Azure portal. This status is normal, and means that the device is ready to receive a module deployment.
On the upper bar, select Set Modules.

Choose which modules you want to run on your device. You can choose from modules that you've already created, modules from Microsoft Artifact Registry, or modules that you've built yourself. In this quickstart, you'll deploy a module from the Microsoft Artifact Registry.
In the IoT Edge modules section, select Add then choose IoT Edge Module.
Update the following module settings:

Setting Value

IoT Module name SimulatedTemperatureSensor

Image URI mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:latest

Restart policy always

Desired status running
Select Next: Routes to continue to configure routes.
Add a route that sends all messages from the simulated temperature module to IoT Hub.

Setting Value

Name SimulatedTemperatureSensorToIoTHub

Value FROM /messages/modules/SimulatedTemperatureSensor/* INTO $upstream
Select Next: Review + create.
Review the JSON file, and then select Create. The JSON file defines all of the modules that you deploy to your IoT Edge device.

Note

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 can take a few minutes.

Setting	Value
IoT Module name	`SimulatedTemperatureSensor`
Image URI	`mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:latest`
Restart policy	always
Desired status	running

Setting	Value
Name	`SimulatedTemperatureSensorToIoTHub`
Value	`FROM /messages/modules/SimulatedTemperatureSensor/* INTO $upstream`

After you create the module deployment details, the wizard returns you to the device details page. View the deployment status on the Modules tab.

You should see three modules: $edgeAgent, $edgeHub, and SimulatedTemperatureSensor. If one or more of the modules has Yes under Specified in Deployment but not under Reported by Device, your IoT Edge device is still starting them. Wait a few minutes, and then refresh the page.

If you have issues deploying modules, see Troubleshoot IoT Edge devices from the Azure portal.

View the 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.

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 messages that it sends include ambient temperature and humidity, machine temperature and pressure, and a timestamp. IoT Edge tutorials use the data created by this module as test data for analytics.

Log in to your IoT Edge for Linux on Windows virtual machine using the following command in your PowerShell session:
```
Connect-EflowVm
```
Note

The only account allowed to SSH to the virtual machine is the user that created it.
Once you are logged in, you can check the list of running IoT Edge modules using the following Linux command:
```
sudo iotedge list
```
View the messages being sent from the temperature sensor module to the cloud using the following Linux command:
```
sudo iotedge logs SimulatedTemperatureSensor -f
```
Tip

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

Clean up resources

If you want to continue on to the IoT Edge tutorials, skip this step. 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. If you don't want to delete the whole group, you can delete individual resources instead.

Important

Check the contents of the resource group to make sure that there's nothing you want to keep. Deleting a resource group is irreversible.

Use the following command to remove the IoTEdgeResources group. Deletion might take a few minutes.

az group delete --name IoTEdgeResources

You can confirm that the resource group is removed by using this command to view the list of resource groups.

az group list

Uninstall IoT Edge for Linux on Windows

If you want to remove the Azure IoT Edge for Linux on Windows installation from your device, use the following commands.

Open Settings on Windows
Select Add or Remove Programs
Select Azure IoT Edge app
Select Uninstall

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.

In the next tutorial, you'll learn how to monitor the activity and health of your device from the Azure portal.

Monitor IoT Edge devices

Jaa