Simulink.ModelReference.modifyProtectedModel

Modify existing protected model

Syntax

Simulink.ModelReference.modifyProtectedModel(model)

Simulink.ModelReference.modifyProtectedModel(model,Name,Value)

[harnessHandle] = Simulink.ModelReference.modifyProtectedModel(model,'Harness',true)

[~ ,neededVars] = Simulink.ModelReference.modifyProtectedModel(model)

Description

Simulink.ModelReference.modifyProtectedModel(model) modifies options for an existing protected model created from the specified model. If Name,Value pair arguments are not specified, the modified protected model is updated with default values and supports only simulation.

Simulink.ModelReference.modifyProtectedModel(model,Name,Value) uses additional options specified by one or more Name,Value pair arguments. These options are the same options that are provided by the Simulink.ModelReference.protect function. However, these options have additional options to change 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. If the model is not found, the software reports an error.

[harnessHandle] = Simulink.ModelReference.modifyProtectedModel(model,'Harness',true) creates a harness model for the protected model. It returns the handle of the harness model in harnessHandle.

[~ ,neededVars] = Simulink.ModelReference.modifyProtectedModel(model) returns a cell array that includes the names of base workspace variables used by the protected model.

Examples

Update Protected Model with Default Values

Create a modifiable protected model with support for code generation, then reset it to default values.

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.

openExample('sldemo_mdlref_counter');
Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Create a modifiable protected model with support for code generation and Web view.

Simulink.ModelReference.protect('sldemo_mdlref_counter','Mode',...
'CodeGeneration','Modifiable',true,'Report',true);

Provide the password to modify the protected model.

Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Modify the model to use default values.

Simulink.ModelReference.modifyProtectedModel(...
'sldemo_mdlref_counter');

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 it to remove the Web view support.

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.

openExample('sldemo_mdlref_counter');
Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Create a modifiable protected model with support for code generation and Web view.

Simulink.ModelReference.protect('sldemo_mdlref_counter','Mode',...
'CodeGeneration','Webview',true,'Modifiable',true,'Report',true);

Provide the password to modify the protected model.

Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Remove support for Web view from the protected model that you created.

Simulink.ModelReference.modifyProtectedModel(...
'sldemo_mdlref_counter', 'Mode', 'CodeGeneration','Report',true);

Change Encryption Password for Code Generation

Change an encryption password for a modifiable protected model.

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.

openExample('sldemo_mdlref_counter');
Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Add the password that the protected model user must provide to generate code.

Simulink.ModelReference.ProtectedModel.setPasswordForSimulation(...
'sldemo_mdlref_counter','cgpassword');

Create a modifiable protected model with a report and support for code generation with encryption.

Simulink.ModelReference.protect('sldemo_mdlref_counter','Mode',...
'CodeGeneration','Encrypt',true,'Modifiable',true,'Report',true);

Provide the password to modify the protected model.

Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Change the encryption password for simulation.

Simulink.ModelReference.modifyProtectedModel(...
'sldemo_mdlref_counter','Mode','CodeGeneration','Encrypt',true,...
'Report',true,'ChangeSimulationPassword',...
{'cgpassword','new_password'});

Add Harness Model for Protected Model

Add a harness model for an existing protected model.

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.

openExample('sldemo_mdlref_counter');
Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Create a modifiable protected model with a report and support for code generation with encryption.

Simulink.ModelReference.protect('sldemo_mdlref_counter','Mode',...
'CodeGeneration','Modifiable',true,'Report',true);

Provide the password to modify the protected model.

Simulink.ModelReference.ProtectedModel.setPasswordForModify(...
'sldemo_mdlref_counter','password');

Add a harness model for the protected model.

[harnessHandle] = Simulink.ModelReference.modifyProtectedModel(...
'sldemo_mdlref_counter','Mode','CodeGeneration','Report',true,...
'Harness',true);

Input Arguments

model — Model name

character vector | string scalar

Model name, specified as a string or character vector. It contains the name of a model or the path name of a 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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Mode','CodeGeneration','OutputFormat','Binaries','ObfuscateCode',true specifies that obfuscated code be generated for the protected model. It also specifies that only binary files and headers in the generated code be visible to users of the protected model.

File Options

Project — Option to collect dependencies in project

false (default) | true

Since R2023b

Option to collect dependencies in project, specified as true or false.

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.

• 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.

• 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.

Example: '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: 'ProjectName','myname'

Dependencies

To enable ProjectName, 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.

• true — Create a harness model for the protected model.

• false — Do not create a harness model for the protected model.

When you create a harness model for a protected model that relies on base workspace definitions, Simulink^® 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: 'Harness',true

Dependencies

• To set Harness to true, set Mode to a value that supports simulation. For example, set Mode to 'Simulation' (default).

• When you set Project to true, Harness is set to true.

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: 'Path','C:\Work'

Dependencies

The model being protected must be on the MATLAB path.

Data Types: char | string

Functionality Options

Report — Option to generate a 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 named sldemo_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: '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.

• true — Share a web view of the model that you protect.

• false — Do not 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 named sldemo_mdlref_counter, enter this command.

  Simulink.ProtectedModel.open('sldemo_mdlref_counter','webview');

Example: '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: 'Mode','Simulation'

CodeInterface — Interface for generated code

'Model reference' (default) | 'Top model'

Interface for generated code, specified as one of these values:

• Model reference — Build a model reference Simulink Coder target. The code is generated from the referenced model as part of a model hierarchy. Code generation uses this command.

  slbuild('model','ModelReferenceCoderTarget')

• Top model — Build a standalone Simulink Coder binary executable file for the specified model, using the current model configuration settings. This interface also builds model reference coder targets for the referenced models. The code is generated from the top model with the standalone code interface. Code generation uses this command.

  slbuild('model','StandaloneCoderTarget')

The value you specify determines how software-in-the-loop (SIL) and processor-in-the-loop (PIL) simulations deploy the generated code for the protected model.

• Model reference — The software deploys the generated code as part of a larger application that uses the referenced model.

• Top model — The software deploys the generated code as a standalone application.

SIL/PIL simulations can verify the protected model code.

To support code generation for a model that references the protected model, specify Model reference.

Regardless of the code interface, you can simulate the protected model in accelerator mode.

Example: '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: '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: 'Callbacks',{pmcallback_sim, pmcallback_cg}

Data Types: cell

Protection Options

ObfuscateCode — Option to obfuscate generated code

true (default) | false

Option to obfuscate generated code, specified as a Boolean value.

Example: '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: '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 (HDL Coder)

Example: '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: 'ChangeSimulationPassword',{'old_password','new_password'}

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: 'ChangeViewPassword',{'old_password','new_password'}

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: 'ChangeCodeGenerationPassword',{'old_password','new_password'}

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 postprocessing function is called.

For a protected model with a top model interface, the Simulink.ModelReference.ProtectedModel.HookInfo object cannot provide information on exported symbols.

Example: 'CustomPostProcessingHook',@(protectedMdlInf)myHook(protectedMdlInf)

Output Arguments

harnessHandle — Handle of harness model

double

Handle of harness model, returned as a double. When model protection does not create a harness model or packages the harness model in a project archive, the returned value is 0.

To create a harness model that is open after model protection, set Harness to true and Project to false (default).

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 R2014b

R2023b: Collect protected model dependencies in project

When you modify a protected model, you can automatically package it 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.