Azure IoT Edge Dev Tool

The Azure IoT Edge Dev Tool greatly simplifies Azure IoT Edge development down to simple Tool commands driven by Environment Variables.

• It gets you started with IoT Edge development with the IoT Edge Dev Container and IoT Edge Solution Scaffolding that contains a sample module and all the required configuration files.
• It speeds up your inner-loop dev (dev, debug, test) by reducing multi-step build & deploy processes into one-line CLI commands and well as drive your outer-loop CI/CD pipeline. You can use all the same commands in both stages of your development life-cycle.

Quickstart

Here is the absolute fastest way to get started with IoT Edge Dev. This quickstart will run a container, create a solution, setup Azure resources, build and deploy modules to your device, setup and start the Edge Runtime and then monitor messages flowing into IoT Hub.

The only thing you need to install is Docker. All of the other dev dependencies are included in the container.

1. Install Docker

2. Run the Azure IoT Edge Dev Container

   Windows

   mkdir c:\temp\iotedge
   docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v c:/temp/iotedge:/home/iotedge jongallant/iotedgedev
   

   Linux

   sudo mkdir /home/iotedge
   docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v /home/iotedge:/home/iotedge jongallant/iotedgedev
   

3. Initialize Edge Solution and Setup Azure Resources

   iotedgedev init

4. Build & Push IoT Edge Modules

   iotedgedev push

   You can also combine build, push and deploy with iotedgedev push --deploy

5. Deploy Modules to IoT Edge Device

   iotedgedev deploy

6. Start the IoT Edge Runtime

   iotedgedev start

7. Monitor Messages sent from IoT Edge to IoT Hub

   iotedgedev monitor

Overview

The Azure IoT Edge Dev Tool enables you to do all of the following with simple one-line CLI commands.

1. Start Container:

   docker run -it -v /var/run/docker.sock:/var/run/docker.sock -v c:/temp/iotedge:/home/iotedge jongallant/iotedgedev

   This container includes all of the dependencies you need for IoT Edge development, including:

   • Docker
   • .NET Core SDK
   • Python
   • Pip
   • Azure CLI

   You can also directly install with: pip install iotedgedev

2. Create Solution: Create a new IoT Edge Solution that includes a sample module and all the the required configuration files.

   iotedgedev solution edgesolution1

   cd edgesolution1

3. Setup Azure: Creates or selects your Azure IoT Hub and Edge Device and updates your Environment Variables.

   iotedgedev azure

   This must be run from the root of your solution, so make sure you cd into the edgesolution1 folder before you run this command.

4. Build, Push & Deploy: Build, Push and Deploy modules:

   iotedgedev push --deploy

   This will dotnet build, publish, docker build, tag and push and deploy modules to your IoT Edge device.

   If your module is not dotnet, then the dotnet build/publish steps will be skipped.

5. Setup & Start: Setup and Start the IoT Edge Runtime:

   iotedgedev start

6. View Messages: View Messages Sent from IoT Edge to IoT Hub:

   iotedgedev monitor

7. View Logs: View and Save Docker log files:

   iotedgedev docker --logs

8. Setup Custom Registry: Use a Custom Container Registry:

   iotedgedev docker --setup-registry

Please see Azure IoT Edge Dev Resources for links to official docs and other IoT Edge dev information.

Setup

Azure Setup

Automated Setup

The following will show you how to setup your Azure Resources via the CLI instead of using the Portal.

First, create a solution with the following command:

iotedgedev solution edgesolution1

Then, cd into that solution:

cd edgesolution

Then, run the iotedgedev azure command to setup your Azure Resources. This command will bring you through a series of prompts to create Azure Resources and retrieve your IoT Hub and Edge Device connection strings and save them to the .env file in the root of the project. All subsequent commands will use those environment variables.

Here are all the azure command options:

You can override all of these parameters with environment variables. Please see the .env file in your solution for details.

iotedgedev azure
    --credentials USERNAME PASSWORD
    --service-principal USERNAME PASSWORD TENANT
    --subscription THE_SUBSCRIPTION_ID 
    --resource-group-location THE_RG_LOCATION
    --resource-group-name THE_RG_NAME 
    --iothub-sku THE_IOT_SKU 
    --iothub-name THE_IOT_NAME 
    --edge-device-id THE_EDGE_DEVICE_NAME
    --update-dotenv

You can use the following az cli command to create a service principal:

az ad sp create-for-rbac -n "iotedgedev01"

Note: Running iotedgedev azure without any other parameters will save you time from looking up the required parameter values. The command will help you choose the parameters in an interactive way.

Alternatively, you can deploy the IoT Hub and Container Registry with this Deploy to Azure template:

Note: If you do not need a Container Registry, or are planning to use a local registry, then you should run the iotedgedev azure command instead of running this Deploy to Azure template, because the template includes a Container Registry.

Manual Setup

1. Create Azure IoT Hub

2. Create Edge Device using the Azure Portal

   • In your IoT Hub, click "IoT Edge", then click "Add IoT Edge Device"

3. Container Registry When you develop for IoT Edge, you need to host your images in a container registry, which the IoT Edge runtime will fetch the images from when it starts.

   By default, the IoT Edge Dev Tool, will use the Local Registry.

   We have tested the following options, but you can host your images on any Docker compatible registry host.

   1. Local Registry

      Set CONTAINER_REGISTRY_SERVER to localhost:5000 and leave CONTAINER_REGISTRY_USERNAME/CONTAINER_REGISTRY_PASSWORD blank.

      CONTAINER_REGISTRY_SERVER="localhost:5000"

   2. Azure Container Registry

      You can create an Azure Container Registry and host your images there. - Make sure you enable Admin Access when you create the Azure Container Registry

      After created, open .env and set the following:

      CONTAINER_REGISTRY_SERVER="ACR URI" 
      CONTAINER_REGISTRY_USERNAME="ACR USERNAME"
      CONTAINER_REGISTRY_PASSWORD="ACR PASSWORD"
      

      Example:

      CONTAINER_REGISTRY_SERVER="jong.azurecr.io" 
      CONTAINER_REGISTRY_USERNAME="jong"
      CONTAINER_REGISTRY_PASSWORD="p@$$w0rd"
      

   3. Docker Hub

      You can also host your images on Docker Hub. Create a Docker Hub account and then open .env and enter the following:

      CONTAINER_REGISTRY_SERVER="DOCKER HUB USERNAME" 
      CONTAINER_REGISTRY_USERNAME="DOCKER HUB USERNAME"
      CONTAINER_REGISTRY_PASSWORD="DOCKER HUB PASSWORD"
      

      Example:

      CONTAINER_REGISTRY_SERVER="jongallant" 
      CONTAINER_REGISTRY_USERNAME="jongallant"
      CONTAINER_REGISTRY_PASSWORD="p@$$w0rd"
      

Dev Machine Setup

Here's what you need to do to get Azure IoT Edge Dev Tool (aka iotedgedev) running on your dev machine. If you are using a separate Edge device, like a Raspberry Pi, you do not need to run all of these steps on your IoT Edge device, you can just use iotedgectl directly on the device. See the IoT Edge Device Setup section below for more information on setting up your Edge device.

Note: See the "Test Coverage" section below to see what the IoT Edge Dev Tool has been tested with.

IoT Edge Dev Container

You can use the IoT Edge Dev Tool container to avoid having to install all the dependencies on your local dev machine.

(Only runs on Linux Containers at this time. Windows Container support coming soon.)

1. Install Docker

2. Run Container

   Your iotedgedev files will be saved to the /iotedge directory on your host machine.

   Windows

   mkdir c:\temp\iotedge
   docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v c:/temp/iotedge:/home/iotedge jongallant/iotedgedev
   

   Linux

   sudo mkdir /home/iotedge
   docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v /home/iotedge:/home/iotedge jongallant/iotedgedev
   

3. Change to the /iotedge directory:

   cd /iotedge

4. Skip all the install steps below and jump to the Usage section below.

Local Dev Machine Setup

You don't need to do this if you are running the container as described in the previous step.

1. Install Docker

   • Windows

     • Switch to Linux Containers if you are running Windows.

   • Windows Subsystem for Linux (WSL)

     Here's a video that shows you how to setup WSL: https://www.youtube.com/watch?v=k5ZtTmHgs_8

     1. Do not install Docker in WSL, you can use Docker on your Windows machine by modifying the path.

     2. In Docker Settings/General, Check "Expose Daemon on tcp:// without TLS"

     3. Execute the following in a Bash terminal. This will make docker available in your Bash terminal.

        echo "PATH=\"$PATH:$HOME/bin:$HOME/.local/bin:/mnt/c/Program\ Files/Docker/Docker/resources/bin\"" >> ~/.bashrc
        echo "alias docker=docker.exe" >> ~/.bashrc
        echo "alias docker-machine=docker-machine.exe" >> ~/.bashrc
        echo "alias docker-compose=docker-compose.exe" >> ~/.bashrc
        echo "export DOCKER_HOST='tcp://localhost:2375'" >> ~/.bashrc
        source ~/.bashrc
        
        sudo sh -c "echo Defaults  env_keep += \"DOCKER_HOST\" >> /etc/sudoers.d/docker"
        

   • Linux

     • We've seen some issues with docker.io. If Edge doesn't run for you, then try installing Docker CE directly instead of via docker.io. Use the CE install steps, or use the convenience script.

2. Install Python 2.7+ or Python 3.6+

   • Windows - Install from Python's website
   • Linux - sudo apt install python-pip or sudo apt install python3-pip

3. Install .NET Core SDK

   • The .NET Core SDK does not run on ARM, so you do not need to install this on Raspberry Pi.

4. Install Azure CLI 2.0

5. Install Azure CLI IoT Extension

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

6. Install System Dependencies

   You can also run under a Python Virtual Environment. See the Python Virtual Environment Setup instructions below for details on how to set that up.

   1. System Dependencies

      1. Mac:

         sudo easy_install pip
         brew install libffi
         

      2. Raspberry Pi:

         sudo pip install --upgrade setuptools pip
         sudo apt install python2.7-dev libffi-dev libssl-dev -y
         

7. Install IoTHub-Explorer

   Currently, the only way to view IoT Hub Messages via CLI is with the iothub-explorer npm package. You need to install Node.js and then install the iothub-explorer package with the following command:

   npm i -g iothub-explorer
   

   You can also use Device Explorer as well, but it is Windows only. The Azure IoT team is working on porting the monitor-events functionality to the official az iot CLI - but for now we'll use the npm package.

8. Install iotedgedev

   You do not need to run this on the IoT Edge device. See the IoT Edge Device Setup section below for more information on setting up your IoT Edge device.

   pip install iotedgedev
   

Usage

Here's how you create a solution, build and deploy modules, and then setup and start the Edge runtime.

Step 1: Create Azure IoT Edge Solution

The following command will setup the folder structure required for this module

Replace edgesolution1 with the name of your solution. Use . to create in the current folder.

iotedgedev solution edgesolution1
cd edgesolution1

Folder Structure

When you create a new solution, it will have the following contents:

1. modules folders - Contains all of the modules for your IoT Edge Solution.

   • The iotedgedev module assumes that you'll structure your Dockerfiles exactly like the filtermodule sample. Have a Docker folder in the root of the solution, then subfolders within that to support multiple Docker files.

   It is important that you follow this structure or the module will not work. Please make suggestions or fork this solution if you would like a different behavior.

2. .env - Contains all the required Environment Variables for your IoT Edge Solution.

3. .gitignore - A .gitignore file for your IoT Edge Solution.

4. Configuration File Templates - There are two files in the root of the solution:

   • deployment.template.json - Contains the config that is deployed to your IoT Edge device. It contains references to your modules, module routes and desired property information.
   • runtime.template.json - Contains the config used by your IoT Edge runtime. It contains your device connection string, your container registry settings and is used when you call the iotedgedev setup or iotedgedev start commands.

5. config folder - All expanded config files are copied to this folder and these files are used at runtime.

6. logs folder - Contains all the Docker log files for the Runtime and your modules.

Step 2: Update Environment Variables

The settings used for this module are stored in a .env file in the root of your solution. System or User Environment Variables take precedence over values in .env file.

1. Open .env and set variables

   You only need to set the IOTHUB_CONNECTION_STRING AND DEVICE_CONNNECTION_STRING settings, which you can get from the Azure Portal.

   IOTHUB_CONNECTION_STRING=""
   DEVICE_CONNECTION_STRING=""
   

   You can use the DOTENV_FILE Environment Variable to point to a different .env file, such as .env.integration or .env.test. This is helpful in CI/CD pipeline scenarios where you'll want to target different environments and devices to ensure all scenarios are tested.

   IoT Edge Dev Tool offers a wizard-like command to guide you through setting up Azure and also setting up the Environment Variables properly.

   iotedgedev azure
   

Step 3: Build and Deploy Modules

Use sudo for Linux. You will not be able to build on the Raspberry Pi, because the .NET Core SDK does not support ARM. You can build on an x86 based machine and deploy to Pi.

iotedgedev build --deploy

The- build command will build each module in the modules folder and push it to your container registry. The- --deploy command will apply the generated config/deployment.json configuration file to your IoT Edge device. You could also call deploy directly with iotedgedev deploy.

You can configure what modules will be built and deployed by using the ACTIVE_MODULES env var in the .env file. You can configure which Dockerfiles get built and deployed by using the ACTIVE_DOCKER_DIRS env var.

Step 4: Setup and Start the IoT Edge Runtime

Use 'sudo' for Linux/RaspberryPi

iotedgedev start

The start command will apply the /config/runtime.json file to your IoT Edge device and will start the IoT Edge runtime. You can also call iotedgedev setup and iotedgedev start independently.

Step 5: Monitor Messages

iotedgedev monitor

This will print messages sent from the device specified in DEVICE_CONNECTION_STRING. To use this command, you first need to install the iothub-explorer npm package with the following command:

npm i -g iothub-explorer

NOTE: iothub-explorer is included in the IoT Edge Dev Container

Step 6: Create a new Module

After you have everything running from the IoT Edge Tool solution template, the next step is to develop all the custom modules you need for your scenario. Here's how you do that:

1. Install the .NET Core Module Template

   This is the same template I used to create the filtermodule. It includes a sample C# module project and Docker files.

   dotnet new -i Microsoft.Azure.IoT.Edge.Module
   

2. Create a new Module

   From the root of your solution:

   dotnet new  aziotedgemodule -o modules/mymodule
   

   Now, when you run iotedgedev build you will see that mymodule is also built and pushed to your container registry.

3. Add Message Property

   We are going to add a new custom property to the message as it is flowing through the system so we can see that our module is working.

   1. Open /modules/mymodule/Program.cs.
   2. Add the following line right above the SendEventAsync call.

   pipeMessage.Properties.Add("abc", "123");
   await deviceClient.SendEventAsync("output1", pipeMessage);
   

4. Add Module to Config

   1. Open deployment.template.json.
   2. Copy and paste the filtermodule section and change filtermodule to mymodule.

       "mymodule": {
           "version": "1.0",
           "type": "docker",
           "status": "running",
           "restartPolicy": "always",
           "settings": {
               "image": "${CONTAINER_REGISTRY_SERVER}/mymodule:0.0.1-amd64",
               "createOptions": ""
           }
       }
   

   Make sure you change it in two places, the name and the settings.image property.

5. Add Route to Config

   By default, your new module acts as a simple pass through. It receives messages and passes them to the output. We will add mymodule in between our existing sensor and filter modules.

   1. Open deployment.template.json
   2. Replace $edgeHub.properties.desired.routes with the following:

       "routes": {
         "sensorToMyModule": "FROM /messages/modules/temp-sensor-module/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/mymodule/inputs/input1\")",
         "myModuleToFilter": "FROM /messages/modules/mymodule/outputs/output1 INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
         "filterToIoTHub": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream"
       },
   

6. Build and Deploy Modules

   Now that we have the module created, code added, and config updated, we are going to rebuild, deploy our module.

   You will notice that the IoT Edge Runtime automatically detects a new deployment, retrieves the new module, applies the new route and keeps sending messages.

   iotedgedev build --deploy

7. Monitor Messages

   Now when we view the messages flowing through the system, we'll see an additional 'abc' property:

   iotedgedev monitor
   

       "machine": {
           "temperature": 102.97201423520322,
           "pressure": 10.338583900213024
       },
       "ambient": {
           "temperature": 20.577302686906094,
           "humidity": 26
       },
       "timeCreated": "2017-12-31T15:15:13.8580843Z"
       }
       ---- application properties ----
       {
           "abc": "123",
           "MessageType": "Alert"
       }
   

That's all there is to it. You can now get started implementing your IoT Edge scenario!

Commands

iotedgedev

Usage: iotedgedev [OPTIONS] COMMAND [ARGS]...

Options:
  --version     Show the version and exit.
  --set-config  Expands environment variables in *.template.json and copies to config folder.
  -h, --help    Show this message and exit.

Commands:
  azure     Manage Azure Resources
  build     Builds All Active Modules
  deploy    Deploys Solution to IoT Edge Device
  docker    Docker Utilities
  e2e       Push, Deploy, Start, Monitor
  init      Creates Solution and Azure Resources
  iothub    Monitor IoT Hub Events
  modules   Build and Deploy IoT Edge Modules
  monitor   Monitors Messages from IoT Edge to IoT Hub
  push      Pushes Active Modules to Container Registry
  restart   Restarts IoT Edge Runtime
  runtime   Manage IoT Edge Runtime
  solution  Manage IoT Edge Solutions
  start     Starts IoT Edge Runtime
  stop      Stops IoT Edge Runtime

iotedgedev azure

Usage: iotedgedev azure [OPTIONS]

  Manage Azure Resources

Options:
  --setup                         Retrieves or creates the required Azure Resources.
  --credentials <TEXT TEXT>...    Enter Azure Credentials (username password).
  --service-principal <TEXT TEXT TEXT>...
                                  Enter Azure Service Principal Credentials (username password tenant).
  --subscription TEXT             The Azure Subscription Name or Id.  [required]
  --resource-group-location [australiaeast|australiasoutheast|brazilsouth|canadacentral|canadaeast|centralindia|centralus|eastasia|eastus|eastus2|japanwest|japaneast|northeurope|northcentralus|southindia|uksouth|ukwest|westus|westeurope|southcentralus|westcentralus|westus2]
                                  The Resource Group Location.  [required]
  --resource-group-name TEXT      The Resource Group Name (Creates a new Resource Group if not found).  [required]
  --iothub-sku [F1|S1|S2|S3]      The IoT Hub SKU.  [required]
  --iothub-name TEXT              The IoT Hub Name (Creates a new IoT Hub if not found).  [required]
  --edge-device-id TEXT           The IoT Edge Device Id (Creates a new Edge Device if not found).  [required]
  --update-dotenv                 If True, the current .env will be updated with the IoT Hub and Device connection
                                  strings.  [required]
  -h, --help                      Show this message and exit.

iotedgedev build

Usage: iotedgedev build [OPTIONS]

  Builds All Active Modules

Options:
  --push      Pushes modules to container registry.
  --deploy    Deploys modules to Edge device using deployment.json in the config folder.
  -h, --help  Show this message and exit.

iotedgedev deploy

Usage: iotedgedev deploy [OPTIONS]

  Deploys Solution to IoT Edge Device

Options:
  -h, --help  Show this message and exit.

iotedgedev docker

Usage: iotedgedev docker [OPTIONS]

  Docker Utilities

