Using Enumerated Data in MATLAB Function Blocks

Enumerated Data in MATLAB Function Blocks

Enumerated data is data that has a finite set of values. An enumerated data type is a user-defined type whose values belong to a predefined set of symbols, also called enumerated values. Each enumerated value consists of a name and an underlying numeric value.

Like other Simulink blocks, MATLAB Function blocks support an integer-based enumerated type derived from the class Simulink.IntEnumType. The instances of the class represent the values that comprise the enumerated type. The allowable values for an enumerated type must be 32-bit integers, but do not need to be consecutive.

For example, the following MATLAB script defines an integer-based enumerated data type named PrimaryColors:

classdef(Enumeration) PrimaryColors < Simulink.IntEnumType
    enumeration
        Red(1),
        Blue(4),
        Yellow(8)
    end
end

PrimaryColors is restricted to three enumerated values:

You can exchange enumerated data between MATLAB Function blocks and other Simulink blocks in a model as long as the enumerated type definition is based on the Simulink.IntEnumType class.

For comprehensive information about enumerated data support in Simulink, see Enumerations in the Simulink documentation.

Back to Top

When to Use Enumerated Data

You can use enumerated types to represent program states and to control program logic, especially when you need to restrict data to a finite set of values and refer to these values by name. Even though you can sometimes achieve these goals by using integers or strings, enumerated types offer the following advantages:

• Provide more readable code than integers

• Allow more robust error checking than integers or strings

  For example, if you mistype the name of an element in the enumerated type, the code generation software alerts you that the element does not belong to the set of allowable values.

• Produce more efficient code than strings

  For example, comparisons of enumerated values execute faster than comparisons of strings.

Back to Top

Simple Example: Defining and Using Enumerated Types in MATLAB Function Blocks

• About the Example

• Class Definition: myMode

• Class Definition: myLED

• Simulink Model

• MATLAB Function Block: checkState

• How the Model Displays Enumerated Data

About the Example

The following example appears throughout this section to illustrate how MATLAB Function blocks exchange enumerated data with other Simulink blocks. This simple model uses enumerated data to represent the modes of a device that controls the colors of an LED display. The MATLAB Function block receives an enumerated data input representing the mode and, in turn, outputs enumerated data representing the color to be displayed by the LED.

This example uses two enumerated types: myMode to represent the set of allowable modes and myLED to represent the set of allowable colors. Both type definitions inherit from the built-in type Simulink.IntEnumType and must reside on the MATLAB path.

See Also.  

• Using Enumerated Data in MATLAB Function Blocks

• How to Define Enumerated Data Types for MATLAB Function Blocks

• How to Instantiate Enumerated Data in MATLAB Function Blocks

Class Definition: myMode

Here is the class definition of the myMode enumerated data type:

classdef(Enumeration) myMode < Simulink.IntEnumType
  enumeration
    OFF(0)
    ON(1)
  end
end

This definition must reside on the MATLAB path in a MATLAB file with the same name as the class, myMode.m.

Class Definition: myLED

Here is the class definition of the myLED enumerated data type:

classdef(Enumeration) myLED < Simulink.IntEnumType
    enumeration
        GREEN(1),
        RED(8),
    end
end

This definition must reside on the MATLAB path in a file called myLED.m. The set of allowable values do not need to be consecutive integers.

Simulink Model

The model that controls the LED display looks like this:

The model contains the following blocks:

MATLAB Function Block: checkState

The function checkState in the MATLAB Function block uses enumerated data to activate an LED display, based on the state of a device. It lights a green LED display to indicate the ON state and lights a red LED display to indicate the OFF state.

function led = checkState(state)
%#codegen
if state == myMode.ON
    led = myLED.GREEN;
else
    led = myLED.RED;
end

The input state inherits its enumerated type myMode from the Simulink step signal; the enumerated type of output led is explicitly declared as myLED:

Explicit enumerated type declarations must include the prefix Enum:. For more information, see Using Enumerated Data in MATLAB Function Blocks.

How the Model Displays Enumerated Data

Wherever possible, Simulink displays the name of an enumerated value, not its underlying integer. For instance, Display blocks display the name of enumerated values. In this example, when the model simulates for less than 10 seconds, the step signal is 0, resulting in a red LED display to signify the off state:

Similarly, if the model simulates for 10 seconds or more, the step signal is 1, resulting in a green LED display to signify the on state:

Simulink scope blocks work differently. For more information, see Enumerations and Scopes.

Back to Top

Using Enumerated Data in MATLAB Function Blocks

Here is the basic workflow for using enumerated data in MATLAB Function blocks:

Back to Top

How to Define Enumerated Data Types for MATLAB Function Blocks

You define enumerated data types for MATLAB Function blocks in the same way as for other Simulink blocks. The basic workflow is:

1. Create a class definition file.

2. Define enumerated values in an enumeration section.

3. Optionally override default methods in a methods section.

4. Save the MATLAB file on the MATLAB path.

For complete descriptions of each procedure, see Specifying an Enumerated Data Type.

Back to Top

How to Add Enumerated Data to MATLAB Function Blocks

You can add inputs, outputs, and parameters as enumerated data, according to these guidelines:

To add enumerated data to a MATLAB Function block:

1. In the MATLAB Function Block Editor, select Tools > Edit Data/Ports.

   The Ports and Data Manager dialog box appears with the General pane selected.

2. In the Name field, enter a name for the enumerated data.

   For parameters, the name must match the enumerated masked parameter or workspace variable name.

3. In the Type field, specify an enumerated type.

   To specify an explicit enumerated type:

   1. Select Enum:<class name> from the drop-down menu in the Type field.

   2. Replace <class name> with the name of an enumerated data type that you defined in a MATLAB file on the MATLAB path.

      For example, you can enter Enum:myLED in the Type field. (See How to Define Enumerated Data Types for MATLAB Function Blocks.)

      Note   The Complexity field disappears when you select Enum:<class name> because enumerated data types do not support complex values.

      For example, the following output led has an explicit enumerated type, myLED:

      

   To inherit the enumerated type from a connected Simulink signal (for inputs only):

   1. Select Inherit:Same as Simulink from the drop-down menu in the Type field.

      For example, the following input state inherits its enumerated type myMode from a Simulink signal:

      

4. Click Apply.

Back to Top

How to Instantiate Enumerated Data in MATLAB Function Blocks

To instantiate an enumerated type in a MATLAB Function block, use dot notation to specify ClassName.EnumName. For example, the following MATLAB function checkState instantiates the enumerated types myMode and myLED from Simple Example: Defining and Using Enumerated Types in MATLAB Function Blocks. The dot notation appears highlighted in the code.

function led = checkState(state)
%#codegen

if state == myMode.ON
    led = myLED.GREEN;
else
    led = myLED.RED;
end

Back to Top

Operations on Enumerated Data

Simulink software prevents enumerated values from being used as numeric values in mathematical computation (see Enumerated Values in Computation).

The code generation software supports the following enumerated data operations:

• Assignment (=)

• Relational operations (==, ~=, <, >, <=, >=, )

• Cast

• Indexing

For more information, see Operations on Enumerated Data Allowed for Code Generation.

Back to Top

Limitations of Enumerated Types

Enumerated types in MATLAB Function blocks are subject to the limitations imposed by the code generation software. See How Working with Enumerated Data Is Different for Code Generation in the Code Generation from MATLAB documentation.

Back to Top

Using Variable-Size Data in MATLAB Function Blocks

Using Global Data with the MATLAB Function Block

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit