A systems control model often does not exist on its own. E.g. the model developer creates the model and writes a documentation about its behavior. Other users need that documentation when using the models to understand the underlying concepts, parameters, etc. The YAKINDU Model Viewer addresses these tasks with two features:
Systems control engineering is a complex field and control engineering projects often require multiple models and multiple documents. Often these artifacts appear as single files in the
file system, on external devices or within a version control system. Under such circumstances it is a challenge to keep completeness and consistency (fit versions etc.) for the system control engineers, developers or testers within the core team. The problem worsens if third parties that provide engineering services are involved.
The core task is to ensure that:
But in the real world engineering departments things often look different. Due to time pressure issues emerge such as: unclear responsibility, lack of completeness, and lack of consistency. Some of them simply emerge because the version of the model does not fit the version of the document.
YAKINDU Model Viewer addresses this task with YAKINDU bundles. You can store Simulink models, libraries and the associated documents of all kinds in a bundle. This YAKINDU bundle ensures that everyone involved in the project processes the same status of the overall project, consisting of different files, i.e. models and documentation or libraries. This reduces the susceptibility to errors due to mismatched artifacts and work statuses and increases completeness and consistency. The creation of a bundle is simple and is integrated directly into the YAKINDU Model Viewer.
YAKINDU bundles that represent a certain status of an engineering project can be stored in parallel for versioning.
The creation of YAKINDU bundles can be automated using a shell command. If a project requires that the status of the model is regularly distributed together with the documents involved, this process can be automated e.g. within a continuous build. This reduces manual efforts.
The recipient of such a bundle is able to start working straight away by simply opening the YAKINDU bundle: then the system controls engineer or tester can look at the models, track signals or look at the associated explanations thanks to the integrated documentation links.
The simplification of teamwork - collaboration - using YAKINDU bundles is remarkable. A bundle is assembled and distributed to all team members, engineers, developers and testers involved. If someone has a specific question about a model element, this team member is able to copy the link to the specific block and exchange with a teammate. The teammate clicks on the hyperlink and immediately opens YAKINDU Model Viewer on this block: now both can be sure to talk about the same element without having to search for it beforehand. Due to the feature IP protection models can be viewed but not copied.
YAKINDU Model Viewer supports links between model elements and documentation documents e.g. PDF files, so the teammate may consult the documentation to the certain Simulink block simply by following the hyperlink.
The structure of a YAKINDU bundle is arbitrary. It is independent from the file system structure. You can create folders and folders within folders and place models or documents within these. By doing this, systems control engineers and developers create a structured view on models and documentation artifacts that fit the requirements of the certain project.
To create links between a specific model and a documentation in YAKINDU Model Viewer, the following steps are necessary:
These steps are described in more detailed in the following sections.
When working in projects you often have to deal with different versions of models and documents which are continuously developed. Different versions often have similar names. When creating and using links between them, the YAKINDU Model Viewer needs to know which versions you work with. This scope can be defined with a so called configuration that you need to create in a first step. The configuration is a kind of container where you can add all files for which you want to create links.
To create a configuration:
Tips for saving the configuration:
Save the configuration at the same or at least near the location of your model and the documentation files.
Creating and saving a configuration
Configuration editor
To add elements, e.g. the models and the documentation files, to the configuration:
icon either on the top left of the tab or in the middle of the editor.
Once you add an element in the configuration list, you can see two columns: the first one displays the name of the entry and the second one shows you the location in which the entry is located in your file system.
Configuration editor with two elements
Tip: Add links to elements that doesn’t exist yet:
Maybe you want to add links to file types that are not editable (e.g. PDF files) or do not exist at the moment because they are generated automatically later. We have a special feature for you that makes that possible:
icon in the configuration editor, and add the name of your PDF document plus the file extension. A red exclamation mark is displayed next to it to show that the file does not exist yet.
Menu icons and placeholder area
To get a better overview of your configuration list, you can organize the elements in a tree structure similar to a file system. With YAKINDU Model Viewer, you can create folders to group the elements into a clear structure.
To create a folder:
in the menu bar. A new folder with the name folder is created and placed in the configuration list. The new created folder is in focus and selected, so that you can directly give it a new name.
New folder in the configuration editor
YAKINDU Model Viewer supports only unique names for each element in the tree. When you enter a file or folder name which already exists, an exclamation mark is displayed next to it, indicating that there is duplicate name.
To rename a folder you first have to select it. Then you can do one of the following:
icon in the menu bar, or
Give a new name to the folder and press [ENTER]. The folder is now renamed.
A folder can contain single resources e.g. .mdl files, Word files etc. or other folders. There are two ways you can add an element into a folder:
1. Select a folder and click the the
icon in the menu bar. Then select a file from the file system and it will be added automatically in the selected folder.
or
2. Drag & drop already existing elements in the configuration editor list into a folder. The targeted folder is highlighted in blue and you can add the element in it.
Drag and drop an element to a folder
Afterwards, the targeted folder is opened and the element that you moved is selected.
Element is added to a folder
To change the order of the elements in the tree, navigate to the element and drag it to a new location. A blue line indicates where the element can be placed.
Rearrange the configuration elements by drag & drop
Right-click on an entry displays an context menu. The menu items ‚Move up/down’ and ‚Move to top/bottom’ accompanied by the related shortcuts, allow you to move the elements accordingly.
Context menu on right-click
To edit a location of an entry, right click on it and select the menu item ‚Edit location’. The file dialog opens where you can choose a new location.
When you don’t need certain files or folders in your configuration, you can simply delete them from the editor.
To delete an element from the configuration list:
button at the top of the editor area or press [DEL], and the selected element will be deleted from the configuration list.
button or [DEL].
Note: Deleting a folder, will also delete the contained elements in it!
Further context menu items allow you to perform actions related to the selected item:
These can also be performed by the accompanied shortcuts or they exist already in the menu bar.
When you have added and arranged all the necessary files, you have successfully created the configuration.
When setting up a new configuration and adding a documentation file without links, a exclamation mark is shown next to the PDF file.
Configuration including a documentation without links
So what we need to do now is creating a link between a model and a documentation:
Copy link of model element to the clipboard
Tip: Don’t worry if you forgot the activate your configuration. A pop-up notification appears when clicking ‚Copy link to clipboard’ which allows you to ‚Activate’ an already opened configuration or to create a new one if none exists yet.
Open and activate an existing configuration
Add link to documentation file
Active configuration with files and links
When you have added all necessary elements to the configuration and the links between the document and the model, you can provide the files and the link information to others by exporting a bundle – a kind of archive. This enables other people to use the added links and navigate quickly between model elements and documentation and vice versa.
However, whenever Intellectual Property Rights (IPRs) are violated, it affects more than just revenues. Therefore, it is essential to ensure IP-protection for your models.
When working with various models, it is important to define that the models you create can only be opened and read by YAKINDU Model Viewer.
With YAKINDU Model Viewer you are able to secure your models within your bundles and ensure that they can only be read by YAKINDU Model Viewer.
The checkbox ‚Encrypt models’ is active on the top of the configuration bar. This means that the models in the exported bundle will be IP protected. To deactivate IP protection, just uncheck the checkbox.
Enable encryption for models
The models that you have added to the configuration can reference blocks from libraries. When you export a bundle, you have to decide if these libraries have to be included in the bundle or not. To export a bundle with all the necessary libraries, activate the checkbox ‚Include libraries’ in the configuration bar. This will allow the user of the bundle to navigate to all blocks without any problem.
Include libraries in the bundle export
To create a bundle:
Export a bundle
After saving the bundle, a dialog window opens and asks you if you want to open it. When selecting ‚yes’, the new bundle opens in a new tab in the editor. You can see a list with the elements that exist in the bundle.
Bundle including a model file, the documentation and link information
YAKINDU Model Viewer supports the navigation between a model and documentation files in both directions via the created links.
In both cases, the easiest way is to open the bundle file ( .ybundle) because it includes all relevant files for you.
Activate a bundle
Documentation on the model
Navigate from model to documentation
You can also navigate from the documentation ( .pdf) to the model ( .mdl).
Navigate from the documentation to the model
In general it is possible to activate link handling support for modelviewer links from each type of file on the operating system.
Activate OS support for following links
Now you can place a link in a word document or a html file that fits to the scheme ‚ylink://’ and points to a model element. If you click on it YAKINDU Modelviewer opens.
With the command line interface CLI you can create bundles without opening YAKINDU Model Viewer. This might be usefull for integrating the bundle creation in your build infrastructure.
To use this command line interface you open the OS shell on the folder „YMV/Model_Viewer/CLI”. Now you start the tool with the following command:
java -jar ymv-cli.jar
With the command line interface you can perform 2 main tasks:
To create a bundle you need to put all necessary files e.g. the model, the documentation and the documentation configuration file in a directory.
With the following command you can bundle these files to a documentation bundle (.ybundle):
java -jar ymv-cli.jar -e -c [path_to_documentation_config] -t [path_to_target_bundle].ybundle
The newly created bundle needs the extension ‚.ybundle’.
