Model Reference Support in SimWB
SIMulation Workbench (SimWB) and the MLToolkit support code generation for models that reference
other models.
Model reference offers several advantages for Hardware-In-the-Loop
(HIL) simulation such as:
- Modular Development
Different teams can work on different parts of a larger project
independently. Their individual models can be integrated into one model that can
be simulated with SimWB.
- Incremental Code Generation
Changes in one model do not need code generation for
the entire model saving both computational cost and time.
- Scalable
Large monolithic models result in huge
computational cost while generating code and updating the model. Model reference
provides a scalable answer to such issues.
For an overview of model reference, refer to the Simulink® documentation.
Contents
Configuring Referenced Models
When you generate code from a model using the MLToolkit, the software automatically replaces supported
source/sink blocks with SimWB-compliant source/sink blocks. This replacement is done to map the
source/sink blocks to their corresponding RTDB variables. Then, the software generates SimWB-compliant code for the
model. For code generation, all model references
must be configured as explained in Model Settings Changed by MLToolkit. You can
configure the models using one of the following approaches:
Alternatively, you can use the configuration set reference feature in Simulink, which allows multiple models to share
a configuration set. If your top-level model and referenced models share the same configuration set, then you can
use the standard MLToolkit GUI workflow to create an RTDB or generate SimWB-compliant code. For more details, see Configuration Set Reference Support.
Automatic Configuration of Referenced Models
To automatically configure all the referenced models in a top level model that is needed
to be built for SimWB, use the SimWB helper function named
simwbConfigModelRef
. This function does not modify the top-level model, but configures all the referenced models. For
example, the command
simwbConfigModelRef('SYS')
configures all the models referenced in the
model 'SYS' to work with MLToolkit and saves them. It also saves a backup copy
of all those models by default. Additional arguments can be supplied as one of the following name-value pairs:
- ModelType - 'TopLevel' or 'Individual' (default: 'TopLevel')
- Target - 'grt' or 'ert' (default: 'grt')
- Backup - true or false (default: true)
Options are case-insensitive on all platforms.
Manual Configuration of Referenced Models
The following example shows how to configure a simple model that
references another model. In this tutorial, we will go over the advantages of model
reference and the steps to configure the referenced models before using with
SimWB. We will work with the basic
model reference demo model named sldemo_mdlref_basic in
Simulink.
- Open the model
sldemo_mdlref_basic by either clicking here or by executing the
following command in MATLAB®:
sldemo_mdlref_basic
- Save the model as my_sldemo_mdlref_basic.
- All of the model blocks in this model reference the same model. Open the
model that it references by clicking any one of the model blocks. It should open
the model sldemo_mdlref_counter. Save this model as
my_sldemo_mdlref_counter.
- Open the 'Configuration
Parameters' for the model my_sldemo_mdlref_counter (Simulation
> Configuration Parameters) and select grt.tlc for the
System Target File (Code Generation > System Target File).
- Also,
change the 'Interface' from 'none' to 'C API' (Code Generation > Interface).
Make sure the 'signals' and 'parameters' check boxes are selected.
- In
the same 'Interface' pane changes the 'Target function library' from 'C89/C90
ANSI' to 'C99 ISO'. Save the model to preserve the changes. The model is now
ready to be included in the_sldemo_mdlref_basic model.
- Let us configure the model my_sldemo_mdlref_basic to have
some output RTDB variables. Prefix 'SW' to the names of all the scopes. This
will allow us to observe the waveforms at those scopes on the real-time host. Save the
model to preserve the changes. Now we are ready to generate code and send it to
the real-time host.
- In the model,
my_sldemo_mdlref_basic, select the
SimWB > Toolkit GUI
to open
the MLToolkit GUI. After logging in open the
RTDB Creator
tab,
set the name of RTDB as
my_sldemo_mdlref_basic
, and click
Create and Upload
RTDB
.
- Open the
Code Generator
tab in the MLToolkit GUI, make sure the
RTDB selected is
my_sldemo_mdlref_basic
, and then click on the
Generate, Export,
and Make
button to generate code and send it to SimWB real-time host.
Upon successful completion of the Make process the following message will be displayed on the MATLAB
command prompt.
You are now ready to use this executable in a test
on the real-time host.
For your convenience, the completed models
my_sldemo_mdlref_basic and
my_sldemo_mdlref_counter are included with SimWB installation. You
can access them with the following commands in MATLAB®:
ccur_sldemo_mdlref_basic
ccur_sldemo_mdlref_counter
Model Settings Changed by MLToolkit
MLToolkit automatically changes the following parameters
of the model for SimWB-compliant code generation.
- SystemTargetFile: Set to grt.tlc unless specified otherwise in the SimWB Preferences
file.
- RTWCAPISignals: Set to 'ON' allowing access to the signals in the SimWB Host.
- RTWCAPIParams: Set to 'ON' allowing access to the
parameters in the SimWB Host.
- GenFloatMathFcnCalls:
Set to use 'ISO C'.
In case of ERT, in addition
to the above parameters SimWB sets the following parameters:
- SupportContinuousTime: Set to 'ON' to support
continuous time found in most of the HIL models.
- GenerateSampleERTMain: Set to 'OFF' since SimWB
will provide the main function.
- GRTInterface: Set to 'ON'.
While this is convenient, there are certain
restrictions on the configuration of the referenced models with respect to the
top model in Simulink.
Simulation Requirements1: Simulation
settings that need to match between top and referenced models are as shown
below.
Dialog Box Pane |
Option |
Requirement |
Solver |
Start time |
The start time of the top model and all referenced models must
be the same, but need not be zero.
|
Stop time |
Simulink uses
Stop time of the top model for simulation, overriding any differing
Stop time in a sub model.
|
Type Solver |
The
Type and Solver of the top model apply throughout the hierarchy.
|
Data Import/Export |
Initial state |
Can be
on for the top model, but must be off for a referenced
model.
|
Optimization |
Inline
parameters |
Can be on or off for
a top model, but must be on for a referenced model.
|
Application lifespan
(days) |
Must be the same for top and
referenced models. |
Model
Referencing |
Total number of instances allowed
per top model |
Must not be Zero in a
referenced model. Specifying One rather than Multiple is
preferable or required in some cases.
|
Hardware Implementation |
Embedded hardware options
|
All values must be the same for top and referenced
models. |
Code Generation Requirements2: Code
generation settings restrictions are listed as shown below.
Dialog Box Pane
|
Option
|
Requirement |
Solver |
Start time |
Some
system targets require the start time of all models to be zero.
|
Hardware Implementation |
Emulation hardware options
|
All values must be the same for top and referenced
models. |
Code Generation |
System target file |
Must
be the same for top and referenced models. |
Language |
Must be
the same for top and referenced models.
|
Generate code only |
Must be the same for top and referenced
models. |
Symbols |
Maximum identifier length |
Cannot be longer for a referenced model than for its parent
model. |
Interface |
Target function library |
Must be the same for top and referenced
models. |
Data exchange > Interface |
C API |
The C API check
boxes for signals, parameters, and states must be the same for top and
referenced models. |
ASAP2 |
Can be on
or off in a top model, but must be off in a referenced model.
If it is not, the Simulink Coder software temporarily sets it to off
during code generation. |
Limitations in Model Reference Support
- If you would like to access the parameters inside the referenced models in
the SimWB Real-Time Host, you need to convert them into Global Tunable
Parameter. A global tunable parameter is a Simulink.Parameter
object whose storage class is "Model Default". The parameter exists
in the MATLAB workspace. Using a global tunable parameter in a referenced model
allows you to control the behavior of the referenced model by setting the parameter
value. All instances of the model use the same value. To see an example, execute
the following command in MATLAB®:
ccur_rtwdemo_capi
Opening this model will load variables used in the model. All the parameters used in
the referenced model ccur_rtwdemo_capi_bot,
Kp and Ki are defined in the workspace as Simulink.Parameter with
storage class set to 'SimulinkGlobal'.
- The source and sink blocks inside the referenced model(s) can not be mapped
to RTDB variables. To work around this issue, you can bring them out to the top
model.
1From Simulink
documentation.
2From Simulink Coder documentation.