Azure IoT Edge Dev Tool

The IoT Edge Dev Tool is designed to simplify Azure IoT Edge development by using simple CLI commands driven by environment variables. It facilitates two main development stages:

1. Getting Started: Provides scaffolding for IoT Edge solutions, including a default module and necessary configuration files, often used in conjunction with the IoT Edge Dev Container.
2. Development Lifecycle: Speeds up the 'inner-loop' (development, debugging, and testing) by condensing multi-step build and deploy processes into single-line CLI commands. These same commands can be used in the 'outer-loop' for CI/CD pipelines.

The iotedgedev CLI is the primary interface for managing Azure IoT Edge development workflows, including solution creation, building, deploying, and simulator management.

Core command groups include:

• solution: Manage IoT Edge solutions (new, add, build, push, deploy, genconfig).
• simulator: Manage the IoT Edge simulator (setup, start, stop).
• docker: Manage Docker containers and images (clean, log, setup).
• iothub: Manage Azure IoT Hub and device deployments (deploy, monitor, setup).
• log & monitor: Utility commands for observing logs and telemetry.

The iotedgedev simulator command group allows you to manage a local IoT Edge simulator for testing modules without a physical device.

Available Commands:

• setup: Prepares the simulator. This must be run before starting.
• start: Launches the simulator.
• stop: Shuts down the simulator.
• modulecred: Retrieves credentials (connection strings, certificate paths) for a specific target module.

The iotedgedev solution command group is used to manage the lifecycle of an IoT Edge solution, including creating, building, and deploying multiple modules.

Core Commands:

• new: Creates a new solution folder.
• init: Creates a new solution and provisions Azure resources.
• add: Adds a new module to an existing solution.
• build: Builds the solution modules.
• push: Pushes module images to a container registry.
• deploy: Deploys the solution to an IoT Edge device.
• genconfig: Expands environment variables and placeholders in a deployment manifest template and copies the result to the config folder.
• e2e: A convenience command to perform the full workflow: Push, deploy, start, and monitor.

In version 0.82.0, the ACTIVE_MODULES environment variable is deprecated. The tool now determines which Dockerfiles to build based on the deployment manifest template and two environment variables:

1. BYPASS_MODULES: A list of module names to skip.
2. ACTIVE_DOCKER_PLATFORMS: A list of platforms to build.

A Dockerfile is built if:

• The module name is not in BYPASS_MODULES AND the module specifies an image placeholder ${MODULES.<module-name>.<platform>} in the deployment manifest template.
• OR the module name is not in BYPASS_MODULES AND the platform is listed in ACTIVE_DOCKER_PLATFORMS.

IoT Edge Dev Tool 0.82.0 uses a deployment manifest template (default: deployment.template.json in the solution root) to build solutions.

Instead of hardcoding long image URLs, you can use image placeholders in the template. The format is ${MODULES.<module-name>.<platform>} (e.g., ${MODULES.filtermodule.amd64}).

When you run the build command, the tool expands these placeholders into actual image URLs and saves the resulting deployment manifest (default: config/deployment.json) to the config folder.

Configuration Environment Variables:

• DEPLOYMENT_CONFIG_TEMPLATE_FILE: Custom path for the template file.
• DEPLOYMENT_CONFIG_FILE: Custom path for the generated deployment manifest.
• CONFIG_OUTPUT_DIR: Custom directory for the config output.

Starting with version 0.82.0, the CLI uses a categorized command structure. Commands are organized into four main categories: docker, iothub, simulator, and solution.

Most commands follow the pattern: iotedgedev <category> <command> --<parameter>.

Some frequently used commands have top-level shortcuts (e.g., iotedgedev add) to provide backward compatibility and ease of use, provided they do not cause ambiguity.

# Standard categorized command
iotedgedev solution add --template python

# Shortcut command
iotedgedev add --template python

By default, virtualenv uses your system's default Python version. To create an environment using a different Python executable, use the --python or -p option followed by the path to the desired Python binary.

Example for creating a Python 2.7 environment named py27: virtualenv --python /usr/bin/python2.7 py27

Use iotedgedev init <folder_name> to create a new solution and set up Azure resources in a single command. This command runs both iotedgedev new <folder_name> and iotedgedev iothub setup.

• If <folder_name> is omitted, it defaults to the current directory (.).
• By default, it adds a C# module named filtermodule. You can customize this using --module <module-name> and --template <template>.

To use an existing IoT Hub and IoT Edge device instead of creating new ones, run iotedgedev new . and manually update the .env file with your IOT_HUB_CONNECTION_STRING and DEVICE_CONNECTION_STRING.

iotedgedev init <folder_name>

# Example with custom module
iotedgedev init my_solution --module my_custom_module --template python

# Using existing resources
iotedgedev new .

You can host the IoT Edge runtime using your own Azure Container Registry (ACR) or a local registry. To do this, set the appropriate container registry values in your .env file, then run the docker setup-registry command. This command pulls all IoT Edge containers from the Microsoft Container Registry, tags them, and pushes them to your specified registry.

Note: On Linux or Raspberry Pi, you must prefix the command with sudo.

# For Linux/Raspberry Pi
sudo iotedgedev docker setup-registry

# For other platforms
iotedgedev docker setup-registry