SinelaboreRT - wiki:news

Leader State Machine - Follower State Machines

anonymous@undisclosed.example.com (Anonymous) — Wed, 06 Apr 2022 10:01:43 +0000

Leader State Machine - Follower State Machines

Background

The Unified Modeling Language (UML) allows to model quite elaborate state machines especially when using concurrent regions (aka AND states or parallel states). Concurrent regions are a powerful design measure but also have its price.

Unexperienced users tend to create one big state diagram containing all parts (subsystems) of the system. Due to their own behavior and parallel execution subsystems must then be modeled as concurrent regions.

Read on to learn about an alternative solution.

Take a microwave oven as example. There is a lamp, motor and the microwave radiator itself all reacting on events. One approach is to create one big parent state and put the different parts of the oven in parallel regions.

Figure 1: Simplified oven model, designed with regions.

The key benefits of UML regions are:

Unordered List Itemconcurrent regions allow to model parallelism.
everything is shown on one page

The drawbacks are:

The diagrams can become quite large. Our diagram just shows some states. Reality might be much more complex.
As a direct consequence one has to scroll back and forth all the time when working on different parts of the model
Refining behavior in concurrent regions makes the parent state containing the regions bigger and bigger. Depending on the modeling tool features’ this often has the consequence that a lot of work is going into moving states around to make space for new ones instead on focussing on the design work itself.

Alternative solution

To reduce the complexity good practice in engineering is to break down the problem into smaller pieces. In software this good approach means to put the subsystem state machines into their own state diagrams.

This has the benefit to create smaller diagrams dedicated to a specific subsystem e.g. the radiator. These diagrams can be developed, verified and validated separately without considering the whole system. Eventually from a different developer (deepening on project size).

As a consequence the state machines must be able to exchange events. Or at least one state machine (the leader) must be able to send events to the other state machines (the followers).

Lets take the microwave example again. Now the leader machine contains only the overall behavior. The radiator, lamp and other subsystems were modeled as follower state machines. They are controlled from the leader machine. E.g. if the main machine reaches cooking it sends the radiator an event to switch on radiation. On this top level we are not interested how the radiator subsystem works in detail. In reality it might be a complex state machine with many states dealing with the radiator electronics in the oven. But this is not relevant on the top level diagram.

The following figures show the leader machine and then two simplified examples of follower state machines.

Figure 2a: Leader machine. It just sends events to the followers to trigger actions. Note that also the leader might receive events from other state machines (e.g. the button subsystem). In one extreme shape there is not even a leader but only cooperating subsystems.

Figure 2b: Simplified lamp subsystem reacting on events from the leader (or from additional sources e.g. hardware triggered events or timer events).

Figure 2c: Simplified radiator subsystem reacting on events from the leader (or from additional sources e.g. hardware triggered events or timer events).

Connecting state machines

For communication between state machines different solutions are available. What is actually used depends a lot on the overall system needs and system features e.g. with/without RTOS etc. On smaller systems binary flags might be sufficient. But usually a good solution is to use queues. Queues decouple the state machines and offer a clear interface to send and receive events. Event queues often have the feature to push events in front so high importance events can be processed first. A subsystem also might defer an event and put it into the queue again if it should be processed later. The subsystems might run in a separate thread (if an OS is present) or can be called from a main loop.

Conclusion

Separating a system into different subsystems running their own state machines is a well know design practice and helps to better keep complex developments under control.

Hope you enjoyed this article. Let me know your feedback!

Peter

~~DISCUSSION|Leave your comments~~

New version 3.6.6

anonymous@undisclosed.example.com (Anonymous) — Mon, 01 Sep 2014 19:03:18 +0000

New version 3.6.6

This new version supports code generation from Astah* models with regions. A region is an orthogonal part of a state. Regions allow to express parallelism within a state. A state can have two or more regions. Region contains states and transitions. To add a region in astah* right click to a state and select Add region from the context menu.

An example state diagram with regions is shown below:

For more information how the code generator generates code from regions download the latest version and check-out the manual esp. sections 2.2 and A.5.

{(rater>id=01092014|name=How do you like this article?|type=rate)} ~~DISCUSSION|Leave your comments~~

Using State-Machines in Low-Power Embedded Systems

anonymous@undisclosed.example.com (Anonymous) — Sun, 12 Mar 2023 16:50:16 +0000

Using State-Machines in Low-Power Embedded Systems

Introduction

I got requests from time to time asking how to integrate state-machines in a specific system design. Usually I can only give some general advice. But I like to present some design principles here which are hopefully useful for developers of deeply embedded systems in general and those of low power systems in particular.

The CPU in a low power system is usually only active from time to time to react on events triggered from outside (e.g. a pressed key) or triggered from inside the system (e.g. ADC ready, timer expired). After processing the event the CPU goes into low power mode again.

All this is done to keep the batteries running as long as possible. A good example for such a system is a wireless temperature sensor mounted outside the window sending temperature data from time to time to a central display, or a monitor attached to a bird to track the flight route or a bike computer etc. The longer the batteries last, the better.

But also systems connected to power all the time might benefit from a low-power design. Power consumption of a device is a real buying criteria nowadays.

System Design

The following example is based on a small MSP430F1232 header board with just 256 bytes of RAM and 8K of program memory. For the development the Code Composer Studio from TI was used. At the end the program needs <2k Flash and 182 bytes RAM incl. stack. The following block diagram shows the controller with its I/O connections.

Figure 1: MSP430F1232 block diagram

To not hide the design principles behind too much details the uC runs just two state machines fully generated from UML state diagrams. One machine is measuring the battery voltage every 2 seconds. The other one measures the temperature also on a cyclic basis using a TMP100 from TI connected via I2C to the uC. Temperature measurement happens only if battery voltage is high enough. Otherwise a LED is pulsed to indicate low voltage state (P1.3). The radio part which sends the temperature to a central server was omitted here.

The two state machines realizing the user application are shown in figure 2 below. The state machines were designed with the built-in Java UML editor. To change or extend the functionality just modify the state machines, regenerate the state-machine code and then compile and link as usual. Changes on I/O port 1 were added to verify the timing via oscilloscope (see below).

Figure 2: Application logic implemented as state machines. Top: Triggering the voltage measurement with a cyclic timeout. Bottom: Switching between two operation modes depending on supply voltage level. Single-shot timers are used for timing.

Reusable Library Layer

The design is based on the following library elements which can be reused from project to project:

A timer abstraction layer provides timers for the user application. The timer abstraction is based on a system tick realized with hardware timer A here. If a timer has expired the tick() routine returns true and the CPU is woken-up. Otherwise the low power mode is entered again.

__interrupt void Timer_A0(void)
{
  bool retVal;
  P1OUT ^= BIT0;        // toggling bit for debugging
  retVal = tick();    // timer service. Check if any timer has expired
 
  if(retVal){
    // at least one timeout timer fired.
    // wake up main loop
    __bic_SR_register_on_exit(LPM0_bits); 
  }
}

Listing 1: Timer interrupt service routine calling the timer handler tick().

The user code can create multiple timers and receive time-out events in case they expire. During timer creation the event queue and the timer event has to be provided. If a timer expires this event will be stored in the given event queue. The timer implementation can be found in the library folder in files timer.c and timer.h. The tick() function is the core of the timer library and shown below:

bool tick(void){
  bool timeoutAvailable=false;
 
  // Iterate over the timers and enque
  // timer events once a timeout has happend.
  for(uint8_t i=0; i<MAX_TIMERS; i++){
 
    if(timers[i].timerStatus==ON){
 
      timers[i].elapsedTicksSinceStart++;
 
      if(timers[i].elapsedTicksSinceStart==timers[i].preset){
        // timeout time elapsed.
        timers[i].timerStatus=OFF; // stop timer
        fifoPut(timers[i].rbuf, timers[i].evTimeout); // enqueue timeout event
        timeoutAvailable=true;
      }
    }
  }
 
  return timeoutAvailable;
}
 
 
// starts timer
// Returns either ON if started or OFF if not started (e.g. preset=0)
TIMER_STATE_T timerStart(uint8_t t_id, uint16_t ticks);
 
// stops timer
void timerStop(uint8_t t_id);
 
// either returns ON or OFF or PAUSE
TIMER_STATE_T timerStatus(uint8_t t_id);
 
// set timer timeout in ticks
void timerSet(uint8_t t_id,uint16_t ticks);
 
// Timer function to be called from the timer irq handler.
// If at least on timer fired the function returns 1. Otherwise 0.
bool tick(void);
 
// pause timer
void timerPause(uint8_t t_id);
 
// resume timer
void timerCont(uint8_t t_id);
 
// Not yet implemented
void timerErase(uint8_t t_id);

Listing 2: The timer interface and the tick handler. The tick handler is checking if any timer has elapsed. In this case the user provided event is stored in the corresponding queue.

A queue service. Queues are used to store events from timers or other event sources in fifo order. Multiple queues can be created usually one per state-machine. The queue code is available in the library folder in files ringbuf.c and ringbuf.h.

typedef struct Buffer {
    uint8_t *data;
    uint8_t mask; // size - 1
    uint8_t read; // index of oldest element
    uint8_t write; // index of field to write to
} FIFO_T;
 
void fifoInit(FIFO_T * const buffer, uint8_t  * const pByte, uint8_t size);
bool fifoPut(FIFO_T * const buffer, uint8_t byte);
bool fifoGet(FIFO_T  * const buffer, uint8_t * const pByte);
bool fifoPutHead(FIFO_T * const buffer,  uint8_t byte);
bool fifoIsEmpty(const FIFO_T * const buffer);

Listing 3: The queue interface. Multiple queues can exist. A state machine usually has one input queue to pick the next event from.

Weaving the state machines and the library part together

On top of the minimal abstraction layer (timers, queues) the application specific part is located. It is implemented as state-machines reacting on the events. The state machine code is fully generated. All is generated from the UML state machine diagrams. The main routine initializes the hardware and then enters a main-loop waiting in low-power mode. ADC and timer iqr handlers wake-up the CPU after they enqueued an event. When woken-up the main loop pulls out these events and calls the appropriate state-machine with the event as parameter. See the following code snippet for the implementation details:

/**
 * Main loop initializes the hardware and software
 * and then waits in low power mode until new events
 * are present. Events are then pulled out of the
 * queues and forwareded to the apropriate state-machine.
 */
void main( void )
{
  // Stop watchdog timer to prevent time out reset
  WDTCTL = WDTPW + WDTHOLD;
 
  // initialize timer 
  TACCTL0 |= CCIE;                           // CCR0 interrupt enabled
  TACCR0 =  41U;
  TACTL = TASSEL_1 + MC_1 + ID_3;           // SMCLK/8, upmode  
 
 
  P1OUT &= 0x00U;               // Shut down everything
  P1DIR &= 0x00U;
  P1DIR |= BIT0 + BIT1+BIT2+BIT3;       // set pins to output the rest are input
  P1OUT |= BIT1 + BIT1+BIT2+BIT3;         //Select pull-up mode
 
  fifoInit(&buf1, buf1data ,sizeof(buf1data)/sizeof(uint8_t));
  fifoInit(&buf2, buf2data ,sizeof(buf2data)/sizeof(uint8_t));
 
  timerInit();
  init_uart();
  radio_init();
  initWindSensor();
 
  // run once to init
  toggle(&smToggle, TOGGLE_NO_MSG);
  pwr(&smPwr, PWR_NO_MSG);
 
  while(1){                      //Loop forever
 
    uint8_t retVal;
    uint8_t bufVal;
 
    do{                         // first process all events for task A
      retVal = fifoGet(&buf1, &bufVal);
      if(retVal!=QUEUE_EMPTY){
        toggle(&smToggle, bufVal);
      }
    }while(retVal!=QUEUE_EMPTY);
 
    do{                        // then all evenets for task B
      retVal = fifoGet(&buf2, &bufVal);
      if(retVal!=QUEUE_EMPTY){
        pwr(&smPwr, bufVal);
      }
    }while(retVal!=QUEUE_EMPTY);
    // more tasks could follow here
 
    __bis_SR_register(LPM3_bits + GIE);  // Enter low power mode once
    __no_operation();                    // no more events must be processed
 
  }
}

Listing 4: The main routine waiting in low power mode until events are available. Then these events are forwarded to the state machine handlers.

How to treat with longer lasting tasks

Execution time for handling events should be as short as possible. Longer lasting tasks should be split into chunks. Take the temperature measurement as an example. The temperature sensor TMP100 requires about 320ms conversion time according to the data sheet. The uC shouldn't wait and burn CPU cycles but either wait in low-power mode or process other events. This can easily be done by starting the conversion in one state (Step1) and then start a timer and enter low-power mode. If the timer fires we pick-up the conversion result (Step2) and process it further.

Another example is the wake-up procedure of the radio. After finishing low-power mode it takes a while before it is ready. Readiness is signalled via a transition of the RTS pin from high to low. After switching on the radio in state Step2a we enter low-power mode again. The level change creates an irq and sends the event evFallingEdgeRTS. Now the radio is ready to transmit data.

Object Diagram

The software design is shown in the next figure as UML object diagram. You can clearly see how the queues decouple the event sources from the event consumers. The main-loop serves as event dispatcher being only active if events are available in one of the queues. The main loop can also be used to prioritize one state machine over an other or ensure the order in which state machines are executed.

Figure 3: Object diagram of the whole application.

To verify the overall system behavior some output port pins were used as follows:

Timer A interrupt routine shown als clk in the first line. The port pin is inverted in each interrupt i.e. every 100 ms.
The supply voltage goes down. As reaction the measurement stops (line 2) and the power fail LED starts flashing (line 4). The evPowerFail starts from state Running. As a result it can happen that the temperature measurement cycle just starts in case a evPowerFail event happens but can't finish. You can see this in the oscilloscope image. There is just one peak. To fix this let the evPowerFail transition start from state Step2. This would ensure that a measurement cycle always completes before state changes to PowerFail.
Line 3 shows the timing of voltage measurement state machine (cycle of 2 seconds).

Figure 4: Oscilloscope image showing the timing of the whole application. Line 1: system tick. Line 2: timing of the temperature measurement phases. Measurement only happens if the supply voltage is above a defined threshold. Line 2: Supply voltage measurement. Line 3: LED output plus: Analog line: battery voltage.

Discussion

This article shows the principle concepts for designing low power embedded systems using state-machines, timers and queues.
Queues and timers as basic services which are application independent and can be reused from system to system. Timer resolution and number of timers and queues can be adjusted to optimize memory needs.
The user application is modeled as state machines receiving events from the outside or inside sources via queues. I.e. decoupling is done with queues.
State-machine processing time must be short enough to ensure that no events get lost and overall response time is ensured.

The source code is just meant for demonstration purposes. I'm happy to receive suggestions for improvement which I will add and make available for others again. The code composer workspace is available for download here.

Hope you enjoyed this article. Let me know your feedback!

Peter Mueller

[MSP430, Application Example]

New Version 2.7

anonymous@undisclosed.example.com (Anonymous) — Mon, 22 Oct 2012 19:46:29 +0000

New Version 2.7

04.01.2012

Version 2.7 of sinelaboreRT extends the test case generation features and makes the specification of multiline state action code in EA easier. Furthermore it adds support for sub-machine states in Enterprise Architect models.

Entering multi-line action code in EA Entering multiline action code (entry / exit / do) for a state was so far limited to one line. The action name was used as code. Now the code can be entered into the behavior field of an action. See the figure above for an example of two lines of entry code.

New test case generation algorithm

So far the code generator used a “depth first” method to find test routes (call the codegen using option -c). The used algorithm generates test routes that are as long as possible. The benefit is that usually fewer but longer routes are generated. The figure on the right shows the Safety Function Block test routes as a tree. You can see how deep this tree is which corresponds to the longest test route.

An additional new algorithms is available now (call the codegen using option -c1). It uses a 'breadth first' algorithm to find test routes. It begins also at the init state and explores all the neighboring states first. Then for each of those nearest states, it explores their unexplored neighbor states, and so on, until 100% transition coverage was reached. The result are shorter but typically more test routes. The following tree shows again the PLC Open Safety Block test tree but now generated using the new algorithm. You can see that the tree is much broader - i.e. there are more test routes to go. But at the same time the routes are much shorter.

It is up to you which algorithm to use. A tester might probably find the shorter routes easier to understand.

Support for Sub-Machine States in Enterprise Architect Models

Sub-machine states hide the complexity of a state from the viewer. A double click on the state opens the internals of this state. From the code generator point of view a sub-machine is a normal state with children. There is absolutely no difference compared to a normal hierarchal state. Take a look into the manual to find out more about the use of sub-machine states.

This new version is free for users who bought their license within the last two years.

Version 3.1

anonymous@undisclosed.example.com (Anonymous) — Thu, 03 Jan 2013 19:48:21 +0000

Version 3.1

Region support for the C++ backend

A UML state might be divided into regions. Each region contains sub-states. Regions are executed in parallel. You can think of regions as independent state machines displayed in one diagram.

For each region an own method is generated in the state machine class. Its name is automatically derived from the region name. If a state contains several regions they are called one after the other (in alphabetical order). If the event sent to the state machine was processed in one of the regions no further event handling happens in the parent state. Otherwise the event is processed in the parent state. This is similar to the event handling of normal hierarchical state machines.

To maintain consistency during execution of machine code a copy of the instance data is created at the beginning of the state machine code. All state machine internal tests are performed on the original instance data. All changes are done on the copy. This ensures that all regions see the same situation when running. At the end of the machine code the modified instance data is copied back to the original data.

Here is an example how the generated C++ code looks like:

