Real-Time Workshop® Embedded Coder™

Creating Simulink and mpt Data Objects

Overview

The Real-Time Workshop Embedded Coder software provides the mpt (module packaging tool) data object, which contains all the properties of Simulink data objects plus properties that provide additional control over module packaging. For a comparison of the properties of Simulink and mpt data objects, see Comparing Simulink and mpt Data Objects.

There are different ways of creating Simulink and mpt data objects for a data dictionary.

• One-by-one, either using the MATLAB command line or using the Model Explorer Add menu and selecting Simulink Parameter, Simulink Signal, MPT Parameter, or MPT Signal. For more information, see Working with Data Objects in the Simulink documentation.

• All at once, invoking Data Object Wizard for an existing model. For more information and examples, see Data Object Wizard in the Simulink documentation and Creating Simulink Data Objects with Data Object Wizard.

• Creating data objects based on an external data dictionary. You can do this manually item by item, or all at once automatically using a script. For more information, see Creating Data Objects Based on an External Data Dictionary.

The following sections illustrate how to create Simulink and mpt data objects and compares their properties as data types.

Back to Top

Creating Simulink Data Objects with Data Object Wizard

You can use Data Object Wizard to create data objects for your model (see Data Object Wizard in the Simulink documentation).

Data Object Wizard is especially useful for creating multiple data objects for

• Existing models that do not currently use data objects.

• Existing models to which you have added signals or parameters and therefore you need to create more data objects.

Creating Simulink Data Objects

This procedure creates Simulink data objects using Data Object Wizard.

1. Open the model whose data objects you want to be in the data dictionary. For example, open rtwdemo_mpf.mdl (which is located in toolbox/rtw/rtwdemos). This model appears as shown below.

   

2. Open Data Object Wizard by entering dataobjectwizard at the MATLAB command line or by selecting Data Object Wizard from the Tools menu of your model. The Data Object Wizard dialog box appears, as shown below.

   

3. In the Model name field, type the name of the model you opened in step 1 and press the Enter key, or navigate to it using the Browse button. The Find button becomes available. Notice the check boxes in the Find options pane.

4. In the Find options pane, select the desired check boxes. For descriptions of each check box, see Data Object Wizard in the Simulink documentation.

   Be sure to check the Alias types option. This finds all user-registered data types in the sl_customization.m file plus all data type replacements specified for the model in the Data Type Replacement pane of the Configuration Parameters dialog box. Data Object Wizard can create Simulink.AliasType objects from these.

5. Click the Find button. After a moment, a list of all of the model's potential data objects appear that are not yet in the code generation data dictionary, as shown below. This includes all of the model's signals (root inputs, root outputs, and block outputs), discrete states, data stores, and parameters, depending on

   • The check boxes you selected in the previous step

   • The constraint mentioned in the note above

   Data Object Wizard finds only those signals, parameters, data stores, and states whose storage class is set to Auto. The Wizard lists each data store and discrete state that it finds as a signal class.

6. Click Check All to select all data objects. Notice in the Choose package for selected data objects field that Simulink, the default, is selected. So all of the data objects are associated with the Simulink package, as shown below.

   

7. Click Create. The data objects are added to the MATLAB workspace, and they disappear from Data Object Wizard.

8. Click Cancel. The Data Object Wizard dialog box disappears.

   Now you can set property values for the data objects.

Setting Property Values for Simulink Data Objects

Most of the property values of data objects are supplied by defaults. A few are from the model. Note that for Simulink data objects, the default storage class is Auto.

1. Type daexplr on the MATLAB command line, and press Enter. The Model Explorer appears.

2. In the Model Hierarchy (left) pane, select Base Workspace. All of the Simulink data objects in the code generation data dictionary appear in the Contents of (middle) pane, as shown below.

   

3. To see the properties of a Simulink data object, select a data object in the middle pane. The right pane displays the property names, as shown below. (For descriptions of the properties, see Parameter and Signal Property Values.) These property names also appear as column headings in the middle pane. You have control over the values specified for these properties.

   

4. For this example, while pressing the Ctrl key, select signal data object A and parameter data object F1 in the middle pane.

5. In the middle pane, move the scroll bar so that you can see the StorageClass column, as shown below.

   

6. For this example, click one of the rows and select Default (Custom). The StorageClass property value for the Simulink data object changes from the default Auto to Default (Custom), as shown below.

   

