Add Model(s) to Digital Twin for multiple Litmus Edge
To add Model(s) with Litmus Excel Add-ins, you should be familiar with how Models work in Digital Twins on Litmus Edge.
Before You Begin
- You have installed the Litmus Excel Add-ins extension. See Install Litmus Excel Add-ins for details.
Initial Preparation
Open a new DT Model Management Tool File in Excel.
If prompted, Enable Content to allow the code to run.
Make sure the the tool is for the Connect To option set to Multiple LE.
Add Models(s)
Mandatory Model Settings
Set the Target Litmus Edge IP
Enter the IPv4 of the Litmus Edge you want add the device on into column Target Litmus Edge IP.
If no API Key for the device was previously provided, the user will need to provide the API key.
Notes:
If no API Key for the device was previously provided, the user will need to provide the API key.
The two M's
Provide the following two Model Settings to start the definition of a model.
- Model Type: Select the type of the Model.
- Model Name: Provide the Name for the Model.
Notes:
The tool will verify that the entries for the Model Name column are unique for the Litmus Edge defined in column Target Litmus Edge IP and notify the user in case the same Model Name was already used.
It is Recommended to click the Compare vs LE Button to check if a Model with the provided Model Type and Name may already be defined on Litmus Edge. If no Model with the selected Model Type and name combination is defined, the row will stay as A for the Action.
Notes:
If none of the Models in the sheet exist, therefore not having a ModelID, the tool will not attempt to read any settings.
If a Model with the selected Model Type and name combination is already defined, the row will change to M for the Action and the settings of the model will be pulled.
Notes:
This doesn't need to be done for every model individually but can instead be done once all desired models have been added to the sheet.
Model Definition Properties
- Static Attributes: Static Attributes allow to manage the metadata for the model. This column combines all of these as a single JSON Object. It is recommended to use the Static Attributes Wizard when setting your specific values for Static Attributes.
- Transformations: Transformations allow to define how to transform the data collected in instances by converting raw JSON data to a desired format by defining the JSON-based schema by the model . This column combines all of these as a single JSON Object. It is recommended to use the Transformations Wizard when setting your specific values for Transformations.
- Dynamic Attributes: Dynamic Attributes allow to manage variable data in the model. This column combines all of these as a single JSON Object. It is recommended to use the Dynamic Attributes Wizard when setting your specific values for Dynamic Attributes.
- Model Schema: Model Schema allows to create a custom data structure for the model. This column combines all of these as a single JSON Object. It is recommended to use the Model Schema Wizard when setting your specific Model Schema.
If all mandatory (*) Model Settings are provided, as well as all not mandatory settings are changed, the Model(s) are ready to be added to Litmus Edge.
Notes:
To add more Models to the sheet, repeat the process described under Add Model(s) to Digital Twin for multiple Litmus Edge for every Model you want to add.
Executing Actions
When all mandatory and not mandatory settings for all Model(s) are set, they are ready to be added.
It is Recommended but not mandatory to verify the configuration first without executing the Action by pressing the Verify Only button.
This will check that all required Model Settings are provided and logically correct. And provide any finding to the user. Example: Below the user not select a UNS Connector despite having enabled UNS in column UNS Enabled.
Important: The tool can not verify if all provided Model settings are factually correct. For example it can not verify that the value of a Static Attribute is correct for what the user want to achieve.
The Model(s) can be added to Litmus Edge by pressing the Verify + Execute button.
The tool will group all the Model(s) based on the Litmus Edge(s) defined in column Target Litmus Edge IP. For each Litmus Edge this will check that all required Model Settings are provided and logically correct. And provide any finding to the user. If no issues have been identified, the tool will verify that the user wants to execute ALL the actions from the Action Column:
- A: Add Model(s)
- M: Modify Model(s)
- D: Delete Model(s)
- I: Ignore Model(s) -> do nothing
To perform all actions, press the Yes button.
The Tool will perform ALL Actions row by row for the Litmus Edge. When finished, a result Summary is shown for each Litmus Edge. Close the Result Summary by pressing the X close button to continue with the next Litmsu Edge.
Once all Litmus Edge have been processed, the tool will ask if the user wants to re-compare all the Model(s) against Litmus Edge. To re-compare, press the Yes button. To not re-compare, press the No button.
If the User selected to press the Yes button from aboves messagebox, the tool will pull all the Model settings from Litmus Edge again including the ModelID and also change the Action to M for each Model with a ModelID or A forModel with no ModelID.
Not Mandatory Model Settings
- Model Description: Enter a short description of the model in the Description field
- UNS Enabled: Select if you want to enable Litmus UNS for the Model.
- UNS Connector: If Litmus UNS Connector(s) are defined for the Litmus Edge, select which Litmus UNS Connector to use to populate the Static Attributes with the Litmus UNS Hierarchy.
Notes:
Selecting an UNS Connector will automatically add the respective Static Attributes associated with the UNS Connector as well as adding them to the Model Schema under the metadata folder by default. Before enabling UNS:
After enabling UNS:
Troubleshooting
The Tool will perform several checks throughout the proces of defining the Model settings. If they do not pass successfully, the user will be notified. The checks include:
- Model Name uniqueness on a Litmus Edge level.
- The tool checks if a Model Name already exist for a specific Litmus Edge in the Tool.
- The user is shown a message box as notification.
- The character(s) are highlighted in red and also shown in a note.
- See Allowed and not allowed Ascii Characters for Names and Descriptions for a full list for both Names and Descriptions.
- Correct JSON formating for Static Attributes, Trasnformations, Dynamic Attributes and Model Schema.
- Example for an invalid JSON formatting of the Static Attributes
- While it is possible to not define entries for the columns Static Attributes, Trasnformations, Dynamic Attributes and Model Schema, the tool verifieds if any of these columns are empty. As this will cause Instances of this model to not return data or not return expected data.
- While it is possible to leave some Values for Static Attributes and Dynamic Attributes empty, the tool checks for such empty values. As this will cause Instances of this model to not return data or not return expected data. Example: No SchemaID defined for Dynamic Attribute.
