Define Edit-Time Checks to Comply with Conditions that You Specify with the Model Advisor
In this example, you create three custom edit-time checks that check for compliance with certain software design standards. Custom edit-time checks help you catch issues earlier in the model design review process, but these checks also report issues in the Model Advisor.
The first check checks that Inport and Outport blocks have certain colors depending on their output data types.
The second check checks whether a Trigger block is higher than other blocks in a subsystem. This check must check edited blocks and other blocks in the same subsystem as the Trigger block.
The third check checks whether signals that connect to Outport blocks have labels.
Register and Define the Custom Edit-Time Checks
To register the custom edit-time check, create an
sl_customization
function. Thesl_customization
function accepts one argument, a customization manager object. To register the custom check, use theaddModelAdvisorCheckFcn
method. The input to this method is a handle to the check definition function. For this example,defineCheck
is the check definition function. Create thesl_customization
function and save it to your working folder.function sl_customization(cm) cm.addModelAdvisorCheckFcn(@defineCheck);
Create the check definition function. Inside the function, create three
ModelAdvisor.Check
objects and specify the check IDs as input arguments. Then, specify theModelAdvisor.Check
Title
andCallbackHandle
properties. TheCallbackHandle
property is the name of the class that you create to define the edit-time check. For this example,MyEditTimeChecks
is the package name andPortColor
,TriggerBlockPosition
, andSignalLabel
are the class names. Then, publish the checks to a new folder in the Model Advisor. For this example, the folder name is DEMO: Edit Time Checks. For this example, create adefineCheck
function and include the code below in it. Save thedefineCheck
function to your working folder.function defineCheck %% Check the background color of Inport and Outport blocks. rec = ModelAdvisor.Check("advisor.edittimecheck.PortColor"); rec.Title = 'Check color of Inport and Outport blocks'; rec.CallbackHandle = 'MyEditTimeChecks.PortColor'; mdladvRoot = ModelAdvisor.Root; mdladvRoot.publish(rec,'DEMO: Edit Time Checks'); %% Check that determines whether Trigger block is the top-most block in a subsystem. rec= ModelAdvisor.Check("advisor.edittimecheck.TriggerBlock"); rec.Title = 'Check that Trigger block position is higher than other blocks'; rec.CallbackHandle = 'MyEditTimeChecks.TriggerBlockPosition'; mdladvRoot.publish(rec,'DEMO: Edit Time Checks'); %% Check that determines whether signals with SignalPropagation 'on' have labels. rec = ModelAdvisor.Check("advisor.edittimecheck.SignalLabel"); rec.Title = 'Check that signals have labels if they are to propagate those labels'; rec.CallbackHandle = 'MyEditTimeChecks.SignalLabels'; mdladvRoot.publish(rec,'DEMO: Edit Time Checks');
Create the first check by creating a class that derives from the
ModelAdvisor.EdittimeCheck
abstract base class. For this example, create a class file namedPortColor.m
. Copy the code below into thePortColor.m
file. Then, create a folder named+MyEditTimeChecks
and save thePortColor.m
file in that folder. Classes must be in a folder that has the same name as their package name.The
PortColor
class defines three methods:PortColor
,blockDiscovered
, andfix
. ThePortColor
method sets theCheckId
andTraversalType
properties. This check has a traversal type ofedittimecheck.TraversalTypes.BLKITER
because the check must check newly added and edited blocks, but it does not have to check for affected blocks in the same subsystem or model as the edited or newly added blocks. TheblockDiscovered
method contains an algorithm that checks the color of Inport and Outport blocks. Then, because the violation is on a block, the algorithm highlights a violating block by creating aModelAdvisor.ResultDetail
violation object with theType
property set to the default value ofSID
. Thefix
method updates blocks that do not have correct colors.Check that Import Blocks Have Certain Colors Class Definition
Create a second check by creating another class that derives from the
ModelAdvisor.EdittimeCheck
abstract base class. For this example, create a class file namedTriggerBlockPosition.m
. Copy the code below into theTriggerBlockPosition.m
file and save it to the+MyEditTimeChecks
folder.The
TriggerBlockPosition
class defines three methods:TriggerBlockPosition
,blockDiscovered
, andfinishedTraversal
. TheTriggerBlockPosition
method sets theCheckId
andTraversalType
properties. This check has a traversal type ofedittimecheck.TraversalTypes.ACTIVEGRAPH
because it must check other blocks in the same subsystem as the Trigger block. TheblockDiscovered
method checks the position of Trigger blocks within subsystems. ThefinishedTraversal
method checks whether the position of these Trigger blocks are higher than other blocks in a subsystem. Then, because the violation is on a block, the algorithm highlights a violating block by creating aModelAdvisor.ResultDetail
violation object with theType
property set to the default value ofSID
.Create a third and final check by creating another class that derives from the
ModelAdvisor.EdittimeCheck
abstract base class. For this example, create a class file namedSignalLabel.m
. Copy the code below into theSignalLabel.m
file and save it to the+MyEditTimeChecks
folder.The
SignalLabel
class defines two methods:SignalLabel
andblockDiscovered
. TheSignalLabel
method sets theCheckId
andTraversalType
properties. This check has a traversal type ofedittimecheck.TraversalTypes.BLKITER
because the check must check newly added and edited blocks, but it does not have to check for affected blocks in the same subsystem or model as the edited or newly added blocks. Because this check is for signals, theblockDiscovered
method must use the parameters on the line handles,LineHandles
, of blocks to find signals with violations. Specifically, for signals that connect to Outport blocks, this algorithm checks whether theName
signal parameter has a value. Then, because the violation is on a signal, the algorithm highlights the signal by creating a violation object with theType
property value set toSignal
.Check the Labels of Signals That Connect to Outport Blocks Class Definition
Run the Edit-Time Checks on a Model
To use the checks, copy the
AdvisorCustomizationExample.slx
model to your current working folder.copyfile(fullfile(matlabroot,'examples','slcheck','main',... 'AdvisorCustomizationExample.slx'),'AdvisorCustomizationExample.slx','f');
Refresh the Model Advisor to update the cache with the new checks on the path.
Advisor.Manager.refresh_customizations
Open the Model Advisor Configuration Editor by entering this command at the command prompt:
Simulink.ModelAdvisor.openConfigUI;
If a model is open, you can also open the editor by clicking the Modeling tab and selecting Model Advisor > Configuration Editor.
Create a custom configuration consisting of the three custom edit-time checks by deleting every folder except for the DEMO: Edit Time Checks folder.
Save the configuration as
my_config.json
.When prompted to set this configuration as the default, click No.
Close the Model Advisor Configuration Editor.
Open the model by entering this command at the command prompt.
open_system('AdvisorCustomizationExample.slx');
Set the custom configuration to the
my_config.json
file by clicking the Modeling tab and selecting Model Advisor > Edit-Time Checks. In the Configuration Parameters dialog box, specify the path to the configuration file in the Model Advisor configuration file parameter. Alternatively, enter this command at the command prompt:ModelAdvisor.setModelConfiguration('AdvisorCustomizationExample', 'my_config.json');
Turn on edit-time checking by clicking the Modeling tab and selecting Model Advisor > Edit-Time Checks. In the Configuration Parameters dialog box, select the Edit-Time Checks parameter. Alternatively, you can enter this command at the command prompt:
edittime.setAdvisorChecking('AdvisorCustomizationExample','on');
Open the Model Advisor by clicking the Modeling tab and selecting Model Advisor. Observe that the three edit-time checks are the only ones in the Model Advisor. Close the Model Advisor.
To view the edit-time warnings, click the blocks and signals highlighted in yellow.
At the top level of the model, the two Inport blocks have an output data type of
int32
. They produce edit-time warnings because they should be cyan. The Outport block does not produce a violation because it has anauto
data type and is white.In the Amplifier subsystem, the Inport and Outport blocks do not produce edit-time warnings because they have a data type of
auto
and are white. The Trigger block does not produce an edit-time warning because it is the top-most block in the model. If you move the Trigger block below another block, the Trigger block has an edit-time warning.The signal connecting to the Outport block produces a warning because it does not have a label.
To fix the edit-time warnings for the two Inport blocks, in the edit-time check warning window, click Fix.
Performance Considerations for Custom Edit-Time Checks
To help prevent custom edit-time checks from negatively impacting performance as
you edit your model, the Model Advisor automatically disables custom edit-time
checks if, in the current MATLAB® session, the check takes longer than 500
milliseconds to execute in at least three different
Simulink® models.
If the Model Advisor disables a custom edit-time check, you will see a warning on the Simulink canvas. You can re-enable the edit-time check by either:
Clicking the hyperlink text in the warning.
Passing the check identifier,
checkID
, to the functioneditime.enableCheck
:edittime.enableCheck(
checkID
)
To prevent a custom edit-time check from being disabled, author the check so that
the check executes in less than 500
milliseconds on your models.
See Also
ModelAdvisor.EdittimeCheck
| ModelAdvisor.Check
| ModelAdvisor.ResultDetail