Specify Bus Properties with Bus Objects

Each bus object provides a reusable specification for a bus that the software can use to validate the properties of the bus and its elements. Multiple blocks, objects, and model components can specify the same bus object.

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

Bus objects are optional for virtual buses but required for nonvirtual buses. For more information about virtual and nonvirtual buses, see Composite Interface Guidelines.

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 `Simulink.Bus` object.
Assign or validate the hierarchy and properties of an output bus at a subsystem or model interface.	Use an Out Bus Element block or `Simulink.Bus` object.
Assign or validate the hierarchy and properties of a bus across multiple blocks or model components.	Use a `Simulink.Bus` object.
Trace the correspondence between the model and generated code for a bus.	Use a nonvirtual bus defined by a `Simulink.Bus` object. 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 `Simulink.ConnectionBus` object. For information about `Simulink.ConnectionBus` objects, see Design Rigid Interface Specifications for Conserving Connections (Simscape).

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 of m/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 a block or object that needs the bus definition.

Use a Simulink.Bus object to specify bus properties for these blocks and objects:

To associate a block or object with a bus object, set the data type of the block or object to Bus: <object name> and replace <object name> with the Simulink.Bus object name. When you set the data type of a Simulink.BusElement object to a Simulink.Bus object, the Bus: prefix is optional.

You can specify the bus object as the data type either before or after defining the bus object. However, before you simulate the model, you must define and load the Simulink.Bus object.

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 `Simulink.Bus` objects. 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 `Simulink.Bus` objects, use the Type Editor, Model Explorer, or `Simulink.Bus.save` function.
Save and load bus objects faster.	Use a MAT file. To create a MAT file that contains `Simulink.Bus` objects from the base workspace, use the Type Editor, Model Explorer, or `save` function.
Compare bus interface information with design documents stored in an external data source	Use a database or other external files. Use the `Simulink.importExternalCTypes` function, scripts, or Database Toolbox™ functionality on C code structure (`struct`) definitions. In preparation for integrating existing algorithmic C code for simulation, for example, by using the Legacy Code Tool, you can package signal or parameter data in the definitions according to structure type.

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.