Merge pull request #215234 from dominicbetts/central-edge-tutorial

IoT Central: add IoT Edge tutorial

Author: 19BMG00

articles/iot-central/TOC.yml

@@ -25,12 +25,12 @@
       items:
       - name: Create and connect a device
         href: core/tutorial-connect-device.md
-      - name: Create a gateway device template
-        href: core/tutorial-define-gateway-device-type.md
-      - name: Connect an IoT Edge device
-        href: /training/modules/connect-iot-edge-device-to-iot-central
       - name: Create a device group
         href: core/tutorial-use-device-groups.md
+      - name: Connect an IoT Edge device
+        href: core/tutorial-connect-iot-edge-device.md
+      - name: Create a gateway device template
+        href: core/tutorial-define-gateway-device-type.md
     - name: Extend your application
       items:
       - name: Create a rule

articles/iot-central/core/how-to-connect-iot-edge-transparent-gateway.md

@@ -143,7 +143,7 @@ To let you try out this scenario, the following steps show you how to deploy the
 
 To try out the transparent gateway scenario, select the following button to deploy two Linux virtual machines. One virtual machine has the IoT Edge 1.1 runtime installed and is the transparent IoT Edge gateway. The other virtual machine is a downstream device where you run code to send simulated thermostat telemetry:
 
