Specify Bus Properties with Bus Objects - MATLAB & Simulink (original) (raw)
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 aSimulink.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.Busobject. - Set the Element names block parameter to
From output data type. - 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.Busobject with elements that specify a unit ofm/s
The Signal Specification block usesm/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 theType 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 asSimulink.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:
- Bus Creator block
- Constant block
- Data Store Memory block
- In Bus Element block
- Inport block
- Out Bus Element block
- Outport block
- Signal Specification block
- Simulink.BusElement object
- Simulink.Parameter object
- Simulink.Signal object
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 theSimulink.Bus object name. When you set the data type of aSimulink.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 theSimulink.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 theSimulink.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 moreSimulink.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, seeProject 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 andActuator_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.