| Simulink® | |
By default, a configuration set is stored within an individual model, which allows it to be used only by that model. Alternatively, a configuration set can stored independently of any model, which allows it to be used by any or all models.
A configuration set that exists outside any model is called a freestanding configuration set. Each model that uses a freestanding configuration set does so by defining a configuration reference that points to the configuration set. The result is the same as if the referenced configuration set were stored within the model.
You can use configuration references and freestanding configuration sets to:
Assign the same configuration set to any number of models
Each model that uses a given configuration set contains a configuration reference that points to a MATLAB® variable. The value of that variable is a freestanding configuration set. All of those models then share that configuration set, and changing the value of any parameter in the set changes it for every model that uses the set. This capability is useful for reconfiguring large numbers of submodels quickly, and for ensuring consistent configuration of parent models and referenced models.
Replace the configuration sets of any number of models without changing the model files
When multiple models use configuration references to access a freestanding configuration set, assigning a different configuration set to the MATLAB variable specified by the references assigns that set to all the models. This capability allows you to maintain a library of configuration sets and assign them as needed to any number of models in a single operation.
Use different configuration sets for a referenced model used in different contexts without changing the model file
A submodel that uses different configuration sets in different contexts contains a configuration reference that specifies the submodel's configuration set as a variable. When an instance of the submodel is called, the Simulink® software assigns that variable a freestanding configuration set for the current context.
The next figure shows one way to use configuration references. Each of the four models represented in the Model Dependency Viewer specifies the configuration reference named my_reference as its active configuration set, and my_reference points to a freestanding configuration set named Configuration. The parameter values in Configuration therefore apply to all four models, and any change to any parameter in Configuration applies to all four models.
To use a configuration reference to link a freestanding configuration set to a model, you:
Create or obtain a configuration set and store it in the base workspace as the value of a MATLAB variable.
Create a configuration reference that specifies the relevant MATLAB variable.
Attach the configuration reference to the model just as you would attach a configuration set.
Activate the reference just as you would activate a configuration set stored within the model.
Access, set, and change configuration set parameters and the MATLAB variable as needed.
A configuration reference is implemented as an object of type Simulink.ConfigSetRef, and a configuration set is an object of type Simulink.ConfigSet The two classes are similar in many ways. Wherever the same operation is applicable to both, the relevant functions and methods are overloaded to work with either class. For example, you can attach or activate a configuration set or a configuration reference using the same GUI operations and API syntax.
You cannot nest configuration references: only one level of indirection is available. You can obtain configuration parameter values by operating on a configuration reference just as if it were the configuration set that it references. See Getting Values from a Referenced Configuration Set for details. General information about configuration sets appears in Configuration Sets.
All freestanding configuration sets are stored in the base workspace as the values of base workspace variables. Although you can store a configuration set in a model and point to it with a base workspace variable, such a configuration set would not be freestanding; trying to use it in a configuration reference would cause an error. You can store a freestanding configuration set in the base workspace in these ways:
Create and populate a new configuration set.
Copy a configuration set that is stored in a model.
Load a configuration set that was saved in a MAT-file.
You can store any number of configuration sets in the base workspace, assigning each to a different variable. You can use any technique to manipulate a freestanding configuration set and its parameter values that you could use with a configuration set stored directly in a model.
You can create a new configuration set in the base workspace using any of the techniques described in Creating Configuration Sets or as follows:
cset = Simulink.ConfigSet
where cset is a new or existing base workspace variable. The new configuration set initially has default parameter values, copied from the default configuration set.
You can copy an existing configuration set to the base workspace using drag and drop operations described in Copying, Deleting, and Moving Configuration Sets, and assign the set to a MATLAB variable. For example:
cset = copy (getActiveConfigSet(mdl)) cset = copy (getConfigSet(mdl, ConfigSetName))
where mdl is any open model, and ConfigSetName is the name of any configuration set attached to the model. The first example obtains the currently active configuration set. The second example obtains a configuration set by specifying the name under which it appears in the Model Explorer.
Be sure to copy any configuration set obtained from an existing model, as shown in the examples. Otherwise, cset will refer to the existing configuration set stored in the model, rather than a new freestanding configuration set in the base workspace, and any use of a configuration references that links to cset will cause an error.
To use a freestanding configuration set across multiple MATLAB sessions, you can save it into a MAT-file. To create the MAT-file, you first copy the configuration set to a base workspace variable, as previously described, then save the variable to the MAT-file:
save (workdir/ConfigSetName.mat, cset)
where workdir is a working directory, ConfigSetName.mat is the name of the MAT-file, and cset is a base workspace variable whose value is the configuration set to be saved. When you later reopen your model, you can reload the configuration set into the variable:
load (workdir/ConfigSetName.mat)
To execute code that reads configuration sets from MAT-files, you can use the pre-load function of a top model, the MATLAB startup script, and various other techniques, including entering the load statement(s) interactively. Any technique that executes the necessary code will work.
Once you have stored a configuration set in the base workspace, as described in Creating a Freestanding Configuration Set, you can link to that configuration set from a configuration reference, and attach the reference to a model. The model then has the same configuration parameters that it would if the referenced configuration set were stored directly in the model. You can attach any number of configuration references to a model. Each must have a unique name.
To create a configuration reference using the GUI:
In the Model Explorer, select the model to which the configuration reference will be attached.
Click the Add Reference tool
or choose Add
> Configuration Reference.
A new configuration reference attaches to the selected model. The default name of the new reference is Reference, with a digit appended if necessary to prevent name conflict. The name of the configuration reference appears in the Model Hierarchy pane under the Model Workspace icon, below the names of any configuration sets.
Select the new configuration reference in the Model Hierarchy pane, or right-click the configuration reference and choose Open from the context menu.
The Configuration Reference dialog appears in the Dialog pane or a separate window.
Change the default Name if desired. This name exists for human readability, and does not affect the configuration reference functionally.
Specify the Referenced configuration set to be the base workspace variable whose value is the freestanding configuration set that you want to reference. Be careful not to specify the name of a configuration reference. Configuration references cannot be nested, and an error will result.
Click OK or Apply.
The Is Resolved field in the dialog changes to yes.
If you do not specify a valid Referenced configuration, a warning is posted. Any attempt to use a configuration reference that lacks a valid Referenced configuration generates an error. The API equivalent of Referenced configuration is WSVarName. You can later use the GUI or API to correct the specification or provide a configuration set with the correct name. See Unresolved Configuration References for more information.
To create and populate a configuration reference using the API:
Create the reference:
cref = Simulink.ConfigSetRef
Change the default name if desired:
cref.Name = 'ConfigSetRefName'
Specify the referenced configuration set:
cref.WSVarName = 'cset'
Be careful not to specify the name of a configuration reference. Configuration references cannot be nested, and an error will result.
Attach the reference to a model:
attachConfigSet(mdl, cref, true)
The third argument is optional and authorizes renaming if needed to avoid a name conflict.
Any attempt to use a configuration reference that does not specify a valid WSVarName generates an error. The GUI equivalent of WSVarName is Referenced configuration. You can later use the API or GUI to correct the reference or provide a configuration set that has the correct name. See Unresolved Configuration References for more information.
Most functions and methods that operate on a configuration reference take a handle to the reference. If you have created a configuration reference programmatically, with a statement like
cref = Simulink.ConfigSetRef
the variable cref contains a handle to the reference. If you do not already have a handle, you can obtain one by executing:
cref = getConfigSet(mdl, 'ConfigSetRefName')
where ConfigSetRefName is the name of the configuration reference as it appears in the Model Explorer, e.g., Reference. This is the name you specified by setting the Name field in the Configuration Reference dialog or executing
cref.Name = 'ConfigSetRefName'
The technique for obtaining a configuration reference handle is the same as you would use to obtain a configuration set handle. Wherever the same operation applies to both configuration sets and configuration references, applicable functions and methods are overloaded to perform correctly with either class.
After you have created a configuration reference and attached it to a model, you can attach copies of the reference to any number of additional models. To create and attach a copy of a configuration reference, you can use any GUI or API technique that you could use to copy and attach a configuration set, such as dragging, pasting, or a function like attachConfigSetCopy. See Copying, Deleting, and Moving Configuration Sets and Configuration Set API.
Models do not share configuration reference objects. Each model has its own copy of any configuration reference attached to it, just as each has its own copy of any attached configuration set. Configuration references in different models establish configuration set sharing by specifying the same base workspace variable, which links the various models to the same freestanding configuration set.
If you use the GUI, attaching an existing configuration reference to an additional model automatically attaches a copy, as distinct from a handle to the original. If necessary to prevent name conflict, the GUI will add or increment a digit at the end of the copied reference's name. If you use the API, be sure to explicitly copy the configuration reference before attaching it, with statements like:
cref = copy (getConfigSet(mdl, ConfigSetName)) attachConfigSet (cref, mdl, true)
If you omit the copy operation, cref will be a handle to the original configuration reference, rather than a copy of the reference, and any attempt to use cref will cause an error. If you omit the argument true to attachConfigSet, the operation will fail if it would cause a name conflict.
The following example shows code for obtaining a freestanding configuration set and attaching references to it to two models. After the code executes, one of the models contains both an internal configuration set and a configuration reference that points to a freestanding copy of that configuration set. If the internal copy is superfluous, it can be removed with detachConfigSet, as shown in the last line of the example.
% Get copy of original config set as
% a variable in the base workspace
open_system('mdl1')
% Get handle to local cset
cset = getConfigSet('mdl1', 'Configuration')
% Create freestanding copy; original remains in model
cset1 = copy(cset)
% In the original model, create a configuration
% reference to the cset copy
cref1 = Simulink.ConfigSetRef
cref1.WSVarName = 'cset1'
% Rename if name conflict occurs
attachConfigSet('mdl1', cref1, true)
% In a second model, create a configuration
% reference to the same cset
open_system('mdl2')
% Rename if name conflict occurs
attachConfigSetCopy('mdl2', cref1, true)
% Delete original cset from first model
detachConfigSet('mdl1', 'Configuration')You can change an existing configuration reference as needed by reopening its Configuration Reference dialog and changing its Name or Referenced configuration. Similarly, you can use the API on an existing configuration reference to change its Name or WSVarName. If you refer to a configuration set that does not yet exist, no error occurs, but the configuration reference is unusable. The configuration reference becomes usable as soon as the configuration set exists.
Once you have created a configuration reference and attached it to a model, you can activate it using any technique that would activate a configuration set stored in the model, such as:
From the GUI, choose Activate from the configuration reference's context menu.
From the API, execute setActiveConfigSet, specifying the configuration reference as the first argument.
When a configuration reference is active, the Is Active field of the Configuration Reference dialog is yes, and the Model Explorer shows the name of the reference suffixed with (Active).
The freestanding configuration set to which the active reference points now provides the configuration parameters for the model containing the reference.
When a configuration reference does not specify a valid configuration set, the configuration reference is unresolved, and the Is Resolved field of its Configuration Reference dialog has the value no. If you activate an unresolved configuration reference, no warning or error occurs. However, an unresolved configuration reference that is Active provides no configuration parameter values to the model. Therefore:
Fields that display values that can be known only by accessing a configuration parameter, like Stop Time in the model window, are blank.
Trying to build the model, simulate it, generate code for it, or otherwise require it to access configuration parameter values, causes an error.
Creating and Attaching a Configuration Reference describes techniques for resolving configuration references.
You can use get_param on a configuration reference to obtain parameter values from the linked configuration set, just as if the reference object were the configuration set itself. The Simulink software retrieves the referenced configuration set and performs the indicated get_param on it.
For example, if configuration reference cref links to configuration set cset, the following operations give identical results:
get_param (cset, 'StopTime') get_param (cref, 'StopTime')
You cannot change a configuration set in any way, including changing configuration parameter values, by operating on a configuration reference. Thus, with cref and cset as above, if you executed:
set_param (cset, 'StopTime', 300) set_param (cref, 'StopTime', 300) % ILLEGAL
the first operation would succeed, but the second would cause an error. Instead, you must obtain the configuration set itself and change it directly, using the GUI or the API.
To obtain a referenced configuration set using the GUI:
Select the configuration reference in the Model Hierarchy pane, or right-click the configuration reference and choose Open from the context menu.
The Configuration Reference dialog appears in the Dialog pane or a separate window.
Click Open to the right of the Referenced configuration field.
The Configuration Parameters dialog box opens on the configuration set specified by Referenced configuration. You can now change and apply or save parameter values as you would for any configuration set.
To obtain a referenced configuration set using the API:
Obtain a handle to the configuration reference, as described in Obtaining a Configuration Reference Handle.
Obtain the configuration set cset from the configuration reference cref:
cset = cref.getRefConfigSet
You can now use set_param on cset to change parameter values. Example:
set_param (cset, 'StopTime', 300)
If you want to change parameter values through the GUI, execute:
cset.openDialog
The Configuration Parameters dialog box opens on the specified configuration set.
You can completely replace the base workspace variable and configuration set that a configuration reference uses. However, the pointer from the configuration reference to the configuration set becomes stale. You must then execute:
cref.refresh
where cref is the configuration reference. If you do not execute refresh, the configuration reference will continue to use the previous instance of the base workspace variable and its configuration set. This example illustrates the problem.
% Create a new configuration set
cset1=Simulink.ConfigSet;
% Set a non-default stop time
set_param (cset1, 'StopTime', 500)
% Create a new config reference
cref1=Simulink.ConfigSetRef;
% Resolve the config ref to the set
cref1.WsVarName='cset1';
% Attach the config ref to a model
attachConfigSet('mdl1', cref1, true)
% Replace config set on base workspace
cset1=Simulink.ConfigSet;
% Call to refresh is commented out!
% cset1.refresh;
% Set a different stop time
set_param (cset, 'StopTime', 75)If you simulate the model, it will stop at 500, not at 75. Calling cset1.refresh where shown prevents the problem.
The Real-Time Workshop® pane of the Configuration Parameters dialog contains a Build button. Its availability differs depending on whether the configuration set displayed by the dialog is stored in a model or is a freestanding configuration set.
When the pane displays a configuration set stored in a model, the Build button is enabled, and you can use it to generate and compile code for the model.
When the pane displays a freestanding configuration set, the Build button is disabled because the configuration set does not know which (if any) models are linked to it.
To provide the same capabilities whether a configuration set is stored in a model or is freestanding, the Configuration Reference dialog contains a Build button. This button has the same effect as its equivalent in the Configuration Parameters dialog, and operates on the model that contains the configuration reference.
You cannot nest configuration references: only one level of indirection is available, so a configuration reference cannot link to another configuration reference; it must specify a freestanding configuration set.
If you replace the base workspace variable and configuration set that a configuration reference uses, you must then execute refresh for every configuration reference that uses the replaced variable and set. See Replacing a Referenced Configuration Set.
If you activate a configuration reference when using a custom target, the ActivateCallback function does not get triggered to notify the corresponding freestanding configuration set. Likewise, if a freestanding configuration set switches from one target to another, the ActivateCallback does not get triggered to notify the new target, even if an active configuration reference points to that target. For more information about ActivateCallback functions, see rtwgensettings Structure in the Real-Time Workshop® Embedded Coder™ Developing Embedded Targets documentation.
| Configuration Sets | Diagnosing Simulation Errors | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |