From: Benjamin Braatz <benjamin.braatz@graph-it.com>
Date: Wed, 9 Nov 2022 14:29:47 +0000 (+0100)
Subject: Add documentation.
X-Git-Url: http://git.graph-it.com/?a=commitdiff_plain;h=9fdf3fb2ffe6038b7da2103d0b0fd3d35e7e5cb6;p=graphit%2Fcontrolpi-statemachine.git

Add documentation.
---

diff --git a/conf.json b/conf.json
index 04fe43a..45773d7 100644
--- a/conf.json
+++ b/conf.json
@@ -1,5 +1,5 @@
 {
-    "Example Server": {
+    "Debug": {
         "plugin": "WSServer",
         "port": 8080,
         "web": {
@@ -7,16 +7,6 @@
                    "location": "Debug" }
         }
     },
-    "Lubrication Button": {
-        "plugin": "Alias",
-        "from": {
-            "target": { "const": "Lubrication Button" },
-            "command": { "const": "press" }
-        },
-        "to": {
-            "event": "pressed"
-        }
-    },
     "Engine Button": {
         "plugin": "Alias",
         "from": {
@@ -37,12 +27,13 @@
             "event": "pressed"
         }
     },
-    "Lubrication": {
-        "plugin": "State"
-    },
     "Engine": {
         "plugin": "State"
     },
+    "Delay": {
+        "plugin": "Wait",
+        "seconds": 5
+    },
     "Machine": {
         "plugin": "StateMachine",
         "init": "off",
@@ -53,11 +44,6 @@
                         "target": "Engine",
                         "command": "set state",
                         "new state": false
-                    },
-                    {
-                        "target": "Lubrication",
-                        "command": "set state",
-                        "new state": false
                     }
                 ],
                 "transitions": [
@@ -76,11 +62,6 @@
                         "target": "Engine",
                         "command": "set state",
                         "new state": false
-                    },
-                    {
-                        "target": "Lubrication",
-                        "command": "set state",
-                        "new state": false
                     }
                 ],
                 "transitions": [
@@ -93,23 +74,18 @@
                     },
                     {
                         "trigger": {
-                            "sender": { "const": "Lubrication Button" },
+                            "sender": { "const": "Engine Button" },
                             "event": { "const": "pressed" }
                         },
-                        "to": "lubrication on"
+                        "to": "on"
                     }
                 ]
             },
-            "lubrication on": {
+            "on": {
                 "commands": [
                     {
                         "target": "Engine",
                         "command": "set state",
-                        "new state": false
-                    },
-                    {
-                        "target": "Lubrication",
-                        "command": "set state",
                         "new state": true
                     }
                 ],
@@ -121,33 +97,20 @@
                         },
                         "to": "emergency"
                     },
-                    {
-                        "trigger": {
-                            "sender": { "const": "Lubrication Button" },
-                            "event": { "const": "pressed" }
-                        },
-                        "to": "off"
-                    },
                     {
                         "trigger": {
                             "sender": { "const": "Engine Button" },
                             "event": { "const": "pressed" }
                         },
-                        "to": "engine on"
+                        "to": "delay"
                     }
                 ]
             },
-            "engine on": {
+            "delay": {
                 "commands": [
                     {
-                        "target": "Engine",
-                        "command": "set state",
-                        "new state": true
-                    },
-                    {
-                        "target": "Lubrication",
-                        "command": "set state",
-                        "new state": true
+                        "target": "Delay",
+                        "command": "wait"
                     }
                 ],
                 "transitions": [
@@ -160,10 +123,10 @@
                     },
                     {
                         "trigger": {
-                            "sender": { "const": "Engine Button" },
-                            "event": { "const": "pressed" }
+                            "sender": { "const": "Delay" },
+                            "event": { "const": "finished" }
                         },
-                        "to": "lubrication on"
+                        "to": "off"
                     }
                 ]
             }
diff --git a/doc/DebugView.png b/doc/DebugView.png
new file mode 100644
index 0000000..8345b9d
Binary files /dev/null and b/doc/DebugView.png differ
diff --git a/doc/index.md b/doc/index.md
index b52b667..11baa12 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -29,4 +29,164 @@ es auch direkt, ohne einen git-Clone installiert werden:
 ```
 
 ## Benutzung
-…
+Eine minimale ControlPi-Konfiguration, die dieses Plugin benutzt, ist im
+git-Repository enthalten:
+```json
+{
+    "Debug": {
+        "plugin": "WSServer",
+        "port": 8080,
+        "web": {
+            "/": { "module": "controlpi_plugins.wsserver",
+                   "location": "Debug" }
+        }
+    },
+    "Engine Button": {
+        "plugin": "Alias",
+        "from": {
+            "target": { "const": "Engine Button" },
+            "command": { "const": "press" }
+        },
+        "to": {
+            "event": "pressed"
+        }
+    },
+    "Emergency Button": {
+        "plugin": "Alias",
+        "from": {
+            "target": { "const": "Emergency Button" },
+            "command": { "const": "press"}
+        },
+        "to": {
+            "event": "pressed"
+        }
+    },
+    "Engine": {
+        "plugin": "State"
+    },
+    "Delay": {
+        "plugin": "Wait",
+        "seconds": 5
+    },
+    "Machine": {
+        "plugin": "StateMachine",
+        "init": "off",
+        "states": {
+            "emergency": {
+                "commands": [
+                    {
+                        "target": "Engine",
+                        "command": "set state",
+                        "new state": false
+                    }
+                ],
+                "transitions": [
+                    {
+                        "trigger": {
+                            "sender": { "const": "Emergency Button" },
+                            "event": { "const": "pressed" }
+                        },
+                        "to": "off"
+                    }
+                ]
+            },
+            "off": {
+                "commands": [
+                    {
+                        "target": "Engine",
+                        "command": "set state",
+                        "new state": false
+                    }
+                ],
+                "transitions": [
+                    {
+                        "trigger": {
+                            "sender": { "const": "Emergency Button" },
+                            "event": { "const": "pressed" }
+                        },
+                        "to": "emergency"
+                    },
+                    {
+                        "trigger": {
+                            "sender": { "const": "Engine Button" },
+                            "event": { "const": "pressed" }
+                        },
+                        "to": "on"
+                    }
+                ]
+            },
+            "on": {
+                "commands": [
+                    {
+                        "target": "Engine",
+                        "command": "set state",
+                        "new state": true
+                    }
+                ],
+                "transitions": [
+                    {
+                        "trigger": {
+                            "sender": { "const": "Emergency Button" },
+                            "event": { "const": "pressed" }
+                        },
+                        "to": "emergency"
+                    },
+                    {
+                        "trigger": {
+                            "sender": { "const": "Engine Button" },
+                            "event": { "const": "pressed" }
+                        },
+                        "to": "delay"
+                    }
+                ]
+            },
+            "delay": {
+                "commands": [
+                    {
+                        "target": "Delay",
+                        "command": "wait"
+                    }
+                ],
+                "transitions": [
+                    {
+                        "trigger": {
+                            "sender": { "const": "Emergency Button" },
+                            "event": { "const": "pressed" }
+                        },
+                        "to": "emergency"
+                    },
+                    {
+                        "trigger": {
+                            "sender": { "const": "Delay" },
+                            "event": { "const": "finished" }
+                        },
+                        "to": "off"
+                    }
+                ]
+            }
+        }
+    }
+}
+```
+
+In der Debug-Oberfläche sieht das Beispiel folgendermaßen aus:
+![Debug-Oberfläche](graphit/controlpi-statemachine/DebugView.png)
+
+Die beiden `Alias`-Instanzen simulieren Taster und die `State`-Instanz
+`Engine` einen Motor, der von der Statemachine gesteuert wird.
+Aus dem initialen Zustand `off` kann durch Drücken des `Engine Button` in
+den Zustand `on` gewechselt werden.
+
+Nochmaliges Drücken des `Engine Button` schaltet die Maschine aber nicht
+sofort ab, sondern wechelt in einen fünf-sekündigen Nachlauf im Zustand
+`delay`.
+Dies wird dadurch erreicht, dass beim Betreten des Zustands dem
+`Wait`-Plugin `Delay` das Kommando `wait` geschickt wird und der Zustand
+dann durch eine Transition, die auf das `finished`-Event reagiert verlassen
+wird.
+
+Außerdem kann die Maschine aus jedem Zustand heraus durch Drücken des
+`Emergency Button` sofort abgeschaltet werden, wobei in den Zustand
+`emergency` gewechselt wird.
+Dieser kann nur verlassen werden, wenn durch nochmaliges Drücken des
+`Emergency Button` bestätigt wird, dass die Gefahr vorüber ist.