-[![Deploy to Azure Button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure-Samples%2Fiot-central-docs-samples%2Fmaster%2Ftransparent-gateway-1-1%2FDeployGatewayVMs.json)
+[![Deploy to Azure Button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure-Samples%2Fiot-central-docs-samples%2Fmain%2Ftransparent-gateway-1-1%2FDeployGatewayVMs.json)
 
 When the two virtual machines are deployed and running, verify the IoT Edge gateway device is running on the `edgegateway` virtual machine:
 
@@ -160,7 +160,7 @@ When the two virtual machines are deployed and running, verify the IoT Edge gate
 
 To try out the transparent gateway scenario, select the following button to deploy two Linux virtual machines. One virtual machine has the IoT Edge 1.2 runtime installed and is the transparent IoT Edge gateway. The other virtual machine is a downstream device where you run code to send simulated thermostat telemetry:
 
-[![Deploy to Azure Button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure-Samples%2Fiot-central-docs-samples%2Fmaster%2Ftransparent-gateway-1-2%2FDeployGatewayVMs.json)
+[![Deploy to Azure Button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure-Samples%2Fiot-central-docs-samples%2Fmain%2Ftransparent-gateway-1-2%2FDeployGatewayVMs.json)
 
 When the two virtual machines are deployed and running, verify the IoT Edge gateway device is running on the `edgegateway` virtual machine:
 

articles/iot-central/core/howto-transform-data.md

@@ -258,7 +258,7 @@ For convenience, this article uses Azure virtual machines to run the gateway and
 | Authentication Type | Password |
 | Admin Password Or Key | Your choice of password for the **AzureUser** account on both virtual machines. |
 
-[![Deploy to Azure Button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure-Samples%2Fiot-central-docs-samples%2Fmaster%2Ftransparent-gateway-1-1%2FDeployGatewayVMs.json)
+[![Deploy to Azure Button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure-Samples%2Fiot-central-docs-samples%2Fmain%2Ftransparent-gateway-1-1%2FDeployGatewayVMs.json)
 
 Select **Review + Create**, and then **Create**. It takes a couple of minutes to create the virtual machines in the **ingress-scenario** resource group.
 

articles/iot-central/core/media/tutorial-connect-iot-edge-device/deployment-manifests.png

@@ -90,4 +90,4 @@ On this view, you can select the columns to display and set a time range to view
 If you'd prefer to continue through the set of IoT Central tutorials and learn more about building an IoT Central solution, see:
 
 > [!div class="nextstepaction"]
-> [Create a gateway device template](./tutorial-define-gateway-device-type.md)
+> [Tutorial: Use device groups to analyze device telemetry](tutorial-use-device-groups.md)

articles/iot-central/core/media/tutorial-connect-iot-edge-device/environmental-telemetry-view.png

@@ -0,0 +1,220 @@
+---
+title: Tutorial - Connect an IoT Edge device to Azure IoT Central | Microsoft Docs
+description: This tutorial shows you how to connect an IoT Edge device to your IoT Central application. You first create an unassigned device, and then add a device template to enable views and forms for an operator to be able to interact with the device.
+author: dominicbetts
+ms.author: dobett
+ms.date: 10/18/2022
+ms.topic: tutorial
+ms.service: iot-central
+services: iot-central
+ms.custom: [device-developer]
+
+# Customer intent: As a solution developer, I want to learn how to connect an IoT Edge device to IoT Central and then configure views and forms so that I can interact with the device.
+---
+
+# Tutorial: Connect an IoT Edge device to your Azure IoT Central application
+
+This tutorial shows you how to connect an IoT Edge device to your Azure IoT Central application. The IoT Edge device runs a module that sends temperature, pressure, and humidity telemetry to your application. You use a device template to enable views and forms that let you interact with the module on the IoT Edge device.
+
+In this tutorial, you learn how to:
+
+> [!div class="checklist"]
+> * Import an IoT Edge deployment manifest into your IoT Central application.
+> * Add an IoT Edge device that uses this deployment manifest to your application.
+> * Connect the IoT Edge device to your application.
+> * Monitor the IoT Edge runtime from your application.
+> * Add a device template with views and forms to your application.
+> * View the telemetry sent from the device in your application.
+
+## Prerequisites
+
+To complete the steps in this tutorial, you need:
+
+[!INCLUDE [iot-central-prerequisites-basic](../../../includes/iot-central-prerequisites-basic.md)]
+
+You also need to be able to upload configuration files to your IoT Central application from your local machine.
+
+## Import a deployment manifest
+
+A deployment manifest specifies the configuration of an IoT Edge device including the details of any custom modules the device should download and run. IoT Edge devices that connect to an IoT Central application download their deployment manifests from the application.
+
+To add a deployment manifest to IoT Central to use in this tutorial:
+
+1. Download and save the [EnvironmentalSensorManifest-1-4.json](https://raw.githubusercontent.com/Azure-Samples/iot-central-docs-samples/main/iotedge/EnvironmentalSensorManifest-1-4.json) deployment manifest to your local machine.
+
+1. In your IoT Central application, navigate to the **Edge manifests** page.
+
+1. Select **+ New**.
+
+1. On the **Customize** page, enter *Environmental Sensor* as the name and then upload the *EnvironmentalSensorManifest-1-4.json* file.
+
+1. After the manifest file is validated, select **Next**.
+
+1. The **Review and finish** page shows the modules defined in the manifest, including the **SimulatedTemperatureSensor** custom module. Select **Create**.
+
+The **Edge manifests** list now includes  the **Environmental sensor** manifest:
+
+:::image type="content" source="media/tutorial-connect-iot-edge-device/deployment-manifests.png" alt-text="Screenshot that shows the Edge Manifests list in the application.":::
+
+## Add an IoT Edge device
+
+Before the IoT Edge device can connect to your IoT Central application, you need to add it to the list of devices and get its credentials:
+
+1. In your IoT Central application, navigate to the **Devices** page.
+
+1. On the **Devices** page, make sure that **All devices** is selected. Then select **+ New**.
+
+1. On the **Create a new device** page:
+    * Enter *Environmental sensor - 001* as the device name.
+    * Enter *env-sens-001* as the device ID.
+    * Make sure that the device template is **unassigned**.
+    * Make sure that the device isn't simulated.
+    * Set **Azure IoT Edge device** to **Yes**.
+    * Select the **Environmental sensor** IoT Edge deployment manifest.
+
+1. Select **Create**.
+
+The list of devices on the **Devices** page now includes the **Environmental sensor - 001** device. The device status is **Registered**:
+
+:::image type="content" source="media/tutorial-connect-iot-edge-device/registered-sensor-device.png" alt-text="Screenshot that shows the registered and unassigned IoT Edge device.":::
+
+Before you deploy the IoT Edge device, you need the:
+
+* **ID Scope** of your IoT Central application.
+* **Device ID** values for the gateway and downstream devices.
+* **Primary key** values for the gateway and downstream devices.
+
+To find these values, navigate to the **Environmental sensor - 001** device from the **Devices** page and select **Connect**. Make a note of these values before you continue.
+
+## Deploy the IoT Edge device
+
+In this tutorial, you deploy the IoT Edge runtime to a Linux virtual machine in Azure. To deploy and configure the virtual machine, select the following button:
+
+[![Deploy to Azure Button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure-Samples%2Fiot-central-docs-samples%2Fmain%2Fedge-vm-deploy-1-4%2FedgeDeploy.json)
+
+On the **Custom deployment** page, use the following values to complete the form:
+
+| Setting | Value |
+| ------- | ----- |
+| `Resource group` | Create a new resource group with a name such as *MyIoTEdgeDevice_rg*. |
+| `Region` | Select a region close to you. |
+| `Dns Label Prefix` | A unique DNS prefix for your virtual machine.  |
+| `Admin Username` |  *AzureUser* |
+| `Admin Password` | A password of your choice to access the virtual machine. |
+| `Scope Id` | The ID scope you made a note of previously. |
+| `Device Id` | The device ID you made a note of previously. |
+| `Device Key` |  The device key you made a note of previously. |
+
+Select **Review + create** and then **Create**. Wait for the deployment to finish before you continue.
+
+## Manage the IoT Edge device
+
+To verify the deployment of the IoT Edge device was successful:
+
+1. In your IoT Central application, navigate to the **Devices** page. Check the status of the **Environmental sensor - 001** device is **Provisioned**. You may need to wait for a few minutes while the device connects.
+
+1. Navigate to the **Environmental sensor - 001** device.
+
+1. On the **Modules** page, check the status of the three modules is **Running**.
+
+On the **Modules** page, you can view status information about the modules and perform actions such as viewing their logs and restarting them.
+
+## View raw data
+
+On the **Raw data** page for the **Environmental sensor - 001** device, you can see the telemetry it's sending and the property values it's reporting.
+
+At the moment, the IoT Edge device doesn't have a device template assigned, so all the data from the device is **Unmodeled**. Without a device template, there are no views or dashboards to display custom device information in the IoT Central application. However, you can use data export to forward the data to other services for analysis or storage.
+
+## Add a device template
+
+A deployment manifest may include definitions of properties exposed by a module. For example, the configuration in the deployment manifest for the **SimulatedTemperatureSensor** module includes the following:
+
+```json
+"SimulatedTemperatureSensor": {
+    "properties.desired": {
+        "SendData": true,
+        "SendInterval": 10
+    }
+}
+```
+
+The following steps show you how to add a device template for an IoT Edge device and the module property definitions from the deployment manifest:
+
+1. In your IoT Central application, navigate to the **Device templates** page and select **+ New**.
+
+1. On the **Select type** page, select **Azure IoT Edge**, and then **Next: Customize**.
+
+1. On the **Customize** page, enter **Environmental sensor** as the device template name.
+
+1. On the **Review** page, select **Create**.
+
+1. On the **Create a model** page, select **Custom model**.
+
+1. On the **Environmental sensor** page, select **Modules**, then **Import modules from manifest**.
+
+1. In the **Import modules** dialog, select the **Environmental sensor** deployment manifest, then **Import**.
+
+The device template now includes a module called **SimulatedTemperatureSensor**, with an interface called **management**. This interface includes definitions of the **SendData** and **SendInterval** properties from the deployment manifest.
+
+A deployment manifest can only define module properties, not commands or telemetry. To add the telemetry definitions to the device template:
+
+1. Download and save the [EnvironmentalSensorTelemetry.json](https://raw.githubusercontent.com/Azure-Samples/iot-central-docs-samples/main/iotedge/EnvironmentalSensorTelemetry.json) interface definition to your local machine.
+
+1. Navigate to the **SimulatedTemperatureSensor** module in the **Environmental sensor** device template.
+
+1. Select **Add inherited interface** (you may need to select **...** to see this option). Select **Import interface**. Then import the *EnvironmentalSensorTelemetry.json* file you previously downloaded.
+
+The module now includes a **telemetry** interface that defines **machine**, **ambient**, and **timeCreated** telemetry types:
+
+:::image type="content" source="media/tutorial-connect-iot-edge-device/telemetry-interface.png" alt-text="Screenshot that shows the device template with the telemetry interface.":::
+
+To add a view that plots telemetry from the device:
+
+1. In the **Environmental sensor** device template, select **Views**.
+
+1. On the **Select to add a new view** page, select **Visualizing the device**.
+
+1. Enter *Environmental telemetry* as the view name.
+
+1. Select **Start with devices**. Then add the following telemetry types:
+    * **ambient/temperature**
+    * **humidity**
+    * **machine/temperature**
+    * **pressure**
+
+1. Select **Add tile**, then **Save**.
+
+1. To publish the template, select **Publish**.
+
+## View telemetry and control module
+
+To view the telemetry from your device, you need to attach the device to the device template:
+
+1. Navigate to the **Devices** page and select the **Environmental sensor - 001** device.
+
+1. Select **Migrate**.
+
+1. In the **Migrate** dialog, select the **Environmental sensor** device template, and select **Migrate**.
+
+1. Navigate to the **Environmental sensor - 001** device and select the **Environmental telemetry** view.
+
+1. The line chart plots the four telemetry values you selected for the view:
+
+    :::image type="content" source="media/tutorial-connect-iot-edge-device/environmental-telemetry-view.png" alt-text="Screenshot that shows the telemetry line charts.":::
+
+1. The **Raw data** page now includes columns for the **ambient**, **machine**, and **timeCreated** telemetry values.
+
+To control the module by using the properties defined in the deployment manifest, navigate to the **Environmental sensor - 001** device and select the **Manage** view.
+
+IoT Central created this view automatically from the **manage** interface in the **SimulatedTemperatureSensor** module. The **Raw data** page now includes columns for the **SendData** and **SendInterval** properties.
+
+## Clean up resources
+
+[!INCLUDE [iot-central-clean-up-resources](../../../includes/iot-central-clean-up-resources.md)]
+
+## Next steps
+
+If you'd prefer to continue through the set of IoT Central tutorials and learn more about building an IoT Central solution, see:
+
+> [!div class="nextstepaction"]
+> [Create a gateway device template](./tutorial-define-gateway-device-type.md)

articles/iot-central/core/media/tutorial-connect-iot-edge-device/registered-sensor-device.png

@@ -22,7 +22,7 @@ In this tutorial, you create a **Smart Building** gateway device template. A **S
 As well as enabling downstream devices to communicate with your IoT Central application, a gateway device can also:
 
 * Send its own telemetry, such as temperature.
-* Respond to writable property updates made by an operator. For example, an operator could changes the telemetry send interval.
+* Respond to writable property updates made by an operator. For example, an operator could change the telemetry send interval.
 * Respond to commands, such as rebooting the device.
 
 In this tutorial, you learn how to:
@@ -163,7 +163,7 @@ To create a simulated gateway device:
 
 1. Keep the generated **Device ID** and **Device name**. Make sure that the **Simulated** switch is **On**. Select **Create**.
 
-To create a simulated downstream devices:
+To create simulated downstream devices:
 
 1. On the **Devices** page, select **RS40 Occupancy Sensor** in the list of device templates.
 
@@ -207,7 +207,7 @@ Both your simulated downstream devices are now connected to your simulated gatew
 
 In the [Create and connect a client application to your Azure IoT Central application](tutorial-connect-device.md) tutorial, the sample code shows how to include the model ID from the device template in the provisioning payload the device sends.
 
-When you connect a downstream device, you can modify the provisioning payload to include the the ID of the gateway device. The model ID lets IoT Central assign the device to the correct downstream device template. The gateway ID lets IoT Central establish the relationship between the downstream device and its gateway. In this case the provisioning payload the device sends looks like the following JSON:
+When you connect a downstream device, you can modify the provisioning payload to include the ID of the gateway device. The model ID lets IoT Central assign the device to the correct downstream device template. The gateway ID lets IoT Central establish the relationship between the downstream device and its gateway. In this case the provisioning payload the device sends looks like the following JSON:
 
 ```json
 {
@@ -329,4 +329,4 @@ In this tutorial, you learned how to:
 Next you can learn how to:
 
 > [!div class="nextstepaction"]
-> [Add an Azure IoT Edge device to your Azure IoT Central application](/training/modules/connect-iot-edge-device-to-iot-central/)
+> [Create a rule and set up notifications in your Azure IoT Central application](tutorial-create-telemetry-rules.md)