Install the Azure* IoT Edge Runtime

ID 675443
Updated 1/12/2021
Version Latest
Public

author-image

By

This is part 1 of a 4-part series that shows you how to manage the Terasic DE10-Nano with Microsoft* Azure* IoT Edge and use container-based virtualization to reprogram the onboard FPGA from the Microsoft* Azure* Cloud. 

About this Tutorial

This tutorial covers the basic hardware and software set up for connecting the Intel® Cyclone® V SoC on the Terasic DE10-Nano to Microsoft* Azure* IoT Edge to manage the DE10-Nano along with other IoT devices in the cloud.

Objectives

In this tutorial, you will learn how to:

  • Prepare the DE10-Nano for use in Azure IoT Edge
  • Install Azure IoT Edge runtime on the DE10-Nano
  • Deploy a simulated temperature sensor to test Azure IoT Edge
  • Verify that the container works from the DE10-Nano and the cloud 

Prerequisites

In this tutorial you will need the following: 

  • Microsoft Azure account
  • Development PC with Linux* (Ubuntu 16.04 recommended)
  • Development PC must operate on a 64-bit architecture & contain 50GB free space (10GB for the Modules as well as 40GB additional free space for Intel® Quartus® software Installation)
  • Serial console application on your development PC such as minicom, screen, or PuTTY.
  • DE10-Nano Development Kit (You can purchase the kit from your local Intel® distributor or directly from Terasic)
  • microSD to SD memory card adapter and SD card reader if your system does not have a microSD card slot or SD card reader. Note: The kit comes with a 4GB microSD card. For better performance, you can purchase a card with a minimum of 8GB. 
  • Ethernet cable

It is helpful but not required to have experience with:

Optional

Hardware accessories for enabling the GUI

  • HDMI cable and compatible display
  • USB adapter (for type A to micro-B USB cable)
  • USB hub
  • USB keyboard
  • USB mouse

 

Step 1: Prepare the DE10-Nano

In this step, you will prepare the DE10-Nano for container virtualization, enabling you to maintain DE10-Nano applications on a cloud service such as Microsoft Azure.

Download the Image from Terasic

The bootable image from Terasic contains Ubuntu 16.04 with a Lightweight X11 Desktop Environment (or LXDE). You can use the Linux GUI, serial console, or ssh.

  1. On your development PC, download the Terasic SD Card Image.
  2. Extract the downloaded image: 
    cd ~/Downloads
unzip DE10-Nano-Cloud-Native.zip

Write the Image to a microSD Card

If your development PC does not have an SD card slot, use a microSD to SD memory card adapter and SD card reader to complete this step.

  1. Insert the microSD into your development PC and identify its device path with lsblk or fdisk -l.

    Input:

    lsblk

    Output:

     NAME              MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
 ...
 <Your Device Path>                 8:0    1  <card size>G  0 disk
 ...

  2. Using the dd command, write the image to the microSD card.
    Note: Take precautions to select the correct path. If you choose another device path, it may crash your development PC. Use status=progress to check the progress of the dd command.

    sudo dd if=DE10-Nano-Cloud-Native.img of=/dev/<your device path> status=progress

  3. See the Linux manual for more information on the dd command (recommended).

    man dd

    An excerpt of the manual:

    dd - convert and copy a file

if=FILE
      read from FILE instead of stdin

of=FILE
      write to FILE instead of stdout

status=LEVEL
        The  LEVEL of information to print to stderr; 
        'none' suppresses everything but error messages,
        'noxfer' suppresses the final transfer statistics,
        'progress' shows periodic transfer statistics

Set up MSEL Switches

The MSEL switches on DE10-Nano are used to configure the board. In this step, you will set the MSEL switches to run Linux.

  1. Set MSEL[4:0] to "01010", according to section 2.2 (MSEL Settings) of the DE10-Nano Getting Started Guide.

Step 2: Power on and Log in

You can operate the DE10-Nano in three ways:

  1. Serial Console
  2. SSH
  3. GUI

