Twin Activate Libraries

In Twin Activate, libraries are self-contained repositories that essentially provide the application with new blocks.

Beyond just blocks, a library also provides Compose OML functions that you can use within your scripts.

Library Structure

This page describes the structure of a typical library.

A library in Twin Activate can be described by the following structure:

Figure 1. Representation of a Typical Library in Twin Activate

key: The library is identified by its key. The key is generated automatically by Twin Activate in the file _key. This file is updated every time the library is edited after a release; a new version of the library is created. The first line of the _key file defines the current version ID, the other lines define the IDs of the old versions. This file should not be manually edited, as this could alter the library.
loader: The blocks of the library are loaded into Twin Activate through the loader.oml file. This file is automatically generated and must not be edited.
libinit: The library can add to the Twin Activate environment palettes, menus, and functions. You can edit the libinit.oml file to perform such actions.
palette: The palettes of the library can be any SCM file loaded as a palette in the libinit file. The palette browser shows only the blocks. The links and annotations are discarded.
block : A block in Twin Activate is defined by the interface file (SCB) and the simulation functions. The block interface files can be organized hierarchically under the condition that the folder that contains the SCB file must have the same name as the SCB. The hierarchical path defines the reference path of the block, relative to the library's top level. The simulation functions of the block must be inside the _sim folder of the library. The relative paths of the simulation functions must be equivalent to the ones defined in the SCB file.
icons: Icons of the blocks should be defined inside the _icons folder of the library.
documentation: The block documentation is generated inside _doc folder.

The library structure is summarized in the following image:

Figure 2. Description of a Library Folder in Twin Activate

Block Structure

This page describes the structure of a block.

In a Twin Activate library, a block is defined by several files of the following types:

SCB: Describes the graphics part of the block. It contains the parameters definition and the evaluation part of the block. This file is generated by selecting a block and using the menu File > Save Selected. The block can also be a masked super block, or an atom block. To create an atom block, use the menu Tools > Block Builder.
OML: Generated from the SCB. It should not be edited, and is used during the evaluation phase of the simulation.
XML: Used for documentation. The skeleton of the file is generated automatically from the SCB file. This file should be completed by the block creator.
HTML: Generated from the XML file. It is under the _doc folder.

The image below illustrates the structure of the constant block in the Twin Activate library.

A block can have one or many simulation functions. They are considered to be C entry point functions. They are defined under the _sim folder of the library. A library creator can decide to either ship the C code or not, but it is mandatory to ship the static and the shared libraries. If a simulation function depends on a third party library, the shared and static library of that third party must be delivered under the _bin folder of the library.

Figure 4. Constant Block: View of the Simulation Folder Content

Palette

The palette is the way to expose the blocks of a library.

The palette is very similar to a model. It can be edited by Twin Activate as any other model. A non-masked super block in a palette is used to create hierarchy in the palette browser. A masked super block is seen in the palette browser as a block. Since the block diagram editor manipulates palettes as models, the extension of the palette file is SCM.

A library can have several palettes, and in contrast, some libraries might not need to expose any block, in which case the library does not have any palette.

Since the palettes are the interface of the library, you can choose the blocks to be exposed. Some of the blocks that are considered support blocks might not be placed into a palette. However, you can still access such blocks through the menu File > Libraries > Insert Block From Library.

A palette does not need to be associated with any library. You can create your own palette based on the existing blocks. You can, for example, create your favorite palette to host your most used blocks. In that case, you create a model and use the menu File > Libraries > Save as Palette. This palette is then loaded and exposed under the Personal page of the Library Browser.

When a library is uninsulated, files are removed. The palettes loaded by that library should be removed from the palette browser. To remove personal palettes, you can use the menu File > Libraries > Remove Palette.

Create a Library

An overview of the two methods to create or edit a library.

Twin Activate offers two ways to create and edit a library:

Library Manager: Provides a GUI to help you create and edit your libraries.
OML functions: Provides OML functions that let you create and edit your libraries.

Note: The Library Manager provides an easy but limited way to edit the library. For advanced users, the use of OML functions is recommended.

Library Manager

An overview of how to create or edit a library using the Library Manager.

The Library Manager lets you:

