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:

  1. Creating an Eclipse project. It will serve as a container for the statechart model.
  2. Modeling the light switch using the YAKINDU Statechart Tools editor. The result will be a static statechart model.
  3. Simulating the model. We can play around with the model, operate the light switch and observe its behavior.

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...:

Selecting "File → New → Project..." in the main menu

Selecting File → New → Project... in the main menu

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

The "New Project" wizard

The New Project wizard

Select General → Project and click Next >.

The wizard shows its next page:

Specifying project name and location

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:

Project "LightSwitch" created

Project LightSwitch created

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.

Selecting "New → Folder" in the context menu

Selecting New → Folder in the context menu

The New Folder wizard opens:

The "New Folder" wizard

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.

Starting with an empty statechart model

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:

Selecting "New → Other" in the context menu

Selecting New → Other in the context menu

The New wizard opens. Select YAKINDU SCT → Statechart model

Selecting "YAKINDU SCT → Statechart model"

Selecting YAKINDU SCT → Statechart model

Click Next >. The wizard shows the New YAKINDU Statechart dialog:

The "New YAKINDU Statechart" dialog

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 preset correctly 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:

Dialog "Confirm Perspective Switch"

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 them. 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.

Please note: If the Confirm Perspective Switch dialog does not appear as described above you probably have already confirmed Do not offer to switch perspective in the future once before.

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 the statechart editor to graphically develop the light switch statechart.


The statechart editor

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.

Statechart validation

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.

Please note: Since the current version of the statechart editor gives that state a proper name („StateA”), the error marker is no longer present in a new model. So the following description is somewhat out of date. This will be fixed in a future version of this documentation. Until then, please follow the subsequent text nevertheless, because you will learn something important about statechart validation.

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.

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 pop-up appears and displays the error description: "A state must have a name."

An error marker and a pop-up window explaining it

An error marker and a pop-up window explaining it

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. 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!

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.

Double-click on the string <name> in the state object. The string turns into a text input field with <name> being highlighted: Double-clicking on the state name
Type the state’s new name, i.e., Off: Typing the new state name
Hit the [Enter] key or click anywhere outside the text field. Bingo! The state now has a proper name and the error marker disappears: Completing the state name change
However, since the state box’s size is smaller than before now 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: Dragging the state
Drop the state box at this very place, and everything looks much better now: Dropping the state
Alternatively, we could have used the state box’s handles to resize it. However, we just deselect the box by clicking elsewhere: Deselecting the state

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.

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. Dragging a new state from the palette to the editing area
Release the mouse button over a gray area, a region: Dropping a new state in a region
The new state appears in the model graph: A new state
Rename the new state to On. Vertically align it to the Off state, if you like: Renaming the new state
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.e., the large rectangle with a gray background, a pop-up 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. Creating a state using the pop-up menu

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.

In the Palette, click on the Transition symbol. The symbol’s background turns blue. Clicking on the _Transition_ symbol in the palette
Click on the Off state, but don’t release the mouse button. Drag the mouse pointer towards the On state. The arrow representing the transition to be established is drawn. Drawing a new transition
Once the mouse pointer reaches the target state, it changes its shape. The mouse pointer reaching a possible target state
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. Editing a transition
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: Completing the transition editing mode

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:

Creating definitions [1]

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:

internal:
    event operate

The keyword internal makes the following definition of the operate event belong to the internal scope. The latter is explained in section "Internal scope".

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:

Creating definitions [2]

Creating definitions [2]

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

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. Inserting a control point
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.e., On. An incoming 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. Creating a transition by using the source state's outgoing arrow handle
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. Completing the transition creation