FPP State machine behavior spec

docs/code-prettify/run_prettify.js

@@ -404,6 +404,7 @@ var IN_GLOBAL_SCOPE = false;
       // We use things that coerce to strings to make them compact when minified
       // and to defeat aggressive optimizers that fold large string constants.
       var FPP_KEYWORDS = [
+          "action," +
           "active," +
           "activity," +
           "always," +
@@ -423,23 +424,30 @@ var IN_GLOBAL_SCOPE = false;
           "cpu," +
           "default," +
           "diagnostic," +
+          "do," +
           "drop," +
+          "else," +
           "enum," +
           "event," +
           "fatal," +
           "format," +
           "get," +
+          "guard," +
           "guarded," +
           "health," +
           "high," +
           "id," +
+          "if," +
           "import," +
           "include," +
+          "initial," +
           "input," +
           "instance," +
           "internal," +
+          "junction," +
           "locate," +
           "low," +
+          "machine," +
           "match," +
           "module," +
           "on," +
@@ -469,6 +477,7 @@ var IN_GLOBAL_SCOPE = false;
           "severity," +
           "size," +
           "stack," +
+          "state," +
           "string," +
           "struct," +
           "sync," +
@@ -479,6 +488,7 @@ var IN_GLOBAL_SCOPE = false;
           "topology," +
           "type," +
           "update," +
+          "visit," +
           "warning," +
           "with," +
           "yellow"

docs/fpp-users-guide.html

@@ -4840,7 +4840,7 @@ <h4 id="Defining-Components_Commands_Formal-Parameters">9.5.2. Formal Parameters
 
   @ Set the state
   async command SET_STATE(
-    state: State @&lt; The new state
+    $state: State @&lt; The new state
   )
 
 }</code></pre>
@@ -6386,7 +6386,7 @@ <h3 id="Defining-Components_Constants-and-Types">9.10. Constants and Types</h3>
 
   @ Set the state
   async command SET_STATE(
-    state: State @&lt; The new state
+    $state: State @&lt; The new state
   )
 
 }</code></pre>
@@ -12360,7 +12360,7 @@ <h4 id="Writing-C-Plus-Plus-Implementations_Implementing-Deployments_Public-Symb
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-05-16 12:07:04 -0700
+Last updated 2024-05-23 09:52:01 -0700
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

docs/index.html

@@ -463,7 +463,7 @@ <h1>F Prime Prime (FPP)</h1>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2021-10-04 10:03:10 -0700
+Last updated 2024-05-02 14:26:32 -0700
 </div>
 </div>
 </body>

docs/spec/Definitions/Component-Definitions.adoc

@@ -322,3 +322,67 @@ active component Imager {
 
 }
 ----
+
+[source,fpp]
+----
+@ A component with state machines
+active component DeviceMgr {
+
+  # ----------------------------------------------------------------------
+  # State machines
+  # ----------------------------------------------------------------------
+
+  @ A state machine representing a device
+  state machine Device {
+
+    @ Start the device
+    event Start
+
+    @ Stop the device
+    event Stop
+
+    @ Initial state is IDLE
+    initial IDLE
+
+    @ The IDLE state
+    state IDLE {
+      on Start visit RUNNING
+    }
+
+    @ The RUNNING state
+    state RUNNING {
+      on Stop visit IDLE
+    }
+
+  }
+
+  @ State machine instance for device 1
+  state machine instance device1: Device
+
+  @ State machine instance for device 2
+  state machine instance device2: Device
+
+  # ----------------------------------------------------------------------
+  # Special ports
+  # ----------------------------------------------------------------------
+
+  ...
+
+  # ----------------------------------------------------------------------
+  # Commands
+  # ----------------------------------------------------------------------
+
+  @ Send a Start event to the specified device
+  async command START(
+    @ The device number
+    deviceNum: U8
+  )
+
+  @ Send a Stop event to the specified device
+  async command STOP(
+    @ The device number
+    deviceNum: U8
+  )
+
+}
+----

docs/spec/Definitions/Module-Definitions.adoc

@@ -40,6 +40,8 @@ A module member is one of the following:
 
 * An <<Specifiers_Include-Specifiers,include specifier>>
 
+* A <<Definitions_State-Machine-Definitions,state machine definition>>
+
 ==== Semantics
 
 A module definition _D_ qualifies the names of all the definitions

docs/spec/Definitions/State-Machine-Definitions.adoc

@@ -0,0 +1,88 @@
+=== State Machine Definitions
+
+A *state machine definition* defines a state machine.
+
+==== Syntax
+
+* `state machine` <<Lexical-Elements_Identifiers,_identifier_>> 
+`{` _state-machine-behavior_ `}` 
+
+_state-machine-behavior_ is an 
+<<Element-Sequences,element sequence>> in
+which each element is a *state machine member*,
+and the terminating punctuation is a semicolon.
+A state machine member is one of the following:
+
+* A <<State-Machine-Behavior_State-Events,state events>>
+* A <<State-Machine-Behavior_State-Actions,state actions>>
+* A <<State-Machine-Behavior_State-Guards,state guards>>
+* A <<State-Machine-Behavior_State-Initial,state initial>>
+* A <<State-Machine-Behavior_State-Definition,state definition>>
+* A <<State-Machine-Behavior_State-Junction,state junction>>
+
+==== Semantics
+
+. The _identifier_ specifies the name of the state machine.
+
+. The _state-machine-behavior_ describes
+a hierarchical state machine.
+
+. _state_events_ specify all the _events_ that can be dispatched to this state machine.  An _event_ causes a state transition.
+
+. _state actions_ specify all the actions that can be invoked by this state machine.  An _action_ is a function that's called on a state transition.
+
+. _state guards_ specify all the guards that are used in transitions by this state machine.  A _guard_ is a predicate that indicates if a transition can occur.
+
+. The state machine must have one _state initial_ that specifies the initial state.
+
+==== Examples
+
+[source,fpp]
+----
+
+state machine MonitorSm {
+
+  event Complete
+  event Drive
+  event Calibrate
+  event RTI
+  event Stop
+  event Fault
+
+  action init2
+  action doCalibrate
+  action motorControl
+  action reportFault
+
+  guard calibrateReady
+
+  initial DeviceOn
+
+  state DeviceOn {
+
+    initial Initializing do init2
+
+    state Initializing {
+      on Complete visit Idle
+    }
+
+    state Idle {
+      on Drive visit Driving
+      on Calibrate if calibrateReady visit Calibrating
+    }
+
+    state Calibrating {
+      on RTI do doCalibrate
+      on Fault go Idle do reportFault
+      on Complete visit Idle
+    }
+
+    state Driving {
+      on RTI do motorControl
+      on Stop visit Idle
+    }
+
+  }
+
+}
+----

docs/spec/Definitions/defs.sh

@@ -17,6 +17,7 @@ Enum-Definitions.adoc
 Enumerated-Constant-Definitions.adoc
 Module-Definitions.adoc
 Port-Definitions.adoc
+State-Machine-Definitions.adoc
 Struct-Definitions.adoc
 Topology-Definitions.adoc
 "

docs/spec/Lexical-Elements.adoc

@@ -41,6 +41,7 @@ U16
 U32
 U64
 U8
+action
 active
 activity
 always
@@ -60,24 +61,33 @@ container
 cpu
 default
 diagnostic
+do
 drop
+else
+entry
 enum
 event
+exit
 false
 fatal
 format
 get
+guard
 guarded
 health
 high
 id
+if
 import
 include
+initial
 input
 instance
 internal
+junction
 locate
 low
+machine
 match
 module
 on
@@ -107,6 +117,7 @@ set
 severity
 size
 stack
+state
 string
 struct
 sync
@@ -118,6 +129,7 @@ topology
 true
 type
 update
+visit
 warning
 with
 yellow

docs/spec/Specifiers/State-Machine-Instance-Specifiers.adoc

@@ -0,0 +1,28 @@
+=== State Machine Instance Specifiers
+
+A *state machine instance specifier* instantiates a  <<Definitions_State-Machine-Definitions,state machine definition>>.
+
+==== Syntax
+
+`state machine instance`
+<<Lexical-Elements_Identifiers,_identifier_>>
+`:`
+<<Scoping-of-Names_Qualified-Identifiers,_qual-ident_>>
+
+==== Semantics
+
+. The _identifier_ is the name of the instantiated state machine
+
+. The _qual-ident_ is the name of the state machine definition
+
+==== Examples
+
+[source,fpp]
+----
+state machine MonitorSm {
+
+}
+
+@ state machine monitor1 is an instance of state machine model MonitorSm
+state machine instance monitor1 : MonitorSm
+----

docs/spec/Specifiers/defs.sh

@@ -21,6 +21,7 @@ Parameter-Specifiers.adoc
 Port-Instance-Specifiers.adoc
 Port-Matching-Specifiers.adoc
 Record-Specifiers.adoc
+State-Machine-Instance-Specifiers.adoc
 Telemetry-Channel-Specifiers.adoc
 Topology-Import-Specifiers.adoc
 "

docs/spec/State-Machine-Behavior/Introduction.adoc

@@ -0,0 +1,2 @@
+== State Machine Behavior
+

docs/spec/State-Machine-Behavior/State-Actions.adoc

@@ -0,0 +1,34 @@
+=== State Actions
+
+*state actions* specifies _actions_ that are invoked upon transitions.  Actions are functions that can carry data.
+
+==== Syntax
+`action`
+<<Lexical-Elements_Identifiers,_identifier_>>
+_[_
+`:` 
+<<Type-Names,_type-name_>>
+`]`
+
+==== Semantics
+. The _identifier_ specifies the action name.
+
+. The _type-name_ specifies an optional data type associated with the action and will be
+passed into the action function when invoked.
+
+==== Examples
+
+[source,fpp]
+----
+struct FaultData {
+    id: U32
+    data: U32
+}
+
+# An action without data
+action initPower
+
+# An action with data
+action reportFault: FaultData
+
+----