Create a new library: You must define the name and the path of the library. The library is installed after creation.
Figure 5. Create Library
Edit an installed library: You can select one of the installed libraries.
Edit a library on disk: You can select the library a folder on your disk. The library will be installed.

After the library is installed, the Library Manager lets you add or replace blocks in the library. You can then select a masked super block and click Add/Replace.

The block is added to the library, the loader is updated, and the palette is regenerated.

You can also remove blocks from the library using the Library Manager.

The Library Manager lets you lock your library. When the library is locked, it is ready to be released.

To lock the library, click Uninstall, and then click Lock. When the library is locked, you cannot add or remove any block from it.

The Library Manager lets you edit a locked library with the Unlock button. This feature creates a new version of the library, a new key is created in the _key file, the blocks are updated, and the palette is regenerated. It references the blocks with the new key.

Figure 9. Example of Library Keys

4364825b-cfc2-48b9-5e236bee2e56
79b2cae8-905e-4851-acfa-77fe58b4ddb3

Figure 10. Library Keys Used in a Block

<block name="actuator" type="block">
    <template name="4364825b-cfc2-48b9-5e236bee2e56/actuator"/>

The models and the scripts that use the old version of the library will still work. You must make sure your library is backward compatible. You cannot remove any block from the library, change the hierarchical organization of the blocks, or remove any exposed OML function. For a given block, you cannot remove any parameter.

OML Functions

An overview of how to create or edit a library using OML functions.

Twin Activate provides OML functions to manipulate the libraries.

Create Library

This function creates a skeleton of the library on the disk. It generates a new key and assigns that key to the library. The arguments of that function are the name of the library and the path where the library must be created.

vssCreateEmptyLibrary(’mylib’,’x:/Libraries’);

Refresh Library

After populating the library with the blocks, the refresh function generates the OML functions used by the evaluator, the XML files used to generate the documentation, and the libraries used by the simulator. This function generates also the loader of the library. The argument of that function is the path of the library.

vssRefreshLibrary(’x:/Libraries/mylib’);

The library is now ready to be used.

Note: Every time you add a block to your library, you must refresh the library and execute the loader so that the new block is taken into account.

Generate Palette

There are several methods to create a palette:

Generate the palette automatically from the library: The palette contains all the blocks of the library. You can then edit the palette to remove or add blocks. The palettes of a library must contain only blocks from the library or from the System (Activate) library. In this case, you can use the following function:
```
vssGeneratePalette(’x:/Libraries/mylib’);
```
Generate the palette manually: You can use the Block Diagram Editor ,because a palette is, in essence, a model. Open a new model, add new blocks to the model through the menu File > Libraries > Insert Block From Library and then save the model in the library.

Add Palette

After the palettes are generated, you must edit the libinit.oml file by adding the AddPalette function, which adds the palettes of the library to the toolbox page.

vssAddPalette([libPath, ’/mylib.scm’]);

where libPath is the path of the library.

Note: To make the library movable, use the variable libPath defined in libinit.oml instead of hard-coding the path of the library.

Install Library

This function installs the library in the Twin Activate environment. It does not change the location of the library on the disk.

vssInstallLibrary(’x:/Libraries/mylib’);

The library is now installed, the palettes are added to the palette browser, and you can start using the library.

Uninstall Library

You can uninstall the library. The palettes that come with the library are removed from the Library Browser. After a library is uninstalled, you cannot run any model that uses blocks from that library.

vssUninstallLibrary(’x:/Libraries/mylib’);

Document Library

You can start documenting your blocks. You must edit the XML file corresponding to each block. The fields that are already filled must not be changed. You can give, for example, more information about the block in the description section. After the blocks are documented, you can use the following function to update the HTML pages.

vssGenerateDocumentation(’x:/Libraries/mylib’);

Lock Library

The library is now ready to be delivered. You must lock the library before releasing. After the library is locked, you cannot add any block or function to the library. The library is now read-only.

vssLockLibrary(’x:/Libraries/mylib’);

Unlock Library

As a library creator, you can still edit your library after it has been locked. In this case, you must first unlock the library. A new key is generated indicating that this is a new version of the library. The new version of the library must be backward compatible. You cannot remove any block from the library, change the hierarchical level of the blocks, or remove any exposed OML function. For a given block, you cannot remove any parameter.

vssUnlockLibrary(’x:/Libraries/mylib’);