VFSM executor library
The idea
We provide a library vfsm.lib
which contains the executor of the StateWORKS specification. The library can be integrated into an application where it is used to process the state machine(s). The VFSM library is intended for use in projects where, for any reason, it is not appropriate to use the RTDB library, and its use implies that the developer will have to generate a greater amount of code than would be the case with the RTDB.
While coding the application we use a set of methods to:
- establish the VFSM Executor (CVfsm, GetSpecInfo)
- process the state transitions and trigger the actions (Execute)
- trace the VFSM Executor (Trace)
The VFSM Executor processes the state transition tables as specified in the StateWORKS Studio, changing states and calling output functions (actions). The main task of a developer is to code the output functions whose prototypes are declared in a file generated by the StateWORKS Studio.
Accessing the executor
The StateWORKS Studio generates (at Build) several files that can be used for implementation of the run-time system. The files: MyStateMachine.str
, MyStateMachine.h
and MyStateMachine_out.h
, (MyStateMachine
stands for the state machine name) are used for building an application with VFSM Executor. Their content must not be changed.
In addition, we use a library vfsm.lib
(which contains the state machine executor) and files: vfsm.h
and vessel.h
. The file vfsm.h
contains declarations of methods that are used for accessing the VFSM Executor while writing the application system:
is a constructor for the state machine, where
stVfsmName
is the name of the state machine (for instance onoff).stConfPath
is the path to the directory containing the specification results (for instance...\Samples\OnOff\Conf
).aActions
is the pointer to the output functions table.iActNum
is the number of output functions.InputObjectName
is the address of the set of pointers to sets of input names.
The 3 last parameters are declared in the file MyStateMachine_out.h
.
reads the information from the specification files required by the Vfsm executor.
is called if an event occurs (an input changes), where
iEvent
has to be an Input Name as specified in the StateWORKS Studio (declared in the fileMyStateMachine.h
).
is called if an event occurs (an input changes), where
iEvent
has to be an Input Name as specified in the StateWORKS Studio (declared in the fileMyStateMachine.h
).Remove
has to be a set of Input Names to be removed while actualizing the VI.
is called if an event occurs (an input changes), where
Events
has to be a set of Input Names as specified in the StateWORKS Studio (declared in the fileMyStateMachine.h
).
is called if an event occurs (an input changes), where
Events
has to be a set of Input Names as specified in the StateWORKS Studio (declared in the fileMyStateMachine.h
).Remove
has to be a set of Input Names to be removed while actualizing the VI.
delivers a string – the name of the present state.
delivers a string – the content of the VI.
delivers a number representing the present state.
is used to enable / disable tracing. The trace file with the name stFileName
(default: MyTrace.txt
) contains all state and VI changes. On entering the Vfsm executor an empty line and the present time is inserted: this arrangement allows seeing multiple state changes caused by a single event.
The vfsm.h
file contains a number of other methods that cannot be used in programming the application; they are for internal use by the VFSM Executor. Their private
access specifier disables any attempt to use them.
Writing output functions (actions)
In contrary to an RTDB based application [1] [2], for a coded application that uses the Vfsm library the use and meaning of RTDB objects is less relevant. Especially object properties do not play any role, as unless you would try to program something similar to the RTDB (and in such a case we would advise you to just use the RTDB!). Thus, any action independently of its type is just a call to an output function which has to perform an action as identified while specifying the state machine.
Prototypes of all output functions are generated by building the state machine configuration in StateWORKS Studio in the file MyStateMachine_out.h
. The implementation of these functions has to be done by a programmer, typically in a file MyStateMachine_out.cpp
.
The names of the output functions are composed of the name of the state machine and the Output Name as used in the StateWORKS Studio, for instance: OnOff_Timer_ResetStart
. The function may return information required to actualize the VI if applicable. For instance, the OnOff_Timer_ResetStart
that starts a timer should return the value to be inserted into VI (RUN
if it would be used). In the example OnOff
the specification uses only the value _OVER
therefore the function OnOff_Timer_ResetStart
will return the value 0 (which means nothing to insert).
Signal conversions
The VFSM Executor operates in a virtual environment defined by a state machine specification in the StateWORKS Studio. Using the RTDB, conversions between the real input signals to the virtual control values as well as between the virtual output values to real output functions are done automatically by the real-time-database. The RTDB holds the entire control structure of the system and handles the communication between objects which are the basic elements of the system containing both the real properties of signals and their virtual values.
The Vfsm library contains only the VFSM Executor. We could implement the conversion between the signals in the real world and the virtual environment of the Executor while writing the application. As this task is an error-prone one (changes in the specification may change the conversion rules) the StateWORKS Studio delivers (in the file MyStateMachine_out.h
) a set of constants which are used in the methods Execute()
for these real/virtual conversions and for actualization of the VI. These constants are automatically adjusted to any change in the specification.
Tracing
The VFSM Executor has a trace facility which can be enabled or disabled using the method Trace()
. If enabled all changes of VI and of states are written into the file MyStateMachine_trace.txt
. The time on entering the executor is written also into the trace file. If the trace facility is disabled the trace content is redirected onto the operator console.
The tracing facility is an essential debugging tool displaying the control flow while processing the state machines by the VFSM Executor. An excerpt of a trace file illustrates its content:
Limitations
The constants provided by StateWORKS Studio in the file MyStateMachine_out.h
do not cover the complement value. If a developer uses the complement values in specification of the state machine he has to provide the interface between the real input/outputs and virtual environment of the VFSM Executor in his code. As this becomes a relatively difficult and error-prone task we suggest use of the RTDB in such a case. Anyway, we do provide a variant of the Execute method that allows actualization of VI by hand.
References
[1] Wagner, F. et al., Modeling Software with Finite State Machines – A Practical Approach, Auerbach Publications, New York, 2006.
[2] StateWORKS RTDB Programmer’s Guide
The article was originally written by author F. Wagner in December 2007.
Here you can view the unedited file directly from the author: PDF