rFSMTools

A set of tools to build, debug and execute
rFSM LUA-based state machines

Download

What is rFSMTools?

rFSMTools is a set of C++ library (librFSM) to load and execute rFSM LUA-based state machines and a graphical modelling tools (rfsmGui) to create, debug and execute the state machine.

Designed for developers

rFSM is a small and powerful Statechart implementation written in Lua for coordination of complex systems. Take maximum advantage of rFSM functionality using rfsmTools to accelerate your application deveploment, debugging and delivery.

Time saver

Build and debug your state machine in few clicks with minimal coding. Simply drags and drops states and transitions directly from the gui, and generates code for your state machine.

Easy to use

Build and edit your state machine directly from rfsmGui modeling tool or any source code editor. We also offer an embedded state-machine source editor for editing and debugging state machines at run time.

Few Dependencies

rFSMTools have been developed with minimum dependencies. The librFSM exploits Lua 5.x and rFSM (embeddable) lua package. The Gui simply relies on Qt 5.x and graphviz library for automatic layouting.

  Features

  Get Started

  Dependencies

librFSM can be built with the built-in rfsm lua library (default is ON).

  • Lua library (5.x)
  • Qt (5.x)
  • Graphviz development library for rfsmGui
  • rFSM (optional)

   Installation on Linux

  • Install one of the lua developemnt library (e.g., 5.1, 5.2, ...) and the graphviz development package
  • If you do not want to use the built-in rfsm then follow the installation of rFSM
                        
$ sudo apt-get install lua5.X-dev libgraphviz-dev

$ sudo apt-get install qtbase5-dev qtdeclarative5-dev qtdeclarative5-qtquick2-plugin \
qtdeclarative5-window-plugin qtdeclarative5-controls-plugin qtdeclarative5-dialogs-plugin

  • Compile and build
                        
$ cd rfsmTools
$ mkdir build; cd build
$ cmake ../; make


Notice:   If you do not want to to use the built-in rfsm you can disable cmake EMBED_RFSM flag

                        
$ cmake -DEMBED_RFSM=OFF ../; make

   Installation on Windows

  • Install lua for windows or download and build one of the lua library (e.g., 5.1, 5.2, ...)
  • Download and Install Qt5. Follow the the installation instruction to set the environemnt variables (Qt5_DIR and PATH).
  • Install graphviz for windows and set/update the corresponding enviornment variables (GRAPHVIZ_ROOT and PATH):
                        
 C:\> setx.exe Qt5_DIR path_to_the_qt_installed_directory\qt5\5.X\msvc20XX\lib\cmake\Qt5
 C:\> setx.exe PATH "%PATH%; path_to_the_qt_installed_directory\qt5\5.X\msvc2010\bin"
 C:\> setx.exe GRAPHVIZ_ROOT path_to_the_graphviz_installed_directory
 C:\> setx.exe PATH "%PATH%; path_to_the_graphviz_installed directory\bin"

  • The compilation is straightforward and uses the CMake build system. Get CMake for windows if you have not yet installed. Then simply run the Cmake and, set the project (rfsmTools) root folder and the desired build folder. Configure and generate project solution for your favorite IDE (e.g. Visual Studio 11). Then open the solution from your IDE and build the project.

   Installation on macOS

                        
$ brew update

  • Install Lua
                        
$ brew install lua

  • Install Qt5
                        
$ brew install qt
$ brew link --force qt

  • Add the following lines to your .bash_profile 
                        
$ export Qt5_DIR=/usr/local/opt/qt5/lib/cmake
$ export PATH=/usr/local/opt/qt5/bin:$PATH

  • Install Graphviz
                        
$ brew install graphviz

Now you can choose to compile using GNU Makefiles or Xcode:
  • GNU Makefiles
                        
$ cd rfsmTools
$ mkdir build; cd build
$ cmake ../; make

  • Xcode
                        
$ ccmake .. -G Xcode

This will generate .xcodeproj file which can be opened with Xcode. Build it by clicking Product -> Build or cmd+B shortcut. One can also compile the Release biaries by clicking Product -> Archive.

  Testing the library


$ ./examples/rfsmTest ../examples/fsm/rfmodule_fsm.lua

  Testing the rFSMGui

Launch the rfsmGui. Open the example rFSM state machine from rfsmTools/examples/fsm/rfmodule_fsm.lua.

  • Running: To execute the state machine, just press the Start from the Run menu. you can interfere the execution of the state machine by Pausing it or sending arbitrary events from Gui.
  • Debugging: In the debug mode, you can step the state machine, send arbitrary events and etc. Debugging state machine using GUI also offer the dry-run mode. When an state machine executed in dry-run mode, none of the entry, doo or exit callbacks of a state are called! To debug the state machine, just press the Step or Run from the 'Debug' menu. Stepping the state machine, consumes an event from the event queue and performs the corresponding transition. Running it, will continue stepping until there is no event left in the event queue.
  • Building: To build a new state machine simply press New rFSM, select the filename and then start creating your rFSM using the build toolbar on the left. Once you finish just press Save and your Lua code will be generated.
     

  • Editing: You can edit a pre-existing state machine in two ways, directly from the embedded source editor and graphically through the rFSMGui. In the latter case it is possible to add/remove/rename states and transitions and pressing Save the code will be generated in one file preserving pre-definded entry, doo, exit functions and all the code defined before "return rfsm.state{" statement.
    For now the "graphical editor" is enabled ONLY for those state machines that are defined in only one file. Later we will remove this limitation.
     

  Example of using rfsm from C++

                  
                   /**
                    * Define a callback class
                    */
                    class MyStateCallback : public rfsm::StateCallback {
                    public:
                        virtual void entry() {
                            std::cout<<"entry() of MyState (hello from C++)"<<std::endl;
                        }
                        virtual void doo() {
                            std::cout<<"doo() of MyState (hello from C++)"<<std::endl;
                        }
                        // ...
                    } myStateCallback;

                    /**
                     * main code
                     */ 
                    int main(int argc, char** argv) {
                    
                        // Create an instance of StateMachine and load an rfsm state machine 
                        rfsm::StateMachine rfsm;   
                        rfsm.load("my-statemachine.lua")

                        // setting some callbacks
                        rfsm.setStateCallback("MyState", myStateCallback);                        

                        // send some events to state machine 
                        rfsm.sendEvent("event1");
                        
                        // step/run through the states 
                        rfsm.step(1);                            
                        std::cout<<rfsm.getCurrentState();
                        rfsm.sendEvents(2, "event1", "event2");
                        rfsm.run()
                        
                        //...    
                        return 0;
                    }

  Contributors

  License




Copyright 2017 iCub Facility

Authors: Ali Paikan, Nicolò Genesio, Silvio Traversaro

CopyPolicy: Released under the terms of the LGPLv2.1 or later.

  Contacts