state machine shorthand - touretzkyds/cozmopedia GitHub Wiki

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 Transition Notation Chaining Multiple Sources and/or Destinations Setting Up A State Machine

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.