Options:
  --setup-registry     Pulls Edge Runtime from Docker Hub and pushes to your specified container registry. Also,
                       updates config files to use CONTAINER_REGISTRY_* instead of the Microsoft Docker hub. See
                       CONTAINER_REGISTRY environment variables.
  --clean              Removes all the Docker containers and Images.
  --remove-modules     Removes only the edge modules Docker containers and images specified in ACTIVE_MODULES, not
                       edgeAgent or edgeHub.
  --remove-containers  Removes all the Docker containers
  --remove-images      Removes all the Docker images.
  --logs               Opens a new terminal window for edgeAgent, edgeHub and each edge module and saves to LOGS_PATH.
                       You can configure the terminal command with LOGS_CMD.
  --show-logs          Opens a new terminal window for edgeAgent, edgeHub and each edge module. You can configure the
                       terminal command with LOGS_CMD.
  --save-logs          Saves edgeAgent, edgeHub and each edge module logs to LOGS_PATH.
  -h, --help           Show this message and exit.

iotedgedev e2e

Usage: iotedgedev e2e [OPTIONS]

  Push, Deploy, Start, Monitor

Options:
  -h, --help  Show this message and exit.

iotedgedev init

Usage: iotedgedev init [OPTIONS]

  Creates Solution and Azure Resources

Options:
  -h, --help  Show this message and exit.

iotedgedev iothub

Usage: iotedgedev iothub [OPTIONS]

  Monitor IoT Hub Events

Options:
  --monitor-events  Displays events that are sent from IoT Hub device to IoT Hub.
  --timeout TEXT    Number of milliseconds to monitor for events.
  -h, --help        Show this message and exit.

iotedgedev modules

Usage: iotedgedev modules [OPTIONS]

  Build and Deploy IoT Edge Modules

Options:
  --build     Builds modules specified in ACTIVE_MODULES Environment Variable.
  --push      Pushes modules specified in ACTIVE_MODULES Environment Variable to container registry.
  --no-build  Informs the push command to not build modules before pushing to container registry.
  --deploy    Deploys modules to Edge device using deployment.json in the config folder.
  -h, --help  Show this message and exit.

iotedgedev monitor

Usage: iotedgedev monitor [OPTIONS]

  Monitors Messages from IoT Edge to IoT Hub

Options:
  --timeout TEXT  Number of milliseconds to monitor for events.
  -h, --help      Show this message and exit.

iotedgedev push

Usage: iotedgedev push [OPTIONS]

  Pushes Active Modules to Container Registry

Options:
  --deploy    Deploys modules to Edge device using deployment.json in the config folder.
  --no-build  Informs the push command to not build modules before pushing to container registry.
  -h, --help  Show this message and exit.

iotedgedev restart

Usage: iotedgedev restart [OPTIONS]

  Restarts IoT Edge Runtime

Options:
  -h, --help  Show this message and exit.

iotedgedev runtime

Usage: iotedgedev runtime [OPTIONS]

  Manage IoT Edge Runtime

Options:
  --setup     Setup Edge Runtime using runtime.json in config folder.
  --start     Starts Edge Runtime. Calls iotedgectl start.
  --stop      Stops Edge Runtime. Calls iotedgectl stop.
  --restart   Restarts Edge Runtime. Calls iotedgectl stop, removes module containers and images, calls iotedgectl
              setup (with --config-file) and then calls iotedgectl start.
  --status    Edge Runtime Status. Calls iotedgectl status.
  -h, --help  Show this message and exit.

iotedgedev solution

Usage: iotedgedev solution [OPTIONS] [NAME]

  Manage IoT Edge Solutions

Options:
  --create TEXT  Creates a new Azure IoT Edge Solution. Use `--create .` to create in current folder. Use `--create
                 TEXT` to create in a subfolder.
  -h, --help     Show this message and exit.

iotedgedev start

Usage: iotedgedev start [OPTIONS]

  Starts IoT Edge Runtime

Options:
  -h, --help  Show this message and exit.

iotedgedev stop

Usage: iotedgedev stop [OPTIONS]

  Stops IoT Edge Runtime

Options:
  -h, --help  Show this message and exit.

Setup Container Registry

You can also use iotedgedev to host the IoT Edge runtime from your own Azure Container Registry or a Local Container Registry. Set the .env values for your Container Registry and run the following command. It will pull all the IoT Edge containers from Dockerhub, tag them and upload them to the container registry you have specified in .env.

Use 'sudo' for Linux/RaspberryPi

iotedgedev docker --setup-registry

View Docker Logs

Show Logs

The iotedgedev module also include a "Show Logs" command that will open a new command prompt for each module it finds in your IoT Edge config. Just run the following command:

Note: I haven't figured out how to launch new SSH windows in a reliable way. It's in the backlog. For now, you must be on the desktop of the machine to run this command.

iotedgedev docker --show-logs

You can configure the logs command in the .env file with the LOGS_CMD setting. The .env file provides two options, one for ConEmu and one for Cmd.exe.

Save Logs

You can also output the logs to the LOGS_PATH directory. The following command will output all the logs and add them to an edge-logs.zip file that you can send to the Azure IoT support team if they request it.

iotedgedev docker --save-logs

Both Show and Save Logs

Run the following to show and save logs with a single command

iotedgedev docker --logs

Local Docker Registry Setup

Instead of using a cloud based container registry, you can use a local Docker registry. Here's how to get it setup.

1. Set CONTAINER_REGISTRY_SERVER in .env to localhost:5000. You can enter a different port if you'd like to.
2. Add localhost:5000 and 127.0.0.1:5000 to Docker -> Settings -> Daemon -> Insecure Registries

In the latest iotedgedev build, step 2 above hasn't been required. But, if you run into issues, you may want to try adding those Insecure Registries.

iotedgedev will look for localhost in your setting and take care of the rest for you.

IoT Edge Device Setup

The iotedgedev module is intended to help with IoT Edge development and doesn't necessarily need to be taken on as a dependency in production or integration environments, where you'll likely want to use the iotedgectl module directly. You can use iotedgedev to generate your runtime.json file on your dev machine, copy that to your IoT Edge device and then use the following command to setup and start your IoT Edge Runtime.

iotedgectl setup --config-file runtime.json
iotedgectl start

Having said that, there's nothing stopping you from deploying iotedgedev to your IoT Edge device. It may be helpful if you want to run the iotedgedev docker --clean command to clean up Docker containers and images. Or if you want to run iotedgedev docker --show-logs to see all the log files on the device or iotedgedev docker --save-logs to output to the LOGS_PATH directory.

Please note that the .NET Core SDK does not support ARM, so you will not be able to run build directly on a Raspberry Pi.

Raspberry Pi

Whether you use iotedgedev or directly use iotedgecgtl on the Raspberry Pi, you will still need to run the following commands before you run the IoT Edge Runtime.

```
sudo pip install --upgrade setuptools pip
sudo apt install python2.7-dev libffi-dev libssl-dev -y
sudo pip install -U azure-iot-edge-runtime-ctl
```

Config Changes

If you are running on Raspberry Pi you need to use the arm32v7 Dockerfile. Open `deployment.template.json`, find the `filtermodule` line and replace `amd64` with `arm32v7`. 

Replace this:
`"image": "${CONTAINER_REGISTRY_SERVER}/filtermodule:0.0.1-amd64",`

With this:
`"image": "${CONTAINER_REGISTRY_SERVER}/filtermodule:0.0.1-arm32v7",`

Environment Variable Change

Open your .env file and add arm32v7 to your ACTIVE_DOCKER_PLATFORMS setting. This will tell the IoT Edge Dev Tool to also build the arm32v7 images.

`ACTIVE_DOCKER_PLATFORMS="amd64,arm32v7"`

Python Virtual Environment Setup

You can run iotedgedev inside a Python Vritual Environment.

1. Install virtualenv

   pip install virtualenv

2. Create virtualenv

   Execute the following from the root of this repository.

   virtualenv venv

   venv is just a env name that can be anything you want, but we recommend sticking with venv because the .gitignore file excludes it.

3. Activate the virtualenv

   Windows: venv\Scripts\activate.bat

   Posix: source venv/bin/activate

4. Install Dependencies

   Continue with the instructions above starting with the Dev Machine Setup -> Install Dependencies.

5. Deactivate the virtualenv

   When you are done with your virtualenv, you can deactivate it with the follow command:

   deactivate

