Real-Time Workshop® Embedded Coder™

Optimizing Your Model with Configuration Wizard Blocks and Scripts

Overview

The Real-Time Workshop Embedded Coder software provides a library of Configuration Wizard blocks and scripts to help you configure and optimize code generation from your models quickly and easily.

The library provides a Configuration Wizard block you can customize, and four preset Configuration Wizard blocks.

These are shown in the figure below.

When you add one of the preset Configuration Wizard blocks to your model and double-click it, a predefined M-file script executes and configures all parameters of the model's active configuration set without manual intervention. The preset blocks configure the options optimally for one of the following cases:

• Fixed-point code generation with the ERT target

• Floating-point code generation with the ERT target

• Fixed/floating-point code generation with TLC debugging options enabled, with the GRT target.

• Fixed/floating-point code generation with the GRT target

The Custom block is associated with an example M-file script that you can adapt to your requirements.

You can also set up the Configuration Wizard blocks to invoke the build process after configuring the model.

Back to Top

Configuration Wizards vs. Auto-Configuring Targets

Configuration Wizard scripts and auto-configuring targets offer two different approaches to automatic model configuration. You need to consider issues of complexity and the needs of your end users when choosing one or the other approach.

Auto-configuring targets (described in Auto-Configuring Models for Code Generation and Generating Efficient Code with Optimized ERT Targets) execute a back end configuration function (hook file) during the code generation process. The auto-configuration function in effect bypasses the options set in the model's configuration set, which are saved and restored transparently across the build process.

Configuration Wizards, on the other hand, execute a configuration script independently from the code generation process. The Configuration Wizard script actually changes the model's active configuration set. These changes are then visible in the GUI and can be saved with the model.

It is generally simpler to create a custom Configuration Wizard script than to create a custom auto-configuring target. Creating a Configuration Wizard script, in many cases, requires only simple modifications to an existing template. Creating a custom auto-configuring target, on the other hand, requires some knowledge of the internals of the build process.

Back to Top

Adding a Configuration Wizard Block to Your Model

This section describes how to add one of the preset Configuration Wizard blocks to a model.

The Configuration Wizard blocks are available in the Real-Time Workshop Embedded Coder block library. To use a Configuration Wizard block:

1. Open the model that you want to configure.

2. Open the Real-Time Workshop Embedded Coder library by typing the command rtweclib.

3. The top level of the library is shown below.

   

4. Double-click the Configuration Wizards icon. The Configuration Wizards sublibrary opens, as shown below.

   

5. Select the Configuration Wizard block you want to use and drag and drop it into your model. In the figure below, the ERT (optimized for fixed-point) Configuration Wizard block has been added to the model.

   

6. You can set up the Configuration Wizard block to invoke the build process after executing its configuration script. If you do not want to use this feature, skip to the next step.

   If you want the Configuration Wizard block to invoke the build process, right-click on the Configuration Wizard block in your model, and select Mask Parameters... from the context menu. Then, select the Invoke build process after configuration option, as shown below.

   

7. Click Apply, and close the Mask Parameters dialog box.

   Note    You should not change the Configure the model for option, unless you want to create a custom block and script. In that case, see Creating a Custom Configuration Wizard Block.

8. Save the model.

9. You can now use the Configuration Wizard block to configure the model, as described in the next section.

Back to Top

Using Configuration Wizard Blocks

Once you have added a Configuration Wizard block to your model, just double-click the block. The script associated with the block automatically sets all parameters of the active configuration set that are relevant to code generation (including selection of the appropriate target). You can verify that the options have changed by opening the Configuration Parameters dialog box and examining the settings.

If the Invoke build process after configuration option for the block was selected, the script also initiates the code generation and build process.

Note   You can add more than one Configuration Wizard block to your model. This provides a quick way to switch between configurations.

Back to Top

Creating a Custom Configuration Wizard Block

