Quickstart: Deploy your first IoT Edge module to a Linux or Mac device - preview

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

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


This quickstart uses your computer or virtual machine like an Internet of Things device. To turn your machine into an IoT Edge device, the following services are required:

  • Python pip, to install the IoT Edge runtime.

    • Linux: sudo apt-get install python-pip.


      On certain distributions (such as Raspbian), you might also need to upgrade certain pip packages and install additional dependencies:

      sudo pip install --upgrade setuptools pip
      sudo apt-get install python2.7-dev libffi-dev libssl-dev
    • MacOS: sudo easy_install pip.

  • Docker, to run the IoT Edge modules

Create an IoT hub with Azure CLI

Create an IoT hub in your Azure subscription. 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 skip this section and go on to Register an IoT Edge device. Each subscription can only have one free IoT hub.

  1. Sign in to the Azure portal.
  2. Select the Cloud Shell button.

    Cloud Shell button

  3. Create a resource group. The following code creates a resource group called IoTEdge in the West US region:

    az group create --name IoTEdge --location westus
  4. Create an IoT hub in your new resource group. The following code creates a free F1 hub called MyIotHub in the resource group IoTEdge:

    az iot hub create --resource-group IoTEdge --name MyIotHub --sku F1 

Register an IoT Edge device

Create a device identity for your simulated device so that it can communicate with your IoT hub. 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 portal, navigate to your IoT hub.
  2. Select IoT Edge (preview).
  3. Select Add IoT Edge device.
  4. Give your simulated device a unique device ID.
  5. Select Save to add your device.
  6. Select your new device from the list of devices.
  7. Copy the value for Connection string--primary key 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

The IoT Edge runtime is deployed on all IoT Edge devices. It comprises two modules. First, the IoT Edge agent facilitates deployment and monitoring of modules on the IoT Edge device. Second, the IoT Edge hub manages communications between modules on the IoT Edge device, and between the device and IoT Hub.

On the machine where you'll run the IoT Edge device, download the IoT Edge control script:

sudo pip install -U azure-iot-edge-runtime-ctl

Configure the runtime with your IoT Edge device connection string from the previous section:

sudo iotedgectl setup --connection-string "{device connection string}" --nopass

Start the runtime:

sudo iotedgectl start

Check Docker to see that the IoT Edge agent is running as a module:

sudo docker ps

See edgeAgent in Docker

Deploy a module

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 (preview) and select your IoT Edge device.
  3. Select Set Modules.
  4. Select Add IoT Edge Module.
  5. In the Name field, enter tempSensor.
  6. In the Image URI field, enter microsoft/azureiotedge-simulated-temperature-sensor:1.0-preview.
  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, select Next.
  10. In the Review template step, select Submit.
  11. Return to the device details page and select Refresh. You should see the new tempSensor module running along the IoT Edge runtime.

    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 the computer running your simulated device again. Confirm that the module deployed from the cloud is running on your IoT Edge device:

sudo docker ps

View three modules on your device

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

sudo docker logs -f tempSensor

View the data from your module

You can also view the telemetry the device is sending by using the IoT Hub explorer tool.

Clean up resources

If you want to remove the simulated device that you created, along with the Docker containers that were started for each module, use the following command:

sudo iotedgectl uninstall

When you no longer need the IoT Hub you created, you can use the az iot hub delete command to remove the resource and any devices associated with it:

az iot hub delete --name {your iot hub name} --resource-group {your resource group name}

Next steps

You learned how to deploy an IoT Edge module to an IoT Edge device. Now try deploying different types of Azure services as modules, so that you can analyze data at the edge.