Azure/iot-plugandplay-models repository
This repository includes DTDL models that are made publicly available on https://devicemodels.azure.com. These models can be used to create Azure IoT Plug and Play solutions.
Related tools, samples, and specs can be found in the Azure/iot-plugandplay-models-tools repo. The current repo only stores DTDL models.
Submit a model
-
Create a GitHub account if you do not have one yet: Join GitHub.
-
Fork the public GitHub repo: https://github.com/Azure/iot-plugandplay-models.
-
Clone the forked repo. Optionally create a new branch to keep your changes isolated from the
main
branch.By forking and cloning the public GitHub repo, a copy of repo will be created in your GitHub account and a local copy is created in your dev machine. Please use this local copy to make modifications.
-
Author a new device model with an unique ID using Digital Twin Model Identifier.
Review the PR requirements for naming conventions.
[!TIP]
DTDL Editor for Visual Studio Code could help you with the language syntax (including auto-completion) and also validate the syntax with DTDL v2. -
Save the device model JSON file to a local folder.
E.g.
C:\iot-plugandplay-models\MyThermostat.json
-
Validate the models locally using the
dmr-client
tool to validate. -
Add the new interfaces to the
dtmi
folder using the folder/filename convention. See the import command below. -
Review and cross check with the PR requirements and ensure all elements are conform to DTDL v2 specification.
-
Commit the changes locally and push to your fork.
-
From your fork, create a PR that targets the
main
branch.
The PR triggers a series of GitHub actions that will validate the new submitted interfaces, and make sure your PR satisfies all the checks.
Microsoft will respond to a PR with all checks in 3 business days.
GitHub Operation Workflow
+-------------------------------------------------+
| iot-plugandplay-models repo (Microsoft) |
+-------------------------------------------------+
| ⭡
| Fork | Pull Request (PR)
🡓 |
+-------------------------------------------------+
| iot-plugandplay-models repo (your Github account) |
+-------------------------------------------------+
| ⭡
| Clone | Commit/Push
🡓 |
+-------------------------------------------------+
| Your development PC |
| - Author device model |
| - Import your model to the DTMI folder |
+-------------------------------------------------+
dmr-client
command line tool
Install the The tool used to validate the models during the PR checks can also be used to add and validate the DTDL interfaces locally.
The Device Models Repository command line tool (aka dmr-client
) is published on NuGet and requires dotnet sdk 3.1
or dotnet sdk 5.0
.
Note: .NET 6 is not yet supported.
You can use the dotnet
command line via the dotnet tool install
command to install dmr-client
. The following is an example to install dmr-client
as a global tool:
> dotnet tool install -g Microsoft.IoT.ModelsRepository.CommandLine --version 1.0.0-beta.4
To learn how to install dmr-client
in a local context, please see this guide.
Note: Previous versions of the tool (prior to
1.0.0-beta.3
) must first be uninstalled withdotnet tool uninstall -g dmr-client
. Use thedotnet tool list -g
command to check the id of the tool you want to uninstall.
Update
To update the dmr-client
tool (assuming a global install) you can run the following command:
> dotnet tool update -g Microsoft.IoT.ModelsRepository.CommandLine --version [target version]
Uninstall
To uninstall the dmr-client
tool (assuming a global install) you can run the following command:
> dotnet tool uninstall -g Microsoft.IoT.ModelsRepository.CommandLine
dmr-client
Usage of After installing Microsoft.IoT.ModelsRepository.CommandLine
the following models repository management commands should be available for usage via the dmr-client
alias.
dmr-client:
Microsoft IoT Models Repository CommandLine v1.0.0-beta.4
Usage:
dmr-client [options] [command]
Options:
--debug Shows additional logs for debugging.
--silent Silences command output on standard out.
--version Show version information
-?, -h, --help Show help and usage information
Commands:
export Exports a model producing the model and its dependency chain in an expanded format. The target repository is used for model resolution.
validate Validates the DTDL model contained in a file. When validating a single model object the target repository is used for model resolution. When
validating an array of models only the array contents is used for resolution.
import Imports models from a model file into the local repository. The local repository is used for model resolution.
index Builds a model index file from the state of a target local models repository.
expand For each model in a local repository, generate expanded model files and insert them in-place. The expanded version of a model includes the model with
its full model dependency chain.
Command Guide
dtmi/
folder
Import a Model to the If you have your model already stored in json files, you can use the dmr-client import
command to add those to the dtmi/
folder with the right file name.
# from the local repo root folder
> dmr-client import --model-file "MyThermostat.json"
This command will rename and locate the file in the appropriate folder
Validate Models
You can validate your models with the dmr-client validate
command.
# Validate a model file using the DTDL parser
> 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 spec
To validate external dependencies, those must exist in the local repo. To validate those you can specify a local
or remote
folder to validate against.
# Validate a model file using the DTDL parser checking dependencies with the current folder as a local repo
> dmr-client validate --model-file ./my/model/file.json --repo .
Strict validation
The Device Model Repo includes additional requirements, these can be validated with the strict
flag.
# Validate a model file using the DTDL parser checking dependencies with the current folder as a local repo in strict mode
> dmr-client validate --model-file ./my/model/file.json --repo . --strict
Export models
Models can be exported from a given repo (local or remote) to a single file using a JSON Array.
# Retrieves an interface from a custom repo by DTMI
> dmr-client export --dtmi "dtmi:com:example:Thermostat;1" --repo https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main
Create Index
The model repo can host a index.json
file with all the ids
avaialble in the repository. Read the Index Spec
# Builds a model index for the repository. If models exceed the page limit new page files will be created relative to the root index.
> dmr-client index --local-repo .
# Build a model index with a custom page limit indicating max models per page.
> dmr-client index --local-repo . --page-limit 100
Create Expanded files
# Expand all models from the root directory of a local models repository following Azure IoT conventions.
# Expanded models are inserted in-place.
> dmr-client expand --local-repo .
# The default --local-repo value is the current directory. Be sure to specifiy the root for --local-repo.
> dmr-client expand
IoT Models Repository SDKs
Azure SDKs focused on models repository consumption are available in the following languages:
Platform | Package | Source | Samples |
---|---|---|---|
.NET | Azure.IoT.ModelsRepository | Source | Samples |
Java | com.azure/azure-iot-modelsrepository | Source | Samples |
Node | @azure/iot-modelsrepository | Source | Samples |
Python | azure-iot-modelsrepository | Source | Samples |
Fetch models without any SDK
Any HTTP client can consume the models by applying the repository convention to convert a DTMI
to a relative path:
Eg, the interface:
dtmi:azure:DeviceManagement:DeviceInformation;1
can be retrieved from here:
https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json
There are samples for .NET and Node in the Azure/iot-plugandplay-models-tools GitHub repository with code you can use to acquire models for your custom IoT solution.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.