Serial Console

  1. Install a serial console application such as screen, PuTTY, or minicom on your development PC. This example uses PuTTY.

    sudo apt install -y putty

  2. Before you power on the DE10-Nano, connect the following:

  • Ethernet cable from DE10-Nano to a modem or router
  • Power supply from DE10-Nano to an outlet
  • USB cable (Mini-B to Type-A) from the DE10-Nano (UART-TO-USB port) to your development PC

  1. Using dmesg, identify the USB device path.

    Input:

    dmesg | tail

    Output:

    [12782.413742] usb 1-2.4: Detected FT232RL
[12782.414335] usb 1-2.4: FTDI USB Serial Device converter now attached to ttyUSB0

    In this example, the path returned is ttyUSB0.

Note: If you cannot find any message, install FT2XXRL device driver FTDI chip D2XX driver Installation.

  1. Open PuTTY and set up a serial connection.

    sudo putty

  2. Set the speed to 115200 and use the USB device path for the serial line.

  3. Click Open and hit Enter to log in.

    Default login credentials:

    • Username: root
    • Password: de10nano

SSH

  1. Before you power on the DE10-Nano, connect the following:
  • Ethernet cable from DE10-Nano to a modem or router
  • Power supply from DE10-Nano to an outlet

  1. Boot DE10-Nano and wait about 30 seconds. If DHCP works, DE10-Nano will receive an IP address from your gateway during the boot process. You can use this IP address to log in via ssh.

  2. Use ip addr or ifconfig to confirm your network address.

    Input:

    ip addr

    Output:

    ...
2: eth0:
 link/ether 94:c6:91:a0:76:17 brd ff:ff:ff:ff:ff:ff
 inet 192.168.3.28/24 brd 192.168.3.255 scope global dynamic eno1
 ...

    In the above example, the host has 192.168.3.28/24 as the IP address. The DE10-Nano should have the same network address.

  3. Use the ping command to search for addresses used on the same network.

    Input:

    echo 192.168.3.{1..254} | xargs -P255 -n1 ping -s1 -c1 -W1 | grep ttl

    Output:

    9 bytes from 192.168.3.1: icmp_seq=1 ttl=64
9 bytes from 192.168.3.28: icmp_seq=1 ttl=64
9 bytes from 192.168.3.98: icmp_seq=1 ttl=64

    In this example, the gateway router uses 192.168.3.1 and the DE10-Nano uses 192.168.3.98.

    Note: If you find several addresses on the same network, use ip addr to find the DE10-Nano network address.

  4. Log in to the console using:

    ssh root@192.168.3.98

    Default login credentials:

    • Username: root
    • Password: de10nano

Set up a Static IP Address (Optional)

Because the DHCP server sets another IP address every time the DE10-Nano reboots, some users may want to set a static IP address.

  1. Use ip addr or ifconfig to confirm your network address.

  2. To set up a new network connection, open a console on the DE10-Nano and type the following:

    Input:

    IPADDR=192.168.3.200/24
GATEWAY=192.168.3.1
DNS=8.8.8.8,8.8.4.4

  3. Set the IPADDR and GATEWAY fields according to your network environment.

    In this example, 192.168.3.1 is used by the gateway router. Thus, 192.168.3.X/24 is the network address. The static IP, 192.168.3.200, is provided to the DE10-Nano. /24 is used after the IP address to identify a subnet mask.

  4. Provide a connection name.

    Input:

    NAME=MyEthConnection

    This example uses "MyEthConnection".

  5. Use nmcli to create a new network connection.

    Because Ubuntu 16.04 on the DE10-Nano uses NetworkManager, you can use nmcli or nmtui.

    Input:

    nmcli connection add type ethernet autoconnect yes ifname eth0 con-name $NAME -- ipv4.method manual ipv4.address $IPADDR ipv4.dns $DNS ipv4.gateway $GATEWAY ipv6.method ignore connection.autoconnect-priority 1

    Output:

    Connection 'MyEthConnection' (d2bd3682-0b3d-4b27-88bc-6c52a4536d03) successfully added.

  6. Reboot the DE10-Nano and check the IP address. If you see the IP address that you set, you can SSH with that IP address.

  7. Connect to the DE10-Nano from a PC with the IP address.

    ssh root@192.168.3.200

    To delete the connection, use the following command:

    nmcli connection delete MyEthConnection

  8. Set an SSH key to easily log in to DE10-Nano (Optional).

    Open a terminal on your development PC (host) and type your public key to DE10-Nano.

    ssh-copy-id root@192.168.3.200

    Set up the ssh config file.

    vim ~/.ssh/config

    Place it below.

    Host de10nano
  HostName 192.168.100.200
  User root

    This allows you to log in with the following keyword only.

    ssh de10nano

GUI

To use the GUI, connect the following hardware to the DE10-Nano. See the image below for the hardware setup. Make sure to connect the power supply from DE10-Nano to an outlet.

  • HDMI cable and compatible display
  • USB adapter (for type A to micro-B USB cable)
  • USB hub
  • USB keyboard
  • USB mouse

GUI Accessories

Step 3: Install Azure IoT Edge

For this step, the DE10-Nano needs to access the internet. Make sure the DE10-Nano is connected to a modem or router via an Ethernet cable.

To use Azure IoT Edge for managing IoT devices using container virtualization, you will need to install Azure IoT Edge on each device.

Note: See Install the Azure IoT Edge runtime on Debian-based Linux systems for Microsoft's tutorial on how to install Azure IoT Edge runtime on Linux devices if you need more information.

Set up apt Package Setting

  1. Log in to the DE10-Nano and open a terminal.

  2. Create a download directory.

    mkdir -p ~/Downloads && cd ~/Downloads

  3. Download the repository configuration file from Microsoft.

    curl https://packages.microsoft.com/config/debian/stretch/multiarch/prod.list > ./microsoft-prod.list

  4. Move the file to a place that apt can access.

    mv ./microsoft-prod.list /etc/apt/sources.list.d/

  5. Install Microsoft's GPG public key

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

Install Moby Engine (container runtime)

  1. Install Moby Engine, which Azure IoT Edge officially supports.

    apt update
apt install -y moby-engine

  2. Install the Moby command-line interface.

    apt install -y moby-cli

Install Azure IoT Edge Runtime

Note: Because the OS of DE10-Nano uses Ubuntu 16.04, you need to install a fixed version of Azure IoT Edge Runtime.

  1. Update the package lists on the DE10-Nano and install Azure IoT Edge.

    apt update
apt install -y libiothsm-std=1.0.8-2 iotedge=1.0.8-2

Step 4: Create an IoT Hub Instance on Azure Portal

You must register the DE10-Nano to the Azure cloud for IoT edge runtime to work.

  1. Sign up for Azure Portal.

  2. Log in to your Azure Portal.

  3. Create a new resource group (recommended). From the Microsoft Azure homepage, navigate to Azure services > Resource groups, click Add.

  4. Set the project details (Subscription, Resource group name, Region). This example uses de10-nano for the resource group name.

    Note: When you complete the tutorials in this series, you can delete the resource group to avoid unintentional costs. For cost details, see Azure billing documentation.

  5. From the homepage, navigate to the search bar, type "iothub", and then select IoT Hub.

    azure-iot-hub-search

  6. Click Add to create an IoT Hub instance.

    azure-iot-hub-creation

  7. Set the project details. For example, Subscription (Free Trial), Resource group (de10-nano), Region (US West 2), and IoT Hub name (de10-nano-iot-hub).

    azure-iot-hub-generate-instance

  8. Click Next: Networking and choose a Connectivity method or leave as default.

  9. Click Next: Size and scale, choose a Pricing and scale tier, and then click Review + create.

    azure-iot-hub-choose-tier

    Note: The tier and number of units determine how many messages can be sent per day from the device to the Azure cloud. The F1: Free tier allows a maximum of 8000 messages per day.

  10. Review the details of the IoT Hub and then click Create. The deployment of your IoT Hub may take a few minutes.

    azure-iot-hub-instantiate

  11. When you see a message that Your deployment is complete, click Go to resource.

azure-iot-hub-go-to-resource

Register DE10-Nano as an IoT Edge Device

