Specify Bus Properties with Bus Objects

A bus can have an associated bus object, which provides properties that Simulink® uses to validate the bus signal. 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 a bus. Another way of thinking of a bus object is that it is 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.

A bus object is an instance of class Simulink.Bus that can be stored in a location such as the base workspace. The object defines the structure of the bus and the properties of its elements, such as nesting, data type, and size.

A bus object serves as the root of an ordered hierarchy of bus elements, which are instances of class Simulink.BusElement. Each element completely specifies the properties of a signal in a bus, such as its name, data type, and dimensionality. The order of the elements contained in the bus object defines the order of the signals in the bus. A bus object can also specify properties that were not defined by constituent signals, but were left to be inherited.

Bus Object Workflow

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

Determine Whether to Use Bus Objects

Required Uses of 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 Bus Objects

If you use Bus Creator block parameters to specify bus signal 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 bus signals 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 bus signals.

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

Determine How to Manage Bus Objects

You can save bus objects to these locations:

  • Data dictionary

  • MATLAB® file

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

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

MATLAB file

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 Bus Objects

To create and edit bus objects interactively, use the Bus Editor. Bus objects created with this tool are initially stored in the base workspace.

To create and edit bus objects programmatically, see Create Bus Objects Programmatically. Bus objects created from classes and functions are initially stored in either the base workspace or a MATLAB file.

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 to be 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 signal must have the same number of bus elements, in the same order. Also, each bus element in the bus object and in the corresponding signal in the model must have the same attributes.

During model development, you can modify bus signals 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 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.

LocationFile Creation MethodFile Contents

Data dictionary

See Migrate Models to Use Simulink Data Dictionary.Bus objects and other base workspace variables used by a model

MATLAB file

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

See Also

Classes

Related Topics