Generating and Inspecting Code

All data objects for the model are in the code generation data dictionary. You have specified property values for each data object's properties as needed. Now you generate and inspect the source code, to see if it needs correction or modification. If it does, you can change property values and regenerate the code until it is what you want.

1. In the Configuration Parameters dialog box, click Real-Time Workshop in the left pane.

2. In the Report pane, select the Create code generation report check box.

   Note    When you select the Create code generation report check box, the Real-Time Workshop Embedded Coder software automatically selects two check boxes on the pane: Launch report automatically and Code-to-model. For large models, you may find that HTML report generation (step 4 below) takes longer than you want. In this case, consider clearing the Code-to-model check box (and the Model-to-code check box if selected). The report will be generated faster.

3. In the Real-Time Workshop pane, select the Generate code only check box. The Build button changes to Generate code.

   Note    The generate code process generates the .c/.cpp and .h files. The build process adds compiling and linking to generate the executable. For details on build, see in the Real-Time Workshop documentation.

4. Click the Generate code button. After a moment, the HTML report appears, listing the generated files on the left pane (under Generated Source Files).

5. Select and review files in the HTML report.

Back to Top

Creating mpt Data Objects with Data Object Wizard

Create mpt data objects using Data Object Wizard the same way you did for Simulink data objects, as explained in Creating Simulink Data Objects, except select mpt as the package instead of Simulink.

Set the property values for the mpt data objects the same way you set them for Simulink data objects, as explained in Setting Property Values for Simulink Data Objects, with the following exceptions:

• Accept the default custom storage class for mpt data objects, Global(Custom)

• For data objects A and F1, type mydefinitionfile in the Definition file field on the Model Explorer.

Then generate and inspect the code.

Note    The Alias field is related to Applying Naming Rules to Identifiers Globally.

Back to Top

Comparing Simulink and mpt Data Objects

The mpt data object contains all the properties of Simulink data objects plus properties that provide additional control over module packaging. The differences between Simulink and mpt data objects can be illustrated by comparing

• Signal and Parameter Properties

• Configuration Parameters

• Generated Code

Key differences include the following:

• Different custom storage classes displayed in the Model Explorer for mpt data objects provide more control over the appearance of the generated code.

• Additional custom attributes (owner, definition file, persistence level, memory section) for mpt data objects provide more control over data packaging in the generated code.

• On the Comments pane of the Configuration Parameters dialog box, the Custom comments (MPT objects only) option allows you to add a comment just above a signal or parameter's identifier in the generated code.

• On the Data Placement pane of the Configuration Parameters dialog box, in the Global data placement (MPT data objects only) subpane:

  • The Module naming parameter allows you to name the module that owns the model

  • The Signal display level parameter allows you to specify whether or not the code generator declares a signal data object as global data

  • The Parameter tune level parameter allows you to specify whether or not the code generator declares a parameter data object as tunable global data

Signal and Parameter Properties

The properties that appear in Model Explorer when mpt is the package include all the properties that appear when Simulink is the package plus additional properties. Notice this by comparing the next two figures. (For descriptions of all properties in Model Explorer, see Parameter and Signal Property Values.)

Configuration Parameters

The following configuration parameters relate to Real-Time Workshop Embedded Coder module packaging features. These parameters are available in the Configuration Parameters dialog box and Model Explorer when the system target file selected for a Simulink model is ert.tlc (or a system target file derived from an ert.tlc):

• Custom comments (MPT objects only) option on the Real-Time Workshop/Comments pane

• In the Global data placement (MPT data objects only) subpane on the Real-Time Workshop/Data Placement pane:

  • Module naming parameter

  • Signal display level parameter

  • Parameter tune level parameter

Generated Code

In the example used in Setting Property Values for Simulink Data Objects, you selected Default (Custom) in the Storage class field for signal A and parameter F1. You selected the default Auto in the Storage class field for the remaining data objects. But for the mpt data objects you used the default Global (Custom) in the Storage class field for all data objects. When you generated code, these selections resulted in the definitions and declarations shown in the table below.

/* For signal A */
ExternalInputs rtU;

