Learn more about Simscape

Adding Custom Block Libraries Generated from Simscape Component Files

On this page…
Workflow Overview Organizing Your Simscape Files Using Source Protection for Simscape Files Converting Your Simscape Files Customizing the Library Name and Appearance Customizing the Library Icon Example — Creating and Customizing Block Libraries Specifics of Using Customized Domains

Workflow Overview

After you have created the textual component files, you need to convert them into Simscape blocks to be able to use them in block diagrams. This process involves:

1. Organizing your Simscape files. Simscape files must be saved in package directories. The package hierarchy determines the resulting library structure.

2. Optional source protection. If you want to share your models with customers without disclosing the component or domain source, you can generate Simscape protected files and share those.

3. Building the custom block library. You can use either the regular Simscape source files or Simscape protected files to do this. Each top-level package generates a separate custom Simscape block library.

Once you generate the custom Simscape library, you can open it and drag the customized blocks from it into your models.

Back to Top

Organizing Your Simscape Files

Simscape files must be saved in package directories. For more information on package directories, see Scoping Classes with Packages in the MATLAB Classes and Object-Oriented Programming documentation. The important points are:

• The package directory name must begin with a + character.

• The rest of the package directory name (without the + character) must be a valid MATLAB identifier.

• The package directory's parent directory must be on the MATLAB path.

Each package where you store your Simscape files generates a separate custom block library.

Package directories may be organized into subdirectories, with names also beginning with a + character. After you build a custom block library, each such subdirectory will appear as a sublibrary under the top-level custom library.

For example, you may have a top-level package directory, named +SimscapeCustomBlocks, and it has three subdirectories, Electrical, Hydraulic, and Mechanical, each containing Simscape files. The custom block library generated from this package will be called SimscapeCustomBlocks_lib.mdl and will have three corresponding sublibraries. For information on building custom block libraries, see Converting Your Simscape Files.

Back to Top

Using Source Protection for Simscape Files

If you need to protect your proprietary source code when sharing the Simscape files, use one of the following commands to generate Simscape protected files:

• ssc_protect — Protects individual files and directories. Once you encrypt the files, you can share them without disclosing the component or domain source. Use them, just as you would the Simscape source files, to build custom block libraries with the ssc_build command.

• ssc_mirror — Creates a protected copy of a whole package in a specified directory. Setting a flag lets you also build a custom block library from the protected files and place it in the mirror directory, thus eliminating the need to run the ssc_build command. Use the ssc_mirror command to quickly prepare a whole package for sharing with your customers, without disclosing the component or domain source.

Unlike Simscape source files, which have the extension .ssc, Simscape protected files have the extension .sscp and are not humanly-readable. You can use them, just as the Simscape source files, to build custom block libraries. Protected files have to be organized in package directories, in the same way as the Simscape source files. For information on organizing your files, see Organizing Your Simscape Files. For information on building custom block libraries, see Converting Your Simscape Files.

Back to Top

Converting Your Simscape Files

After you have created the textual component files and organized them in package directories, you need to convert them into Simscape blocks to be able to use them in block diagrams. You do this by running the ssc_build command on the top-level package directory containing your Simscape files. The package may contain either the regular Simscape source files or Simscape protected files.

Note   Before running the ssc_build command for the first time, you have to set up your compiler by running mex -setup. For more information, see Building MEX-Files in the MATLAB External Interfaces documentation.

For example, you may have a top-level package directory, where you store your Simscape files, named +SimscapeCustomBlocks. To generate a custom block library, at the MATLAB command prompt, type:

ssc_build SimscapeCustomBlocks;

Note   The package directory name begins with a leading + character, whereas the argument to ssc_build must omit the + character.

This command generates a file called SimscapeCustomBlocks_lib.mdl in the parent directory of the top-level package (that is, in the same directory that contains your +SimscapeCustomBlocks package). Because this directory is on the MATLAB path, you can open the library by typing its name at the MATLAB command prompt. In our example, type:

SimscapeCustomBlocks_lib 

The model file generated by running the ssc_build command is the custom Simscape library containing all the sublibraries and blocks generated from the Simscape files located in the top- level package. Once you open the custom Simscape library, you can drag the customized blocks from it into your models.

Creating Sublibraries

Package directories may be organized into subdirectories, with names also beginning with a + character. After you run the ssc_build command, each such subdirectory will appear as a sublibrary under the top-level custom library. You can customize the name and appearance of sublibraries by using library configuration files.

Note   When you add or modify component files in package subdirectories, you still run the ssc_build command on the top-level package directory. This updates all the sublibraries.

You may have more than one top-level package directory, that is, more than one package directory located in a directory on the MATLAB path. Each top-level package directory generates a separate top-level custom library.

Back to Top

Customizing the Library Name and Appearance

Package names must be valid MATLAB identifiers. The top-level package always generates a library model with the name package_name_lib.mdl. However, library configuration files let you provide descriptive library names and specify other customizations for sublibraries, generated from subdirectories in the package hierarchy.

A library configuration file must be located in the package directory and named lib.m.

Library configuration files are not required. You can choose to provide lib.m for some subpackages, all subpackages, or for none of the subpackages. If a subpackage does not contain a lib.m file, the sublibrary is built using the default values. The top-level package can also contain a lib.m file. Options such as library name, and other options that do not make sense for a top-level library, are ignored during build. However, having a file with the same name and options in the top-level package provides a uniform mechanism that lets you easily change the library hierarchy.

The following table describes the supported options. The only option that is required in a lib.m file is Name; others are optional.

Option	Usage	Description	Default	For Top-Level Package
Name	libInfo.Name = name	name will be used as the name of the sublibrary (name of the Simulink subsystem corresponding to the sublibrary)	Package name	Ignored
Annotation	libInfo.Annotation = annotation	annotation will be displayed as annotation when you open the sublibrary. It can be any text that you want to display in the sublibrary.	No annotation in the library	Used in annotation for top- level library
ShowIcon	libInfo.ShowIcon = false	If there is no library icon file lib.img, as described in Customizing the Library Icon, this option is ignored. If there is an icon file, you can choose to not use it by setting this option to false.	true	Ignored
ShowName	libInfo.ShowName = true	Allows you to configure whether the sublibrary name is shown in the parent library. If there is no library icon file, then the default library icon contains the library name, and showing it again is redundant. If you are using a library icon file, set showName to true to display the library name below the icon.	false	Ignored
Hidden	libInfo.Hidden = true	Allows you to configure whether the sublibrary is visible in the parent library. Use this option for a sublibrary containing blocks that you do not want to expose, for example, those kept for compatibility reasons.	false	Ignored

Back to Top

Customizing the Library Icon

If a subpackage contains a file named lib.img, where img is one of the supported image file formats (such as jpg , bmp, or png), then that image file is used for the icon representing this sublibrary in the parent library. The icon file (lib.img) and customization file (lib.m) are independent, you can provide one or the other, both, or none.

The following image file formats are supported:

• jpg

• bmp

• png

If there are multiple image files, the formats take precedence in the order listed above. For example, if a subpackage contains both lib.jpg and lib.bmp, lib.jpg is the image that will appear in the parent library.

You can turn off customizing the library icon by setting showIcon to false in the library customization file lib.m. In this case, the default library icon will be used. For more information, see Customizing the Library Name and Appearance.

Back to Top

Example — Creating and Customizing Block Libraries

Consider the following directory structure:

- +MySimscapeLibrary 
|-- +MechanicalElements 
| |-- lib.m 
| |-- lib.jpg 
| |-- inertia.ssc 
| |-- spring.ssc 
|-- +ElectricalElements  
| |-- ...
|-- +HydraulicElements  
| |-- ...

This means that you have a top-level package called +MySimscapeLibrary, which contains three subpackages, +MechanicalElements, +ElectricalElements, and +HydraulicElements. The +MechanicalElements package contains two component files, inertia.ssc and spring.ssc, a library icon file lib.jpg, and the following library configuration file lib.m:

function lib ( libInfo )
libInfo.Name = 'Basic Mechanical Elements';
libInfo.Annotation = sprintf('This library contains basic mechanical elements');
libInfo.ShowName = true;

When you run

ssc_build MySimscapeLibrary;

the top-level package generates a library model called MySimscapeLibrary_lib, as follows:

Notice that the sublibrary generated from the +MechanicalElements package is presented in its parent library with a customized icon and name (Basic Mechanical Elements).

If you double-click the Basic Mechanical Elements sublibrary, it opens as follows:

Back to Top

Specifics of Using Customized Domains

If you define your own physical domains and use them in your custom blocks, several rules apply.

• If the domain file resides in a different package from the components that use it, build the domain package first.

• If you have opened the Library Browser, or a Simulink library or model, before building the package containing the domain, you have to restart MATLAB before you can use the components referencing this domain in your block diagrams.

Otherwise, all the rules for building component libraries apply to domains. Place domain files in package directories and build them using the ssc_build command.

Back to Top

Using Simscape Files in Block Diagrams

Customizing the Block Name and Appearance

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS