Main Content

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

  1. To register the custom edit-time check, create an sl_customization function. The sl_customization function accepts one argument, a customization manager object. To register the custom check, use the addModelAdvisorCheckFcn method. The input to this method is a handle to the check definition function. For this example, defineCheck is the check definition function. Create the sl_customization function and save it to your working folder.

    function sl_customization(cm)
cm.addModelAdvisorCheckFcn(@defineCheck);

  2. Create the check definition function. Inside the function, create three ModelAdvisor.Check objects and specify the check IDs as input arguments. Then, specify the ModelAdvisor.Check Title and CallbackHandle properties. The CallbackHandle property is the name of the class that you create to define the edit-time check. For this example, MyEditTimeChecks is the package name and PortColor, TriggerBlockPosition, and SignalLabel 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 a defineCheck function and include the code below in it. Save the defineCheck 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');

  3. Create the first check by creating a class that derives from the ModelAdvisor.EdittimeCheck abstract base class. For this example, create a class file named PortColor.m. Copy the code below into the PortColor.m file. Then, create a folder named +MyEditTimeChecks and save the PortColor.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, and fix. The PortColor method sets the CheckId and TraversalType properties. This check has a traversal type of edittimecheck.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. The blockDiscovered 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 a ModelAdvisor.ResultDetail violation object with the Type property set to the default value of SID. The fix method updates blocks that do not have correct colors.

     Check that Import Blocks Have Certain Colors Class Definition

  4. Create a second check by creating another class that derives from the ModelAdvisor.EdittimeCheck abstract base class. For this example, create a class file named TriggerBlockPosition.m. Copy the code below into the TriggerBlockPosition.m file and save it to the +MyEditTimeChecks folder.

    The TriggerBlockPosition class defines three methods: TriggerBlockPosition, blockDiscovered, and finishedTraversal. The TriggerBlockPosition method sets the CheckId and TraversalType properties. This check has a traversal type of edittimecheck.TraversalTypes.ACTIVEGRAPH because it must check other blocks in the same subsystem as the Trigger block. The blockDiscovered method checks the position of Trigger blocks within subsystems. The finishedTraversal 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 a ModelAdvisor.ResultDetail violation object with the Type property set to the default value of SID.

     Check the Position of Trigger Blocks Class Definition

  5. 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 named SignalLabel.m. Copy the code below into the SignalLabel.m file and save it to the +MyEditTimeChecks folder.

    The SignalLabel class defines two methods: SignalLabel and blockDiscovered. The SignalLabel method sets the CheckId and TraversalType properties. This check has a traversal type of edittimecheck.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, the blockDiscovered 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 the Name signal parameter has a value. Then, because the violation is on a signal, the algorithm highlights the signal by creating a violation object with the Type property value set to Signal.

     Check the Labels of Signals That Connect to Outport Blocks Class Definition

Run the Edit-Time Checks on a Model

  1. 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');

  2. Refresh the Model Advisor to update the cache with the new checks on the path.

    Advisor.Manager.refresh_customizations

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

  4. Create a custom configuration consisting of the three custom edit-time checks by deleting every folder except for the DEMO: Edit Time Checks folder.

  5. Save the configuration as my_config.json.

  6. When prompted to set this configuration as the default, click No.

  7. Close the Model Advisor Configuration Editor.

  8. Open the model by entering this command at the command prompt.

    open_system('AdvisorCustomizationExample.slx');

    Model to check for edit-time violations

  9. 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');

  10. 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');

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

  12. To view the edit-time warnings, click the blocks and signals highlighted in yellow.

    Model with edit-time warnings

    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 an auto 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.

  13. 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 function editime.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

| |

Related Topics