Merge pull request #280714 from dominicbetts/central-modelling

IoT Central: Clarifications around creating device templates

Author: v-dirichards

articles/iot-central/TOC.yml

@@ -111,7 +111,7 @@
       href: core/howto-create-iot-central-application.md
     - name: Build and connect devices
       items:
-        - name: Set up a device template
+        - name: Create a device template
           href: core/howto-set-up-template.md
         - name: Edit a device template
           href: core/howto-edit-device-template.md

articles/iot-central/core/concepts-device-templates.md

@@ -3,7 +3,7 @@ title: What are device templates in Azure IoT Central
 description: Device templates let you specify the behavior of the devices connected to your application. They also define a UI for the device in IoT Central.
 author: dominicbetts
 ms.author: dobett
-ms.date: 06/05/2023
+ms.date: 07/12/2024
 ms.topic: conceptual
 ms.service: iot-central
 services: iot-central
@@ -13,15 +13,15 @@ ms.custom: device-developer
 
 # What are device templates?
 
-A device template in Azure IoT Central is a blueprint that defines the characteristics and behaviors of a type of device that connects to your application. For example, the device template defines the telemetry that a device sends so that IoT Central can create visualizations that use the correct units and data types.
+A device template in Azure IoT Central is a blueprint that defines the characteristics and behaviors of a type of device that connects to your application. For example, the device template defines the telemetry that a device sends so that IoT Central can create visualizations that use the correct units and data types. Telemetry that matches the device template definition is referred to as *modeled* data. Telemetry that doesn't match the device template definition is referred to as *unmodeled* data.
 
-A solution builder adds device templates to an IoT Central application. A device developer writes the device code that implements the behaviors defined in the device template. To learn more about the data that a device exchanges with IoT Central, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).
+A solution builder adds device templates to an IoT Central application. A device developer writes the device code that implements the behaviors defined in the device template. To learn more about how to create a device template or have one automatically generated, see [Create a device template in your Azure IoT Central application](howto-set-up-template.md). To learn more about the data that a device exchanges with IoT Central, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).
 
 A device template includes the following sections:
 
 - _A device model_. This part of the device template defines how the device interacts with your application. Every device model has a unique ID. A device developer implements the behaviors defined in the model.
   - _Root component_. Every device model has a root component. The root component's interface describes capabilities that are specific to the device model.
-  - _Components_. A device model may include components in addition to the root component to describe device capabilities. Each component has an interface that describes the component's capabilities. Component interfaces may be reused in other device models. For example, several phone device models could use the same camera interface.
+  - _Components_. A device model can include components in addition to the root component to describe device capabilities. Each component has an interface that describes the component's capabilities. Component interfaces can be reused in other device models. For example, several phone device models could use the same camera interface.
   - _Inherited interfaces_. A device model contains one or more interfaces that extend the capabilities of the root component.
 - _Views_. This part of the device template lets the solution developer define visualizations to view data from the device, and forms to manage and control a device. Views don't affect the code that a device developer writes to implement the device model.
 
@@ -101,7 +101,7 @@ You can also mark a property as writable on an interface. A device can receive a
 
 Devices don't need to be connected to set property values. The updated values are transferred when the device next connects to the application. This behavior applies to both read-only and writable properties.
 
-Don't use properties to send telemetry from your device. For example, a readonly property such as `temperatureSetting=80` should mean that the device temperature has been set to 80, and the device is trying to get to, or stay at, this temperature.
+Don't use properties to send telemetry from your device. For example, a readonly property such as `temperatureSetting=80` should mean that the device temperature is set to 80, and the device is trying to get to, or stay at, this target temperature.
 
 For writable properties, the device application returns a desired state status code, version, and description to indicate whether it received and applied the property value.
 
@@ -249,6 +249,6 @@ A solution developer creates views that let operators monitor and manage connect
 - Tiles to let the operator call commands, including commands that expect a payload.
 - Tiles to display labels, images, or markdown text.
 
