Quickstart: Deploy your first IoT Edge module to a Linux x64 device

Azure IoT Edge moves the power of the cloud to your Internet of Things devices. In this quickstart, learn how to use the cloud interface to deploy prebuilt code remotely to an IoT Edge device.

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.

Quickstart architecture

This quickstart turns your Linux computer or virtual machine into an IoT Edge device. Then you can deploy a module from the Azure portal to your device. 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.

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 Linux device or virtual machine to act as your IoT Edge device. If you want to create a virtual machine in Azure, use the following command to get started quickly:

    az vm create --resource-group IoTEdgeResources --name EdgeVM --image Canonical:UbuntuServer:16.04-LTS:latest --admin-username azureuser --generate-ssh-keys --size Standard_B1ms
    

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 --hub-name {hub_name} --device-id myEdgeDevice --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 and start the Azure IoT Edge runtime on your IoT Edge device. 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 configuration, you provide 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.

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

Register your device to use the software repository

The packages that you need to run the IoT Edge runtime are managed in a software repository. Configure your IoT Edge device to access this repository.

The steps in this section are for devices running Ubuntu 16.04. To access the software repository on other versions of Linux, see Install the Azure IoT Edge runtime on Linux (x64) or Install Azure IoT Edge runtime on Linux (ARM32v7/armhf).

  1. On the machine that you're using as an IoT Edge device, install the repository configuration.

    curl https://packages.microsoft.com/config/ubuntu/16.04/prod.list > ./microsoft-prod.list
    sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
    
  2. Install a public key to access the repository.

    curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
    sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/
    

Install a container runtime

The IoT Edge runtime is a set of containers, and the logic that you deploy to your IoT Edge device is packaged as containers. Prepare your device for these components by installing a container runtime.

  1. Update apt-get.

    sudo apt-get update
    
  2. Install Moby, a container runtime.

    sudo apt-get install moby-engine
    
  3. Install the CLI commands for Moby.

    sudo apt-get install moby-cli
    

Install and configure the IoT Edge security daemon

The security daemon installs as a system service so that the IoT Edge runtime starts every time your device boots. The installation also includes a version of hsmlib that allows the security daemon to interact with the device's hardware security.

  1. Download and install the IoT Edge Security Daemon.

    sudo apt-get update
    sudo apt-get install iotedge
    
  2. Open the IoT Edge configuration file. It is a protected file so you may have to use elevated privileges to access it.

    sudo nano /etc/iotedge/config.yaml
    
  3. Add the IoT Edge device connection string. Find the variable device_connection_string and update its value with the string that you copied after registering your device. This connection string associates your physical device with the device identity that you created in Azure.

  4. Save and close the file.

    CTRL + X, Y, Enter

  5. Restart the IoT Edge security daemon to apply your changes.

    sudo systemctl restart iotedge
    

Tip

You need elevated privileges to run iotedge commands. Once you sign out of your machine and sign back in the first time after installing the IoT Edge runtime, your permissions are automatically updated. Until then, use sudo in front of the commands.

View the IoT Edge runtime status

Verify that the runtime was successfully installed and configured.

  1. Check to see that the Edge Security Daemon is running as a system service.

    sudo systemctl status iotedge
    

    See the Edge Daemon running as a system service

  2. If you need to troubleshoot the service, retrieve the service logs.

    journalctl -u iotedge
    
  3. View the modules running on your device.

    sudo 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.

Open the command prompt on your IoT Edge device again. Confirm that the module deployed from the cloud is running on your IoT Edge device:

sudo iotedge list

View three modules on your device

View the messages being sent from the tempSensor module:

sudo iotedge logs tempSensor -f 

After a logoff and login, sudo is not required for the above command.

View the data from your module

The temperature sensor module may be waiting to connect to Edge Hub if the last line you see in the log is Using transport Mqtt_Tcp_Only. Try killing the module and letting the Edge Agent restart it. You can kill it with the command sudo docker stop tempSensor.

You can also view the telemetry as it arrives 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. 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 want to remove the installations from your device, use the following commands.

Remove the IoT Edge runtime.

sudo apt-get remove --purge iotedge

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

sudo 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.

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

Remove the container runtime.

sudo apt-get remove --purge moby-cli
sudo apt-get remove --purge moby-engine

Next steps

This quickstart is the prerequisite for all of the IoT Edge tutorials. You can 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.