/* For parameter F1 */
if(rtU.A * 2.0 > 10.0) {...

/* For signal A */
typedef struct {
  real_T A;
} ExternalInputs;

extern ExternalInputs rtU;

real_T A;
real_T F1 = 2.0;

extern real_T A;
extern real_T F1;

real_T A;
real_T F1 = 2.0;

extern real_T A;
extern real_T F1;

The results shown in the second and third columns of the preceding table require the following configuration parameter adjustments on the Real-Time Workshop > Data Placement pane:

• Set Data definition to Data defined in single separate source file.

• Set Data definition filename to global.c

• Set Data declaration to Data declared in single separate source file.

• Set Data definition filename to global.h

See the left column of the table, which shows generated code for Simulink signal and parameter data objects, whose Storage class field is Auto. The input A is defined as part of the structure rtU as shown above. In the case of the Simulink parameter data object F1, since the StorageClass was set to auto, the code generator chose to include the literal value of F1 in the generated code. F1 is a constant in the Stateflow diagram whose value is initialized as 2.0:

if(rtU.A * 2.0 > 10.0) { ...

For more details, see Introduction to Custom Storage Classes in the Real-Time Workshop Embedded Coder documentation and Summary of Signal Storage Class Options in the Real-Time Workshop documentation.

See the middle column of the table. The Simulink data objects whose Storage class is not Auto are defined in a definition statement in the global source file (global.c) and declared in a declaration statement in the global header file (global.h).

In the right column, Simulink data objects whose Storage class is not Auto are defined in mydefinitionfile, as you specified. The declarations for those objects are in the global header file.

Back to Top

Creating Data Objects Based on an External Data Dictionary

This procedure creates data objects based on an external data dictionary (such as a Microsoft^® Excel^® file). You can do this manually (that is, one-by-one) or automatically (all at once).

Manually Creating Objects to Represent External Data

You can create data objects (and their properties) one-by-one, based on an external data dictionary, as follows:

1. Open the external file that contains the data (such as a spreadsheet or database file).

2. Determine all of the data in this file that correspond to the parameters and signals in the model. In the code generation data dictionary, parameters in the external file belong to the Simulink parameter class and signals belong to the Simulink signal class.

3. On the MATLAB command line, type daexplr and press Enter. The Model Explorer appears.

4. On the Model Hierarchy (left) pane, expand Simulink Root, and select Base Workspace.

5. On the Add menu, select MPT Parameter or Simulink Parameter. The default name Param appears in the Contents of (middle) pane.

6. Double-click Param and rename this data object as desired.

7. Repeat steps 5 and 6 for each additional data item in the external file that belongs to the mpt.Parameter class or Simulink.Parameter class.

   Now you will add data items in the external file that belong to the mpt.Signal class or Simulink.Signal class.

8. On the Add menu, select MPT Signal or Simulink Signal. The default name Sig appears in the Contents of pane.

9. Double-click Sig and rename the data object as desired.

10. Repeat steps 8 and 9 for each additional data item in the external file that belongs to the mpt.Signal class or Simulink.Signal class.

    All external data items for the mpt.Parameter or Simulink.Parameter class, and the mpt.Signal or Simulink.Signal class now appear in the Contents of pane and in the MATLAB workspace. Therefore, they have been created in the code generation data dictionary.

    Note    The property values for these data objects are supplied by default.

Automatically Creating Objects to Represent External Data

You can create data objects (and their properties) all at once, based on an external data dictionary by creating and running a .m file. This file contains the same MATLAB commands you could use for creating data objects one-by-one on the command line, as explained in Working with Data Objects in the Simulink documentation. But instead of using the command line, you place the MATLAB commands in the .m file for all of the desired data in the external file:

1. Create a new .m file.

2. Place information in the file that describes all of the data in the external file that you want to be data objects. For example, the following information creates two mpt data objects with the indicated properties. The first is for a parameter and the second is for a signal:

   % Parameters
   mptParCon = mpt.Parameter;
   mptParCon.RTWInfo.CustomStorageClass ='Const';
   mptParCon.value = 3;
   % Signals
   mptSigGlb = mpt.Signal;
   mptSigGlb.DataType = 'int8';

3. Run the .m file. The data objects appear in the MATLAB workspace.

Note   If you want to import data from an external data dictionary, you can write functions that read the information, convert these to data objects, and load them into the MATLAB workspace. Among available MATLAB functions that you can use for this process are xmlread, xmlwrite, xlsread, xlswrite, csvread, csvwrite, dlmread, and dlmwrite.

Back to Top

Overview of the Data Dictionary

Saving and Loading Data Objects