Simulink.Bus.createObject

Create Simulink.Bus objects from blocks or MATLAB structures

Syntax

busInfo = Simulink.Bus.createObject(model,blocks)

busInfo = Simulink.Bus.createObject(struct)

busInfo = Simulink.Bus.createObject(___,file)

busInfo = Simulink.Bus.createObject(___,file,format)

busInfo = Simulink.Bus.createObject(struct,file,format,scope)

Description

busInfo = Simulink.Bus.createObject(model,blocks) creates Simulink.Bus objects for the specified blocks and returns information about the created Bus objects. These Bus objects are created in the base workspace or, if available, the data dictionary used by the model.

busInfo = Simulink.Bus.createObject(struct) creates Bus objects from a structure that can contain MATLAB^® timeseries, MATLAB timetable, and matlab.io.datastore.SimulationDatastore objects or a numeric structure. These Bus objects are created in the base workspace or, if available, the data dictionary used by the model.

busInfo = Simulink.Bus.createObject(___,file) saves Bus objects in a function that defines object properties in a cell array of cell arrays, then creates the Bus objects by calling Simulink.Bus.cellToObject.

busInfo = Simulink.Bus.createObject(___,file,format) saves Bus objects in a function with the specified format. The function can define object properties using cell arrays or arrays.

busInfo = Simulink.Bus.createObject(struct,file,format,scope) creates the Bus objects in the data dictionary specified by scope.

Examples

Create Simulink.Bus Object from Bus Creator Block

Open the example model.

open_system('BusObjectCreationModel')

Create a Bus object that corresponds with the bus created by the Bus Creator block.

busInfo = Simulink.Bus.createObject('BusObjectCreationModel',...
    'BusObjectCreationModel/Bus Creator');

Create and Save Simulink.Bus Objects in a Function

Create Bus objects from two Bus Creator blocks and save the Bus object definition in a function.

Open the example model.

open_system('BusObjectCreationModel');

Assign the block handle for the Bus Creator block to a variable with the getSimulinkBlockHandle function.

bc = getSimulinkBlockHandle('BusObjectCreationModel/Bus Creator');

Alternatively, you can select a Bus Creator block in the model then use the gcbh function to get its block handle.

Assign the block handle for the Bus Creator1 block to a variable.

bc1 = getSimulinkBlockHandle('BusObjectCreationModel/Bus Creator1');

To create a Bus object, specify the block handle variables in a vector. To save the Bus object definition, also specify a file name.

busInfo = Simulink.Bus.createObject('BusObjectCreationModel',...
    [bc bc1], 'BusObjectFunction');

Since these Bus Creator blocks create a bus hierarchy, specifying only the Bus Creator1 block creates both Bus objects in the Workspace and in the function.

Compare the BusObjectFunction against the function created by this command.

topBusInfo = Simulink.Bus.createObject('BusObjectCreationModel',...
    bc1, 'BusObjectFunctionFromHierarchy');

For a function that is formatted to be easier to read, specify the function format as object.

topBusInfo1 = Simulink.Bus.createObject('BusObjectCreationModel',...
    bc1, 'BusObjectFunctionFormatted','object');

Input Arguments

model — Model name or handle

character vector

Model name or handle, specified as a character vector.

blocks — Blocks associated with buses

character vector | cell array of block path names | vector of block handles

Blocks associated with buses, specified as a character vector, cell array of block path names, or vector of block handles. For one block, specify the full path name of the block. For multiple blocks, specify either a cell array of block path names or a vector of block handles.

This function can create Bus objects from these blocks:

• Bus Creator blocks

• Subsystem Inport blocks

• Subsystem Outport blocks

If you specify a block associated with a bus hierarchy, the function also creates Bus objects for all nested buses in the hierarchy.

struct — Structure of objects or numeric structure

structure of MATLAB timeseries, MATLAB timetable, and matlab.io.datastore.SimulationDatastore objects | numeric structure

Structure of objects or numeric structure, specified as a structure that can contain MATLAB timeseries, MATLAB timetable, and matlab.io.datastore.SimulationDatastore objects or a numeric structure.

file — Name of function being generated

character vector

Name of function being generated, specified as a character vector. The file name must be unique.

format — Format of function being generated

'cell' (default) | 'object'

Format of function being generated, specified as either 'cell' or 'object'. The 'cell' format is more compact, but the 'object' format is easier to read.

The 'cell' format saves the Bus object definitions in a cell array of cell arrays and creates the Bus objects by calling Simulink.Bus.cellToObject. Each subordinate cell array represents a Bus object and contains these properties:

1. Bus name

2. Header file

3. Description

4. Data scope

5. Alignment

6. Preserve Element Dimensions

7. Elements

The elements field is a cell array that contains this information for each of the Simulink.BusElement objects that the Bus object references:

1. Element name

2. Dimensions

3. Data type

4. Sample time — The cell array contains this field when the sample time is not inherited. A noninherited sample time causes an error during model compilation. For more information, see Simulink.BusElement objects no longer support the SampleTime property.

5. Complexity

6. Dimensions mode

7. Minimum

8. Maximum

9. Units

10. Description

The 'object' format saves the Bus object definitions as arrays. The function uses array indexing to access elements of the array and dot notation to assign property values. For more information, see Array Indexing and Access to Property Values.

scope — Data dictionary to contain Simulink.Bus objects

Simulink.data.Dictionary object

Data dictionary, specified as a Simulink.data.Dictionary object. Before you use this argument, represent the dictionary with a Simulink.data.Dictionary object by using, for example, the Simulink.data.dictionary.create or Simulink.data.dictionary.open function.

If scope is empty, the function uses the MATLAB base workspace as the source of the Bus objects.

Output Arguments

busInfo — Bus information for specified blocks

structure array

Bus information for the specified blocks, returned as a structure array. Each element of the structure array corresponds to one block and contains these fields:

• block — Handle of the block

• busName — Name of the Bus object associated with the block

Tips

If you specify a model name, the model must compile successfully before you use the Simulink.Bus.createObject command.

Compatibility Considerations

Simulink.BusElement objects no longer support the SampleTime property

Errors starting in R2020b

The SampleTime property of Simulink.BusElement objects is no longer supported.

BusElement objects that specify a sample time cause an error during compile. To remove the sample time specification from a BusElement object, set its SampleTime to -1.

Simulink.Bus.cellToObject continues to accept cell arrays that specify sample time for bus elements. Simulink.Bus.objectToCell, Simulink.Bus.save, and Simulink.Bus.createObject continue to return cell arrays or arrays that include the sample time when it is noninherited. When the sample time is inherited (-1), they omit it. Similarly, the Bus Editor and Model Explorer omit the sample time when it is inherited.

To specify the sample time for an element of a bus, use the SampleTime block parameter of corresponding blocks. For example, you can use In Bus Element, Out Bus Element, and Signal Specification blocks to specify sample time.