SinelaboreRT Header Logo

SinelaboreRT

It's better when it's simple!

User Tools

Site Tools


Sidebar

UML-Tool specific Intro

Language Backends

Getting started

How-To

Examples

Designers Toolbox

There are better ways to model state machines than using spread sheets!

In the past different μC manufacturers have published application notes about the benefit of using state machines for the design of embedded software. An example is the application note SLAA402 from Texas Instruments (TI). It suggests to generate source code based on a spread sheet table. Nowadays several affordable UML modeling tools are available supporting the efficient design of state machines in a graphical way. SinelaboreRT generates production quality source code from state diagrams created with many different UML tools. Give it a try!

wiki:manual:editor

State Diagram Editor Introduction

Overview

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

| The first diagram with an init state, a normal state, a final state and a choice.

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.

What is new in this version?

The latest release version is 5.0. The state machine editor was reworked from ground up and is much more user friendly than before. It allows to create state machine designs within minutes. Compared to other general purpose UML tools the number of required clicks and time is significant lower.

Installation

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
  • 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.0
...

State Machine Editor

Overview

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 from 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).

Starting the editor the very first time

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.0/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 must fit to your installation. Most probably you have not yet created a configuration file so far. Therefore the editor asks you to point to the dot.exe file. To avoid this step create a file called codegen.cfg file with the following content. The concrete path depends on your system. Adjust it accordingly.

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

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

 Visual editor after startup Figure 1: Visual editor after startup.

Creating a state diagram

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

Adding states

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 in the diagram. There was no init state yet so it was created automatically for you too.

Add state S2 as shown in figure 4.

Adding transitions

To add transitions right click on the state 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.

Adding a final state

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

Adding a choice

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 are needed. State names for choices are automatically assigned and can't be changed. 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. One guard must be 'else'. Add the action code as shown in figure 4.

First diagram done

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.

 The first diagram with an init state, a normal state, a final state and a choice. 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

Creating code from your first state diagram

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. In case you deleted a state or transitions and there are inconsistencies the built-in diagram 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. Define the signature of the event handler function. We want to have a parameter for the instance data and another one for the event. To do so add the following two lines to the config.cfg file. They let the code generator generate function parameters for the instance variable and the event variable. This is what you usually want.
    HsmFunctionWithInstanceParameters=yes
    HsmFunctionWithEventParameter=yes
  2. Define the target programming language and other user defined code. Click the 'Code' button in the menu bar. 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.

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

  • 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

Compiling the first application

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

Wrapping up

In this manual you learned how to install the SinelaboreRT tool and use it to edit state machines. We also generated code 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.

This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies

Leave your comments

Enter your comment:
 
wiki/manual/editor.txt · Last modified: 2021/02/14 17:52 by pmueller