itemis CREATE for Eclipse

itemis CREATE for Eclipse is our most advanced version, offering additional features that are currently exclusive to the Eclipse platform. This version is designed for users who need advanced capabilities beyond the standard web version.
Whether you’re looking for enhanced testing features, deeper integration with C/C++, or support for multi-state machines, itemis CREATE for Eclipse provides everything you need to take your development to the next level.

If your project requires complex testing scenarios or you are working with embedded systems that rely on C/C++ integration, this is the ideal version for you.
The following features are currently only available in our Eclipse-based version:

Testing framework to test your state machines with unit tests
Multi state machine modelling define and execute a set of connected state machines.
Deep integration with the C and C++ programming language to directly access C variables, types etc.
SCXML support to edit, simulate and export statecharts compliant to the SCXML standard.
Advanced simulation and debugging with breakpoints and snapshots

You can download itemis CREATE for Eclipse here.

Installation

In order to start working with itemis CREATE, you have to install the software on your computer. The installation process is pretty simple, just download the archive, unpack it, and start the executable.

In case you want to install itemis CREATE into an existing Eclipse instance, read section Installing to an existing Eclipse instance.

Installing on Windows

Installing itemis CREATE on a Windows machine boils down to the following steps:

Unpack the downloaded archive (just double-click on it)
Start the application with a double-click on the executable SCT.exe.
Upon the first start you will be asked to select a workspace. This is the folder where your project data will be located. Choose a folder as you like. You can still change the workspace later via File → Switch Workspace in the main menu.

Congratulations, you have just installed and started itemis CREATE!

You can proceed now by installing a itemis CREATE license or by creating your first itemis CREATE project.

Installing on macOS

Installing itemis CREATE on macOS boils down to the following steps:

Unpack the downloaded archive (just double-click on it)
Move the unpacked application bundle to your Applications folder. This is required to successfully perform updates later on.
Start the application with a double-click. Upon the first start, Mac OS X will verify the application and show you a security warning, indicating that you did not download the application from Apple’s App Store. Just click Open and ignore that warning.
Upon the first start you will be asked to select a workspace. This is the folder where your project data will be located. Choose a folder as you like. You can still change the workspace later via File → Switch Workspace in the main menu.

Congratulations, you have just installed and started itemis CREATE!

You can proceed now by installing a itemis CREATE license or by creating your first itemis CREATE project.

Installing on Linux

Installing itemis CREATE on a Linux machine boils down to the following steps:

Unpack the downloaded archive (just double-click on it)
Start the application with a double-click on the executable SCT.exe or with ./SCT command in your command-line tool.
Upon the first start you will be asked to select a workspace. This is the folder where your project data will be located. Choose a folder as you like. You can still change the workspace later via File → Switch Workspace in the main menu.

Congratulations, you have just installed and started itemis CREATE!

You can proceed now by installing a itemis CREATE license or by creating your first itemis CREATE project.

Installing to an existing Eclipse instance

This chapter outlines the steps to install itemis CREATE on an existing Eclipse instance. Ensure Eclipse is up and running before adding itemis CREATE as an additional plugin.

Please note: On macOS, this only works if your .app file is located in your Applications folder.

Attention!

itemis CREATE is compatible with Eclipse versions released within the last two years.

In the the Help menu, select Install New Software

The Install wizard opens. Click on the Add... button in the upper-right corner.

In the dialog that appears, enter the name and URL of the update repository. You can find the repository URL on the itemis CREATE download page.

Eclipse connects to the repository and displays available software. Select the items you wish to install and click Next >..

If there are any issues with compatibility, Eclipse will attempt to resolve them automatically. Choose the best solution and click Next >..

Review the items to be installed and click Next.

Select the radio button labelled I accept the terms of the license agreements then click Finish.

Eclipse will download and install the software. Once finished, it will prompt you to restart Eclipse. Choose to restart immediately or later.

After restarting, Eclipse will show the Welcome window, now featuring itemis CREATE.

Updating itemis CREATE

Attention!

itemis CREATE is compatible with Eclipse versions released within the last two years.

To check whether a new itemis CREATE release is available and to install it, select the Help → Check for Updates menu item.

If Eclipse finds any software items to be updated – not just itemis CREATE –, it will guide you through the process of updating them. Generally Eclipse has to be restarted afterwards to have any changes take effect.

You can configure Eclipse as follows to automatically check for updates:

Select the Window → Preferences menu item. The Preferences dialog opens.

Go to the Install/Update → Automatic Updates section. Here you can configure whether and when Eclipse should check for updates and what to do when it finds any.

Installing an itemis CREATE license

itemis CREATE come with an evaluation license that is valid for 30 days. If you want to continue working with itemis CREATE beyond that period of time you have to acquire a license .

We offer free of charge academic licenses hich include the complete itemis CREATE feature set. If you think you meet the requirements for these licenses, you can apply for them on our website .

The license manager documentation describes how you can install a license file or configure a license server for floating licenses. To access that documentation, select Help → Help Contents from itemis CREATE’s main menu, then open the itemis CREATE License Management documentation.

Editing statecharts

This section explains how you can edit statecharts using itemis CREATE.

Creating and deleting statecharts

Statecharts are comprised in statechart model files. The filename extension of these files is .sct. Their internal format is XML Metadata Interchange or XMI, which is an XML language.

Creating a statechart

In order to create a new statechart, use the project explorer view:

Right-click on a project or on a folder you want to create the new statechart in. The context menu appears.
In the context menu, select New → Other…. The New dialog appears.
In the New dialog, select itemis CREATE → Statechart Model and click Next >. The New itemis CREATE wizard appears.
In the File Name field, enter a filename for the statechart file to be created. The filename extension must be .sct.
Click Next >.
In the wizard, select a statechart domain. Which domains are available depend on your itemis CREATE license. The Default domain for “normal” statecharts without any language integration is always available.
Click Finish.
If the Confirm Perspective Switch dialog appears, answer its question as you see fit.
The new statechart file is created in the location you specified and opened in the statechart editor.

Copying an existing statechart

In order to copy an existing statechart file, proceed as follows:

In the project explorer view, right-click on the statechart’s filename. The context menu appears.
In the context menu, select Copy.
Right-click on the project or folder you want to insert the copied file in. The context menu appears.
In the context menu, select Paste.
If there is already a file with the same name as the file to be copied in the target project or folder – which is always the case if you are copying a file within the same project or directory –, the Name conflict dialog appears.
1. Specify a name for the new file. The Name conflict dialog and makes a suggestion, which you can modify.
2. Click OK to paste the new file to the target project or folder.
If the target project or folder does not contain a file with the same name as the source file, the copied file will have the same name as the original.

Deleting a statechart

In order to delete a statechart file, proceed as follows:

Right-click on the statechart file in the Project Explorer view. The context menu appears.
In the context menu, select Delete.
The Delete Resources confirmation dialog appears. You have three choices:
1. Click Preview > to inspect what the delete operation is going to do, if confirmed.
2. Click Cancel to cancel the delete operation. Your statechart file will persist.
3. Click OK to actually delete the statechart file.

Editor UI

itemis CREATE comes with a statechart editor. This section explains the statechart editor and how you can use it to graphically edit your statecharts.

The SC Modeling perspective

SC Modeling is an Eclipse perspective supporting the modeling of statecharts. The perspective defines the following views and their positions:

Project Explorer (left): This view displays your workspace and projects, folders, and files contained therein. You can also use the Project Explorer to inspect the internal structure of your statechart models.
Properties (bottom): This view displays properties, regarding the semantic model or the graphical appearance, of the selected element in the statechart editor. You can directly edit these properties in this view.
Problems (bottom): This view displays errors and warnings existing in your workspace. Double-clicking on an entry typically opens the location of the respective error or warning.
Tasks (bottom): This view displays any tasks you have defined in your statechart previously. Section "Working with statechart tasks" explains how to do that.
Outline (right): This view is a bird’s eye view on the opened statechart. It also indicates the current viewport for better orientation in large models.

You can change the positions and sizes of these views, you can delete them, or add more views, using standard Eclipse mechanisms.

Canvas

The canvas is the statechart editor’s drawing area. When you create a new statechart model, the canvas comprises the definition section and a single region.

The following list gives an overview of what kind of actions you can perform on the canvas:

Add or remove a region
- To add a region to the canvas, select Region in the editor palette, then click on the canvas location you want to place the region.
- To remove a region from the canvas, select the region, then
  - press the [Del] key, or
  - select Delete from model in the context menu, or
  - select Edit → Delete in the menu bar.
Zooming
- Press and hold [Ctrl] and turn the mouse wheel to zoom in or out.
- Right-click on the canvas to open its context menu. In the context menu, several zooming functions are available in the Zoom submenu.

Editor palette

The editor palette provides you with a set of various actions and statechart editing tools. By default, the palette is located right of the canvas, but you can also drag it to the left.

You can hide the palette by clicking on the small triangle on the right-hand side in the palette’s title bar. Click on the triangle again to make the palette reappear.

Editor palette

Editing action tools

Below its title bar, the palette contains a toolbar with the following editing action tools (from left to right):

Symbol	Action	Description
	Select	Left-click at an object to select it.
	Zoom in	Left-click to zoom in. Press `[Shift]` and left-click to zoom out. Drag to zoom to selection.
	Zoom out	Left-click to zoom out. Press `[Shift]` and left-click to zoom in.
	Note	Create a note, a text or a note attachment.

Statechart elements tools

The palette comprises a couple of tools serving to add statechart elements to the diagram (from top to bottom):

Symbol	Description
	Adds a transition.
	Adds a state.
	Adds a composite state.
	Adds an orthogonal state.
	Adds a region.
	Adds an entry point.
	Adds a shallow history state.
	Adds a deep history state.
	Adds a final state.
	Adds an exit point.
	Adds a choice.
	Adds a synchronization.

Outline view

The Outline view allows you to keep the big picture of your statechart model and navigate it easily. It displays the model outline either as a graphical overview or as a hierarchical outline.

Graphical overview

Click on the Overview icon in the Outline view’s title bar to engage the graphical overview.

While the statechart editor window – due to zooming or the size of the whole statechart – might display a cutout only, the Outline view shows the whole diagram as an overview. It is scaled down as needed to completely fit into the available area.

A light-grey overlay rectangle represents the statechart editor’s viewport.

Drag this rectangle with your mouse to move the statechart editor’s viewport.
Click into the outline view to position the rectangle’s center to the point you have clicked.

Hierarchical outline

Click on the Outline icon in the Outline view’s title bar to engage the hierarchical outline.

Problems view

The problems view by default lists all errors, warnings and other types of messages in all open projects.

The messages are grouped by message type, typically “error” or “warning”. Click on the show/hide symbol to open or close the respective message group’s contents.

Double-clicking on an entry in the problems view takes you directly to the resource or model element causing the problem.

You can configure the problems view in a multitude of ways, e.g., to group entries by different criteria, to sort them in a specific way, or to restrict them to certain projects. You can even define multiple problems views, each with different selection or display criteria.

To start configuring the problems view, click on the small triangle pointing downwards in the Problem view’s title bar. A drop-down menu will open and display the options that you have.

To configure the view click the small triangle pointing downwards in the view’s title bar. A drop-down menu opens and shows the options you have.

Please note: The problems view reflects the error/warning status of persisted statecharts only, i.e., statecharts that have been saved to the statechart file. If you create an error during editing, for example a new state that is not (yet) connected to any other state, the respective element will have an error marker on the canvas, however, it will not appear in the problems view, unless you have saved the statechart. The same holds true for resolved errors: An error will disappear from the problems view only after you saved the fixed error to the statechart file.

Editing states and other nodes

Generally, there are two different ways to edit states and other nodes:

Using the graphical editor to modify a node in the diagram.
Selecting a node and editing its properties in the properties view.

There are certain properties that you can only edit with one of these methods. For example, to modify a state’s position or size, you have to use the statechart editor. To change a state’s transitions' priorities, you have to use the properties view.

Editing transitions

Generally, there are two different ways to edit transitions:

Using the graphical editor to modify a transition in the diagram.
Selecting a transition and editing its properties in the properties view.

There are certain properties that you can only edit with one of these methods. For example, to add guidance points to a transition’s arrow, you have to use the statechart editor. To change a transition’s arrow’s color, you have to use the properties view.

Editing the documentation of states and transitions

You can attach documentation to states and transitions. In this context, documentation is some text offering additional information to a human reader. In the model, it does not serve any functional purpose.

By default, a state’s rectangle shows the state’s behaviour, and a transition shows its expression alongside its arrow. You can instead display an objects’s documentation, i.e., the documentation of a state or transition:

Right-click on the object.
In the context menu, select Toggle documentation.
The object now shows its documentation in place of the formerly displayed text.

In order to return back to the object’s normal view, select Toggle documentation again.

While the documentation is shown, you can modify it in the statechart editor. Double-click on the documentation text field to start editing it. Click outside the state or transition to quit editing.

The properties view of states and transition always shows both documentation and statechart language elements side by side in different compartments. This might be a more comfortable way of editing any of them.

Editing regions

In a statechart model, you can have

top-level regions, which are directly placed on the canvas, and
regions inside of composite or orthogonal states.

Their graphical representation differ somewhat, thus editing them is also somewhat different.

Editing top-level regions

You can place a top-level region anywhere on the canvas, and you can change its size at will. To change the location or the size of a region, use the graphical editor. Drag the region to move it elsewhere. Use a selected region’s handles to resize it.

Editing regions in orthogonal states

Regions inside an orthogonal or composite state are confined by their enclosing state. They are sized automatically, depending on their contents, and they are arranged either vertically or horizontally.

You can toggle between vertical and horizontally representation of regions in an orthogonal state as follows:

Right-click on the orthogonal state’s title. The context menu opens.
In the context menu, select Toggle Subregion Alignment.
The layout of the regions switches from horizontal to vertical or vice versa.

Changing the name of a region

You can change the name of a region in the statechart editor as well as in the properties view.

In the statechart editor,
- double-click on the region’s current name,
- edit the name in the text field that appeares after double-clicking,
- press the [Return] key to finish editing.
In the properties view,
- modify the Region Name property. It is a region’s only property you can access through the properties view.

Editing hierarchies

Statecharts can get rather big and complex. Composite states are a way to reduce complexity and thus make statecharts easier to create, comprehend and maintain. A composite state comprises a state machine of its own within a region. The states belonging to such a nested state machine are called substates. Orthogonal states are a generalization of composite states, comprising two or more independent state machines in separate regions that are executed virtually concurrently.

A complementary way to mitigate the size of large statecharts are subdiagrams. A subdiagram externalizes the possibly large region(s) contained by a composite state into a subdiagram. In this case the composite state no longer displays its substates. Instead it is visualized very similarly to a regular state. The only difference is a small icon in its lower right corner, marking it as a composite state and giving access to its internal structure: the subdiagram. This way a composite state consumes much less space and gives the user the opportunity to better envision the overall picture. Section "Using subdiagrams" explains how to work with subdiagrams, how to create them and how to inline them again, if needed.

Composite states resp. subdiagrams can be nested to any depth.

The statechart editor provides various refactorings to support editing these hierarchies.

Using subdiagrams

As a statechart grows, it may easily become too big to still give a comprehensive overview of the whole model. Subdiagrams come as a solution. Basically, you can “fold away” a composite state into a subdiagram.

Composite state

When the Extract Subdiagram refactoring is executed on a composite state, all containing regions are extracted into a separate diagram. The composite state no longer clutters the diagram with all its internal details, but instead appears almost like a normal state. The only difference is a small decorator icon in the lower-right corner of the state, indicating the existence of a subdiagram. When you hover over this decorator with the mouse cursor, you’ll see a small preview of the subdiagram’s content.

Extracting a subdiagram creates entry and exit points in the subdiagram as needed.

Subdiagram pop-up window

A click on the decorator opens the subdiagram in a separate editor tab. The breadcrumb at the top allows easy navigation throughout the hierachy levels.

Subdiagram editor

Using the inlining subdiagram refactoring, you can turn a subdiagram back into the composite state.

Using the definition section

By default, a statechart’s definition section is positioned at the left-hand side of the canvas.

You can edit the definition section in two different modes: Legacy mode and the new pinnable mode. Starting with version 3.3 of itemis CREATE the pinnable mode is the default editing mode.

Legacy mode

Legacy mode is the definition section’s traditional editing mode, which has been available in itemis CREATE for a long time already.

To edit the definition section, double-click into it and enter your statements. While editing, syntax highlighting is applied to the text in the definition section. To quit editing, click outside the definition section. Now the text will appear without any syntax coloring.

Technically, the definition section is part of the canvas. If you print the canvas or save it to an image file, the definition section is included in the result. Definition section and top-level region are always scrolled in sync, which might have the rather unwanted effect that your statechart diagram is scrolled off your screen if you have a very long definition section and you are editing something down below in it.

Pinnable mode

Pinnable mode is an improved editing mode that has been introduced with itemis CREATE 3.20. However, it is slightly incompatible with previous versions, so you have the choice to use it or not.

In pinnable mode, the definition section can be either part of the canvas (“inlined”) or not (“pinned”), and you can change that at will. The definition section comes with a little pin symbol "pin" at its top-left. Click on it, and the definition section will be detached from the canvas. This has a couple of advantages:

You can edit definition section and graphical statechart independently of each other. In particular, you can scroll either area as you like, while the other one will remain where it is.
The definition section is syntax-highlighted all the time.
If you don’t need to see the definition section you can collapse resp. fold it away by clicking on the little triangle in the top-left corner. Click on it once more to make the definition section visible again. Another way to expand the definition section is to click on the vertical bar labeled “Definition section”.

Collapsing the pinned definition section

