YAKINDU Bundles – Bundle Simulink models with their associated documents Copy link to clipboard
As already mentioned above, working with various models and documents and different versions of them is usual in system controls engineering projects. 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:
- The state of the model(s) and associated documents fit together and match a well known state of completeness.
- Every person that works with the set of models and documents has a clear understanding about the requirements that are implemented, the remaining tasks, or known bugs.
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.
Create and export a bundle manually Copy link to clipboard
To create a bundle:
- Click on the ‘Export bundle’ button on the top right corner of the configuration editor.
Export a bundle
- A file selection dialog opens where you can give a name to the bundle and save it. The bundle file extension should be .ybundle.
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
Model IP protection Copy link to clipboard
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 itemis Model Viewer.
With itemis Model Viewer you are able to secure your models within your bundles and ensure that they can only be read by itemis 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
Include libraries when exporting a bundle Copy link to clipboard
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
Create and export a bundle with the command line interface Copy link to clipboard
With the command line interface CLI you can create bundles without opening itemis Model Viewer. This might be useful 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:
- create and export a ybundle based on a documentation configuration file (.yconf)
- encrypt the created bundle
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 -en [path_to_documentation_config] -t [path_to_target_bundle].ybundle
The newly created bundle needs the extension ‘.ybundle’.
Navigate between model and documentation Copy link to clipboard
itemis 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.
- Go to the main menu and select File > Open File.... A file selection dialog opens and you can select the bundle file ( .ybundle). Alternatively, you can double-click the bundle file in your local file folder and it will open directly in the itemis Model Viewer. The bundle opens in a new tab in the editor area.
- Activate the bundle by clicking on the ‘Activate’ link in the top left corner of the bundle view. The color of the status bar changes to green indicating that the current bundle is active
Activate a bundle
Navigate from model to documentation Copy link to clipboard
- Open the model included in your bundle by double clicking it in the bundle view. All model elements having a link are marked with a document icon:
- Hover the icon to see a preview of the documentation that is related to the model element.
Documentation on the model
- To read the whole documentation, click on the tooltip and the document will open at the position of the link in the itemis Model Viewer.
Navigate from model to documentation
Navigate from documentation to model Copy link to clipboard
You can also navigate from the documentation ( .pdf) to the model ( .mdl).
- Go to the bundle and double-click the PDF file. This will open in a new tab in the itemis Model Viewer.
- Click on a link (links are blue and underlined) in the document and the model will open in a new tab.
- The model element corresponding to the link is highlighted by having a red border around it.
Navigate from the documentation to the model
Activate OS support for links Copy link to clipboard
In general it is possible to activate link handling support for modelviewer links from each type of file on the operating system.
- Click “Window” - "Preferences"
- Go to page “General” - "Link Handling"
- Check the checkbox for ylink link handling
- Click "Apply and Close"
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 itemis Model Viewer opens.