Simulink.Bus

Specify properties of buses

Description

A Simulink.Bus object, when used with Simulink.BusElement objects, specifies and validates the properties of a bus and its elements. When you simulate or update a model, the software checks whether buses connected to blocks match the Simulink.Bus objects that the blocks specify.

A bus object specifies only the architectural properties of a bus. For example, a bus object can specify element names, hierarchy, order, and data types. A bus object is analogous to a struct in C code because 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.

Simulink.Bus objects contain Simulink.BusElement objects. Each bus element object specifies the properties of a signal in a bus, such as its name, data type, and dimension. The order of the bus element objects in the bus object defines the order of the signals in the bus.

A bus object can specify properties that were not defined by constituent signals, but were left to be inherited.

To create and modify bus objects in the base workspace or a data dictionary, you can use the Type Editor, Model Explorer, or MATLAB^® commands. You cannot store Simulink.Bus objects in model workspaces.

To use Simulink.Bus objects in a model, see Specify Bus Properties with Bus Objects.

Creation

You can create a Simulink.Bus object in multiple ways.

• To interactively create a Simulink.Bus object, use the Type Editor or Model Explorer.

• To programmatically create a Simulink.Bus object with default properties, use the Simulink.Bus function described below.

• To programmatically create Simulink.Bus objects from blocks in a model, MATLAB data, and external C code, see Programmatically Create Simulink Bus Objects.

Syntax

name = Simulink.Bus

Description

name = Simulink.Bus returns a Simulink.Bus object with default property values. The name of the object is the name of the MATLAB variable to which you assign the object.

Properties

Description — Bus description

'' (default) | character vector | string scalar

Bus description, specified as a character vector or string scalar. Use the description to document information about the object, such as the kind of signal it applies to or where the object is used. This information does not affect Simulink^® processing.

Data Types: char | string

Elements — Elements of bus

empty array (default) | array of Simulink.BusElement objects

Elements of bus, specified as an array of Simulink.BusElement objects. Each bus element object defines the name, data type, dimensions, and other properties of a signal within the bus. For more information, see Simulink.BusElement.

DataScope — Data type definition mode in generated code

'Auto' (default) | 'Exported' | 'Imported'

Data type definition mode in generated code, specified as 'Auto', 'Exported', or 'Imported'. This property specifies whether during code generation the data type definition is imported from, or exported to, the header file specified with the HeaderFile property.

Value	Action
'Auto' (default)	Import the data type definition from the specified header file. If you do not specify the header file, export the data type definition to the default header file.
'Exported'	Export the data type definition to the specified header file or default header file.
'Imported'	Import the data type definition from the specified header file or default header file.

To prevent ill-formed header file inclusions in generated code, a Simulink.Bus object must specify DataScope as 'Exported' and HeaderFile as a C header file when the Simulink.Bus object has at least one nested Simulink.Bus object that specifies DataScope as 'Exported' and HeaderFile as a C header file.

Note

To import enum or struct types that are not declared with a typedef statement:

