Create Stateflow Charts for Execution as MATLAB Objects

To combine the advantages of state machine programming with the full functionality of MATLAB^®, create a standalone Stateflow^® chart outside of a Simulink^® model. Save the standalone chart with the extension .sfx and execute it as a MATLAB object. Refine your design by using chart animation and graphical debugging tools.

With standalone charts, you can create MATLAB applications such as:

MATLAB App Designer user interfaces that use mode logic to manage the behavior of widgets. See Design Human-Machine Interface Logic by Using Stateflow Charts.
Communication protocols and data stream processing applications that use sequential logic. See Model a Communications Protocol by Using Chart Objects.
Data Acquisition Toolbox™ or Instrument Control Toolbox™ applications that use timer-based logic to monitor and control external tasks. See Implement a Financial Strategy by Using Stateflow.

These applications can be shared and executed without requiring a Stateflow license. For more information, see Share Standalone Charts.

Construct a Standalone Chart

To construct a standalone Stateflow chart, open the Stateflow Editor by using the edit function. For example, at the MATLAB Command Window, enter:

edit chart.sfx

If the file chart.sfx does not exist, the Stateflow Editor opens an empty chart with the name chart. Otherwise, the editor opens the chart defined by the sfx file.

In the Stateflow Editor, create a standalone chart by combining states, transitions, data, and other elements. For more information, see Construct and Run a Stateflow Chart.

After you save the standalone chart, the help function displays information about executing it in MATLAB:

help chart.sfx

To close the standalone chart from the MATLAB Command Window, use the sfclose function:

sfclose chart

Create a Stateflow Chart Object

To execute a standalone chart in MATLAB, first create a Stateflow chart object. Use the name of the sfx file for the standalone chart as a function. Specify the initial values of data as name-value pairs. For example, suppose that you defined a standalone chart with data objects called data1 and data2. Then this command creates the chart object chartObject, initializes data1 and data2, and executes its default transition:

chartObject = chart(data1=value1,data2=value2)

To display chart information, such as the syntax for execution, the values of the chart data, and the list of active states, use the disp function:

disp(chartObject)

Execute a Standalone Chart

After you define a Stateflow chart object, you can execute the standalone chart by calling the step function (with data values, if necessary):

step(chartObject,data1=value1,data2=value2)

Alternatively, you can call one of the input event functions:

event_name(chartObject,data1=value1,data2=value2)

In either case, the values are assigned to local data before the chart executes.

If your chart has graphical or MATLAB functions, you can call them directly in the MATLAB Command Window. Calling a chart function does not execute the standalone chart.

function_name(chartObject,u1,u2)

Note

If you use nargin in a graphical or MATLAB function in your chart, nargin counts the chart object as one of the input arguments. The value of nargin is the same whether you call the function from the chart or from the MATLAB Command Window.

You can execute a standalone chart without opening the Stateflow Editor. If the chart is open, then the Stateflow Editor highlights active states and transitions through chart animation.

For the purposes of debugging and unit testing, you can execute a standalone chart directly from the Stateflow Editor. During execution, you enter data values and broadcast events from the user interface. For more information, see Execute and Unit Test Stateflow Chart Objects.

You can execute a standalone chart from a MATLAB script, a Simulink model, or an App Designer user interface. For more information, see:

Stop Chart Execution

To stop executing a chart, destroy the chart object by calling the delete function:

delete(chartObject)

After the chart object is deleted, any handles to the chart object remain in the workspace, but become invalid. To remove the invalid handle from the workspace, use the command clear:

clear chartObject

If you clear a valid chart object handle and there are other handles to the same chart object, the chart object is not destroyed. For example, when you are executing a chart, the Stateflow Editor contains internal handles to the chart object. Clearing the chart object handle from the workspace does not destroy the chart object or remove the chart animation highlighting in the editor. To reset the animation highlighting, right-click the chart canvas and select Remove Highlighting.

Share Standalone Charts

You can share standalone charts with collaborators who do not have a Stateflow license.

If your collaborators have the same or a later version of MATLAB than you have, they can execute your standalone charts as MATLAB objects without opening the Stateflow Editor. Chart animation and debugging are not supported. Run-time error messages do not link to the state or transition in the chart where the error occurs.

Note

To run standalone charts that you saved in R2019a or R2019b, your collaborators must have the same version of MATLAB.

If your collaborators have an earlier version of MATLAB, export a standalone chart to a format that they can use. You can only export to R2019a and later releases. To complete the export process, you need access to the versions of Stateflow from which and to which you are exporting.

Using the later version of Stateflow, open the standalone chart.
On the State Chart tab, select Save > Previous Version.
In the Export to Previous Version dialog box, specify a file name for the exported chart.
From the Save as type list, select the earlier version to which to export the chart.
Click Save.
Using the earlier version of Stateflow, open and resave the exported chart.

To export a chart from the MATLAB Command Window, call the Stateflow function exportToVersion. For more information, see Export Chart to an Earlier Version of MATLAB.

Note

Attempting to execute an exported chart before resaving it will result in an error.

Properties and Functions of Stateflow Chart Objects

A Stateflow chart object encapsulates data and operations in a single structure by providing:

Private properties that contain the internal state variables for the standalone chart.
A step function that calls the various operations implementing the chart semantics.

