Merge pull request #95533 from baanders/11-11-Pnp-Quickstart3

GitHubber17 · web-flow · commit ccf424f65cab · 2019-11-11T10:56:15.000-08:00
Pnp Quickstart 3
diff --git a/articles/iot-pnp/quickstart-create-pnp-device-linux.md b/articles/iot-pnp/quickstart-create-pnp-device-linux.md
@@ -54,23 +54,23 @@ You can find your _company model repository connection string_ in the [Azure Cer
 
 ## Prepare an IoT hub
 
-You need an Azure IoT hub in your Azure subscription to complete this quickstart. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
+You also need an Azure IoT hub in your Azure subscription to complete this quickstart. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin. If you don't have an IoT hub, there will be steps to create one below.
 
 If you're using the Azure CLI locally, the `az` version should be **2.0.75** or later, the Azure Cloud Shell uses the latest version. Use the `az --version` command to check the version installed on your machine.
 
-Add the Microsoft Azure IoT Extension for Azure CLI:
+Run the following command to add the Microsoft Azure IoT Extension for Azure CLI to your Cloud Shell instance:
 
 ```azurecli-interactive
 az extension add --name azure-cli-iot-ext
 ```
 
 The steps in this quickstart require version **0.8.5** or later of the extension. Use the `az extension list` command to check the version you have installed, and the `az extension update` command to update if necessary.
 
-If don't have an IoT hub, create one using the following commands, replacing `{YourIoTHubName}` with a unique name of your choice. If you're running these commands locally, first sign in to your Azure subscription using `az login`. If you're running these commands in the Azure cloud shell, you're signed in automatically:
+If don't have an IoT hub, create one using the following commands, replacing `<YourIoTHubName>` with a unique name of your choice. If you're running these commands locally, first sign in to your Azure subscription using `az login`. If you're running these commands in the Azure cloud shell, you're signed in automatically:
 
   ```azurecli-interactive
   az group create --name pnpquickstarts_rg --location centralus
-  az iot hub create --name {YourIoTHubName} \
+  az iot hub create --name <YourIoTHubName> \
     --resource-group pnpquickstarts_rg --sku S1
   ```
 
@@ -79,23 +79,23 @@ The previous commands create a resource group called `pnpquickstarts_rg` and an
 > [!IMPORTANT]
 > During public preview, IoT Plug and Play features are only available on IoT hubs created in the **Central US**, **North Europe**, and **Japan East** regions.
 
-Run the following command to create a device identity for a device called `mypnpdevice` in your IoT hub. Replace the `{YourIoTHubName}` placeholder with the name of your IoT hub:
+Run the following command to create a device identity in your IoT hub. Replace the **YourIoTHubName** and **YourDevice** placeholders with your actual names.
 
 ```azurecli-interactive
-az iot hub device-identity create --hub-name {YourIoTHubName} --device-id mypnpdevice
+az iot hub device-identity create --hub-name <YourIoTHubName> --device-id <YourDevice>
 ```
 
-Run the following commands to get the _device connection string_ for the device you just registered. You need this connection string later in this quickstart:
+Run the following commands to get the _device connection string_ for the device you just registered.
 
 ```azurecli-interactive
-az iot hub device-identity show-connection-string --hub-name {YourIoTHubName} --device-id mypnpdevice --output table
+az iot hub device-identity show-connection-string --hub-name <YourIoTHubName> --device-id <YourDevice> --output table
 ```
 
 ## Author your model
 
 In this quickstart, you use an existing sample device capability model and associated interfaces.
 
-1. Create a `pnp_app` directory in your home directory. You use this folder for the device model files and device code stub.
+1. Create a `pnp_app` directory in your local drive. You use this folder for the device model files and device code stub.
 
     ```bash
     cd ~
@@ -110,34 +110,34 @@ In this quickstart, you use an existing sample device capability model and assoc
     curl -O -L https://raw.githubusercontent.com/Azure/IoTPlugandPlay/master/samples/EnvironmentalSensor.interface.json
     ```
 
-1. Open `pnp_app` folder with VS Code. You can view the files with intellisense:
+1. Open `pnp_app` folder with VS Code. You can view the files with IntelliSense:
 
     ![Device capability model](media/quickstart-create-pnp-device-linux/dcm.png)
 
 1. In the files you downloaded, replace `<YOUR_COMPANY_NAME_HERE>` in the `@id` and `schema` fields with a unique value. Use only the characters a-z, A-Z, 0-9, and underscore. For more information, see [Digital Twin identifier format](https://github.com/Azure/IoTPlugandPlay/tree/master/DTDL#digital-twin-identifier-format).
 
 ## Generate the C code stub
 
-Now you have a DCM and its associated interfaces, you can generate the device code that implements the model. To generate the C code stub in VS code:
+Now that you have a DCM and its associated interfaces, you can generate the device code that implements the model. To generate the C code stub in VS Code:
 
-1. With the `pnp_app` folder open in VS code, use **Ctrl+Shift+P** to open the command palette, enter **IoT Plug and Play**, and select **Generate Device Code Stub**.
+1. With the `pnp_app` folder open in VS Code, use **Ctrl+Shift+P** to open the command palette, enter **IoT Plug and Play**, and select **Generate Device Code Stub**.
 
     > [!NOTE]
-    > The first time you use the IoT Plug and Play Code Generator utility, it takes a few seconds to download.
+    > The first time you use the IoT Plug and Play Code Generator utility, it takes a few seconds to download and install automatically.
 
-1. Choose the **SampleDevice.capabilitymodel.json** file to use to generate the device code stub.
+1. Choose the **SampleDevice.capabilitymodel.json** file to use for generating the device code stub.
 
-1. Enter the project name **sample_device**, it will be the name of your device application.
+1. Enter the project name **sample_device**. This will be the name of your device application.
 
 1. Choose **ANSI C** as your language.
 
 1. Choose **Via IoT Hub device connection string** as connection method.
 
 1. Choose **CMake Project on Linux** as your project template.
 
-1. Choose **Via Source Code** as the way to include the SDK.
+1. Choose **Via Source Code** as the way to include the device SDK.
 
-1. VS Code opens a new window with generated device code stub files.
+1. A new folder called **sample_device** is created in the same location as the DCM file, and in it are the generated device code stub files. VS Code opens a new window to display these.
     ![Device code](media/quickstart-create-pnp-device-linux/device-code.png)
 
 ## Build and run the code
@@ -170,7 +170,7 @@ You use the device SDK source code to build the generated device code stub. The
 
     ```sh
     cd ~/pnp_app/sample_device/cmake
-    ./sample_device "{IoT Hub device connection string}"
+    ./sample_device "<device connection string>"
     ```
 
 1. The device application starts sending data to IoT Hub.
@@ -192,25 +192,25 @@ To validate the device code with the **az** CLI, you need to publish the files t
     > [!NOTE]
     > The connection string is only required the first time you connect to the repository.
 
-1. In VS Code output window and notification, you can check the files have been published successfully.
+1. In VS Code output window and notification, you can check that the files have been published successfully.
 
     > [!NOTE]
     > If you get errors on publishing the device model files, you can try use command **IoT Plug and Play: Sign out Model Repository** to sign out and go through the steps again.
 
 ### Use the Azure IoT CLI to validate the code
 
-After the device client sample starts, you can check it's working with the Azure CLI.
+After the device client sample starts, you can check that it's working with the Azure CLI.
 
 Use the following command to view the telemetry the sample device is sending. You may need to wait a minute or two before you see any telemetry in the output:
 
 ```azurecli-interactive
-az iot dt monitor-events --hub-name {your IoT hub} --device-id mypnpdevice
+az iot dt monitor-events --hub-name <YourIoTHubNme> --device-id <YourDevice>
 ```
 
 Use the following command to view all the properties sent by the device:
 
 ```azurecli-interactive
-az iot dt list-properties --device-id mypnpdevice --hub-name {Your IoT hub name} --source private --repo-login "{Your company model repository connection string}"
+az iot dt list-properties --device-id <YourDevice> --hub-name <YourIoTHubNme> --source private --repo-login "<Your company model repository connection string>"
 ```
 
 ## Next steps
@@ -220,4 +220,4 @@ In this quickstart, you learned how to create an IoT Plug and Play device using
 To learn more about DCMs and how to create your own models, continue to the tutorial:
 
 > [!div class="nextstepaction"]
-> [Tutorial: Create a test a device capability model using Visual Studio Code](tutorial-pnp-visual-studio-code.md)
+> [Tutorial: Create and test a device capability model using Visual Studio Code](tutorial-pnp-visual-studio-code.md)
diff --git a/articles/iot-pnp/quickstart-create-pnp-device.md b/articles/iot-pnp/quickstart-create-pnp-device.md
@@ -1,5 +1,5 @@
 ---
-title: Create an IoT Plug and Play Preview device | Microsoft Docs
+title: Create an IoT Plug and Play Preview device (Windows) | Microsoft Docs
 description: Use a device capability model to generate device code. Then run the device code and see the device connect to your IoT Hub.
 author: miagdp
 ms.author: miag
@@ -45,43 +45,35 @@ You can find your _company model repository connection string_ in the [Azure Cer
 
 ## Prepare an IoT hub
 
-You also need an Azure IoT hub in your Azure subscription to complete this quickstart. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
+You also need an Azure IoT hub in your Azure subscription to complete this quickstart. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin. If you don't have an IoT hub, follow [these instructions to create one](../iot-hub/iot-hub-create-using-cli.md).
 
-> [!NOTE]
+> [!IMPORTANT]
 > During public preview, IoT Plug and Play features are only available on IoT hubs created in the **Central US**, **North Europe**, and **Japan East** regions.
 
-Add the Microsoft Azure IoT Extension for Azure CLI:
+Run the following command to add the Microsoft Azure IoT Extension for Azure CLI to your Cloud Shell instance:
 
 ```azurecli-interactive
 az extension add --name azure-cli-iot-ext
 ```
 
-Run the following command to create the device identity in your IoT hub. Replace the **YourIoTHubName** and **YourDevice** placeholders with your actual names. If you don't have an IoT Hub, follow [these instructions to create one](../iot-hub/iot-hub-create-using-cli.md):
+Run the following command to create the device identity in your IoT hub. Replace the **YourIoTHubName** and **YourDevice** placeholders with your actual names.
 
 ```azurecli-interactive
-az iot hub device-identity create --hub-name [YourIoTHubName] --device-id [YourDevice]
+az iot hub device-identity create --hub-name <YourIoTHubName> --device-id <YourDevice>
 ```
 
-Run the following commands to get the _device connection string_ for the device you just registered:
+Run the following command to get the _device connection string_ for the device you just registered:
 
 ```azurecli-interactive
-az iot hub device-identity show-connection-string --hub-name [YourIoTHubName] --device-id [YourDevice] --output table
+az iot hub device-identity show-connection-string --hub-name <YourIoTHubName> --device-id <YourDevice> --output table
 ```
 
-Run the following commands to get the _IoT hub connection string_ for your hub:
+Run the following command to get the _IoT hub connection string_ for your hub:
 
 ```azurecli-interactive
-az iot hub show-connection-string --hub-name [YourIoTHubName] --output table
+az iot hub show-connection-string --hub-name <YourIoTHubName> --output table
 ```
 
-Make a note of the device connection string, which looks like:
-
-```json
-HostName={YourIoTHubName}.azure-devices.net;DeviceId=MyCDevice;SharedAccessKey={YourSharedAccessKey}
-```
-
-You'll use this value later in the quickstart.
-
 ## Prepare the development environment
 
 ### Get Azure IoT device SDK for C
@@ -113,9 +105,9 @@ In this quickstart, you prepare a development environment by installing the Azur
 
 In this quickstart, you use an existing sample device capability model and associated interfaces.
 
-1. Create a `pnp_app` directory in your local drive.
+1. Create a `pnp_app` directory in your local drive. You use this folder for the device model files and device code stub.
 
-1. Download the [device capability model](https://github.com/Azure/IoTPlugandPlay/blob/master/samples/SampleDevice.capabilitymodel.json) and [interface sample](https://github.com/Azure/IoTPlugandPlay/blob/master/samples/EnvironmentalSensor.interface.json) and save files into `pnp_app` folder.
+1. Download the [device capability model and interface sample files](https://github.com/Azure/IoTPlugandPlay/blob/master/samples/SampleDevice.capabilitymodel.json) and [interface sample](https://github.com/Azure/IoTPlugandPlay/blob/master/samples/EnvironmentalSensor.interface.json) and save files into `pnp_app` folder.
 
     > [!TIP]
     > To download a file from GitHub, navigate to the file, right-click on **Raw**, and then select **Save link as**.
@@ -130,29 +122,29 @@ In this quickstart, you use an existing sample device capability model and assoc
 
 Now that you have a DCM and its associated interfaces, you can generate the device code that implements the model. To generate the C code stub in VS Code:
 
-1. With the folder with DCM files open, use **Ctrl+Shift+P** to open the command palette, enter **IoT Plug and Play**, and select **Generate Device Code Stub**.
+1. With the `pnp_app` folder open in VS Code, use **Ctrl+Shift+P** to open the command palette, enter **IoT Plug and Play**, and select **Generate Device Code Stub**.
 
     > [!NOTE]
     > The first time you use the IoT Plug and Play CodeGen CLI, it takes a few seconds to download and install automatically.
 
-1. Choose the DCM file you want to use to generate the device code stub.
+1. Choose the **SampleDevice.capabilitymodel.json** file to use for generating the device code stub.
 
-1. Enter the project name **sample_device**, it will be the name of your device application.
+1. Enter the project name **sample_device**. This will be the name of your device application.
 
 1. Choose **ANSI C** as your language.
 
 1. Choose **Via IoT Hub device connection string** as connection method.
 
-1. Choose **CMake Project on Windows** as project template.
+1. Choose **CMake Project on Windows** as your project template.
 
 1. Choose **Via Vcpkg** as way to include the device SDK.
 
 1. A new folder called **sample_device** is created in the same location as the DCM file, and in it are the generated device code stub files. VS Code opens a new window to display these.
     ![Device code](media/quickstart-create-pnp-device/device-code.png)
 
-## Build the code
+## Build and run the code
 
-You build the generated device code stub together with the device SDK. The application you build simulates a device that connects to an IoT hub. The application sends telemetry and properties and receives commands.
+You use the device SDK source code to build the generated device code stub. The application you build simulates a device that connects to an IoT hub. The application sends telemetry and properties and receives commands.
 
 1. Create a `cmake` subdirectory in the `sample_device` folder, and navigate to that folder:
 
@@ -164,7 +156,7 @@ You build the generated device code stub together with the device SDK. The appli
 1. Run the following commands to build the generated code stub (replacing the placeholder with the directory of your Vcpkg repo):
 
     ```cmd\sh
-    cmake .. -G "Visual Studio 16 2019" -A Win32 -Duse_prov_client=ON -Dhsm_type_symm_key:BOOL=ON -DCMAKE_TOOLCHAIN_FILE="{directory of your Vcpkg repo}\scripts\buildsystems\vcpkg.cmake"
+    cmake .. -G "Visual Studio 16 2019" -A Win32 -Duse_prov_client=ON -Dhsm_type_symm_key:BOOL=ON -DCMAKE_TOOLCHAIN_FILE="<directory of your Vcpkg repo>\scripts\buildsystems\vcpkg.cmake"
 
     cmake --build .
     ```
@@ -184,7 +176,7 @@ You build the generated device code stub together with the device SDK. The appli
 1. After the build completes successfully, run your application, passing the IoT hub device connection string as a parameter.
 
     ```cmd\sh
-    .\Debug\sample_device.exe "[IoT Hub device connection string]"
+    .\Debug\sample_device.exe "<device connection string>"
     ```
 
 1. The device application starts sending data to IoT Hub.
@@ -197,7 +189,7 @@ You build the generated device code stub together with the device SDK. The appli
 
 To validate the device code with **Azure IoT Explorer**, you need to publish the files to the model repository.
 
-1. With the folder with DCM files open in VS Code, use **Ctrl+Shift+P** to open the command palette, type and select **IoT Plug & Play: Submit files to Model Repository**.
+1. With the `pnp_app` folder open in VS Code, use **Ctrl+Shift+P** to open the command palette, type and select **IoT Plug & Play: Submit files to Model Repository**.
 
 1. Select `SampleDevice.capabilitymodel.json` and `EnvironmentalSensor.interface.json` files.
 
@@ -213,9 +205,9 @@ To validate the device code with **Azure IoT Explorer**, you need to publish the
 
 ### Use the Azure IoT explorer to validate the code
 
-1. Open Azure IoT explorer, you see the **App configurations** page.
+1. Open Azure IoT explorer. You see the **App configurations** page.
 
-1. Enter your IoT Hub connection string and click **Connect**.
+1. Enter your _IoT Hub connection string_ and select **Connect**.
 
 1. After you connect, you see the device overview page.
 
@@ -227,25 +219,25 @@ To validate the device code with **Azure IoT Explorer**, you need to publish the
 
 1. Select the **Telemetry** page and hit _Start_ to view the telemetry data the device is sending.
 
-1. Select the **Properties(non-writable)** page to view the non-writable properties reported by the device.
+1. Select the **Properties (non-writable)** page to view the non-writable properties reported by the device.
 
-1. Select the **Properties(writable)** page to view the writable properties you can update.
+1. Select the **Properties (writable)** page to view the writable properties you can update.
 
 1. Expand property **name**, update with a new name and select **Update writable property**.
 
-1. To see the new name shows up in the **Reported Property** column, click the **Refresh** button on top of the page.
+1. To see the new name show up in the **Reported Property** column, select the **Refresh** button on top of the page.
 
-1. Select the **Command** page to view all the commands the device supports.
+1. Select the **Commands** page to view all the commands the device supports.
 
 1. Expand the **blink** command and set a new blink time interval. Select **Send command** to call the command on the device.
 
-1. Go to the simulated device to verify that the command executed as expected.
+1. Go to the simulated device command prompt and read through the printed confirmation messages, to verify that the commands have executed as expected.
 
 ## Next steps
 
 In this quickstart, you learned how to create an IoT Plug and Play device using a DCM.
 
-To learn more about IoT Plug and Play, continue to the tutorial:
+To learn more about DCMs and how to create your own models, continue to the tutorial:
 
 > [!div class="nextstepaction"]
-> [Create and test a device capability model using Visual Studio Code](tutorial-pnp-visual-studio-code.md)
+> [Tutorial: Create and test a device capability model using Visual Studio Code](tutorial-pnp-visual-studio-code.md)
