Simulink.Bus.createObject

Create Simulink.Bus objects from blocks or MATLAB structures

Syntax

busInfo = Simulink.Bus.createObject(mdl,busSource)

busInfo = Simulink.Bus.createObject(S)

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

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

busInfo = Simulink.Bus.createObject(S,file,fileFormat,scope)

Description

busInfo = Simulink.Bus.createObject(mdl,busSource) creates Simulink.Bus objects for the buses specified by busSource in the model specified by mdl. The function returns information about the created objects.

When the model uses a data dictionary, this function creates the objects in the data dictionary. Otherwise, this function creates the objects in the base workspace.

busInfo = Simulink.Bus.createObject(S) creates Simulink.Bus objects from the structure specified by S. The structure can contain MATLAB^® timeseries, MATLAB timetable, and matlab.io.datastore.SimulationDatastore objects. The structure can be a numeric structure.

The function creates the objects in the base workspace.

busInfo = Simulink.Bus.createObject(___,file) saves the Simulink.Bus object definitions in a function. The name of the function is specified by file.

Specify any of the input argument combinations in the previous syntaxes followed by the file argument.

busInfo = Simulink.Bus.createObject(___,file,fileFormat), where fileFormat is "object", saves the Simulink.Bus object definitions using arrays. The "object" format makes the function easier to read. The default for fileFormat is "cell", which uses cell arrays and is more compact.

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

Examples

Create Simulink.Bus Object from Bus Creator Block

Create Simulink.Bus objects from a Bus Creator block that creates a bus with multiple levels of hierarchy.

Open the example model named BusHierarchy.

mdl = "BusHierarchy";
open_system(mdl)

Create a Simulink.Bus object from the Bus Creator block named Bus Creator1. This block receives input from a source block and another Bus Creator block.

block = "BusHierarchy/Bus Creator1";
busInfo = Simulink.Bus.createObject(mdl,block);

This command creates Simulink.Bus objects named TopBus and NestedBus in the base workspace. Each bus object represents a bus in the bus hierarchy.

To view the Simulink.Bus objects, open the Type Editor.

typeeditor

Create Simulink.Bus Object from Bus Element Port

Create Simulink.Bus objects from a bus element port, which Out Bus Element blocks represent.

Open the example model named BusOutput.

mdl = "BusOutput";
open_system(mdl)

The output bus has multiple levels of hierarchy. The top-level bus contains a nested bus.

Create Simulink.Bus objects that define the bus hierarchy at the output port named OutBus.

port = "BusOutput/OutBus";
busInfo = Simulink.Bus.createObject(mdl,port);

To view the objects, open the Type Editor.

typeeditor

Create and Save Simulink.Bus Objects in Function

Create Simulink.Bus objects from a Bus Creator block and save the Simulink.Bus object definitions in a function.

Open the example model named BusHierarchy.

mdl = "BusHierarchy";
open_system(mdl);

Create Simulink.Bus objects from the Bus Creator block named Bus Creator1. This block receives input from a source block and another Bus Creator block. To save the Simulink.Bus object definitions in a function, also specify a filename.

block = "BusHierarchy/Bus Creator1";
file = "BusObjectFunction";
busInfo = Simulink.Bus.createObject(mdl,block,file);

These commands create Simulink.Bus objects named TopBus and NestedBus in the base workspace and a file named BusObjectFunction in your current folder.

To examine the file contents, open the file. By default, the file uses the "cell" format. For example, the Chirp element is defined by a cell array.

{'Chirp', 1, 'double', 'real', 'Sample', 'Fixed', [], [], '', ''};

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

file1 = "BusObjectFunctionFormatted";
busInfo1 = Simulink.Bus.createObject(mdl,block,file1,"object");

To examine the file contents, open the file. In the "object" format, the Chirp element is defined by an array that uses dot notation to assign property values.

elems(1) = Simulink.BusElement;
elems(1).Name = 'Chirp';
elems(1).Dimensions = 1;
elems(1).DimensionsMode = 'Fixed';
elems(1).DataType = 'double';
elems(1).Complexity = 'real';
elems(1).Min = [];
elems(1).Max = [];
elems(1).DocUnits = '';
elems(1).Description = '';

Create Simulink.Bus Objects from MATLAB Structures

When you create a nonvirtual bus with a Constant block, you must specify a MATLAB structure for Constant value and a Simulink.Bus object as the Output data type.

For this example, create a structure that contains other structures.

bus_struct.A.A1 = 0;
bus_struct.A.A2 = [0 + 0i;0 + 0i;0 + 0i;0 + 0i;0 + 0i];
bus_struct.B = 5;
bus_struct.C.C1 = 0;
bus_struct.C.C2.A1 = 0;
bus_struct.C.C2.A2 = [0 + 0i;0 + 0i;0 + 0i;0 + 0i;0 + 0i];

Create the Simulink.Bus objects that correspond with the structure.

busInfo = Simulink.Bus.createObject(bus_struct);

The function creates four Simulink.Bus objects. The object named slBus1 corresponds to the top-level structure and uses a default name. The objects named A, C, and C2 correspond to the nested structures.

To view the objects, open the Type Editor.

typeeditor

Input Arguments

mdl — Model name or handle

character vector | string scalar

Model name or handle, specified as a character vector or string scalar.

The model you specify must compile successfully.

busSource — Source of bus definition

character vector | string scalar | cell array of block paths | vector of block handles

Source of bus definition, specified as a character vector, string scalar, cell array of block paths, or vector of block handles.

This function can create Simulink.Bus objects from buses at these sources:

• Bus Creator blocks

• Input ports represented by In Bus Element blocks

• Output ports represented by Out Bus Element blocks

• Subsystem Inport blocks

• Subsystem Outport blocks

When the bus has hierarchy, the function also creates Simulink.Bus objects for the nested buses in the bus hierarchy.

To specify a bus at a Bus Creator, Inport, or Outport block, use the corresponding block path or handle.

Example: Simulink.Bus.createObject(mdl,"BusHierarchy/Bus Creator") specifies one bus source via a block path.

Example: Simulink.Bus.createObject(mdl,{'BusHierarchy/Bus Creator','BusHierarchy/Bus Creator1'}) specifies multiple bus sources via a cell array of block paths.

Example: Simulink.Bus.createObject(mdl,[bc bc1]) specifies multiple bus sources via a vector of block handles.

To specify a bus at a port represented by an In Bus Element or Out Bus Element block, use the path to the port or element. For a port, the path is composed of the model name and port name. For an element of a port, the path is composed of the model name, port name, and one or more element names.

Example: Simulink.Bus.createObject(mdl,"BusOutput/OutBus") specifies the top-level bus of a root-level bus element port.

Example: Simulink.Bus.createObject(mdl,"BusOutput/OutBus.NestedBus") specifies a nested bus of a root-level bus element port.

S — 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 as a numeric structure.

When you specify a structure with hierarchy, this function creates Simulink.Bus objects for each structure in the hierarchy.

file — Name of function being generated

character vector | string scalar

Name of function being generated, specified as a character vector or string scalar. The filename must be unique.

fileFormat — 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 defines the Simulink.Bus object with a cell array of cell arrays and creates the objects by calling Simulink.Bus.cellToObject. Each subordinate cell array represents a Simulink.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 Simulink.Bus object references:

1. Element name

2. Dimensions

3. Data type — When this field specifies a Simulink.Bus object, the specification does not include the Bus: prefix. This prefix is optional when you set the data type of a Simulink.BusElement object to a Simulink.Bus object.

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

7. Dimensions mode

8. Minimum

9. Maximum

10. Units

11. Description

The "object" format defines the Simulink.Bus object with arrays. The function uses array indexing to access elements of the array and dot notation to assign property values.

scope — Data dictionary to contain 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.

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

Output Arguments

busInfo — Bus object information

structure array

Bus object information, returned as a structure array.

When you specify blocks as the bus sources, each element of the busInfo structure array corresponds to one block and contains these fields:

• block — Handle of the block

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

When you specify a structure or a bus at a bus element port, the busInfo structure contains these fields:

• block — Empty matrix ([])

• busName — Name of the Simulink.Bus object that corresponds to the structure or bus

Version History

Introduced before R2006a

R2024a: Create objects from bus element ports

Create Simulink.Bus objects from buses at bus element ports. For more information, see busSource.

R2020b: Simulink.BusElement objects no longer support the SampleTime property

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

R2016b: Simulink.BusElement objects will no longer support the SamplingMode property

The SamplingMode property of Simulink.BusElement objects has been removed. Scripts that use the SamplingMode property of Simulink.BusElement objects continue to work. The Simulink.Bus.cellToObject function continues to require the SamplingMode field. The Simulink.Bus.objectToCell function continues to include the sampling mode in the output cell arrays. When you save Simulink.Bus object definitions to functions that use cell arrays, the cell arrays continue to include the sampling mode.

In a future release, support for the SamplingMode property will be removed.

To specify whether a signal is sample-based or frame-based, define the sampling mode of input signals at the block level instead of at the signal level.