// State machine event handler
int testcase::processEvent(TESTCASE_EVENT_T msg){
 
	int evConsumed = 0;
 
	if(m_initialized==false) return 0;
 
	//Create copy of statevar
	stateVarsCopy = stateVars;
 
	switch (stateVars.stateVar) {
 
		case S1:
			/* calling region code */
			evConsumed |= testcaseS1Region1(msg);
			evConsumed |= testcaseS1Region2(msg);
 
			/* Check if event was already processed  */
			if(evConsumed==0){
                          ...
 
 
                break;
	} /* end switch stateVar_root */
	// Copy state variables back
	stateVars = stateVarsCopy;
 
	return evConsumed;
} // end processEvent
 
 
 
// Region handler code for state S1 Region1
int testcase::testcaseS1Region1(TESTCASE_EVENT_T msg){
   ...
}
 
// Region handler code for state S1 Region2
int testcase::testcaseS1Region2(TESTCASE_EVENT_T msg){
   ...
}

New Parameter PrefixStateNamesWithMachineName

This parameter allows to prefix state names with the C machine name. Use this option if multiple state-machine header files are included into one other file (e.g. main.c) to avoid definition conflicts due to double used state names. See also parameter PrefixMsg- WithMachineName.

New Parameter PrefixStateNamesWithParentName

This parameter allows to prefix state names with the parent state name. Use this option if you have a hierarchical state machine and want to use the same state names in different child states. Example: There are two parent states called EngineOn and EngineOff. And in both states you have children FuelPumpOn and FuelPumpOff. To make the children names unique they can be prefixed with the parent name.

This new version is free for users who bought their license within the last two years.

Initial pseudo-states can end in a choice state now

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:47:15 +0000

Initial pseudo-states can end in a choice state now

In the current released version of sinelabore it is only possible to connect an initial pseudo-state to a normal state (hierarchical or flat). In some situations is is desirable to decide at runtime which state should be active initially when entering the state machine or a hierarchical state.

For that purpose it is now possible to connect the initial pseudo-state to a choice state which then points to the real initial state. This is possible

on the root level of a state machine diagram
in hierarchical states
in regions
in sub-machines

This adds a lot of new possibilities to design state diagrams.

This new feature requires a lot of coding internal in the generator backends and other parts of the code. Therefore this feature is only available in the CX backend initially. Also some other features of the code generator can't be used at the moment if “init to choice transitions” are used. Not available is:

test case generation
simulation / editing using the built in editor
robustness checks (partly)

More backends and the missing features will be added step by step depending on your feedback.

Please send me a note if you want to test the new beta. Feedback is highly welcome!

{(rater>id=7|name=How do you like this article?|type=rate)} ~~DISCUSSION:closed|Leave your comments~~

New versions 2.8.1 to 2.8.3

anonymous@undisclosed.example.com (Anonymous) — Mon, 22 Oct 2012 19:07:06 +0000

New versions 2.8.1 to 2.8.3

This update of the SinelaboreRT code helps Enterprise Architect and Magic Draw users to keep complex state diagrams with many transitions and/or states well-arranged.

Entry & Exit Points

So far transitions entering a sub-machine always had to end in the initial state. If this is not what you want it is possible now to use entry points to overcome this limitation. Entry points serve as glue between the sub-machine state and the internal of the sub- machine.

Exit states provide a similar function. If a transition should start from a specific state inside the sub-machine and should enter a state outside the sub-machine an exit state can be used. Again this exit state serves as glue between the inside and outside view.

The following figures shows a state diagram with the sub-machine state S2 and the internals of this sub-machine state.

Multiple Triggers per Transition

EA allows to define more than one trigger for a transition. This is useful if different triggers should trigger the same transition and have the same action code.

Multiple Transitions ending in a Choice

To simplify complex state diagrams it can be helpful to specify multiple incoming transitions into a choice state instead of duplicating the choices. The left side of the diagram shows how much simpler the right diagram can be represented now. Internally - before code generation starts - the code generator transforms your drawing back to the left representation.

This version of the code-generator uses the new jdom2.jar package. Copy the jar file to the correct place on your PC. If you don't know what this means please read section 'Installation' in the manual.

This new version is free for users who bought their license within the last two years.

Swift backend added

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 May 2024 20:42:32 +0000

Swift backend added

Swift is a new object-oriented programming language for iOS and OS X development. To generate Swift code call the code generator with the command line flag −l swift . To gener- ate a configuration file with all parameters related to the Swift code generation call the code generator as follows once:

java −jar codegen.jar −l swift −gencfg > codegen.cfg .

The events that can be sent to the machine are defined in a public enumeration.

The generator generates just one Swift class which implements the complete state machine. This has the benefit that your Swift project does not become bloated with all kinds of helper classes. This means that the generated code does not follow the usual state pattern as you might expect (if you are familiar with common design patterns). The reason is that the machine code is completely generated and no hand-coding is involved.

Separate generated from non-generated Code

Even if the state machine is fully generated this is usually only a smaller part of your application whereas the lager part is coded manually. For several reasons it is important to clearly separate generated code from non-generated code. Use one of the following possibilities to achieve this.

The most basic method is to put hand written code into libraries and call the library from within the state machine.
Generated classes can also subclass non-generated classes (base class of StateMachine). Such base classes can contain useful methods that can be called from within the generated subclasses.
Hand written code is located in a child class of the state machine. I.e. the state machine classes are parts of other classes.

Supported state machine features

States and sub-states
Deep - and flat hierarchy
Entry, Exit and Action code of states
Regions are supported and implemented as sub-functions called from the main state machine handler.
Option to define state machine signature
Choice pseudo-states

Example Design and Generated Code

swift_testcase.swift

Please note that the Swift back-end is work-in-progress. If you are interested to test and work with the code generator send me a mail and you will receive the latest beta version. Your feedback and feature requests are highly welcome!

~~DISCUSSION|Leave your comments~~

Generate code from Astah* activity diagrams

anonymous@undisclosed.example.com (Anonymous) — Sat, 07 Jun 2014 09:44:09 +0000

Generate code from Astah* activity diagrams

In the latest version of the SinelaboreRT code generator support for activity diagrams was added for astah* users. astah* is a UML modeling tool written in Java and can therefore run on various platforms like Windows or Mac. In opposite to some other tools it provides a Java API for direct access of the model file. Therefore it is not necessary to export the model (e.g. in XMI format) but the SinelaboreRT code generator can directly access the model file. This makes the development cycle very fast. Give it a try!

The following figure shows an extended version of the microwave oven example. A simple hardware selftest function was added to the transition leaving the initial state. In case this test is ok the software enters the normal operation states. Otherwise an error state.

The hardware selftest function was modelled as activity. The activity itself is trivial but enough to show the new possibilities. The code of each action forming the activity is available in the properties dialog of the actions. Take a look into the manual what other diagram elements can be used.

To generate code from the activity diagram use the following commands (command line on a Mac):

java -Djava.ext.dirs=“../../bin/”:“/Applications/astah community/astah community.app/Contents/Java/” -Djava.awt.headless=true -jar ../../bin/codegen.jar -l cx -A -v -p ASTAH -o oven -t “final:oven:selftest”

The -D options tells java where to look for the jar files. The new option -A enables code generation for activity diagrams.

In case of questions, problems or suggestions please contact us.

Have fun! Peter

New Version 3.0

anonymous@undisclosed.example.com (Anonymous) — Tue, 29 Jan 2013 17:09:59 +0000

New Version 3.0

Generate code from state machines with regions

In state diagrams usually only one state is active at a time. In UML state diagrams regions also allow to model concurrency - i.e. more than one state is active at a time (AND states).

A UML state may be divided into regions. Each region contains sub-states. Regions are executed in parallel. You can think of regions as independent state machines displayed in one diagram. The state machine below (Fig. 1) shows several regions each running in parallel in the state Active. Dashed lines are used to divide a state into regions.

Consider a microwave oven. The power setting, light and microwave radiator are be considered as independent (concurrent) parts of the oven, each with its own states. The door and timer as the main external trigger are used in the regions to trigger state transitions. For example the radiator is switched on if the door gets closed and the timer is > zero.

As you can see multiple concurrent regions can be used to explicitly visualize different parts of a device. And all the states in the one diagram.

The model and the generated code thereof is provided in the examples folder of the current release.

Figure 1a: State machine model of a microwave oven using regions (created with UModel).

UML tool Modelio supported

Modelio is an open source modeling environment based on Eclipse and providing high quality UML modeling capabilities. Commercial support is available too. The following figures show state diagrams created with Modelio. The tool runs on Linux and Windows.

Model with parallel regions.

Model with a sub-machine in state S2.

Supported state diagram features:

Hierarchical states
Regions (CX language backend only)
Sub-machines in a top level state
(Signal-)Events with event name, guard and action
Initial and final pseudo-states
History states
Choices

For a quick start download the latest release version and import the microwave oven into your Modelio workspace.

This new version is free for users who bought their license within the last two years.

~~DISCUSSION:closed|Leave your comments~~

Multiple instances of the same machine

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:44:23 +0000

Multiple instances of the same machine

Sometimes you want to run the same state machine multiple times. E.g. processing three serial interfaces with the same state machine. In object orient languages this is easy as the concept of objects is the basis of these languages. You would simply instantiate the class three times.

Luckily in C there is also a well known concept to do this. Instead of defining objects you define a (instance) structure that contains all local data a function needs. When calling that function a pointer to the instance data structure is handed over. In our case the function is the state machine handler. The code generator automatically creates the instance data structure automatically for you.

In this example we will show you how to “create multiple instances” of the state machine. And then we show you how to create an own structure where additional private data for the state handler can be defined.

Let's start …

Create Multiple Instances

Follow these simple steps to prepare the generated code for multiple instances. First set some parameters in the configuration file:

Set parameter HsmFunctionWithInstanceParameters to YES
Set parameter HsmFunctionWithEventParameter to YES

As a result the generated state machine handler signature looks like this:

void  testcase(TESTCASE_INSTANCEDATA_T* userInstanceVar, TESTCASE_EVENT_T msg)

You can now simply declare multiple variables of type TESTCASE_INSTANCEDATA_T which contains the data per instance. When calling the state machine just point to one of these variables.

Sometimes it is necessary that a state machine knows on which object it currently works on. Therefore a predefined member called inst_id is generated by default. You can set it to any value that makes sense in your context (e.g. provide the COM port number the machine currently processes).

TESTCASE_INSTANCEDATA_T instDataA = TESTCASE_INSTANCEDATA_INIT;
TESTCASE_INSTANCEDATA_T instDataB = TESTCASE_INSTANCEDATA_INIT;
TESTCASE_INSTANCEDATA_T instDataC = TESTCASE_INSTANCEDATA_INIT;
 
// Set object ID if the machine needs to know which object it is
// E.g. which serial port to open ...
instDataA.inst_id=0;
instDataB.inst_id=1;
instDataC.inst_id=2;
 
// call "object A"
testcase(&instDataA, msg);
 
// call "object B"
testcase(&instDataB, msg);
 
// call "object C"
testcase(&instDataC, msg);

I think you agree that there is no magic in running multiple instances of the state handler.

Provide an own Instance Structure

Sometimes it makes sense to provide an own instance structure. In our example we want to store the baud rate, parity and other values relevant for each serial port.

So first define an own struct in a file called own_inst_type.h (as an example). The example below shows how to define local variables like the noRxBytes (number of already defined bytes) as well as parameters like the parity etc.

#ifndef __OWN_INST_TYPE__
#define __OWN_INST_TYPE__
 
typedef struct InstanceData MY_TESTCASE_INSTANCEDATA_T;
 
#include <stdint.h>
#include <testcase_ext.h>
#include "testcase.h"
 
struct InstanceData{
        uint16_t baudrate;
        uint8_t noBits;
        uint8_t parity;
        uint8_t stopBit; 
        TESTCASE_INSTANCEDATA_T instanceVar;
};
 
#endif // __OWN_INST_TYPE__

Then tell the code generator to use this struct. Add the third line to the configuration file which then looks like this:

HsmFunctionWithInstanceParameters=YES
HsmFunctionWithEventParameter=YES
HsmFunctionUserDefinedParameter=MY_TESTCASE_INSTANCEDATA_T

The generated state machine signature now looks as follows. The difference is that the own instance structure is now used instead of the generic one.

void  testcase(MY_TESTCASE_INSTANCEDATA_T* userInstanceVar, TESTCASE_EVENT_T msg)

To use the newly defined instance type declare the instance variables now as follows:

// init three different serial ports
MY_TESTCASE_INSTANCEDATA_T instDataA = {0,9600,8,'N',1,TESTCASE_INSTANCEDATA_INIT};
MY_TESTCASE_INSTANCEDATA_T instDataB = {0,19200,8,'E',1,TESTCASE_INSTANCEDATA_INIT};
MY_TESTCASE_INSTANCEDATA_T instDataC = {0,9600,8,'N',1,TESTCASE_INSTANCEDATA_INIT};
 
// Set object ID if the machine needs to know which object it is
// E.g. which serial port to open ...
instDataA.instanceVar.inst_id=0;
instDataB.instanceVar.inst_id=1;
instDataC.instanceVar.inst_id=2;
 
// call "object A"
testcase(&instDataA, msg);

Now the state machine is ready to use the new private instance data inside the machine code.

Putting all Things Together

Coming back now to the example of three serial interfaces. The following figure shows a simplified state machine for handling a serial interface. The state machine is generic. Whether COM0 or COM1 or COM2 is processed is determined only from the content of the instance variable. And also other parameters are stored there and of course the local machine variables.

I hope that the concepts how to run multiple state machines of the same type are clearer now. And also how to define an own instance structure that is necessary for more complex machines.

In case of any questions don't hesitate to contact me!

~~DISCUSSION:closed|Leave your comments~~

Creating complex state machines

anonymous@undisclosed.example.com (Anonymous) — Sat, 21 Sep 2013 17:12:45 +0000

Creating complex state machines

The sinelabore code generator allows the generation of state machine code from quite complex state machines.

Nevertheless there are users who want to generate code from even more complex models. Especially if you used specialized state machine modeling tools before and now want to switch to general purpose UML tools this is for you.

Examples for features not possible before are states in regions that contain regions again (region in region¹⁾. Or models with sub-machines in regions. Both is shown in the figure below.

Have fun!

{(rater>id=5|name=How do you like this article?|type=rate)} ~~DISCUSSION|Leave your comments~~

¹⁾

Regions are well supported from the code-generator. But simulation and test-case generation is not yet possible. For more details have a look in the manual.

Building a ModbusRTU server with state machines, activity diagrams and minimal runtime environment

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:41:59 +0000

Building a ModbusRTU server with state machines, activity diagrams and minimal runtime environment

In one of the last design articles I described how to use state-machines in low power embedded software design together with timers and queues to create a wireless sensor node.

This time I use the same architecture to design and implement a basic ModbusRTU server. A UML state machine diagram shows the core behavior of the server. An activity diagram shows how the received frame is checked and a reply telegram generated. The server supports not all function codes and has a simple address map. But it will be easy to expand the design with more features.

The design is based again on a small TI MSP430 board already used in the previous article. The whole server runs in less than 256 bytes of ram and needs only few kilobytes of code. A RS485 interface was added as physical interface as defined by the ModbusRTU specification.

Modbus defines function codes to read/write either bit or word data. Function code four is defined to read analog input words (in our case only simulated values). Function codes one and five are defined to read/write digital outputs (coils). For demo purposes a LED is connected to a port pin of the µC.

For those not familiar with Modbus and ModbusRTU. Have a look www.modbus.org and search for the technical specification of the RS485 layer and the ModbusRTU server protocol.

Overall System Design

The model was realized with the Astah UML Editor. The model file is available here modbus.asta for download. The fastest overview provides an interaction diagram (see below). The relevant players are:

modbus: The central function realizing the modbus server functionality. The code was fully generated from a state machine diagram discussed later on.
modbus_helper: Helper functions used from the state machine and the rx frame checking code.
ringbuf, timer, crc16 …: Library classes that can be reused from project to project. These classes were already used in the previous examples (e.g. wireless temperature sensor).
timerA: Hardware timer to generate system tick
rs485: serial interface handler

The main() function initializing the hardware and software is not shown. It cyclically calls the modbus state machine and timer. In case of any pending events the modbus state machine is called.

For practical reasons classes were implemened as C/H files and member functions as C-functions. In the case a class is used multiple times instance data is packed into a structure and provided as reference to the functions. An example for this “object aware programming” is the fifo class.

Beside the object interaction diagram the following workspace view shows the project structure and used/generated files.

ModbusRTU State Machine

The state machine starts in state Idle. It initially enables the receiver and waits for the first byte. Then it changes to state Receiving until the complete frame was received. Every new byte retriggers the timer. The condition to detect that a complete frame was received is not receiving any new byte for a given amount of time (depends on baud rate, about 4ms @ 9600 Baud). The timer event evTimeout indicates this. The frame is checked before exiting the Receiving state (explained later on). Depending of the check result the machine either

enters Idle again without answering the request (see Modbus spec)
enables the transmitter and sends an error message back to the master
enables the transmitter and sends requested information back to the master.

When the complete reply frame was sent - indicated by event evTxDone from the rs485 transceiver - the state machine waits for about 4ms to indicate frame end and then goes to state Idle again waiting for the next frame.

Despite the ModbusRTU state machine looks simple it implements everything required for a slave!

Checking the Received Frame

Quite some complexity is hidden in checking the received frame (exit code of state Receiving). Therefore this function is designed with the help of an activity diagram and is fully generated from the code generator. The ModbusRTU specification uses flow charts. I tooke over the flow charts to a certain extend and reused that way what the ModbusRTU designers put into the spec.

The ModbusRTU spec contains an own flow chart for each function code. The presented design combined these single diagrams into just one activity diagram. As a consequence the single activities (e.g. check number of inputs, check valid address range) uses the function code to distinguish different requests. It is a matter of taste if this should also be made explicit in the activity diagram.

Testing

To test the complete design and implementation a ModbusRTU master is required. The next figures shows QModbus [2] running on a Linux box. There are also other command line tools which makes batch testing simpler.

The timing of the final device is shown below. D0 shows the system clock generated by hardware timer A. It calls the timer tick function. If no timer events were detected the CPU enters low power mode again. D2 shows the receiving telegram. D1 the transmission telegram. The CPU replys within 14ms. This could be further optimized if needed. The RS485 line is shown in the bottom part as differential signal (CH1-CH2).

One hint regarding stack-check: During development I had the need to check how much stack my code needs. I found the following code snipped on the web which turned out to be very useful. After running my test cases I could directly see how much space was left just looking at the memory browser window.

    // for checking the stack later on
    extern unsigned int _stack;
    extern unsigned int __STACK_END;
    unsigned int* p;
 
 
    p = &_stack;
    while (p < (&__STACK_END -3))
    {
        *p = 0xA5A5;
        p++;
    }
    // end for checking the stack later on

Wrapping Up

This article has presented the design of a MobusRTU server. It is is based on some library classes which can be reused from project to project. In addition state machine and activity diagrams were used to model the behavior of the device. From these models code was generated. So the design and the code will be always in sync and the modes are not just drawings!

The source code and model file is available upon request. I'm happy to receive suggestions for improvement which I will add and make available for others again.

Hope you enjoyed this article. Let me know your feedback! Peter

~~DISCUSSION:closed|Leave your comments~~

References: [1] www.modbus.org [2] http://qmodbus.sourceforge.net

[Modbus, ModbusRTU, Application Example, Activity, MSP430]

Using State-Machines in Low-Power Embedded Systems - Part II

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:42:03 +0000

Using State-Machines in Low-Power Embedded Systems - Part II

In the last part I've described a basic system design based on state machines, timers and queues. In this short update I extend the existing design with a radio transmitting the measured temperature to a central server. The updated hardware diagram looks as follows:

One new hardware signal is the /RTS line indicating readiness of the radio. The other one is an output signal to drive the radio into sleep mode and back into active mode.

The updated state machine works as follows. To keep the battery driven system running as long as possible the radio is in low-power mode most of the time. Only just before sending the µC wakes-up the radio in Step2a. The falling edge of the /RTS signal indicates the radio readiness which leads into Step2. In Step2 transmission takes place on interrupt basis (started by putchar()). During transmission /RTS is high. If transmission is over /RTS goes to low again. If this happens the radio is switched off again. In case transmission couldn’t completed the radio is switched off latest after 200ms. In Step3 we wait for 5s then the board signals the successful transmission with a short blink code (state BlinkGood). An then the cycle begins again. Output PORT1/Bit1 is used for debugging purposes. In low power mode just the LED blinks two times slowly to indicate low battery.

To feed in the /RTS signal into the state machine a new interrupt handler was added as shown below:

#pragma vector=PORT2_VECTOR
__interrupt void Port_2(void)
{
	if(fifoPut(&buf1, evFallingEdgeRTS)){
		globalErrHandler(); // buffer full
	}else{
		P2IFG &= ~RADIO_RTS;
		disableRtsIRQ();
		// wake up main routine to process state machines
		__bic_SR_register_on_exit(LPM3_bits);
	}
}

Listing 1: The falling edge event is put into the fifo queue. The state machine takes out event by event from that queue processing the events.

The main part of the UART code is the putchar() function and the transmit interrupt.

// Send a character via serial interface. If no transmission is running
// the character is directly put into the tx register, otherwise enqueued.
void putchar(uint8_t cByte)
{
	TX_INT_DISABLE; // disable transmit interrupt (in IE2)
	if(fifoIsEmpty(&txbuf) && (!txrunning)){ // queue empty and no transmission running
	    txrunning=true;
	    TXBUF0 = cByte; // load tx register, inc index
	}else{
		fifoPut(&txbuf, cByte);
	}
	TX_INT_ENABLE; // enable interrupt (in IE2)
}
 
 
 
// UART0 TX ISR. 
// The isr takes out the next char from the fifo.
#pragma vector=USART0TX_VECTOR
__interrupt void usart0_tx (void){
 
	static uint8_t txchar;
 
	bool empty = fifoGet(&txbuf,&txchar);
	_EINT();
	if(!empty){
		TXBUF0 = txchar;
	}else{// buffer empty, nothing to do
		txrunning=false;
	}
}

The updated state machine design was created with the built-in state machine editor of SinelaboreRT. The reason is simple: I wanted to use the development environment CCS from Texas Instruments on Linux. And Cadifra is only available on Windows. But this was no problem because every state machine can be automatically migrated to the internal editor. Those of you not knowing CCS should really take a look on it. It has some really cool features - e.g. the power measurement option to just name one.

Let me know if you are interested in the complete source code or need more explanation.

Have fun! Peter

~~DISCUSSION:closed|Leave your comments~~

New version 3.6 has support for activity diagrams

anonymous@undisclosed.example.com (Anonymous) — Tue, 13 May 2014 16:45:11 +0000

New version 3.6 has support for activity diagrams

There are two diagrams that can be used to express dynamic behaviour in the UML. State machine diagrams express the states of an object and the events and transitions to change the state. In contrast activity diagrams (aka flow diagrams) describe the control flow of an algorithm. The great thing of both types of diagrams is that they allow to generate 100% code out of the model description.

The latest version of the sinelabore code generator can now also generate code from activity diagrams. Activity diagrams consist of the following elements:

Black circle to indicate the begin of the activity
Circled black circle to indicate the end of the activity (return)
Rounded rectangles representing actions
Diamonds representing decisions and merge
Arrows connect the other elements and represent the flow throughout the diagram. Arrows might have a guard expression. If the guard expression is true the control flow follows this arrow to the next action.
Activity diagrams might contain sub-activities

In addition to this basic elements UML activity diagrams also allow to model loops and decisions.

To generate code from an activity diagram just call the code generator with the new command line parameter -A. The other command line parameters are still the same. Use the -t parameter to define the path in the model file to the class containing the activity. And -l for the target language.

Presently the code generator only supports XMI files exported from Enterprise Architect models and can only generate C code.

The following figure shows a fictitious activity diagram with all the elements presently supported from the code generator.

The code generator supports several configuration parameters that can be specified in the codegen.cfg file. The parameters are:

ActivityFileNamePostfix: By default the c/h file with the activity are based on the name specified by -o and the activity name in the model file. But for specific reasons it might be necessary to provide an additional postfix to the file names.

ActivityFunctionParameterDefinition: Allows to define the parameters for the activity function in the c file

ActivityFunctionPrefixHeader: Same as above but for the header file

ActivityFunctionPrefixCFile: Allows to define the type of the return value if the activity returns something

ActivityFunctionReturnCode: Defines the code snipped that is used at the end of the activity to actually return something.

To generate code from the above example diagram call the code generator the following way:

java -jar codegen.jar -A -p EA -o testcase -t “Model:test:class_with_activities” testcase.xml

The generated c-file can be found here. Due the way the algorithm is generated (based on a while loop with switch / case statements) all kinds of loops including back links can be generated without problem. For the shown diagram the generated code contains just 180 lines of code including empty lines and some documentation.

⇒The activity generator backend is still under development. Error handling and parser robustness must be increased. Additionally sections about the activity generator must be added to the manual.

Nevertheless the generator can already be used for real word applications. Please give it a try! Your feedback is very welcome.

Beside the activity generator backend the new version also contains several improvements in the state machine generator. In addition support for transitions from initial states to choice states in Java was added.

Have fun!

How to generate Lua Code from State Diagrams

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 May 2024 20:42:23 +0000

How to generate Lua Code from State Diagrams

Lua is a powerful, efficient, lightweight, embeddable scripting language (http://www.lua.org/). To generate Lua code call the code generator with the command line flag -l lua .

The generator generates one Lua module which implements the complete state machine. Take this simple state machine as example.

For a simple state machine with 4 states and 2 events the generated module looks like this:

function testcase:new()
        local new_inst = {}
        setmetatable( new_inst, testcase)
 
        -- machine states
        new_inst.states = {
                S1="S1",
                S11="S11",
                S12="S12",
                S3="S3",
                __UNKNOWN_STATE__="__UNKNOWN_STATE__"
        }
 
        -- machine events
        new_inst.events = {
                evB="evB",
                evA="evA",
                TESTCASE_NO_MSG="TESTCASE_NO_MSG"
        }
 
        -- Set state vars to default states
        new_inst.stateVar = new_inst.states.S1
        new_inst.stateVarS1 = new_inst.states.S11 -- set init state of S1 
 
        new_inst.init=false
        return new_inst
end
 
function testcase:processEvent(Event)
...
return evConsumed;
end
 
return testcase

The statemachine can be used as follows:

testcase = require "testcase"
 
local testcase1 = testcase:new()
Event = {event = testcase1.events.TESTCASE_NO_MSG, condition=false};
testcase1:processEvent(Event)
 
Event.event=testcase1.events.evA;
testcase1:processEvent(Event)

The following state machine features are supported:

States and sub-states
Deep – and flat hierarchy
Entry, Exit and Action code of states
Regions are supported and implemented as sub-functions called from the main state machine handler
Choice pseudo-states

The complete example is available in the examples/microwave_handbook_lua folder.

Any feedback is highly welcome!

Need to design on a Unix like OS?

anonymous@undisclosed.example.com (Anonymous) — Sun, 14 Sep 2014 09:56:44 +0000

Need to design on a Unix like OS?

Due to the fact that the code generator is written in Java it runs on basically all operating systems. The only requirement is to have a fairly recent Java version installed. But what if you want to design on a Unix system?

Most UML modelling tools don't run on Unix systems. What can you do?

Simply use the built in state machine editor. The only additional prerequisite is to install graphviz (for auto-layout) which is available also for many Unix like systems.

Below the state diagram editor runs on my FreeBSD server showing the GUI on my Mac box.

Enjoy your flexibility

Peter

freebsd-version -u
10.0-RELEASE-p8
export DISPLAY=192.168.6.25:0.0
java -jar codegen.jar -p ssc -E -o test.xml test.xml

Astah SysML

anonymous@undisclosed.example.com (Anonymous) — Sun, 23 Feb 2020 18:22:56 +0000

Astah SysML

In the latest version of the SinelaboreRT code generator the SysML Modeling tool Astah SysML is supported. The following screenshots show how the modeling tool looks like.

Instead using classes in class diagrams SysML uses blocks and block definition diagrams.

This example is the the model of a microwave oven as used in the manual and examples folder.

Also activity diagrams are possible and the generator can generate 100% code from these diagrams.

For a quick start download the latest release version and load the Astah SysML microwave oven from the examples folder.

This new version is free for users who bought their license within the last two years.

Have fun!

Generating C# code

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 May 2024 20:42:13 +0000

Generating C# code

To generate C# code call the code generator with the new command line flag -l csharp. All states are created into one source file. The file name is determined by the -o command line switch.

The generated code does not follow the state pattern as you might expect (if you are fa- miliar with common design patterns). The reason is that the machine code is completely generated and no hand-coding is involved. So the number of classes and files in your project is reduced to a minimum. The following figure shows the structure of the generated code. The classes marked with <generated> are generated from the code generator. Classes marked with <optional> are optional and must be provided by yourself if needed.

Figure: Structure of the generated C# code.

Microwave Oven Example in C#

A microwave oven is taken from the examples folder of the code generator to demonstrate the generator features. The example realizes a simple microwave oven and can be compiled with Microsoft Visual Studio¹⁾ on Windows²⁾. The next figure shows the state diagram of the oven. It was created with the Cadifra UML editor.

A simple hardware abstraction layer provides helper functions like a timer etc. You can see how it is called from the state machine (e.g. in an entry action) as hal.ovenOff().

You have the option to either generate an own state class per state or inline all the entry/do/exit action code directly into the generated state machine code. As there is no need for separate state classes (e.g. complex and long actions) they were inlined in this example. The generation process can be controlled with a simple configuration file as shown below. You can also see that we provide an own base class for the Oven class to implement some special functions directly usable from the state machine.

Namespace=OvenMachineNS
BaseClassMachine=OvenBase
BaseClassStates=StateBase
SeparateStateClasses=NO

To generate code from the diagram call the generator as follows:

java -Djava.ext.dirs=../bin/ -jar  "../bin/codegen.jar" -p CADIFRA -l csharp -o Oven oven.cdd

The generated code looks as follows:

namespace OvenMachineNS
{
  public class Oven : OvenBase
  {
 
    public enum States : int{
      Super,
      Completed,
      CookingPause,
      Idle,
      Cooking,
      __UNKNOWN_STATE__
    }
 
    public enum Events : int {
      evDoorOpen,
      evDec,
      evTimeout,
      evDoorClosed,
      evInc,
      evPwrLow,
      evPwrHigh,
      OVEN_NO_MSG
    }
 
  ...
 
 
    public int ProcessEvent(Events msg){
 
      int evConsumed = 0;
 
 
 
      if(m_initialized==false) return 0;
 
      /* action code */
      /* just a comment */
 
 
        switch (stateVar) {
 
          case States.Super:
 
            switch (stateVarSuper) {
 
              case States.Idle:
                if(msg==Events.evDoorClosed){
                  if(hal.timer_preset()>0){
                    /* Transition from Idle to Cooking */
                    evConsumed=1;
 
                    /* Action code for transition  */
                    hal.timer_start();
 
                    /* OnEntry code of state Cooking */
                    hal.ovenOn();
 
                    /* adjust state variables  */
                    stateVarSuper = States.Cooking;
                  }else{
                    /* Intentionally left blank */
                  } /*end of event selection */
                }else{
                  /* Intentionally left blank */
                } /*end of event selection */
              break; /* end of case Idle  */
 
              case States.Cooking:
 
  ...
 
 
 
          break; /* end of case Super  */
 
          default:
            /* Intentionally left blank */
          break;
        } /* end switch stateVar_root */
    return evConsumed;
  }
  }
  } // end of namespace

Finally start the generated exe file and play with the microwave oven. First increment the cooking time. Then start cooking by closing the door.

The sinelabore code generator provides much more features than just code generations. Before generation an extensive check is performed to ensure your diagram is correct (e.g. each transition has an associated event, all state names are unique …). You can add trace code if needed, simulate the state machine, generate test cases and more.

If you want to try out the example yourself download the code generator demo. The oven can be found in the examples folder.

~~DISCUSSION:closed|Leave your comments~~

¹⁾ , ²⁾

New versions 2.9

anonymous@undisclosed.example.com (Anonymous) — Mon, 22 Oct 2012 19:06:08 +0000

New versions 2.9

Editor / Simulator Improvements

A new editor component is used in the built–in state machine editor / simulator. The new editor supports folding, line numbers, syntax highlighting, correct copy/cut/paste short-cuts for the different operating systems and other nice features. Thanks to Robert Futrell for his very nice component (see section copyright in the manual for more info). The figure below gives an impression how the editor now looks like.

Issue fixed when simulating state machines with a history state

Visual representation of innerEvents in the built–in editor improved. Inner events are now clearly represented in the graphics as well as in the tree view

Other improvements

The isIn() methods returns a bool now instead an int in C++
getInnermostActiveState() is now a public method in Java

This version of the code-generator uses the new rsyntaxtextarea.jar package. Copy this jar file like the other jar files in the bin folder to the correct place on your PC. If you don't know what this means please read section 'Installation' in the manual.

This new version is free for users who bought their license within the last two years.

Using Activities -- Updated Microwave Oven

anonymous@undisclosed.example.com (Anonymous) — Sun, 18 May 2014 16:41:11 +0000

Using Activities -- Updated Microwave Oven

In the manual a simplified microwave oven is used to explain the generation of source code from state machine diagrams. This example was updated here to show how to generate code also from activity diagrams.

The extended state machine of the oven is shown below. For demonstration on how to use activities the oven performs a hardware selftest at startup. The hardware test happens on the incoming transition of the choice. Depending on the result of the selftest the machine enters an error state (marked in red) or the normal operation state (super). The hardware selftest routine was modelled as activity diagram.

The following code snipped shows the call of the hardware selftest. The selftest function itself was fully generated from the code generator

...
uint8_t hwStatus; // selftest status
 
void  oven(OVEN_INSTANCEDATA_T *instanceVar){
 
	OVEN_EV_CONSUMED_FLAG_T evConsumed = 0U;
 
 
	/*execute entry code of default state once to init machine */
	if(instanceVar->superEntry==1U){
		hwStatus = hardwareTest();
		if(hwStatus>0){
			instanceVar->stateVar = Error;
		}else{
			instanceVar->stateVar = Super;
		}
 
		instanceVar->superEntry=0U;
	}
 
 
	switch (instanceVar->stateVar) {
...

The hardware selftest function was modelled in an own activity diagram. A class can have one or more activity diagrams. The code generator generates an own c-file/header per activity. The activity of the hardware test function is shown below. The single steps do not really do anything useful and only the most basic features of an activity diagram are used. But it shows the principles and how well both generators complement each other.

To generate code from the diagram call the code generator as follows. The -A enables the generation of code from activity diagrams. Without this flag state machine code is generated. To generate both call the generator twice.

java -jar codegen.jar -p EA -A -t "Model:Class Model:first_example_step3" -o oven  first_example_step3.xml

The latest download contains the full model and code in the examples folder. The example is called microwave_handbook_enterpr_arch

In case of questions just send a mail.

Have fun!

New version 3.6.5

anonymous@undisclosed.example.com (Anonymous) — Sun, 18 Apr 2021 11:42:16 +0000

New version 3.6.5

This new version provides two important optimisations which results in better readability of the generated code and the activity diagram itself.

a) Actions in an activity diagram can contain spaces e.g. “check hardware” is translated into “CHECK_HARDWARE”. This increases the readability of the activity diagram.

b) Combining multiple actions into one action. If successive actions only have one incoming edge they can be combined into one actions. This increases performance and readability of the generated code.

The following activity diagram shows some examples where actions can be combined. This is the unnamed action and Action10 in the sub-activity Activity1. As well as Action2 with Action 3 with spaces and Action5 to Action9. The generated code for the latter looks as follows. The new action has a generated name but the comment clearly indicates which actions were the basis for the new action.

/* Merged from nodes:   Action5 Action8 Action9 */
case TEST_OPERATION_326F4FB4_71A5_42F3_94F5_BF4E5D5BA1EE:
   printf("action 5\n");
   printf("Effekt Action 8\n");
   printf("Action 9\n");
   id=TEST_OPERATION_ACTIVITYFINAL;
   break;

Feedback is as always welcome! Have fun!

Peter Mueller

~~DISCUSSION:closed|Leave your comments~~

Vending Machine example on GitHub

anonymous@undisclosed.example.com (Anonymous) — Sun, 25 Sep 2022 08:57:54 +0000

Vending Machine example on GitHub

Overview

A new fully functional vending machine example is available now. It is now hosted on GitHub so you can quickly check out the model and code yourself. Link to the repository: https://github.com/sinelabore/examples

The envisioned machine is shown below.

To compile the example just call make. It is assumed that you have installed the code generator from sinelabore and the Astah* Community UML tool (locations see Makefile).

After startup you can select a product “A”, “B” or “C” by pressing one of theses buttons on your keyboard.

Then you have to insert the coins to pay for the product. Only 10Ct, 20Ct and 50Ct coins are supported. To “insert” them click “1”,“2” or “5” on your keyboard.

After you paid the product will be released and you receive back your change.

Implementation

Most of the code is automatically generated from the UML model. It contains two state machines and an activity diagram. The state machines receive events from a message queue and can also send messages to other state machines. This is a well known design pattern to decouple objects. A timer service provides basic timer services that can be used from the state machines to realize delays or repetitive activities.

Product Store State Machine

The “product_store_sm” implements a simple product store containing the goods. It is responsible to release the products by turning on the motor etc.

Vending Machine

This is the controller machine keeping things together.

Change Algorithm

This is a simple algorithm modeled with the help of an activity diagram to release the right amount of money if the user overpaid. It takes care if one coin type is empty.

Have fun!

Activity diagram generation from UModel

anonymous@undisclosed.example.com (Anonymous) — Tue, 03 Jun 2014 20:17:30 +0000

Activity diagram generation from UModel

With this new version 3.6.2 it is now possible to generate code from activity diagrams created with UModel. UModel has support for the basic activity elements such as actions, init - and final nodes.

The microwave oven model microwave_handbook_umodel was extended to show how to use activity diagrams together with state machines in UModel. The example uses a selftest function called at initialisation of the state machine. If the selftest fails the machine enters an error state. The following figures show the extended oven model and a very simple selftest activity diagram.

Download the latest version and give it a try. Activity modelling is a very useful extension to state machine modelling!

Have fun!

Screenshots of the Simulator using Regions

anonymous@undisclosed.example.com (Anonymous) — Fri, 01 Mar 2013 19:13:24 +0000

Screenshots of the Simulator using Regions

The following screenshots show the simulator simulating the microwave oven example as available in the examples folder. States marked in red are active at the moment. Transitions marked in blue can be triggered from the active states. The output window shows the executed code (i.e. the entry/do/exit code you added to the state diagram). The simulator has to be called as shown below. I assume your shell prompt is located in the microwave_ea9_using_regions_c folder. Make sure you have Graphviz installed and in codegen.cfg configuration file the correct path to the dot.exe is set (e.g. DotPath=“C:\\Program Files\\Graphviz2.22\\bin\\dot.exe” for Windows or DotPath=/usr/local/bin/dot if you are on OS X)

java -Djava.ext.dirs=../../bin/ -jar ../../bin/codegen.jar -E -p EA -t "Model:implementation:oven" -o oven  oven.xml

After startup and reset of the simulation

After some time of cooking and then opening the door (pause)

After oven has counted down to zero and waiting the cook to open the door.

A demo of the code generator is available for download. Give it a try!

Generate code from state machines with regions

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:47:48 +0000

Generate code from state machines with regions

In state diagrams usually only one state is active at a time. In UML state diagrams regions also allow to model concurrency - i.e. more than one state is active at a time (AND states).

The latest beta now supports the modeling of parallel regions with the following constraints:

Transitions must not cross region boarders. Why this is important is discussed further down
No regions in regions
No support for fork
Join can be realized with transitions using guards like isInS221 && isInS222 as an example
UModel and EnterpriseArchitect as modeling tools
Only C/Ccode generation. No simulation etc. The remainder of this article explains how to use regions based on the microwave oven example also used in the manual. It also discusses why it can be tricky to use regions. ==== Notation ==== A UML state may be divided into regions. Each region contains sub-states. Regions are executed in parallel. You can think of regions as independent state machines displayed in one diagram. The state machine below (Fig. 1) shows several regions each running in parallel in the state ''Active''. Dashed lines are used to divide a state into regions. ==== Using multiple regions ==== Consider a microwave oven. The power setting, light and microwave radiator are be considered as independent (concurrent) parts of the oven, each with its own states. The door and timer as the main external trigger are used in the regions to trigger state transitions. For example the radiator is switched on if the door gets closed and the timer is > zero. As you can see multiple concurrent regions can be used to explicitly visualize different parts of a device. And all the states in the one diagram. The model and the generated code thereof is provided in the examples folder of the latest beta. {{ :wiki:news:oven_with_regions_umodel.png?nolink
Oven model with regions}} Figure 1a: State machine model of a microwave oven using regions (created with UModel). Figure 1b: State machine model of a microwave oven using regions (created with EA). ==== Alternative design without using regions ==== The microwave oven can also be modelled in a different way as shown below (the example is taken from the manual and code is available in the examples folder of the SinelaboreRT download). This model was created from an outside perspective not showing the state of different parts explicitly. It might be easier to follow the state flow during debugging and simulation because there is no parallelism. On the other hand the status of some parts of the oven are not a visible as in the model with regions. Figure 2: Oven model not using regions. ==== How regions are implemented ==== The following brief descriptions explains how regions are implemented. * For each region an own function is generated. Its name is automatically derived from the region name. * If a state contains several regions they are called one after the other (in alphabetical order). If the event sent to the state machine was processed in one of the regions no further event handling happens. Otherwise the event is processed in the parent state. This is similar to the event handling of normal hierarchical state machines. * To maintain consistency during execution of machine code a copy of the instance data is created at the beginning of the state machine code. All tests are performed on the original instance data. All changes are done on the copy. This ensures that all regions “see” the same situation when running. At the end of the machine code the modified instance data is copied back to the original data. Note: this is not yet available in the Cbackend.</del> Here is the simplified C-code example of the oven state machine. <code c> void oven(OVEN_INSTANCEDATA_T *instanceVar){ OVEN_EV_CONSUMED_FLAG_T evConsumed = 0U; OVEN_INSTANCEDATA_T instanceVarCopy = *instanceVar; switch (instanceVar->stateVar) { case Active: /* calling region code */ evConsumed = ovenActiveLight(instanceVar, &instanceVarCopy, msg);
evConsumed |= ovenActivePower(instanceVar, &instanceVarCopy, msg); evConsumed |= ovenActiveRadioator(instanceVar, &instanceVarCopy, msg);

/* Check if event was already processed */ if(evConsumed==0U){ .... /* handle event on parent level */

break; } /* end switch stateVar_root */

/* Save the modified instance data */ *instanceVar = instanceVarCopy;

} OVEN_EV_CONSUMED_FLAG_T ovenActiveLight(OVEN_INSTANCEDATA_T *instanceVar, OVEN_INSTANCEDATA_T *instanceVarCopy, OVEN_EVENT_T msg){

...

} OVEN_EV_CONSUMED_FLAG_T ovenActivePower(OVEN_INSTANCEDATA_T *instanceVar, OVEN_INSTANCEDATA_T *instanceVarCopy, OVEN_EVENT_T msg){

...

} OVEN_EV_CONSUMED_FLAG_T ovenActiveRadioator(OVEN_INSTANCEDATA_T *instanceVar, OVEN_INSTANCEDATA_T *instanceVarCopy, OVEN_EVENT_T msg){

...

} </code> And the same example for C: <code c++> State machine event handler int oven::processEvent(OVEN_EVENT_T msg){ int evConsumed = 0; OVEN_INSTANCEDATA_T instanceVarCopy = *instanceVar; if(m_initialized==false) return 0; switch (stateVar) { case Active: /* calling region code */ evConsumed |= ovenActiveLight(msg); evConsumed |= ovenActivePower(msg); evConsumed |= ovenActiveRadioator(msg); /* Check if event was already processed */ if(evConsumed==0){ …. /* handle event on parent level */ … return evConsumed; } /* Region code for state Active */ int oven::ovenActiveLight(OVEN_EVENT_T msg){ … } int oven::ovenActivePower(OVEN_EVENT_T msg){ … } int oven::ovenActiveRadioator(OVEN_EVENT_T msg){ … } </code> ==== Points to consider with regions ==== Transitions must not cross region boundaries In the first diagram state transitions do not cross region boundaries and therefore the modeller’s intension is quite clear. But look at the next diagram which is a valid diagram too. Now it is not clear anymore what the modeller had in mind. And it is also not very obvious what a code generator would/should generate. For that reason it is necessary that a code generator defines some limits here. Regions must work on the same instance data State diagrams follow the run-to-completion concept: Transitions that fire are fully executed and the state machine reaches a stable state configuration until it returns and can respond to the next event. To ensure this a copy of the instance data is kept and state changes are only performed on that copy. In practice this means that changes in one region does not influence other regions. Look into the following figure below. * If the event evClosed is sent region ValveA and ValveB change state. * But there is no state change in region Motor at the same time. The reason is that the transition from Stop → Run was not triggered at the beginning of the machine execution. * This behavior ensures that the result of a machine execution step is 100% predictable and e.g. not dependent of the execution order of the regions. * But on the other side it means that a second run of the machine is required to reach state MachineRun. I.e. the region Motor is always one cycle behind the Valve regions. ==== And the conclusions? ==== Usually there is a way to model a problem with regions and without regions. The solution with regions allows to model a kind of parallelism and allows to explicitly display independent parts of a system. On the other side exactly this parallelism is responsible that models with regions looks a bit more complex at first view. If you have comments and suggestions please let me know! If you are interested to test this version download the latest beta following this download link. —- ~~DISCUSSION:closed|Leave your comments~~