Product Support

1820 - How Do I Use the Stateflow API?

What Is the Stateflow API?
How Do I Create a New Stateflow chart?
How Do I Access the Stateflow Machine Object?
How Do I Access the Stateflow chart Object?
How Do I Create New Objects in the Chart?
How Do I Add Default Transitions to a Chart?
How Do I Make Parallel States?
How Do I Add a History Junction?
How Do I Add Data and Events?
How Do I Add Multiline Labels?

Section 1: What Is the Stateflow API?

The Stateflow Application Program Interface (API) is a tool of convenience that allows you to create or edit Stateflow diagrams with MATLAB commands. Throughout this example, Stateflow API commands are used to create and manipulate the Stateflow diagram shown below.

Section 2: How Do I Create a New Stateflow chart?

Close all Simulink models
Use the MATLAB function SFNEW to create an untitled Simulink model with a new Stateflow chart in it.
```
sfnew
```

You must first close all existing models if you would like to use only the SFNEW function. If you do not wish to close all your existing models, you can use the following instructions instead:

First, find what Stateflow charts currently exist, and assign the handles for those charts to a variable, oldMachines:
```
oldMachines=find(sfroot,'-isa','Stateflow.Machine');
```
Now, create a new Stateflow chart and then assign the handles for all charts to a new variable, allMachines:
```
sfnew
allMachines=find(sfroot,'-isa','Stateflow.Machine');
```
To isolate the new Stateflow chart, use the SETDIFF function to determine the difference between allMachines and oldMachines and assign the handles for the new chart the variable myNewMachine:
```
myNewMachine=setdiff(allMachines, oldMachines);
```

Section 3: How Do I Access the Stateflow Machine Object?

In the Stateflow API, each model you create or load into memory is represented by an object of type Machine. In the Stateflow API, all Machine objects are contained in the Stateflow API Root object. Therefore, the first handle that you require in the Stateflow API is a handle to the Root object:

rt=sfroot

The MATLAB function SFROOT returns the Stateflow Root object, and the workspace variable rt now becomes a handle to the Stateflow Root object. You can use this handle to access the Machine object representing the new untitled Simulink model. First, locate the Machine object using the MATLAB FIND function. The FIND function in Stateflow takes the form

objArray = thisObject.find(Specifier,Value, ...)

where objArray is an array of Machine objects meeting the criteria specified in the FIND parameters, and thisObject is the handle of the object for which to find contained objects. In this example, thisObject is an object of type Root, represented by the rt variable. The (Specifier, Value) pairs specify the criteria for the FIND function. Several options exist for (Specifier, Value) pairs. The -isa specifier, followed by the Stateflow.Machine value, results in a search for Stateflow objects of type Machine.

Find the Machine object and assign it a handle, m, as follows:

m=rt.find('-isa','Stateflow.Machine')

The workspace variable m now represents the Machine object corresponding to the new Stateflow chart.

Section 4: How Do I Access the Stateflow chart Object?

Access the new chart object and assign it the workspace variable chart as follows:

chart = m.find('-isa','Stateflow.Chart')

Open the Stateflow chart with the following API command:

chart.view

The preceding command calls the view method of the chart object whose handle is chart. You should now have an empty Stateflow chart open in front of you.

Section 5: How Do I Create New Objects in the Chart?

This section addresses how to create states, substates and transitions within your Stateflow chart.

Creating States and Substates

Using the handle for the Chart object, the Stateflow API has various constructors for adding objects to a Stateflow chart. For example
```
sA=Stateflow.State(chart)
```
creates a state (represented by the workspace variable sA) in the parent chart (represented by the workspace variable chart). The variable sA is now a state object with several properties that can be specified. To view these properties, type
```
sA.get
```
in the MATLAB Command Window. These properties can be set as follows:
```
sA.Name='A';

sA.Position=[50 50 310 200];
```
The state, represented by the variable sA, now has a name and a position. The position and size of a state in the Stateflow chart is given in the form of a 1-by-4 array [x y w h], where x and y are the coordinates for the state's left upper vertex relative to the upper left vertex of the Stateflow diagram editor workspace, and w and h are the width and height of the state, respectively.
You can add additional states to the chart using the Stateflow API State constructor. If a new state is to be a substate of a previous state, the input argument to the State constructor must be the state in which the substate is to be placed. For example
```
sA1 = Stateflow.State(sA);
sA1.Name = 'A1';
```
creates substate A1 in state A. You can then set the Position parameter to place the substate A1 in the correct position within state A:
```
sA1.Position = [80 120 90 60];
```
You can also add a second substate to state A:
```
sA2 = Stateflow.State(sA)
sA2.Name = 'A2';
sA2.Position = [240 120 90 60];
```
State A now has two substates, A1 and A2.

Creating Transitions

You can add a transition to a chart using the Stateflow API Transition constructor as follows:

