h1(#Gettingstartedtutorial). Getting started

h2(#Introduction). Introducing YAKINDU Statechart Tools

This tutorial introduces YAKINDU Statechart Tools (SCT). It provides an integrated modeling environment for the specification and development of reactive, event-driven systems based on the concept of state machines or statecharts. It is an easy-to-use tool featuring sophisticated graphical statechart editing, validation and simulation of statecharts as well as code generation for C, C++, and Java.

This tutorial you will teach how to
* create a new statechart model, and
* execute it using the simulation engine.

Please note that this tutorial will not explain statecharts in general, so you should familiarize yourself with the basic concepts of state machines first.[1]

In order to get a fully-working statechart implementation that you can integrate with your project, you will have to familiarize yourself with _code generation_, which is covered by the chapter "Code generation":../../04_code_generation/code_generation.html in this documentation. You can generate your state machine implementation as source code in C, C++, and Java out of the box. Alternatively, you can write your own code generator for other programming languages or for other purposes.

Before we get started, make sure you have YAKINDU Statechart Tools installed. For installation instructions, see the "Installation documentation":../02_installation/installation.html.


h2. The light switch example

The most simple example of a state machine that actually does something is a light switch. In this scenario there is a light bulb and a switch to turn the bulb on and off. Of course there's also a power source and some electrical cabling to put it all together.

h3. The behaviour of a light switch

When modeling the light switch example as a statechart, we can disregard everything (even the bulb) except for the switch. The behaviour of the switch is very simple:
* Initially the light switch is off, i. e. it is in its *Off* state.
* If the light switch is operated while being in its *Off* state, it changes to its *On* state.
* If the light switch is operated while being in its *On* state, it changes to its *Off* state.


h2. Modeling the light switch as a statechart

Now let's model the light switch as a statechart using YAKINDU Statechart Tools. This involves the following steps:
# Creating an Eclipse project. It will serve as a container for the statechart model.
# Modeling the light switch using the YAKINDU Statechart Tools editor. The result will be a static statechart model.
# Simulating the model. We can play around with the model, operate the light switch and observe its behaviour.

h3. Creating an Eclipse project

The first step is to create a new Eclipse project that can serve as a container for our model. From the main menu, select _File → New → Project…_:

!images/light_switch_010_menu_file_new_project.png(Selecting "File → New → Project…" in the main menu)!

The _New Project_ wizard opens, showing a couple of different project types structured in various folders.

!images/light_switch_020_wizard_new_project_general_project.png(The "New Project" wizard)!

Select _General → Project_ and click _Next >_.

The wizard shows its next page:

!images/light_switch_040_wizard_new_project.png("Specifying project name and location")!

Specify a meaningful _Project name_, e. g. *LightSwitch*, and optionally select a _Location_ to create the project in.

Click _Finish_.

Eclipse creates the new project: 

!images/light_switch_060_project_created.png(Project "LightSwitch" created)!


h3. Creating a folder for the model

Now that we have created the Eclipse project, we can establish the statechart model of the light switch. It is good practice to use a separate directory for models, so let's create a new folder called _model_.

Right-click on the project's root, i. e. on *LightSwitch*, then select _New → Folder_ from the context menu.

!images/light_switch_100_menu_new_folder.png(Selecting "New → Folder" in the context menu)!

The _New Folder_ wizard opens:

!images/light_switch_110_wizard_new_folder.png(The "New Folder" wizard)!

Give the model folder a reasonable name, e. g. *model*, and type it into the _Folder Name_ text field. Then click _Finish_.

The new _model_ folder is created and appears in the _Project Explorer_ view at the left.


h3. Starting with an empty statechart model

h4. Using the YAKINDU Statechart wizard

Now we are going to create an empty statechart model in the _model_ folder. Right-click on the _model_ folder and select _New → Other_ in the context menu:

!images/light_switch_120_menu_new_other.png(Selecting "New → Other" in the context menu)!

The _New_ wizard opens. Select _YAKINDU SCT → Statechart model_

!images/light_switch_130_wizard_new.png(Selecting "YAKINDU SCT → Statechart model")!

Click _Next >_. The wizard shows the _New YAKINDU Statechart_ dialog:

!images/light_switch_140_wizard_new_yakindu_statechart.png(The "New YAKINDU Statechart" dialog)!

The dialog asks you for the project, the directory, and the name of the model file to be created. Eclipse project and directory should be correctly preset already. In our case the corresponding text field contains *LightSwitch/model* which means the directory named *model* in the *LightSwitch* project. You can change that if you wish, but most likely you won't.

The default file name in the _File Name_ field is *default.sct*, however. You should change that to something more meaningful. In our case we type *LightSwitch.sct* into the _File name_ field, see the screenshot above.

Click _Finish_.

Since there's a dedicated perspective for statechart models, Eclipse asks you whether you want to change to it now or not:

!images/light_switch_150_dialog_confirm_perspective_switch.png(Dialog "Confirm Perspective Switch")!

Please answer the question regarding switching to the _YAKINDU Modeling_ perspective by clicking on the _Yes_ button. The _YAKINDU Modeling_ perspective has a graphical editor for statechart models, and you will need it to create and modify statecharts. On the other hand your answer really doesn't matter that much, because you can switch perspectives at any time. If you check _Do not offer to switch perspective in the future_ before clicking _Yes_, Eclipse will never ask this question again, at least regarding the _YAKINDU Modeling_ perspective.


h4. The initial model

An empty statechart is created and displayed in the *statechart editor* in the middle of the Eclipse workbench. In the screenshot below the statechart editor is marked by a red rectangle. Subsequently, we will use statechart editor to graphically develop the light switch statechart.

p(#light_switch_220_statechart_editor). 

!{width:60%}images/light_switch_220_statechart_editor.png(The statechart editor)!

Actually the new statechart isn't really empty. It already contains the initial state (a small filled black circle), a "normal" state, and a transition leading from the former to the latter.

h3. Statechart validation

h4. Error markers in the model graph

The "normal" state, however, has a small filled red circle containing a white 'X' attached. This is an error marker and tells you that something is wrong with your model, particularly with the object it is attached to.

h4. Error markers in the project explorer

The error marker is also shown in the _Project Explorer_ view at the left-hand side of the main window. In this way you can see immediately which of your projects contain errors. Click on the small show/hide symbol (triangle) left of a project's or any other resource's name to show or hide its respective contents. By doing so, you can quickly encircle the directories and files that are affected by errors. In the screenshot above we have clicked open the _LightSwitch_ project and the _model_ directory, showing the error is in the _LightSwitch.sct_ file.

h4. Validation principles

This error marker exemplifies YAKINDU Statechart Tools' model validation capabilities. Statechart validation includes syntactical and semantical checks of the whole statechart. For example, a statechart is checked for unreachable states, dead ends, or references to unknown events. These validation constraints are checked during editing. In case any constraints are violated, error or warning markers are attached to the faulty model elements. Thus the user receives direct and immediate feedback on the validation state of his statechart.

Hovering with the mouse over the error marker in the statechart editor reveals what the problem is. A small popup appears and displays the error description: "A state must have a name."

!images/light_switch_210_error_marker_and_popup.png(An error marker and a popup window explaining it)!

h4. Error markers in the "problems" view

An alternative place to see error messages is the _Problems_ view. This view has the particular advantage to comprise all notifications in a clearly arranged list form, see the "screenshot above":#light_switch_220_statechart_editor. It displays:
* A summary comprising the total number of errors, warnings, and others. In our case we have one error and nothing else.
* Zero or more lists containing errors, warnings, and other types of messages, if available. In our example there is a just a single list containing error messages. Click on the show/hide symbol to show the message list's contents or the list's header only. 

Double-clicking on an error message in the _Problems_ view brings you directly to the erroneous object.

Hang on, we will correct the error in a second!


h3. Giving a state a name

As we have seen, the initial statechart is erroneous insofar as the state does not have a name. So let's fix that.

Remember the requirements of our light switch example? The first requirement demands the switch to be off initially. The erroneous state is reached from the initial state immediately, so it is appropriate to name it *Off*.

table(scedit).
| Double-click on the string @<name>@ in the state object. The string turns into a text input field with @<name>@ being highlighted: | !images/light_switch_230_statechart_editor_change_state_name_01.png(Changing a state's name [1])! |
| Type the state's new name, i.&nbsp;e. @Off@: | !images/light_switch_230_statechart_editor_change_state_name_02.png(Changing a state's name [2])! |
| Hit the @[Enter]@ key or click anywhere outside the text field. Bingo! The state now has a proper name and the error marker disappears: | !images/light_switch_230_statechart_editor_change_state_name_03.png(Changing a state's name [3])! |
| However, since the state box's size is smaller now than before while the box's left position remains unchanged, the graph looks crooked. |
| We can improve it by dragging the state box a little bit to the right. When it is centered below the initial state symbol, a vertical blue line appears giving the user a visual hint: | !images/light_switch_230_statechart_editor_change_state_name_04.png(Changing a state's name [4])! |
| Drop the state box at this very place, and everything looks much better now: | !images/light_switch_230_statechart_editor_change_state_name_05.png(Changing a state's name [5])! |
| Alternatively, we could have used the state box's handles to resize it. However, we just deselect the box by clicking elsewhere: | !images/light_switch_230_statechart_editor_change_state_name_06.png(Changing a state's name [6])! |



h3. Creating a state

With the *Off* state only the light switch statechart isn't complete yet. We also need an *On* state, and we going to create it now.

table(scedit).
| In order to add another state, move the mouse pointer to the _Palette_ compartment at the right-hand side of the statechart editor. Click on the _State_ symbol in the palette without releasing the mouse button, and drag the symbol over to the editing area. | !images/light_switch_240_statechart_editor_create_state_01.png(Creating a state [1])! |
| Release the mouse button over a gray area, a region: | !images/light_switch_240_statechart_editor_create_state_02.png(Creating a state [2])! |
| The new state appears in the model graph: | !images/light_switch_240_statechart_editor_create_state_03.png(Creating a state [3])! |
| Rename the new state to *On*. Vertically align it to the *Off* state, if you like: | !images/light_switch_240_statechart_editor_create_state_04.png(Creating a state [4])! |
| You'll notice that the new state is showing an error marker. The reason is that it is not yet possible to reach the *On* state. |
| Before we'll go on and fix that problem, here's another way to create a new state. When you are hovering with the mouse pointer over the main region, i.&nbsp;e. the rectangle with a gray background, a popup menu shows up. If you click on the 'S' symbol in that menu, a new state will be created. Other options in this menu are to create an initial state, a final state, or a choice. | !images/light_switch_240_statechart_editor_create_state_05.png(Creating a state [5])! |

h3. Creating a transition

As we have seen above, the *On* state is not reachable as of yet. So let's model switching the light switch from "off" to "on" as a transition leading from the *Off* state to the *On* state.

table(scedit).
|In the _Palette_, click on the _Transition_ symbol. The symbol's background turn blue. | !images/light_switch_250_statechart_editor_create_transition_01.png(Creating a transition [1])! |
| Click on the *On* state, but don't release the mouse button. Drag the mouse pointer towards the *Off* state. A light gray line is shown as a preview of the transition to be established: | !images/light_switch_250_statechart_editor_create_transition_02.png(Creating a transition [2])! |
| Once the mouse pointer reaches the target state, it changes its shape: | !images/light_switch_250_statechart_editor_create_transition_03.png(Creating a transition [3])! |
| Releasing the mouse button establishes the transition. A text input field to specify event trigger, guard condition and effect appears. We want the transition to be triggered when the light switch is operated, so let's type @operate@ into the text field. | !images/light_switch_250_statechart_editor_create_transition_04.png(Creating a transition [4])! |
| If you suspect that something is not in order, because the input text is underlined in red, you are right. We will explain and deal with that in a minute. |
| Clicking anywhere outside the text field terminates the editing mode: | !images/light_switch_250_statechart_editor_create_transition_05.png(Creating a transition [5])! |

The event trigger _operate_ is flagged as an error. The reason is that an event with that name is not known yet. The screenshot below shows how to change that:

!images/light_switch_260_statechart_editor_create_definitions_01.png(Creating definitions [1])!

Double-click into the *definition section* on the left-hand side of the statechart editor. The section becomes an editable text field.

Enter the following text:

bc(prettyprint). 
internal:
	event operate

Click anywhere outside of the text field, which terminates editing the definition section. The statechart editor digests the definition, recognizes the definition of the _operate_ event, and validates the model as being okay:

!images/light_switch_260_statechart_editor_create_definitions_02.png(Creating definitions [2])!

In its current state the model would not allow to turn the light switch off again, which is somewhat unsatisfactory. However, operating the light switch while it is on should turn it off. Let's model this by adding another transition. It should lead from the source state *On* to the target state *Off*.

table(scedit).
| However, in order to not get two straight lines being close together in the graph, let's first make some room and turn the present line into an arc. Move the mouse pointer over the transition line, but not over the text. The mouse pointer changes its shape to indicate that you can insert a control point. Click and hold to add the control point, then drag it to an appropriate position. | !images/light_switch_270_statechart_editor_create_transition_01.png(Creating another transition [1])! |
| Now let's insert the second transition. This time we won't use the palette, but instead use another method. Hover the mouse pointer over the source state, i.&nbsp;e. *On*. An ingoing and an outgoing arrow appear, both with a handle.  Click and hold the handle of the outgoing arrow and drag it to the *Off* target state. | !images/light_switch_270_statechart_editor_create_transition_02.png(Creating another transition [2])! |
| Upon releasing the mouse button the transition is established. Type @operate@ as the transition's event trigger into the text field. Reshape the transition arrow to make the graph look nice. | !images/light_switch_270_statechart_editor_create_transition_03.png(Creating another transition [3])! |



h2. Simulating the light switch model

Simulating a model means to execute it, raise events manually, have time events and run cycle-based events being triggered automatically, and observe its behaviour.

Start the simulation by right-clicking on the _LightSwitch.sct_ file in the project explorer and selecting _Run As → Statechart Simulation_:

!images/light_switch_300_statechart_simulator_run_as_statechart_simulation.png(Selecting "Run As → Statechart Simulation" in the context menu)!

The perspective changes from _SC Modeling_ to _SC Simulation_. This perspective defines two additional views:
* The _Debug_ view at the top shows all running statechart instances and allows to select one of them. YAKINDU Statechart Tools allow multiple executions of the same statechart as well as parallel executions of different statecharts at the same time.
* The _Simulation_ view on the right-hand side is used to raise events and to inspect and modify variables.

Not surprisingly, the simulation starts at the initial state and then transitions to the *Off* state immediately. The latter becomes the active state now. It is highlighted by a red background:

!images/light_switch_310_statechart_simulator_state_off.png(Light switch simulation in "off" state)!

Now that the light switch is off, let's turn the lights on by operating the switch. In the simulation, we will have to raise the _operate_ event. How can we do this?

In the _Simulation_ view at the right-hand side of the Eclipse workbench, click on the _internal_ entry's show/hide symbol to display its contents.

!images/light_switch_320_statechart_simulator_state_events.png(Displaying event names in the statechart simulator)!

The _operate_ event is shown. Click on it to raise the event, i.&nbsp;e. to operate the light switch. 

The transition arc leading from the *Off* state to the *On* state flashes briefly in red, and the *On* state becomes active. Its background color changes to red while the *On* state's background color becomes normal again. 

!images/light_switch_330_statechart_simulator_state_on.png(Light switch simulation in "on" state)!

Click on _operate_ again, and the active state changes back to *Off*. Click on _operate_ several times and enjoy watching the state machine's behaviour.

Stop the simulator by clicking at the little red termination button in the toolbar at the top.



</p><hr/><p>

fn1. "UML state machine":http://en.wikipedia.org/wiki/UML_state_machine