Getting started with StateBuilderCpp.

In this tutorial, a LED system will be described and implemented with a finite state machine (FSM)

LED problem description

The LED example has a very simple state machine: 2 leaf states SwitchedOff and SwitchedOn, 2 events On() andOff(), 2 actions DoOff() and DoOn() and 2 transitions.

LED state machine xml description

The following file Led.fsmcpp represents the state machine description in XML.

Actually, StateBuilderCpp reads XML state machines that validate against the schema file StateMachineCpp-v1.xsd. A schema file contains the vocabulary and the grammar to describe state machines.

Led state machine diagram

The state diagram is a graphical representation of the LED state machine described above. This state diagram is automatically generated from Led.fsmcpp.

Led State Diagram

Generated code class diagram

From the description of the LED state machine in Led.fsmcpp listed above, StateBuilderCpp generates a set of classes: a context class and various state classes. Only the context class is used by the application class Led

The state machine design pattern found in the book "Design Patterns: Elements of Reusable Object-Oriented Software" written by the "Gang of Four" is used as the basic foundation for the generated code.

The class diagram of the LED state pattern is illustrated below:

LED state pattern class diagram

The state pattern is a way to implement hierarchical state machine. Each state is a class, events are members funtions of these class.

Meaning of the settings, events and state XML tag

The settings tag

The context class generated has its name inferred from the filename: Led.fsmcpp => LedContext

This state machine controls one instance of ledPrivate of type LedPrivate which can be find in LedPrivate.h

The oject instance name ledPrivate is referenced in the actions to get access to this object.

From the object class name LedPrivate, the context class constructor is :
LedContext::LedContext(LedPrivate &ledPrivate)

The asynchronous attribute tells the state machine is synchronous.

The library attribute set to std tells the code generator to use only the standard C++ library. Other values for this attribute are qt and boost.

The events tag

The events tag has a list of event source, each eventSource has a list of events.

The context class has a method for each event:

From now on, we know how the create an instance of the context class and send events to this context.

The state tag

Class Diagram

The following picture is a UML class diagram of the Led system:

LED state pattern class diagram

Here is a brief description of the relationships between the classes Led, LedContext and LedPrivate.

Source code





Runtime Output

LedContext: entering in state Root
LedContext: entering in state SwitchedOff
LedContext: transition begins from state SwitchedOff to SwitchedOn, event On
LedContext: leaving from state SwitchedOff
LedContext: entering in state SwitchedOn
LedContext: transition has ended from state SwitchedOff to SwitchedOn, event On
LedContext: transition begins from state SwitchedOn to SwitchedOff, event Off
LedContext: leaving from state SwitchedOn
LedContext: entering in state SwitchedOff
LedContext: transition has ended from state SwitchedOn to SwitchedOff, event Off

What's next ?

This guide illustrates how StateBuilderCpp can be used to implement and integrate a finite state machine into an application.

For more complex state machines, please have a look at the state machine examples. Discover the features such as asynchrounous, hierarchical and concurrent state machines than can be used to solve complex real world problems.