Expanding the pinned definition section

By default, the pinned definition section takes 20 percent of the canvas' view, but you can resize it as you like.

You can unpin the definition section and inline it with the canvas. To do so, click on the pin symbol "pin" , which in the pinned state is in the definition section’s upper-right corner.

Please note: The definition section is available for top-level diagrams only. If you are editing a subdiagram you will need to use the Properties View to edit the definition of your statechart model.

Please also note: Pinning and inlining the definition section changes your statechart model. You have to save it in order to maintain the current status.

Pinning the statechart diagram definition section

Inlining the statechart diagram definition section

In the pinned definition section, you can edit the name of the statechart by changing the displayed text in the top-center of the section.

Changing the statechart name

Refactorings

Refactoring means modifying certain model aspects while maintaining the model’s semantics. The statechart editor allows for the refactoring of variables, events, interfaces, and states, including composite and orthogonal states. A state’s context menu contains the Refactor submenu with the individual refactoring actions explained below. Depending on certain conditions, a refactoring might be executable or not, which will be explained below.

Renaming variables, events and interfaces

Using the Rename refactoring, you can change the name of a variable, event or interface throughout your statechart model. Each occurrence of that name will be changed to the new name.

To initiate renaming, right-click on the name of a variable, event or interface in the diagram editor, in the definition section, or in a text field in the properties view, then select Rename ….

Renaming a variable

The Rename … dialog opens.
In that dialog, type the entity’s new name into the text field.
Click on OK to change each occurence of the old name to the new name.
Click on Cancel to not rename anything.

Folding incoming actions

When building a statechart model step by step, you may come into a situation where you have defined several transitions having the same target state and sharing a common set of actions.

The Fold Incoming Actions refactoring moves these actions from the transitions to the target state’s entry block. To preserve model semantics, only actions that are defined on all incoming transitions will be moved. Since the execution order must be preserved, the refactoring algorithm starts with the right-most action and proceeds action by action to the left. As soon as it detects an action that is not defined on all incoming transitions, it stops moving actions to the entry block.

Consider the following model:

Moving incoming actions to entry block

Only the most-right action y += 42 can be moved to the entry block of the target state. Although x += 1 is also a common action of both transitions, it cannot be moved to the target state, because the semantics of the B → Target transition would change, in that y = x would be executed before x had been incremented.

Another aspect to take into account are transitions leading to target states that are nested in composite states. Consider the following example:

Moving incoming actions into a nested state's entry block

Moving incoming actions into a nested state’s entry block

The actions y = x of the two incoming transitions leading to the Target state cannot be moved to Target's entry block, because doing so would change the model’s semantics. The reason is the composite state’s entry action x += 1. It will be executed after the action of transition A → Target and before the actions in the entry block of Target. Moving y = x from the transition to Target's entry block would change that order. The statechart editor pays regard to this constraint and prohibits the refactoring.

To fold incoming actions, right-click on the state to refactor, then select Refactor → Fold Incoming Actions in the context menu. The menu entry is active only if there are actual actions to move into the target state’s entry block, with the above rules applied.

Folding outgoing actions

The fold outgoing actions refactoring is similar to folding incoming actions, except that it moves actions from outgoing transitions to the source state’s exit block. To preserve model semantics, only actions that are defined on all outgoing transitions will be moved. Since the execution order must be preserved, the refactoring algorithm starts with the left-most action and proceeds action by action to the right. As soon as it detects an action that is not defined on all outgoing transitions, it stops moving actions to the exit block.

Preconditions for this refactoring are analog to "Folding incoming actions". Consider the following example:

Moving outgoing actions to exit block

Here, the actions y = x cannot be moved from the outgoing transitions to the exit block of the source state, because the composite state has an exit action. For the Source → A transition, the proper execution order is to first execute x += 1 of the nesting composite state’s exit block, followed by y = x of the transition. Moving y = x to the exit block of state Source would reverse this order and thus will be prohibited by the statechart editor.

To fold outgoing actions, right-click on the state to refactor, then select Refactor → Fold Outgoing Actions in the context menu. The menu entry is active only if there are actual actions to move into the source state’s exit block, with the above rules applied.

Unfolding entry actions

This refactoring is the reverse of folding incoming actions. It removes all entry actions from a target state and appends them to each of its incoming transition’s actions.

Transitions crossing the borders of composite states enclosing the target state might inhibit refactoring, see section "Unfolding exit actions" for an analogous example.

To unfold entry actions, right-click on the state to refactor, then select Refactor → Unfold Entry Actions in the context menu. The menu entry is active only if there are actual actions in the state’s entry block that can be moved to the state’s incoming transitions while maintaining semantic equivalence and preserving execution order.

Unfolding exit actions

This refactoring is the reverse of folding outgoing actions. It moves all exit actions from a source state and prepends them to each of its outgoing transition’s actions.

Transitions crossing the borders of composite states enclosing the source state might inhibit refactoring. Consider the following example:

Unfolding exit actions to outgoing transitions

Unfolding the exit action y = x of the Source state to the two outgoing transitions would be invalid, because the execution order of said action and the composite state’s exit action would be reversed.

To unfold exit actions, right-click on the state to refactor, then select Refactor → Unfold Exit Actions in the context menu. The menu entry is active only if there are actual actions in the state’s exit block that can be moved to the state’s outgoing transitions, while maintaining semantic equivalence and preserving execution order.

Grouping states into composite

This refactoring creates a new composite state containing the selected states. The latter must belong to the same region.

To execute this refactoring, select one or more states from the same region, right-click on one of them, and select Refactor → Group States Into Composite in the context menu. The menu entry is active only if the selected states belong to the same region.

Extracting subdiagram

This refactoring extracts the regions of the selected composite or orthogonal state into a subdiagram. Entry and exit points are created as needed in the subdiagram. See section "Using subdiagrams" for more details.

To extract a subdiagram, right-click on the composite or orthogonal state to refactor, then select Refactor → Extract Subdiagram in the context menu.

Inlining subdiagram

This refactoring inlines the selected node’s subdiagram in order to show it directly in the composite state’s diagram region. See section "Using subdiagrams" for more details.

To inline a subdiagram, right-click on a composite state with a subdiagram, then select Refactor → Inline Subdiagram in the context menu.

Using editing proposals

Using text proposals

Proposals assist you when writing statechart language expressions. Whenever editing some text anywhere in the graphical statechart editor or in the properties view, at any point you can press the [Ctrl+Space] key combination to get some context-sensitive help.

Certain proposals, like statechart language keywords, have documentation associated with them. When such a proposal is selected, either using the mouse or the keyboard, this information is shown in a secondary pop-up window next to the proposal.

You can either use the mouse or the keyboard to select and insert a proposal in the text:

Double-click on a proposal to insert it in the text at the current position.
Use the up and down arrow keys to navigate to the proposal you want to insert in the text, then press [Return] to actually insert the proposal at the current position.

Using actions proposals on states

When a state is selected, [Ctrl+Space] opens a pop-up window showing a context-sensitive menu with possible action choices to perform on the state.

These action proposals have additional information associated to them. When a proposal is selected either using the mouse or the keyboard, this information is shown in a secondary pop-up window next to the proposal.

You can either use the mouse or the keyboard to execute a proposal:

Double-click on a proposal to execute it.
Use the up and down arrow keys to navigate to the proposal you want to execute, then press [Return] to actually execute it.

Searching and navigating in statecharts

itemis CREATE support you in quickly finding model elements and navigating to them.

The larger the model, the greater the need to quickly search for certain elements, e.g., for all states with a given name or name pattern, all occurrences of a certain variable, etc. itemis CREATE' searching functionality helps you master even large statecharts.

Searching via search dialog

One option, and the most complex one, is to use the search dialog. You can open it using the [Ctrl+H] shortcut or by selecting Search → Search… in the main menu.

Doing so will open a dialog with several tabs, as shown in the following screenshot:
Search Dialog

The tab you want to use is Statechart search.

Please note: If you cannot find this tab, you probably disabled it in the past by mistake. You can enable it again by clicking on the Customize… button and selecting Statechart Search, as shown by the following figure:

Switching to Statechart search will show you a clean and easy to understand dialog, which can be extended using the Show advanced settings check box for a more professional usage. The following subsection describes the possible settings.

User tip: Checking the Remember last used page option in the Customize dialog will help you to keep the focus on the Statechart Search tab for further search processes.

Search dialog settings

The Statechart search dialog has several options to control your search.

Advanced search dialog

The following table lists the various search options and explains what the search function does if the corresponding checkmark is set.

Setting	Description
Case sensitive	Differentiate between upper-case and lower-case letters in the search string. If this option is not checked, upper-case letters and their corresponding lower-case letters are regarded the same.
Regular expression	Interpret the search string as a regular expression. Please note that itemis CREATE supports Java regular expressions, as explained in the java.util.regex.Pattern class API documentation.
Search for states/regions	Include states and regions with matching names in the search result.
Search for declarations	Include matching declarations in the search result. Declarations are statechart language elements in the definition section, such as variables, events, operations, and named interfaces. The search function will find all occurrences of matching elements.
Search for properties	Include elements with matching properties in the search result. The following items are regarded as properties: Documentation of model elements Behavior of states, i.e., local actions, etc. Text of text elements and notes
Scope: workspace	Perform the search operation on all statecharts in the workspace.
Scope: selected resources	If a statechart editor has the focus, perform the search operation only on that statechart. If the Project explorer view has the focus, perform the search operation on all statecharts in the selected resources.

Search view

After setting the search options as needed, run the search using the Search button. The search results will be shown in a view called Search.

We will demonstrate the search view using the light switch example from our five-minutes tutorial, using the following settings:

Setting	Value
Search string	O*
Case sensitive	✘
Regular expression	✘
Search for states/regions	✔
Search for declarations	✔
Search for properties	✔
Scope: Workspace	✔
Scope: Selected resource	✘

The search view consists of three main components and looks like the following screenshot.

Search view

Component	Functions
Searchbar text section	Displays the search string and the number of matches. The latter is updated while the search is running.
Toolbar section	See section "Toolbar section"
Result section	See section "Result section"

Toolbar section

The toolbar section consists of ten buttons with the following functionalities:

Button	Action	Functionality
	Redo search	Executes the same search again on the possibly changed model.
	Cancel searching	Cancels a currently running search. The button is active only if a search run is being executed.
	History	Use this function to display the search history, to select a formerly-executed search (click on Redo search to actually execute it), or to clear the history.
	Pin search	Pins the results view. Future search results will be shown in a new search view, instead of rewriting the pinned search view.
	Collapse all	Collapses the search result tree and displays the root entries only.
	Expand all	Expands the search result tree and displays all search result entries.
	Search menu	Contains various search options.
	Minimize	Minimizes the search view and all its sibling views. A “restore” symbol is shown in a sidebar.
	Maximize	Maximizes the search view and all its sibling views to the full window size.
	Restore	Undoes the Maximize function. This button is shown only if the search view is maximized.

Result section

The result section displays the matching statechart elements in a two-column, tree-based view.

The left-hand column, named Location, shows location and type of each match. Additionally, the whole path from the project down to the matching element is shown.
The right-hand column, named Matches shows the matches themselves. Intermediate path elements that are no matches but are displayed in the Location column don’t have a counterpart in the Matches column.

Result section actions

You can perform certain actions on the entries in the first column:

	Action	Function
	Click on the button	“closes” the node and collapses all child nodes.
	Click on the button	“Opens” the node and expands its immediate child nodes.
	Double-click on a matching element	Navigates to the matching element in the statechart editor, as long a it is not a descendant of an internal or interface element.
	Double-click on a non-matching path element	Closes an expanded node, opens a collapsed node.

Finding references

Another realized search feature is to find references of model elements. You can perform this search on choosing Find references in the context menu of:

model elements in the editor
model elements in the project explorer
referenced object in syntax-checking editors inside statechart models like the definition section or the state behavior editor

This will search for usages of the same element in the local statechart and display them in the search view. Using this method can help you to save time searching for usages of variables, events and operations inside your statechart.

The next section introduces the differences between the first method and this method.

Differences between “Find references” and "Search dialog"

As stated in the previous section, Find references is searching for the usages of the exact same model element as selected, whereas in the Search dialog, you have to enter a search string which will find all occurrences of model elements that match the search string.

Finding occurrences of model elements matching the search string makes it possible to search in different statecharts at the same time, while finding references of a model element is limited to the statechart defining that model element. Depending on your search goals, one method could be more suitable than the other.

To clarify the difference between these methods, different search operations were done using the same model. The used model can be taken from the following figure. It does not have any meaning and is only used for clarification purposes.

Example Model

Search operation	Results
Find references on variable test in the default (unnamed) interface	Finds two matches: Entry action in the test state using the test variable Definition of the test variable in the unnamed interface
Find references on variable test in named interface first	Finds one match: Definition of the test variable in the named interface first
Find references on state test	Finds one match: The test state itself
Search Dialog with the same settings as in section "Search view" and "test" being the search string	Finds four matches: Entry action in the test state using the test variable Definition of the test variable in the unnamed interface Definition of the test variable in the named interface first The test state
Search Dialog with the same settings as in section "Search view" and "test" being the search string	Finds one match: Definition of the test variable in the named interface first
Search Dialog with almost the same settings as in section "Search view", but with Search for declarations deactivated and with "test" being the search string	Finds match: The test state
Search Dialog with almost the same settings as in section "Search view", but with Search for states/regions deactivated and with "test" being the search string	Finds three matches: Entry action in the test state using the test vwe should ariable Definition of the test variable in the unnamed interface Definition of the test variable in the named interface first

As can be seen in this case the search dialog has problems with searching references for the variable test in the unnamed interface.

Open model element

Open model element is another kind of search method. It can be used to quickly navigate to states and regions. To access Open model element, use the [Ctrl+Shift+Q] shortcut or select Navigate → Open model element in the main menu.

By doing so, the dialog shown in the next screenshot will open.

Open model element

The dialog consists of a single input element Searchbar and two output elements Result list / Result location .

A search operation performed with Open model element is equivalent to "Searching via search dialog" with the following setting:

Setting	Value
Search string	same as in
Case sensitive	✘
Regular expression	✘
Search for States/Regions	✔
Search for Declarations	✘
Search for Properties	✘
Scope: Workspace	✘
Scope: Selected resource	✔

Differences between Open model element and Search dialog are subtle, but noticeable. The results will promptly appear in Result list while typing your search string in Searchbar . The hierarchy of a selected result is displayed in Result location as a text instead of using a tree.

Navigating to a result can be done by double-clicking on the result. Or select the result and clicking on the OK button or hit the [Enter] key.

The Open model element dialog remembers any matching search results. On reopening the dialog, remembered model elements matching the new search string will be displayed above any newly-found elements. This makes it easier to navigate to them again at a later time.

Remembered elements

Remembered elements can be removed from the history by selecting them and pressing the [Del] key or by right-clicking on a remembered element and choosing Remove from history in the context menu.

Comparing statecharts

The statechart editor allows for comparing two or even three statecharts to each other, displaying the results, and possibly merging selected differences. Figure "Comparing two statecharts" shows a sample comparison result.

Comparing two statecharts

Comparing a statechart to its local history

Whenever a statechart is saved to its statechart file, the previous version of the file is saved to the local history.

Warning: The local history typically contains a few recent versions of a file. However, you should never rely on anything being available in the local history at all. It is definitely no replacement for a data backup or a version control system

To compare a statechart to an older version in the local history, proceed as follows:

In the project view, right-click on a statechart model file. The context menu opens.
In the context menu, select Compare With → Local History….
In the local history, double-click on the file’s version to compare to.
The comparison results are shown.

Comparing two statecharts

To compare two statecharts, proceed as follows:

In the project view, select two statechart model files.
Right-click on one of the selected statechart model files. The context menu opens.
In the context menu, select Compare With → Each Other.
The comparison results are shown.

Comparing three statecharts

To compare three statecharts, proceed as follows:

In the project view, select three statechart model files.
Right-click on one of the selected statechart model files. The context menu opens.
In the context menu, select Compare With → Each Other.
The Select common ancestor dialog appears. It shows the three selected statechart model files.
Select one of them. It will be regarded as the common ancestor of the two others.
The comparison results are shown.

Exporting a statechart as an image file

A complete statechart or parts of it can be saved as an image file as shown in the following steps:

In the statechart editor:
- To create an image file of the whole statechart with all regions and definition sections, inline the definition section via the button on the top right of it and then right-click on the main region and select File → Save As Image File....
- To create an image file of some statechart elements, select these elements and right-click on one of them. In the example below, the main region has been selected.
The context menu appears.
In the context menu, select File → Save As Image File....
The Save As Image File dialog appears.
Specify the filesystem folder for the exported image file in the Folder text field.
Enter the name of the export image file into the File Name text field. The filename extension depends on the selected image format (see below).

Select the image format from the Image Format drop-down menu. itemis CREATE supports the following formats:

Image format	Description
BMP, PNG	Lossless pixel image formats
JPG, JPEG	Lossy pixel image format. You can specify the image quality via the Quality (%) setting.
SVG	Scalable Vector Graphics
PDF	Portable Document Format

Note
The image export functionality is subject to the capabilities of your Java Runtime Environment (JRE). You can export images only in those image formats your JRE actually supports.

The Quality (%) text field is active for JPEG images only. JPEG is a lossy format, and reducing the quality results in a smaller file size. However, due to the nature of statechart images, a lossless format like PNG is most often a better choice, for sure in quality and perhaps even in file size.
Check Overwrite existing file without warning if you don’t want to be bothered by a confirmation dialog which will appear if the export file already exists.
Check Export to HTML to create both the image file plus an HTML file including it.

Working with statechart tasks

While you are busily developing a statechart, it is quite common that you have ideas about what else you could or should do to improve the statechart. However, in order to not get side-tracked, you decide to do it later. Examples are to write a proper documentation for a state, to refine a transition whose final specification you don’t have yet, etc.

For all these and other purposes you can define tasks in all places in your statechart where a comment is allowed. A task is a special comment comprising the words FIXME or TODO. Adding one of these words to a comment is called “tagging” the comment as a task.

The nice thing is that you don’t have to remember all the places you took a note and defined a task. itemis CREATE lists all of your tasks in the tasks view. Figure "Tasks defined by tags in the statechart showing up in the tasks view" is showing an example with various tasks being defined in a transition, in a state’s behavior, in a state’s documentation, and in the statecharts definition section.

Tasks defined by tags in the statechart showing up in the "tasks" view

Tasks defined by tags in the statechart showing up in the tasks view

In the example, state B has been selected in the statechart editor (top), so that the tasks defined in the state’s behavior and in its documentation are shown in the properties view (middle).

Task have a priority. While TODO stamps a task as being of normal priority, FIXME indicates a high-priority task.

By default, tasks are ordered by priority in the tasks view (bottom), and high-priority tasks are accentuated by a red exclamation mark. However, you can change the sorting order and other settings using the view’s menu. Click on the little triangle on the right-hand side of the task view’s title to open the view menu.

Double-clicking on a task in the tasks view navigates to the location where the task is defined. If needed, the corresponding statechart diagram is opened. The graphical element holding the task definition is highlighted.

Note

The tasks view is updated only when the statechart is saved.

Using the example wizard

The example wizard gives you convenient access to the examples in the public itemis CREATE examples repository. You can browse the available examples and read their documentation in the wizard. By a simple click you can instantiate an example as a new Eclipse project. Within such a sample project, you can explore and modify the state machine models using the statechart editor, run the state machines in the simulator, generate source code, etc.

Upon its first invocation, the example wizard downloads the complete examples repository and creates a copy on your local disk. After that, all examples are immediately available to you, even if you are offline. The example wizard will take notice when new examples are available in the online repository and offers to download them. It is also possible to download the examples repository out-of-band and later tell the example wizard where it can find the local copy.

Downloading the examples repository

When you start the example wizard for the first time, it does not yet have any examples available that it could show to you. Thus downloading the online examples repository is required as a special first step.

In order to start the example wizard, select File → New → Example… in the itemis CREATE main menu. The New Example dialog opens.
In the New Example dialog, select itemis CREATE Examples, then click on Next >. The example wizard opens.
The example wizard outputs a message saying that it could not find any examples and offers to download them.
Click on the Download button. The example wizard downloads the online examples repository and creates a clone of it on your local computer. This can take some time. – Downloading can fail for a variety of reasons, not being able to access the Github server being one of them. If this happens, don’t panic – and read how to manually create a local copy of the examples repository.

Example wizard when invoked for the first time

When the download is completed, you can browse the examples repository.

Changing the repository location

You can change the location used by the example wizard to store the online repository’s local clone.

When the example wizard shows the Download button on its first start, click on the link "change the storage location here". The example wizard’s preferences dialog opens. Alternatively, open Window → Preferences and select itemis CREATE → Example wizard.
On the examples preferences page, enter the desired directory into the Storage Location text field.
Click on OK. The dialog closes.

You can change the storage location of your local examples repository clone at any time. In fact, it doesn’t even need to be a clone of the official examples repository. Any directory containing subdirectories with itemis CREATE examples suffices.

If the directory exists, the example wizard searches it for examples and displays them.
If the directory does not exist, the example wizard behaves as if being called for the first time. That is, it informs the user that it does not have any examples yet and offers to download them.

Browsing the examples repository

The example wizard shows the available examples on the left-hand side.

Click on an example to select it and show its documentation on the right-hand side.

Click on Finish to create the selected example as a new project in your workspace.

Example wizard showing all available examples

Manually creating a local copy of the examples repository

The example wizard tries to download a copy of the itemis CREATE examples repository and install it on your local machine. However, if your Internet access is restricted or you don’t have Internet access at all, this will fail.

To circumvent this problem, you can

download the examples repository elsewhere, i. e. on a computer with Internet access,
copy it to the computer you want to run itemis CREATE, and
have the example wizard work with that local copy.

Subsequently we will explain the necessary steps in detail.

Downloading the repository as a ZIP archive:

On a computer with Internet access, go to the examples repository’s release branch.
Click on the green Clone or download button. A submenu opens.
In the submenu, click on Download ZIP.
The download starts and transfers the ZIP archive file examples-release.zip to your computer.
Copy the examples-release.zip file to the computer without Internet access and continue with the following steps on that machine.
Unpack the archive file. A directory named examples-release is created, containing the itemis CREATE examples repository.
In itemis CREATE, select Window → Preferences. The preferences dialog opens.
In the preferences dialog, navigate to itemis CREATE → Example wizard.
Click on Browse..., and select the folder that you just extracted from the ZIP file, then click OK.
On the next try, the example wizard will now show a catalogue of itemis CREATE examples.

Alternatively, you can clone the repository. Cloning the examples repository containing the itemis CREATE examples is more complex than just downloading a ZIP archive. However, you will get certain advantages in return, like the ability to detect and receive updates, the option to create your own examples and submit them as a pull request, or to get hold of the complete history of the examples repository – which could also be considered a drawback, taking its size into account.

Clone https://github.com/Yakindu/examples to your local computer. If you are using a command-line tool, the proper command to create the directory examples on your disk is:
git clone 'https://github.com/Yakindu/examples.git'
Step into that directory:
cd examples
Checkout the release branch:
git checkout release
Now the examples directory reflects the current release state.
In the itemis CREATE main menu, select File → New → Example…. The New Example dialog opens.
In the New Example dialog, select itemis CREATE examples and click on Next >. The example wizard opens.
When the example wizard is opened for the first time, there are no examples on the local disk yet.
In itemis CREATE, select Window → Preferences. The preferences dialog opens.
In the preferences dialog, navigate to itemis CREATE → Example wizard.
Click on Browse..., and select the folder you just cloned, then click OK.
On the next try, the example wizard will show a catalogue of itemis CREATE examples.

Updating the examples repository

When the example wizard is started and the storage location is a clone of the online examples directory, it checks whether there are any updates in the online examples repository. If new examples are available or existing examples have changed in the online repository, the example wizard offers to update your local examples repository clone accordingly.

Example wizard offering to update the examples repository

Click on the Update button to update your local repository.

If your storage location is a plain directory and not a clone of the online examples repository, no update will ever be done.

Contributing your own examples

If you have a project that you want to share with the community, you can contribute it as an example. Once the itemis CREATE team has reviewed and applied your contribution, it will be available for all users of itemis CREATE via the example wizard’s update functionality.

For more information on how to contribute examples, please visit our Wiki page.

Preferences

Many aspects of itemis CREATE can be configured by preferences. You can find them here:

In the main menu, select Window → Preferences. The Preferences dialog appears.
In the navigation on the left-hand side, scroll to itemis CREATE. Open it and its subentries as needed.
Click on an entry to display the associated preference page on the right-hand side of the Preferences dialog, see, e.g., figure "Preferences: Diagram appearance".

In the subsequent sections we will quickly walk through the preferences.

Diagram appearance

Preferences: Diagram appearance

Colors, line styles, and fonts

The diagram appearance preferences define

the default colors for the backgrounds and borders of states and regions,
the default routing style for transitions and other lines, with oblique and rectilinear being the options at your choice, and
the default font for any text.

Please keep in mind that these settings will apply to new elements only. Existing regions, states, etc. will remain as they are. However, you can modify the properties of an existing element anytime, using its properties view.

Font scaling

This option is only available on Microsoft Windows. By default, font scaling is deactivated in itemis CREATE. If you are working on different machines with different Windows font scaling, this option can be enabled to have the same font and box sizes on all machines.

Syntax coloring

By default, itemis CREATE highlights textual statechart language elements in different colors while the corresponding text fragment is being edited.

If the "Enable syntax coloring" option is checked, syntax highlighting is turned on all the time, i.e., also for text that is not being edited.

You can configure the colors to actually use on the following preference pages:

Expression syntax coloring
Generator model syntax coloring
SCTUnit syntax coloring

Definition section pinning

Check or uncheck the "Enable pinning of statechart definition section pinning" option to toggle between pinning and legacy mode of the definition section. Section "Using the definition section" explains what this is all about.

Showing transition and region priorities

In order to display transition and region priorities in a statechart, set a check mark at the respective preference option. Section "Transition priorities" explains what transition priorities are and shows an example.

Disabling live validation

While you are editing a statechart, the statechart editor validates your model on each and every modification you make. That’s very helpful, because the editor provides you with instant feedback, so you can see immediately what is right, wrong, or dubious, and you can take corrective action, if needed.

However, on very large and complex statechart models, validation may take a considerable amount of time, causing delays and impeding your editing. Remove the check mark from Enable live validation, and your model will be validated only before it is saved to the statechart file.

Example wizard

Preferences: Example wizard

You can change the example wizard storage location here. This is a local directory where the example wizard stores your local clone of the examples Git repository. The default is the sct4_examples directory in your home directory.

You could also change the location of the Git repository and the branch to use, but you won’t probably want to do that.

Expressions preferences

Preferences: Expressions

Certain dialogs in the statechart editor allow you to opt for never seeing them again. By clicking on the Clear button on this preference page the hidden dialogs pertaining to the statechart language will be shown again at their respective locations.

Expression syntax coloring

Preferences: Expression syntax coloring

This preference page defines foreground color, background color, font, and style for displaying certain syntactical elements in statechart language texts.

Expression templates

Preferences: Expression templates

Templates are sections of textual code that occur frequently enough to make you want to insert them with a few keystrokes only. This function is known as content assist; the sections of code that are inserted are known as templates.

To insert an existing content assist template, type the initial character, then press [Ctrl+Space]. The templates whose names begin with that character will appear. Double-click on a template to insert it.

On this preference page you can create, edit, and delete statechart language templates.

Generator model

Preferences: Generator model

By default, code generators automatically generate artifacts defined by generator models in .sgen files. Using this preference setting, you can switch this behavior off or on.

Generator model refactoring

Preferences: Generator model refactoring

Change these preference settings for refactoring in generator models as you see fit.

The "Save all modified resources automatically prior to refactoring" option is somewhat dangerous, because you might have made changes to files that you intentionally do not want to save to disk – or at least not yet. For that reason, this option is turned off by default.

The "Rename in editor without dialog if possible" pertains to how the renaming operation is performed. By default, if you click on a name and press [Shift+Alt+R], you can edit the name directly in the source code, and all other occurences of that element are renamed while you are typing. If this is not possible or if this option is not checked, a dialog will ask you for the element’s new name.

Generator model syntax coloring

Preferences: Generator model syntax coloring

This preference page defines foreground color, background color, font, and style for displaying certain syntactical elements in generator model texts.

Generator model templates

Preferences: Generator model templates

On this preference page you can create, edit, and delete generator model language templates.

SCTUnit

Preferences: SCTUnit

Certain dialogs in SCTUnit allow you to opt for never seeing them again. By clicking on the Clear button on this preference page the hidden dialogs pertaining to SCTUnit will be shown again at their respective locations.

SCTUnit refactoring

Preferences: SCTUnit refactoring

Change these preference settings for refactoring in SCTUnit source files as you see fit.

SCTUnit syntax coloring

Preferences: SCTUnit syntax coloring

This preference page defines foreground color, background color, font, and style for displaying certain syntactical elements in SCTUnit source texts.

SCTUnit templates

Preferences: SCTUnit templates

On this preference page you can create, edit, and delete SCTUnit language templates.

Simulation

Preferences: Simulation

Set your color preferences for the statechart simulator on this preference page.

Simulating statecharts

itemis CREATE supports model simulation.
Simulating a statechart model means to execute it, raise events manually, have time-based and other events being triggered automatically, and observe the model’s behavior.

You can run multiple state machines in parallel and even multiple instances of the same state machine.

An introduction to simulation is given in section "Simulating the light switch model".

Starting a simulation

You have several options to start a statechart simulation.

Using the statechart model file context menu

The most direct way is to start the simulation based on the statechart model file.

In the project explorer view, right-click on the statechart model file. The context menu opens.
In the context menu, select Run As → Statechart Simulation, see figure "Selecting Run As → Statechart Simulation in the context menu" .

Selecting "Run As → Statechart Simulation" in the context menu

Selecting Run As → Statechart Simulation in the context menu

Repeating the last simulation

In order to re-run the simulation you have most recently executed, simply

press [Ctrl+F11] on the keyboard

select Run → Run in the main menu.

To be exact, this operation does not necessarily re-run the last simulation, but rather the last executed launch. So if, for example, you first run a statechart simulation followed by running a Java program, then upon pressing [Ctrl+F11] that Java program is executed once again, not the statechart simulation.

Repeating an earlier simulation

Let’s consider a scenario where you want to execute a simulation that you have run before, but not as the most recently executed launch. So you cannot use the procedure described in section "Repeating the last simulation".

However, as long as you haven’t launched too many other programs in between, chances are good to find your simulation in the history.

Try the following:

In the main menu, open the Run menu and move your mouse pointer over the Run History entry.
A submenu attached to the Run History menu entry opens, containing the most recently executed launches. Check whether the simulation you want to execute is available in the submenu. If it is, select it to start the simulation.

Creating and executing a launch configuration

When a statechart is simulated for the first time, a launch configuration is automatically created. A launch configuration describes the parameters used for a particular launch. In case of a statechart simulation, it describes which statechart is to be simulated and the simulation mode (event-driven or cycle-based). For details on how to create and modify a launch configuration, see section "Configuring a simulation".

To execute an existing launch configuration, proceed as follows:

In the main menu, select Run → Run Configurations…. The Run Configurations dialog appears.
The list on the left-hand side of the Run Configurations dialog displays all available launch configurations. Select the launch configuration you want to execute.
Click on Run to execute the launch configuration.

The SC Simulation perspective

The SC Simulation perspective provides selected views that are most useful when running a statechart simulation.

Engaging the SC Simulation perspective

When a simulation starts, the perspective usually changes to the SC Simulation perspective. If this doesn’t happen, you can manually engage the SC Simulation perspective as follows:

In the main menu, select Window → Perspective → Open Perspective → SC Simulation.

Alternatively, you can do the following:

In the main menu, select Window → Perspective → Open Perspective → Other…. The Open Perspective dialog appears.
In the Open Perspective dialog, select SC Simulation.
Click on Okay. The SC Simulation perspective opens.

Views contained in the SC Simulation perspective

By default, the SC Simulation perspective shows the following views:

Project Explorer (top-left): This view displays your workspace and projects, folders, and files contained therein. You can also use the Project Explorer to inspect the internal structure of your statechart models.
Outline (bottom-left): This view is a bird’s eye view on the opened statechart. It also indicates the current viewport for better orientation in large models.
Simulation (right): This view shows the current state of all variables and events during a simulation. A detailed description is available in section "The Simulation view".
Breakpoints (right): This view shows a list of all breakpoints. You can use it for disabling, enabling, or removing breakpoints as well as for defining conditional breakpoints.%

Displaying simulation progress in the statechart editor

The SC Simulation perspective also includes the statechart editor. In a running simulation, the statechart editor highlights active states by coloring their backgrounds.

When a transition is taken, the transition arc leading from the source state to the target state flashes briefly in the transition highlighting color. After that, the target state becomes active and changes its background to the state highlighting color. The source state’s background color becomes normal again.

The "SC Simulation" perspective

The SC Simulation perspective

The Simulation view

The Simulation view is used to manually raise events and to inspect and modify variables of a running simulation. By default, that view is located on the right-hand side of the SC Simulation perspective, see figure "Simulation view" for an example.

The Simulation view groups events and variables by their interfaces. The unnamed interface appears as default in the interface list. Click on the small triangle left from an interface’s name to show or hide that interface’s contents, i.e., events and variables.

The simulation view also displays time events, provided the statechart uses time constructs like after or every. Press or release the "show time events" button symbol: "show time events" to toggle between displaying and not displaying time events. You can click on a time event to raise it, i.e., you don’t have to wait for 24 hours to elapse in real time until the "after 24 * 60 * 60 s" transition fires.

You can have multiple simulation instances running at the same time. They may simulate the same or different statecharts. Use the simulation view’s drop-down menu to switch between simulation instances.

A digital clock right from the drop-down menu displays the virtual time elapsed in the simulation. It pauses while the simulation is suspended.

The "Simulation" view

The Simulation view

Please note:

Depending on your screen resolution and font size settings, you might not be able to spot the Simulation view by its name, because the tab containing it is quite narrow and might not provide enough space for displaying the title. Hover over the tabs to reveal their respective titles in a pop-up window.

Figure "The SC Simulation perspective" is demonstrating this: The user has hovered the mouse pointer over a tab that just displays the first letters of its title. However, a pop-up window right under the pointer shows the tab’s full title “Simulation”.

Controlling a simulation

To terminate the simulation, click on the Terminate button .
To suspend the simulation, click on the Suspend button .
To resume a suspended simulation, click on the Resume button .
Use the Step Over button to execute a single run-to-completion step.
To terminate the current simulation and run it again from the start, use the Terminate and Relaunch button .
To start a new simulation while keeping the current one active, use the Restart button .

Interacting with a simulation

You can interact with a running simulation by manually raising events and by inspecting and modifying variables. You can do so at any point in time, but in most cases you will do it while the simulation “sits idle” at its active state and waits for an event to trigger a transition.

Raising an event in the simulation

To raise an event, proceed as follows:

In the simulation view, click on the small triangle to open the interface containing the event, if needed.
Click on the event to raise it for the next run-to-completion step.

If the simulated statechart’s execution semantic is EventDriven then the simulation view will contain a global event called triggerWithoutEvent. Clicking on it will call the statechart’s triggerWithoutEvent operation and with that it will perform a run-to-completion step without raising any event.

Inspecting a variable

To inspect a variable’s value, proceed as follows:

In the simulation view, click on the small triangle to open the interface containing the variable, if needed.
The variables contained in the interface are displayed.

Watch the displayed values change as the simulation progresses and actions in states or transitions are executed that modify the variables' contents.

Modifying a variable

To manually modify a variable’s value, proceed as follows:

If needed, open the interface containing the variable by clicking on the small, hollow triangle left from the interface name in the simulation view.
Click on the variable’s value. You can edit the value now.
Enter the variable’s new value and press [Enter]. The new value is assigned to the variable and replaces the former value.

Configuring a simulation

Section "Creating and executing a launch configuration" describes how to start an existing launch configuration.

The present section describes how to create and configure a new launch configuration for a statechart simulation.

In the main menu, select Run → Run Configurations…. The Run Configurations dialog appears.
In the Run Configurations dialog, right-click on Statechart Simulation and select New in the context menu.
Alternatively, you can select Statechart Simulation and then click on the New symbol near the top-left corner of the dialog.
However you do it, a new launch configuration is created and displayed in the main area of the Run Configurations dialog. The launch configuration’s Main tab is opened.
Enter the launch configuration’s parameters as necessary:
- In the Name text field, change the default name New_configuration to something sensible, e.g., Light switch.
- In the Model file text field, enter the path to the statechart model you want to simulate. Click on the Search button to browse for statecharts.
- If your model uses Java operations, specify the Java class implementing those operations in the Operation class text field. If you have multiple Java classes, specify them as a comma-separated list.

Please note: Besides the Main tab described above, a statechart simulation launch configuration also has a tab named Common. This tab is a common standard to all types of launch configurations, and it is described in the Eclipse documentation.

In addition to creating new launch configurations, you can also duplicate or delete launch configurations in the Run configurations dialog. Right-click on a launch configuration and select Duplicate or Delete from the context menu.

Debugging with breakpoints

Introduction

itemis CREATE includes two simulator features that increase your productivity considerably when debugging statecharts:

You can attach breakpoints to states and transitions. If a statechart simulation reaches a transition or state with a breakpoint, it suspends execution of the simulation. A breakpoint can be amended with a condition. Such a breakpoint will suspend the simulation only if that condition is fulfilled, i.e., evaluates to true.
You can create snapshots of your statechart simulation. A snapshot contains everything making up your state machine simulation at any point in time. It describes the state of the state machine. Snapshots can be saved and restored later in order to continue the simulation from exactly the point the snapshot was taken.

The light switch example

Throughout this chapter we will be using the light switch statechart as an example. It models a lamp which can be turned on and off and also supports various brightness values.

If you press the pressLightOn button, the lamp turns on at its lowest brightness value. If you operate pressLightOn repeatedly, each time the lamp becomes brighter until it reaches its maximum brightness. Pressing the pressLightOff button immediately turns off the light completely. The brightness can only be raised as long as it hasn’t yet reached its maximum value of five. After that, the guard condition disallows to raise it any further.

Here’s the light switch example’s statechart followed by its definition section:

The light switch sample statechart

interface:
    in event pressLightOn
    in event pressLightOff

interface Lamp:
    var brightness: integer

Breakpoints

Breakpoints allow for automatically suspending the simulation when a certain element of the state machine is activated. Optionally, a halting condition can be specified to better control the behavior of a breakpoint. Breakpoints can be set on transitions or states. If a state or transition with a breakpoint is reached, the simulation pauses, and the current state of variable values can be examined in the simulation view. It is possible to change variable values and to trigger events that will be raised when the simulation run is manually resumed.

Figure "Transition vs. state breakpoints" depicts at which point of execution a breakpoint pauses the simulation.

Transition vs. state breakpoints

Executing in debug mode

To make use of breakpoints, the statechart simulation needs to be executed in debug mode. You have already seen how to start a statechart simulation in run mode. For using breakpoints and snapshots, however, the debug mode is needed.

Right-click on the statechart model. The context menu opens.
Select Debug As → Statechart Simulation, see Figure "Starting a simulation in debugging mode".
The statechart simulation starts in the debugging mode.

Starting a simulation in debugging mode

Starting a simulation in debug mode

Setting a breakpoint

Right-click on a state or transition. The context menu opens.
Select Toggle breakpoint from the context menu, see Figure "Setting a breakpoint".

Setting a breakpoint

States and transitions with a breakpoint are labeled with a Symbol: Breakpoint enabled symbol. Figure "Breakpoints on transition and state" shows an example.

Breakpoints on transition and state

Hitting a breakpoint

If the simulation runs into a state with a breakpoint, the state’s entry actions, if any, are executed. After that, execution of the state machine is suspended. The state is highlighted by a small green border.

Highlighting a suspended state

If the simulation runs into a transition with a breakpoint, execution of the state machine is suspended. The transition is highlighted by drawing the transition arc in green. The transition’s actions, if any, are executed when the state machine is resumed.

Highlighting a suspended transition

Continuing the simulation

In order to continue from a breakpoint, you have two options:

To continue execution, click on the resume button in the simulation view. The statechart simulation continues until the next breakpoint is hit or the simulation is terminated.
To execute only the next run-cycle of the simulation and then suspend again, click on the step-over button in the simulation view.

Using the breakpoints view

The breakpoints view shows a list of all breakpoints. The respective breakpoint name identifies the state or transition in question. See figure "Breakpoints view" for an example.

You can use the breakpoints view for disabling, enabling, and removing breakpoints as well as for defining conditional breakpoints.

The "Breakpoints" view

The Breakpoints view

Enabling and disabling breakpoints

A breakpoint is either enabled or disabled.

An enabled breakpoint causes the statechart simulation to suspend when reaching it. In the statechart and in the breakpoints view, an enabled breakpoint is visualized by a filled light blue circle with a grey border: .
A disabled breakpoint is ignored by the statechart simulation. In the statechart and in the breakpoints view, a disabled breakpoint is visualized by a hollow circle with a grey border: .

Figure "Breakpoints view" shows an enabled and a disabled breakpoint in the statechart editor and in the breakpoints view, respectively.

You can instruct the statechart simulation to skip all breakpoints by clicking on the Button [disengaged]: Skip all breakpoints button in the breakpoints view. The button will appear “pressed”, and while it is, the “skip breakpoints” functionality is engaged. That means, the simulation will not suspend at any breakpoint.

This is different from disabling all breakpoints, in that each breakpoint keeps its state of being enabled or disabled. Once you disengage the skip breakpoints functionality by clicking on the Button [engaged]: Skip all breakpoints button again, the simulation will suspend again at enabled breakpoints and will not suspend at disabled breakpoints.

Removing breakpoints

In order to remove some breakpoints, select these breakpoints in the breakpoints view, then click on the Button: Remove button. The selected breakpoints will be removed.

To remove all breakpoints, click on the Button: Remove all button

Conditional breakpoints

A conditional breakpoint has an associated condition and suspends the simulation only if

that condition is fulfilled (true) and
the breakpoint is enabled.

In order to attach a condition to a breakpoint, proceed as follows:

In the breakpoints view, select the breakpoint in question.
Check the Conditional checkbox, see figure "Breakpoints view" in the lower right area. The associated text field becomes writable.
Enter the condition into the text field. Like in the statechart editor, a content assist is available when pressing [Ctrl+Space]. The expression you entered into the text field is validated automatically. In the example shown in figure "Breakpoints view", the transition suspends the simulation only if the variable brightness has a value of 4.

Debugging a statechart

Changing variable values

In the suspended status of a statechart simulation, you can change variable values using the simulation view. When continuing execution – see section Continuing the simulation – you can observe how your state machine behaves with those modified values.

Raising multiple events simultaneously

If you click on an event’s name in the simulation view to raise that event in normal simulation, i.e., while execution isn’t suspended, the state machine processes that event and takes the corresponding transition, if any.

However, while the simulation is suspended, you can raise multiple events, without instant execution. Once execution resumes, the state machine’s behavior depends on its execution scheme:

In the cycle-based execution scheme, both events are handled at the same time, or, to be more exact, in the same run-to-completion step (RTC).
In the event-driven execution scheme, each of the two events will trigger a run-to-completion step (RTC) of its own.

Let’s have a look at an example. Please note that this example uses the cycle-based execution scheme! This is important, because in the the event-driven case the state machine’s behavior would be different.

Let’s consider that you want to press the "light on" and "light off" buttons at the same time and want to observe what happens. Figure "Raising multiple events simultaneously" shows the scenario:

Raising multiple events simultaneously [1]

The simulation has encountered a breakpoint at the LightOn state and has been suspended there.
The simulation view shows the pressLightOn and the pressLightOff events. Both events are labeled with a symbol, meaning the respective event is not raised.

Raising multiple events simultaneously [2]

Clicking on an event raises it and adds a blue triangle to the event symbol: . Since the simulation remains suspended, the user can raise multiple events.

Both events are raised and will be handled by the state machine during the next run-to-completion step. The latter will be performed as soon as the user clicks on the step-over button Symbol: Step Over or the resume button Symbol: Resume .

Please note: Under the even-driven execution scheme, multiple events are never processed at the same time. Each event triggers a separate RTC.

Please note: While the execution is still suspended, you can “unraise” an already raised event by clicking on the event symbol a second time. The blue triangle will disappear, and upon continuation of the simulation the event will not be handled.

Transition priorities

It is important to understand that in the event-driven execution scheme there is a queue of events, while in the cycle-based scheme there isn’t. If in the latter case multiple events occur simultaneously, they are all present at the same time, and the state machine has to figure out which event should trigger which transition. For example, what should the light switch state machine do, if it is in the LightOn state and both events, pressLightOn and pressLightOff, have been raised simultaneously?

The answer is transition priorities. The state machine always consults the active state’s transitions in a well-defined order, it fires the first matching transition it encounters, and it forgets about the rest. Transition priorities are specified in the corresponding property of the respective state, see figure "Transition priorities". You can change these priorities, and thus the order the transitions are being checked, by selecting a transition and moving it up or down by clicking on the respective button.

The first transition whose condition is fulfilled will be executed. Under the cycle-based execution scheme, all remaining events are quashed. In the light switch example as shown in figure "Transition priorities", the pressLightOff event would “win” and trigger a transition from the LightOn to the LightOff state, while the pressLightOff event would be discarded.

Transition priorities

Generating Code

In order to deploy a code generator and actually generate code, you have to set up a code generator project. This is described in the following subsections.

For configuring the code generation process, itemis CREATE uses a textual generator model called SGen. It can be created either by using the itemis CREATE Statechart generator model wizard or by creating a text file with the filename extension .sgen.

To create a generator model using the wizard, proceed as follows:

In the project explorer view, right-click on your project. The context menu opens.
In the context menu, select New → Code generator model.
The New itemis CREATE SGen model wizard opens.
Select an appropriate folder and specify the filename of your SGen model. The filename must have the extension .sgen.
Click on Next >.
From the Generator drop-down menu, choose the code generator you want to use, e.g., CREATE Statechart Java code generator.
Check the statechart(s) to generate code from.
Click on Finish.

Selecting code generator and statecharts

The result is the specified .sgen file. It has the following format:

GeneratorModel for [GeneratorId] {
	statechart [StatechartReference] {
		feature [Feature] {
			[ParameterName] = [ParameterValue]
		}
	}
}

The [GeneratorId] represents the unique ID of the chosen generator. Currently, itemis CREATE supports the following code generators out of the box:

create::c – Generator ID for the C code generator
create::cpp – Generator ID for the C++ code generator
create::python – Generator ID for the Python code generator
create::java – Generator ID for the Java code generator
create::scxml – Generator ID for the SCXML code generator
create::images – Generator ID for the statechart image generator

A single generator model may contain multiple statechart … { … } blocks and thus specify the code generation for multiple statecharts. For each statechart, the generator process can be configured with Features. Each feature has one or more parameters. These parameters can be configured with ParameterName = ParameterValue.

Besides generating code from a statechart model, it is also possible to generate code from a test file written in the SCTUnit language. The SCTUnit code generators translate SCTUnit tests into a unit test framework of the target langauge. The following generators are available:

* create::sctunit::c – Generator ID for the SCTUnit C code generator
* create::sctunit::cpp – Generator ID for the SCTUnit C++ code generator
* create::sctunit::python – Generator ID for the SCTUnit Python code generator
* create::sctunit::java – Generator ID for the SCTUnit Java code generator
* create::sctunit::scxml::qt – Generator ID for the SCTUnit SCXML Qt code generator

See also chapter Generating SCTUnit source code for more information.

Running a generator

Provided you have created the generator model, proceed as follows:

In the project explorer view, right-click on the .sgen file containing the generator model. The context menu opens.
In the context menu, select Generate Code Artifacts.
The generator is executed.

The source files the generator produces depend on the generator itself. Each generator makes use of its specific target language and the latter’s features and best practices. For example, the Java generator generates Java interfaces and classes, and the C and C++ generators generate .h header files and .c source files. The location of the generated sources can be changed in the generator model. The respective options are explained in the following section.

The generator model is executed by a so-called Eclipse builder. Thus, the artifacts are generated automatically whenever the statechart is modified, as long as Project → Build Automatically is checked. If you want or need to execute your generator model manually, select Generate Statechart Artifacts from the package explorer's context menu.

Headless code generation

State machine code is fully derived from a statechart model, and section Generating state machine code explains how to interactively run a code generator. Since release 2.9.0, itemis CREATE additionally provides a headless code generator infrastructure. This allows for code generation without a user interface which in turn allows to integrate code generation into continuous integration (CI) build environments.

Best practice is to generate code on the fly during a continuous integration build instead of cluttering your version control system with generated artifacts.

The headless code generator can simply be called from a command line and thus can be integrated with different CI tools easily. No matter if you are using Gradle, Maven or make, all you need is a Java runtime on your build machine.

The headless code generator is not capable to generate images yet.

Installation

The scc statechart compiler

The SCT installation directory contains the file scc (Linux, macOS) resp. scc.bat (Windows): the statechart compiler. Technically, it is a script file launching the SCT executable, passing proper parameters for headless code generation.

Please include the SCT installation directory in your PATH environment variable, so the scc command can be executed anywhere from a command-line shell!

The following Linux example assumes itemis CREATE to be installed in /opt/software/yakindu-sct:

export PATH="/opt/software/yakindu-sct:${PATH}"

Calling scc with the -h option prints the the integrated help information. In a command-line shell, enter the following command:

scc -h

The output should be similar to the following:

--------------------------------------------------------------
SCC - itemis CREATE State Chart Compiler ((c) by itemis AG)

          Visit http://www.statecharts.org
--------------------------------------------------------------
usage: scc [-d <path>] [-h] [-m <path(s)>] [-v <arg>]
 -d,--baseDir <path>    Relative or absolute path to the working directory that contains your statechart projects. If
                        not set, the current directory is used.
 -h                     Shows help content.
 -m,--model <path(s)>   A list of comma-separated relative or absolute paths to model(s) used during execution. If not
                        set, the runtime value of baseDir is used.
 -v,--variables <arg>   A list of comma-separated key/value pairs to override variables in SGen models. Example: 
                       -v key1=value1,key2=value2

Generating code

For the purpose of this documentation we are assuming the following directory structure. This includes SCT-related files like generator models and statechart models.

Headless Directory Structure

Within our sample directory structure the generator model project1/default.sgen contains the following:

GeneratorModel for create::java {
	statechart default {
		feature Outlet {
			targetProject = "project1"
			targetFolder = "src-gen"
		}
	}
}

Generating code for an Eclipse project

The most simple way to invoke the code generator on the command line is to generate the code for a single Eclipse project. Using a commend-line shell, change to the project directory you want to generate code. Example:

cd [somepath]/basedir/project1

Then invoke the statechart compiler without any parameters:

scc

Please make sure scc is on your PATH environment variable. Alternatively specify the path to the scc executable in the command.

--------------------------------------------------------
SCC - itemis CREATE State Chart Compiler ((c) by itemis AG)
	  Visit http://www.statecharts.org
--------------------------------------------------------
1 gen model(s) and 1 statechart(s) loaded.
Generating 'default' to target project 'project1' ...
default done.
Generated (1 of 1) gen model(s).

The statechart compiler will invoke the code generator for all .sgen files contained in the project directory. It will look them up recursively. You’ll find the generated code at the location specified in the .sgen file:

[somepath]/basedir/[sgen.targetProject]/[sgen.targetFolder]

In this case the statechart compiler determines whether a .project file is available in the current directory and will automatically adjust the generation target to be the parent of the actual project directory to ensure the parameters defined in an .sgen file are interpreted correctly.

Using scc options

Within the root folder of your itemis CREATE installation enter one of the following platform-specific commands. The string [pathToBasedir] must be replaced by the concrete path to the base directory, i.e., the common parent directory of the project directories.

Windows:

scc -d [pathToBasedir] -m project1\default.sgen,project2\default.sct

Linux:

./scc -d [pathToBasedir] -m project1/default.sgen,project2/default.sct

macOS:

cd SCT.app/Contents/Eclipse/
./scc -d [pathToBasedir] -m project1/default.sgen,project2/default.sct

Please see the following sample output as a result of the command:

--------------------------------------------------------
SCC - itemis CREATE State Chart Compiler ((c) by itemis AG)
	  Visit http://www.statecharts.org