tA1A2 = Stateflow.Transition(chart)
tA1A2.source = sA1;
tA1A2.destination = sA2;
tA1A2.sourceOclock = 3;
tA1A2.destinationOclock = 9;

The above commands create a transition from state A1 to state A2. The source and destination properties specify from which states the transition will begin and end. The SourceOclock and DestinationOclock properties allow you to specify where on the state the transition begins or ends. In our example, sourceOclock is set to 3, which results in the transition tA1A2 beginning at the 3 o'clock position on state A1. Therefore, the transition will begin at the right side of the state. If sourceOclock were set to 6, 9 or 12 , then the transition would begin at the bottom, left, or top side of the state, respectively.
To add a label to the transition, use the LabelString property as follows:
```
tA1A2.LabelString = 'E1';
```
You can position the transition label by any of the following:
1. Obtaining the current position of the label
```
pos=tA1A2.LabelPosition;
```
2. Increasing the first element of the position, corresponding to the label's x coordinate
```
pos(1)=pos(1)+20; 
```
3. Modifying the position of the label to use this new position
```
tA1A2.LabelPosition = pos;
```

Section 6: How Do I Add Default Transitions to a Chart?

A default transition is constructed using the same Stateflow Transition constructor as a regular transition. The source, however, is specified via coordinates, rather than via the state and clock positions shown previously.

Create the transition:
```
dtA=Stateflow.Transition(chart)
```

Set the destination point:

dtA.Destination = sA1;
dtA.DestinationOclock = 0;

Determine the x and y coordinates of the source endpoint. For the x coordinate, find the middle of the state by averaging the x position and the width of the state:
```
xsource = (sA1.Position(1) + sA1.Position(3)/2);
```
Use the y position of the state and subtract the desired length of the default transition line:
```
ysource=sA1.Position(2) - 20;
```
Set the SourceEndPoint property of the transition to the previously calculated xsource and ysource values:
```
dtA.SourceEndPoint = [xsource ysource];
```

Section 7: How Do I Make Parallel States?

First, add a fourth state to the Stateflow diagram.

sB=Stateflow.State(chart)
sB.Name='B';
sB.Position = [380 50 310 200];

Note: You may have to increase the size of the Stateflow diagram window, or zoom out on the diagram, in order to view all states.

Next, set the Decomposition property for the parent of the two states that you want to make parallel to PARALLEL_AND. Here, the parent of states A and B is the Chart object:

chart.Decomposition = 'PARALLEL_AND';

Section 8: How Do I Add a History Junction?

Add a junction to the Stateflow chart and set the junction's Type property to be HISTORY:

sJ = Stateflow.Junction(chart)
sJ.Type='HISTORY'

Next, specify the position of the history junction. The Position property of the junction has two properties that can be specified, the Center and the Radius. The Center property is a 1-by-2 array, [x y], specifying the x and y coordinates of the center of the history junction. The following command places the history junction in the bottom left corner of State A:

sJ.Position.Center = [70 220]

Section 9: How Do I Add Data and Events?

Adding Events

Add an event to the Stateflow chart using the Event constructor:
```
sE1=Stateflow.Event(chart)
```
Set event properties as done previously for Transitions. As shown below, you can set the scope of the event using the Scope property. Here, the event is assigned as an input from Simulink.
```
sE1.Name = 'E1';
sE1.Scope = 'INPUT_EVENT';
```
Since the scope is set to Input from Simulink, the chart icon in Simulink will now have a trigger input at the top of the block.

Adding Data

You can add data to a Stateflow chart the same way an event is added. The properties can also be specified the same wayy. Note that two properties, InitFromWorkspace and SaveToWorkspace, allow for the data to be read into Stateflow from the MATLAB workspace, or for the final value to be saved to the MATLAB workspace from Stateflow. These two properties take logical inputs as values; 1 if the property is on, 0 if the property is off.

sD1 = Stateflow.Data(chart)
sD1.Name = 'out_data'
sD1.Scope = 'LOCAL_DATA'
sD1.SaveToWorkspace = 1

Note: To view Events or Data corresponding to a Stateflow chart, select Explorer from the Tools pull-down menu in the Stateflow chart window.

Section 10: How Do I Add Multiline Labels?

Multiline labels are often required for various actions to take place when a state is active or inactive. To add a multiline label:

Create a state B1 as a substate in State B

sB1 = Stateflow.State(sB)
sB1.Name = 'B1';
sB1.Position = [440 70 200 150];

Add a multiline label to State B1. Stateflow API implements multiline labels using the SPRINTF command. The following code will add a string, consisting of the SPRINTF command, as the label to State B1:
```
str = sprintf('B1\nen:out_data=out_data+1;')
sB1.LabelString = str;
```
The \n in the SPRINTF command serves as a return line character. Now, every time state B1 is entered, the variable out_data will be increased by 1.

Products & Services	Industries	Academia	Support	User Community	Company