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 configuration to include the DTMI (Digital Twin Model Identifier). For C# models, the model generator tool adds or updates the AzureDigitalTwinModelName property in the appsettings.json file with the DTMI value. For rules-based models, the AzureDigitalTwinModelName property is added or updated in the ModelDefinition-{model name}.json file.

These tools 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 configuration 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

  • ScaleOut digital twin type: ScaleOut digital twin model type in the format “mymodelassembly.dll, namespace.modelclassname” (optional for rules-based models)

  • ScaleOut digital twin message type: ScaleOut digital twin message type in the format “mymodelassembly.dll, namespace.messageclassname” (optional for rules-based models)

  • 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

  • ScaleOut 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#/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.

Usage

java -jar ADTModelGenerator.jar
        --model-name <model-name>
        --rtdt-zip-file-path <zip-file-path>
        --dt-class <fully-qualified-class-name>
        [--adt-dtmi <dtmi>]
        [--output-dir <output-directory>]

Parameters

Required Parameters:

-m, –model-name <model-name> The ScaleOut Real-Time Digital Twin model name.

-z, –rtdt-zip-file-path <zip-file-path> The path to the ScaleOut Real-Time Digital Twin ZIP archive file.

-d, –dt-class <fully-qualified-class-name> The fully qualified Digital Twin class name.

This class must be an implementation of DigitalTwinBase.

Optional Parameters:

-a, –adt-dtmi <dtmi> The Azure Digital Twins Digital Twin Model Identifier.

If this parameter is not provided, a DTMI is generated based on the Digital Twin model name.

-o, –output-dir <output-directory> The output directory where the generated Azure Digital Twins DTDL v2 schema will be written.

If this parameter is not provided, the default output location is: ./out/

Example

java -jar ADTModelGenerator.jar
        --model-name ThermostatModel
        --rtdt-zip-file-path ./models/ThermostatModel.zip
        --dt-class com.example.twins.ThermostatTwin
        --adt-dtmi dtmi:com:example:Thermostat;1
        --output-dir ./generated-dtdl

The same command using short parameters:

java -jar ADTModelGenerator.jar
        -m ThermostatModel
        -z ./models/ThermostatModel.zip
        -d com.example.twins.ThermostatTwin
        -a dtmi:com:example:Thermostat;1
        -o ./generated-dtdl

Output

When the command completes successfully, the generated Azure Digital Twins DTDL v2 schema is written to the configured output directory.

If –output-dir is not specified, the schema is written to the default ./out directory relative to the current working directory.

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)

-t type, --sdt_model_type type

ScaleOut digital twin model type in the format “mymodelassembly.dll, namespace.modelclassname” (optional for rules-based models)

-s type, --sdt_message_type type

ScaleOut digital twin message type in the format “mymodelassembly.dll, namespace.messageclassname” (optional for rules-based models)

-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
                        -t "gentracker.dll, mycompany.GeneratorTracker"
                        -s "gentrackermsgs.dll, mycompany.GeneratorTrackerMessage"
                        -d "Generator Tracker"
ADTModelGenerator validate -m \path\to\GeneratorTracker_adt.json