state machine shorthand

Dave Touretzky edited this page Dec 26, 2016 · 17 revisions

cozmo_fsm provides a state machine shorthand notation that makes it easy to construct well-formed state machines. Files written in this notation must be translated into Python files using the genfsm tool.

Table of Contents

Node Notation

Node classes must be subclasses of StateNode. The syntax for constructing a node instance is:

label: NodeClass(arguments)
The label is optional, but can be useful when tracing a state machine with lots of similar nodes. The colon indicates that this a label definition rather than a reference to a label defined elsewhere. A node must have a label for a transition to refer to it explicitly. If omitted, a label will be automatically generated based on the node class name. Labels must be unique within a state machine and must be legal Python variable names. Examples:
greet: Say("Hello world")
wait: StateNode()
Forward(50)

Transition Notation

Transition classes must be subclasses of Transition. The syntax ofr constructing a transition instance is:

source =label: type(arguments)=> destination
The source and destination must be a node definition, a node label, or a list of node labels.

The transition label is optional and usually omitted, but is useful when tracing a state machine with lots of similar transitions. If omitted, a label will be automatically generated based on the transition class name. Labels must be unique within a state machine and must be legal Python variable names.

The type can be either a full class name or an abbreviation. Abbreviations are defined for the most common transition types as indicated in the table below.

Unlike in Python, the argument list for a transition is optional. If there are no arguments, it is legal to write just the transition class name with no following parentheses. Examples (omitting the source and destination):

=C=>
=T(5)=>
=mylabel:MyTransition("spam",42)=>
Shorthand Long Form Description
N NullTrans Fires immediately.
T(secs) TimerTrans(secs) Fires after the specified number of seconds.
C or C(n) CompetionTrans Fires when all (or at least n) source nodes have completed.
S or S(n) SuccessTrans Fires when all (or at least n) source nodes have posted a SuccessEvent.
F or F(n) FailureTrans Fires when all (or at least n) source nodes have posted a FailureEvent.
Tap or Tap(cube) TapTrans Fires when any cube (or a specific cube, e.g., cube1) is tapped.

Chaining

Node and transition definitions can be chained together to form linear sequences.

Example:
start: Say("Foo") =T(10)=> Forward(200) =C=> Turn(180) =C=> start

Multiple Sources and/or Destinations

Normally each transition has one source node and one destination node, but it's possible to have multiple sources and/or multiple destinations. In that case the nodes must be defined elsewhere, and the transition is preceded or followed by a list of node labels enclosed in braces.

Examples:
launch: StateNode =N=> {parallel_action_1, parallel_action_2}
{sing, dance} =C(1)=> think

Setting Up A State Machine

To create a state machine you define a node class for the parent (must be a subclass of StateNode), and then instantiate its nodes as children. The special syntax $setup{...} indicates that state machine shorthand is being used and needs to be translated to Python code. For example:

 def Greet(StateNode):
     $setup {
         Say("hello world") =C=> StateNode =T(5)=> Say("Bye-bye now.")
     }

Instead of using {...} to delimit the shorthand notation, you can use three quotes ("""), which will cause a Python-sensitive text editor to treat the shorthand as a Python comment.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.