--------------------------------------------------------
1 gen model(s) and 1 statechart(s) loaded.
Generating 'default' to target project 'project1' ...
default done.
Generated (1 of 1) gen model(s).

As you can see the headless code generation has properly executed. The generated code will be placed into a folder depending on the values configured within your generator model file.

For our example this means the generated code can be found in

basedir/project1/src-gen/

Available scc options

All parameters are essentially optional. The reason is that for a directory structure adhering to Eclipse workspace standards like projects within a root folder, or no additional hierarchies, everything can be calculated automatically.

Specifying a base directory

You can specify a base directory using the -d basedir option. It is used for two major tasks:

It is used to evaluate the absolute paths to model locations, provided they are given as relative paths.
It is used to evaluate the respective generation target folders, depending on the values given in the generator models.

Default: If the -d option is not specified, this is equivalent to -d ., i.e., the current working directory will be the base directory.

The target folder of generated artifacts will be evaluated as follows:

basedir/sgen.targetProject/sgen.targetFolder

Specifying statechart model files

Use the -m models option to select certain models known by the statechart compiler. Usually these will be .sgen or .sct files. However, other model files that are supported by particular code generators, can be specified, too, e.g., C header files for itemis CREATE Professional’s Deep C Integration. The -m option’s value can be absolute or relative, can be a file or a folder and can be a single value or a comma-separated list of values.

If model is a comma-separated list of values, the statechart compiler will handle each value as described for model in the subsequent bullet points.
If model is relative, it is evaluated as basedir/model.
If model is a folder, the generator will search recursively for all model files known by the statechart compiler within basedir/statechart_model.

Default: If the -m option is not specified, this is equivalent to -m basedir, i.e., all model files in and beneath basedir are processed.

Specifying property values

Use the -v name1=value1;name2=value2;nameN=valueN option to override properties name1, name2, nameN, specified in the generator models, by the given values value1, value2, and valueN, respectively. See section "Using properties and expressions in generator models" for details.

Troubleshooting

If the scc command fails, here are some tips and fixes.

[ERROR] Neither ‘SCT’ nor ‘eclipse’ executable found!

If you encounter this error message on Linux, this means the scc command was neither able to locate a SCT executable binary nor an eclipse executable. This happens if the scc executable, which is really only a launcher, is not in the same directory as the SCT or eclipse executables. In a itemis CREATE stand-alone installation, the executable binary is named SCT. However, its name is eclipse if you have installed itemis CREATE from an update site into an already existing Eclipse installation. The scc launcher tries to find one of SCT or eclipse and launches the correct one.

The Eclipse executable launcher was unable to locate its companion shared library

This error message is usually issued if you have installed itemis CREATE from an update site into an already existing Eclipse installation and you installed the latter using the Eclipse Installer / Oomph.

Fixing this is easy: You have to change a single line in the headless.ini file in the Eclipse installation directory.

At first, open the eclipse.ini file in the same directory and search for the --launcher.library line. Copy the path that is on the next line. The two lines might look like this:

--launcher.library
/home/user/.p2/pool/plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.400.v20160518-1444

You’ll find a similar entry like in the headless.ini as well, probably looking like this:

--launcher.library
plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.400.v20160518-1444

Replace the path in the headless.ini file with the path from eclipse.ini. After saving headless.ini, scc should work.

[ERROR] Cannot find any .project files

Upon execution scc searches for .project files which are used to properly interpret generation target locations as specified in the sgen files. These .project files are hidden files that contain some meta information about your projects in your itemis CREATE workspace. If scc does not find these files you might have copied your models to another folder and missed to also copy these
files.

[ERROR] Couldn’t resolve reference to EObject

This error usually denotes a configuration problem when using scc in combination with the deep C integration feature. For example, if you are referring to imported C elements in your statechart models, and the corresponding header files can no more be resolved on your CI build server, the linker is unable to find the referenced C elements and produces this error message. To overcome this problem, you might want to check if your settings in C/C++ General -> Path and Symbols do not contain any paths that do not exist on your build environment. Also make sure that scc can access these settings which are stored in the .cproject file.

Using C/C++ code in statecharts

itemis CREATE comes with a Deep C/C++ Integration feature, which allows for using C/C++ types, variables, and operations directly within the statechart model. C/C++ header files located in your workspace are automatically recognized by the tool, and all contained type and operation declarations are made accessible in the statechart editor with all its editing features like code completion and validation. In addition to your custom C/C++ types, the C99 standard primitive types, like int16_t, are also available out of the box.

Making your self-defined C/C++ types, structs, and unions available in your itemis CREATE statecharts saves you a lot of time and hassle that would otherwise be needed to map data from your C-type variables to statechart variables and vice versa.

The following screencast gives an overview of the Deep C/C++ Integration feature:

Another feature that comes with the Deep C/C++ Integration is the @ShortCIdentifiers annotation. It changes the naming scheme used by the code generator and activates more checks in the statechart validation to ensure that no identifiers produced by the code generator are longer than 31 characters.

Please be aware that the Deep C/C++ Integration requires a Professional Edition License.

What can you do with Deep C/C++ Integration?

Deep C/C++ Integration allows you to use constructs declared in C/C++ header files seamlessly in your statecharts. For C, this includes:

Functions, including variadic parameters
Structs, unions and enums contained in a typedef
- Function pointers contained in a struct can be called right from your statechart
Values introduced by the #define statement, e.g., #define ARRAYSIZE 20
Variables
Arrays, provided they are allocated in the header file
Pointers

The following C++ features are supported:

Classes, including their fields and functions
Namespaces
Template classes and functions
Functions with optional parameters

C/C++ features that are currently unsupported:

Structs, unions and enums that are not contained in a typedef
Accessing or modifying function pointer values in structs
Constructors and initializers
Memory allocation
C++ references

How to use Deep C/C++ Integration

Using Deep C/C++ Integration is pretty straightforward:

You have to use a “C/C++ domain” statechart or change the domain of an existing statechart.
The Eclipse project your statechart is in must be a CDT project.

The subsequent sections will explain how to use Deep C/C++ Integration in practice, using a sample project. In this example, we will define some geometry types like Point or Triangle in C/C++ header files and demonstrate how to make them available and use them in a statechart model. While this example covers C constructs only, there is no extra effort involved in using C++ features – with one exception: Your project must be a C/C++ or a pure C++ project.

Creating a new C project

In the Eclipse main menu, select File → New → Project…. The New Project wizard opens.
Select C/C++ → C Project.
Click Next >. The C Project dialog appears.
Enter the name of your project into the Project name field. For the sake of this example, we call the project Geometry.
Specify the location of the project folder by either using the default location or by explicitly specifying a directory in the Location field.
Select the Project type. In order to keep things plain and simple, for this example we create an Empty Project.
Select the toolchain you want to work with. It contains the necessary tools for C development. By default only the toolchains supporting your local platform are displayed. Since this example has been created on a Linux machine, the toolchain Linux GCC is shown.
Click Next >.
Specify platforms, configurations, and project settings. This is more specific to C than to itemis CREATE, so we won’t go into any details here.
Click Finish.
Eclipse asks whether it should associate this kind of project with the C/C++ perspective. Usually this is what you want, so set a checkmark at Remember my decision and click Yes.
Eclipse creates the C project, here Geometry.

Creating a C header file

Now we can create a C header file specifying our own C type definitions which we can use in a state machine later. In order to create the file, let’s proceed as follows:

In the project explorer view, right-click on the project. The context menu opens.
In the context menu, select New → Header File.
The dialog New Header File is shown. Specify the name of the header file. Here we choose point.h.
Click Finish.
The header file point.h is created.

Defining a C struct

In the created header file we define a struct type named Point, which we will later use in a statechart. A (two-dimensional) point consists of an x and a y coordinate. We choose int16_t to represent a coordinate, i.e., a 16-bit signed integer. The complete header file containing the struct definition looks like this:

/*
 * point.h
 *
 */

#ifndef POINT_H_
#define POINT_H_

#include <stdint.h>

typedef struct {
    int16_t x;
    int16_t y;
} Point;

#endif /* POINT_H_ */

Please note: In C it is possible to define structs, unions and enums without a typedef. They can be referenced by using the corresponding qualifying keyword ( struct, union, or enum, respectively). As the statechart language does not support these qualifiers, the usage of struct, union and enumeration types is currently restricted to those defined by a typedef.

Using C types in a statechart

Creating a statechart model

Let’s create a statechart model now to make use of the C type Point we have just defined.

Right-click on the project. The context menu opens.
Select New → C Statechart Model …. The New itemis CREATE wizard is shown.
In the dialog, specify the directory and the filename for the new statechart model file. The filename should end with .sct.
Click Finish. If Eclipse asks you whether to switch to the itemis CREATE Modeling perspective, please confirm.
The new statechart model is created:

Defining a C-type variable in a statechart

Variables are defined in the definition section on the left-hand side of the statechart editor. Double-click into the definition section to edit it.

In order to make use of the struct defined above we have to import the point.h header file:

import: "point.h"

With the definitions from point.h at hand, we can declare a variable pointA of the Point type. In the statechart’s definition section, enter the following text:

interface:
    var pointA:

On the right-hand side of the colon in the variable declaration, the variable’s type must follow. In order to see which types are available, press [Ctrl+Space]. The content assist opens and shows the C types available, depending on the headers imported within your statechart, i.e.

the C basic standard types,
the C99 types, provided by including stdint.h,
the self-defined Point type, provided by including point.h,
the qualifier pointer.

Using content assist to display available types

Selecting the Point menu entry completes the variable definition:

A "Point" variable

A Point variable

Using a C-type variable in a statechart

A statechart variable with a C type can be used everywhere a “normal” statechart variable can be used.

It is now possible to declare variables with the type of the different statecharts, namely “CycleBasedStatemachine” and “EventDrivenStatemachine”. This is a representation of the statechart interface, which allows the
users to model multi-statemachine scenarios without binding the variables to a specific statechart. To access these types the internal “statemachine.types” have to be imported with the “import” keyword.

Let’s consider the above example extended by an additional count variable of the C99 int8_t standard type. Additionally, we introduce an event that will be used as a trigger to switch between states.

import: "point.h"
interface:
    var count: int8_t
    var pointA: Point
    in event tick

The statechart below uses these variables in various places, i.e., in transition actions, in internal actions, and in guard conditions.

Using C-type variables

Variables of primitive types like var count: int8_t are accessed as expected, e.g., count = 0 or count += 1;

The dot notation is used to access structure elements. For example, pointA.x = 0; pointA.y = 0 sets pointA to the origin of the coordinate system.

The statechart type system

When parsing a C header file, itemis CREATE are mapping the C data types to an internal type system. You can open a C header file in Eclipse with the Sample Reflective Ecore Model Editor to see how the mapping result looks like.

In case you are interested in the EMF model underlying itemis CREATE’s type system, you can find it in the source code of the itemis CREATE open edition at /org.yakindu.base.types/model/types.ecore.

Imports and includes

Importing a C header

itemis CREATE gives you direct access to C header files within the statechart model. This saves time during development, especially while integrating your state machine with your C program. In general you can import (include) all C header files residing in the same project as well as those header files that are available on one of the CDT project’s include paths, see Properties → C/C++ General → Paths and Symbols in the context menu of your C project. Valid file extensions for C/C++ header files: “.h”, “.hh”, “hpp”, “hxx” and “.inc”.

To import a C header file, go to the beginning of your statechart’s definition section, enter import: and hit [Ctrl]+[Space]. The content assist now shows all C header files you can import (besides other syntactical elements that would be valid here). In our example one of the first includes provided by the content assist is point.h, which is found in /Geometry/point.h. Other imports shown by the content assist are provided by the various include paths configured in your CDT project. For example, figure "Selecting a C header to import" shows headers on the basic cygwin toolchain on a Windows system.

Please note: Contrary to a C compiler, itemis CREATE do not support transitive imports. That is to say, if a header file a.h imports another header file b.h using the #include directive, b.h will not be “seen” in itemis CREATE unless you import it explicitly in your statechart’s definition section.

The following picture for example .

Selecting a namespace to import

Selecting a C header to import

If we had more than a single header file in the project, we would see them all. The content assist shows all header files in a project, including those in subdirectories. A C header’s path is relative to the statechart it is imported into.

Click on the point.h entry in the menu to complete the import statement. The result looks like this:

import: "point.h"

interface:
    var pointA: Point

Data structure traversal via dot notation

The dot notation to access structure members can traverse an arbitrary number of stages. As an example, let’s define a datatype named Triangle. A triangle is defined by three points. Using dot notation in a statechart, you can navigate from a triangle to its individual points and further on to the points' coordinates.

The C header file triangle.h specifies the Triangle type:

#ifndef TRIANGLE_H_
#define TRIANGLE_H_

#include "./point.h"

typedef struct {
    Point a, b, c;
} Triangle;

#endif /* TRIANGLE_H_ */

A Triangle consists of the three Points a, b, and c. Let’s define a Triangle t in a statechart’s definition section as follows:

import: "triangle.h"

interface:
    var t: Triangle

With this definition we can use expressions like t.a.x, see the image below. Regardless of where you are currently editing an expression, you can always use the code assist to explore which fields are available at that very point and of which types these fields are. Example:

Content assist in data structure traversal

Pointers

Pointers are a core feature of the C programming language. itemis CREATE’s Deep C/C++ Integration is making C pointers available to you in your statecharts. In particular, you can

declare typed pointer variables,
assign a pointer to a pointer variable of the same type,
retrieve the pointer pointing to a given variable,
pass pointers as parameters to functions, and
receive a pointer as a functions return value.

Declaring pointer variables

From version 5.1 Create supports the usage of smart pointers. They can be used externally e.g. in a header file or can be declared internally e.g. as the type of a statechart variable. As smart pointers got introduced in C++11 they are only supported with our C++11 code generator. Other C domain code generators will replace smart pointers with raw pointers. With this addition, some generator options got introduced too to enable the customization of which parts of the generated code the user wants to use smart pointers. For more detail on that please see GeneratorOptions feature .

Please be aware of that unique pointers may result in not functioning code out of the box as they require special handling regarding ownership.

Pointer variables are declared in a statechart’s definition section as shown in the following example:

var n: int32_t
var pInt: pointer<int32_t>
var spInt: shared_ptr<int32_t>
var ppInt: pointer<pointer<int32_t> >
var pTriangle: pointer<Triangle>;

The declarations above declare

n as a (non-pointer) variable of type int32_t,
pInt as a pointer variable that is pointing to a variable of type int32_t,
spInt as a smart pointer variable that is pointing to a variable of type int32_t,
ppInt as a pointer that is pointing to a pointer that is pointing to a variable of type int32_t, and
pTriangle as a pointer to a variable of the self-defined type Triangle.

Please note: When closing the type specification in a pointer declaration with angle brackets, e.g., pointer<pointer<int32_t> >, the > characters must be separated from each other by one or more white space characters. Writing, for example, pointer<pointer<int32_t>> would result in an error. This restriction will be fixed in a later release.

Using pointer variables

In order to actually assign a pointer to a pointer variable, you have to get hold of that pointer. To retrieve the pointer to a variable v, use v's extension function pointer. That is, for a variable v, the expression v.pointer evaluates to a pointer to v. Each variable has the pointer extension function.

From version 5.1 all variables also have the unique_ptr, shared_ptr, weak_ptr extension functions that will function just like the already existing pointer extension, only retrieving the corresponding smart pointer instead of raw pointer type.

Please be aware that unique pointers may result in not functioning code out of the box as they require special handling regarding ownership.

Example: Let’s say the pointer variable pInt (declared in the example above) should point to the variable n. The following assignment accomplishes this:

pInt = n.pointer

Similarly, a pointer to a pointer to a base type can be retrieved as follows:

ppInt = pInt.pointer;

Or even:

ppInt = n.pointer.pointer

In order to deference a pointer, i. e. to retrieve the value of what the pointer is pointing to, use the value extension function, which is available on all pointer-type variables.

Example: Let’s say the pointer variable pInt (declared in the example above) is pointing to some int32_t variable. The value of the variable pInt is pointing to should be assigned to the int32_t variable n. The following assignment accomplishes this:

n = pInt.value;

Similarly, if ppInt points to a pointer pointing to some int32_t variable, the following statement retrieves the latter’s value:

n = ppInt.value.value;

Passing pointer parameters to C functions is straightforward. Let’s say you have a C function to rotate a triangle around a center point by a given angle. The C function is defined like this:

Triangle* rotateTriangle(Triangle* triangle, Point* centerPoint, float angle) { … }

Provided the function is declared in an imported C header file, you can call it directly like this:

pTriangle2 = rotateTriangle(pTriangle, pCenterPoint, 45.0);

Please note: Assigning a pointer to a pointer variable is only possible if the pointer types are the same.

Arrays

Unlike other variables, arrays are not defined in a statechart’s definition section, but rather on the C side in header files. Importing a C header containing an array definition makes the array available to a statechart.

While itemis CREATE’s Deep C/C++ Integration provides mechanisms for accessing individual elements of an existent array, arrays must be allocated statically or dynamically in C. Initializing the array elements is possible in C as well as in the statechart. However, depending on the concrete application it might generally be easier in C.

From version 5.1 it is also possible to use the array access on pointers that are declared in the statechart itself.

The header file sample_arrays.h defines a couple of sample arrays:

#ifndef SAMPLE_ARRAYS_H_
#define SAMPLE_ARRAYS_H_

#include <stdint.h>
#include "triangle.h"

int32_t coordinates[] = {0, 0, 10, 0, 5, 5};

Triangle manyTriangles[200];

int32_t * pArray[10];

#endif /* SAMPLE_ARRAYS_H_ */

The following arrays are defined:

coordinates is statically allocated to hold six int32_t elements and it is initialized with values for all six of them. More precisely, the number of elements in the initializer determines the size of the array.
manyTriangles is statically allocated with enough memory to hold 200 elements of the self-defined Triangle type. However, these elements are not initialized. This can and should be done either in C or in the state machine. An example is given below.
pArray is of size 10 and holds pointers to int32_t values.

As mentioned above, importing a header file containing array definitions into the statechart’s definition section is sufficient to make the arrays available in a statechart. Example:

import: sample_arrays

With this import, you can access the arrays in statechart language expressions, for example in a state’s local reactions:

entry /
coordinates[2] = 42

Writing to array elements is as straightforward as you would expect. Examples:

coordinates[0] = coordinates[0] + 1;
pArray[3] = n.pointer;
pArray[4] = coordinates[0].pointer

Passing arrays as parameters to C functions is straightforward. Let’s say you have a C function sort to sort the elements of a one-dimensional int32_t array and return a pointer to the sorted array:

int32_t* sort(int32_t data[], int size) {…}

Please note that in C a function cannot return an array as such, but only a pointer to it. Analogously you cannot pass an array by value as a parameter to a function, i. e. the data bytes the array is consisting of are not copied into the function’s formal parameter. Instead a pointer to the array is passed to the function, or – to be more exact – a pointer to the array’s first element. To express this in the function’s formal parameter type, you can specify the sort function equivalently to the above definition as follows. The data parameter is now specified as int32_t* data instead of int32_t data[], but the meaning is exactly the same.

int32_t* sort(int32_t* data, int size) {…}

Provided the function is declared in an imported C header file, you can call it directly like this:

sort(coordinates, 6)

Please note: The current itemis CREATE release only supports statically allocated arrays. Arrays dynamically allocated using malloc() or calloc() will be supported in a later version.

Enums

Besides specifying structured types, it is also possible to declare enumeration types in a C header. Here’s the header file color.h, which defines the Color enumeration type:

#ifndef COLOR_H_
#define COLOR_H_

typedef enum {
    RED, GREEN, BLUE, YELLOW, BLACK, WHITE
} Color;

#endif /* COLOR_H_ */

Now let’s extend the Triangle defined above by a fill color:

#ifndef TRIANGLE_H_
#define TRIANGLE_H_

#include "./point.h"
#include "./color.h"

typedef struct {
    Point a, b, c;
    Color fillColor;

} Triangle;

#endif /* TRIANGLE_H_ */

Similar to the Triangle type or any other C type, the Color enumeration type can be used in the statechart, e.g., by declaring an additional interface variable:

import: "color.h"
import: "triangle.h"

interface:
    var t: Triangle
    var c: Color = Color.BLUE

Please note that unlike structured types, enumeration variables can be initialized directly in their definitions within the statechart’s definition section.

In order to see which enumeration values are available, the content assist, triggered by [Ctrl+Space], is helpful again.

Using content assist to select an enumeration value [1]

Once initialized, the c variable can now be used, e.g., in an assignment to the triangle t's fill color:

t.fillColor = c;

Accordingly, during simulation, the values of enum variables are displayed in the simulation view. It is also possible to modify them manually.

Using content assist to select an enumeration value [2]

Operations

A function declared in a C header file becomes available in a statechart. The state machine can call it as an operation.

Let’s say our rectangle.h header file not only defines the data type, but also declares one or more C functions to operate on them. The following line declares a function named area, taking a Rectangle parameter by value and returning an int32_t result.

extern int32_t area(Rectangle r);

For the sake of the example, let’s assume the function calculates the area of the given rectangle. Of course we could also do this with means built into the statechart language. However, in the general case you neither can nor want to do that.

Implementing the functionality in the statechart language might not be possible, because the latter does not provide the necessary means, e.g., to pull some data from an external source.
Even if it would be possible to implement the functionality in the statechart language, it might still not be desirable, if the functionality has been developed and fully tested in C already. You will neither want to re-invent the wheel nor would you want to introduce any new errors into an alternative implementation.

itemis CREATE parses function declarations in header files and makes the functions available in the statechart language. It doesn’t care where those functions are defined – or whether they are defined at all – nor what they do. Questions like these will become relevant later when the state machine is generated as C source code, compiled and linked to the functions' implementations.

For now, once the statechart knows about the area function’s declaration in the C header file, the function can be used immediately in statechart language operations. A corresponding operation declaration in the statechart’s definition section is not needed. Example:

Using content assist to enter a C function call

Here’s the complete example with the area calculations done by the area function:

Example calling the "area" function

Example calling the “area” function

Please note: State machines calling C functions as operations are debarred from simulation and debugging. The simulator is not yet capable to call C functions.

C++ classes

Classes and structs declared in C++ header files are usable from statecharts as well.

class Point
{
    public:
        int32_t get_x();
        void set_x(int32_t x);
        int32_t get_y();
        void set_y(int32_t y);
    private:
        int32_t x;
        int32_t y;
};

By importing a header file containing this C++ class definition, one or more variables of the Point type can be defined in the statechart:

import: "Point.h"
interface:
    var PointA: Point
    var PointB: Point
    out event e

As expected, it is possible to access public functions and fields of these variables. For example, x and y can be set and read from within a state’s or a transition’s reactions:

entry / PointA.set_x(42); PointA.set_y(0)

[PointA.get_x() == 42] / raise e

There are some constraints which you must consider:

If you declare variable values or event payloads to be instances of a class or struct then the class must define a public default constructor (one without parameters).
If a variable value in a public interface is defined to be a class instance then the class must define a public copy constructor and a public assign operator. These exist if they are not explicitly deleted or declared private. This constraint does not apply to internal variables.
If an event payload is defined to be a class instance then the class must define a public copy constructor and a public assign operator. This constraint applies independent of the interface type.

Reference types can be used without these constraints.

C++ template classes and functions

Template classes

C++ allows to create generic constructs by defining templates. For example, if you want to be able to create Point objects with integer as well as floating point coordinates, you could write:

template<typename T>
class Point
{
    public:
        T get_x();
        void set_x(T x);
        T get_y();
        void set_y(T y);
    private:
        T x;
        T y;
};

This definition creates a generic type in itemis CREATE. In the definition section, you then supply the concrete type parameter, here int32_t:

import: "Point.h"
interface:
    var PointA: Point<int32_t>
    var PointB: Point<int32_t>
    out event e

Instead of int32_t, double, ComplexNumber, or any other type could have been specified instead.

itemis CREATE verifies the usage. Thus with int32_t, the function call PointA.set_x(4.2) would be flagged as an error.

Template functions

C++ also allows to create template functions, which can, but don’t have to, be a part of a class.

A typical example is a max(T a, T b) function:

template<typename T>
T max(T a, T b)
{
    return (a < b) ? b : a;
}

Template functions do not have to have their type parameter declared. itemis CREATE checks whether the supplied arguments are compatible. Calling max(4, 3.5) would be fine, and T would be inferred to be double, whereas max(4, true) is invalid, because integer types and boolean types are not compatible.

Namespaces

In C++, things can be organized in namespaces. Namespaces are typically applied to classes.

namespace Geo {

    class Point
    {
    public:
        double get_x();
        void set_x(double x);
        double get_y();
        void set_y(double y);
    private:
        double x;
        double y;
    };

}

To use the Point class, one would have to write Geo::Point in C++. In itemis CREATE, namespaces are reflected as packages. For each header file you import into your statechart, a package is created, plus an additional package for each namespace.

In the definition section, one would write:

import: "Point.h"
interface:
    var PointA: Geo.Point
    var PointB: Geo.Point
    out event e

Namespaces can be nested, so if namespace Geo would be contained in namespace Math, Point would be addressed as Math.Geo.Point.

Simulation

During a statechart simulation full access to the C data structures is possible on all layers. The user can inspect them as well as modify them in the simulation view.

The state machine below exemplifies this. Initially it defines two rectangles a and b with certain widths and heights. The state machine calculates the rectangles' respective area size, stores their sizes in two int32_t variables named area_a and area_b, and compares them. Depending on the result, it proceeds to state A is larger or to A is smaller. Only if both a and b have the same area – not necessarily the same width and height –, the state machine proceeds to its final state.

When one of the states A is larger or A is smaller is active, the rectangles' properties can be changed. Triggering the compare_size event transitions to the Check state which repeats the area size comparison as described above.

The rectangle comparison statechart

The state machine’s definitions are as follows:

import: "rectangle.h"

interface:
    var a: Rectangle
    var b: Rectangle
    var area_a: int16_t
    var area_b: int16_t

internal:
    event compare_size

The Rectangle datatype is defined in a new header file rectangle.h with the following contents:

#include "./point.h"

typedef struct {
    Point lowerLeft;
    int16_t width, height;
} Rectangle;

In order to simulate the statechart, right-click on the statechart file in the project explorer and select Run As → Statechart Simulation from the context menu.

The statechart simulation

starts,
performs the initializing actions specified in the transition from the initial state to the Check state,
in the Check state, calculates the rectangles' areas and stores the results in the area_a and area_b variables,
transitions to the A is larger state, because its guard condition is fulfilled, and
stops, waiting for the compare_size event to occur.

Inspecting C data structures

The simulation view in the screenshot above is showing the state machine’s variables and their values. Click to open or close the nested data structures. The image below shows in particular

the rectangles' respective width and height values as have been set initially,
the calculated areas of the a and b rectangles,
the coordinates of the points defining the respective lower left corner of the rectangles.

Warning: Simple C variables and fields in C data structure are not initialized. Never try to read a variable or field you haven’t written before, because it might contain arbitrary values.

Even if the Point data structures in the example above look like having been initialized to defined values, they are not. Without going into details, in C, variables are generally not initialized. This also holds for statechart variables from the C integration. If you are reading a variable, make sure you have written to it before. Otherwise you might get surprising and non-deterministic results.

Modifying C data structures

Change a variable’s or field’s value as follows:

Click on the value displayed in the simulation view.
Enter the new value into the text field, see figure "Modifying C data values" where a.height is being edited and the previous value 7 is replaced by 3.
Press the [Enter] key to quit editing and to write the new value to the variable or field. Giving the input focus to another window has the same effect.
You can cancel editing by pressing the [Esc] key. The variable’s or field’s value remains unchanged.

Modifying C data values

In the example, click compare_size to trigger the event. The state machine transitions to the Check state, recalculates the areas, and behaves as explained above.

Rectangle areas modified and rechecked

Looking up a type definition

Given a variable definition in a statechart’s definition section, you can lookup the corresponding type definition. The definition section must be in editing mode, i.e., you must have double-clicked into it. Now press the [Ctrl] key and move the mouse pointer over the type name. The former changes its shape into a hand symbol and the latter changes into a hyperlink:

Looking up a C type

Click on the hyperlink to open the header file containing the respective type declaration.

Showing the C type definition

Generating C source code

Code generation, i.e., turning a statechart model into source code of a programming language, is explained in the section Generating state machine code. Therefore we won’t go into the details here, but instead only put some emphasis on code generation specialties of Deep C/C++ Integration.

Creating a generator model

In the statechart model introduced above, do the following:

In the project view, right-click on the project’s name. The context menu opens.
In the context menu, select New → Code generator model. The itemis CREATE generator model wizard opens.
Enter a filename into the File name field, e.g., c.sgen, and click Next >.
In the Generator drop-down menu, select itemis CREATE Statechart C Code Generator.
Select the statechart models to generate C source code for. Click Finish.

itemis CREATE creates the following generator model in the file c.sgen:

GeneratorModel for create::c {

    statechart statechart {

        feature Outlet {
            targetProject = "Geometry"
            targetFolder = "src-gen"
            libraryTargetFolder = "src"
        }
    }
}

itemis CREATE creates the target folders src and src-gen and generates the C source representing the statemachine into them.

The generated C code

Particularly interesting are the files Statechart.h and Statechart.c.

Statechart.h first includes the sc_types.h header followed by very same C header files that have been included in the statechart:

#include "sc_types.h"
#include "rectangle.h"

The generated code in Statechart.h then uses the native standard and user-defined C data types. For example, the statechart implementation defines the type StatechartIface as follows:

/*! Type definition of the data structure for the StatechartIface interface scope. */
typedef struct
{
    Rectangle a;
    Rectangle b;
    int32_t area_a;
    int32_t area_b;
    Point p;
} StatechartIface;

By including Statechart.h all definitions are available in Statechart.c, too. For example, a getter and a setter function for the Rectangle variable a are defined as follows:

Rectangle statechartIface_get_a(const Statechart* handle)
{
    return handle->iface.a;
}
void statechartIface_set_a(Statechart* handle, Rectangle value)
{
    handle->iface.a = value;
}

The external area function is called in the entry actions section of state Check:

/* Entry action for state 'Check'. */
static void statechart_enact_main_region_Check(Statechart* handle)
{
    /* Entry action for state 'Check'. */
    handle->iface.area_a = area(handle->iface.a);
    handle->iface.area_b = area(handle->iface.b);
}

The @ShortCIdentifiers annotation

It is possible to add annotations to a statechart’s specification to alter their or the code generator’s behavior, see Statechart Annotations.

The C/C++ domain offers one more annotation: @ShortCIdentifiers helps you to keep the generated code compliant to rules which require C identifiers not to be longer than 31 characters (or rather, to be uniquely identified by the first 31 characters). To achieve this, instead of aggressively shortening names which are part of a statechart’s API, itemis CREATE gives feedback about the names that will be generated and warns if any user input results in C code that is non-compliant with the 31 character rule. This puts the user in charge of the naming scheme and keeps the resulting C identifiers predictable.

This is mainly done by:

Using only the actual state’s name to identify it and forcing you to use individual names for all states
Checking all names that will be generated by constructs in the statecharts and providing you with feedback if any of them will be longer than 31 characters
An intelligent name shortening strategy is applied to the static functions in the statechart’s source file that keeps a good balance between readability and shortness

Please note that the generator model’s option statemachinePrefix is ignored when @ShortCIdentifiers is used.

Keep in mind that all public functions and types of the statechart are prefixed with its name, so keeping that one short helps a lot.

Example

See the following example:

Unambiguous state names produce errors

State names that are not globally unique produce errors.

Warnings for elements in the definition section

The name of some elements in the definition section produces warnings because resulting identifiers in the source code will be longer than 31 characters.

All issues resolved

All issues resolved: the states were renamed to be globally unique and some identifiers as well as the statechart’s name were shortened to keep everything short.

The state’s names need to be globally unique because of a change in the naming scheme of the state enum.

Enum without @ShortCIdentifiers:

/*! Enumeration of all states */ 
typedef enum
{
	House_last_state,
	House_main_region_Idle,
	House_main_region_Automation,
	House_main_region_Automation_heater_Manual,
	House_main_region_Automation_heater_Auto,
	House_main_region_Automation_heater_Auto_modes_Normal,
	House_main_region_Automation_heater_Auto_modes_Absence,
	House_main_region_Automation_lights_Lights_Off,
	House_main_region_Automation_lights_Lights_On,
	House_main_region_Automation_pond_Pond_Off,
	House_main_region_Automation_pond_Pond_On
} HouseStates;

Enum with @ShortCIdentifiers:

/*! Enumeration of all states */ 
typedef enum
{
	House_last_state,
	House_Idle,
	House_Automation,
	House_Manual,
	House_Auto,
	House_Normal,
	House_Absence,
	House_Lights_Off,
	House_Lights_On,
	House_Pond_Off,
	House_Pond_On
} HouseStates;

Notice how the state’s names are not prefixed with their containing regions anymore to save characters.

The name shortening algorithm for the static functions works like this, again without @ShortCIdentifiers:

/* prototypes of all internal functions */
static sc_boolean check_main_region_Idle_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_heater_Manual_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_heater_Auto_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_heater_Auto_modes_Normal_lr0_lr0(const House* handle);
static sc_boolean check_main_region_Automation_heater_Auto_modes_Normal_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_heater_Auto_modes_Absence_lr0_lr0(const House* handle);
static sc_boolean check_main_region_Automation_heater_Auto_modes_Absence_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_lights_Lights_Off_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_lights_Lights_On_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_pond_Pond_Off_tr0_tr0(const House* handle);
static sc_boolean check_main_region_Automation_pond_Pond_On_tr0_tr0(const House* handle);

With @ShortCIdentifiers annotation:

/* prototypes of all internal functions */
static sc_boolean Idle_tr0_check(const House* handle);
static sc_boolean Automation_tr0_check(const House* handle);
static sc_boolean Manual_tr0_check(const House* handle);
static sc_boolean Auto_tr0_check(const House* handle);
static sc_boolean Normal_lr0_check(const House* handle);
static sc_boolean Normal_tr0_check(const House* handle);
static sc_boolean Absence_lr0_check(const House* handle);
static sc_boolean Absence_tr0_check(const House* handle);
static sc_boolean Lights_Off_tr0_check(const House* handle);
static sc_boolean Lights_On_tr0_check(const House* handle);
static sc_boolean Pond_Off_tr0_check(const House* handle);
static sc_boolean Pond_On_tr0_check(const House* handle);

Currently supported primitive types

Deep C/C++ Integration natively supports the following primitive C types. That is, in a statechart without any additional data type definitions, the following types are readily available:

bool
double
float
int16_t
int32_t
int64_t
int8_t
string
uint16_t
uint32_t
uint64_t
uint8_t
void

Current restrictions

The current release candidate of itemis CREATE PRO is still missing some C functionalities that will be approached as soon as possible by subsequent releases. Among others, the following issues are known to be not available yet:

Syntax issue when declaring nested pointers.

There is a known syntax issue when declaring nested pointers in the statechart’s definition section. It is required to put a space
between every closing character (>) after declaring the type for the pointer.

Type range checks

Type range validations are currently not implemented. As a consequence, it is possible to e.g., assign an int32_t value to an int8_t variable one without any warning.

Plain struct, union, and enum types

In C it is possible to define structs, unions and enums without a typedef. They can be referenced by using the corresponding qualifying keyword ( struct, union, or enum, respectively). As the statechart language does not support these qualifiers, the usage of struct, union and enumeration types is currently restricted to those defined by a typedef.

Evaluation of functions in the simulation

Using the C/C++ domain, it is possible to call functions that are declared in header files. The generated code will do this correctly, but the simulation will not actually evaluate the functions, for multiple reasons:

Parsing and interpreting C-Code completely and correctly with all possible side effects is very hard and we could never guarantee that itemis CREATE does the right thing in the simulation.
Even if we could do that, the Compiler can link against one of many possible implementations of the same declaration, and choosing the correct one would be pretty hard, too.

Due to this, we decided not to implement this feature, and doing so is currently not on our roadmap.

However, when using our testing framework SCTUnit, you have the option to mock these functions, and these mocks are then called during testing.

Constructors

Using the C/C++ domain allows you to import classes defined in a C++ header file, and use them as types. This means that you can instantiate objects of these types just like in regular C++ code. However, itemis CREATE currently does not support constructors, so there are certain limitations:

If the class has a default constructor with no arguments, you can just declare the variable as usual in the statechart: var o: MyClass. The constructor of the generated statechart class will then automatically call the default constructor of MyClass to instantiate the object.
If the class does not have a default constructor, this will fail. In this case, you should declare a pointer instead: var o: pointer<MyClass> - this way, the constructor of the statechart does nothing at all. Instead, you can then assign a proper value to it, ideally after you call the statechart’s init-function, and before you call the enter-function. This ensures correct initialization before the statechart is running.

Please get in touch with us

Please note that the preceding list of restrictions might not be complete. If you discover any further problems, please do not hesitate to contact us! Your feedback is highly appreciated!

Multi state machine modeling

The behavior of large systems is often too complex to be captured by a single statechart. So if a statechart gets too large you should think about splitting it into two or more smaller parts. Beside the fact that the smaller state machines are easier to handle and maintain there are additional reasons for using multiple state machines instead of single monolithic ones:

Separation of concerns enables a better software architecture.
State machines can be reused in different contexts. So if you have identical copies of sub states spread around your state machines then this could be a good starting point.
If you build a distributed system then you require separate state machines for the different nodes.

This chapter describes how you can use itemis CREATE to model and simulate a system which consists of multiple collaborating state machines and how you can embed a statechart as a sub machines into another statechart. This chapter introduces all relevant concepts using an example.

The example is a traffic control of a street crossing using traffic lights. While a single traffic light is not so complex the coordination of different traffic lights on a crossing is a good example to highlight the collaboration between different state machines.

Street crossing with three state machines.

The example consists of a system of three state machine instances. There are two instances of the statechart TrafficLight . Each instance just cares about controlling the different modes of a single traffic light. The TwoWayTrafficControl coordinates both traffic lights and makes sure that the traffic is always safe by making sure that no two traffic lights are green at the same time.

Referencing state machines

First of all – in order to enable collaboration between separate state machines it must be possible that state machines can reference other state machines. To establish such a reference two steps are required:

The external statechart must be made visible by defining an import scope using import: "xyz.sct" in the statecharts declaration area. Specify relative paths if the statecharts are not located in the same directory.
Define a variable of the desired state machine type: var otherMachine : SomeMachineType

For our example statechart TwoWayTrafficControl the declarations look like this:

import: "TrafficLight.sct"
interface: 
    var trafficLightA : TrafficLight
    var trafficLightB : TrafficLight

According to the steps described above the statechart TrafficLight.sct is imported. As two instances of this referenced statechart are required, two variables are defined. So if you want to implement a three or four way traffic control you can simply define as many variables for state machine references as you require.

State machine types and instances

A statechart does not only contain the definition of behavior. It also includes structural properties like its declared variables and events. These define its public interface and this interface is represented by a type.

Lets take a look at the example statecharts to get an idea how the state machine types look like:

State machine types derived from statechart definitions.

The statechart TrafficLight.sct defines the type TrafficLight and the statechart TwoWayTrafficControl.sct defines TwoWayTrafficControl. The types include all members defined in the statecharts declaration section. The variables which are of type TrafficLight are references to instances of this type.

You should know the following facts about state machine types:

Each statechart has its own type. This type has the same name as the statechart.
The state machine type is a class type. All members defined in the statechart’s default interface are direct members of this type.
These members can be variables, events, and operations.
The type members have the identical name as defined in the statechart.
State machine types used in variables, events and operations are always reference types.
Named interfaces are owned by the state machine and are represented as a member with the interface name as name.
These named interface members are complex types which include all members defined in the interfaces.
All declarations of the internal scope are not exposed through the state machine type.
The state machine type inherits from the abstract type IStatemachine. This type defines additional life cycle operations which are implemented by each state machine.
Each statechart owns an additional enumeration type named <StatechartName>States. It defines an enumeration value for each state of the statechart.

If you know the state machine code which is generated from statecharts then you will discover that the definitions of the state machine types directly match the definitions of the generated code.

State machine types are always used as reference types. This implies that the state machine which defines a variable of a state machine type does not own the state machine instance. It will never be created by the state machine itself.

As a state machine type is a regular type you can use it like any other type. So you can assign state machine references to variables, use it as event payload, pass it as operation parameter, or use it as an operation’s return value.

Variables of state machine references can be reassigned. A valid value is null. null is the default value after initializing a state machine.

Sending events, receiving events, and accessing variables

A state machine reference can be used to interact with the referenced state machine. All elements which are exposed by the state machine type can be used:

Raise in events on the referenced state machine.
React on out events from referenced state machines.
Get and set variables (including referenced state machines).

The statechart TwoWayTrafficControl raises different events on the referenced state machines.

Traffic controller raises events on referenced state machines.

Different states (like Release A) also use outgoing events ( trafficLightA.released) as transition triggers.

A loosely coupled architecture makes use of asynchronous message passing and this perfectly matches to statechart events. A statechart which raises an event should not make any assumptions when the event is processed.

Accessing variables implies a tighter coupling of state machines as these are accessed in a synchronized fashion.

As an example the statechart TwoWayTrafficControl could configure the TrafficLight state machines using variables that these provide.

entry / trafficLightA.config.realeasePeriod = 60

Here the v ariable releasePeriod is set as an entry action. releasePeriod is defined by the named interface config thus it is accessed in two step using the dot expression ‘.’ .

Controlling a state machines life cycle

In addition to the events and variables which are declared by the statechart, also additional life cycle operations exist. As explained before (see type IStatemachine in previous chapter), they implicitly exist for each state machine and can be used to control its life cycle.

operation	purpose
enter() : void	An inactive state machine can be activated by calling this operation. During activation the initial state will be activated and all required entry actions are executed. A state machine is inactive by default after creation.
exit() : void	A call to exit deactivates an active state machine. During exit, all active states will be exited and all relevant exit actions will be executed. After exit, no state is active.
isActive() : boolean	Returns true if the state machine is active and false otherwise. A state machine is active if there is at least one active state. This operation can be used in guards to test the life cycle state of a state machine.
isStateActive(state) : boolean	Can be used in guards to check the activation of a specific state. The state parameter must be of the state machines state enumeration type.
isFinal() : boolean	Returns true if all active states are final states. The final state won’t change until the state machine is exited and reentered. This operation can be used in guards to check if a state machine has finished its work.
runCycle() : void	Performs a state machine run-to-completion step. If a state machine takes full control of a cycle-based state machine then it has to decide when the run-to-completion step must be executed.
triggerWithoutEvent() : void	For EventDriven statecharts, it performs a state machine run-to-completion step without raising any event. It can be also used by the client code.

Using these operations implies a tighter semantic coupling of separate state machines. It is the basis for the implementation of sub state machines as described in the following chapter.

An example for using life cycle operations is given in:

the next chapter
state machine activation
and state machine testing

Defining sub state machines

A common concept for structuring statecharts is the decomposition into different sub state machines. This is a concept that you can find in modeling languages like the UML and others.

The basic idea is that a state machine which is assigned to a state as sub machine is executed as if it is part of the enclosing state machine. This means its life cycle is coupled to the life cycle of its owning state. It will be activated when its parent state becomes active, and will be deactivated when the parent state deactivates.

Such a sub machine pattern can be defined using the life cycle methods introduced in the previous chapter. The pattern for using sub state machines looks like this:

entry / otherMachine.enter
oncycle / otherMachine.runCycle 
exit / otherMachine.exit

The call to runCycle is only required if the referenced state machine is cycle-based. The equivalent is the following statement:

submachine otherMachine

The submachine statement is not only a shortcut. It is more expressive, less verbose and avoids errors by applying higher level validations. You can simply use this statement like any other within the state. Using it is recommended when you want to use sub state machines.

If the referenced state machine is event-driven, then the triggerWithoutEvent operation can be called, which will perform a run-to-completion step without raising any event.
This allows the guard conditions to be evaluated and the transitions to potentially fire. It is also suitable for firing transitions with the “always” keyword.

So lets take a look how sub state machines can be applied to the traffic control example. The state Operate contains several sub states which control the traffic flow by alternately releasing and blocking the traffic flow of the two directions.

Traffic controller raises events on referenced state machines.

This set of sub states consists of two groups which are similar to each other. The first group consists of the states all blocked before A, Release A, and A Released. The second group is identical except for the fact that A is replaced by B. So the behavior is cloned. Sub state machines can be used to eliminate such redundancies.

Using sub machine in traffic control.

Here, introducing the submachine required three steps.

Create a new statechart ReleaseProcess.sct and copy the three states of the identified group. As the statechart should not be specific for a specific traffic light it requires a variable to reference the controlled state machine: var trafficLight : TrafficLight
Replace each group by a single state. These are Process A and Process B here.
Integrate the new statechart ReleaseProcess as a sub state machine.
- This requires an additional variable which holds the reference to the sub state machine: var process : ReleaseProcess
- The new states integrate the submachine. On entry, the new process state machine is configured with the proper traffic light state machine: entry / process.trafficLight=trafficLightA
- The sub machine is hooked into the state: submachine process
- The transitions of the two states are triggered when the ReleaseProcess state machine has finished its work and is in a final state. The guard is defined on the transitions: [process.isFinal]

This results in the following TwoWayTrafficController and ReleaseProcess state machines:

Traffic controller raises events on referenced state machines.

This example shows a typical scenario where using sub machines makes much sense. Here, sub machine controls a process which consists of several steps. Here, it just contains a happy case but it may also define error states. This process can be reused easily if the state machine should be extended to a 3 or 4-way traffic control. So setting up a 4-way traffic control in the initial statechart would require 4x3=12 states while using a sub machine requires 4+3=7 states.

In this example the state machine process is used as sub machine in both states Process A and Proces B. When state machine process reaches its final state, the state transition from state Process A to state Process B will be executed. During this state transition, first, Process A will be exited. As a result also the sub machine will be exited. Second, Process B will be entered. As a result, the process state machine will be configured to use the other traffic light state machine and the process state machine will be activated by calling its enter operation. This will activate the initial state Safe. So the process state machine is reset to control the next process.

Sub machines are comparable with sub regions and as it is possible to define multiple sub regions for a state it is also possible to define any number of sub state machines. It is even possible that a state defines both – sub regions and sub machines. If both are defined then they are processed according to the execution order:

In the case of @ChildFirstExecution the sub regions are processed first.
In the case of @ParentFirstExecution the sub machines are processed first.

Additionally, the order of the submachine statement within a state’s behavior definition is relevant for the execution order:

Submachines are entered, exited, and executed (runCycle call) according to the order of the submachine statements.
Entry actions which are defined before the submachine statement are executed before entering the sub machine. Those defined after are executed later. This may be relevant for properly setting up sub machines.
Exit actions which are defined before the submachine statement are executed before exiting the sub machine. Those defined after are executed later. This may be relevant for properly tearing down sub machines.
In the case of cycle-based sub machines all local reactions of a state which are defined before the submachine statement are executed before executing the sub machine’s run-to-completion step. Those defined after are executed later.

As shown in the example a state machine can be used as a sub machine within different states. The only constraint that must be considered is that these states must be exclusive to each other so that both states can’t be active at the same time. In other words, a machine can only be a sub machine in one active state at once. The subsequent use of a state machine as sub machine is no problem.

Multi state machine modeling principles

The ability to access the state machine life cycle operations which were introduced in the previous chapter provides the basis for the implementation of sub state machine. Nevertheless, the concept of sub state machines defines tight life cycle constraints and this is just one pattern to control a state machine. The life cycle operations can also be used to control state machines beyond the concept of sub machines. So it is possible to enter a machine in a state and exit it in another state.

Future versions of this document will discuss different principles and best practices for multi state machine modeling.

Simulating multiple state machines

The statechart simulation supports the simulation of multiple statechart instances. Simply choose a statechart and choose Run As > Statechart Simulation from the menu.

If the statechart defines variables which refer to other statechart types then the simulation engine will care about setting up the simulation scenario which includes statechart instances of the involved statechart types.

When starting the simulation for the statechart TwoWayTrafficControl the simulation view will list TwoWayTrafficControl.sct as the current simulation session. Additionally, the statechart instances which were created for the simulation session are listed as children of the simulation session.

The first statechart simply has no specific name and is of type TwoWayTrafficControl . The second and third are instances of the statechart TrafficLight. Their name is the name of the variables which are defined by TwoWayTrafficControl as statechart references.

If you click on the statechart instances then a simulation viewer for the specific statechart instance will be opened.

In the detail view below also the variables that reference statecharts are visualized with a statechart icon. You can unfold the details of the referenced statechart by clicking on the grey triangle.

Simulation view for traffic control.

State machine creation

The simulation engine creates statechart instances according to the following strategy:

create the root statechart instance
for each defined statechart reference of the instance
1. if no instance was created for this reference definition (precludes infinite recursion)
  1. create a statechart instance of referenced type
  2. set the reference
  3. continue with 2.)

As described in the previous chapters - statechart instances never create other statechart instances. Statecharts are created by the simulation environment.

State machine activation

After all statechart instances were created and connected the simulation engine will activate the root statechart instance. All other instances are not activated. This implies that the root statechart must initiate the activation of the referenced machine instances. This can be done by

calling their enter methods
or using them as sub machines.

If this is the case then everything works out of the box. There are additional cases where controlling the referenced statechart’s life cycle is not desired, e.g. to have a system of loosely coupled instances. Such systems typically just send events to each other and are inherently asynchronous. If you run the simulation for one of the involved statecharts then all instances except for the simulation root will never be activated.

In these cases you should setup an additional statechart which controls the life cycles of the loosely coupled state machine instances. This statechart defines the system behavior and thus we call it system statechart.

This case can be illustrated using the traffic light control example. Here, all involved statecharts interact using events. An additional statechart StreetCrossingSystem.sct defines the system behavior. This includes the start up sequence of all involved statechart instances.

system behavior of a street crossing.

The system statechart defines a reference called controller to a TwoWayTrafficControl state machine type. It does not start up everything immediately – what would be possible – but defines a set of states which define different system scenarios. The initial state is Off. In this state no state machine is active. By raising the event startAll the system enters the state On which makes sure that all state machines are active. Mention that the system behavior can access the referenced statecharts of referenced statecharts.

The system behavior also defines an additional state for each TrafficLight state machine instance. Here, a temopary outage of a TrafficLight is simulated by deactivating the machines.

System statecharts can be used to fully control state machines. They can be used to set up complex system scenarios and finally may automate execution sequences to bring the system in a defined state which would require much click work for the user.

Testing multiple state machines

SCUnit supports unit testing of multiple state machines. A SCTUnit test is defined for a state machine type which is the test instance of the unit test.

If the statechart defines variables which refer to other statechart types then the test environment will care about setting up the test scenario which includes statechart instances of the involved statechart types. Here the same instantiation strategy as described for the simulation is applied.

If the statechart under test does not control the life cycle of the referenced state machines, then this can simply be done by the test case itself.

An simple test case for the traffic control example could look like this.

testclass TwoWayTrafficControl for statechart TwoWayTrafficControl {
	@Test operation testStartUp() {
		enter  
		trafficLightA.^enter
		trafficLightB.^enter
		assert active (main.Off)
		assert trafficLightA.isStateActive(TrafficLightStates.Off)
		assert trafficLightB.isStateActive(TrafficLightStates.Off)
	}
}

In SCTUnit state machines must be activated explicitly. this is also true for the state machine under test which is a TwoWayTrafficControl state machine instance. The machine under test is activated by the enter statement while the two TrafficLight state machine instances are activated by calling the enter operation on the reference.

The following assertions check if the initial states were activated. This is done by using the built-in function active for the machine under test while the referenced machines are tested using the isStateActive operations.

To be able to call the triggerWithoutEvent operation for EventDriven statecharts a variable have to be defined for the statechart with the type of Statemachine. After that through this variable, every operation defined by the statechart type will be accessible.

Use the SCTUnit built-in functions for the state machine under test and use the operations defined by the state machine types for the referenced state machines.

Generating code for multi state machine systems

If a statechart uses other statecharts then this will be the same on the level of the generated code. You will find dependencies from the generated using state machine type to the the generated used state machine type.

The code generation process does not change when statecharts use other statecharts. Simply define the code generator ( sgen ) files as before. Make sure that the generator properties, especially those that relate to output paths fit together.

SCXML domain

itemis CREATE comes with an SCXML domain which allows to generate SCXML code from your statechart, as well as to simulate and test it in a way that is compliant to the SCXML execution semantics.

SCXML, short for State Chart XML, is a statechart interchange format. It is based on XML and has been standardized by the W3C. This standardization makes statecharts highly portable and independent of a particular implementation. The prerequisite is of course that the respective execution environment corresponds to the SCXML specification.

The current version of the specification was released by the W3C in September 2015. A “hello world” in SCXML looks like this:

Please be aware that the SCXML Integration requires a Professional Edition License.

<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="hello">
  <final id="hello">
    <onentry>
      <log expr="'hello world'" />
    </onentry>
  </final>
</scxml>

The XML defines all the states, transitions, events and variables used in the state machine. Besides the state machine’s structural elements, the SCXML standard also defines the execution semantics of that state machine. And this is one of the biggest advantages of SCXML – the same statechart model can run on different SCXML engines on different platforms and it always behaves in exactly the same way – as long as the engines conform to the specified execution semantics.

SCXML is supported on nearly all platforms. For Java, Apache Commons SCXML is the most popular SCXML Engine. There are even SCXML engines written in JavaScript to be used in web applications, like SCION. Another very popular platform that uses SCXML for Human Machine Interfaces is the SCXML Interpreter for Qt.

To use the SCXML domain, just select it on the domain selection page when creating a new statechart. Alternatively, you can select it in the statechart’s property view. When using the SCXML domain, everything will by fully compliant with the SCXML standard. We adapted the built-in simulation engine to reflect the SCXML execution semantics, and of course the SCTUnit framework also supports the SCXML standard. Thus, you can be sure that your SCTUnit test results exactly reflect the behavior of the SCXML engine of your choice.

SCXML code generation

Generating SCXML code works like with any other code generator. You need to create a generator model and select the SCXML code generator. Please note, that your statechart must have the SCXML domain enabled.

In the generator model, you need to specify the target folder for the generated XML file. For this, you can use the Outlet feature like for any other code generator in itemis CREATE:

GeneratorModel for create::scxml {

    statechart example {

        feature Outlet {
            targetProject = "scxml.example"
            targetFolder = "gen"
        }
    }
}

This example will generate the XML file into the “gen” folder of your “scxml.example” project.

You can also omit the targetProject attribute and specify a path on your file system. The path can be absolute or relative to the generator model location.

Simulating and testing SCXML statecharts

Statecharts with the SCXML domain can also be simulated in the same way standard statecharts are simulated. The only difference is that the itemis CREATE simulation engine will use the Apache Commons SCXML engine under the hood. This ensures that the simulation shows the same behavior as when using the SCXML model in other contexts. The same holds for using our test framework SCTUnit with an SCXML statechart.

On Target Debugging with YET

itemis CREATE statechart models are executable. There are many use cases that require information about the execution itself. Examples are remote debugging of state machines, execution analysis, testing, co-simulation and others. This information may be provided live during the execution or it could be used post-mortem when the execution of the system already finished. In any case this information must be explicit and it must be possible to store it persistently and provide other tools access to this information.

The YAKINDU Execution Tracing (YET) infrastructure provides open formats, protocols, and APIs. It enables interoperability between state machines which execute on a target in the one side and itemis CREATE (and other) tools on the other side.

This chapter describes some application scenarios at first and then describes how to use YET

Please be aware that YET tracing and debugging requires a Professional Edition License.
Please be aware that YET tracing and debugging is currently only supported by the C code generator.

Application scenarios

The execution trace model enables interoperability between different tools and as such serves a large number of application scenarios. The possible interoperability is shown in the following figure.

Interoperability based on execution traces

Interoperability based on execution traces

One important part is to enable execution tracing and stimulation for all contexts in which statecharts are executed. One important context is a concrete collaborative embedded system which executes one or more state machines. The others are simulations like the itemis CREATE interpreter based simulation or a Functional Mock-up Interface (FMI) based co-simulation context. On the other side there are tools which analyze the system or the statechart execution. These interpret and analyze the statechart execution traces in a specific way. Some of these just consume execution traces. Others can also stimulate execution and as such can be executed ‘in the loop’ with statecharts.

The execution trace decouples the statechart execution from analysis tools. So, both sides can be combined in a flexible way with each other. There are some application scenarios which are implemented based on this concept.

Model-level target debugging of state machines

In (embedded) software development scenarios, CREATE Statecharts are transformed to state machine code that runs within a target application. To enable model-level debugging of these state machine implementations within the itemis CREATE, a YET based integration is applied.

Integration scenarios for model-level target debugging

Integration scenarios for model-level target debugging

Model-level debugging may cover two variants. First, a bidirectional online integration based on streams (YET stream). Second, a file-based integration (YET file) which covers offline post-mortem analysis of execution traces.

In both cases YET must contain execution trace events that allow:

tracking of variable values
tracking of statechart events
tracking of active states and transitions

YET stream is bidirectional and also supports

changing variable values and
raising events

on the state machine if that direction is supported by the target application.

Of course YET traces can be analyzed manually as the file format is human readable. This is already a great help in the day to day work. Additionally, tool support enables the visualization of execution traces using the itemis CREATE simulation UI. This enables the playback of traces stored in files or the live visualization and interaction based on a YET stream.

Test statechart execution traces using SCTUnit

While the model-level target debugging supports the interactive analysis of a state machine execution there are cases where automated checking of execution results are required. This is the case if execution traces are very large or must be analyzed very often. A specific kind of automated execution analysis, which is supported by itemis CREATE, is SCTUnit. SCTUnit is a model-level unit testing framework and can check statechart behavior for correctness. As a YET trace is a representation of a statecharts behavior it can be used as a subject of test. According to the the debugging scenario, which are described in the previous section, unit tests can be executed on a execution trace which is stored in a file. If it is connected to a statechart using a YET stream then also stimulation of the statechart and an ‘in the loop’ execution is possible. This can be used to set up HiL (or other kind of XiL) test scenarios.

Testing state machine execution on an embedded target

Testing state machine execution on an embedded target

SCTUnit itself is a text based language which follows the typical XUnit testing approach. Test cases are implemented as simple scripts. These scripts can directly be executed in the itemis CREATE tool or can be transpiled to code. A very simple example for a statechart unit test provides the following code:

testclass TrafficLightTest for statechart TrafficLightCtrl {
	
	@Test operation switchTrafficLightOn () {
				
		// given the traffic light is inactive
		assert !is_active
		// when
		enter
		// then traffic light is off which means no color was switched on
		assert TrafficLight.displayRed
		assert !TrafficLight.displayGreen
		assert !TrafficLight.displayYellow
	}
	

	@Test operation switchLightFromRedToGreen () {
				
		// given
		switchTrafficLightOn
		// when
		raise TrafficLight.releaseTraffic
		proceed 60s
		// then 
		assert TrafficLight.displayGreen
	}
}

The unit test is defined as a test class. A test class refers to the statechart under test and defines two test cases. Each is implemented by a test operation. ‘assert’ statements check properties of the state machine. The ‘enter’ statement activates the state machine and ‘raise’ raises an event. So both are stimuli processed by the statechart. The ‘proceed’ statement controls time and continues the test after 60 seconds have passed. A unit test is optimized to check specific execution sequences. For more complex conditional and iterative scenarios also ‘if’ statements and ‘while’ loops can be defined which can make use of local variables.

FMI based co-simulation

Co-simulation is a major field for the application of YET. itemis CREATE can be used to create Functional Mock-up Units (FMUs) that can be integrated in co-simulations based on the Functional Mock-up Interface (FMI) standard. Different scenarios are supported. First, the debugging and testing approaches described in the previous sections can also be applied using a FMI co-simulation instead of a concrete embedded target. An additional scenario is to integrate the CREATE Statechart simulation into a FMI co-simulation using a tool wrapper FMU. This is a FMU which wraps a simulation tool and does not execute a statechart on its own. Instead, the statechart is executed by the CREATE Statechart simulation. This simulation runs in a separate process. This requires execution events to be exchanged between the FMU and the simulator.

FMU tool wrapper delegates execution to itemis CREATE simulator

FMU tool wrapper delegates execution to itemis CREATE simulator

Integrating CREATE Statecharts in FMI-based co-simulation scenarios requires additional plugins. A detailed description of this features is not included in this document but it will follow soon. Please contact statecharts@itemis.com if you require more information earlier.

Analyse statechart execution using data visualization & analysis tools

In addition to the tool features provided by itemis CREATE, out of the box analysis and trace visualization tools can be integrated. An example for such a tool is impulse which is a visualization and analysis workbench. It enables engineers to understand and debug complex systems by relating signals and data from arbitrary sources to statechart execution. This data can be visualized using a rich set of diagrams.

CREATE Statechart execution visualized in impulse

CREATE Statechart execution visualized in impulse

The correlation of data from different sources and its visualization is not scope of itemis CREATE tools. Thus it makes much sense to integrate dedicated tools for this purpose. impulse can read and analyse YET trace files of CREATE Statecharts.

Analyse execution traces from file

Analyse execution traces from file

Using YET

In order to use execution tracing for target debugging or unit testing some implementation and configuration steps are necessary. In general the system which executes the statechart must be prepared to produce an execution trace and the system which analyses a YET trace must be prepared properly. Depending on the system simple configurations or manual implementation tasks are required. Here the following cases are described:

Preparing an embedded system for tracing
Trace and debug statechart execution
Unit test a statechart YET trace

Preparing an embedded system for tracing

A generated state machine which should be debugged or remote controlled must be enabled for execution tracing. This consists of the following steps.

Preparing the generated state machine for execution tracing.
Set up the trace handling in the target application. This step may require application specific implementation work.

By default the tracing feature of state machines is disabled in order to save resources if it is not required. Nevertheless enabling tracing for a state machine is a simple configuration topic for code generators. The second step is more complex as it may require application specific implementation work.

Enable tracing when generating state machine
The generated state machine code must be instrumented for raising trace events. So you first have to enable the tracing feature in your sgen generator file. This can be done by adding another feature called "Tracing" to the C generator configuration. The configuration below gives an example.

GeneratorModel for create::c {

    statechart tictoc {
        feature Outlet {
            targetProject = "example"
		targetFolder = "sc"
		libraryTargetFolder = "sc/base"
        }		
        feature Tracing {
            generic = true
        }
    }
}

The feature "Tracing" has the property "generic" with the value "true" ( "false" is the default). As a result an additional C header file named "sc_tracing.h" is generated. It declares the generic trace API which will be used by all state machines with enabled tracing. These declarations include the type sc_trace_handler. A state machine uses such a trace handler instance to call trace callbacks which can be processed by a trace handler implementation. This API is independent of YET. It can be used to adapt any execution tracing or logging infrastructure.

Adding a YET tracer
While the step before enables a generic trace API for the state machine, an additional generator can be configured which generates a YET specific implementation of the sc_trace_handler. This is also straightforward. Simply add a new sgen file to the project. Corresponding to the example above it looks like:

GeneratorModel for create::c::yet {

	statechart tictoc {
		feature Outlet {
			targetProject = "example"
			targetFolder = "sc"
			libraryTargetFolder = "sc/base"
		}	
	}
}

This generator model uses create::c::yet generator instead of the create::c. It just requires an Outlet feature and the same values should be used as in the normal C code generator model. This generator adds several additional source files to the project:

sc_yet.[h|c] - implements a set of functions which are used to create and parse YET execution events. This implementation is completely independent of statechart semantics and can be used to support execution tracing for other models.
yet_sc_tracer.[h|c] - this module implements all generic parts for YET statechart tracing which can be applied to all statecharts. So it is aware of statechart semantics and provides an implementation of sc_trace_handler.
<Statechart>Tracer.[h|c] - this module implements the statechart model specific parts of a YET tracer.
<Statechart>Meta.[h|c] - this module defines data structures which provide names as strings for the different statechart features like variables, events, and states. This is separated from the tracer module as these structures are independent from YET and can be reused for other purpose (like a generic MQTT adaption).

Please keep in mind:

that the generic tracing feature currently only supports the C language
not all data types are supported – especially types which are contributed using the deep C integration like structs, unions, pointer types are not supported yet.

Setting up tracing in the application
The generated infrastructure is capable of producing and consuming trace. What is missing is connecting this functionality to the outside world. This part is not covered by a code generator and must be implemented manually based on the API which is provided by the generated code and reusable software components.

Connecting trace infrastructure to physical channels

Connecting trace infrastructure to physical channels

The generated code provides a yet_sc_tracer instance. This instance must be connected to physical channels which care about the physical handling of trace events. Three different implementations of physical channels are currently provided:

yet_logger - logs trace events by writing them to the standard output stream of the process.
yet_file_writer - writes trace events to a file using a single line for each entry. The result is a valid yet trace file.
yet_udp_stream - implements a bidirectional transport of trace events based on UDP datagrams. Each datagram contains a single trace event.

The integration of the tracer instance on the one side and the physical channels on the other side are based on observable message streams. These support an asynchronous, reactive programming model and allow a loose coupling between the different components. The message streams are based on the principles of reactive extensions (ReactiveX) without making use of any external ReactiveX library.

The yet_sc_tracer provides an observable stream of trace messages where each trace message is a simple string. This stream can be observed by any number of observers and all physical channels provide an observer which can subscribe to the observable trace messages. In addition, the tracer defines the observer message_receiver which processes incoming trace events which are stimuli for the state machine. This can, for instance be connected to the observable received_messages which is provided by the bidirectional yet_udp_stream. The figure above shows how the observable streams are connected. On the code level the setup is straight forward. First, we need a state machine and initialize it.

    SomeStateMachine machine;
    someStateMachine_init(&machine);

The code for setting up the timer service is omitted here. Next, a tracer instance is defined and initialized.

    yet_sc_tracer tracer;
    someStateMachine_init_sc_tracer(&tracer, &machine);

Without a physical channel, tracing has no effect. So we need to define and initialize an instance for each discussed physical channel.

    yet_file_writer yet_file;
    yet_udp_stream  yet_stream;
    yet_logger      yet_log;

    yet_file_writer_init(&yet_file, "machine.yet");
    yet_udp_stream_init(&yet_stream, ip, port);
    yet_logger_init(&yet_log);

Now all instances are in place but we have to connect the observable streams with the observers as discussed above. This is done by defining a list of observers for each observable which must be connected.

    sc_observer* out_trace_observers[] = {
                 &(yet_log.message_logger),
                 &(yet_file.message_writer),
                 &(yet_stream.message_sender) };

    sc_observer* in_trace_observers[] = {
                 &(yet_log.message_logger),
                 &(tracer.scope.message_receiver) };

Then the observers must subscribe to the observable. 

    SC_OBSERVABLE_SUBSCRIBE(&(yet_stream.received_messages),               
                            in_trace_observers);
    SC_OBSERVABLE_SUBSCRIBE(&(tictocTracer.scope.trace_messages), 
                            out_trace_observers);

The observer subscriptions here go beyond the scenario which is described by the previous figure as the yet_log will also care about the incoming trace events from the yet_stream instance. So it logs outgoing and incoming trace events. Some more things should be mentioned here:

The involved instances do not know anything about the other instances. So the configuration can be changed without impact on the implementation of these instances.
There can be any number of physical channel instances. E.g. multiple trace files could be defined.
It is easy to implement custom physical channels and add them to the scenario.
Observers and observables can also be used to implement other functionality than physical channels like buffers, filters, aggregators etc.. E.g. a simple observable could implement a trace event counter.

This provides a high flexibility for the application developer and the implementation of the existing physical channels is a good template for custom implementations.

Trace and debug statechart execution

Debugging a statechart YET trace is simple. Within a statechart editor or on the model file entry in the project explorer choose "Run As > Statechart Trace Debugging" from the context menu.

CStarting a trace debug session

Starting a trace debug session

This will launch the trace debugger and by default will try to read the execution trace from the file "trace.yet" from the root of the project folder. If it is not already in place then create this trace file e.g. by starting the application with enabled YET file tracing. The UI of the trace debugger is identical to the regular simulation UI.

If you want to choose a different trace file you have to reconfigure the run configuration which was created by the "Run As > Statechart Trace Debugging" action. To do this choose "Run As > Run Configurations…" from the context menu. The "Run Configurations" dialog pops up and choose the proper entry in the category "Statechart Trace Debugging". The tab "Statechart Trace" provides several configuration options.

First the instance name is used to distinguish between multiple running instances of the same state machine if multiple state machines are executed on the target and if they share a common trace channel. The default is just the name of the statechart model.

The obviously most important option is how you want to read or receive traces. It is possible to choose one of three trace provider:

Read trace from file - supports to configure what file should be used.
Read trace from UDP socket - opens a UDP socket on the local machine with a configurable port (default 444). The physical trace channel on the embedded target can connect to this port to setup a bidirectional communication channel.
Read trace from TCP socket - uses TCP instead of UDP to setup a bidirectional communication channel and can be configured in the same way.The default port is 8444.

If UDP or TCP based YET streams are used then the debugging UI supports raising events and modifying statechart variables.

Configuration of trace debug session

Configuration of trace debug session

After that click “Apply” and “Run”. The trace debugger UI will be activated. If UDP or TCP trace provider are used then no active statechart state may be highlighted in the Debugger UI. This is always the case if no remote target is connected or if the statechart is not yet activated on the remote target.

Testing statechart execution traces

Instead of the interactive debugger a trace can also be consumed by unit tests. Within a SCTUnit editor or on test file entry in the project explorer choose "Run As > Statechart SCT Unit Trace Test" from the context menu. The unit test runner will start up an execute the tests.

All points regarding setting up a run configuration for trace tests is identical to the steps required for the interactive trace debugging as the same configuration dialogs are applied. The only difference is that the category ‘SCT Unit Trace Test’ is used instead of ‘Statechart Trace Debugging’ .