Getting started with StateBuilderDotNet.

In this tutorial, a LED system will be described and implemented using a finite state machine.

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.fsmcs represents the state machine description in XML.

Actually, StateBuilderDotNet reads XML state machines that validate against the schema file StateMachineDotNet-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.fsmcs.

Led State Diagram

Generated code class diagram

From the description of the LED state machine in Led.fsmcs listed above, StateBuilderDotNet 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.fsmcs => LedContext

The namespace for the generated class is given through the namespace tag.

This state machine controls the instance led of type Led

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

From the object class name Led, the context class constructor is : LedContext(Led led)

The asynchronous attribute tells the state machine is synchronous.

The events tag

The events tag has a list of event source, each eventSource have 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 and LedContext.

Source code

Led.h

Runtime Output

Here is the output when calling context.EnterInitialState(), context.On() and context.Off()

LedContext: entering in state Root
LedContext: entering in state SwitchedOff
DoOff
LedContext: transition begins from state SwitchedOff to SwitchedOn, event On
LedContext: leaving from state SwitchedOff
LedContext: entering in state SwitchedOn
DoOn
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
DoOff
LedContext: transition has ended from state SwitchedOn to SwitchedOff, event Off
    

What's next ?

This guide illustrates how StateBuilderDotNet 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 that can be used to solve complex real world problems.