Test Coverage

This module has been tested with the following:

• Windows 10 Fall Creators Update
• Windows Subsystem for Linux, Ubuntu 16.04
• Ubuntu 16.04
• Mac Sierra 10.12.6
• Raspberry Pi with Raspbian Stretch (.NET Core Runtime Only, .NET Core SDK not supported on ARM.) - You cannot use Raspberry Pi as a IoT Edge dev machine, but it can host the IoT Edge runtime.
• Python 2.7.13 and Python 3.6.3
• Docker Version 17.09.1-ce-win42 (14687), Channel: stable, 3176a6a

Troubleshooting

1. Invalid Reference Format

   500 Server Error: Internal Server Error for url: http+docker://localunixsocket/v1.30/images
   500 Server Error: Internal Server Error ("invalid reference format")
   

   Solution: You likely installed Docker via sudo apt install docker.io. Use the proper steps for CE here, or use the convenience script.

2. Permissions Error

   The directory '/home/user/.cache/pip/http' or its parent directory is not owned by the current user and the cache has been disabled. Please check the permissions and owner of that directory. If executing pip with sudo, you may want sudo's -H flag.
   

   Solution: Run pip install with -H sudo -H pip install -U -r requirements.txt then sudo -H pip install -U -r requirements_nodeps.txt --no-deps

3. Latest Docker Image Not Pulled from Registry

   By design, Docker only pulls images that have been changed. When you are developing you tend to push new images on a frequent basis, which Docker will not pull unless it has a unique tag. You could assign every push a new tag, or you can simply run the following command on the IoT Edge device.

   iotedgedev runtime --restart
   

   This stops the runtime, removes your ACTIVE_MODULES containers and images, calls setup and then starts the runtime. Docker will then be forced to pull the imageS from the registry because it does not have them locally anymore.

4. 404 Client Error: Not Found ("No such container: edgeAgent")

   I occasionally see this when running iotedgedev runtime --restart, but I have never seen it cause any issues. LMK if you see any issues because of it.

5. ('Connection aborted.', error(2, 'No such file or directory'))

   This means that you have likely do not have DOCKER_HOST Environment Variable set. If you are running WSL, then please see the Dev Machine Setup steps above. You have to write DOCKER_HOST to your ~/.bashrc file.

   ERROR: Could not login to Container Registry. Please verify your credentials in CONTAINER_REGISTRY_ environment variables. 
   If you are using WSL, then please set DOCKER_HOST Environment Variable. See the [IoT Edge Dev Tool readme](https://aka.ms/iotedgedev) for full instructions.
   

   ('Connection aborted.', error(2, 'No such file or directory'))
   ERROR: Could not connect to docker daemon.
   ERROR: Docker is unavailable
   CRITICAL: IoT Edge dependency not available: docker
   

Issues

Please use the GitHub issues page to report any issues.

Contributing

Please fork, branch and pull-request any changes you'd like to make.

Contributor Dev Machine Setup

1. Clone or Fork this Repository

   git clone https://github.com/azure/iotedgedev.git

2. Rename .env.tmp in the root of the repo to .env and set the IOTHUB_CONNECTION_STRING_ and DEVICE_CONNECTION_STRING values to settings from your IoT Hub and Edge Device. To set these values you could run iotedgedev azure in the root of the repo.

3. Install Microsoft Visual C++ Build Tools

4. Run npm install from the root directory to install the required npm packages for iothub-explorer calls.

5. Install OpenSSL 1.1.0g

   • Windows
     1. Download from OpenSSL's website
     2. Extract the downloaded .tar.gz to C:\OpenSSL\

6. Make sure both Python 2.7 and Python 3.6 are installed

7. Install dependencies

   Run the following command to install all the dependencies needed to build iotedgedev and run the tests.

   pip install -r requirements_dev.txt
   

8. Editable Mode

   Run the following command from the root of the IoT Edge Dev Tool Solution to see changes to iotedgedev commands as you change code.

   pip install -e .
   

Run Tests

Run the following command to run tests.

`tox`