Install Azure IoT Edge runtime on Linux (ARM32v7/armhf)

The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices as small as a Raspberry Pi or as large as an industrial server. Once a device is configured with the IoT Edge runtime, you can start deploying business logic to it from the cloud.

To learn more about how the IoT Edge runtime works and what components are included, see Understand the Azure IoT Edge runtime and its architecture.

This article lists the steps to install the Azure IoT Edge runtime on a Linux ARM32v7/armhf IoT Edge device. For example, these steps would work for Raspberry Pi devices. For a list of supported ARM32 operating systems, see Azure IoT Edge supported systems.

Note

Packages in the Linux software repositories are subject to the license terms located in each package (/usr/share/doc/package-name). Read the license terms prior to using the package. Your installation and use of the package constitutes your acceptance of these terms. If you do not agree with the license terms, do not use the package.

Install the latest version

Use the following sections to install the most recent version of the Azure IoT Edge service onto your Linux ARM devices.

Install the container runtime

Azure IoT Edge relies on an OCI-compatible container runtime. For production scenarios, it is highly recommended you use the Moby-based engine provided below. It is the only container engine officially supported with Azure IoT Edge. Docker CE/EE container images are compatible with the Moby-based runtime.

The following commands install both the Moby-based engine and command-line interface (CLI). The CLI is useful for development but optional for production deployments.

# You can copy the entire text from this code block and 
# paste in terminal. The comment lines will be ignored.

# Download and install the moby-engine
curl -L https://aka.ms/moby-engine-armhf-latest -o moby_engine.deb && sudo dpkg -i ./moby_engine.deb

# Download and install the moby-cli
curl -L https://aka.ms/moby-cli-armhf-latest -o moby_cli.deb && sudo dpkg -i ./moby_cli.deb

# Run apt-get fix
sudo apt-get install -f

Install the IoT Edge Security Daemon

The IoT Edge security daemon provides and maintains security standards on the IoT Edge device. The daemon starts on every boot and bootstraps the device by starting the rest of the IoT Edge runtime.

# You can copy the entire text from this code block and 
# paste in terminal. The comment lines will be ignored.

# Download and install the standard libiothsm implementation
curl -L https://aka.ms/libiothsm-std-linux-armhf-latest -o libiothsm-std.deb && sudo dpkg -i ./libiothsm-std.deb

# Download and install the IoT Edge Security Daemon
curl -L https://aka.ms/iotedged-linux-armhf-latest -o iotedge.deb && sudo dpkg -i ./iotedge.deb

# Run apt-get fix
sudo apt-get install -f

Once IoT Edge is successfully installed, the output will prompt you to update the configuration file. Follow the steps in the Configure the Azure IoT Edge security daemon section to finish provisioning your device.

Install a specific version

If you want to install a specific version of Azure IoT Edge, you can target the component files directly from the IoT Edge GitHub repository. Use the same curl commands listed in the previous sections to get all of the IoT Edge components onto your device: the Moby engine and CLI, the libiothsm, and finally the IoT Edge security daemon. The only difference is that you replace the aka.ms URLs with links directly pointing to the version of each component that you want to use.

Navigate to the Azure IoT Edge releases, and find the release version that you want to target. Expand the Assets section for the version, and choose the files that match your IoT Edge device's architecture. Every IoT Edge release contains iotedge and libiothsm files. Not all releases include moby-engine or moby-cli. If you don't already have the Moby container engine installed, look through the older releases until you find one that includes the Moby components.

Once IoT Edge is successfully installed, the output will prompt you to update the configuration file. Follow the steps in the next section to finish provisioning your device.

Configure the Azure IoT Edge security daemon

Configure the IoT Edge runtime to link your physical device with a device identity that exists in an Azure IoT hub.

The daemon can be configured using the configuration file at /etc/iotedge/config.yaml. The file is write-protected by default, so you might need elevated permissions to edit it.

A single IoT Edge device can be provisioned manually using a device connections string provided by IoT Hub. Or, you can use the Device Provisioning Service to automatically provision devices, which is helpful when you have many devices to provision. Depending on your provisioning choice, choose the appropriate installation script.

Option 1: Manual provisioning

To manually provision a device, you need to provide it with a device connection string that you can create by registering a new IoT Edge device in your IoT hub.

Open the configuration file.

sudo nano /etc/iotedge/config.yaml

Find the provisioning configurations of the file and uncomment the Manual provisioning configuration section. Update the value of device_connection_string with the connection string from your IoT Edge device. Make sure any other provisioning sections are commented out.

# Manual provisioning configuration
provisioning:
  source: "manual"
  device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
  
# DPS TPM provisioning configuration
# provisioning:
#   source: "dps"
#   global_endpoint: "https://global.azure-devices-provisioning.net"
#   scope_id: "{scope_id}"
#   attestation:
#     method: "tpm"
#     registration_id: "{registration_id}"

Save and close the file.

CTRL + X, Y, Enter

After entering the provisioning information in the configuration file, restart the daemon:

sudo systemctl restart iotedge

Option 2: Automatic provisioning

To automatically provision a device, set up Device Provisioning Service and retrieve your device registration ID. There are a number of attestation mechanisms supported by IoT Edge when using automatic provisioning but your hardware requirements also impact your choices. For example, Raspberry Pi devices do not come with a Trusted Platform Module (TPM) chip by default.

Open the configuration file.

sudo nano /etc/iotedge/config.yaml

Find the provisioning configurations of the file and uncomment the section appropriate for your attestation mechanism. When using TPM attestation, for example, update the values of scope_id and registration_id with the values from your IoT Hub Device Provisioning service and your IoT Edge device with TPM, respectively.

   # Manual provisioning configuration
   # provisioning:
   #   source: "manual"
   #   device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
  
   # DPS TPM provisioning configuration
   provisioning:
     source: "dps"
     global_endpoint: "https://global.azure-devices-provisioning.net"
     scope_id: "{scope_id}"
     attestation:
       method: "tpm"
       registration_id: "{registration_id}"

Save and close the file.

CTRL + X, Y, Enter

After entering the provisioning information in the configuration file, restart the daemon:

sudo systemctl restart iotedge

Verify successful installation

If you used the manual configuration steps in the previous section, the IoT Edge runtime should be successfully provisioned and running on your device. Or, if you used the automatic configuration steps, then you need to complete some additional steps so that the runtime can register your device with your IoT hub on your behalf. For next steps, see Create and provision a simulated TPM IoT Edge device on a Linux virtual machine.

You can check the status of the IoT Edge Daemon using:

systemctl status iotedge

Examine daemon logs using:

journalctl -u iotedge --no-pager --no-full

And, list running modules with:

sudo iotedge list

Tips and suggestions

You need elevated privileges to run iotedge commands. After installing the runtime, sign out of your machine and sign back in to update your permissions automatically. Until then, use sudo in front of any iotedge the commands.

On resource constrained devices, it is highly recommended that you set the OptimizeForPerformance environment variable to false as per instructions in the troubleshooting guide.

If your network that has a proxy server, follow the steps in Configure your IoT Edge device to communicate through a proxy server.

Uninstall IoT Edge

If you want to remove the IoT Edge installation from your Linux device, use the following commands from the command line.

Remove the IoT Edge runtime.

sudo apt-get remove --purge iotedge

When the IoT Edge runtime is removed, the container that it created are stopped but still exist on your device. View all containers to see which ones remain.

sudo docker ps -a

Delete the containers from your device, including the two runtime containers.

sudo docker rm -f <container name>

Finally, remove the container runtime from your device.

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

Next steps

Now that you have an IoT Edge device provisioned with the runtime installed, you can deploy IoT Edge modules.

If you are having problems with the IoT Edge runtime installing properly, refer to the troubleshooting page.

To update an existing installation to the newest version of IoT Edge, see Update the IoT Edge security daemon and runtime.