Getting started on Windows with Cadifra and MinGW

This section guides you through the whole development process from designing a state machine to integrating it into an application. This will help you to get familiar with the code generator and its features.

All files for this tutorial are available in this folder: examples/microwave_handbook_cadifra

A Microwave Oven

In this section we create the model of a simple microwave oven using a state machine diagram. A microwave oven was chosen because it is self-explanatory and not too complex to model. To keep this example as simple and clear as possible the hardware interaction routines are excluded. The following figure 1 shows the hardware of our fictitious microwave oven. For this example we are using the Cadifra UML editor. If you use another supported UML tool the required steps are slightly different. But if you are familiar with your UML tool it should be no problem to follow the tutorial and create the model on your own. In the appendix you will find hints on how to draw state diagrams for all the supported tools. It is recommended to have a quick look over the section that covers your tool. In addition the examples folder of your installation contains models for all supported tools (e.g. Enterprise Architect, UModel . . . ).

Microwave Oven Image Figure 1: Fictitious microwave oven. With a wheel the cooking time can be adjusted between 0 – 60 seconds. The power can be set to high (II) or low (I).

The oven controller should be able do the following things:

Cooking time can be adjusted using a wheel between 0s and 60s.

Cooking starts if the cooking time is larger than zero. And the door is closed.

If the door is opened during cooking the microwave generator is switched off. Cooking time stops.

Cooking continuous if the cooking time is not over and the door is closed again

Cooking stops if the cooking time is over or the time is adjusted to zero.

Cooking time and power can be changed at any time.

Drawing the Initial Diagram

To start designing a state machine diagram, you first have to start the Cadifra UML editor and select the state machine mode either from the tool bar or from the menu entry Diagram→State. Now you can draw states and transitions. Right click to the drawing area to select the state chart element you want to use. Create step by step the complete start chart. The next figure shows an initial diagram fulfilling the above requirements. You can either draw it yourself or load it from the folder example1 located in the installation directory.

Microwave Oven State Machine initial design Figure 2: First state machine design of the microwave oven. Only states and events are modelled yet.

Such an initial design is already useful. It can be used to discuss (e.g. with customers) if the requirements are fulfilled and it reacts to all events as expected. At this stage often unclear points in the the specification can be identified. E.g. in our design a user has to open the door once after the cooking time is over before cooking can be started again. This behavior is not explicitly specified in the requirements. It might be acceptable but it is also possible to go directly to state idle instead. Our initial design is not optimal as you can easily see. Requirement six (power and cooking time can be adjusted at any time) leads to a lot of similar state transitions. To avoid this the design can be changed into a hierarchical one.

The hierarchical version

To convert the existing design into a hierarchical one move the existing states into a new parent state. The previous states are now children of the new state called Super. The power and time related events are now handled by the outer state. Please note that the outer state is a history state. This is necessary because we want to go back to the last inner state after event processing of events handled by the outer state. So far the machine can receive events and change state as reaction. But some important details are still missing. For example a close door event in state idle causes a state change to cooking even if the cooking time was not set to a value ≠ zero. This is in opposite to requirement two. To avoid a state change a guard must be added or alternatively a choice as done here. Furthermore action and entry/exit code is still missing all over the diagram. An additional Error state was added too. It is entered if the hardware self test failed after power on. The next figure 3 shows the final state machine design. Functions with prefix timer are helper functions providing timer functionality. Functions with prefix oven are functions related to power control. See next section for further details. In this example we touched the most basic design elements of a state charts. In the next section we focus on code generation and execution of our design on a PC. Please note that the design presented here is not the only possible solution for the given requirements. Also some functions of a real microwave oven – e.g. control of a lamp in the oven – are still missing.

Microwave Oven State Machine hierarchical design

Figure 3: Complete state machine design of the microwave oven. All necessary actions, guards, entry and exit code was added.

Creating Code

It is assumed you have Java and MinGW (a gcc compiler for Windows) installed. For a check if everything is installed correctly open a command window and change the working directory to this folder. Then type in the following commands.

C:\>java −version
java version "1.8.0_231"
Java(TM) SE Runtime Environment ( build 1.8.0_231−b11)
Java HotSpot(TM) 64−Bit Server VM ( build 25.231−b11 , mixed mode)

Add the bin folder of MinGW to your path and check if the compiler can be called now.

C:\>path %path%;C:\MinGW\bin C:\>mingw32−gcc
mingw32−gcc: fatal error: no input files
compilation terminated .

Your output should look similar. Details might differ depending on your installed program versions. Now change to the ready made example in the examples folder. I assume that the code generator is directly installed on c:\.

C:\>cd c:\sinelaboreRT4.1\examples\microwave_handbook_cadifra_win32

Type in mingw32-make clean to first remove existing built results. Then type in mingw32-make to build everything.

mingw32-make
java -cp "../../bin/*" codegen.Main -p CADIFRA -p Cadifra -l cx -doxygen -o oven first_example_step3.cdd
Create inline doxygen of state machine function
A linked note starts not with 'Compartment' and is therefore ignored
Starting robustness tests of state machine ...
State names: ..............
Machine hierarchy: ........
Machine height = 2
Transitions: ..............
Default states: ...........
Final states: .............
Choices: ..................
No. of children in composites: ...
Connectivity of states: ...
M1054: State Error has no outgoing transitions which indicates a dead end -> check your design.
Can't find the License.txt file or invalid file. Codegen is running in demo mode
Expected license file location: ../../bin/License.txt
Running in demo mode!
gcc -Wall -g main.c -c -o main.o
gcc -Wall -g oven_hlp.c -c -o oven_hlp.o
gcc -Wall -g oven.c -c -o oven.o
gcc -o oven main.o oven_hlp.o oven.o
C:\sinelaboreRT4.1\examples\microwave_handbook_cadifra_win32>

The oven.exe file should be built successfully now. Start the program and type several times + ti increment the cooking timer. Then press c to close the door. Watch what happens. Test the other events you can fire.

It is now recommended to start the Cadifra UML editor again. And play with the state diagram. Look into the generated code to get familiar with the many possibilities the code generator offers.

~~DISCUSSION|Leave your comments~~