Documentation Center

  • Trials
  • Product Updates

Generate Custom Block Libraries from Simscape Component Files

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.

Organizing Your Simscape Files

Simscape files must be saved in package directories. For more information on package directories, see Packages Create Namespaces 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 and will have three corresponding sublibraries. For information on building custom block libraries, see Converting Your Simscape Files.

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.

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.

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 Simulink® model file called SimscapeCustomBlocks_lib 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.

When to Rebuild the Custom Library

You need to rebuild the custom Simscape libraries:

  • Whenever you modify the source files.

  • For use on each platform. Textual component files are platform-independent, but Simscape blocks are not. If you (or your customers) run MATLAB on multiple platforms, generate a separate version of custom block libraries for each platform by running the ssc_build or ssc_mirror command on this platform.

  • For use with each new version of Simscape software. Every time you or your customers upgrade to a new release, you or they have to rebuild the custom block libraries. For information on how to protect your proprietary source code when sharing the Simscape files with customers, see Using Source Protection for Simscape Files.

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

OptionUsageDescriptionDefaultFor Top-Level Package
NamelibInfo.Name = namename will be used as the name of the sublibrary (name of the Simulink subsystem corresponding to the sublibrary) Package nameIgnored
AnnotationlibInfo.Annotation = annotationannotation 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 libraryUsed in annotation for top-level library
ShowIconlibInfo.ShowIcon = falseIf 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. trueIgnored
ShowNamelibInfo.ShowName = trueAllows 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.falseIgnored
HiddenlibInfo.Hidden = trueAllows 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.falseIgnored

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.

Create a Custom Block Library

This example illustrates how you can convert a package of Simscape component files into a custom block library, containing sublibraries with customized names and appearance. It summarizes the techniques described in Organizing Your Simscape Files, Converting Your Simscape Files, and Customizing the Library Name and Appearance.

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:

Was this topic helpful?