Specify Bus Properties with Simulink.Bus Objects

A bus can be associated with a Simulink.Bus object, which specifies properties that Simulink^® uses to validate the bus. Bus objects are optional for virtual buses, but required for nonvirtual buses.

A 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 all the pins and their configuration and controls what types of wires can be connected to it. Similarly, a Bus object defines the configuration and properties of the signals that the associated bus must have.

Bus Object Workflow

Using Bus objects in a model involves performing these tasks, in many cases iteratively.

Determine Whether to Use Simulink.Bus Objects

Required Uses of Simulink.Bus Objects

You must use Bus objects for these modeling configurations:

Nonvirtual buses that cross model reference boundaries
Stateflow^® charts with bus input or output
S-function or Legacy Code Tool interface with external code

You can associate a Bus object with multiple blocks. Some blocks require that you specify a Bus object if the block has a bus input or output. When a Bus object governs a signal input or output for a block, the signal must be a bus that has the properties specified by the object. Any variance causes an error.

These blocks require a Bus object for bus input and output.

Optional Uses of Simulink.Bus Objects

If you use Bus Creator block parameters to specify bus properties, all blocks downstream from the bus inherit the same properties.

You can use Bus Creator block parameters to define virtual buses and perform limited error checking. To perform thorough error checking on a bus, associate a Bus object with that bus. Using Bus objects to check buses for errors is important when you want to create reusable and shareable model components.

To make tracing the correspondence between the model and the generated code for a bus easier, use a nonvirtual bus. The generated code for a nonvirtual bus produces a structure. Nonvirtual buses can result in multiple copies of some buses.

These blocks can specify a Bus object for bus input and output.

Determine How to Manage Simulink.Bus Objects

You can save 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.

Different Bus object storage locations provide different advantages.

Location	Usage Considerations
Data dictionary	Use for large model componentization. When you save to a data dictionary from the base workspace, you get all the variables used by the model, not just the `Bus` objects. Before you save to a data dictionary, read Considerations before Migrating to Data Dictionary.
Function	Use for when you want to use MATLAB^® for traceability and model differencing.
MAT-file	Use for faster `Bus` object saving and loading.
Database or other external files	Use for comparing bus interface information with design documents stored in an external data source.

Create and Specify Simulink.Bus Objects

To create or edit Bus objects interactively, use the Bus Editor or Model Explorer. Bus objects created with these tools are initially stored in the base workspace or data dictionary. To visualize bus hierarchy and access capabilities such as import and export, use the Bus Editor. When you have many Bus objects or the Bus objects are stored in multiple locations, use the Model Explorer. The Model Explorer provides quick startup regardless of the number of Bus objects and allows you to easily switch between editing Bus objects in the base workspace and data dictionaries.

To create and edit Bus objects programmatically, see Create Bus Objects Programmatically. Bus objects are initially stored in either the base workspace or a function.

After you create a 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, in the Block Parameters dialog box, set Data type to Bus: <object name> and replace <object name> with the 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 Bus object and the corresponding bus must have the same number of bus elements, in the same order. Also, each element in the Bus object and in the corresponding bus must have the same data type and dimensions.

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

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.

Location	File Creation Method	File Contents
Data dictionary	See Migrate Models to Use Simulink Data Dictionary.	`Bus` objects and other base workspace variables used by a model
Function	Use the Bus Editor or `Simulink.Bus.save` function.	`Bus` objects
MAT-file	Use the Bus Editor.	`Bus` objects
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.	`Bus` objects

You can customize Bus object export by providing a custom function that writes to a location outside MATLAB. For example, exported Bus objects can be saved as records in a database. See Customize Bus Object Import and Export for details.

When you modify saved Bus objects, you must resave them to keep the changes.

Map Simulink.Bus Objects to Models

Before you simulate a model, all the Bus objects it uses must be loaded into the base workspace. 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:

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.
You can customize Bus object import by providing a custom function that reads from a location outside MATLAB. See Customize Bus Object Import and Export for details.
Model callbacks — Automatically load or run files that define Bus objects by using the load function in a model callback.
If a model uses only a few Bus objects, consider copying the Bus object code directly into the callback, instead of loading a file. For an example, open model ex_bus_tutorial_nonvirtual and examine the callback.

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.

Documentation