You will register the DE10-Nano as an IoT Edge device in this step.

  1. Navigate to Automatic Device Management or IoT Edge and click on IoT Edge as shown below.

    azure-iot-hub-register-iot-edge

  2. Click Add as IoT Edge device.

    azure-iot-hub-add-iot-edge-device

  3. Under Device ID, set the name of your device (For example, de10-nano-device). Click Save.

    azure-iot-hub-create-a-device

  4. Select your device and double-click.

    azure-iot-hub-see-device-information

  5. Copy the Primary Connection String. You can also choose to copy the Secondary Connection String. Azure cloud can confirm that DE10-Nano is a valid device with the connection string.

    Below is an example of the connection string, which varies from device to device.

    HostName=de10nano-iothub.azure-devices.net;DeviceId=de10-nano-iotedge;SharedAccessKey=rPiy9a15CM4WQ54EAwXq6/XQ07diE0zUi0NXTCBmuic=

    azure-iot-hub-copy-connection-string

Step 5: Update the IoT Edge Daemon Config File

Before running IoT Edge runtime, the connection string must be copied into the IoT Edge configuration file on DE10-Nano. If IoT Edge runtime on DE10-Nano is executed without setting the connection string, the application will not start.

  1. Open a terminal on the DE10-Nano using SSH, a serial console, or the GUI.

  2. Open /etc/iotedge/config.yaml with an editor.

    vim /etc/iotedge/config.yaml

  3. Replace <ADD DEVICE CONNECTION STRING HERE> with the connection string you copied.

    You can jump the line to type /device_connection in normal mode.

    Before:
...
# Manual provisioning configuration
provisioning:
  source: "manual"
  device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
...

After:
...
# Manual provisioning configuration
provisioning:
  source: "manual"
  device_connection_string: "HostName=...;DeviceId=...;SharedAccessKey=..."
...

    Use :wq! to save your changes.

  4. Enable your iotedge daemon.

    systemctl enable iotedge

  5. Restart iotedge.

    systemctl restart iotedge

  6. Check the status of iotedge. The Active: status should show as active (running).

    Input:

    systemctl status iotedge

    Output:

    ● iotedge.service - Azure IoT Edge daemon
