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.

Learn more about GitHub
Sign Contributor License Agreement
Fork the public GitHub repo: https://github.com/Azure/iot-plugandplay-models.

Learn more about forking a repo
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 add-models tool 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.

Learn more about pull request

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` Tool

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

Note: These tools require the .NET SDK (3.1 or greater)

Install `dmr-client`

Linux/Bash

curl -L https://aka.ms/install-dmr-client-linux | bash

Windows/Powershell

iwr https://aka.ms/install-dmr-client-windows -UseBasicParsing | iex

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 those to the dtmi/ folder with the right file name.

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

Note: You can use the --local-repo argument to specify the local repo 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 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.

# from the repo root folder
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.

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

Export models

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

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

Consuming

Any HTTP client can consume the models by just applying the convention to translate DTMI ids to relative paths:

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 with code you can use to acquire models from 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.

bawilless/iot-plugandplay-models