Specify Bus Properties with Bus Objects
Bus objects provide a reusable specification for a bus that the software can use to validate the properties of the bus and its elements. Multiple blocks and model components can specify the same bus object. Bus objects are optional for virtual buses, but required for nonvirtual buses.
A Simulink.Bus
object specifies only the
architectural properties of a bus, as distinct from the values of the signals it contains. For
example, a bus object can specify the number of elements in a bus, the order of those
elements, whether and how elements are nested, and the data types of constituent signals; but
not the signal values.
A bus object is analogous to a structure definition in C: it defines the members of the bus, but does not create the bus. A bus object is also similar to a cable connector. The connector defines the pins and their configuration and controls what types of wires can connect to it. Similarly, a bus object defines the configuration and properties of the signals that the associated bus must have.
Determine Whether to Use Bus Objects
You can specify bus properties individually or with a bus object. Depending on your modeling requirement, the way you define the bus properties can differ.
Modeling Requirement | Specification Source |
---|---|
Assign or validate the hierarchy and properties of an input bus at a subsystem or model interface. | Use an In Bus Element block or
|
Assign or validate the hierarchy and properties of an output bus at a subsystem or model interface. | Use an Out Bus Element block or
|
Assign or validate the hierarchy and properties of a bus across multiple blocks or model components. | Use a |
Trace the correspondence between the model and generated code for a bus. | Use a nonvirtual bus defined by a The generated code for a nonvirtual bus produces a structure. Nonvirtual buses can result in multiple copies of some buses. |
Design rigid interface specifications for Simscape™ conserving connections and lock down connection names and types. | Use a For information about
|
When the ports of model components directly connect to each other, specify the same or an equivalent bus object for the blocks that represent those ports. By specifying a bus object with the same hierarchy and properties at both sides of the interface, you enforce consistency at the interface between the two components. For more information about interface design, see Define Interfaces of Model Components.
You must use Simulink.Bus
objects for these modeling
configurations:
Nonvirtual buses
Stateflow® charts with bus input or output
S-functions or Legacy Code Tool interfaces with external code
Blocks that require a bus object to define bus input or output. For more information, see Bus-Capable Blocks.
To enforce strong data typing when you create a bus with a Bus Creator block:
Set the Output data type block parameter to a
Simulink.Bus
object.Clear the Use names from inputs instead of from bus object block parameter.
Set the Element name mismatch configuration parameter to
error
. This configuration parameter checks that input element names match the corresponding names in the bus object.
When you specify a bus object as the data type of a block or object, the properties specified by the bus object typically override the properties specified by the block or object.
For example, suppose a Signal Specification block has these settings:
Unit set to
ft/s
Data type set to a
Simulink.Bus
object with elements that specify a unit ofm/s
The Signal Specification block uses m/s
as
the unit for the bus elements.
Bus objects appear in the generated code only when they define nonvirtual buses. For bus objects that define virtual buses, the properties that the bus objects specify appear in the generated code instead of the bus object.
Create Simulink Bus Objects
To create or edit Simulink.Bus
objects interactively, use the Type Editor or
Model Explorer.
The Type Editor displays the bus hierarchy, provides capabilities such as import and export,
and lets you update other types, such as Simulink.ValueType
objects. The
Model Explorer lets you update data objects such as Simulink.Parameter
objects. Bus objects created with either tool are initially stored in the base workspace or
a data dictionary.
For an example that creates a bus object using the Type Editor, see Define Multilevel Bus Hierarchy Using Type Editor.
To create or edit bus objects programmatically, see Programmatically Create Simulink Bus Objects. Bus objects created programmatically are initially stored in the base workspace, a data dictionary, or a function.
Specify Simulink Bus Objects
After you create a Simulink.Bus
object and specify its attributes, you
can associate it with any block that needs to use the bus definition that the object
provides.
To associate a block with a bus, set the Output data type or
Data type block parameter to Bus: <object
name>
and replace <object name>
with the
Simulink.Bus
object name.
You can specify the bus object as the data type of a block either before or after
defining the bus object. However, before you simulate the model, the
Simulink.Bus
object must be defined and loaded.
During model development, you can modify buses to match bus objects or modify bus objects to match buses. If you do not want to change the bus object, you can:
Create a bus object that matches the changes to the bus and use the new bus object for the blocks that the changed bus connects to.
Revert the bus changes so that the bus continues to match the associated bus object.
Save Simulink Bus Objects
You can save Simulink.Bus
objects to these locations:
Data dictionary
Function
MAT-file
Database or other external files
If you do not save bus objects, then when you reopen a model that uses the bus objects, you need to recreate the bus objects.
Choose where to store bus objects based on your modeling requirements.
Modeling Requirement | Location |
---|---|
Store data for large models and model hierarchies. | Use a data dictionary. When you save to a data dictionary
from the base workspace, you get all the variables used by the model, not just
the To save changes to a data dictionary, use the Type Editor or Model Explorer. To update a model to use a data dictionary, see Migrate Models to Use Simulink Data Dictionary. |
Use MATLAB® for traceability and model differencing. | Use a script or function. To create a script or function
that defines one or more |
Save and load bus objects faster. | Use a MAT file. To create a MAT file that contains
|
Compare bus interface information with design documents stored in an external data source | Use a database or other external files. Use the |
To save bus objects stored in the base workspace, you can use any MATLAB technique that saves the contents of the base workspace. However, the resulting file contains everything in the base workspace, not just bus objects.
When you modify bus objects, you must resave them to keep the changes.
Map Simulink Bus Objects to Models
Before you simulate a model, all the Simulink.Bus
objects it uses must be
loaded into the base workspace or a data dictionary used by the model. For automation and
consistency across models, mapping bus objects to models is important.
By identifying all of the bus objects that a model requires, you can ensure that those objects are loaded before model execution.
By identifying all models that use a bus object, you can ensure that changes to a bus object do not cause unexpected changes in any of the models that use the bus object.
To ensure the necessary bus objects load before model execution, consider these approaches:
Projects — Automatically load or run files that define bus objects by configuring the files to run when you open a project. For details, see Project Management.
Data dictionaries — Store bus objects with variables and other objects for one or more models.
To share a bus object among models, you can link each model to a dictionary and create a common referenced dictionary to store the object. For an example, see Partition Dictionary Data Using Referenced Dictionaries.
Databases — Capture mapping information in an external data source, such as a database.
Model callbacks — Load or run files that define bus objects by using a model callback, such as
PreLoadFcn
. For more information, see Model Callbacks.If a model uses only a few bus objects, consider copying the bus object code directly into the callback, instead of loading a file.
To find where a bus object is used in an open model, see Finding Blocks That Use a Specific Variable.
Tip
Using a rigorous and standard naming convention is very helpful for mapping
bus object usage. For example, consider the model and data required for
an actuator control function. Naming the model Actuator
and the input
and output ports Actuator_bus_in
and
Actuator_bus_out
, respectively, makes the connection between the
bus objects and the model clear.
Note that this approach can cause issues if the output from one model is fed directly to another model. In this case, the naming mismatch results in an error.