Loaded: loaded (/lib/systemd/system/iotedge.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2020-02-14 05:42:46 UTC; 1min 51s ago
    Docs: man:iotedged(8)
Main PID: 4148 (iotedged)
    Tasks: 9
Memory: 2.4M
    CPU: 1min 9.765s
CGroup: /system.slice/iotedge.service
        └─4148 /usr/bin/iotedged -c /etc/iotedge/config.yaml

    If iotedge does not work, see the Azure IoT Edge Trouble Shooting Page.

Step 6: Set up DNS and Log Policy

Set up DNS on Container Runtime

  1. Check the IoT Edge runtime health.

    Input:

    iotedge check

    Output:

    Configuration checks
 --------------------
 ...
 ‼ DNS server - Warning
     Container engine is not configured with DNS server setting, which may impact connectivity to IoT Hub.
     Please see https://aka.ms/iotedge-prod-checklist-dns for best practices.
     You can ignore this warning if you are setting DNS server per module in the Edge deployment.
 ‼ production readiness: certificates - Warning
     Device is using self-signed, automatically generated certs.
     Please see https://aka.ms/iotedge-prod-checklist-certs for best practices.
 ...
 ‼ production readiness: logs policy - Warning
     Container engine is not configured to rotate module logs which may cause it run out of disk space.
     Please see https://aka.ms/iotedge-prod-checklist-logs for best practices.
     You can ignore this warning if you are setting log policy per module in the Edge deployment.
 × Edge Hub can bind to ports on host - Error
     Could not check current state of Edge Hub container
 ...
 19 check(s) succeeded.
 3 check(s) raised warnings. Re-run with --verbose for more details.
 1 check(s) raised errors. Re-run with --verbose for more details.
 ...

    In this example, there are a few warnings and one error for IoT Edge.

    • If the DHCP server does not assign a DNS address, you will need to assign a DNS address. If you do not receive a DNS warning, no action is needed.
    • In this tutorial, you can ignore the following:
      • Certificate warnings
      • Logs policy warnings. As needed, you can set these.
      • Edge Hub error.

    Note: The Edge Hub error occurs when there has never been a deployment on an IoT Edge device. If you deploy a container from the Azure cloud, the Edge Hub container is automatically generated, and this error will go away. This is a known issue, see Microsoft GitHub Issue No.36941.

  2. Make a new folder.

    mkdir /etc/docker

  3. Open daemon.json.

    vim /etc/docker/daemon.json

  4. Copy and paste the code below into the daemon.json file. Use :wq! to save your changes.

    {
    "dns": ["8.8.8.8", "8.8.4.4"]
}

    8.8.8.8 and 8.8.4.4 are public DNS addresses provided by Google. In this tutorial, they are used as DNS servers.

Set up Log Policy

  1. Put log settings after DNS setting.

    vim /etc/docker/daemon.json
    {
    "dns": ["8.8.8.8", "8.8.4.4"],
    "log-driver": "json-file",
    "log-opts": {
    "max-size": "10m",
    "max-file": "3"
    }
}

    Note: Be sure to copy the above syntax exactly since incorrect syntax will disconnect the device.

  2. Restart the container runtime.

    systemctl restart docker

    In this step, container runtime and Azure IoT Edge are installed. Also, DE10-Nano is registered on the Azure cloud, allowing you to deploy an application from the Azure cloud to the DE10-Nano.

  3. Check Azure* IoT Edge runtime again.

    Input:

    iotedge check

    Output:

    21 check(s) succeeded.
1 check(s) raised warnings. Re-run with --verbose for more details.
1 check(s) raised errors. Re-run with --verbose for more details.

    The DNS warning and logs policy warning has disappeared. You can continue to ignore the Edge Hub error.

Step 7: Expand microSD Card Storage Size

Containers often consume microSD card storage. We recommend that you expand your microSD card partition. The scripts in this step expand your card partition to the maximum storage capacity of the microSD card.

  1. Execute the following shell script on DE10-Nano to expand the storage size.

    ~/expand_rootfs.sh

  2. Reboot the DE10-Nano

    reboot

  3. Execute the following shell script after you reboot.

    ~/resize2fs_once

  4. Check the partition size.

    Input:

    df -Th

    Output:

    Filesystem     Type      Size  Used Avail Use% Mounted on
/dev/root      ext3       15G  2.0G   12G  15% /

    In this example, the storage is extended to 12GB for a 16GB microSD card.

Step 8: Deploy a Simulated Temperature Sensor

In this step, you deploy your first module from the Azure Marketplace. The module that you deploy in this step simulates a temperature sensor and sends simulated data to the cloud.

Note: See Quickstart: Deploy your first IoT Edge module to a virtual Linux device for Microsoft's tutorial on how to remotely deploy a module to an IoT Edge device. This step generally follows the instructions in the Microsoft tutorial.

  1. Open Azure Portal and search for "Simulated". Under Marketplace, click on Simulated Temperature Sensor.

    azure-iot-hub-find-temperature-module

  2. Set the Subscription, IoT Hub, and IoT Edge Device Name. Click on Find Device and devices which belong to your specified IoT Hub will appear.

  3. Click Create.

    azure-iot-hub-specify-iot-edge

  4. Make sure that SimulatedTemperatureSensor exists in IoT Edge Modules and then click on Next: Routes.

    azure-iot-hub-set-module

  5. Keep the defaults set for routes and then click Review + create.

    azure-iot-hub-routes

  6. Click Create. The sensor module will be sent to your device and deployed automatically.

    azure-iot-hub-set-routes

  7. Navigate to the device page. You will see the deployed sensor module.

    azure-iot-hub-iot-edge

  8. Open a DE10-Nano console and use iotedge list to confirm that the module is deployed (that is, STATUS: running).

    Input:

    iotedge list

    Output:

    NAME                        STATUS           DESCRIPTION      CONFIG
edgeAgent                   running          Up 2 minutes     mcr.microsoft.com/azureiotedge-agent:1.0
edgeHub                     running          Up a minute      mcr.microsoft.com/azureiotedge-hub:1.0
SimulatedTemperatureSensor  running          Up 2 minutes     mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0

    "SimulatedTemperatureSensor" should display, indicating that you deployed the container module on your DE10-Nano.

The first deployment may take some time. Use the iotedge list command several times and wait until edgeHub, edgeAgent and SimulatedTemperatureSensor are listed as above. edgeHub and edgeAgent are containers for managing your IoT Edge.

Check Container Data from the DE10-Nano Device

  1. Check the IoT Edge runtime log to make sure that the module is sending simulated data to the Azure cloud.

    Input:

    iotedge logs SimulatedTemperatureSensor | tail -n 3

    Output:

    02/14/2020 07:10:29> Sending message: 499, Body:
[{"machine":{"temperature":109.61642031237317,"pressure":11.095541554574158},"ambient":{"temperature":20.776358844375405,"humidity":26},"timeCreated":"2020-02-14T07:10:29.6590332Z"}]
02/14/2020 07:10:34> Sending message: 500, Body: [{"machine":{"temperature":109.47054543368078,"pressure":11.078922897507937},"ambient":{"temperature":20.883418869871374,"humidity":25},"timeCreated":"2020-02-14T07:10:34.6897821Z"}]
Done sending 500 messages

    The module will stop after sending 500 messages and you will need to restart it.

    iotedge restart SimulatedTemperatureSensor

Check Container Data from the Cloud

Confirm that the sensor module runs on the DE10-Nano by checking it from the Azure cloud.

Install Azure CLI

This step uses a development PC with Ubuntu 16.04 and follows the Azure CLI installation guide for Ubuntu.

Note: See the Azure Command-Line Interface (CLI) documentation for Microsoft's tutorial on how to install the Azure CLI.

  1. From your development PC, download and execute the install script.

    curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

    This script automatically installs the Azure CLI application on your PC.

  2. Enter your authentication information in a browser window.

    az login

Note: If you have an "xdg-open" error, make sure that BROWSER environment variable is set.

```
echo $BROWSER

export BROWSER=firefox
```

  1. Install the Azure IoT extension for Azure CLI.

    Microsoft provides an open-source extension, Azure IoT extension for Azure CLI, for developing Azure IoT applications with Azure CLI.

    In this tutorial, we use it to see messages that the IoT Hub has received.

    az extension add --name azure-cli-iot-ext

  2. Enable az command completion.

    source /etc/bash_completion.d/azure-cli

Note: If you re-open your terminal, the completion feature will be effective automatically.

Confirm DE10-Nano Messages with Azure CLI

  1. Monitor DE10-Nano messages with Azure CLI

    Since you have linked the Azure CLI to your cloud account, you can use Azure CLI to monitor data received by the IoT Hub cloud. Put the name of your IoT Hub after --hub-name in the following command. For example, de10-nano-iot-hub.

    Input:

    az iot hub monitor-events --hub-name de10-nano-iot-hub

    Output:

    ...
{
    
    "event": {
        "origin": "de10-nano-iotedge",
        "payload": "{\"machine\":{\"temperature\":104.63849517546522,\"pressure\":10.528436159230216},\"ambient\":{\"temperature\":20.712849819666172,\"humidity\":25},\"timeCreated\":\"2020-02-14T06:48:35.4649348Z\"}"
    }
}
{
    "event": {
        "origin": "de10-nano-iotedge",
        "payload": "{\"machine\":{\"temperature\":104.8690607204889,\"pressure\":10.554703120055697},\"ambient\":{\"temperature\":21.158996682920957,\"humidity\":26},\"timeCreated\":\"2020-02-14T06:48:40.5055251Z\"}"
    }
}
...

Note: If you cannot see any messages, use iotedge logs to check if the SimulatedTemperatureSensor module is still working.

Next Steps

Congratulations! You completed the first tutorial in this series. To continue to the next tutorial, go to Build an Azure Container-based Application using Microsoft Visual Studio.

If you plan to continue to the next tutorial in this series, do not delete the resource group you created earlier. If not, you may now delete it. When you delete the resource group, you also delete all Azure services you associated with it.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.