• Include (#include) the header file containing the declaration in the Simulation Target configuration parameters.

• Ensure that Import custom code in the Simulation Target configuration parameters is selected. This parameter is selected by default.

To avoid potential MISRA C:2012 violations, set the data scope to Imported or Exported.

Data Types: char | string

HeaderFile — C header file used with data type definition

'' (default) | character vector | string scalar

C header file used with data type definition, specified as a character vector or string scalar. Based on the value of the DataScope property, import the data type definition from or export the data type definition to the header file. The Simulink Coder™ software uses this property for code generation. Simulink software ignores this property.

By default, the generated #include directive uses the preprocessor delimiter " instead of < and >. To generate the directive #include <myTypes.h>, specify HeaderFile as <myTypes.h>.

Data Types: char | string

Alignment — Data alignment boundary

-1 (default) | integer

Data alignment boundary, specified as an integer, in number of bytes. -1 specifies that no data alignment occurs. The Simulink Coder software uses this property for code generation. Simulink software ignores this property. For more information, see Optimize Performance of Memory Access by Using Data Alignment (Embedded Coder).

The starting memory address for the data allocated for the bus is a multiple of the Alignment setting. If the object occurs in a context that requires alignment, you must specify an Alignment value with a positive integer that is a power of 2.

Before R2024a: Specify a value not exceeding 128.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

PreserveElementDimensions — Specification to preserve dimensions of multidimensional bus elements

'false' (default) | 'true'

Specification for the code generator to preserve dimensions of multidimensional bus elements in the generated code, specified as 'false' or 'true'. For more information, see Preserve Dimensions of Bus Elements in Generated Code (Embedded Coder).

Data Types: logical

Object Functions

getNumLeafBusElements	Number of leaf elements in Simulink.Bus object
getLeafBusElements	Leaf elements in Simulink.Bus object

Examples

Create Bus Objects from Bus Element Objects

Create a hierarchy of Simulink.Bus objects using arrays of Simulink.BusElement objects.

Create an array that contains two BusElement objects, named Chirp and Sine, in the base workspace.

elems(1) = Simulink.BusElement;
elems(1).Name = 'Chirp';

elems(2) = Simulink.BusElement;
elems(2).Name = 'Sine';

Array indexing lets you create and access the elements of the array. Dot notation lets you access property values of the elements.

Create a Bus object, named Sinusoidal, that contains the elements defined in the elems array.

Sinusoidal = Simulink.Bus;
Sinusoidal.Elements = elems;

To create a hierarchy of Bus objects, create another Bus object to reference the Bus object named Sinusoidal.

Create an array that contains two BusElement objects, named NestedBus and Step. Specify the Bus object named Sinusoidal as the data type of the NestedBus element.

clear elems

elems(1) = Simulink.BusElement;
elems(1).Name = 'NestedBus';
elems(1).DataType = 'Bus: Sinusoidal';

elems(2) = Simulink.BusElement;
elems(2).Name = 'Step';

Create a Bus object, named TopBus, that contains the elements defined in the elems array.

TopBus = Simulink.Bus;
TopBus.Elements = elems;

You can view the hierarchy of the created objects in the Type Editor.

typeeditor

Inspect Bus Objects Programmatically

While the Type Editor lets you inspect a hierarchy of Simulink.Bus objects interactively, you can also inspect the objects programmatically.

Open the example. Then, load the bus objects by running the function named busObjectDefinition.

busObjectDefinition

Two bus objects appear in the base workspace.

Inspect Top-Level Bus Object

Inspect the top-level bus object, which is named TopBus.

TopBus

TopBus = 
  Bus with properties:

                  Description: ''
                    DataScope: 'Auto'
                   HeaderFile: ''
                    Alignment: -1
    PreserveElementDimensions: 0
                     Elements: [2x1 Simulink.BusElement]

Based on the value of the Elements property, TopBus contains two Simulink.BusElement objects.

Inspect the elements of TopBus.

TopBus.Elements(1)

ans = 
  BusElement with properties:

              Name: 'NestedBus'
        Complexity: 'real'
        Dimensions: 1
          DataType: 'Bus: Sinusoidal'
               Min: []
               Max: []
    DimensionsMode: 'Fixed'
              Unit: ''
       Description: ''

Based on the value of the DataType property, the first element represents a nested bus object named Sinusoidal.

TopBus.Elements(2)

ans = 
  BusElement with properties:

              Name: 'Step'
        Complexity: 'real'
        Dimensions: 1
          DataType: 'double'
               Min: []
               Max: []
    DimensionsMode: 'Fixed'
              Unit: ''
       Description: ''

Based on the values of the Name and DataType properties, the second element represents a signal named Step.

Inspect Nested Bus Object

Inspect the elements of the nested Simulink.Bus object named Sinusoidal.

Sinusoidal

Sinusoidal = 
  Bus with properties:

                  Description: ''
                    DataScope: 'Auto'
                   HeaderFile: ''
                    Alignment: -1
    PreserveElementDimensions: 0
                     Elements: [2x1 Simulink.BusElement]

Based on the value of the Elements property, Sinusoidal contains two Simulink.BusElement objects.

Inspect the elements of Sinusoidal.

Sinusoidal.Elements(1)

ans = 
  BusElement with properties:

              Name: 'Chirp'
        Complexity: 'real'
        Dimensions: 1
          DataType: 'double'
               Min: []
               Max: []
    DimensionsMode: 'Fixed'
              Unit: ''
       Description: ''

Sinusoidal.Elements(2)

ans = 
  BusElement with properties:

              Name: 'Sine'
        Complexity: 'real'
        Dimensions: 1
          DataType: 'double'
               Min: []
               Max: []
    DimensionsMode: 'Fixed'
              Unit: ''
       Description: ''

Based on the values of the Name and DataType properties, the elements represent two signals: Chirp and Sine.

Inspect Leaf Elements of Bus Objects

To directly inspect the leaf elements of a bus object, use the getNumLeafBusElements and getLeafBusElements object functions.

To get the number of leaf elements in TopBus, use the getNumLeafBusElements object function.

num = getNumLeafBusElements(TopBus)

num = 
3

To get information about the leaf elements in TopBus, use the getLeafBusElements object function. For example, inspect the first element of TopBus.

leaf = getLeafBusElements(TopBus);
leaf(1)

ans = 
  BusElement with properties:

              Name: 'Chirp'
        Complexity: 'real'
        Dimensions: 1
          DataType: 'double'
               Min: []
               Max: []
    DimensionsMode: 'Fixed'
              Unit: ''
       Description: ''

Version History

Introduced before R2006a

R2024a: Alignment property supports more values

The Alignment property supports any positive integer that is a power of 2. Previously, this property did not support values exceeding 128.