Merge pull request #268915 from dominicbetts/model-repo-remove

IoT PnP: Remove publish to model repository references

Author: ttorble

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

@@ -39,7 +39,7 @@ For a device to interact with IoT Central, it must be assigned to a device templ
 IoT Central can automatically assign a device to a device template when the device connects. A device should send a [model ID](../../iot/iot-glossary.md?toc=/azure/iot-central/toc.json&bc=/azure/iot-central/breadcrumb/toc.json#model-id) when it connects. IoT Central uses the model ID to identify the device template for that specific device model. The discovery process works as follows:
 
 1. If the device template is already published in the IoT Central application, the device is assigned to the device template.
-1. If the device template isn't already published in the IoT Central application, IoT Central looks for the device model in the [public model repository](https://github.com/Azure/iot-plugandplay-models). If IoT Central finds the model, it uses it to generate a basic device template.
+1. If the device template isn't already published in the IoT Central application, IoT Central looks for the device model in the public device model repository. If IoT Central finds the model, it uses it to generate a basic device template.
 1. If IoT Central doesn't find the model in the public model repository, the device is marked as **Unassigned**. An operator can:
 
     - Create a device template for the device and then migrate the unassigned device to the new device template.

articles/iot-develop/.openpublishing.redirection.iot-develop.json

@@ -92,12 +92,12 @@
     },
     {
       "source_path_from_root": "/articles/iot-pnp/howto-manage-models.md",
-      "redirect_url": "/azure/iot-develop/concepts-model-discovery",
+      "redirect_url": "/azure/iot/concepts-model-discovery",
       "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-pnp/howto-use-iot-pnp-cli.md",
-      "redirect_url": "/azure/iot-develop/concepts-model-repository",
+      "redirect_url": "/azure/iot/concepts-model-discovery",
       "redirect_document_id": false
     },
     {
@@ -342,18 +342,18 @@
     },
     {
       "source_path_from_root": "/articles/iot-pnp/concepts-model-discovery.md",
-      "redirect_url": "/azure/iot-develop/concepts-model-discovery",
-      "redirect_document_id": true
+      "redirect_url": "/azure/iot/concepts-model-discovery",
+      "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-pnp/concepts-model-parser.md",
-      "redirect_url": "/azure/iot-develop/concepts-model-parser",
-      "redirect_document_id": true
+      "redirect_url": "/azure/iot/concepts-model-parser",
+      "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-pnp/concepts-model-repository.md",
-      "redirect_url": "/azure/iot-develop/concepts-model-repository",
-      "redirect_document_id": true
+      "redirect_url": "/azure/iot/concepts-model-discovery",
+      "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-pnp/connect-web.md",
@@ -493,12 +493,12 @@
     {
       "source_path_from_root": "/articles/iot-develop/concepts-model-discovery.md",
       "redirect_url": "/azure/iot/concepts-model-discovery",
-      "redirect_document_id": true
+      "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-develop/concepts-model-repository.md",
-      "redirect_url": "/azure/iot/concepts-model-repository",
-      "redirect_document_id": true
+      "redirect_url": "/azure/iot/concepts-model-discovery",
+      "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-develop/concepts-model-parser.md",
@@ -569,6 +569,11 @@
       "source_path_from_root": "/articles/iot-develop/quickstart-send-telemetry-central.md",
       "redirect_url": "/azure/iot-central/core/tutorial-connect-device",
       "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/iot/concepts-model-repository.md",
+      "redirect_url": "/azure/iot/concepts-model-discovery",
+      "redirect_document_id": true
     }
   ]
 }

articles/iot/TOC.yml

@@ -95,8 +95,6 @@ items:
             href: concepts-modeling-guide.md
           - name: Use models in a solution
             href: concepts-model-discovery.md
-          - name: Model repository
-            href: concepts-model-repository.md
           - name: Model parser
             href: concepts-model-parser.md
 

articles/iot/concepts-architecture.md

@@ -25,11 +25,9 @@ The following diagram shows the key elements of an IoT Plug and Play solution:
 
 ## Model repository
 
-The [model repository](./concepts-model-repository.md) is a store for model and interface definitions. You define models and interfaces using the [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md).
+The [model repository](./concepts-model-discovery.md) is a store for curated model and interface definitions. Models and interfaces are defined using the [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md).
 
-The web UI lets you manage the models and interfaces.
-
-The model repository has built-in role-based access controls that let you manage access to interface definitions.
+The web UI lets you search for and retrieve the models and interfaces.
 
 ## Devices
 
@@ -89,6 +87,5 @@ The backend solution can use the information from the interface definitions to:
 
 Now that you have an overview of the architecture of an IoT Plug and Play solution, the next steps are to learn more about:
 
-- [The model repository](./concepts-model-repository.md)
 - [Digital twin model integration](./concepts-model-discovery.md)
 - [Developing for IoT Plug and Play](./concepts-developer-guide-device.md)

articles/iot/concepts-model-discovery.md

@@ -3,7 +3,7 @@ title: Use IoT Plug and Play models in a solution | Microsoft Docs
 description: As a solution builder, learn about how you can use IoT Plug and Play models in your IoT solution.
 author: dominicbetts
 ms.author: dobett
-ms.date: 1/23/2024
+ms.date: 03/13/2024
 ms.topic: conceptual
 ms.service: iot
 ---
@@ -111,16 +111,69 @@ A solution can get the model definition by using one of the following options:
 
 ### Model repository
 
-Solutions can use the [model repository](concepts-model-repository.md) to retrieve models. Either the device builders or the solution builders must upload their models to the repository beforehand so the solution can retrieve them.
+Solutions can retrieve DTDL models from the device model repository (DMR). The DMR is a public repository, hosted by Microsoft, that contains a collection of curated DTDL models. The public device models stored in the DMR are available for everyone to consume and integrate in their applications from the public endpoint [https://devicemodels.azure.com](https://devicemodels.azure.com).
 
 After you identify the model ID for a new device connection, follow these steps:
 
-1. Retrieve the model definition using the model ID from the model repository. For more information, see [Device model repository](concepts-model-repository.md).
+1. Retrieve the model definition using the model ID from the model repository. For more information, see [Resolve models](#resolve-models).
 
 1. Using the model definition of the connected device, you can enumerate the capabilities of the device.
 
 1. Using the enumerated capabilities of the device, you can enable users to [interact with the device](tutorial-service.md).
 
+### Resolve models
+
+The DMR conventions include other artifacts for simplifying consumption of hosted models. These features are *optional* for custom or private repositories.
+
+- *Index*. All available DTMIs are exposed through an *index* composed by a sequence of json files, for example: [https://devicemodels.azure.com/index.page.2.json](https://devicemodels.azure.com/index.page.2.json)
+- *Expanded*. A file with all the dependencies is available for each interface, for example: [https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json](https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json)
+- *Metadata*. This file exposes key attributes of a repository and is refreshed periodically with the latest published models snapshot. It includes features that a repository implements such as whether the model index or expanded model files are available. You can access the DMR metadata at [https://devicemodels.azure.com/metadata.json](https://devicemodels.azure.com/metadata.json)
+
+To programmatically access the public DTDL models in the DMR, you can use the `ModelsRepositoryClient` available in the NuGet package [Azure.IoT.ModelsRepository](https://www.nuget.org/packages/Azure.IoT.ModelsRepository). This client is configured by default to query the public DMR available at [devicemodels.azure.com](https://devicemodels.azure.com/) and can be configured to any custom repository.
+
+The client accepts a `DTMI` as input and returns a dictionary with all required interfaces:
+
+```cs
+using Azure.IoT.ModelsRepository;
+
+var client = new ModelsRepositoryClient();
+ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
+models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));
+```
+
+The expected output displays the `DTMI` of the three interfaces found in the dependency chain:
+
+```txt
+dtmi:com:example:TemperatureController;1
+dtmi:com:example:Thermostat;1
+dtmi:azure:DeviceManagement:DeviceInformation;1
+```
+
+The `ModelsRepositoryClient` can be configured to query a custom DMR -available through http(s)- and to specify the dependency resolution by using the `ModelDependencyResolution` flag:
+
+- Disabled. Returns the specified interface only, without any dependency.
+- Enabled. Returns all the interfaces in the dependency chain
+
+> [!TIP]
+> Custom repositories might not expose the `.expanded.json` file. When this file isn't available, the client will fallback to process each dependency locally.
+
+The following sample code shows how to initialize the `ModelsRepositoryClient` by using a custom repository base URL, in this case using the `raw` URLs from the GitHub API without using the `expanded` form since it's not available in the `raw` endpoint. The `AzureEventSourceListener` is initialized to inspect the HTTP request performed by the client:
+
+```cs
+using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
+
+var client = new ModelsRepositoryClient(
+    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));
+
+ModelResult model = await client.GetModelAsync(
+    "dtmi:com:example:TemperatureController;1", 
+    dependencyResolution: ModelDependencyResolution.Enabled);
+
+model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));
+```
+
+There are more samples available in the Azure SDK GitHub repository: [Azure.Iot.ModelsRepository/samples](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/modelsrepository/Azure.IoT.ModelsRepository/samples).
+
 ### Custom store
 
 Solutions can store these model definitions in a local file system, in a public file store, or use a custom implementation.