-## Next steps
+## Next step
 
 Now that you've learned about device templates, a suggested next step is to read [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md) to learn more about the data a device exchanges with IoT Central.

articles/iot-central/core/howto-manage-device-templates-with-rest-api.md

@@ -3,7 +3,7 @@ title: Add device templates in Azure IoT Central with the REST API
 description: How to use the IoT Central REST API to add, update, delete, and manage device templates in an application
 author: dominicbetts
 ms.author: dobett
-ms.date: 06/14/2023
+ms.date: 07/12/2024
 ms.topic: how-to
 ms.service: iot-central
 services: iot-central
@@ -180,7 +180,7 @@ The request body has some required fields:
 * `@id`: a unique ID in the form of a simple Uniform Resource Name.
 * `@type`: declares that the top-level object is a `"ModelDefinition","DeviceModel"`.
 * `@context`: specifies the DTDL version used for the interface.
-* `contents`: lists the properties, telemetry, and commands that make up your device. The capabilities may be defined in multiple interfaces.
+* `contents`: lists the properties, telemetry, and commands that make up your device. The capabilities can be defined in multiple interfaces.
 * `capabilityModel` : Every device template has a capability model. A relationship is established between each module capability model and a device model. A capability model implements one or more module interfaces.
 
 > [!TIP]
@@ -1308,7 +1308,3 @@ The response to this request looks like the following example:
     ]
 }
 ```
-
-## Next steps
-
-Now that you've learned how to manage device templates with the REST API, a suggested next step is to [How to create device templates from IoT Central GUI](howto-set-up-template.md#create-a-device-template).

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

@@ -3,7 +3,7 @@ title: Transform telemetry on ingress to IoT Central
 description: To use complex telemetry from devices, you can use mappings to transform it as it arrives in your IoT Central application.
 author: dominicbetts
 ms.author: dobett
-ms.date: 06/13/2023
+ms.date: 07/12/2024
 ms.topic: how-to
 ms.service: iot-central
 services: iot-central
@@ -18,6 +18,9 @@ Data mapping lets you transform complex device telemetry into structured data in
 * Normalize telemetry from different devices by mapping JSON paths on multiple devices to a common alias.
 * Export to destinations outside IoT Central.
 
+> [!TIP]
+> If you want to autogenerate a device template from unmodeled telemetry, see [Autogenerate a device template](howto-set-up-template.md#autogenerate-a-device-template).
+
 :::image type="content" source="media/howto-map-data/map-data-summary.png" alt-text="Diagram that summarizes the mapping process in IoT Central." border="false":::
 
 The following video walks you through the data mapping process:
@@ -150,7 +153,3 @@ The results of these mapping rules look like the following examples:
 ```
 
 Now you can use the mapped aliases to display telemetry on a chart or dashboard. You can also use the mapped aliases when you export telemetry.
-
-## Next steps
-
-Now that you've learned how to map data for your device, a suggested next step is to learn [How to use data explorer to analyze device data](howto-create-analytics.md).

articles/iot-central/core/howto-set-up-template.md

@@ -1,9 +1,9 @@
 ---
-title: Define a new IoT device type in Azure IoT Central
-description: How to create a device template in your Azure IoT Central application. You define the telemetry, state, properties, and commands for your device type.
+title: Create a device template in Azure IoT Central
+description: How to create a device template. You define the telemetry, state, properties, and commands for your template. Device templates can also be autogenerated.
 author: dominicbetts
 ms.author: dobett
-ms.date: 03/01/2024
+ms.date: 07/12/2024
 ms.topic: how-to
 ms.service: iot-central
 services: iot-central
@@ -13,11 +13,13 @@ ms.custom: device-developer
 #customer intent: As an solution builders, I want define the device types that can connect to my application so that I can manage and monitor them effectively.
 ---
 
-# Define a new IoT device type in your Azure IoT Central application
+# Create a device template in your Azure IoT Central application
 
-A device template is a blueprint that defines the characteristics and behaviors of a type of device that connects to an Azure IoT Central application.
+A device template is a blueprint that defines the characteristics and behaviors of a type of device that connects to an Azure IoT Central application. For example, you can create a device template for a sensor that sends telemetry, such as temperature and properties, such as location. To learn more, see [What are device templates?](concepts-device-templates.md).
 
-This article describes how to create a device template in IoT Central. For example, you can create a device template for a sensor that sends telemetry, such as temperature and properties, such as location. From this device template, an operator can create and connect real devices.
+This article describes some of the ways to create a device template in IoT Central such as [autogenerating a device template from a telemetry message](#autogenerate-a-device-template) or defining one in the [IoT Central UI](#create-a-device-template-in-your-azure-iot-central-application).
+
+From a device template, an operator can create and connect real devices.
 
 The following screenshot shows an example of a device template:
 
@@ -29,15 +31,11 @@ The device template has the following sections:
 - Raw data - View the raw data sent by your designated preview device. This view is useful when you're debugging or troubleshooting a device template.
 - Views - Use views to visualize the data from the device and forms to manage and control a device.
 
-To learn more, see [What are device templates?](concepts-device-templates.md).
-
 To learn how to manage device templates by using the IoT Central REST API, see [How to use the IoT Central REST API to manage device templates.](../core/howto-manage-device-templates-with-rest-api.md)
 
-## Create a device template
-
 You have several options to create device templates:
 
-- Design the device template in the IoT Central GUI.
+- Design the device template in the IoT Central UI.
 - Import a device template from the list of featured device templates. Optionally, customize the device template to your requirements in IoT Central.
 - When the device connects to IoT Central, have it send the model ID of the model it implements. IoT Central uses the model ID to retrieve the model from the model repository and to create a device template. Add any cloud properties and views your IoT Central application needs to the device template.
 - When the device connects to IoT Central, let IoT Central [autogenerate a device template](#autogenerate-a-device-template) definition from the data the device sends.
@@ -47,7 +45,9 @@ You have several options to create device templates:
 > [!NOTE]
 > In each case, the device code must implement the capabilities defined in the model. The device code implementation isn't affected by the cloud properties and views sections of the device template.
 
-This section shows you how to import a device template from the list of featured device templates and how to customize it using the IoT Central GUI. This example uses the **Onset Hobo MX-100 Temp Sensor** device template from the list of featured device templates:
+## Import a device template
+
+This section shows you how to import a device template from the list of featured device templates and how to customize it using the IoT Central UI. This example uses the **Onset Hobo MX-100 Temp Sensor** device template from the list of featured device templates:
 
 1. To add a new device template, select **+ New** on the **Device templates** page.
 1. On the **Select type** page, scroll down until you find the **Onset Hobo MX-100 Temp Sensor** tile in the **Featured device templates** section.
@@ -78,9 +78,9 @@ The following steps show how to use this feature:
 
     :::image type="content" source="media/howto-set-up-template/infer-model-3.png" alt-text="Screenshot that shows how to rename the autogenerated device template." lightbox="media/howto-set-up-template/infer-model-3.png":::
 
-## Manage a device template
+## Manage device templates in the UI
 
-You can rename or delete a template from the template's editor page.
+You can create, edit, rename, or delete a template from the template's editor page.
 
 After you define the template, you can publish it. Until the template is published, you can't connect a device to it, and it doesn't appear on the **Devices** page.
 
@@ -283,6 +283,6 @@ Add forms to a device template to enable operators to manage a device by viewing
 
 Before you can connect a device that implements your device model, you must publish your device template.
 
-To publish a device template, go to you your device template, and select **Publish**.
+To publish a device template, go to your device template, and select **Publish**.
 
 After you publish a device template, an operator can go to the **Devices** page, and add either real or simulated devices that use your device template. You can continue to modify and save your device template as you're making changes. When you want to push these changes out to the operator to view under the **Devices** page, you must select **Publish** each time.