Merge pull request #58225 from kgremban/nov16-quickstartvm

Improve clarity of quickstarts

Author: Ja-Dunn

articles/iot-edge/quickstart-linux.md

@@ -4,14 +4,11 @@ description: In this quickstart, learn how to deploy prebuilt code remotely to a
 author: kgremban
 manager: philmea
 ms.author: kgremban
-ms.date: 08/14/2018
+ms.date: 10/14/2018
 ms.topic: quickstart
 ms.service: iot-edge
 services: iot-edge
 ms.custom: mvc
-
-experimental: true
-experiment_id: 21cb7321-bcff-4b
 ---
 
 # Quickstart: Deploy your first IoT Edge module to a Linux x64 device
@@ -56,9 +53,11 @@ IoT Edge device:
 * A Linux device or virtual machine to act as your IoT Edge device. If you want to create a virtual machine in Azure, use the following command to get started quickly:
 
    ```azurecli-interactive
-   az vm create --resource-group IoTEdgeResources --name EdgeVM --image Canonical:UbuntuServer:16.04-LTS:latest --admin-username azureuser --generate-ssh-keys --size Standard_B1ms
+   az vm create --resource-group IoTEdgeResources --name EdgeVM --image Canonical:UbuntuServer:16.04-LTS:latest --admin-username azureuser --generate-ssh-keys --size Standard_DS1_v2
    ```
 
+   When you create a new virtual machine, make a note of the **publicIpAddress**, which is provided as part of the create command output. You use this public IP address to connect to the virtual machine later in the quickstart.
+
 ## Create an IoT hub
 
 Start the quickstart by creating your IoT hub with Azure CLI.
@@ -73,7 +72,7 @@ The following code creates a free **F1** hub in the resource group **IoTEdgeReso
    az iot hub create --resource-group IoTEdgeResources --name {hub_name} --sku F1 
    ```
 
-   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**.
+   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**. If you get an error that the IoT Hub name isn't available, it means that someone else already has a hub with that name. Try a new name. 
 
 ## Register an IoT Edge device
 
@@ -82,21 +81,23 @@ Register an IoT Edge device with your newly created IoT hub.
 
 Create a device identity for your simulated device so that it can communicate with your IoT hub. The device identity lives in the cloud, and you use a unique device connection string to associate a physical device to a device identity. 
 
-Since IoT Edge devices behave and can be managed differently than typical IoT devices, you declare this to be an IoT Edge device from the beginning. 
+Since IoT Edge devices behave and can be managed differently than typical IoT devices, declare this identity to be for an IoT Edge device with the `--edge-enabled` flag. 
 
 1. In the Azure cloud shell, enter the following command to create a device named **myEdgeDevice** in your hub.
 
    ```azurecli-interactive
    az iot hub device-identity create --hub-name {hub_name} --device-id myEdgeDevice --edge-enabled
    ```
 
-1. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub. 
+   If you get an error about iothubowner policy keys, make sure that your cloud shell is running the latest version of the azure-cli-iot-ext extension. 
+
+2. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub. 
 
    ```azurecli-interactive
    az iot hub device-identity show-connection-string --device-id myEdgeDevice --hub-name {hub_name}
    ```
 
-1. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section. 
+3. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section. 
 
 ## Install and start the IoT Edge runtime
 
@@ -107,13 +108,21 @@ The IoT Edge runtime is deployed on all IoT Edge devices. It has three component
 
 During the runtime configuration, you provide a device connection string. Use the string that you retrieved from the Azure CLI. This string associates your physical device with the IoT Edge device identity in Azure. 
 
-Complete the following steps in the Linux machine or VM that you prepared to function as an IoT Edge device. 
+### Connect to your IoT Edge device
+
+The steps in this section all take place on your IoT Edge device. If you're using your own machine as the IoT Edge device, you can skip this part. If you're using a virtual machine or secondary hardware, you want to connect to that machine now. 
+
+If you created an Azure virtual machine for this quickstart, retrieve the public IP address that was output by the creation command. You can also find the public IP address on your virtual machine's overview page in the Azure portal. Use the following command to connect to your virtual machine. Replace **{publicIpAddress}** with your machine's address. 
+
+```azurecli-interactive
+ssh azureuser@{publicIpAddress}
+```
 
 ### Register your device to use the software repository
 
 The packages that you need to run the IoT Edge runtime are managed in a software repository. Configure your IoT Edge device to access this repository. 
 
-The steps in this section are for x64 devices running **Ubuntu 16.04**. To access the software repository on other versions of Linux or device architectures, see [Install the Azure IoT Edge runtime on Linux (x64)](how-to-install-iot-edge-linux.md) or [Install Azure IoT Edge runtime on Linux (ARM32v7/armhf)](how-to-install-iot-edge-linux-arm.md).
+The steps in this section are for x64 devices running **Ubuntu 16.04**. To access the software repository on other versions of Linux or device architectures, see [Install the Azure IoT Edge runtime on Linux (x64)](how-to-install-iot-edge-linux.md) or [Linux (ARM32v7/armhf)](how-to-install-iot-edge-linux-arm.md).
 
 1. On the machine that you're using as an IoT Edge device, install the repository configuration.
 
@@ -162,7 +171,7 @@ The security daemon installs as a system service so that the IoT Edge runtime st
    sudo apt-get install iotedge
    ```
 
-2. Open the IoT Edge configuration file. It is a protected file so you may have to use elevated privileges to access it.
+2. Open the IoT Edge configuration file. It's a protected file so you may have to use elevated privileges to access it.
 
    ```bash
    sudo nano /etc/iotedge/config.yaml
@@ -240,15 +249,15 @@ View the messages being sent from the tempSensor module:
 
 The temperature sensor module may be waiting to connect to Edge Hub if the last line you see in the log is `Using transport Mqtt_Tcp_Only`. Try killing the module and letting the Edge Agent restart it. You can kill it with the command `sudo docker stop tempSensor`.
 
-You can also view the telemetry as it arrives at your IoT hub by using the [Azure IoT Toolkit extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit). 
+You can also watch the messages arrive at your IoT hub by using the [Azure IoT Toolkit extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit). 
 
 ## Clean up resources
 
 If you want to continue on to the IoT Edge tutorials, you can use the device that you registered and set up in this quickstart. Otherwise, you can delete the Azure resources that you created and remove the IoT Edge runtime from your device.
 
 ### Delete Azure resources
 
-If you created your virtual machine and IoT hub in a new resource group, you can delete that group and all the associated resources. If there's anything in that resource group that you want to keep, then just delete the individual resources that you want to clean up. 
+If you created your virtual machine and IoT hub in a new resource group, you can delete that group and all the associated resources. Double check the contents of the resource group to make sure that there's nothing you want to keep. If you don't want to delete the whole group, you can delete individual resources instead.
 
 Remove the **IoTEdgeResources** group.
 

articles/iot-edge/quickstart.md

@@ -4,14 +4,11 @@ description: Try out Azure IoT Edge by running analytics on a simulated edge dev
 author: kgremban
 manager: philmea
 ms.author: kgremban
-ms.date: 08/02/2018
+ms.date: 10/02/2018
 ms.topic: quickstart
 ms.service: iot-edge
 services: iot-edge
 ms.custom: mvc
-
-#experimental: true
-#experiment_id: 2c2f48c7-50a9-4e
 ---
 
 # Quickstart: Deploy your first IoT Edge module from the Azure portal to a Windows device - preview
@@ -59,8 +56,8 @@ IoT Edge device:
 * A Windows computer or virtual machine to act as your IoT Edge device. Use a supported Windows version:
   * Windows 10 or newer
   * Windows Server 2016 or newer
-* If it's a Windows computer, ensure it meets the [system requirements](https://docs.microsoft.com/virtualization/hyper-v-on-windows/reference/hyper-v-requirements) for Hyper-V.
-* If it's a virtual machine, enable [nested virtualization](https://docs.microsoft.com/virtualization/hyper-v-on-windows/user-guide/nested-virtualization) and allocate at least 2GB memory.
+* If it's a Windows computer, check that it meets the [system requirements](https://docs.microsoft.com/virtualization/hyper-v-on-windows/reference/hyper-v-requirements) for Hyper-V.
+* If it's a virtual machine, enable [nested virtualization](https://docs.microsoft.com/virtualization/hyper-v-on-windows/user-guide/nested-virtualization) and allocate at least 2 GB memory.
 * Install [Docker for Windows](https://docs.docker.com/docker-for-windows/install/) and make sure it's running.
 
 > [!TIP]
@@ -80,7 +77,7 @@ The following code creates a free **F1** hub in the resource group **IoTEdgeReso
    az iot hub create --resource-group IoTEdgeResources --name {hub_name} --sku F1
    ```
 
-   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**.
+   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**. If you get an error that the IoT Hub name isn't available, it means that someone else already has a hub with that name. Try a new name. 
 
 ## Register an IoT Edge device
 
@@ -89,21 +86,23 @@ Register an IoT Edge device with your newly created IoT Hub.
 
 Create a device identity for your simulated device so that it can communicate with your IoT hub. The device identity lives in the cloud, and you use a unique device connection string to associate a physical device to a device identity.
 
-Since IoT Edge devices behave and can be managed differently than typical IoT devices, you declare this to be an IoT Edge device from the beginning.
+Since IoT Edge devices behave and can be managed differently than typical IoT devices, declare this identity to be for an IoT Edge device with the `--edge-enabled` flag. 
 
 1. In the Azure cloud shell, enter the following command to create a device named **myEdgeDevice** in your hub.
 
    ```azurecli-interactive
    az iot hub device-identity create --device-id myEdgeDevice --hub-name {hub_name} --edge-enabled
    ```
 
-1. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub.
+   If you get an error about iothubowner policy keys, make sure that your cloud shell is running the latest version of the azure-cli-iot-ext extension. 
+
+2. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub.
 
    ```azurecli-interactive
    az iot hub device-identity show-connection-string --device-id myEdgeDevice --hub-name {hub_name}
    ```
 
-1. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section.
+3. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section.
 
 ## Install and start the IoT Edge runtime
 
@@ -116,7 +115,9 @@ During the runtime installation, you're asked for a device connection string. Us
 
 The instructions in this section configure the IoT Edge runtime with Linux containers. If you want to use Windows containers, see [Install Azure IoT Edge runtime on Windows to use with Windows containers](how-to-install-iot-edge-windows-with-windows.md).
 
-Complete the following steps in the Windows machine or VM that you prepared to function as an IoT Edge device.
+### Connect to your IoT Edge device
+
+The steps in this section all take place on your IoT Edge device. If you're using your own machine as the IoT Edge device, you can skip this part. If you're using a virtual machine or secondary hardware, you want to connect to that machine now. 
 
 ### Download and install the IoT Edge service
 
@@ -193,15 +194,15 @@ iotedge logs tempSensor -f
 
   ![View the data from your module](./media/quickstart/iotedge-logs.png)
 
-You can also view the messages that are received by your IoT hub by using the [Azure IoT Toolkit extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit).
+You can also watch the messages arrive at your IoT hub by using the [Azure IoT Toolkit extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit). 
 
 ## Clean up resources
 
 If you want to continue on to the IoT Edge tutorials, you can use the device that you registered and set up in this quickstart. Otherwise, you can delete the Azure resources that you created and remove the IoT Edge runtime from your device.
 
 ### Delete Azure resources
 
-If you created your virtual machine and IoT hub in a new resource group, you can delete that group and all the associated resources. If there's anything in that resource group that you want to keep, then just delete the individual resources that you want to clean up.
+If you created your virtual machine and IoT hub in a new resource group, you can delete that group and all the associated resources. Double check the contents of the resource group to make sure that there's nothing you want to keep. If you don't want to delete the whole group, you can delete individual resources instead.
 
 Remove the **IoTEdgeResources** group.
 

includes/iot-edge-deploy-module.md

@@ -5,25 +5,34 @@
  author: kgremban
  ms.service: iot-edge
  ms.topic: include
- ms.date: 08/14/2018
+ ms.date: 10/14/2018
  ms.author: kgremban
  ms.custom: include file
 ---
 
 One of the key capabilities of Azure IoT Edge is being able to deploy modules to your IoT Edge devices from the cloud. An IoT Edge module is an executable package implemented as a container. In this section, you deploy a module that generates telemetry for your simulated device.
 
 1. In the Azure portal, navigate to your IoT hub.
-1. Go to **IoT Edge** under **Automatic Device Management** and select your IoT Edge device.
-1. Select **Set Modules**.
-1. In the **Deployment Modules** section of the **Add Modules** step, click **Add** then select **IoT Edge Module**.
-1. In the **Name** field, enter `tempSensor`.
-1. In the **Image URI** field, enter `mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0`.
-1. Leave the other settings unchanged, and select **Save**.
+
+2. Go to **IoT Edge** under **Automatic Device Management** and select your IoT Edge device.
+
+3. Select **Set Modules**. A three-step wizard opens in the portal, which guides you through adding modules, specifying routes, and reviewing the deployment. 
+
+4. In the **Add Modules** step of the wizard, find the **Deployment Modules** section. Click **Add** then select **IoT Edge Module**.
+
+   ![Add a new IoT Edge module](./media/iot-edge-deploy-module/add-module.png)
+
+5. In the **Name** field, enter `tempSensor`.
+
+6. In the **Image URI** field, enter `mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0`.
+
+7. Leave the other settings unchanged, and select **Save**.
 
    ![Save IoT Edge module after entering name and image URI](./media/iot-edge-deploy-module/name-image.png)
 
-1. Back in the **Add Modules** step, select **Next**.
-1. In the **Specify routes** step, you should have a default route that sends all messages from all modules to IoT Hub. If not, add the following code then select **Next**.
+8. Back in first step of the wizard, select **Next**.
+
+9. In the **Specify Routes** step of the wizard, you should have a default route that sends all messages from all modules to IoT Hub. If not, add the following code then select **Next**.
 
    ```json
    {
@@ -33,7 +42,10 @@ One of the key capabilities of Azure IoT Edge is being able to deploy modules to
    }
    ```
 
-1. In the **Review Deployment** step, select **Submit**.
-1. Return to the device details page and select **Refresh**. In addition to the edgeAgent module that was created when you first started the service, you should see another runtime module called **edgeHub** and the **tempSensor** module listed.
+10. In the **Review Deployment** step of the wizard, select **Submit**.
+
+11. Return to the device details page and select **Refresh**. In addition to the edgeAgent module that was created when you first started the service, you should see another runtime module called **edgeHub** and the **tempSensor** module listed.
+
+   It may take a few minutes for the new modules to show up. The IoT Edge device has to retrieve its new deployment information from the cloud, start the containers, and then report its new status back to IoT Hub. 
 
    ![View tempSensor in list of deployed modules](./media/iot-edge-deploy-module/deployed-modules.png)