This project provides new and exciting IoT commands and capabilities focused around the IoT Hub and IoT Device Provisioning services. Functionality is provided as an Azure CLI extension package for seamless integration with existing command-line functionality.
NEW 9/14/18 - In order to satisfy new CI linter rules for the Azure CLI, we have replaced multi-character short options (like '-props', or '-pri') with long option versions ('--props', '--pri').
The option names have not changed, but to fix any existing scripts, please use the '--' prefix for any command options that are not single characters. Single character options such as '-l', '-n', and '-d' are unaffected.
The extension augments the vanilla Azure CLI IoT by adding to or modifying the existing command space. The extension includes capabilities in the following categories:
- IoT Hub
- IoT Edge
- IoT Device Provisioning Service (DPS)
The extension is designed to be plug-and-play with Azure CLI. Even if you have Azure CLI installed make sure it is up to date.
❗ For installation troubleshooting please go to the respective docs section for help.
Before installation ensure that your Azure CLI version meets the following criteria. The criteria differs based on OS and method of installation. Use az --version to determine the CLI version.
In all cases your CLI needs to be at least v2.0.24.
| CLI Install Method | NOT compatible with |
|---|---|
| Windows via MSI | v2.0.34 to v2.0.38 |
| Windows via PIP, Linux or macOS | v2.0.34 to v2.0.36 |
Validate that your Azure CLI version is compatible.
Common Az CLI extension operations
Add: az extension add --name azure-cli-iot-ext
List: az extension list
Update: az extension update --name azure-cli-iot-ext
Remove: az extension remove --name azure-cli-iot-ext
At a minimum your CLI core version must be within the compatibility criteria defined above.
Follow the installation instructions on GitHub or Microsoft Docs to setup Azure CLI in your environment.
Now that you have a compatible Azure CLI installed you can add the IoT extension. When you install an extension, any additional Python dependencies required are automatically downloaded and installed.
There are multiple options for installation. After installing the extension, you can use az extension list to validate the currently installed extensions or az extension show --name azure-cli-iot-ext to see details about the IoT extension.
In all cases, make sure the IoT extension is version 0.3.2 or greater.
Install the extension from the official Microsoft Azure CLI Extension Index
az extension add --name azure-cli-iot-ext
- You can use
az extension list-availableto see all available extensions on the index - It is possible to update an extension in place using
az extension update --name <extension name>
Navigate to this project's release tab in GitHub to see the list of releases. Run the extension add command using the --source parameter.
The argument for the source parameter is either the URL download path (the extension package ends with '.whl') of your chosen release, or the local path to the extension where you downloaded the release package.
az extension add --source <local file path to release.whl OR url for release.whl>
For example, to install version 0.3.2
az extension add --source 'https://github.com/Azure/azure-iot-cli-extension/releases/download/v0.3.2/azure_cli_iot_ext-0.3.2-py2.py3-none-any.whl'
You can create a wheel package locally from source to be used in Azure CLI.
To build the wheel locally, ensure you have the Python wheel package installed i.e. pip install wheel. Then run python setup.py bdist_wheel where the current directory is the extension root. The wheel (with .whl suffix) will be generated and available in the new dist folder.
Now follow the local package installation method.
Your subscription details are used to interact with target resources.
You can login interactively, pass in account credentials, or use a service principal with password/certificate options.
More details about Azure CLI authentication.
If you have any suggestions or find bugs, please let us know.
To remove the extension at any time, you can use az extension remove --name azure-cli-iot-ext.
❗ For installation troubleshooting please go to the respective docs section for help.
The Microsoft Docs extensions reference are updated per release.
-
Many commands require the default policy to exist on the target resource which is being manipulated. For example IoT Hub based commands commonly look for the iothubowner policy. This behavior will change in a future update.
-
For command parameters that take JSON, for example the
az iot hub device-twin updatecommand's--setparameter, the JSON input format is different between CMD/PowerShell and Bash-like shells.
Please read the Tips Wiki page for more detail and to maximize the functionality and enjoyment out of the IoT extension.
Jump start your Azure IoT automation experience by checking out example automation scripts using the IoT extension!
Extension development depends on a local Azure CLI dev environment. First, follow these instructions to prepare your machine.
Next, update your AZURE_EXTENSION_DIR environment variable to a target extension deployment directory. This overrides the standard extension directory.
Example export AZURE_EXTENSION_DIR=~/.azure/devcliextensions/
Run the following command to setup and install all dependencies in the extension deployment directory.
pip install -U --target <extension deployment directory>/azure-cli-iot-ext <iot extension code root>
Repeat the above command as needed.
At this point, assuming the setup is good the extension should be loaded and you should see the extension command space. Use az --debug and az extension list for debugging this step.
Helpful Reference docs for Az CLI Extension development
Update the PYTHONPATH environment variable with both the extension dev deployment directory and root for the extension source code.
Example export PYTHONPATH=~/.azure/devcliextensions/azure-cli-iot-ext/:~/source/azure-cli-iot-ext/
Current testing patterns make use of pytest and unittest. We also use pytest-mock and pytest-cov plugins for pytest so make sure you pip install these dependencies beforehand. You can leverage our requirements file at the root of this project to install from.
After obtaining the above, ensure you have activated your Python virtual environment and your extension deployment directory is prepared.
Hub:
pytest <extension root>/azext_iot/tests/test_iot_ext_unit.py
DPS:
pytest <extension root>/azext_iot/tests/test_iot_dps_unit.py
Currently integration tests leverage Azure CLI live scenario tests. Update the following environment variables OR use an updated pytest.ini (copying and renaming pytest.ini.example) in the extension root directory prior to running integration tests.
These variables are shared between Hub and DPS integration tests:
AZURE_TEST_RUN_LIVE # Set to 'True' to hit live endpoints.
azext_iot_testrg # Target resource group for tests.
azext_iot_testhub # Target IoT Hub for respective category of tests.
Now you can run Hub integration tests:
pytest <extension root>/azext_iot/tests/test_iot_ext_int.py
Optionally set azext_iot_teststorageuri to your empty blob container sas uri to test device export and enable file upload test. For file upload, you will need to have configured your IoT Hub before running.
For DPS update the following environment variable prior to running.
azext_iot_testdps # Target IoT Hub DPS for respective category of tests.
Now you can run DPS integration tests:
pytest <extension root>/azext_iot/tests/test_iot_dps_int.py
At this point if your environment has been setup to execute all tests, you can leverage pytest discovery to run all tests and provide a coverage report.
pytest -v <extension root> --cov=azext_iot --cov-config <extension root>/.coveragerc
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.