Create Custom Blocks Using MATLAB System Block and System objects - MATLAB & Simulink (original) (raw)

This topic introduces the MATLAB System block, explains how to use the block to implement your System object™, and describes how to configure the block for your Simulink® model.

System Objects

System objects let you implement algorithms using the MATLAB® language. The MATLAB System block enables you to use System objects in Simulink.

Before you use a MATLAB System block, you must have a System object to associate with the MATLAB System block. A System object is a specialized kind of MATLAB class. System objects are designed specifically for implementing and simulating dynamic systems with inputs that change over time. For more information on creating System objects, see Customize System Objects for Simulink.

Why Use the MATLAB System Block?

The MATLAB System block lets you:

• Integrate your System objects with Simulink
• Share the same System object in MATLAB and Simulink
• Unit test your algorithm in MATLAB before using it in Simulink
• Customize dialog box customization
• Simulate efficiently with better initialization
• Handle states
• Customize block icons with port labels
• Access two simulation modes

System objects exist in other MATLAB products. MATLAB System block supports only the System objects written in the MATLAB language. In addition, if a System object has a corresponding Simulink block, you cannot implement a MATLAB System block for it.

Note

To use your System object in the Simulink environment with MATLAB System block, it must have a constructor that you can call with no arguments. By default, the System object constructor has this capability and you do not need to define your own constructor. However, if you create your own System object constructor, you must be able to call it with no arguments.

Choose the Right Block Type to Include MATLAB Algorithms in Simulink

There are several mechanisms for including MATLAB algorithms in Simulink, such as:

• MATLAB System block
• MATLAB Function block
• Interpreted MATLAB Function block
• Level-2 MATLAB S-Function block

For help on choosing the right block, see Comparison of Custom Block Functionality.

Implement a System object in Simulink Using MATLAB System Block

To implement your System object with a custom block behavior in Simulink use the MATLAB System Block and follow these steps:

1. Create a new model and add the MATLAB System block to your model.
   
2. In the block dialog box, from the New list, selectBasic, Advanced, or Simulink Extension if you want to create a new System object from a template. Modify the template according to your needs and save the System object.
3. Enter the full path name for the System object in the System object name. Click the list arrow. If valid System objects exist in the current folder, the names appear in the list.
   The MATLAB System block icon and port labels update to those of the corresponding System object. For example, suppose you selected a System object named lmsSysObj in your current folder. The block updates as shown in the figure:
   
4. Double-click the block. The MATLAB System block dialog box reflects the System object parameters. The dialog box includes a Source code if the System object uses MATLAB language.
   It does not appear if you have:
   • Converted the System object to P-code.
   • Overridden the default behavior using the getHeaderImpl method.
     
5. Click Source code and observe that the public and active properties in the System object appear in the MATLAB System block dialog box as block parameters.
6. Select how you want the model to simulate the block using theSimulate using parameter. (This parameter appears at the bottom of each MATLAB System block if there is only one tab, or the bottom of the first of multiple tabs.)

Note

After you associate the block with a System object class name, you cannot assign a new System object using the same MATLAB System block dialog box. Instead, right-click the MATLAB System block, selectBlock Parameters (MATLABSystem) and enter a new class name in System object name.

To implement a block with another System object, right-click the MATLAB System block and selectBlock Parameters (MATLABSystem). Then, use the block dialog box to identify a new class name in System object name. For more information, see Implement a System object in Simulink Using MATLAB System Block.

Change Block Icon and Port Labels

You can customize the MATLAB System icon, port labels, and dialog box using the Mask Editor or by adding specific methods to your System object.

• To design a MATLAB System icon and dialog box, use the Mask Editor (Since R2023b). You can also migrate existing mask customizations to the Mask Editor. This capability eliminates the need to develop or maintain methods in a System object file. For more information, see Customize MATLAB System Icon and Dialog Box Using Mask Editor.
• Alternatively, you can add methods to your System object to change the block icon appearance and the block dialog box:
  • When you change the icon appearance and port labels of your block:
    * To define the icons, implement the getIconImpl method.
    * To define the port labels, implement the getInputNamesImpl method to change the input and getOutputNamesImpl method to change the output port labels.

  For an example, see Customize MATLAB System Block Appearance.
  If you do not implement these methods, by default the System object uses the input and output port names from thestepImpl method. If you are using nondirect feedthrough, by default the System object uses the input names from updateImpl and the output port names from outputImpl.

  • To change the MATLAB System block dialog box, implement the getPropertyGroupsImpl method in the System object code of the MATLAB System block. Inside the method, implement these classes.

Change the MATLAB System Block Icon to an Image

You can change the image of MATLAB System block in MATLAB Editor. For a list of accepted image files, see image. To use an existing image file for the MATLAB System block:

1. Double-click your MATLAB System block.
2. In the block dialog box, click the Source code. The MATLAB Editor that contains the System object code opens.
3. In the MATLAB Editor, from the System Block drop-down list, select Add Image Icon.
4. In the Add image icon dialog box, clickBrowse to select an image of your choice.
5. Click OK to insert the corresponding code for the getIconImpl method in your System object.

For more information, see Customize System Block Appearance Programmatically.

Specify Sample Time for MATLAB System Block

The sample time of a block is a parameter that indicates when the block produces an output, and eventually updates its internal state. To specify sample time for aMATLAB System block, implement the getSampleTimeImpl method with a call to createSampleTime method. To query the MATLAB System block for current sample time and simulation time, use the getSampleTime and getCurrentTime methods. For more information, see Specify Sample Time for MATLAB System Block System Objects.

• To specify a discrete sample time, in the createSampleTime method, set 'Type' to 'Discrete' and set the'SampleTime' property.
• To specify an inherited sample time, in the createSampleTime, set 'Type' to 'Inherited'. When using an inherited sample time, you can alter or error out on specific sample times by specifying the 'AlternatePropagation' or 'ErrorOnPropagation' Name-Value pair.
• To specify the fixed-in-minor-step sample time, in the createSampleTime, set 'Type' to 'Fixed In Minor Step'.
• To configure a block to specify controllable sample time with a resolution Tbase, where Tbase is the smallest allowable time interval between block executions, in the createSampleTime method, set the 'Type' property to 'Controllable' and set the 'TickTime' property to Tbase. You can set the n in your MATLAB System block using setNumTicksUntilNextHit. A block using controllable sample time can be dynamically set to execute at n multiples of Tbase, then the block's next execution is

For more information, see Types of Sample Time. To see an example on how to control the sample time of the MATLAB System block using System object methods, see Specify Sample Time for MATLAB System Block System Objects.

Block Simulation Modes

You can use MATLAB System blocks in Simulink models for simulation via interpreted execution or code generation.

• With interpreted execution, the model simulates the block using the MATLAB execution engine.
  Note
  With interpreted execution, if you set the parameter to On orUse division for reciprocals of integers only in the Configuration Parameters dialog box, you might get unoptimized numeric results. These unoptimized numeric results are because MATLAB code does not support this parameter.
• With code generation, the model simulates the block using the generated code (requires the use of the subset of MATLAB code supported for code generation). For a list of supported functions, see Functions and Objects Supported for C/C++ Code Generation.

Interpreted Execution vs. Code Generation

Implementing a MATLAB System block with a valid System object class name enables the Simulate using parameter. This parameter appears at the bottom of the MATLAB System block dialog box if there is only one tab, or the bottom of the first of multiple tabs. Use the Simulate using parameter to control how the block simulates. This table describes how to choose the right value for your purpose.

To take advantage of faster performance, consider using propagation methods in your System object. For more information, see Add and Implement Propagation Methods.

Note

If your Simulink model is set up to simulate in Normal mode and if you useMATLAB System block via code generation, individualMATLAB System blocks can take advantage of acceleration via code generation. If the Simulink model is set up to simulate in accelerator mode or any of the other target modes, MATLAB System block's Simulate using parameter does not have any effect. However, there is one exception, if the model is set up to simulate in accelerator mode and you use MATLAB System block with interpreted execution mode, the block will run in interpreted execution mode.

Simulation Using Code Generation

Simulating the MATLAB System block using code generation requires that you have a compatible compiler installed in your system. To see a list of supported compilers, open Supported and Compatible Compilers, click the tab that corresponds to your operating system, find the Simulink Product Family table, and go to the **For Model Referencing, Accelerator mode, Rapid Accelerator mode, and MATLAB Function blocks column.

A model can have multiple copies of the same MATLAB System block. Blocks are considered the same if they:

• Use the same System object.
• Have inputs and tunable parameters that have identical signals, data types, and complexities.
• Have nontunable parameters that have the same value.

When the model has multiple copies of the same block, the software does not regenerate the code for each block. The model reuses the code from the first time code was generated for the block.

Default Input Signal Attributes of MATLAB System Block

If a MATLAB System block has one or more inputs that are not connected to another block’s output port or connected to a port that has underspecified attributes, the default input signal attributes for the unspecified attributes are:

Use Nonvirtual Buses with MATLAB System Block

The MATLAB System block supports nonvirtual buses as input and output signals. The corresponding System object input or output must be a MATLAB structure whose fields match those defined by the nonvirtual bus. If the System object output is a MATLAB structure, it must define propagator methods. In addition, the getOutputDataTypeImpl method must return the name of the corresponding bus object. This bus object must exist in the base workspace or a data dictionary linked to the model. For an example, see Using Buses with MATLAB System Blocks.

Note

If the output is the same bus type as the input, do not use the propagatedInputDataType method to obtain the name of the bus object. Instead, you must return the name of the bus object directly.

MATLAB System Block Limitations

These capabilities are not supported.

MATLAB System Block and System Objects Examples

For examples of MATLAB System and System objects, see: