2.3 HelloWorld Example

The design and simulation of a HelloWorld example is discussed in this section. This model has two states A (default state) and B (final state). When simulation is started, only event e is accepted, which changes the model from state A to state B, and prints a ``Hello World!'' message.

To design a textual model manually, the designer writes the description according to the DCharts textual syntax (see my master's thesis) and saves it in a .des file. For this example, the textual description is listed below:

DESCRIPTION: # description of the model
    Hello World Example

STATECHART:  # definition of the state hierarchy
    A [DS]
    B [FS]

TRANSITION:  # one single transition
    S: A
    N: B
    E: e
    O: [DUMP("Hello World!")]

This description is saved as HelloWorld.des. Several important points about this description are explained below:

• Three descriptors are used in this example. Descriptor DESCRIPTION starts a segment of description of the model (usually in natural language). Empty lines or lines with only spaces or tabs are removed automatically. If a model has multiple description segments, they are literally combined to become one single description. The default SVM interface prints this description on the screen when the simulation is started.

• Descriptor STATECHART starts the definition of the state hierarchy. If a model has several such segments, they are literally combined before the simulator understands the state hierarchy of the model. In this example, A and B are the two top-level states. They are defined in separate lines and aligned left. Substates of a state (if any) should appear in lines immediately under its definition, with more leading spaces. Sibling states are always aligned left. (Examples of more complex state hierarchies are discussed later.)

  Property [DS] is assigned to state A, which means it is a default state. Similarly, property [FS] of state B means it is a final state.

• Descriptor TRANSITION starts the definition of one single transition. In this example, the transition has the following properties:
  1. S property specifies the source state of the transition.

  2. N property specifies the destination state of the transition.

  3. E property specifies the event that triggers the transition.

  4. O property specifies a list of commands to be executed as the output of the transition. [DUMP(...)] is a predefined macro that prints a message.

• Comments are placed to the right of a ``#'' mark until the end of the line. They are similar to the C-style comments behind ``//''.

To run the model, first make sure that HelloWorld.des is in the current directory and the SVM directory is added to the PATH environment variable. Execute the following command:

svm HelloWorld.des

The default graphical interface (Figure 2.1) will be shown, and the simulation is started.

Figure 2.1: Screenshot 1 of the HelloWorld example

First-time users may not be familiar with this default graphical interface, and brief explanation may be required. There are two separate windows: the right one is the main window, and the left one is the state hierarchy window.

• Main window:
  1. The left panel of the main window lists all the currently enabled events. When simulation of the above example is started, event e is enabled because, if it is received, it triggers the only transition in the model. There are no other enabled events.

  2. The output box is the area where messages from the model is printed. In this case, when the simulation is started, the description is printed automatically to this area.

  3. The command box receive interactive commands from the user. During a simulation, three types of commands are acceptable:
     1. Enabled events (as are listed in the left panel);

     2. debug command, which switches the simulator to the debug mode (discussed later);

     3. exit command, which forces the simulation to stop immediately and closes the SVM windows.

     An unaccepted command entered by the user is simply ignored.

  4. The ``Show State Hierarchy'' button is initially disabled. If the user closes the state hierarchy window, it becomes enabled and clicking on it brings up the state hierarchy window again. (Closing the main window itself has the same effect as typing the exit command in the command box.)

  5. The ``Snapshot'' button takes a snapshot of the current state of the simulation. The snapshot is saved in a text file, which can be used to resume the simulation at the current state. Snapshotting is discussed later.

  6. The ``About SVM'' button brings up the about dialog.

  7. The ``Exit'' button provides the same functionality as the exit command.

  8. The status bar at the bottom always shows the current state of the model (in the format of Python list).

• State hierarchy window:
  1. The top bar shows the file name of the current model.

  2. The state list shows the state hierarchy in a tree style. Leaf states which the model is current in are highlighted with yellow background.

  3. The bottom box shows the full path of the currently selected state in the state list. The full path of a state consists of the names of all its superstates and its own name in the order of their levels. Those names are separated by a dot. For example, the full path of state A in this example is A. If A1 is a child of A, the full path of A1 is A.A1.

     If no state is selected in the state list (as in Figure 2.1), this box is empty.

To send event e to the HelloWorld model, the user should either use the left mouse button to double click the event name in the enabled event list, or type in e in the command box and then enter. This event triggers the only transition defined in the model, and message ``Hello World!'' is printed in the output box (Figure 2.2).

Figure 2.2: Screenshot 2 of the HelloWorld example

Now, because state B (the current state) is a final state, there is no enabled event any more, and the enabled event list becomes empty. To close SVM, the user should either enter command exit in the command box, or click the ``exit'' button with the left mouse button, or close the main window.