Building Custom Block Libraries

Workflow Overview

To generate a custom block library from Simscape™ component files, follow these steps:

Organize your Simscape files. Simscape files must be saved in namespace folders. The namespace hierarchy determines the resulting library structure.
Optionally, provide 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.
Build the custom block library. You can use either the regular Simscape source files or Simscape protected files to do this. Each top-level namespace 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 namespace folders. The important points are:

The namespace folder name must begin with a + character.
The rest of the namespace folder name (without the + character) must be a valid MATLAB^® identifier.
The namespace folder's parent folder must be on the MATLAB path.

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

Namespace folders may be organized into subfolders, with names also beginning with a + character. After you build a custom block library, each such subfolder will appear as a sublibrary under the top-level custom library.

For example, you may have a top-level namespace folder named +SimscapeCustomBlocks, and it has three subfolders, +Electrical, +Hydraulic, and +Mechanical, each containing Simscape files. By default, the custom block library generated from this namespace will be called SimscapeCustomBlocks_lib (you can specify a different name). The library will have three sublibraries with names corresponding to the namespace subfolders (Electrical, Hydraulic, and Mechanical). 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:

sscprotect — Protects individual files and folders. 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 sscbuild command.
sscmirror — Creates a protected copy of a whole namespace in a specified folder. Setting a flag lets you also build a custom block library from the protected files and place it in the mirror folder, thus eliminating the need to run the sscbuild command. Use the sscmirror command to quickly prepare a whole namespace 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 namespace folders, 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 namespace folders, you need to convert them into Simscape blocks to be able to use them in block diagrams. You do this by running the sscbuild command on the top-level namespace folder containing your Simscape files. The namespace may contain either the regular Simscape source files or Simscape protected files.

For example, you may have a top-level namespace folder, where you store your Simscape files, named +SimscapeCustomBlocks. You can generate a custom block library either from the namespace parent folder, or from a folder inside the namespace. From the namespace parent folder, at the MATLAB command prompt, type:

sscbuild SimscapeCustomBlocks;

Note

The namespace folder name begins with a leading + character, whereas the argument to sscbuild must omit the + character.

This command generates a Simulink^® model file called SimscapeCustomBlocks_lib in the parent folder of the top-level namespace (that is, in the same folder that contains your +SimscapeCustomBlocks namespace). Because this folder 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 sscbuild command is the custom Simscape library containing all the sublibraries and blocks generated from the Simscape files located in the top-level namespace. Once you open the custom Simscape library, you can drag the customized blocks from it into your models.

When building a custom library from a namespace, sscbuild lets you specify a different name and location for the library file than the default ones. For more information, see sscbuild.

Creating Sublibraries

Namespace folders may be organized into subfolders, with names also beginning with a + character. After you run the sscbuild command, each such subfolder 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 namespace subfolders, you still run the sscbuild command on the top-level namespace folder. This updates all the sublibraries.

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

Related Examples

Create a Custom Block Library