Use Simulink.Signal
Objects to Specify and Control Signal
Attributes
A Simulink.Signal
object enables you to assign or validate the attributes
of a signal or discrete state, such as its data type, numeric type, dimensions, and so
on. For programmatic and reference information, see Simulink.Signal
.
Using Signal Objects to Assign or Validate Signal Attributes
This section describes how you can use signal objects to assign or validate signal attributes. The same techniques work with discrete states also. To use a signal object to assign or validate signal attribute values:
Create a
Simulink.Signal
object that has the same name as the signal to which you want to assign attributes or whose attributes you want to validate.Open the Model Explorer.
In the Model Hierarchy pane, select either the Base workspace or Model workspace node, depending on the context you want for the signal object. If you create the signal object in a model workspace, you must set the Storage class parameter to
Auto
.Select Add > Simulink Signal.
Set the properties of the object that correspond to the attributes left unspecified by the signal source, or that correspond to the attributes you want to validate. See Property Dialog Box for details.
Enable explicit or implicit signal resolution:
Explicit resolution: In the Signal Properties dialog box for the signal, enable Signal name must resolve to Simulink signal object. This is the preferred technique. See Explicit and Implicit Symbol Resolution for more information.
When you use this technique, set Configuration Parameters > Diagnostics > Data Validity > Signal resolution to a value other than
None
. To use only explicit resolution (a best practice), set the parameter toExplicit only
.Implicit resolution: Set the Configuration Parameters > Diagnostics > Data Validity > Signal resolution option for the model to
Explicit and implicit
orExplicit and warn implicit
. Explicit resolution is the preferred technique.
Assign the signal object to a workspace variable.
Associate the signal object with the source signal.
Give the signal the same name as the workspace variable that references the signal object.
You can use a variety of techniques to associate a signal object with a signal. For examples, see Use Signal Objects to Initialize Signals and Discrete States, Using Signal Objects to Tune Initial Values, and Organize Parameter Data into a Structure by Using Struct Storage Class (Embedded Coder).
Validation
The result when a signal does not match a signal object can depend on several factors. Simulink® software can validate a signal property when you update the diagram, while you run a simulation, or both. When and how validation occurs can depend on internal rules that are subject to change, and sometimes on configuration parameter settings.
Not all signal validation compares signal source attributes with signal object properties. For example, if you specify Minimum and Maximum signal values using a signal object, the signal source must specify the same values as the signal object (or inherit the values from the object) but such validation relates only to agreement between the source and the object, not to enforcement of the minimum and maximum values during simulation.
If the value of Configuration Parameters > Diagnostics
> Data Validity > Simulation range checking is
none
(the default), Simulink does not enforce any minimum and maximum signal values during
simulation, even though a signal object provided or validated them. To enforce
minimum and maximum signal values during simulation, set Simulation range checking to warning
or
error
. See Specify Signal Ranges and Model Configuration Parameters: Data Validity Diagnostics for
more information.
Multiple Signal Objects
You can associate a given signal object with more than one
signal if the storage class of the signal object is Auto
or
Reusable
. If the storage class is Auto
and
you clear optimizations such as Signal storage reuse so that
the generated code allocates memory for all of the associated signals, the signals
each appear as a uniquely named field of the global structure that contains signal
and state data. If the storage class of the object is other than
Auto
or Reusable
, you can associate the
signal object with no more than one signal.
You can associate a given signal with no more than one signal object. The signal can refer to the signal object more than once, but every reference must resolve to exactly the same signal object. Referencing two different signal objects that have exactly the same properties causes a compile-time error.
A compile-time error occurs if a model associates more than one signal object with any signal. To prevent the error, decide which object you want the signal to use, then delete or reconfigure all references to any other signal objects, so that all remaining references resolve to the chosen signal object. See Highlight Signal Sources and Destinations for a description of techniques that you can use to trace the full extent of a signal.
Signal Specification Block: An Alternative to Simulink.Signal
You can use a Signal Specification block rather
than a Simulink.Signal
object to assign properties left unspecified
by a signal source. Each technique has advantages and disadvantages:
Using a signal object simplifies the model and allows you to change signal property values without editing the model, but does not show signal property values directly in the block diagram.
Using a Signal Specification block displays signal property values directly in the block diagram, but complicates the model and requires editing it to change signal property values.
The following two models illustrate the respective advantages of the two ways of assigning attributes to a signal.
In the first example, the signal object named Sig1
specifies
the sample time and data type of the signal emitted by input port
In1
.
To determine the properties of the Sig1
signal, you can view
the signal object in the Model Explorer. In this model, the sample time is
-1
and the data type is auto
.
Using a signal object to specify the sample time and data type properties of
signal Sig1
allows you to change the sample time or data type
without having to edit the model. For example, you could use the Model Explorer, the
MATLAB® command line, or a MATLAB program to change these properties.
The second example uses a Signal Specification block specifies the sample time and
data type of the signal emitted by input port In2
. The Signal
Specification block displays the data type and signal sample time properties right
in the diagram, which in this case are uint8
and
4
, respectively.
Bus Support
Using Bus Objects as the Data Type
Simulink.Signal
supports nonvirtual buses as the output data type.
If you set the Data type of the signal object to be a bus object, then you cannot associate the signal object with a non-bus signal.
Using Structures for the Initial Value
If you use a bus object as the data type, set Initial
value to 0
or a MATLAB structure that matches the bus object.
The structure you specify must contain a value for every element of the bus represented by the bus object.
You can use the Simulink.Bus.createMATLABStruct
to create a full structure that
corresponds to a bus.
You can use Simulink.Bus.createObject
to
create a bus object from a MATLAB structure.
Property Dialog Box
For examples and programmatic information about Simulink.Signal
, see
Simulink.Signal
.
- Data type
Data type of the signal. The default entry,
auto
, specifies that Simulink should determine the data type. Use the adjacent dropdown list to specify built-in data types (for example,uint8
) or a data type such as'half'
. To specify a custom data type, enter a MATLAB expression that specifies the type, (for example, a base workspace variable that references aSimulink.NumericType
object).To specify a bus object as the data type for the signal object, use the
Bus: <object_name>
option. See Bus Support for details about what you need to do if you specify a bus object as the data type.Click the Show data type assistant button
to display the Data Type Assistant, which helps you set the Data type parameter. (See Specify Data Types Using Data Type Assistant.)
- Complexity
Numeric type of the signal. Valid values are
auto
(determined by Simulink),real
, orcomplex
.- Dimensions
Dimensions of this signal. Valid values are
-1
(the default) specifying any dimensions,N
specifying a vector signal of sizeN
, or[M N]
specifying anMxN
matrix signal.- Dimensions mode
Dimensions mode of this signal. From the drop-down list, select
Auto — Allows variable-size and fixed-size signals.
Fixed — Allows only fixed-size signals. Does not allow variable-size signals.
Variable — Allows only variable-size signals.
- Sample time
Rate at which the value of this signal should be computed. See Specify Sample Time for details.
- Minimum
Minimum value that the signal should have. The default value is
[]
(unspecified). Specify a finite, real, double, scalar value.Note
If you specify a bus object as the data type for a signal, do not set the minimum value for bus data on the signal property dialog box. Simulink ignores this setting. Instead, set the minimum values for bus elements of the bus object specified as the data type. For information on the Minimum property of a bus element, see
Simulink.BusElement
.Simulink uses this value in the following ways:
When updating the diagram or starting a simulation, Simulink generates an error if the signal's initial value is less than the minimum value or if the minimum value is outside the range for the data type of the signal.
When you enable the Simulation range checking diagnostic, Simulink alerts you during simulation if the signal value is less than the minimum value (see Simulation range checking).
- Maximum
Maximum value that the signal should have. The default value is
[]
(unspecified). Specify a finite, real, double, scalar value.Note
If you specify a bus object as the data type for a signal, do not set the maximum value for bus data on the signal property dialog box. Simulink ignores this setting. Instead, set the maximum values for bus elements of the bus object specified as the data type. For information on the Maximum property of a bus element, see
Simulink.BusElement
.Simulink uses this value in the following ways:
When updating the diagram or starting a simulation, Simulink generates an error if the initial value of the signal is greater than the maximum value or if the maximum value is outside the range of the data type of the signal.
When you enable the Simulation range checking diagnostic, Simulink alerts you during simulation if the signal value is greater than the maximum value (see Simulation range checking).
- Stored Integer Minimum
For signal objects with a fixed-point data type, the minimum value that the signal should have, specified as a stored integer value. The value is derived from the real-world value Minimum. This property is available only in the property dialog box.
- Stored Integer Maximum
For signal objects with a fixed-point data type, the maximum value that the signal should have, specified as a stored integer value. The value is derived from the real-world value Maximum. This property is available only in the property dialog box.
- Initial value
Signal or state value before a simulation takes its first time step. You can specify any MATLAB expression, including the name of a workspace variable, that evaluates to a numeric scalar value or array.
You can use the MATLAB command prompt to provide an initial value for a signal. Even if you use a number, specify the initial value as a character vector.
mySigObject.InitialValue='5.3';
mySigObject.InitialValue = 'myNumericVariable';
To specify an initial value for a signal that uses a numeric data type other than
double
, cast the initial value to the signal data type. For example, you can specifysingle(73.3)
to use73.3
as the initial value for a signal of data typesingle
.If you use a bus object as the data type for the signal object, set Initial value to a character vector containing either
0
or a MATLAB structure that matches the bus object. See Bus Support for details.If the initial value evaluates to a MATLAB structure, then in the Configuration Parameters dialog box, set Underspecified initialization detection to
simplified
.If necessary, Simulink converts the initial value to ensure type, complexity, and dimension consistency with the corresponding block parameter value. If you specify an invalid value or expression, an error message appears when you update the model. Also, Simulink performs range checking of the initial value. The software alerts you when the initial value of the signal lies outside a range that corresponds to its specified minimum and maximum values and data type.
Classic initialization mode: In this mode, initial value settings for signal objects that represent the following signals and states override the corresponding block parameter initial values if undefined (specified as
[]
):Output signals of conditionally executed subsystems and Merge blocks
Block states
Simplified initialization mode: In this mode, initial values of signal objects associated with the following blocks are ignored. The initial values of the corresponding blocks are used instead.
Outport blocks of conditionally executed subsystems
Merge blocks
- Unit
Physical unit in which the value of this signal is expressed, (for example, inches). To specify a unit, begin typing in the text box. As you type, the parameter displays potential matching units. For more information, see Unit Specification in Simulink Models.
- Storage class
Storage class of this signal. For more information, see C Code Generation Configuration for Model Interface Elements (Simulink Coder) and Organize Parameter Data into a Structure by Using Struct Storage Class (Embedded Coder).
If you create the signal object in a model workspace, you must set the object storage class to
Auto
.- Identifier
Alternate name for this signal. Simulink ignores this setting. This property is used for code generation.
- Alignment
Data alignment boundary, specified in number of bytes. The starting memory address for the data allocated for the signal will be a multiple of the Alignment setting. The default value is
-1
, which specifies that the code generator should determine an optimal alignment based on usage. Otherwise, specify a positive integer that is a power of 2, not exceeding 128. This field is intended for use by Simulink Coder™ software. See Data Alignment for Code Replacement (Embedded Coder). Simulink software ignores this setting.- Description
Description of this signal. This field is intended for use in documenting this signal. This property is used by the Simulink Report Generator and for code generation.
If you have an Embedded Coder® license, you can add the signal description as a comment for the variable declaration in generated code.
Specify a storage class for the signal object other than
Auto
.On the Code Generation > Comments pane of the Model Configuration Parameters dialog box, select the model configuration parameter Simulink data object descriptions. For more information, see Simulink data object descriptions (Embedded Coder).