Simulink.ModelReference.modifyProtectedModel
Modify existing protected model
Syntax
Description
modifies options for an existing protected model specified by
harnessHandle
= Simulink.ModelReference.modifyProtectedModel(mdl
)mdl
. If you do not specify name-value arguments, the
modified protected model is updated with default values and supports only
simulation.
When model protection creates and opens a harness model, the handle of the
harness model is returned by harnessHandle
. By default,
harnessHandle
returns 0
.
specifies options using one or more name-value arguments in addition to the
input arguments in previous syntaxes. For example, change the encryption
passwords for read-only view, simulation, and code generation. When you add
functionality to the protected model or change encryption passwords, the
unprotected model must be available. The software searches for the model on the
MATLAB® path.harnessHandle
= Simulink.ModelReference.modifyProtectedModel(mdl
,Name=Value
)
[
returns the names of base workspace variables used by the protected model in
harnessHandle
,neededVars
] = Simulink.ModelReference.modifyProtectedModel(___)neededVars
. Specify an input argument combination from
the previous syntaxes.
Examples
Update Protected Model with Default Values
Create a modifiable protected model with support for code generation, then reset the protected model to use default values.
Open an example that contains the referenced model named
sldemo_mdlref_counter
.
mdl = "sldemo_mdlref_counter";
openExample(mdl)
Add the password for when a protected model is modified. If you skip this step, you are prompted to set a password when a modifiable protected model is created.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Create a modifiable protected model with support for code generation.
Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",... Modifiable=true,Report=true);
Provide the password to modify the protected model.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Modify the model to use default values.
Simulink.ModelReference.modifyProtectedModel(mdl);
The resulting protected model is updated with default values and supports only simulation.
Remove Functionality from Protected Model
Create a modifiable protected model with support for code generation and web view, then modify the protected model to remove the web view support.
Open an example that contains the referenced model named
sldemo_mdlref_counter
.
mdl = "sldemo_mdlref_counter";
openExample(mdl)
Add the password for when a protected model is modified. If you skip this step, you are prompted to set a password when a modifiable protected model is created.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Create a modifiable protected model with support for code generation and web view.
Simulink.ModelReference.protect(mdl,... Mode="CodeGeneration",Webview=true,... Modifiable=true,Report=true);
Provide the password to modify the protected model.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Remove support for web view from the protected model that you created.
Simulink.ModelReference.modifyProtectedModel(... mdl,Mode="CodeGeneration",Report=true);
Change Encryption Password for Code Generation
Change an encryption password for a modifiable protected model.
Open an example that contains the referenced model named
sldemo_mdlref_counter
.
mdl = "sldemo_mdlref_counter";
openExample(mdl)
Add the password for when a protected model is modified. If you skip this step, you are prompted to set a password when a modifiable protected model is created.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Add the password that the protected model user must provide to generate code.
Simulink.ModelReference.ProtectedModel.setPasswordForSimulation(... mdl,"simpassword");
Create a modifiable protected model with a report and support for code generation with encryption.
Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",... Encrypt=true,Modifiable=true,Report=true);
Provide the password to modify the protected model.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Change the encryption password for simulation.
Simulink.ModelReference.modifyProtectedModel(... mdl,Mode="CodeGeneration",Encrypt=true,Report=true,... ChangeSimulationPassword={'simpassword','new_password'});
Add Harness Model for Protected Model
Create a harness model for an existing protected model.
Open an example that contains the referenced model named
sldemo_mdlref_counter_bus
.
mdl = "sldemo_mdlref_counter_bus";
openExample(mdl)
Add the password for when a protected model is modified. If you skip this step, you are prompted to set a password when a modifiable protected model is created.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Create a modifiable protected model with a report and support for code generation with encryption.
Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",... Modifiable=true,Report=true);
Provide the password to modify the protected model.
Simulink.ModelReference.ProtectedModel.setPasswordForModify(... mdl,"password");
Add a harness model for the protected model and determine the variables required by the protected model.
[harness,neededVars] = Simulink.ModelReference.modifyProtectedModel(... mdl,Mode="CodeGeneration",Report=true,Harness=true);
The harness model handle is given by harness
.
The variables you must send the recipient are given by
neededVars
. The value of
neededVars
is a cell array that contains the names of
the variables required by the protected model. However, the cell array might
also contain the names of variables that the model does not need.
Tip
To automatically package required variable definitions with the
protected model in a project, set Project
to
true
.
Before you share the protected model, edit neededVars
to delete the names of any variables that the model does not need. Save the
required variables in a data dictionary.
Input Arguments
mdl
— Model name
character vector | string scalar
Model name, specified as a string or character vector. Specify the name of the protected model that you want to modify or the path of the Model block that references the protected model.
Data Types: char
| string
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Mode="CodeGeneration",OutputFormat="Binaries",ObfuscateCode=true)
specifies that obfuscated code be generated for the protected model and that only
binary files and headers in the generated code be visible to users of the protected
model.
Project
— Option to collect dependencies in project
false
(default) | true
Since R2023b
Option to collect dependencies in project, specified as false
or
true
.
Specify whether to package supporting files, including a harness model, with the protected model in a project archive. The type and number of supporting files depends on the model being protected. Examples of supporting files are a MAT file with base workspace definitions and a data dictionary pruned to relevant definitions. The supporting files are not protected.
false
— Create only the protected model. If the protected model has dependencies, you must share them separately. Similarly, if you create a harness model for the protected model, you must share the harness model separately.true
— Create a project archive (.mlproj
) that contains the protected model, its dependencies, and its harness model. The supporting files are not protected. The project archive is a single file that allows for easy sharing. To create the interactive project, open the project archive.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Project=true)
Tips
Before sharing the project, check whether the project contains the required supporting files. If supporting files are missing, simulating or generating code for the related harness model can help identify them. Add the missing dependencies to the project and update the harness model as needed. For more information, see Manage Project Files.
Dependencies
To set Project
to true
, set
Mode
to a value that supports simulation.
For example, set Mode
to
"Simulation"
(default).
Data Types: logical
ProjectName
— Custom project name
character vector | string scalar
Since R2023b
Custom project name, specified as a character vector or string scalar.
Specify the name of the project archive that contains the generated files. The project inside the archive uses the same name.
If you do not specify a custom project name, the default name for the project is
the protected model name followed by _protected
.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Project=true,ProjectName="MyProject")
Dependencies
To enable this argument, set Project
to
true
.
Data Types: char
| string
Harness
— Option to create harness model
false
(default) | true
Option to create harness model, specified as a Boolean value.
Specify whether to create a harness model for the protected model. The harness model provides an isolated environment for the protected model, which is referenced by a Model block.
false
— Do not create a harness model for the protected model.true
— Create a harness model for the protected model.
When you create a harness model for a protected model that relies on base workspace definitions, the software creates a MAT file that contains the base workspace definitions.
The harness model must have access to supporting files, such as a MAT file with base workspace definitions or a data dictionary.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Harness=true)
Dependencies
Data Types: logical
Path
— Folder for protected model
current working folder (default) | character vector | string scalar
Folder for protected model, specified as a character vector or string scalar.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Path="C:\Work")
Dependencies
The model being protected must be on the MATLAB path.
Data Types: char
| string
Tag
— Custom text string for additional information
character vector | string scalar
Since R2024b
Custom text string for additional information, specified as a character vector or string scalar.
Being able to trace a protected model to the corresponding version of the design file can be useful for debugging. To store file provenance information in a protected model, specify a custom text tag with information such as the job number, Git™ commit, or continuous integration system tag associated with creating the protected model.
The tag length must not exceed 256 characters.
To generate a tag based on environment variables, use the getenv
function.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Tag=
myTag
)
Data Types: char
| string
Verbose
— Verbose output of build process information
false
or 0
(default) | true
or 1
Since R2024b
Verbose output of build process information, specified as a numeric or
logical 1
(true
) or
0
(false
).
By default, the model protection process displays limited build
process information. To display verbose build process information during
model protection, set Verbose
to
true
.
To control the display of build process information, the model protection process temporarily overrides the values of the Verbose accelerator builds and Verbose build configuration parameters.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Verbose=true)
Data Types: logical
Report
— Option to generate report
false
(default) | true
Option to generate report, specified as a Boolean value.
To view the report, perform one of these actions:
Simulink® Editor: On the Model block, right-click the protected-model badge icon . Then, select Display Report.
MATLAB Command Window: Use the
Simulink.ProtectedModel.open
function. For example, to display the report for a protected model namedsldemo_mdlref_counter
, enter this command.Simulink.ProtectedModel.open("sldemo_mdlref_counter","report");
The report is generated in HTML format. It includes information on the environment, functionality, and interface for the protected model.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Report=true)
Dependencies
To set Report
to true
, set
Mode
to a value that supports simulation.
For example, set Mode
to
"Simulation"
(default).
Data Types: logical
Webview
— Option to include read-only web view
false
(default) | true
Option to include read-only web view, specified as a Boolean value.
Specify whether to share an interactive rendition of a Simulink model that the recipient can view in a web browser. This read-only web view of the model includes the contents and block parameters of the model.
false
— Do not share a web view of the model that you protect.true
— Share a web view of the model that you protect.
To open a web view of a protected model, perform one of these actions:
Current Folder Browser: Double-click the protected model file (
.slxp
).MATLAB Command Window: Use the
Simulink.ProtectedModel.open
function. For example, to display the web view for a protected model namedsldemo_mdlref_counter
, enter this command.Simulink.ProtectedModel.open("sldemo_mdlref_counter","webview");
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Webview=true)
Dependencies
Creating a read-only web view of the model requires a Simulink Report Generator™ license.
Data Types: logical
Mode
— Model protection mode
"Simulation"
(default) | "CodeGeneration"
| "HDLCodeGeneration"
| "ViewOnly"
Model protection mode, specified as one of these values:
"Simulation"
(since R2023b) — A model that references the protected model can run in normal, accelerator, or rapid accelerator mode.Before R2023b: Use
"Accelerator"
instead of"Simulation"
."CodeGeneration"
— A model that references the protected model can run in normal, accelerator, rapid accelerator, or external mode and can support C and C++ code generation. This option requires a Simulink Coder™ license."HDLCodeGeneration"
— A model that references the protected model can run in normal, accelerator, or rapid accelerator mode and can support HDL code generation. This option requires an HDL Coder™ license."ViewOnly"
— The protected model supports only a read-only web view. The protected model does not support simulation or code generation. This option requires a Simulink Report Generator license.
For information about simulation modes in model hierarchies, see Choose Simulation Modes for Model Hierarchies.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Mode="Simulation")
CodeInterface
— Interface for generated code
"Model reference"
(default) | "Top model"
Interface for generated code, specified as one of these values:
"Model reference"
— A Model block that references the protected model can support C and C++ code generation and simulation in accelerator, software-in-the-loop (SIL), or processor-in-the-loop (PIL) mode. For SIL and PIL simulations, the software deploys the generated code as part of a larger application that uses the referenced model. The generated artifacts match those generated by theslbuild
function with the"ModelReferenceCoderTarget"
build specification."Top model"
— A Model block that references the protected model can support simulation in accelerator, software-in-the-loop (SIL), or processor-in-the-loop (PIL) mode. For SIL and PIL simulations, the software deploys the generated code as a standalone application. The generated artifacts match those generated by theslbuild
function with the"StandaloneCoderTarget"
build specification.
SIL and PIL simulations can verify the protected model code.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,CodeInterface="Top
model")
Dependencies
The System target file configuration
parameter must be set to an ERT-based system target file, for example,
ert.tlc
. This option requires an Embedded Coder® license.
hdl
— Option to generate HDL code
false
(default) | true
Option to generate HDL code, specified as a Boolean value.
For the protected model to support simulation, C and C++ code generation, and HDL code
generation, set Mode
to
"CodeGeneration"
and hdl
to
true
.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Mode="CodeGeneration",hdl=true)
Tips
For the protected model to support simulation and HDL code
generation, but not C or C++ code generation, set
Mode
to
"HDLCodeGeneration"
. You do not have to set
hdl
to true
.
Dependencies
To generate HDL code, you must have an HDL Coder license.
This argument affects the output only when you set
Mode
to"CodeGeneration"
.
Data Types: logical
Callbacks
— Option to specify callbacks for protected model
{}
(default) | cell array
Option to specify callbacks for protected model, specified as a cell array of
Simulink.ProtectedModel.Callback
objects.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Callbacks={pmcallback_sim,pmcallback_cg})
Data Types: cell
ObfuscateCode
— Option to obfuscate generated code
true
(default) | false
Option to obfuscate generated code, specified as a Boolean value.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Mode="CodeGeneration",ObfuscateCode=true)
Dependencies
This option is applied only when you set Mode
to "CodeGeneration"
. Obfuscation is not supported
for HDL code generation.
Data Types: logical
OutputFormat
— Protected code visibility
"CompiledBinaries"
(default) | "MinimalCode"
| "AllReferencedHeaders"
Protected code visibility, specified as one of these values:
"CompiledBinaries"
— Include only compiled binaries for the generated code. The binary files and headers are visible."MinimalCode"
— Include only the minimal header files required to build the code with the chosen build settings. The code in the build folder is visible. Recipients can inspect the code in the protected model report and recompile it for their purposes."AllReferencedHeaders"
— Include header files found on the include path. The code in the build folder is visible. The headers referenced by the code are also visible.
This argument determines what part of the code generated for a protected model is visible to users.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Mode="CodeGeneration",OutputFormat="AllReferencedHeaders")
Dependencies
This argument affects the output only when you set
Mode
to "Simulation"
,
"Accelerator"
, or
"CodeGeneration"
.
Encrypt
— Option to encrypt protected model
false
(default) | true
Option to encrypt protected model, specified as a Boolean value.
This option applies when you have specified a password during protection, or by using these functions:
Password for read-only view of model:
Simulink.ModelReference.ProtectedModel.setPasswordForView
Password for simulation:
Simulink.ModelReference.ProtectedModel.setPasswordForSimulation
Password for code generation:
Simulink.ModelReference.ProtectedModel.setPasswordForCodeGeneration
Password for HDL code generation:
Simulink.ModelReference.ProtectedModel.setPasswordForHDLCodeGeneration
To apply the specified passwords to the protected model, set
Encrypt
to true
.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Encrypt=true)
Data Types: logical
ChangeSimulationPassword
— Option to change encryption password for simulation
cell array of two character vectors
Option to change encryption password for simulation, specified as a cell array of two character vectors. The first vector is the old password. The second vector is the new password.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Encrypt=true,ChangeSimulationPassword={'old_password','new_password'})
Dependencies
To enable this argument, set Encrypt
to
true
.
Data Types: cell
ChangeViewPassword
— Option to change encryption password for read-only view
cell array of two character vectors
Option to change encryption password for read-only view, specified as a cell array of two character vectors. The first vector is the old password. The second vector is the new password.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Encrypt=true,ChangeViewPassword={'old_password','new_password'})
Dependencies
To enable this argument, set Encrypt
to
true
.
Data Types: cell
ChangeCodeGenerationPassword
— Option to change encryption password for code generation
cell array of two character vectors
Option to change encryption password for code generation, specified as a cell array of two character vectors. The first vector is the old password. The second vector is the new password.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Encrypt=true,ChangeCodeGenerationPassword={'old_password','new_password'})
Dependencies
To enable this argument, set Encrypt
to
true
.
Data Types: cell
CustomPostProcessingHook
— Option to add postprocessing function for protected model files
function handle
Option to add a postprocessing function for protected model files, specified as a function handle.
The function accepts a Simulink.ModelReference.ProtectedModel.HookInfo
object as
an input variable. This object provides information on the source code
files and other files generated during protected model creation. The
object also provides information on exported symbols that you must not
modify. Prior to packaging the protected model, the software calls the
postprocessing function.
For a protected model with a top model interface, the Simulink.ModelReference.ProtectedModel.HookInfo
object cannot provide
information on exported symbols.
Example: Simulink.ModelReference.modifyProtectedModel(mdl,Mode="CodeGeneration",CustomPostProcessingHook=@(protectedMdlInf)myHook(protectedMdlInf))
Dependencies
To enable this argument, set Mode
to
"CodeGeneration"
.
Output Arguments
harnessHandle
— Handle of harness model
double
neededVars
— Names of base workspace variables
cell array
Names of base workspace variables that the protected model uses, returned as a cell array.
The cell array includes:
Parameters that are used by the model interface
Parameters that specify part of a data type, such as a bus object, enumerated type, or value type
Parameters that are used by data store memory
The cell array can also include variables that the protected model does not use.
Version History
Introduced in R2014bR2024b: Specify custom text tag with additional information
The new Tag
argument lets you specify custom text with
information that is relevant to the protected model.
Being able to trace a protected model to the corresponding version of the design file can be useful for debugging. To store file provenance information in a protected model, specify a custom text tag with information such as the job number, Git commit, or continuous integration system tag associated with creating the protected model.
R2024b: Model protection now provides limited build process information by default
To focus on the high-level steps in the model protection process, the
Simulink.ModelReference.modifyProtectedModel
function now displays limited build process
information by default. The model protection process temporarily overrides the
values of the Verbose accelerator builds and
Verbose build configuration
parameters.
To display verbose build process information during model protection, set
Verbose
to true
.
R2023b: Collect protected model dependencies in project
When you modify a protected model, you can automatically package the protected model with its dependencies and a harness model in a project archive. When the recipient extracts the contents of the project archive and opens the harness model, they should be able to simulate the protected model without needing to define missing variables or objects. Before sharing the project archive, check whether the project contains the required supporting files, and update the harness model as needed.
Use Project
to save the protected model, its dependencies, and its
harness model in a project archive (.mlproj
). The project archive
provides a way to share a project in a single file.
Use ProjectName
to specify a custom project name.
For more information, see Package and Share Protected Models
R2023b: External mode support with Mode
set to 'CodeGeneration'
When you set Mode
to 'CodeGeneration'
, the
protected model supports external mode simulation.
R2023b: Default Mode
value is 'Simulation'
The name of the default Mode
value has changed from
'Accelerator'
to 'Simulation'
. The behavior of the
default value has not changed.
R2023b: 'Accelerator'
is not recommended
The Mode
value 'Accelerator'
is not recommended.
Use 'Simulation'
instead.
'Simulation'
and'Accelerator'
behave the same.'Simulation'
aligns better with the simulation option in the Create Protected Model dialog box.'Accelerator'
refers to only one of the supported simulation modes. A model that references a protected model that supports simulation can run in normal, accelerator, or rapid accelerator mode.
There are no plans to remove 'Accelerator'
.
R2023a: Mode
will not support normal mode restrictions
In a future release, when you set Mode
to
'Normal'
, the function will create a protected model that supports
simulation when the parent model simulates in normal, accelerator, or rapid accelerator
mode. This change will standardize simulation support for new protected models. Protected
models created before this change will be unaffected.
Currently, when you set Mode
to 'Normal'
, the
function creates a protected model that supports simulation only when the parent model
simulates in normal mode.
R2023a: Default Mode
value is 'Accelerator'
The default value of the Mode
argument is
'Accelerator'
. A model that references the protected model can run in
normal, accelerator, or rapid accelerator mode.
With this change, the Create Protected Model dialog box and
Simulink.ModelReference.protect
function use the same default model
protection mode.
Previously, the default value of the Mode
argument was
'Normal'
. The 'Normal'
model protection mode
restricts the use of the protected model such that the protected model supports simulation
only when the parent model simulates in normal mode.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)