Programmatically Specify Block Parameters and Properties - MATLAB & Simulink (original) (raw)
Block parameters typically define model dynamics and mathematics. They also let you configure the appearance of the block. Whether a block has parameters that you can set and the nature of those parameters is specific to each block.
Block properties typically describe fundamental block characteristics and help determine when the block executes. Block properties include block annotations, callbacks that execute when a block event occurs, execution order priority, and tags that help identify the block.
To write scripts that create and modify models, use the get_param and set_param functions to query and modify block property and parameter values. For example, suppose you have a Gain block in a model named mymodel.
- This command sets the
Gainparameter of the Gain block to2.
set_param("mymodel/Gain",Gain="2") - This command orients the Gain block to the left. By default, the block faces the opposite direction.
set_param("mymodel/Gain",Orientation="left") - This command associates an
OpenFcncallback with theGain block.
set_param("mymodel/Gain",OpenFcn="my_open_cb") - This command sets the
Positionproperty of the Gain block. The block is 75 pixels wide by 25 pixels high.
set_param("mymodel/Gain",Position=[50 250 125 275])
For background information on programmatic modeling, see Programmatic Modeling Basics.
For information about how to specify paths that contain multiline names or special characters, see Specify Paths That Contain Multiline Names and Special Characters.
Block-Specific Parameters
Most block-specific parameters are documented on the page that documents the block. For example, the parameters of the Gain block are documented on the Gain block reference page. For programmatic information on a parameter, expand the corresponding parameter entry on the block reference page.
For a script that gets and sets the values of the block-specific parameters, select a block and open the Property Inspector. In the Property Inspector, click Script Reference. The script gets the parameter values with the get_param function and sets the parameter values with the set_param function. If you change the value of a parameter, the script updates to reflect the new value.
To get a list of programmatic block parameters, select a block. Then, query one of these properties with the get_param function.
DialogParameters— Block-specific parameters for an unmasked block, or mask parameters for a masked block.IntrinsicDialogParameters— Block-specific parameters for masked or unmasked blocks.ObjectParameters— Block-specific parameters and common block properties.
Some of the returned parameters and properties can be for internal use only. When a block property or parameter is undocumented, consider that parameter to be for internal use only.
Common Block Properties
A common property of Simulink® objects is the read-only Type property. For blocks, this property returns 'block'.
Each block has a block type. For some blocks, the block type is the same as the block name in the Library Browser. For example, the block type of a Gain block is Gain. For other blocks, the block type differs from the block name in the Library Browser. For example, the block type of an Add block is Sum.
- To get the block type for blocks without a mask, query the read-only
BlockTypeproperty with the get_param function. - To get the block type for blocks with a mask, query the
MaskTypeproperty with theget_paramfunction. Typically, masked blocks have aBlockTypeofSubSystem.
For information about the properties of a masked block, see Mask Parameters.
For information about block callback properties, see Block Callbacks.
These tables list additional properties common to Simulink blocks.
Common Block Properties: Names and Handles
| Property | Description | Values |
|---|---|---|
| Handle (read-only) | Numeric block handle.Assign the handle to a variable and use that variable name to specify the block. The handle applies to only the current MATLAB® session. | double number |
| InputSignalNames (read-only) | Names of input signals. | cell array |
| LineHandles (read-only) | Handles of lines connected to block.Assign a line handle to a variable and use that variable name to specify the line. The handle applies to only the current MATLAB session. | structure |
| Name | Block or signal name.To specify a signal name, use the corresponding port or line handle.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport(1); set_param(out1,Name="NewName"); To propagate the signal name, compile the model.set_param(gcs,SimulationCommand="update");Alternatively, to name an output signal of a block, useSignalNameFromLabel. | character vector |
| OutputSignalNames (read-only) | Names of output signals. | cell array |
| Parent (read-only) | Name of the system that owns the block. | character vector |
| PortHandles (read-only) | Handles of the block ports.Assign a port handle to a variable and use that variable name to specify the port. The handle applies to only the current MATLAB session.The structure has these fields: Inport — Handles of the input portsOutport — Handles of the output portsEnable — Handle of the enable portTrigger — Handle of the trigger portState — Handle of the state portLConn — Handles of the left connection ports for blocks that support physical modeling toolsRConn — Handles of the right connection ports for blocks that support physical modeling toolsIfaction — Handle of the action portReset — Handle of the reset portEvent — Handles of the subsystem reinitialize event ports | structure array |
Common Block Properties: Ports
| Property | Description | Values | |
|---|---|---|---|
| CompiledBusType (read-only) | Returns whether the port connects to a virtual bus or nonvirtual bus.To get compiled information about the port, use the corresponding port or line handle and compile the model.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport; feval(gcs,[],[],[],"compile"); bt = get_param(out1,"CompiledBusType") feval(gcs,[],[],[],"term");See Display Bus Information. | 'NOT_BUS' | 'VIRTUAL_BUS' | 'NON_VIRTUAL_BUS' |
| CompiledPortComplexSignals (read-only) | Complexity of port signals after updating diagram.To get compiled information about the ports, compile the model.feval(gcs,[],[],[],"compile"); cs = get_param(gcb,"CompiledPortComplexSignals") feval(gcs,[],[],[],"term"); | structure array | |
| CompiledPortDataTypes (read-only) | Data types of port signals after updating diagram.To get compiled information about the ports, compile the model.feval(gcs,[],[],[],"compile"); dt = get_param(gcb,"CompiledPortDataTypes") feval(gcs,[],[],[],"term"); | structure array | |
| CompiledPortDesignMin (read-only) | Design minimum of port signals after updating diagram.To get compiled information about the port, use the corresponding port or line handle and compile the model.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport; feval(gcs,[],[],[],"compile"); min = get_param(out1,"CompiledPortDesignMin") feval(gcs,[],[],[],"term"); CompiledPortDesignMin returns an empty array if the block is inactive due to any one of these conditions at compile time: Block is in an inactive path of an inline variant block.Block is an inactive choice of a Variant Subsystem block.Block is inactive due to a condition propagated from a Variant Subsystem block.Block is in a subsystem that is commented out or commented through.Block is commented out or commented through. | structure array | |
| CompiledPortDesignMax (read-only) | Design maximum of port signals at compile time.To get compiled information about the port, use the corresponding port or line handle and compile the model.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport; feval(gcs,[],[],[],"compile"); max = get_param(out1,"CompiledPortDesignMax") feval(gcs,[],[],[],"term"); CompiledPortDesignMax returns an empty array if the block is inactive due to any one of these conditions at compile time: Block is in an inactive path of an inline variant block.Block is an inactive choice of a Variant Subsystem block.Block is inactive due to a condition propagated from a Variant Subsystem block.Block is in a subsystem that is commented out or commented through.Block is commented out or commented through. | structure array | |
| CompiledPortDimensions (read-only) | Dimensions of port signals after updating diagram.To get compiled information about the port, use the corresponding port or line handle and compile the model.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport; feval(gcs,[],[],[],"compile"); d = get_param(out1,"CompiledPortDimensions") feval(gcs,[],[],[],"term"); For details, see Get Compiled Port Dimensions. | numeric array | |
| CompiledPortDimensionsMode (read-only) | Indication of whether the port signal has a variable size after updating diagram. 0 indicates the signal does not have a variable size.1 indicates the signal has a variable size.To get compiled information about the port, use the corresponding port or line handle and compile the model.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport; feval(gcs,[],[],[],"compile"); dm = get_param(out1,"CompiledPortDimensionsMode") feval(gcs,[],[],[],"term"); See Determine Whether Signal Line Has Variable Size. | double number | |
| CompiledPortFrameData (read-only) | Frame mode of port signals after updating diagram.To get compiled information about the port, use the corresponding port or line handle and compile the model.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport; feval(gcs,[],[],[],"compile"); fd = get_param(out1,"CompiledPortFrameData") feval(gcs,[],[],[],"term"); | structure array | |
| CompiledPortUnits (read-only) | Structure array of block port units after updating diagram.To get compiled information about the port, compile the model.feval(gcs,[],[],[],"compile"); units = get_param(gcb,"CompiledPortUnits") feval(gcs,[],[],[],"term"); | structure array | |
| CompiledPortWidths (read-only) | Structure of port widths after updating diagram.To get compiled information about the port, compile the model.feval(gcs,[],[],[],"compile"); units = get_param(gcb,"CompiledPortWidths") feval(gcs,[],[],[],"term"); | structure array | |
| IOSignalStrings | Block paths to objects that are connected to the Viewers and Generators Manager. The software saves these paths when the model is saved. | list | |
| PortConnectivity (read-only) | Array of structures, each of which describes one of the block input or output ports. Each port structure has these fields:Type — Port type, port number, or both. The value can be:n, where n is the number of the port for data ports'enable' if the port is an enable port'trigger' if the port is a trigger port'state' for state ports'ifaction' for action ports'LConn_#' for a left connection port where # is the port number'RConn#_' for a right connection port where # is the port number'event' for reinitialize event ports of subsystemsPosition — A two-element vector, [x _y_], that specifies the port position.SrcBlock — Handle of the block connected to this port. For output ports, the value is []. For unconnected input ports, the value is -1. The SrcBlock property is a valid source handle for Variant Subsystem blocks.SrcPort — Number of the port connected to this port, starting at zero. For both output ports and unconnected input ports, the value is [].DstBlock — Handle of the block to which this port is connected. For input ports, the value is []. For unconnected output ports, the value is a 1-by-0 empty matrix.DstPort — Number of the port to which this port is connected, starting at zero. For input ports, the value is[]. For unconnected output ports, the value is a 1-by-0 empty matrix. For Simscape™ blocks, the value is port handles. | structure array | |
| PortRotationType (read-only) | Type of port rotation used by this block. | 'default' | 'physical' | |
| Ports (read-only) | Number of each kind of port this block has.The order of the elements in the returned vector corresponds to these port types: Inport — Input portOutport — Output portEnable — Enable portTrigger — Trigger portState — State portLConn — Left connection portRConn — Right connection portIfaction — Action portReset — Reset event portEvent — Reinitialize event port | vector | |
| SignalHierarchy (read-only) | If the signal is a bus, returns the name and hierarchy of the elements in the bus.To get the signal hierarchy, use the corresponding port or line handle and compile the model.ports = get_param(gcb,"PortHandles"); out1 = ports.Outport; feval(gcs,[],[],[],"compile"); sh = get_param(out1,"SignalHierarchy") feval(gcs,[],[],[],"term"); See Display Bus Information. | values that reflect the structure of the signal |
Common Block Properties: Behavior
| Property | Description | Values | |
|---|---|---|---|
| Commented | Exclude block from simulation. | 'off' (default) | 'on' | 'through' |
| CompiledIsActive (read-only) | Specifies whether the block status is active at compile time.CompiledIsActive returnsoff if any one of these conditions is true at compile time:Block is an inactive path of an inline variant.Block is an inactive choice of a variant subsystem.Block is in a subsystem that is commented out.Block is inactive due to a condition propagated from a variant subsystem.CompiledisActive returnsoff for inactive choices and returns on for active choices of a variant subsystem. | 'off' | 'on' | |
| CompiledSampleTime (read-only) | Block sample time after updating diagram.To get the sample time, compile the model.feval(gcs,[],[],[],"compile"); ts = get_param(gcb,"CompiledSampleTime") feval(gcs,[],[],[],"term"); CompiledSampleTime returns an empty vector or cell array if the block is inactive due to any one of these conditions at compile time: Block is in an inactive path of an inline variant block with theVariant activation time parameter set toupdate diagram, update diagram analyze all choices, or code compile.Block is an inactive choice of a Variant Subsystem block with the Variant activation time parameter set toupdate diagram, update diagram analyze all choices, or code compile.Block is inactive due to a condition propagated from a Variant Subsystem block with the Variant activation time parameter set to update diagram,update diagram analyze all choices, orcode compile.Block is in a subsystem that is commented out or commented through.Block is commented out or commented through. | vector or cell array of sample time and offset time, respectively | |
| IsStateOwnerBlock (read-only) | Indicates whether the block is a supported state owner block that can be used with the State Reader and State Writer blocks. | 'off' | 'on' | |
| ExtModeLoggingSupported (read-only) | Enable a block to support uploading of signal data in external mode, for example, with a scope block. | 'off' (default) | 'on' | |
| ExtModeLoggingTrig | Enable a block to act as the trigger block for external mode signal uploading. | 'off' (default) | 'on' | |
| ExtModeUploadOption | Enable a block to upload signal data in external mode when the Select all check box on the External Signal & Triggering dialog box is not selected. A value of log indicates the block uploads signals. A value of none indicates the block does not upload signals. The value monitor is currently not in use. If the Select all check box on the External Signal & Triggering dialog box is selected, it overrides this parameter setting. | 'none' (default) | 'log' | 'monitor' |
| Selected | Status of whether or not block is selected. | 'on' (default) | 'off' | |
| StatePerturbationForJacobian | State perturbation size to use during linearization. For details, see Change Perturbation Level of Blocks Perturbed During Linearization (Simulink Control Design). | character vector | |
| Priority | Specifies the block order of execution relative to other blocks in the same model. Set by the Priority field on the General pane of the Block Properties dialog box. | '' (default) | character vector |
Common Block Properties: Appearance
| Property | Description | Values | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| BackgroundColor | Block background color. | 'black' | 'white' | 'red' | 'green' | 'blue' | 'cyan' | 'magenta' | 'yellow' | 'gray' | 'lightBlue' | 'orange' | 'darkGreen' | '[r,g,b]' | '[r,g,b,a]', where r, g, and b are the red, green, and blue values of the color in the range 0.0 to 1.0. If specified, the alpha value (a) is ignored. |
| BlockMirror | Block mirror. | 'off' (default) | 'on' | ||||||||||||
| BlockRotation | Block rotation angle.For 0 degrees rotation, the value is0. For 270 degree rotation, the value is270. | double number | ||||||||||||
| DropShadow | Display drop shadow. | 'off' (default) | 'on' | ||||||||||||
| FontAngle | Font angle. | 'auto' (default) | 'normal' | 'italic' | 'oblique' | ||||||||||
| FontName | Font name. | character array | ||||||||||||
| FontSize | Font size.A value of -1 specifies that this block inherits the font size specified by theDefaultBlockFontSize model parameter. | '-1' (default) | real | ||||||||||||
| FontWeight | Font weight. | 'auto' (default) | 'light' | 'normal' | 'demi' | 'bold' | |||||||||
| ForegroundColor | Foreground color of block icon.The value changes if it is too similar to the canvas color specified by the ScreenColor parameter. To get the actual value, use the get_param function. | 'black' | 'white' | 'red' | 'green' | 'blue' | 'cyan' | 'magenta' | 'yellow' | 'gray' | 'lightBlue' | 'orange' | 'darkGreen' | '[r,g,b]' | '[r,g,b,a]', where r, g, and b are the red, green, and blue values of the color in the range 0.0 to 1.0. If specified, the alpha value (a) is ignored. |
| HideAutomaticName | Specify whether the block name given automatically by the Simulink Editor displays in the model.For information on using this parameter, see Hide or Display Block Names. | 'on' (default) | 'off' | ||||||||||||
| NamePlacement | Position of block name. | 'normal' (default) |'alternate' | ||||||||||||
| Orientation | Direction block faces. | 'right' (default) | 'left' | 'up' | 'down' | ||||||||||
| Position | Position of block in model window.The origin is the upper-left corner of the Simulink Editor canvas before any canvas resizing. Supported coordinates are between -1073740824 and 1073740823, inclusive. Positive values are to the right of and down from the origin. Negative values are to the left of and up from the origin.To help with block alignment, the position you set can differ from the actual block position by a few pixels. To return the actual position, use the get_param function. | vector of coordinates, in pixels: [left top right bottom] | ||||||||||||
| ShowName | Display or hide block name.For information on using this parameter, see Hide or Display Block Names. | 'on' (default) | 'off' |
Common Block Properties: Metadata
| Property | Description | Values |
|---|---|---|
| AttributesFormatString | Block annotation text that corresponds to block properties. | character vector |
| BlockDescription (read-only) | Block description shown at the top of the block parameters dialog box or property inspector. | character array |
| Description | Description of block. Set by the Description field in the General pane of the Block Properties dialog box. | text and tokens |
| RTWData | User specified data, used by Simulink Coder™ software. Intended only for use with user written S-functions. For details, see S-Function RTWdata (Simulink Coder). | structure of character vectors |
| Tag | Text that appears in the block label that Simulink software generates. Set by the Tag field on the General pane of the Block Properties dialog box. | '' (default) | character vector |
| UserData | User-specified data that can have any MATLAB data type. | '[]' (default) |
| UserDataPersistent | Status of whether or not UserData will be saved in the model file. | 'off' (default) | 'on' |
Common Block Properties: Libraries
| Property | Description | Values | |||||||
|---|---|---|---|---|---|---|---|---|---|
| AncestorBlock | Name of the library block that the block is linked to for blocks with a disabled link. | character vector | |||||||
| BlockKeywords | Associates one or more keywords with a custom library block. | character vector | string scalar | string array | ||||||
| LibraryVersion | For a linked block, the initial value of this property is theModelVersion of the library at the time the link was created. The value updates with increments in the model version of the library. | '1.1' (default) | character vector | |||||||
| LinkData | Array of details about changes to the blocks inside the link that differ between a parameterized link and its library, listing the block names and parameter values. Use [] to reset to deparameterized, for example,set_param(gcb,'linkData',[]). | cell array | |||||||
| LinkStatus | Link status of block. Updates out-of-date linked blocks when queried using the get_param function.See Control Linked Blocks Programmatically. | 'none' | 'resolved' | 'unresolved' | 'implicit' | 'inactive' | 'restore' | 'propagate' | 'propagateHierarchy' | 'restoreHierarchy' |
| ReferenceBlock | Name of the library block to which this block links. | '' (default) | character vector | |||||||
| StaticLinkStatus (read-only) | Link status of block. Does not update out-of-date linked blocks when queried using the get_param function. See alsoLinkStatus. | 'none' | 'resolved' | 'unresolved' | 'implicit' | 'inactive' | 'restore' | 'propagate' | 'propagateHierarchy' | 'restoreHierarchy' |
Some common block properties are for internal use only. For example, these properties are for internal use only:
DataTypeOverride_CompiledDiagnosticsHiliteAncestorsIOTypeMinMaxOverflowLogging_CompiledModelParamTableInfoRequirementInfo
Maximum Size Limits for Block Parameter Values
For block parameters that accept array values, the number of elements in the array cannot exceed what int_T can represent. This limitation applies to both simulation and Simulink Coder code generation.
The maximum number of characters that a parameter edit field can contain is 49,000.