Simulink®

Working with Structures and Bus Signals

About Structures in Embedded MATLAB Function Blocks

Embedded MATLAB Function blocks support MATLAB structures (see Structures in the MATLAB Programming Fundamentals documentation). In Embedded MATLAB Function blocks, you can define structure data as inputs or outputs that interact with bus signals. You can also define structures inside Embedded MATLAB functions that are not part of Embedded MATLAB Function blocks (see Using Structures in the Embedded MATLAB documentation).

The following table summarizes how to create different types of structures in Embedded MATLAB Function blocks:

Structures in Embedded MATLAB Function blocks can contain fields of any type and size, including muxed signals, buses, and arrays of structures, as described in Elements of Structures in the Embedded MATLAB Subset in the Embedded MATLAB documentation.

Back to Top

Example of Structures in an Embedded MATLAB Function Block

The following example shows how to use structures in an Embedded MATLAB Function block:

In this model, an Embedded MATLAB Function block receives a bus signal using the structure inbus at input port 1 and outputs two bus signals from the structures outbus at output port 1 and outbus1 at output port 2. The input signal comes from the Bus Creator block MainBusCreator, which bundles signals ele1, ele2, and ele3. The signal ele3 is the output of another Bus Creator block SubBusCreator, which bundles the signals a1 and a2. The structure outbus connects to a Bus Selector block BusSelector1; the structure outbus1 connects to another Bus Selector block BusSelector3.

Like other outputs in the Embedded MATLAB subset, structure outputs must be initialized. The Embedded MATLAB function in this example implicitly defines a local structure variable mystruct using the struct function, and uses this local structure variable to initialize the value of the first output outbus. It initializes the second output outbus1 to the value of field ele3 of structure inbus.

Structure Definitions in Example

Here are the definitions of the structures in the Embedded MATLAB Function block in the example, as they appear in the Ports and Data Manager:

Bus Objects Define Structure Inputs and Outputs

Each structure input and output must be defined by a Simulink.Bus object in the base workspace (see Workflow for Creating Structures in Embedded MATLAB Function Blocks). This means that the structure shares the same properties as the bus object, including number, name, and type of fields. In this example, the following bus objects define the structure inputs and outputs:

The Simulink.Bus object MainBus defines structure input inbus and structure output outbus. The Simulink.Bus object SubBus defines structure output outbus1. Based on these definitions, inbus and outbus have the same properties as MainBus and, therefore, reference their fields by the same names as the fields in MainBus, using dot notation (see Indexing Substructures and Fields). Similarly, outbus1 references its fields by the same names as the fields in SubBus. Here are the field references for each structure in this example:

To learn how to define structures in Embedded MATLAB, see Workflow for Creating Structures in Embedded MATLAB Function Blocks.

Back to Top

How Structure Inputs and Outputs Interface with Bus Signals

Buses in a Simulink model appear inside the Embedded MATLAB Function block as structures; structure outputs from the Embedded MATLAB Function block appear as buses in Simulink models. When you create structure inputs, the Embedded MATLAB Function block determines the type, size, and complexity of the structure from the input signal. When you create structure outputs, you must define their type, size, and complexity in the Embedded MATLAB function.

You connect structure inputs and outputs from Embedded MATLAB Function blocks to any bus signal, including:

• Blocks that output bus signals — such as Bus Creator blocks

• Blocks that accept bus signals as input — such as Bus Selector and Gain blocks

• S-Function blocks

• Other Embedded MATLAB Function blocks

Working with Virtual and Nonvirtual Buses

Embedded MATLAB Function blocks supports nonvirtual buses only (see Virtual and Nonvirtual Buses in the Simulink User's Guide). When models that contain Embedded MATLAB function inputs and outputs are built, hidden converter blocks are used to convert bus signals for use with Embedded MATLAB, as follows:

• Converts incoming virtual bus signals to nonvirtual buses for Embedded MATLAB structure inputs

• Converts outgoing nonvirtual bus signals from Embedded MATLAB to virtual bus signals

Back to Top

Rules for Defining Structures in Embedded MATLAB Function Blocks

Follow these rules when defining structures in Embedded MATLAB Function blocks:

• For each structure input or output in an Embedded MATLAB Function block, you must define a Simulink.Bus object in the base workspace to specify its type. For more information, see Simulink.Bus.

• Embedded MATLAB Function blocks support nonvirtual buses only (see Working with Virtual and Nonvirtual Buses).

Back to Top

Workflow for Creating Structures in Embedded MATLAB Function Blocks

Here is the workflow for creating a structure in Embedded MATLAB:

1. Decide on the type (or scope) of the structure (see About Structures in Embedded MATLAB Function Blocks).

2. Based on the scope, follow these guidelines for creating the structure:

   For Structure Scope:	Follow These Steps:
   Input	Create a Simulink.Bus object in the base workspace to define the structure input. Add data to the Embedded MATLAB Function block, as described in Adding Data to an Embedded MATLAB Function Block. The data should have the following properties Scope = Input Mode = Bus Object Bus object = name of the Simulink.Bus object that defines the structure input See Rules for Defining Structures in Embedded MATLAB Function Blocks.
   Output	Create a Simulink.Bus object in the base workspace to define the structure output. Add data to the Embedded MATLAB Function block with the following properties: Scope = Output Mode = Bus Object Bus object = name of the Simulink.Bus object that defines the structure input Define and initialize the output structure implicitly as a variable in the Embedded MATLAB function, as described in Defining Outputs as Structures in the Embedded MATLAB documentation. Make sure the number, type, and size of fields in the output structure variable definition match the properties of the Simulink.Bus object.
   Local	Define the structure implicitly as a local variable in the Embedded MATLAB function, as described in Defining Local Structure Variables in the Embedded MATLAB documentation. By default, local variables in Embedded MATLAB are temporary.
   Persistent	Define the structure implicitly as a persistent variable in the Embedded MATLAB function, as described in Making Structures Persistent in the Embedded MATLAB documentation.
   Parameter	Create a structure variable in the base workspace. Add data to the Embedded MATLAB Function block with the following properties: Name = same name as the structure variable you created in step 1. Scope = Parameter Make sure the Tunable property is unchecked. See Working with Non-Tunable Structure Parameters in Embedded MATLAB Function Blocks.

Back to Top

Indexing Substructures and Fields

As in MATLAB, you index substructures and fields of Embedded MATLAB structures by using dot notation. Unlike MATLAB, you must reference field values individually (see Limitations with Structures in the Embedded MATLAB documentation).

For example, in the model described in Example of Structures in an Embedded MATLAB Function Block, the Embedded MATLAB function uses dot notation to index fields and substructures:

function [outbus, outbus1] = fcn(inbus)

substruct.a1 = inbus.ele3.a1;
substruct.a2 = int8([1 2;3 4]);

mystruct = struct('ele1',20.5,'ele2',single(100),
                  'ele3',substruct);

outbus = mystruct;
outbus.ele3.a2 = 2*(substruct.a2);

outbus1 = inbus.ele3;

The following table shows how Embedded MATLAB resolves symbols in dot notation for indexing elements of the structures in this example:

Back to Top

Assigning Values to Structures and Fields

You can assign values to any Embedded MATLAB structure, substructure, or field. Here are the guidelines:

For example, the following table presents valid and invalid structure assignments based on the specifications for the model described in Example of Structures in an Embedded MATLAB Function Block:

Back to Top

Working with Non-Tunable Structure Parameters in Embedded MATLAB Function Blocks

You can define non-tunable structure parameters in Embedded MATLAB Function blocks. Models that contain non-tunable structure parameters will compile both for simulation and code generation with Real-Time Workshop.

Defining Non-Tunable Structure Parameters

To define non-tunable structure parameters in Embedded MATLAB Function blocks, follow these steps:

1. Define and initialize a structure variable

   A common method is to create a structure in the base workspace. For other methods, see Working with Block Parameters.

2. In the Ports and Data Manager or Model Explorer, add data in the Embedded MATLAB Function block with the following properties:

   Property	What to Specify
   Name	Enter same name as the structure variable you defined in the base workspace
   Scope	Select Parameter
   Tunable	Uncheck this check box
   Type	Select Inherit: Same as Simulink

   For example, the data dialog box fields should look something like this:

   

   Caution   Embedded MATLAB Function blocks do not support tunable structure parameters. If you define a structure parameter as tunable, you receive a run-time error: Parameter is a tunable structure parameter which is not supported. Set the parameter to be non-tunable, or do not use a structure value.

3. Click Apply.

FIMATH Properties of Non-Tunable Structure Parameters

FIMATH properties for non-tunable structure parameters containing fixed-point values are based on the initial values of the structure. They do not come from the FIMATH properties specified for fixed-point input signals to the parent Embedded MATLAB Function block. (These FIMATH properties appear in the properties dialog box for Embedded MATLAB Function blocks.)

Rules for Defining Non-Tunable Structure Parameters

Non-tunable structure parameters in Embedded MATLAB Function blocks have the same limitations as structures in Embedded MATLAB functions. See Limitations with Structures in the Embedded MATLAB documentation.

Example: Using a Non-Tunable Structure Parameter to Initialize a Matrix

The following simple example uses a non-tunable structure parameter input to initialize a matrix output. The model looks like this:

This model defines a structure variable p in its pre-load callback function, as follows:

The structure p has two fields, rows and cols, which specify the dimensions of a matrix. The Embedded MATLAB Function block uses a constant input u to initialize the matrix output y. Here is the code:

function y = fcn(u, p)
y = zeros(p.rows,p.cols) + u;

Running the model initializes each element of the 2-by-3 matrix y to 99, the value of u:

Back to Top

Limitations of Structures in Embedded MATLAB Function Blocks

Structures in Embedded MATLAB Function blocks support a subset of the operations available for MATLAB structures (see Limitations with Structures in the Embedded MATLAB documentation).

Back to Top

Resolving Signal Objects for Output Data

Working with Frame-Based Signals