A chart object can have other properties and functions that correspond to the various elements present in the chart.

Standalone Chart Elements	Chart Object Elements
Local and constant data	Public properties
Input events	Functions that execute the chart
Graphical and MATLAB functions	Functions that you can call from the MATLAB Command Window

Chart Object Configuration Options

When you create a chart object, you can specify chart behavior by including these configuration options as name-value pairs.

Configuration Option	Description	Example
`-animationDelay`	Specify the delay that the chart animation uses to highlight each transition segment. The default value is `0.01` seconds. To produce a chart with no animation delays, set to zero.	Create a chart object that has slow animation by specifying one-second delays. chartObject = chart('-animationDelay',1)
`-enableAnimation`	Enable chart animation and debugging instrumentation. The default value is `true`.	Create a chart object that has animation and debugging instrumentation disabled. chartObject = chart('-enableAnimation',false)
`-eventQueueSize`	Specify the size of the queue used for events and temporal logic operations. The default value is `20`. To disable the queuing of events, set to zero. For more information, see Events in Standalone Charts.	Create a chart object that ignores all events without warning if they occur when the chart is processing another operation. chartObject = chart('-eventQueueSize',0)
`-executeInitStep`	Enable the initial execution of default transitions. The default value is `true`.	Create a chart object but do not execute the default transition. chartObject = chart('-executeInitStep',false)
`-warningOnUninitializedData`	Enable the warning about empty chart data after initializing the chart object. The default value is `true`.	Eliminate the warning when creating a chart object. chartObject = chart('-warningOnUninitializedData',false)

Initialization of Chart Data

In the Stateflow Editor, you can use the Symbols pane to specify initial values for chart data. When you create a chart object, chart data is initialized in alphabetical order according to its scope. Constant data is initialized first. Local data is initialized last.

If you use an expression to specify an initial value, then the chart attempts to resolve the expression by:

Using the values of other data in the chart.
Calling functions on the search path.

For example, suppose that you specify an initial value for the local data x by using the expression y. Then:

If the chart has a constant called y, y is initialized before x. The local data x is assigned the same initial value as y.
If the chart has a local data called y, x is initialized before y. The local data x is assigned to an empty array. If the configuration option -warningOnUninitializedData is set to true, a warning occurs.
If the chart has no data named y, x is initialized by calling the function y. If the file y.m is not on the search path, this error occurs:
```
Undefined function or variable 'y'.
```

Stateflow does not search the MATLAB workspace to resolve initial values, so this error occurs even if there is a variable called y in the MATLAB workspace.

Capabilities and Limitations

Supported Features

Classic chart semantics with MATLAB as the action language. You can use the full functionality of MATLAB, including those functions that are restricted for code generation in Simulink. See Execute Stateflow Chart Objects Through Scripts and Models.

Note
In standalone Stateflow charts, the operating system command symbol ! is not supported. To execute operating system commands, use the function system.
Exclusive (OR) and Parallel (AND) state decomposition with hierarchy. See Define Exclusive and Parallel Modes by Using State Decomposition and Use State Hierarchy to Design Multilevel State Complexity.
Flow charts, graphical functions, and MATLAB functions. See Reusable Components in Charts.
Conversion of MATLAB code to graphical functions by using the Pattern Wizard. See Convert MATLAB Code into Stateflow Flow Charts.
Chart local and constant data without restriction to type. See Execute and Unit Test Stateflow Chart Objects.
Input events. See Design Human-Machine Interface Logic by Using Stateflow Charts.
Operators hasChanged, hasChangedFrom, and hasChangedTo that detect changes in the values of local data.
Note
Standalone Stateflow charts do not support change detection on an element of a matrix or a field in a structure.
Temporal logic operators:
- after, at, and every operate on the number of input events, chart invocations (tick), and absolute time (sec). Use these operators in state on actions and as transition triggers.
- count operates on the number of chart invocations (tick).
- temporalCount operates on absolute time (sec, msec, and usec).
- elapsed operates on absolute time (sec).
Standalone charts define absolute-time temporal logic in terms of wall-clock time, which is limited to 1 millisecond precision.
Function getActiveStates to access the states that are active during execution of the chart. To store the active states as a cell array, enter:
```
states = getActiveStates(chartObject)
```
Stateflow function exportAsClass that exports the standalone chart as the equivalent MATLAB class. Use this function to debug run-time errors that are otherwise difficult to diagnose. For example, suppose that you encounter an error while executing a Stateflow chart that controls a MATLAB application. If you export the chart as a MATLAB class file, you can replace the chart with the class in your application and diagnose the error by using the MATLAB debugger. To export the chart chart.sfx as a class file chart.m, enter:
```
Stateflow.exportAsClass("chart.sfx")
```
When you execute the MATLAB class, the Stateflow Editor does not animate the original chart.

Limitations

Content specific to Simulink:

Sample time and continuous-time semantics.
C action language.
Simulink functions and Simulink subsystems as states.
Input, output, and parameter data.
Data store memory data.
Output and local events.
Input, output, and local messages.

Other limitations:

No Mealy or Moore semantics.
No State Transition Tables.
No Truth Table functions.
No state-parented local data or functions.
No transition actions (actions that execute after the source state for the transition is exited but before the destination state is entered).