Skip to content

Files

Latest commit

changeworldchangeworld
Fix typo
May 18, 2022
104039d · May 18, 2022

History

History
199 lines (129 loc) · 10.2 KB

concepts-model-repository.md

File metadata and controls

199 lines (129 loc) · 10.2 KB
title description author ms.author ms.date ms.topic ms.service services
Understand concepts of the device models repository | Microsoft Docs
As a solution developer or an IT professional, learn about the basic concepts of the device models repository.
rido-min
rmpablos
01/20/2022
conceptual
iot-develop
iot-develop

Device models repository

The device models repository (DMR) enables device builders to manage and share IoT Plug and Play device models. The device models are JSON LD documents defined using the Digital Twins Modeling Language (DTDL).

The DMR defines a pattern to store DTDL interfaces in a folder structure based on the device twin model identifier (DTMI). You can locate an interface in the DMR by converting the DTMI to a relative path. For example, the dtmi:com:example:Thermostat;1 DTMI translates to /dtmi/com/example/thermostat-1.json and can be obtained from the public base URL devicemodels.azure.com at the URL https://devicemodels.azure.com/dtmi/com/example/thermostat-1.json.

Index, expanded and metadata

The DMR conventions include additional artifacts for simplifying consumption of hosted models. These features are optional for custom or private repositories.

Public device models repository

Microsoft hosts a public DMR with these characteristics:

  • Curated models. Microsoft reviews and approves all available interfaces using a GitHub pull request (PR) validation workflow.
  • Immutability. After it's published, an interface can't be updated.
  • Hyper-scale. Microsoft provides the required infrastructure to create a secure, scalable endpoint where you can publish and consume device models.

Custom device models repository

Use the same DMR pattern to create a custom DMR in any storage medium, such as local file system or custom HTTP web servers. You can retrieve device models from the custom DMR in the same way as from the public DMR by changing the base URL used to access the DMR.

Note

Microsoft provides tools to validate device models in the public DMR. You can reuse these tools in custom repositories.

Public models

The public device models stored in the models repository are available for everyone to consume and integrate in their applications. Public device models enable an open eco-system for device builders and solution developers to share and reuse their IoT Plug and Play device models.

Refer to the Publish a model section for instructions on how to publish a model in the models repository to make it public.

Users can browse, search, and view public interfaces from the official GitHub repository.

All interfaces in the dtmi folders are also available from the public endpoint https://devicemodels.azure.com

Resolve models

To programmatically access these interfaces, you can use the ModelsRepositoryClient available in the NuGet package Azure.IoT.ModelsRepository. This client is configured by default to query the public DMR available at 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:

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 should display the DTMI of the three interfaces found in the dependency chain:

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

The ModelsRepositoryClient can be configured to query a custom model repository -available through http(s)- and specify the dependency resolution using any of the available ModelDependencyResolution:

  • 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 not available the client will fallback to process each dependency locally.

The next 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:

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 within the source code in the Azure SDK GitHub repository: Azure.Iot.ModelsRepository/samples

Publish a model

Important

You must have a GitHub account to be able to submit models to the public DMR.

  1. Fork the public GitHub repository: https://github.com/Azure/iot-plugandplay-models.
  2. Clone the forked repository. Optionally create a new branch to keep your changes isolated from the main branch.
  3. Add the new interfaces to the dtmi folder using the folder/filename convention. To learn more, see Import a Model to the dtmi/ folder.
  4. Validate the models locally using the dmr-client tool. To learn more, see validate models.
  5. Commit the changes locally and push to your fork.
  6. From your fork, create a pull request that targets the main branch. See Creating an issue or pull request docs.
  7. Review the pull request requirements.

The pull request triggers a set of GitHub Actions that validate the submitted interfaces, and makes sure your pull request satisfies all the requirements.

Microsoft will respond to a pull request with all checks in three business days.

dmr-client tools

The tools used to validate the models during the PR checks can also be used to add and validate the DTDL interfaces locally.

Note

This tool requires the .NET SDK version 3.1 or greater.

Install dmr-client

dotnet tool install --global Microsoft.IoT.ModelsRepository.CommandLine --version 1.0.0-beta.6

Import a model to the dtmi/ folder

If you have your model already stored in json files, you can use the dmr-client import command to add them to the dtmi/ folder with the correct file names:

# from the local repo root folder
dmr-client import --model-file "MyThermostat.json"

Tip

You can use the --local-repo argument to specify the local repository root folder.

Validate models

You can validate your models with the dmr-client validate command:

dmr-client validate --model-file ./my/model/file.json

Note

The validation uses the latest DTDL parser version to ensure all the interfaces are compatible with the DTDL language specification.

To validate external dependencies, they must exist in the local repository. To validate models, use the --repo option to specify a local or remote folder to resolve dependencies:

# from the repo root folder
dmr-client validate --model-file ./my/model/file.json --repo .

Strict validation

The DMR includes additional requirements, use the stict flag to validate your model against them:

dmr-client validate --model-file ./my/model/file.json --repo . --strict true

Check the console output for any error messages.

Export models

Models can be exported from a given repository (local or remote) to a single file using a JSON Array:

dmr-client export --dtmi "dtmi:com:example:TemperatureController;1" -o TemperatureController.expanded.json

Create the repository index

The DMR can include an index with a list of all the DTMIs available at the time of publishing. This file can be split in to multiple files as described in the DMR Tools Wiki.

To generate the index in a custom or private DMR, use the index command:

dmr-client index -r . -o index.json

Note

The public DMR is configured to provide an updated index available at: https://devicemodels.azure.com/index.json

Create expanded files

Expanded files can be generated using the command:

dmr-client expand -r .

Next steps

The suggested next step is to review the IoT Plug and Play architecture.