Azure
/
iotedgedev
зеркало из https://github.com/Azure/iotedgedev.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Merge branch 'master' into feature/add-device-tagging

This commit is contained in:
Tamara Rahimi 2021-09-03 07:46:15 +00:00
Родитель 49caf1f288 ccd767a7cd
Коммит 2841d7b8e9
20 изменённых файлов: 1422 добавлений и 8 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

2
.devcontainer/Dockerfile
Просмотреть файл

@ -54,8 +54,6 @@ RUN \
rm -rf /tmp/* && \ rm -rf /tmp/* && \
rm -rf /var/lib/apt/lists/* rm -rf /var/lib/apt/lists/*
# Customize bash # Customize bash
RUN \ RUN \
# Git command prompt # Git command prompt

3
.devcontainer/devcontainer.json
Просмотреть файл

@ -27,5 +27,8 @@
"ms-azuretools.vscode-docker", "ms-azuretools.vscode-docker",
"redhat.vscode-yaml", "redhat.vscode-yaml",
"mikestead.dotenv", "mikestead.dotenv",
"streetsidesoftware.code-spell-checker",
"yzhang.markdown-all-in-one",
"davidanson.vscode-markdownlint"
] ]
} }

54
.github/workflows/wiki.yml поставляемый Normal file
Просмотреть файл

@ -0,0 +1,54 @@
name: Update wiki
on:
push:
branches: [master]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Push documentation changes to wiki
env:
EMAIL: actions@github.com
USER_NAME: Github Actions
REPO_DEST: iotedgedev.wiki
REPO_DEST_URL: github.com/Azure/iotedgedev.wiki.git
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
set -e
# Save iotedgedev repo folder path
REPO_SOURCE=$(pwd)
# Exit iotedgedev repo folder
cd ..
# Clone repositories
git clone https://${REPO_DEST_URL}
# Update wiki repository with documentation folder contents
cd ${REPO_DEST}
git rm -rf .
git clean -fxd
yes 2>/dev/null | cp -rf ${REPO_SOURCE}/docs/* .
git reset
# If changes found, commit and push them
if git diff-index HEAD && [ ! -n "$(git status -s)" ]; then
git status
echo "No changes found in /docs. Exiting..."
else
git status
echo "Changes found in /docs. Committing and pushing..."
git config user.email ${EMAIL}
git config user.name ${USER_NAME}
git add .
git commit -m "Update documentation | From github actions number: ${GITHUB_RUN_ID}"
git push "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@${REPO_DEST_URL}"
fi

12
.vscode/settings.json поставляемый
Просмотреть файл

@ -2,7 +2,17 @@
"python.pythonPath": "${workspaceFolder}\\venv\\Scripts\\python.exe", "python.pythonPath": "${workspaceFolder}\\venv\\Scripts\\python.exe",
"cSpell.words": [ "cSpell.words": [
"dotenv", "dotenv",
"envvar" "envvar",
"edgesolution",
"gitignore",
"iotedge",
"iotedgedev",
"iothub",
"mkdir",
"posix",
"quickstart",
"venv",
"virtualenv"
], ],
"python.linting.enabled": true, "python.linting.enabled": true,
"python.linting.pylintEnabled": false, "python.linting.pylintEnabled": false,

102
docs/Azure-Setup.md Normal file
Просмотреть файл

@ -0,0 +1,102 @@
#### 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 new edgesolution1`
Then, `cd` into that solution:
`cd edgesolution`
Then, run the `iotedgedev iothub setup` 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 `iotedgedev iothub setup` command options:
> You can override all of these parameters with environment variables. Please see the .env file in your solution for details.
```
iotedgedev iothub setup
--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 iothub setup` 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:
[![Azure Deployment](https://azuredeploy.net/deploybutton.png)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure%2Fiotedgedev%2Fmaster%2Fassets%2Fdeploy%2FARMDeployment%2Fazuredeploy.json)
> Note: If you do not need a Container Registry, or are planning to use a local registry, then you should run the **iotedgedev iothub setup** command instead of running this **Deploy to Azure** template, because the template includes a Container Registry.
#### Manual Setup
1. [**Create Azure IoT Hub**](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-csharp-csharp-getstarted#create-an-iot-hub)
1. **Create Edge Device** using the Azure Portal
- In your IoT Hub, click "IoT Edge", then click "Add IoT Edge Device"
1. **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 modules 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` and `CONTAINER_REGISTRY_PASSWORD` blank.
```
CONTAINER_REGISTRY_SERVER="localhost:5000"
```
1. Azure Container Registry
You can create an [**Azure Container Registry**](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-get-started-portal) 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"
```
1. 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"
```

544
docs/Command-List.md Normal file
Просмотреть файл

@ -0,0 +1,544 @@
# Commands
## iotedgedev
```text
Usage: iotedgedev [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
add Add a new module to the solution
build Build the solution
deploy Deploy solution to IoT Edge device
genconfig Expand environment variables and placeholders in deployment manifest template file and copy to config folder
init Create a new IoT Edge solution and provision Azure resources
log Open a new terminal window for EdgeAgent, EdgeHub and each Edge module and save to LOGS_PATH
monitor Monitor messages from IoT Edge device to IoT Hub
new Create a new IoT Edge solution
push Push module images to container registry
setup Setup IoT Edge simulator. This must be done before starting
start Start IoT Edge simulator
stop Stop IoT Edge simulator
docker Manage Docker
iothub Manage IoT Hub and IoT Edge devices
simulator Manage IoT Edge simulator
solution Manage IoT Edge solutions
```
## iotedgedev add
```text
Usage: iotedgedev add [OPTIONS] NAME
Add a new module to the solution, where NAME is the module name
Options:
-t, --template [c|csharp|java|nodejs|python|csharpfunction]
Specify the template used to create the default module [default: csharp]
-g, --group-id TEXT (Java modules only) Specify the groupId [default: com.edgemodule]
-h, --help Show this message and exit.
```
## iotedgedev build
```text
Usage: iotedgedev build [OPTIONS]
Build the solution
Options:
-p, --push Push module images to container registry [default: False]
-d, --deploy Deploy modules to Edge device using deployment.json in the config folder [default: False]
-f, --file TEXT Specify the deployment manifest template file [default: deployment.template.json]
-P, --platform TEXT Specify the platform [default: amd64]
-h, --help Show this message and exit.
```
## iotedgedev deploy
```text
Usage: iotedgedev deploy [OPTIONS]
Deploy solution to IoT Edge device
Options:
-f, --file TEXT Specify the deployment manifest file [default: config\deployment.amd64.json]
-h, --help Show this message and exit.
```
## iotedgedev genconfig
```text
Usage: iotedgedev genconfig [OPTIONS]
Expand environment variables and placeholders in deployment manifest
template file and copy to config folder
Options:
-f, --file TEXT Specify the deployment manifest template file [default: deployment.template.json]
-P, --platform TEXT Specify the platform [default: amd64]
-h, --help Show this message and exit.
```
## iotedgedev init
```text
Usage: iotedgedev init [OPTIONS]
Create a new IoT Edge solution and provision Azure resources
Options:
-er, --edge-runtime-version TEXT
Specify the IoT Edge Runtime Version. Currently available 1.0 and 1.1 [default: 1.1]
-m, --module TEXT Specify the name of the default module [default: filtermodule]
-t, --template [c|csharp|java|nodejs|python|csharpfunction]
Specify the template used to create the default module [default: csharp]
-g, --group-id TEXT (Java modules only) Specify the groupId [default: com.edgemodule]
-h, --help Show this message and exit.
```
## iotedgedev log
```text
Usage: iotedgedev log [OPTIONS]
Open a new terminal window for EdgeAgent, EdgeHub and each Edge module and
save to LOGS_PATH. You can configure the terminal command with LOGS_CMD.
Options:
-l, --show Open a new terminal window for EdgeAgent, EdgeHub and each Edge module. You can configure the terminal command with LOGS_CMD. [default: False]
-s, --save Save EdgeAgent, EdgeHub and each Edge module logs to LOGS_PATH. [default: False]
-h, --help Show this message and exit.
```
## iotedgedev monitor
```text
Usage: iotedgedev monitor [OPTIONS]
Monitor messages from IoT Edge device to IoT Hub
Options:
-t, --timeout TEXT Specify number of seconds to monitor for messages
-h, --help Show this message and exit.
```
## iotedgedev new
```text
Usage: iotedgedev new [OPTIONS] NAME
Create a new IoT Edge solution, where NAME is the solution folder name.
Use "." as NAME to create in the current folder.
Options:
-m, --module TEXT Specify the name of the default module [default: filtermodule]
-t, --template [c|csharp|java|nodejs|python|csharpfunction]
Specify the template used to create the default module [default: csharp]
-g, --group-id TEXT (Java modules only) Specify the groupId [default: com.edgemodule]
-h, --help Show this message and exit.
```
## iotedgedev push
```text
Usage: iotedgedev push [OPTIONS]
Push module images to container registry
Options:
-d, --deploy Deploy modules to Edge device using deployment.json in the config folder [default: False]
--no-build Inform the push command to not build module images before pushing to container registry [default: False]
-f, --file TEXT Specify the deployment manifest template file [default: deployment.template.json]
-P, --platform TEXT Specify the platform [default: amd64]
-h, --help Show this message and exit.
```
## iotedgedev setup
```text
Usage: iotedgedev setup [OPTIONS]
Setup IoT Edge simulator. This must be done before starting
Options:
-g, --gateway-host TEXT GatewayHostName value for the module to connect. [default: <your hostname>]
-h, --help Show this message and exit.
```
## iotedgedev start
```text
Usage: iotedgedev start [OPTIONS]
Start IoT Edge simulator. To start in solution mode, use `iotedgdev
simulator start -s [-v] [-b]`. To start in single module mode, use
`iotedgedev simulator start -i input1,input2 [-p 53000]`
Options:
-u, --setup Setup IoT Edge simulator before starting. [default: False]
-s, --solution Start IoT Edge simulator in solution mode using the deployment.json in config folder. [default: False]
-v, --verbose Show the solution container logs. [default: False]
-b, --build Build the solution before starting IoT Edge simulator in solution mode. [default: False]
-f, --file TEXT Specify the deployment manifest file. When `--build` flag is set, specify a deployment manifest template and it will be built. [default: config\deployment.amd64.json]
-P, --platform TEXT Specify the platform [default: amd64]
-i, --inputs TEXT Start IoT Edge simulator in single module mode using the specified comma-separated inputs of the target module, e.g., `input1,input2`.
-p, --port INTEGER Port of the service for sending message. [default: 53000]
-h, --help Show this message and exit.
```
## iotedgedev stop
```text
Usage: iotedgedev stop [OPTIONS]
Stop IoT Edge simulator
Options:
-h, --help Show this message and exit.
```
## iotedgedev docker
```text
Usage: iotedgedev docker [OPTIONS] COMMAND [ARGS]...
Manage Docker
Options:
-h, --help Show this message and exit.
Commands:
clean Remove all the containers and images
log Open a new terminal window for EdgeAgent, EdgeHub and each Edge module and save to LOGS_PATH
setup Pull Edge runtime images from MCR and push to your specified container registry
```
## iotedgedev docker clean
```text
Usage: iotedgedev docker clean [OPTIONS]
Remove all the containers and images
Options:
-m, --module Remove only the Edge module containers and images, not
EdgeAgent or EdgeHub [default: False]
-c, --container Remove all the containers [default: False]
-i, --image Remove all the images [default: False]
-h, --help Show this message and exit.
```
## iotedgedev docker log
```text
Usage: iotedgedev docker log [OPTIONS]
Open a new terminal window for EdgeAgent, EdgeHub and each Edge module and
save to LOGS_PATH. You can configure the terminal command with LOGS_CMD.
Options:
-l, --show Open a new terminal window for EdgeAgent, EdgeHub and each Edge module. You can configure the terminal command with LOGS_CMD. [default: False]
-s, --save Save EdgeAgent, EdgeHub and each Edge module logs to LOGS_PATH. [default: False]
-h, --help Show this message and exit.
```
## iotedgedev docker setup
```text
Usage: iotedgedev docker setup [OPTIONS]
Pull Edge runtime images from Microsoft Container Registry and push to
your specified container registry. Also, update config files to use
CONTAINER_REGISTRY_* instead of the Microsoft Container Registry. See
CONTAINER_REGISTRY environment variables.
Options:
-h, --help Show this message and exit.
```
## iotedgedev iothub
```text
Usage: iotedgedev iothub [OPTIONS] COMMAND [ARGS]...
Manage IoT Hub and IoT Edge devices
Options:
-h, --help Show this message and exit.
Commands:
deploy Create a deployment in IoT Hub
monitor Monitor messages from IoT Edge device to IoT Hub
setup Retrieve or create required Azure resources
```
## iotedgedev iothub deploy
```text
Usage: iotedgedev iothub deploy [OPTIONS]
Create a deployment in IoT Hub. For more information on how automatic deployments work see:
https://docs.microsoft.com/en-us/azure/iot-edge/module-deployment-monitoring
Options:
-f, --file TEXT Specify the deployment manifest file [default: config/deployment.amd64.json]
-n, --name TEXT Specify the name of the deployment that will be created in the IoT hub. [required]
-p, --priority TEXT Specify the deployment priority as positive integer. In the event that two or more
deployments are targeted at the same device, the deployment with the highest
numerical value for Priority will apply. [required]
-t, --target-condition, --tc TEXT
Specify a target condition to determine which devices will be targeted with this
deployment. The condition is based on device twin tags or device twin reported
properties and should match the expression format. For example,
tags.environment='test' and properties.reported.devicemodel='4000x'. This property
can be set via this parameter or in the .env under
'IOTHUB_DEPLOYMENT_TARGET_CONDITION' [default: ;required]
-h, --help Show this message and exit.
```
## iotedgedev iothub monitor
```text
Usage: iotedgedev iothub monitor [OPTIONS]
Monitor messages from IoT Edge device to IoT Hub
Options:
-t, --timeout TEXT Specify number of seconds to monitor for messages
-h, --help Show this message and exit.
```
## iotedgedev iothub setup
```text
Usage: iotedgedev iothub setup [OPTIONS]
Retrieve or create required Azure resources
Options:
--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]
-u, --update-dotenv If True, the current .env will be updated with the IoT Hub and Device connection strings. [default: False; required]
-h, --help Show this message and exit.
```
## iotedgedev simulator
```text
Usage: iotedgedev simulator [OPTIONS] COMMAND [ARGS]...
Manage IoT Edge simulator
Options:
-h, --help Show this message and exit.
Commands:
modulecred Get the credentials of target module such as connection string and certificate file path.
setup Setup IoT Edge simulator. This must be done before starting
start Start IoT Edge simulator
stop Stop IoT Edge simulator
```
## iotedgedev simulator modulecred
```text
Usage: iotedgedev simulator modulecred [OPTIONS]
Get the credentials of target module such as connection string and
certificate file path.
Options:
-l, --local Set `localhost` to `GatewayHostName` for module to run on host natively. [default: False]
-o, --output-file TEXT Specify the output file to save the credentials. If the file exists, its content will be overwritten.
-h, --help Show this message and exit.
```
## iotedgedev simulator setup
```text
Usage: iotedgedev simulator setup [OPTIONS]
Setup IoT Edge simulator. This must be done before starting
Options:
-g, --gateway-host TEXT GatewayHostName value for the module to connect.
[default: <your hostname>]
-h, --help Show this message and exit.
```
## iotedgedev simulator start
```text
Usage: iotedgedev simulator start [OPTIONS]
Start IoT Edge simulator. To start in solution mode, use `iotedgdev
simulator start -s [-v] [-b]`. To start in single module mode, use
`iotedgedev simulator start -i input1,input2 [-p 53000]`
Options:
-u, --setup Setup IoT Edge simulator before starting. [default: False]
-s, --solution Start IoT Edge simulator in solution mode using the deployment.json in config folder. [default: False]
-v, --verbose Show the solution container logs. [default: False]
-b, --build Build the solution before starting IoT Edge simulator in solution mode. [default: False]
-f, --file TEXT Specify the deployment manifest file. When `--build` flag is set, specify a deployment manifest template and it will be built. [default: config\deployment.amd64.json]
-P, --platform TEXT Specify the platform [default: amd64]
-i, --inputs TEXT Start IoT Edge simulator in single module mode using the specified comma-separated inputs of the target module, e.g., `input1,input2`.
-p, --port INTEGER Port of the service for sending message. [default: 53000]
-h, --help Show this message and exit.
```
## iotedgedev simulator stop
```text
Usage: iotedgedev simulator stop [OPTIONS]
Stop IoT Edge simulator
Options:
-h, --help Show this message and exit.
```
## iotedgedev solution
```text
Usage: iotedgedev solution [OPTIONS] COMMAND [ARGS]...
Manage IoT Edge solutions
Options:
-h, --help Show this message and exit.
Commands:
add Add a new module to the solution
build Build the solution
deploy Deploy solution to IoT Edge device
e2e Push, deploy, start, monitor
genconfig Expand environment variables and placeholders in deployment manifest template file and copy to config folder
init Create a new IoT Edge solution and provision Azure resources
new Create a new IoT Edge solution
push Push module images to container registry
```
## iotedgedev solution add
```text
Usage: iotedgedev solution add [OPTIONS] NAME
Add a new module to the solution, where NAME is the module name
Options:
-t, --template [c|csharp|java|nodejs|python|csharpfunction]
Specify the template used to create the default module [default: csharp]
-g, --group-id TEXT (Java modules only) Specify the groupId [default: com.edgemodule]
-h, --help Show this message and exit.
```
## iotedgedev solution build
```text
Usage: iotedgedev solution build [OPTIONS]
Build the solution
Options:
-p, --push Push module images to container registry [default: False]
-d, --deploy Deploy modules to Edge device using deployment.json in the config folder [default: False]
-f, --file TEXT Specify the deployment manifest template file [default: deployment.template.json]
-P, --platform TEXT Specify the platform [default: amd64]
-h, --help Show this message and exit.
```
## iotedgedev solution deploy
```text
Usage: iotedgedev solution deploy [OPTIONS]
Deploy solution to IoT Edge device
Options:
-f, --file TEXT Specify the deployment manifest file [default: config\deployment.amd64.json]
-h, --help Show this message and exit.
```
## iotedgedev solution e2e
```text
Usage: iotedgedev solution e2e [OPTIONS]
Push, deploy, start, monitor
Options:
-h, --help Show this message and exit.
```
## iotedgedev solution genconfig
```text
Usage: iotedgedev solution genconfig [OPTIONS]
Expand environment variables and placeholders in deployment manifest
template file and copy to config folder
Options:
-f, --file TEXT Specify the deployment manifest template file [default: deployment.template.json]
-P, --platform TEXT Specify the platform [default: amd64]
-h, --help Show this message and exit.
```
## iotedgedev solution init
```text
Usage: iotedgedev solution init [OPTIONS]
Create a new IoT Edge solution and provision Azure resources
Options:
-m, --module TEXT Specify the name of the default module [default: filtermodule]
-t, --template [c|csharp|java|nodejs|python|csharpfunction]
Specify the template used to create the default module [default: csharp]
-g, --group-id TEXT (Java modules only) Specify the groupId [default: com.edgemodule]
-h, --help Show this message and exit.
```
## iotedgedev solution new
```text
Usage: iotedgedev solution new [OPTIONS] NAME
Create a new IoT Edge solution, where NAME is the solution folder name.
Use "." as NAME to create in the current folder.
Options:
-m, --module TEXT Specify the name of the default module [default: filtermodule]
-t, --template [c|csharp|java|nodejs|python|csharpfunction]
Specify the template used to create the default module [default: csharp]
-g, --group-id TEXT (Java modules only) Specify the groupId [default: com.edgemodule]
-h, --help Show this message and exit.
```
## iotedgedev solution push
```text
Usage: iotedgedev solution push [OPTIONS]
Push module images to container registry
Options:
-d, --deploy Deploy modules to Edge device using deployment.json in the config folder [default: False]
--no-build Inform the push command to not build module images before pushing to container registry [default: False]
-f, --file TEXT Specify the deployment manifest template file [default: deployment.template.json]
-P, --platform TEXT Specify the platform [default: amd64]
-h, --help Show this message and exit.
```

51
docs/Command-Tips.md Normal file
Просмотреть файл

@ -0,0 +1,51 @@
### Setup Container Registry
You can also use IoT Edge Dev Tool 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 Microsoft Container Registry, tag them and push them to the container registry you have specified in `.env`.
> Use 'sudo' for Linux/Raspberry Pi
```
iotedgedev docker setup-registry
```
### View Docker Logs
#### Show Logs
IoT Edge Dev Tool also includes 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 log --show
```
You can configure the logs command in the `.env` file with the `LOGS_CMD` setting. The `.env` file provides two options, one for [ConEmu](https://conemu.github.io/) 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 log --save
```
#### Both Show and Save Logs
Run the following to show and save logs with a single command
```
iotedgedev docker log --show --save
```
### 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` file to `localhost:5000`. You can enter a different port if you'd like to.
1. Add `localhost:5000` and `127.0.0.1:5000` to Docker -> Settings -> Daemon -> Insecure Registries
> In the latest IoT Edge Dev Tool, Step 2 above hasn't been required. But, if you run into issues, you may want to try adding those Insecure Registries.
IoT Edge Dev Tool will look for `localhost` in your setting and take care of the rest for you.

23
docs/Edge-Device-Setup.md Normal file
Просмотреть файл

@ -0,0 +1,23 @@
IoT Edge Dev Tool 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 IoT Edge runtime directly. Please check below documents for the instructions on setting up IoT Edge runtime:
- [Linux X64](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge-linux)
- [Linux ARM32](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge-linux-arm)
- [Windows with Windows container](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge-windows-with-windows)
- [Windows with Linux container](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge-windows-with-linux)
- [IoT Core](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-core)
Having said that, there's nothing stopping you from deploying IoT Edge Dev Tool 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 log --show` to see all the log files on the device or `iotedgedev docker log --save` to output to the LOGS_PATH directory.
> Please note that you will need .NET Core SDK 2.1 to add C# modules and C# Function modules on a Raspberry Pi. Check [Manual Dev Machine Setup](manual-dev-machine-setup#c-module-and-c-azure-functions-module) to learn how to install.
### Raspberry Pi
##### Config Changes
If you are running on Raspberry Pi you need to use the arm32v7 Dockerfile. Open `deployment.template.json`, find the JSON dictionary for `filtermodule`, and replace `"image": "${MODULES.filtermodule.amd64}",` with `"image": "${MODULES.filtermodule.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"
```

10
docs/Home.md Normal file
Просмотреть файл

@ -0,0 +1,10 @@
Welcome to the IoT Edge Dev Tool wiki!
The **IoT Edge Dev Tool** greatly simplifies [Azure IoT Edge](https:/azure.microsoft.com/en-us/services/iot-edge/) development down to simple commands driven by environment variables.
- It gets you started with IoT Edge development with the [IoT Edge Dev Container](quickstart-with-iot-edge-dev-container) and IoT Edge solution scaffolding that contains a default 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 as well as drives your outer-loop CI/CD pipeline. _You can use all the same commands in both stages of your development life-cycle._
## Issues
Please use the [GitHub issues page](https://github.com/azure/iotedgedev/issues) to report any issues.

77
docs/Manual-Dev-Machine-Setup.md Normal file
Просмотреть файл

@ -0,0 +1,77 @@
Here is what you need to do to get Azure IoT Edge Dev Tool (aka `iotedgedev`) running on your dev machine manually instead of using the IoT Edge Dev Container.
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 install and setup Edge runtime directly on the device. See the [Edge Device Setup](edge-device-setup) wiki page for more information on setting up your Edge device.
> Note: See the ["Test Coverage"](test-coverage) wiki page to see what the IoT Edge Dev Tool has been tested with.
1. Install **[Docker](https://docs.docker.com/engine/installation/)**
- Windows
- Be sure to check whether you are running in Linux container mode or Windows container mode.
- 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](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/#install-docker-ce), or use the [convenience script](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/#install-using-the-convenience-script).
- By default, you need `sudo` to run `docker` commands. If you want to avoid this, please follow the [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user).
1. Install **Python 2.7+ or Python 3.6+** and **pip** (Python 3.6 is recommended)
- Windows: [Install from Python's website](https://www.python.org/downloads/)
- Linux: `sudo apt install python-pip` or `sudo apt install python3-pip`
- macOS: The OpenSSL used by the system built-in Python is old and vulnerable. Please use Python installed with [Homebrew](https://docs.brew.sh/Homebrew-and-Python)
1. Install **[Azure CLI 2.0](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)**
1. Install **[Azure CLI IoT extension](https://github.com/Azure/azure-iot-cli-extension/)**
- New Install: `az extension add --name azure-cli-iot-ext`
- Update Install: `az extension update --name azure-cli-iot-ext`
1. (Python < 3.5 only) Install **[Node.js](https://nodejs.org/en/download/)** and the **`iothub-explorer`** package
- uamqp, which is needed by Azure CLI IoT extension for monitoring messages, is not supported in Python < 3.5. For Python < 3.5 users, please install [Node.js](https://nodejs.org/en/download/) and the `iothub-explorer` Node.js package: `npm i -g iothub-explorer`
1. (Raspberry Pi only) Install extra system dependencies
```
sudo apt-get install python2.7-dev libffi-dev libssl-dev -y
```
1. (Linux only) Install [Docker Compose](https://docs.docker.com/compose/)
```
pip install -U docker-compose
```
1. Install **`iotedgedev`**
> You do not need to run this on the Edge device. See the [Edge Device Setup](edge-device-setup) page for more information on setting up your Edge device.
> You can also run under a Python Virtual Environment. See the [Python Virtual Environment Setup](python-virtual-environment-setup) instructions page for details on how to set that up.
> There is a known dependency conflict between `iotedgedev` and now-deprecated `azure-iot-edge-runtime-ctl`. Please make sure you have uninstalled `azure-iot-edge-runtime-ctl` before installing `iotedgedev`: `pip uninstall azure-iot-edge-runtime-ctl `, or use a clean virtual environment.
```
pip install -U iotedgedev
```
1. Install module dependencies
##### C# module and C# Azure Functions module
Install **[.NET Core SDK](https://www.microsoft.com/net/download)**.
> You need .NET Core SDK 2.1 or later to run it on ARM. There is no official document on installing .NET Core SDK on ARM yet, but you can follow the [ARM32v7 Dockerfile](https://github.com/dotnet/dotnet-docker/blob/master/src/sdk/3.1/buster/arm32v7/Dockerfile).
##### Python module
1. Install **[Git](https://git-scm.com/)**
2. Install **[Cookiecutter](https://github.com/audreyr/cookiecutter)**
```
pip install -U cookiecutter
```
##### Node.js module
1. Install **[Node.js](https://nodejs.org/en/download/)**
2. Install **[Yeoman](http://yeoman.io/)** and **[Azure IoT Edge Node.js module generator](https://github.com/Azure/generator-azure-iot-edge-module)** packages
```
npm i -g yo generator-azure-iot-edge-module
```
##### Java module
1. Install **[JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html)**
1. Install **[Maven](https://maven.apache.org/)**
1. Follow the [Usage Wiki](usage) to learn the usage of IoT Edge Dev Tool

131
docs/Migration-Guides.md Normal file
Просмотреть файл

@ -0,0 +1,131 @@
IoT Edge Dev Tool 0.82.0 provides support for the GA release of Azure IoT Edge and other new features, while on the other hand, introduces some breaking changes to better serve these new features. If you have used IoT Edge Dev Tool during the Azure IoT Edge public preview, this document will help you migrate your code and workflow to IoT Edge Dev Tool 0.82.0.
### Retirement of `iotedgectl`
With the GA release of Azure IoT Edge, iotedgectl (a.k.a, [azure-iot-edge-runtime-ctl](https://pypi.org/project/azure-iot-edge-runtime-ctl/)) is retired. In IoT Edge Dev Tool 0.82.0, we replace `iotedgectl` with the IoT Edge Simulator provided by the [iotedgehubdev CLI](https://pypi.org/project/iotedgehubdev/). The `setup`, `start`, and `stop` commands will now control IoT Edge Simulator instead.
### Updated command list and options
IoT Edge Dev Tool 0.82.0 comes with a new CLI UX. All commands are organized into four categories: `docker`, `iothub`, `simulator`, and `solution`. The general style is **iotedgedev _category_ _command_ --_parameter_**. For some frequently used commands, there is also an **iotedgedev _command_ --_parameter_** style shortcut (only if the shortcut won't cause confusion, similar to the relationship between `docker logs` and `docker container logs`). The shortcuts also add backward compatibility with some public preview style commands.
Here is what you would see when you type `iotedgedev --help` (shortcuts are intentionally listed before the categories):
```
$ iotedgedev --help
Usage: iotedgedev [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
add Add a new module to the solution
build Build the solution
deploy Deploy solution to IoT Edge device
genconfig Expand environment variables and placeholders in *.template.json
and copy to config folder
init Create a new IoT Edge solution and provision Azure resources
log Open a new terminal window for EdgeAgent, EdgeHub and each Edge
module and save to LOGS_PATH
monitor Monitor messages from IoT Edge device to IoT Hub
new Create a new IoT Edge solution
push Push module images to container registry
setup Setup IoT Edge simulator. This must be done before starting
start Start IoT Edge simulator
stop Stop IoT Edge simulator
docker Manage Docker
iothub Manage IoT Hub and IoT Edge devices
simulator Manage IoT Edge simulator
solution Manage IoT Edge solutions
```
Here is the help message for a category:
```
$ iotedgedev solution --help
Usage: iotedgedev solution [OPTIONS] COMMAND [ARGS]...
Manage IoT Edge solutions
Options:
-h, --help Show this message and exit.
Commands:
add Add a new module to the solution
build Build the solution
deploy Deploy solution to IoT Edge device
e2e Push, deploy, start, monitor
genconfig Expand environment variables and placeholders in *.template.json
and copy to config folder
init Create a new IoT Edge solution and provision Azure resources
new Create a new IoT Edge solution
push Push module images to container registry
```
Here is the help message for a specific command. Only the parameters relevant to the command are listed. In addition, parameter shortcuts are also added, like `-t` below for `--template`, whenever possible.
```
$ iotedgedev solution add --help
Usage: iotedgedev add [OPTIONS] NAME
Add a new module to the solution, where NAME is the module name
Options:
-t, --template [c|csharp|java|nodejs|python|csharpfunction]
Specify the template used to create the
default module [default: csharp]
-g, --group-id TEXT (Java modules only) Specify the groupId
[default: com.edgemodule]
-h, --help Show this message and exit.
```
Below is a full table of the public preview commands, new commands, and shortcuts (if applicable):
Public Preview Command | New Command | Shortcut
-- | -- | --
`--set-config` | `solution genconfig` | `genconfig `
`solution --create --module --template` | `solution new --module/-t --template/-t` | `new`
`init` | `solution init` | `init`
`e2e` | `solution e2e` |
`addmodule --template` | `solution add --template/-t` | `add --template/-t`
`build --push --deploy` | `solution build --push/-p --deploy/-d` | `build --push/-p --deploy/-d`
`push --deploy --no-build` | `solution push --deploy/-d --no-build` | `push --deploy/-d --no-build`
`deploy` | `solution deploy` | `deploy`
`monitor --timeout` | `iothub monitor --timeout/-t` | `monitor --timeout/-t`
`azure --setup --credentials --service-principal --subscription --resource-group-location --resource-group-name --iothub-sku --iothub-name --edge-device-id --update-dotenv` | `iothub setup --credentials --service-principal --subscription --resource-group-location --resource-group-name --iothub-sku --iothub-name --edge-device-id --update-dotenv/-u` |  
`modules --add --template` | `solution add --template` | `add --template/-t`
`modules --build --push --deploy` | `solution build --push/-p --deploy/-d` | `build --push/-p --deploy/-d`
`modules --push --deploy` | `solution push --deploy/-d --no-build` | `push --deploy/-d --no-build`
`modules --deploy` | `solution deploy` | `deploy`
`runtime --setup` | *deprecated, see [Retirement of `iotedgectl`](#retirement-of-iotedgectl) section* |  
`runtime --start` | *deprecated, see [Retirement of `iotedgectl`](#retirement-of-iotedgectl) section* |  
`runtime --stop` | *deprecated, see [Retirement of `iotedgectl`](#retirement-of-iotedgectl) section* |  
`runtime --restart` | *deprecated, see [Retirement of `iotedgectl`](#retirement-of-iotedgectl) section* |  
`runtime --status` | *deprecated, see [Retirement of `iotedgectl`](#retirement-of-iotedgectl) section* |  
`docker --setup-registry` | `docker setup` |  
`docker --clean --remove-modules --remove-containers --remove-images` | `docker clean --modules/-m --containers/-c --image/-i` |  
`docker --logs --show-logs --save-logs` | `docker log --show/-l --save/-s` | `docker log --show/-l --save/-s`
### Deployment manifest template
IoT Edge Dev Tool 0.82.0 relies on the deployment manifest template to build the solution (see [Deprecation of `ACTIVE_MODULES`](#deprecation-of-active_modules) section for details). By default, it's the `deployment.template.json` file in the root of the solution folder, but you can also customize it with the `DEPLOYMENT_CONFIG_TEMPLATE_FILE` environment variable. The major difference between deployment manifest template and deployment manifest is that module image URLs in deployment manifest template can be placeholders (whose format looks like `${MODULES.filtermodule.amd64}`). The image placeholders can help you easily update the referenced module and image platform without typing lengthy image URLs. When building solutions, IoT Edge Dev Tool will parse the image placeholders, expand them with the actual image URLs and save the results in the deployment manifest in the config output folder. By default, it's the `deployment.json` file in the `config` folder, but you can also customize it with the `DEPLOYMENT_CONFIG_FILE` and `CONFIG_OUTPUT_DIR` environment variables. In addition, when adding modules, IoT Edge Dev Tool will add a corresponding section for the module in the deployment manifest template with `${MODULES.<module-name>.amd64}` as the image.
To migrate your solutions created in the public preview to leverage the new build process, you can rename your deployment manifest, and update the images of the modules which you want to build with the corresponding image placeholders.
### New module folder structure
IoT Edge Dev Tool now calls module templates when adding new modules to the solution. For C# module developers, you don't need to execute `dotnet new` commands yourself. You only need to execute `iotedgedev add` command, specify the module name and template (for example, `csharp` or `csharpfunction`). IoT Edge Dev Tool will scaffold a new module from the template, save the module files in the `${MODULES_PATH}/<module-name>` folder (`modules/<module-name>` by default), and update the deployment manifest template for you. In each module folder, there are now four types of files:
* Module code files, for example, `Program.cs` and `*.csproj`
* Dockerfiles for each platform, for example, `Dockerfile.amd64`, `Dockerfile.amd64.debug` and `Dockerfile.arm32v7`
* `module.json` file which specifies the meta-data of the module, including image repository, mapping between platforms and Dockerfiles, and build options.
* Miscellaneous files, for example, `.gitignore`.
To migrate your modules created in the public preview to work with IoT Edge Dev Tool 0.82.0, you need to create a module.json file from [here](https://github.com/Azure/dotnet-template-azure-iot-edge-module/blob/master/content/dotnet-template-azure-iot-edge-module/CSharp/module.json), update the `repository` as the module image repository such as `myregistry.azurecr.io/filtermodule`, or with environment variable placeholders `${CONTAINER_REGISTRY_SERVER}/filtermodule`. Next you need to update the `platforms` dictionary to make sure that platform-Dockerfile mapping is correct. The built module image will have the tag format `<repository>:<version>-<platform>`, for example `myregistry.azurecr.io/filtermodule:0.0.1-amd64`.
### Building code in Dockerfiles
The recent releases of IoT Edge module templates ship with Dockerfiles which will build the code binaries in the containers. For example, C# module developers now don't need to run `dotnet build` or `dotnet publish` on their development machine. A single `docker build` command will build the binaries in the container and copy them to the final module image. You can check the C# module template Dockerfile [here](https://github.com/Azure/dotnet-template-azure-iot-edge-module/blob/master/content/dotnet-template-azure-iot-edge-module/CSharp/Dockerfile.amd64), which leverages Docker's [multi-stage build feature](https://docs.docker.com/develop/develop-images/multistage-build/). On the other hand, IoT Edge Dev Tool is continuously adding support for modules in more languages such as Node.js and Python, with diverse steps to build. As a result, the `iotedgedev build` command will only build the Dockerfiles, but not run language-specific building commands.
### Deprecation of `ACTIVE_MODULES`
With the full support of deployment manifest template for module management, IoT Edge Dev Tool 0.82.0 now comes with new logic of determining which Dockerfiles to build. The `ACTIVE_MODULES` environment variable will be replaced by the image placeholders (whose format looks like `${MODULES.filtermodule.amd64}`) in deployment manifest template, and the `BYPASS_MODULES` and `ACTIVE_DOCKER_PLATFORMS` environment variables jointly. IoT Edge Dev Tool will built a Dockerfile if it meets either of the following two requirements:
1. The module name is not in `BYPASS_MODULES`, and a module specifies `${MODULES.<module-name>.<platform>}` as its image in the deployment manifest template.
1. The module name is not in `BYPASS_MODULES`, and the platform is in `ACTIVE_DOCKER_PLATFORMS`.
The default value of `BYPASS_MODULES` and `ACTIVE_DOCKER_PLATFORM` are both `""`, which means you only need to update the deployment manifest template to specify which Dockerfiles to build. Although this will serve most requirements, you are free to update `BYPASS_MODULES` and `ACTIVE_DOCKER_PLATFORM` for your specific scenarios.
### Misc

66
docs/Overview.md Normal file
Просмотреть файл

@ -0,0 +1,66 @@
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 microsoft/iotedgedev`
This container includes all of the dependencies you need for IoT Edge development, including:
- Docker
- Python
- Pip
- Azure CLI
- Git
- .NET Core SDK
- OpenJDK
- Node.js
- [C# module template](https://www.nuget.org/packages/Microsoft.Azure.IoT.Edge.Module/)
- Maven (for scaffolding [Java modules](https://github.com/Microsoft/azure-maven-archetypes/tree/master/azure-iot-edge-archetype))
- [Yeoman](http://yeoman.io/) and [Node.js module template](https://www.npmjs.com/package/generator-azure-iot-edge-module)
- [Cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) (for scaffolding [Python modules](https://github.com/Azure/cookiecutter-azure-iot-edge-module))
- [C# Functions module template](https://www.nuget.org/packages/Microsoft.Azure.IoT.Edge.Function/)
You can also directly install with: `pip install iotedgedev`
1. **Create Solution**: Create a new IoT Edge Solution that includes a sample module and all the the required configuration files.
```
iotedgedev new edgesolution`
cd edgesolution
```
1. **Setup Azure**: Creates or selects your Azure IoT Hub and Edge Device and updates your Environment Variables.
`iotedgedev iothub setup`
> This must be run from the root of your solution, so make sure you cd into the `edgesolution1` folder before you run this command.
1. **Build, Push & Deploy**: Build, Push and Deploy modules:
`iotedgedev push --deploy`
> This will run `iotedgedev build`, `iotedgedev push`, and `iotedgedev deploy` on deployment.template.json targeting amd64 platform. You can use the `--file` and `--platform` parameters to change this behavior.
If your module is included in the `BYPASS_MODULES` environment variable, or not included in the deployment manifest template, then the `iotedgedev build` and `iotedgedev push` steps will be skipped.
1. **Setup**: Setup the IoT Edge Simulator (provided by the [iotedgehubdev](https://pypi.org/project/iotedgehubdev/) tool):
`iotedgedev setup`
1. **Start**: Start IoT Edge Simulator:
`iotedgedev start -f config/deployment.amd64.json`
1. **View Messages**: View Messages Sent from IoT Edge to IoT Hub:
`iotedgedev monitor`
1. **View Logs**: View and Save Docker log files:
`iotedgedev docker log`
1. **Setup Custom Registry**: Use a Custom Container Registry:
`iotedgedev docker setup-registry`
Please see [Azure IoT Edge Dev Resources](https://github.com/Azure/iotedgedev) for links to official docs and other IoT Edge dev information.

35
docs/Python-Virtual-Environment-Setup.md Normal file
Просмотреть файл

@ -0,0 +1,35 @@
You can run IoT Edge Dev Tool inside a [Python Virtual Environment](https://docs.python.org/3/tutorial/venv.html). A Python virtual environment is a self-contained directory tree that contains a Python installation for a particular version of Python, plus a number of additional packages.
1. Install `virtualenv`
`pip install virtualenv`
1. Create a virtual environment
`virtualenv venv`
> `venv` is just a env name that can be anything you want, but we recommend sticking with `venv` if you want to contribute to IoT Edge Dev Tool because the `.gitignore` file excludes it.
> To create a virtual environment with a Python version different with your system default, just use the `--python/-p` option to specify the Python executable path, *e.g.*:
> ```
> virtualenv --python /usr/bin/python2.7 py27
> ```
1. Activate the virtual environment
- Windows
- cmd.exe: `venv\Scripts\activate.bat`
- PowerShell: `venv\Scripts\activate.ps1` (You may need to run `Set-ExecutionPolicy RemoteSigned` in an Administrator Powershell first to allow scripts to run)
- Posix: `source venv/bin/activate`
> It will be active until you deactivate it or close the terminal instance.
1. Install dependencies
Continue with the instructions above starting with the [Manual Dev Machine Setup](manual-dev-machine-setup) -> Install Dependencies.
1. Deactivate the virtual environment
When you are done with your virtualenv, you can deactivate it with the follow command:
`deactivate`

145
docs/Quickstart-with-IoT-Edge-Dev-Container.md Normal file
Просмотреть файл

@ -0,0 +1,145 @@
Here is the absolute fastest way to get IoT Edge Dev Tool (aka `iotedgedev`) running on your dev machine with the 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. The only thing you need to install is Docker. All of the other dev dependencies are included in the container.
1. **Install [Docker CE](https://docs.docker.com/install/)**
- For Windows, please follow [the document](https://docs.docker.com/docker-for-windows/#shared-drives) to open Docker Settings and setup a Shared Drive.
- For macOS, please follow [the document](https://docs.docker.com/docker-for-mac/#file-sharing) to choose local directories to share with your containers.
1. **Run the IoT Edge Dev Container**
Before you run the container, you will need to create a local folder to store your IoT Edge solution files.
**Windows**
```
mkdir c:\temp\iotedge
docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v c:/temp/iotedge:/home/iotedge microsoft/iotedgedev
```
**Linux**
```
sudo mkdir /home/iotedge
sudo docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v ~/iotedge:/home/iotedge microsoft/iotedgedev
```
**macOS**
```
mkdir ~/iotedge
docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v ~/iotedge:/home/iotedge microsoft/iotedgedev
```
1. **Initialize IoT Edge solution and setup Azure resources**
`iotedgedev init`
> `iotedgedev init` will create a solution and setup your Azure IoT Hub in a single command. The solution comes with a default C# module named `filtermodule`.
<details>
<summary>More information</summary>
1. You will see structure of current folder like below:
```
│ .env
│ .gitignore
│ deployment.debug.template.json
│ deployment.template.json
│
├─.vscode
│ launch.json
│
└─modules
└─filtermodule
│ .gitignore
│ Dockerfile.amd64
│ Dockerfile.amd64.debug
│ Dockerfile.arm32v7
│ Dockerfile.windows-amd64
│ filtermodule.csproj
│ module.json
│ Program.cs
```
2. Open `.env` file, you will see the `IOTHUB_CONNECTION_STRING` and `DEVICE_CONNECTION_STRING` environment variables filled correctly.
3. Open `deployment.template.json` file
1. You will see below section in the modules section:
```
"filtermodule": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "${MODULES.filtermodule}",
"createOptions": ""
}
}
```
2. Two default routes are added:
```
"routes": {
"sensorTofiltermodule": "FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
"filtermoduleToIoTHub": "FROM /messages/modules/filtermodule/outputs/* INTO $upstream"
}
```
4. You will see privacy statement like below:
```
Welcome to iotedgedev!
-------------------------
Telemetry
---------
The iotedgedev collects usage data in order to improve your experience.
The data is anonymous and does not include commandline argument values.
The data is collected by Microsoft.
You can change your telemetry settings by updating 'collect_telemetry' to 'no' in ~/.iotedgedev/setting.ini
```
</details>
1. **Build IoT Edge module images**
`sudo iotedgedev build`
> This step will build user modules in deployment.template.json targeting amd64 platform. You can use the `--file` and `--platform` parameters to change this behavior.
<details>
<summary>More information</summary>
1. You will see a "BUILD COMPLETE" for each module and no error messages in the terminal output.
2. Open `config/deployment.amd64.json` file, you will see the module image placeholders expanded correctly.
3. Run `sudo docker image ls`, you will see the module images you just built.
</details>
1. **Setup and start the IoT Edge Simulator to run the solution**
`sudo iotedgedev start --setup --file config/deployment.amd64.json`
> IoT Edge Simulator does not support running Python and C modules yet. You'll need IoT Edge Runtime to run your Python and C modules.
<details>
<summary>More information</summary>
1. You will see an "IoT Edge Simulator has been started in solution mode." message at the end of the terminal output
2. Run `sudo docker ps`, you will see your modules running as well as an edgeHubDev container
</details>
1. **Monitor messages sent from IoT Edge Simulator to IoT Hub**
`iotedgedev monitor`
<details>
<summary>More information</summary>
1. You will see your expected messages sending to IoT Hub
</details>

7
docs/Test-Coverage.md Normal file
Просмотреть файл

@ -0,0 +1,7 @@
This module has been tested with the following:
- Windows 10 April 2018 Update
- Ubuntu 16.04
- macOS High Sierra 10.13.6
- Raspberry Pi with Raspbian Stretch
- Python 2.7.13, Python 3.6.5 and Python 3.7.0
- Docker Version 18.06.1-ce-win73 (19507), Channel: stable, b0f14f1

21
docs/Troubleshooting.md Normal file
Просмотреть файл

@ -0,0 +1,21 @@
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](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/#install-docker-ce), or use the [convenience script](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/#install-using-the-convenience-script).
1. `('Connection aborted.', error(2, 'No such file or directory'))`
This means that you have likely do not have `DOCKER_HOST` Environment Variable set.
```
ERROR: Could not login to Container Registry. Please verify your credentials in CONTAINER_REGISTRY_ environment variables.
```
```
('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

114
docs/Usage.md Normal file
Просмотреть файл

@ -0,0 +1,114 @@
# Usage
You can use the IoT Edge Dev Tool container to avoid having to install all the dependencies on your local dev machine. The only thing you need to install is Docker. All of the other dev dependencies are included in the container. Please see the [Quickstart](quickstart-with-IoT-Edge-Dev-Container) to learn more.
To set up development machines manually instead of using the IoT Edge Dev Container, please see the [Manual Development Machine Setup Wiki](manual-Dev-Machine-Setup).
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 install and setup Edge runtime directly on the device. See the [Edge Device Setup](edge-device-setup) wiki page for more information on setting up your Edge device.
Note: See the ["Test Coverage"](test-coverage) wiki page to see what the IoT Edge Dev Tool has been tested with.
1. **Initialize IoT Edge solution and setup Azure resources**
```sh
iotedgedev init
```
`iotedgedev init` will run both `iotedgedev new .` and `iotedgedev iothub setup`, which will create a new solution and setup your Azure resources in a single command.
If you want to use your existing IoT Hub and IoT Edge device, you can run `iotedgedev new .`, and update the `.env` file with the IoT Hub connection string and IoT Edge device connection string.
`iotedgedev init` and `iotedgedev new .` will add a default C# module named `filtermodule` to the solution. To customize this behavior, append the parameters `--module <module-name--template <template>`.
1. **Add modules to IoT Edge solution**
```sh
iotedgedev add <module-name--template <template>
```
Currently the available template values are `c`, `csharp`, `java`, `nodejs`, `python`, `csharpfunction`. We are working on supporting more templates.
1. **Build IoT Edge module images**
```sh
sudo iotedgedev build
```
You can avoid `sudo` if you are running IoT Edge Dev Tool outside Docker container, and:
* You are on Windows or macOS.
* You are on Linux, and you have followed the [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) to allow running Docker commands without `sudo`.
1. **Setup the [IoT Edge Simulator]((https://pypi.org/project/iotedgehubdev/).)**
```sh
sudo iotedgedev setup
```
IoT Edge Simulator does not support running Python and C modules yet. You'll need IoT Edge Runtime to run your Python and C modules.
You can avoid `sudo` if you are on Windows, and running IoT Edge Dev Tool outside Docker container.
1. **Start the IoT Edge Simulator to run the solution**
```sh
sudo iotedgedev start
```
You can also combine setup and start with `sudo iotedgedev start --setup`
You can avoid `sudo` if you are running IoT Edge Dev Tool outside Docker container, and:
* You are on Windows or macOS.
* You are on Linux, and you have followed the [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) to allow running Docker commands without `sudo`.
1. **Monitor messages sent from IoT Edge Simulator to IoT Hub**
```sh
iotedgedev monitor
```
1. **Stop the IoT Edge Simulator**
```sh
sudo iotedgedev stop
```
You can avoid `sudo` if you are running IoT Edge Dev Tool outside Docker container, and:
* You are on Windows or macOS.
* You are on Linux, and you have followed the [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) to allow running Docker commands without `sudo`.
1. **Setup the IoT Edge Runtime**
1. Copy the device connection string from the `DEVICE_CONNECTION_STRING` environment variable in the `.env` file, [Azure Portal](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-register-device-portal#retrieve-the-connection-string), or [Azure CLI](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-register-device-cli#retrieve-the-connection-string).
1. Follow [Edge Device Setup](edge-device-setup) to setup and start the IoT Edge Runtime with the copied device connection string
1. **Push IoT Edge module images**
```sh
sudo iotedgedev push
```
You can avoid `sudo` if you are running IoT Edge Dev Tool outside Docker container, and:
* You are on Windows or macOS.
* You are on Linux, and you have followed the [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) to allow running Docker commands without `sudo`.
1. **Deploy modules to IoT Edge device**
```sh
iotedgedev deploy
```
You can also combine push and deploy with `iotedgedev push --deploy`
1. **Deploy modules with automatic deployments to IoT Hub**
```sh
iotedgedev iothub deploy
```
> More information on how automatic deployments work can be found here: <https://docs.microsoft.com/en-us/azure/iot-edge/module-deployment-monitoring?view=iotedge-2020-11>
1. **Monitor messages sent from IoT Edge Runtime to IoT Hub**
```sh
iotedgedev monitor
```

13
docs/_Sidebar.md Normal file
Просмотреть файл

@ -0,0 +1,13 @@
* [Home](home)
* Dev Machine Setup
* [Quickstart with IoT Edge Dev Container](quickstart-with-iot-edge-dev-container)
* [Manual Setup](manual-dev-machine-setup)
* [Azure Setup](azure-setup)
* [Edge Device Setup](edge-device-setup)
* [Command List](command-list)
* [Python Virtual Environment Setup](python-virtual-environment-setup)
* [Test Coverage](test-coverage)
* [Troubleshooting](troubleshooting)
* [Contributing](https://github.com/Azure/iotedgedev/blob/master/CONTRIBUTING.md)
* Misc
* [Migration Guides for Public Preview Users](migration-guides)

16
iotedgedev/cli.py
Просмотреть файл

@ -251,7 +251,7 @@ main.add_command(deploy)
@iothub.command( @iothub.command(
name="deploy", name="deploy",
context_settings=CONTEXT_SETTINGS, context_settings=CONTEXT_SETTINGS,
help="Create a deployment in IoT Hub") help="Create a deployment in IoT Hub. For more information on how automatic deployments work see: https://docs.microsoft.com/en-us/azure/iot-edge/module-deployment-monitoring")
@click.option("--file", @click.option("--file",
"-f", "-f",
"manifest_file", "manifest_file",
@ -262,25 +262,31 @@ main.add_command(deploy)
@click.option("--name", @click.option("--name",
"-n", "-n",
required=True, required=True,
help="Specify the deployment name") help="Specify the name of the deployment that will be created in the IoT hub.")
@click.option("--priority", @click.option("--priority",
"-p", "-p",
required=True, required=True,
help="Specify the deployment priority") help=("Specify the deployment priority as positive integer. "
"In the event that two or more deployments are targeted at the same device, the deployment with the highest numerical value for Priority will apply."))
@click.option("--target-condition", @click.option("--target-condition",
"--tc", "--tc",
"-t", "-t",
"target_condition", "target_condition",
default=envvars.get_envvar("IOTHUB_DEPLOYMENT_TARGET_CONDITION"), default=envvars.get_envvar("IOTHUB_DEPLOYMENT_TARGET_CONDITION"),
show_default=True, show_default=True,
required=False, required=True,
help="Specify the deployment target condition") help=("Specify a target condition to determine which devices will be targeted with this deployment. "
"The condition is based on device twin tags or device twin reported properties and should match the expression format. "
"For example, tags.environment='test' and properties.reported.devicemodel='4000x'. "
"This property can be set via this parameter or in the .env under 'IOTHUB_DEPLOYMENT_TARGET_CONDITION'"))
@click.option("--device-tag", @click.option("--device-tag",
"-dt", "-dt",
"device_tag", "device_tag",
default=envvars.get_envvar("DEVICE_TAGS"), default=envvars.get_envvar("DEVICE_TAGS"),
required=False, required=False,
help="Specify the tags to be added to the device twin") help="Specify the tags to be added to the device twin")
@with_telemetry @with_telemetry
def iothub_deploy(manifest_file, name, priority, target_condition, device_tag): def iothub_deploy(manifest_file, name, priority, target_condition, device_tag):
ensure_azure_cli_iot_ext() ensure_azure_cli_iot_ext()

4
vsts_ci/.vsts-ci.yml
Просмотреть файл

@ -2,6 +2,10 @@
# Create and test a Python package on multiple Python versions. # Create and test a Python package on multiple Python versions.
# Add steps that analyze code, save the dist with the build record, publish to a PyPI-compatible index, and more: # Add steps that analyze code, save the dist with the build record, publish to a PyPI-compatible index, and more:
# https://docs.microsoft.com/vsts/pipelines/languages/python # https://docs.microsoft.com/vsts/pipelines/languages/python
pr:
- master
trigger: none
jobs: jobs:
- job: Windows - job: Windows