Azure Digital Twins Model Generator Tools

The ScaleOut Digital Twin Builder™ Software Toolkit provides two tools that assist in integrating real-time digital twin models with Azure Digital Twins models. These tools generate an Azure Digital Twins model definition in JSON format from the zip file that holds a real-time digital twin model and updates the existing real-time digital twin’s model.json file to include the DTMI (Digital Twin Model Identifier). They store the properties defined in the real-time digital twin model in an Azure digital twin component named “scaleout_rtdt”. This component can be used either to create a new Azure digital twin model or to add a new component to an existing model. For convenience in creating a new model, the model definition file also contains a skeleton Azure Digital Twins model with the component as its only contents.

Note

These tools also update the real-time digital twin model’s zip file to include the Azure model identifier in the real-time digital twin model’s JSON specification file.

Once you have created an Azure Digital Twins model definition, you can upload it to the Azure Digital Twins service. This should be done prior to deploying the real-time digital twin model to ScaleOut Digital Twins™.

The model generator tools require the following parameters:

  • Azure digital twin model identifier: an identifier in the format dtmi:<domain>:<unique-model-identifier>;<model-version-number>, where domain and unique model identifier are arbitrary strings and model version number is a number; for example, dtmi:mycompany:mydigitaltwin;1

  • Azure digital twin model display name: a string to be used as a display name for the Azure digital twin model in the Azure Digital Twins Explorer

  • Real-time digital twin file path: full path name for the zip file that implements a real-time digital twin model

  • Azure digital twins model file path: full path name for the Azure digital twin model definition JSON file that is produced by the tool.

Separate model generation tools are provided for Java-based real-time digital twin models and for C# or rules-based models. In addition to generating a model definition, the C# tool can validate a model definition file prior to uploading it to the Azure Digital Twins service.

Note

Note that rules-based models are created using the ScaleOut Model Development Tool and can include machine learning algorithms.

The following sections describe the specific command-line options for the two tools with examples.

Model Generator for Java Models

The Azure Digital Twins model generator for Java real-time digital twins is available as a Java jar file called ADTModelGenerator.jar. It can be downloaded as a zip file from ScaleOut Software’s web site here.

You can invoke the model generator as follows:

java -jar ADTModelGenerator.jar <options>

where the available options are:

-m identifier, --adt_model_id identifier

Azure digital twin model identifier (DTMI)

-d description, --display_name description

Azure digital twin model description

-z file, --rtdt_zip_file_path file

Path to the real-time digital twin zip file

-a file, --adt_model_json_file_path file

Output path for the Azure digital twin model definition file

Example:

java -jar ADTModelGenerator.jar -z /path/to/GeneratorTracker.zip -a /path/to/output/GeneratorTracker_adt.json  -m dtmi:mycompany:GeneratorTracker;1 -d "Generator Tracker"

Model Generator for C# and Rules-Based Models

The Azure Digital Twins model generator for C#/rules-based real-time digital twin models runs as a .NET tool and downloaded from a NuGet package.

You can install the model generator tool from nuget.org using the following command:

dotnet tool install -g Scaleout.AzureDigitalTwins.ModelGenerator

Note

The -g flag installs the tool globally for the user. If omitted, the tool will be installed as a local tool for the current directory. See dotnet tool install for more information.

The tool can be updated as follows:

dotnet tool update -g Scaleout.AzureDigitalTwins.ModelGenerator

The following command uninstalls the tool:

dotnet tool uninstall -g Scaleout.AzureDigitalTwins.ModelGenerator

Note

Omit the -g flag in the update and uninstall commands if the tool was installed in the local folder.

You can invoke the model generator tool as follows:

ADTModelGenerator <verb> <options>

where the available verbs are:

  • build: generate an Azure digital twins model definition from a real-time digital twin model

  • validate: validate an Azure digital twin model definition file for correctness

  • help: display help information

  • version: display version information

The options available for the build verb are:

-m identifier, --adt_model_id identifier

Azure digital twin model identifier (DTMI)

-d description, --display_name description

Azure digital twin model description

-z file, --rtdt_zip_file_path file

Path to the real-time digital twin zip file

-a file, --adt_model_json_file_path file

Output path for the Azure digital twin model definition file

--help

Displays help

--version

Displays version

The options available for the validate verb are:

-m file, --adt_model_json_file_path file

Path to the Azure digital twin model definition file

--help

Displays help

--version

Displays version

Important

The model definition zip file will be updated at the end of a successful run of the build command to add the ‘AzureDigitalTwinModelName’ parameter with the ‘adt_model_id’ value.

Example:

ADTModelGenerator build -z \path\to\GeneratorTracker.zip -a \path\to\output\GeneratorTracker_adt.json -m dtmi:mycompany:GeneratorTracker;1 -d "Generator Tracker"
ADTModelGenerator validate -m \path\to\GeneratorTracker_adt.json