The Custom Configuration Wizard block is shipped with an associated M-file script, rtwsampleconfig.m. The script is located in the directory matlabroot/toolbox/rtw/rtw.

Both the block and the script are intended to provide a starting point for customization. This section describes:

• How to create a custom Configuration Wizard block linked to a custom script.

• Operation of the example script, and programming conventions and requirements for a customized script.

• How to run a configuration script from the MATLAB command line (without a block).

Setting Up a Configuration Wizard Block

This section describes how to set up a custom Configuration Wizard block and link it to a script. If you want to use the block in more than one mode, it is advisable to create a Simulink library to contain the block.

To begin, make a copy of the example script for later customization:

1. Create a directory to store your custom script. This directory should not be anywhere inside the MATLAB directory structure (that is, it should not be under matlabroot).

   The discussion below refers to this directory as /my_wizards.

2. Add the directory to the MATLAB path. Save the path for future sessions.

3. Copy the example script (matlabroot/toolbox/rtw/rtw/rtwsampleconfig.m) to the /my_wizards directory you created in the previous steps. Then, rename the script as desired. The discussion below uses the name my_configscript.m.

4. Open the example script into the MATLAB editor. Scroll to the end of the file and enter the following line of code:

   disp('Custom Configuration Wizard Script completed.');

   This statement is used later as a test to verify that your custom block has executed the script.

5. Save your script and close the MATLAB editor.

The next step is to create a Simulink library and add a custom block to it. Do this as follows:

1. Open the Real-Time Workshop Embedded Coder library and the Configuration Wizards sublibrary, as described in Adding a Configuration Wizard Block to Your Model.

2. Select New Library from the File menu of the Configuration Wizards sublibrary window. An empty library window opens.

3. Select the Custom M-file block from the Configuration Wizards sublibrary and drag and drop it into the empty library window.

4. To distinguish your custom block from the original, edit the Custom M-file label under the block as desired.

5. Select Save as from the File menu of the new library window; save the library to the /my_wizards directory, under your library name of choice. In the figure below, the library has been saved as my_button, and the block has been labeled my_wizard M-file.

   

The next step is to link the custom block to the custom script:

1. Right-click on the block in your model, and select Mask Parameters from the context menu. Notice that the Configure the model for menu set to Custom. When Custom is selected, the Configuration function edit field is enabled, so you can enter the name of a custom script.

2. Enter the name of your custom script into the Configuration function field. (Do not enter the .m filename extension, which is implicit.) In the figure below, the script name my_configscript has been entered into the Configuration function field. This establishes the linkage between the block and script.

   

3. Note that by default, the Invoke build process after configuration option is deselected. You can change the default for your custom block by selecting this option. For now, leave this option deselected.

4. Click Apply and close the Mask Parameters dialog box.

5. Save the library.

6. Close the Real-Time Workshop Embedded Coder library and the Configuration Wizards sublibrary. Leave your custom library open for use in the next step.

Now, test your block and script in a model. Do this as follows:

1. Open the vdp demo model by typing the command:

   vdp

2. Open the Configuration Parameters dialog box and view the Real-Time Workshop options by clicking on the Real-Time Workshop entry in the list in the left pane of the dialog box.

3. Observe that the vdp demo is configured, by default, for the GRT target. Close the Configuration Parameters dialog box.

4. Select your custom block from your custom library. Drag and drop the block into the vdp model.

5. In the vdp model, double-click your custom block.

6. In the MATLAB window, you should see the test message you previously added to your script:

   Custom Configuration Wizard Script completed.

   This indicates that the custom block successfully executed the script.

7. Reopen the Configuration Parameters dialog box and view the Real-Time Workshop pane again. You should now see that the model is configured for the ERT target.

Before applying further edits to your custom script, proceed to the next section to learn about the operation and conventions of Configuration Wizard scripts.

Creating a Configuration Wizard Script

You should create your custom Configuration Wizard script by copying and modifying the example script, rtwsampleconfig.m. This section provides guidelines for modification.

The Configuration Function.   The example script implements a single function without a return value. The function takes a single argument cs:

function rtwsampleconfig(cs)

The argument cs is a handle to a proprietary object that contains information about the model's active configuration set. The Simulink software obtains this handle and passes it in to the configuration function when the user double-clicks a Configuration Wizard block.

Your custom script should conform to this prototype. Your code should use cs as a "black box" object that transmits information to and from the active configuration set, using the accessor functions described below.

Accessing Configuration Set Options.   To set options or obtain option values, use the Simulink set_param and get_param functions (if you are unfamiliar with these functions, see the Simulink Reference document).

Option names are passed in to set_param and get_param as strings specifying an internal option name. The internal option name is not always the same as the corresponding option label on the GUI (for example, the Configuration Parameters dialog box). The example configuration accompanies each set_param and get_param call with a comment that correlates internal option names to GUI option labels. For example:

set_param(cs,'LifeSpan','1'); % Application lifespan (days)

To obtain the current setting of an option in the active configuration set, call get_param. Pass in the cs object as the first argument, followed by the internal option name. For example, the following code excerpt tests the setting of the Create code generation report option:

if strcmp(get_param(cs, 'GenerateReport'), 'on')
    ...

To set an option in the active configuration set, call set_param. Pass in the cs object as the first argument, followed by one or more parameter/value pairs that specify the internal option name and its value. For example, the following code excerpt turns off the Support absolute time option:

set_param(cs,'SupportAbsoluteTime','off');

Selecting a Target.   A Configuration Wizard script must select a target configuration. The example script uses the ERT target as a default. The script first stores string variables that correspond to the required System target file, Template makefile, and Make command settings:

stf = 'ert.tlc';
tmf = 'ert_default_tmf';
mc  = 'make_rtw';

The system target file is selected by passing the cs object and the stf string to the switchTarget function:

switchTarget(cs,stf,[]);

The template makefile and make command options are set by set_param calls:

set_param(cs,'TemplateMakefile',tmf);
set_param(cs,'MakeCommand',mc);

To select a target, your custom script needs only to set up the string variables stf, tmf, and mc and pass them to the appropriate calls, as above.

Obtaining Target and Configuration Set Information.   The following utility functions and properties are provided so that your code can obtain information about the current target and configuration set, with the cs object:

• isValidParam(cs, 'option'): The option argument is an internal option name. isValidParam returns true if option is a valid option in the context of the active configuration set.

• getPropEnabled(cs, 'option'): The option argument is an internal option name. Returns true if this option is enabled (that is, writable).

• IsERTTarget property: Your code can detect whether or not the currently selected target is derived from the ERT target is selected by checking the IsERTTarget property, as follows:

    isERT = strcmp(get_param(cs,'IsERTTarget'),'on');

This information can be used to determine whether or not the script should configure ERT-specific options, for example:

if isERT
  set_param(cs,'ZeroExternalMemoryAtStartup','off'); 
  set_param(cs,'ZeroInternalMemoryAtStartup','off'); 
  set_param(cs,'InitFltsAndDblsToZero','off');
  set_param(cs,'InlinedParameterPlacement',... 
                 'NonHierarchical');
     set_param(cs,'NoFixptDivByZeroProtection','on')
end

Invoking a Configuration Wizard Script from the MATLAB Command Prompt

Like any other M-file, Configuration Wizard scripts can be run from the MATLAB command prompt. (The Configuration Wizard blocks are provided as a graphical convenience, but are not essential.)

Before invoking the script, you must open a model and instantiate a cs object to pass in as an argument to the script. After running the script, you can invoke the build process with the rtwbuild command. The following example opens, configures, and builds a model.

open my_model;
cs = getActiveConfigSet ('my_model');
rtwsampleconfig(cs);
rtwbuild('my_model');

Back to Top

Custom File Processing

Replacement of STF_rtw_info_hook Mechanism