In this guideline you learn how use the SinelaboreRT graphical editor based on the following state diagram and generate code from it.

State machines show the dynamic behaviour of an application. It is a graph of states and transitions describing the response to events depending on the current state. State machines are used for decades in hardware design. And during the last years also more and more in the area of software development. Especially in the embedded real-time domain the use of state machines is popular because the behaviour of devices in this domain can be often very well described with state machines.

An important aspect of state machines is that the design can be directly transformed into executable code. This means that there is no break between the design and the implementation.

The SinelaboreRT state machine editor is part of the code generator and not an extra package. Depending on the command line options either the editor, the simulator or the code generator is started.

Like the code generator the visual editor can be used across most platforms like Windows, Linux and Mac.

The state machine editor was designed to allow to create state machine designs within minutes. Compared to other general purpose UML tools the number of required clicks and time is significant lower.

To use the visual editor the following software is required:

• SinelaboreRT software itself: For SinelaboreRT no installation is needed. The ZIP-file contains a 'bin' folder with the packed Java program (jar file).
• Java runtime environment: The editor is entirely written in Java. It can run on different operating systems such as Windows, Linux or MacOS therefore. The required Java runtime environment is available for download here: http://jdk.java.net. LTS version 11 is recommended.
• Graphviz layout engine: The Graphviz layout engine is used internally. Install the version for your operating system from here: http://www.graphviz.org/.

We assume in this manual that you installed all tools directly under C: (for Windows). Your output should be similar to the one below (version numbers might differ). If you selected different installation paths adjust the examples in the coming sections accordingly.

C:\>dir
...
16.01.2021  16:39    <DIR>          Graphviz-2.44.1
16.01.2021  20:46    <DIR>          jdk-11
24.01.2021  17:35    <DIR>          sinelaboreRT5.2
...

The state machine editor was developed to efficiently create state charts. Therefore it uses a tree based creation approach and not a graphical based approach that is normally used by UML tools. The graphical representation of the model is generated automatically. No time needs to be wasted to move graphical elements around to create a nice looking drawings. State and transition details can be provided with view clicks. Dedicated code entry fields provide syntax highlighting and allow definition of guards, actions and entry/do/exit code.

Once the diagram is ready it is possible to directly generate code form it. Or alternatively save the model file and call the code generator on the command line to generate code separately (e.g. in your make file).

Open a Command window on Windows (or a terminal on MacOS/Linux) and start the editor as follows.

c:\jdk-11\bin\javaw.exe -cp “c:/sinelaboreRT5.2/bin/*” codegen.Main -p ssc -E

Using the command line flag -E starts the state chart editor. -p ssc defines the model file format (the native editor format which is XML based and human readable). The path to Java executable must match your installation.

Most probably you have not yet created a configuration file so far. Within the configuration file you can influence the code generation and adjust other parameters. Therefore the editor asks you to point to the dot.exe file. To avoid this step next time create a file called codegen.cfg with the following content. The concrete file path to the dot.exe depends on your system. Adjust the path accordingly.

DotPathWin="c:\\Graphviz-2.44.1\\bin\\dot.exe"
#Use this on Linux/MacOS
#DotPath="/usr/local/bin/dot"
LicensePath=...

After the dot.exe was found the editor window will appear and everything is ready for creating your first state diagram. So far there is only an empty workspace as shown in the next figure

Figure 1: Visual editor after startup.

In this section we create a diagram as shown in figure 4.

To add a new state select the root node and right click to bring up the context menu. Then select Insert state. At minimum a unique state name must be specified. Also add some entry and exit code as shown in final diagram (see figure 4). This will help you to follow the state flow in our demo application later on. Once done click OK to close the dialog.

Figure 2: Create/Edit a state. All relevant properties can be directly provided.

The new state was created and shown as graphical diagram. There was no init state yet so it was created automatically for you too.

Add state S2 as shown in figure 4.

To add transitions right click on the state in the state tree where a transition should start from (here the initial state). Select Insert transition in the context menu. A window is shown where all transition related properties can be set. Select the transition's target state. Here please select S1. Also add a triggering event, guard and action code as needed. Then click OK. Transitions are represented with an arrow in the state tree. Note: For the transition from an init state to the default state no triggering event is needed.

Figure 3: Creating a transition with triggering event, guard, action and other properties.

As a next step add a final state. This works like adding a normal state but no properties can be entered. State names for final states are automatically assigned. Right click on the topmost root state and add a final state.

Choices realise a dynamic conditional branch. They enable splitting of transitions into multiple outgoing paths such that the decision on which path to take is defined by the provided guards. A choice must have one incoming transition, and two or more outgoing transitions. Each outgoing transition must have a guard. One of the guards must be defined as 'else' (default path). This ensures that always on of the outgoing transitions can be taken. For more details see the code generator manual.

Adding a choice works like adding a normal state but no properties can be entered. State names for choices are automatically assigned. Right click on the topmost root state and add a choice.

Then add tree transitions. One entering the choice. Define the triggering event here. Next two transitions leaving the choice. Specify a guard for each transition that leaves the choice. One guard must be 'else'. Add the action code as shown in figure 4.

Congratulations! You finished your first state machine diagram now. It should now look like figure 4.

The status output window shows that there are no errors in the model. Therefore it is possible to save it now. To save the diagram use the 'Save As' button. Once saved, you can find the project name in the info bar at the bottom of the editor window. Use manual.xml as file name.

Figure 4: The first diagram with an init state, a normal state, a final state and a choice.

Exit the editor now.

To start the editor again and directly load your project, provide the project file name as last parameter on the command line. Example:

c:\jdk-11\bin\javaw.exe -cp “c:/sinelaboreRT5.0/bin/*” codegen.Main -p ssc -E manual.xml

In opposite to typical UML modelling tools the editor allows only to draw valid diagrams. E.g. it insists that a transition has always a trigger. Or a state name is always present and unique. In case you deleted a state or transitions and there are inconsistencies the built-in model checker warns you. Before not all problems are fixed it is not possible to save the diagram or generate code.

Before you actually can generate code you need to do the following steps:

1. Click the 'Code' button in the menu bar. First define the target programming language and other user defined code. This brings up the following window which allows you to make all relevant adjustments. Insert the required include files and an external variable which we will define in main.c later on.

1. Define the signature of the event handler function. We want to have a parameter for the instance data and another one for the event. Click on the “Handler Signature” button to open a dialog that allows you to select what you want. And as a result you get a list of configuration parameter that you can copy to your configuration file.

   HsmFunctionWithInstanceParameters=yes
   HsmFunctionWithEventParameter=yes

1. Add additional variables to the instance data if needed. To do so click on the button “Attributes” and add the required fields.

Figure 5: The code window allows to select the programming language and the various code sections inserted into the generated code. g

• Header Code: For example include files or other code like function definitions and variables copied at the very beginning of the generated state machine code implementation file.
• Action code: Code executed at the begin of the state machine function.
• Post action code: Code executed at the very end of the state machine just before it returns.

In case the state diagram has no errors (check performed without any faults) you can press the generate button. Otherwise look in the status output window what the problem is and fix it. The code is generated to the same folder where the project file is located.

The following files were generated:

D:\>dir
 Verzeichnis von D:\

30.01.2021  17:37               137 codegen.cfg
30.01.2021  17:51             2.209 manual.c
30.01.2021  17:51               650 manual_ext.h
30.01.2021  17:51             2.232 manual.h
30.01.2021  17:51             1.990 manual_dbg.h

Content of the files:

• manual.c file containing the state machine implementation
• manual_ext.h file containing the events that can be processed from the machine
• manual.h header file of the state machine
• manual_dbg.h Support code for debugging the machine if needed

To built the first application we need a small main program to call and stimulate the generated state code.

Here is a simple main.c that you can use.

#include <stdio.h>
#include <stdint.h>
#include "manual_ext.h"
#include "manual.h"
 
MANUAL_INSTANCEDATA_T instData = MANUAL_INSTANCEDATA_INIT;
 
uint8_t i=0;
 
int main(void){
	manual(&instData, MANUAL_NO_MSG);
	printf("--\n");
	manual(&instData, ev1);
	printf("--\n");
	manual(&instData, ev2);
 
	printf("Now we set i>0\n");
	i=1;
	manual(&instData, ev2);
 
	// From now on no reaction is possible anymore because
	// the machine is in a final state
	manual(&instData, ev2);
	manual(&instData, ev1);
 
	return 0;
}

This simple code can be compiled with basically any compiler. I installed gcc for windows on my PC. To compile the code use the following command. If you had no typos you should see no compiler errors.

D:\>g++ -Wall -pedantic main.c manual.c -o manual.exe

Now call the manual.exe. The output is like follows:

D:\>manual.exe
Entry S1
--
Exit S1
ev1
Entry S2
--
Exit S2
ev2
Entry S2
Now we set i>0
Exit S2
ev2
i>0

D:\>

In this manual you learned how to install the SinelaboreRT tool and how to use it to model a state machine. We also generated fully automatically the state machine code from your model and executed it. Hope you are convinced how easy it is to create state diagrams and generate code from it once you set-up the required tools.

As next step I recommend you to modify the state diagram, recreate the code and understand more and more the possibility you have. Have a look into the code generator manual about supported configuration options and further command line parameters.

Have fun!!!

*) All the details are described in the code generator Manual.