cheatsheet.tex

\documentclass[10pt,landscape]{article}
 \usepackage{multicol}
\usepackage{calc}
\usepackage{ifthen}
\usepackage[landscape]{geometry}
\usepackage{amsmath,amsthm,amsfonts,amssymb}
\usepackage{color,graphicx,overpic}
\usepackage{hyperref}
\usepackage{fancyvrb}
\usepackage{url}

\include{pygmentize}

\pdfinfo{
  /Title (rfsm-cheatsheat.pdf)
  /Creator (TeX)
  /Producer (pdfTeX 1.40.0)
  /Author (Markus Klotzbuecher)
  /Subject (rFSM cheatsheet)
  /Keywords (rfsm, statecharts, cheatsheet, lua)}

% This sets page margins to .5 inch if using letter paper, and to 1cm
% if using A4 paper. (This probably isn't strictly necessary.)
% If using another size paper, use default 1cm margins.
\ifthenelse{\lengthtest { \paperwidth = 11in}}
    { \geometry{top=.5in,left=.5in,right=.5in,bottom=.5in} }
    {\ifthenelse{ \lengthtest{ \paperwidth = 297mm}}
        {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} }
        {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} }
    }

% Turn off header and footer
\pagestyle{empty}

% Redefine section commands to use less space
\makeatletter
\renewcommand{\section}{\@startsection{section}{1}{0mm}%
                                {-1ex plus -.5ex minus -.2ex}%
                                {0.5ex plus .2ex}%x
                                {\normalfont\normalsize\bfseries}}
\renewcommand{\subsection}{\@startsection{subsection}{2}{0mm}%
                                {-1explus -.5ex minus -.2ex}%
                                {0.5ex plus .2ex}%
                                {\normalfont\small\bfseries}}
\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{0mm}%
                                {-1ex plus -.5ex minus -.2ex}%
                                {1ex plus .2ex}%
                                {\normalfont\footnotesize\bfseries}}
\makeatother

% Define BibTeX command
\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}

% Don't print section numbers
\setcounter{secnumdepth}{0}


\setlength{\parindent}{0pt}
\setlength{\parskip}{0pt plus 0.5ex}

%My Environments
\newtheorem{example}[section]{Example}
% -----------------------------------------------------------------------

\begin{document}
\raggedright
\scriptsize
\begin{multicols}{3}


% multicol parameters
% These lengths are set only within the two main columns
%\setlength{\columnseprule}{0.25pt}
\setlength{\premulticols}{1pt}
\setlength{\postmulticols}{1pt}
\setlength{\multicolsep}{1pt}
\setlength{\columnsep}{2pt}

\begin{center}
     \Large{\underline{rFSM Cheatsheet}}\\
     \small{(beta5)} \\
\end{center}

\section{Specifying rFSM Models}

\subsubsection{Synopsis}
\begin{verbatim}
    return rfsm.state {
       ...
    }
\end{verbatim}

\subsubsection{Decription}

A rFSM model is contained in a file that returns the toplevel state.

\subsection{Toplevel rFSM Configuration}

The following fields may defined in the toplevel state:

\begin{itemize}
\item \texttt{\texttt{getevents()}}: function that will be executed
  during step/run and must return a table of new events (index part
  only).
\item \texttt{dbg}, \texttt{info}, \texttt{err}: log functions. Must
  accept multiple parameters to log.
\end{itemize}


%%% States
\subsection{States}

States are the principle building block of rFSM Statecharts.

\subsubsection{Synopsis}

\begin{verbatim}
    rfsm.state {
       entry=function() do_this() end,
       exit=function() do_that() end,

       substate1=rfsm.state{...}, ...
       transition{...} ...
    }
\end{verbatim}

\subsubsection{Fields}

\begin{itemize}
\item \texttt{entry(fsm, state, 'entry'}: entry function
\item \texttt{exit(fsm, state, 'exit'}: entry function
\item \texttt{doo(fsm, state, 'doo'}: doo function/coroutine (only permited for leaf states)
\end{itemize}


\subsubsection{Description}

States model distinguishable conditions and encapsulate behavior. If a
state has substates it is called a \textbf{composite state}. Otherwise
it is called a \textbf{leaf state}. If a transition ends on a
composite state, this state must define an initial
transition. \textbf{Common error:} forgetting the commas.

\subsection{Transitions}

Transition connect states.

\subsubsection{Synopsis}

\begin{verbatim}
    rfsm.transition{ src=''stateX'', tgt=''stateY'',
                     events={"e_1", "e_2"} }
    rfsm.trans{ ... } -- short form
\end{verbatim}

\subsubsection{Fields}

\begin{itemize}
\item \texttt{src=<state-ref>}: source state reference
\item \texttt{tgt=<state-ref>}: target state reference
\item \texttt{events=\{event1, event2, ...\} }: list of events of
  which each may trigger the transition (\texttt{or}).
\item \texttt{guard}: side-effect free function that returns
  \texttt{true} or \texttt{false}. If false will inhibit transition.
\item \texttt{effect}: function that is execute when transition is taken.
\item \texttt{pn=<number>}: Priority number. Transitions with larger
  numbers take priority in case of conflicting transitions.
\end{itemize}


\subsubsection{Description}

Transitions define how the FSM changes state when events are received.
\texttt{<state-ref>} can be \textit{absolute} ``root.s1.s2'',
\textit{local} ``s1'' or \textit{relative} (``.subst1.subst2'').
Transitions may cross state boundaries or be layered on top of deeper
nested states by parent states using the relative notation.

\subsection{Connectors}
\label{sec:connectors}

\subsubsection{Synopsis}
\begin{verbatim}
    rfsm.connector{}
    rfsm.conn{} -- short form
\end{verbatim}

\subsubsection{Description}

Connectors can be used to build composite transitions by chaining
multiple connectors, or for defining different entry and exit points
of composite states. \textit{Note:} connectors only permit to build
more sophisticated transitions, the connector is \textit{never}
active!

\section{Loading, Instantiating and Advancing}

\subsection{Loading and Instantiating}

\subsubsection{Synopsis}

\begin{itemize}
\item \texttt{model=rfsm.load(filename)} Load a rFSM Model from a file.
\item \texttt{rfsm.init(model)} instantiate and validate a rFSM model
\end{itemize}

\subsection{Advancing rFSM instances}

\subsubsection{Synopsis}

\begin{itemize}
\item \texttt{rfsm.step(fsm)}: \texttt{step} a rFSM instance. This will execute at most one transition or one doo cycle.
\item \texttt{rfsm.step(fsm, N)}: \texttt{step} as above, but will perform at most \texttt{N} transitions or doo cycles.
\item \texttt{rfsm.run(fsm)} will run step until there are no new events and no active \texttt{doo} function.
\item \texttt{rfsm.send\_events(fsm, event1, event2, \dots)}: send events to the internal fsm queue.
\end{itemize}

\subsubsection{Description}

The basic step consists of the following: \textbf{1.} retrieve new
events using \texttt{getevents} hook. \textbf{2.} Find enabled
transitions starting from \texttt{root} state to active
leaf. \textbf{3.} If enabled transition found $\rightarrow$
execute. \textbf{4.} elseif active \texttt{doo} $\rightarrow$ run
it. \textbf{5.} discard current events.

After each \texttt{step} exactly \textbf{one} leaf-state will be
active.

\section{Miscellaneous}
\label{sec:miscellaneous}

\subsection{Tracing}
\label{sec:debugging}

Enable state entry and exit debug messages:

\begin{verbatim}
require "rfsmpp"
fsm.dbg=rfsmpp.gen_dbgcolor("fsmX",
                            { STATE_ENTER=true,
                              STATE_EXIT=true }, false)
\end{verbatim}
\medskip
Most important debug IDs are:
\begin{verbatim}
STATE_ENTER, STATE_EXIT, EFFECT, DOO, EXEC_PATH, 
ERROR, HIBERNATING, RAISED, TIMEEVENT
\end{verbatim}

\subsection{Time Events}

\begin{verbatim}
require "rfsm_timeevent
rfsm_timeevent.set_gettime_hook(gettime_func)
return rfsm.state {
   trans{ src="sA", tgt="sB", events={ "e_after(3)"} },
   ...
}
\end{verbatim}

\subsubsection{Description}
The \texttt{rfsm\_timeevent} module enables relative time
events. After loading, a suitable \texttt{gettime} function must be
set. This function returns two values: current seconds and current
nanoseconds. Available functions: \texttt{rtp.clock\_gettime} (from
the rtp module, see section \textit{Links}), \texttt{rtt.getTime} from RTT-Lua, or for
second resolution events the Lua built-in:
\begin{verbatim}
function gettime() return os.time(), 0 end
\end{verbatim}

\textit{Note:} These timeevents only work for periodically triggered
components.

\subsection{Sequential AND state}

\subsubsection{Synopsis}

\begin{verbatim}
    seqAND = rfsm.seqand {
       subfsm1=rfsm.init(rfsm.load("subfsm1.lua")),
       subfsm2=...
    }
\end{verbatim}

\subsubsection{Fields}

\begin{itemize}
\item \texttt{order}: table of substate names that indicate the desired execution order. Not mentioned states are executed last.
\item \texttt{andseqdbg}: if true print debug info
\item \texttt{step}: number of steps to advance each time.
\item \texttt{run}: if true, don't step but \texttt{run}.
\item \texttt{idle\_doo}: doo flag to be returned by seqand yield.
\end{itemize}

\subsubsection{Description}
Specialized state that \texttt{step}'s or \texttt{run}'s the
initialized substates in a serialized manner inside the \texttt{doo}
function of the seqand state.

\subsection{Complete Example}

\begin{verbatim}
local state, trans, conn = rfsm.state, rfsm.conn, rfsm.trans
return rfsm.state {
   dbg=rfsmpp.gen_dbgcolor("sample-fsm")
   entry=function() enable_robot() end,
   entry=function() disable_robot() end,

   stopped = state{},

   moving = state {
      entry=function() start_motor() end,
      exit=function() stop_motor() end,

      doo = function()
        while true do
           compute_next_pos()
           rfsm.yield(true)
        end,
   }
   trans{ src="initial", tgt="stopped" },
   trans{ src="stopped", tgt="moving", events={"e_start"} },
   trans{ src="moving", tgt="stopped", events={"e_stop"} },
}
\end{verbatim}

\subsection{Links}
\label{sec:links}

\url{www.orocos.org/rfsm}
\url{http://www.orocos.org/wiki/orocos/toolchain/LuaCookbook}
\url{https://github.com/kmarkus/rtp}

% You can even have references
\rule{0.3\linewidth}{0.25pt}
\scriptsize
\bibliographystyle{abstract}
\bibliography{refFile}
\end{multicols}
\end{document}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End: