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:

  • Create hyperlinks between model elements and documentation sections that can be followed in both directions
  • Create bundles of all associated models and documentation documents that belong to a certain project or project state

YAKINDU Bundles – Bundle‌ ‌Simulink‌ ‌models‌ ‌with‌ ‌their‌ ‌associated‌ documents

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:‌

  • 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.

Bundle Simulink models with their associated documents

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:

  • For preparation, you have to create a configuration first.
  • Copy the link of a model element to your clipboard.
  • Paste the link in the documentation file.

These steps are described in more detailed in the following sections.

Creating a configuration

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:

  • Click on File > New yconf in the main menu. A file selection dialog opens.
  • Enter the name of the configuration file with extension .yconf, and save it in the desired folder.

Tips for saving the configuration:
Save the configuration at the same or at least near the location of your model and the documentation files.

Create and save a configuration

Creating and saving a configuration

  • Once you have saved it, the configuration opens in a new YAKINDU Model Viewer editor tab.

Configuration editor

Configuration editor

To add elements, e.g. the models and the documentation files, to the configuration:

  • Click on the icon "add" icon either on the top left of the tab or in the middle of the editor.
  • A file selection dialog opens. Select the elements you want to add.

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

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:

  • Add a so called ‚placeholder element’ to the configuration, by clicking the icon "placeholder" 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.
  • You can now add the links to the editable version of the document, e.g. a Word document. (You don’t need to add this file to the configuration)
  • Transform the Word document to PDF. Ensure that it has the same name as the PDF file. It should also be saved at the same location as the configuration file. (If you want to save it as another location, you can use a relative path as name of the placeholder element, e.g. ‚subfoldername/placeholdername.pdf’)
  • As soon as the PDF file is available, YAKINDU Model Viewer will automatically detect the change, the exclamation mark will disappear and the included links will be available.

Menu icons and placeholder area

Menu icons and placeholder area

Creating folders in the configuration

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:

  • Click on the folder icon icon "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 editor

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:

  • Click once more on it and the name becomes editable.
  • Click on the icon "rename" icon in the menu bar, or
  • Right-click on the folder. A context menu appears and then select the menu item ‚Rename’.

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 "add" icon in the menu bar. Then select a file from the file system and it will be added automatically in the selected folder.
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

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

Element is added to a folder

Edit and arrange the elements in the configuration list

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.

Order by drag & drop

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

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:

  • Select the element by clicking on it.
  • Click on the button at the top of the editor area or press [DEL], and the selected element will be deleted from the configuration list.
  • Right-click on the element and select the context menu item ‚Delete’.
  • To delete multiple elements, press [Ctrl+A] to select them all, use [Ctrl+Left click] to select several element, or use [Shift+Left click] to select a range. Then click on the 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:

  • Open: opens the element in a new tab in the YAKINDU Model Viewer (.mdl or .pdf file) or in the original tool (Word file).
  • Add file: adds a new element in the configuration list.
  • Add folder: adds a new folder in the configuration list.
  • Add placeholder: adds a placeholder in the configuration list.
  • Open folder in file manager: open the folder in the file system that contains the selected element.
  • Expand/collapse folder: expands or collapses a closed or opened folder.
  • Rename: renames a folder in the configuration list.

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 with no links connected

Configuration including a documentation without links

So what we need to do now is creating a link between a model and a documentation:

  • Activate the configuration for which you want to create links by clicking the ‚Activate’ button at the top of the configuration editor.
  • Open the model from the configuration, e.g. by double-clicking the element in the configuration editor.
  • Right click on a model element and select the ‚Copy link to clipboard(L)’ menu item. Now the link information is stored in your clipboard.

Copy model element to the clipboard

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

Open and activate an existing configuration

  • Now open the documentation file to which you want to add the link. The file must be an editable text format, e.g. a Word document. (See the section about placeholders if your links should be available in PDF files)
  • Select the text part which should be replaced by the link and press [Ctrl+V]. The link is added to the selected term.
  • Save the file.

Add link to documentation file

Add link to documentation file

  • Create a new PDF document with the same name as the documentation file.

Active configuration with files and links

Active configuration with files and links

Provide link information to others

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.

Model IP protection

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

Enable encryption for models

Include libraries when exporting a bundle

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

Include libraries in the bundle export

Create and export a bundle

To create a bundle:

  • Click on the ‚Export bundle’ button on the top right corner of the configuration editor.

Export a bundle

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 view

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.

  • 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 YAKINDU 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

Activate a bundle

  • 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

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 YAKINDU Model Viewer.

Navigate from the model to the documentation

Navigate from model to documentation

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 YAKINDU 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

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.

  • Click „Window” - "Preferences"
  • Go to page „General” - "Link Handling"
  • Check the checkbox for ylink link handling
  • Click "Apply and Close"

Activate link handling on the preference page

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.

The command line interface

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

command line interface

With the command line interface you can perform 2 main tasks:

  • create a ybundle based on a documentation configuration file (.yconf)
  • send a link to a defined receiver

Create a 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 [path_to_documentation_config] -t [path_to_target_bundle].ybundle 

The newly created bundle needs the extension ‚.ybundle’.