diff --git a/.vuepress/sidebar.js b/.vuepress/sidebar.js index e3252ed0..68ea5ba9 100644 --- a/.vuepress/sidebar.js +++ b/.vuepress/sidebar.js @@ -26,14 +26,20 @@ module.exports = () => { ...getFiles('doku/RedMatic') ] }, - + { + title: 'Crashkurs', + collapsable: false, + children: [ + ...getFiles('doku/Crashkurs') + ] + }, { title: 'FAQ', collapsable: false, children: [ ...getFiles('doku/FAQ') ] - } + }, ]; sidebar['/nodes/'] = [ diff --git a/doku/Crashkurs/01_node-red-editor.md b/doku/Crashkurs/01_node-red-editor.md new file mode 100644 index 00000000..b09406a4 --- /dev/null +++ b/doku/Crashkurs/01_node-red-editor.md @@ -0,0 +1,47 @@ +# Node-RED + +> Node-RED is a programming tool for wiring together hardware devices, APIs and online services in new and interesting ways. + It provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes in the palette that can be deployed to its runtime in a single-click. + + +## Editor + +![node-red editor](./images/redmatic-1.png) + +Der Flow Editor von Node-RED ist nicht sonderlich kompliziert. Auf der linken Seite sind die installierten Nodes aufgelistet. +In der Mitte werden die einzelnen Flows designed, darüber die Flow-Tabs die zur Kategorisierung dienen. Die rechte Seitenleiste +ist wiederum in Tabs aufgeteilt um verschiedene Ansichten auszuwählen. Das Bild zeigt das Debug-Panel was Ausgaben aus `debug` +Nodes anzeigt. Wichtig sind auch die _Node information_ die nützliche Hilfestellungen der aktuell ausgewählten Node anzeigen. + +Um Flows zu erstellen werden die Nodes per drag & drop in den Editor gezogen. Sie werden durch _Wires_ miteinander verbunden +indem man einen Verbindungspunkt anklickt, die Maustate gedrückt hält und den Verbindungspunkt der Ziel-Node auswählt. + +![node-red editor](./images/crash-2.mov.gif) + +::: tip + Mit `Strg-click` öffnet sich ein Autocompleter-Widget um eine neue Node an der Mausposition einzufügen. +::: + +## Deployment + +Wenn ein Flow fertig gestellt ist muss er deployed, also aktiv geschaltet werden. Hierzu dient der `Deploy` Button +in der oberen rechten Ecke des Editors. Nach einem Deployment werden die Änderungen übernommen und live geschaltet. + +Es gibt verschiedene Arten des Deployments: + +* **Full** + Deployed _alle_ Flows. Gleicht einem Neustart von Node-RED und initiiert + Flows deren Input Node _Beim Start letzten bekannten Wert ausgeben_ gewählt haben. + Bei häufiger Anwendung kann sich dies negativ auf den DutyCycle der CCU auswirken. + +* **Modified Flows** + Deployed alle Flows aus allen geänderten Flow-Tabs. + +* **Modified Nodes** + Es werden nur veränderte Nodes deployed. Diese Option sollte während der Entwicklung verwendet werden. + + +## Weitere Dokumentation + +* [Node-RED Website](https://nodered.org/) +* [Node RED Programming Guide](http://noderedguide.com/) diff --git a/doku/Crashkurs/02_flows.md b/doku/Crashkurs/02_flows.md new file mode 100644 index 00000000..86aa921f --- /dev/null +++ b/doku/Crashkurs/02_flows.md @@ -0,0 +1,46 @@ +# Flows + +![RedMatic Flow](./images/flow.png) + +Ein Flow ist das Zusammenspiel von einem `Input` Event bis hin zu einer `Output` Aktion. + +Das eintreffende Event startet eine Kette von Modifikationen, Prüfungen oder Verzögerungen was zu einem Ergebnis führt. +Dies wird an eine `Output` Node übergeben welche z.B. einen Aktor schaltet oder eine E-Mail verschickt. + +Zwischen den einzelnen Nodes wird das Event anhand eines `msg` Objekts übergeben. Es besitzt, je nach Event, verschiedene Properties. +Eine Konvention von Node-RED sieht `msg.payload` als den Wert vor, der den Zustand/Wert angibt, also z.B. true/false für an/aus. + +Die Properties von `msg` sind in Datentypen eingeteilt wie _boolena_, _number_, _string_ oder _JSON_. + +![prop types](./images/prop-types.png) + +## Input Nodes + +Input Nodes starten einen Flow. Das kann aus verschiedensten Gründen notwendig sein. Zum Beispiel zu einer bestimmten +Uhrzeit, wenn ein Taster gedrückt wird, wenn eine Temperatur überschritten wird und noch aus vielen weiteren anderen Gründen. + +Jede Node die einen Verbindungspunkt auf der rechten Seite hat und auf ein externes Ereignis reagiert kann einen Flow starten. +Meist kann man aus dem Info-Panel die nötigen Daten ablesen um das Event weiter zu verarbeiten. + + +## Modification Nodes + +Sie dienen zur Steuerung des Flow-Verhaltens und legen z.B. den Unterschied zwischen ein- oder ausschalten einer Lampe fest. +Zudem können sie auch genutzt werden um den Flow vorzeitig zu beenden wenn beispielsweise am Tag kein Licht durch einen +Bewegungsmelder angeschaltet werden soll. Einige Nodes haben mehrere Outputs an denen der Flow fortgesetzt werden kann. +Zum Beispiel kann `Output 1` genutzt werden um eine Lampe EIN und `Output 2` um die selbe Lampe AUS zu schalten, +je nachdem ob die Lampe gerade an oder aus ist. + + +## Output Nodes + +Eine Output Node bewegt ein externes System dazu den Zustand zu ändern. Man erkennt sie neben dem Namen daran, dass +sie auf der linken Seite einen Verbindungspunkt haben, oft aber nicht auf der rechten Seite. Ein Output kann das Schalten +eines Homematic Aktors sein, eine Telegram Nachricht oder E-Mail aber auch die Zustandsänderung eines Dashboard-Widgets. + + +## Subflows + +Node-RED unterstützt das Konzept von Subflows. Ein Subflow ist die Kapselung von verschiedenen Nodes und daraus +eine wiederverwendbare eigene Node zu erstellen. Dies ist sehr nützlich wenn oft die selben Nodes in Flows +verwendet werden. Wie auch jede andere Node kann ein Subflow einen einzigen Input haben und verschiedene Outputs. diff --git a/doku/Crashkurs/20-beispiele.md b/doku/Crashkurs/20-beispiele.md new file mode 100644 index 00000000..16bb5254 --- /dev/null +++ b/doku/Crashkurs/20-beispiele.md @@ -0,0 +1,44 @@ +# Beispiele + +## Licht schalten + +![Toggle light flow](./images/bsp-licht-schalten/flow-toggle-light.png) + +Zur besseren Übersicht ist oben zuerst eine `comment` Node mit der Beschriftung "Licht Arbeitszimmer" eingefügt. + +Als Input Node kommt die [ccu value Node](/nodes/ccu/value.html) zum Einsatz. Sie kann sowohl einzelne Datenpunke +lesen als auch schreiben, je nachdem ob sie am Anfang oder am Ende eines Flows positioniert wird. +In diesem Beispiel soll das Licht über einen Homematic Wandtaster geschaltet werden weshalb als _Interface_ `BidCos-RF` +in den Node Einstellungen gewählt wird. Der Channel und der Datapoint legen den Wert fest auf den reagiert werden soll. +Ein gültiger Channel könnte `OEQ0537081:1 Gang unten Taster` sein. Je nach gewähltem Kanal stehen verschiedene Datenpunkte +zur Verüfung. Im Falle eines Tasters z.B. `PRESS_SHORT`, `PRESS_LONG` oder `PRESS_CONT`. Letzteres ist ein Event was +bei dauerhaftem Druck immer wieder erzeugt wird. + +![Edit value node props](./images/bsp-licht-schalten/edit-value-node-props.png) + +Da wir den selben Taster zum ein- und ausschalten nutzen wollen müssen wir den Zustand des Aktors je nach aktuellem +Zustand setzen. Aus diesem Grund wird nun der Zustand abgefragt und je nach Wert wird der Flow an `Output 1` oder `Output 2` +fortgesetzt. Hierzu kann die [ccu switch Node](/nodes/ccu/switch.html) verwendet werden. Der aktuelle Zustand eines +Schaltaktors steht im Datenpunkt `STATE` und dem Property `value`. Zu einem Datenpunkt gibt es weitere Properties +wie z.B. den Zeitstempel der letzten Änderung. + +![ccu switch node props](./images/bsp-licht-schalten/ccu-switch-node-props.png) + +Nachdem jetzt bekannt ist ob die Lampe an oder aus ist wird der Zustand, genauer `msg.payload` invertiert. +Dazu kann eine `change` Node verwendet werden. Sie setzt beliebige Properties von `msg` auf einen neuen Wert. +Entsprechend den Ausgängen der `ccu switch` Node kann hier `true` bzw `false` gesetzt werden. + +![change node props](./images/bsp-licht-schalten/change-node-props.png) + +Zuletzt wird das Event `msg` an die Output Node übergeben wofür wieder die [ccu value Node](/nodes/ccu/value.html) +verwendet werden kann. + +![value node props](./images/bsp-licht-schalten/ccu-value-output-node-props.png) + +Um den Flow aktiv zu schalten wird er zum Schluß deployed. + +::: tip +Die `debug` Node eignet sich sehr gut um die Werte eines Events zu analysieren. +Im Debug-Tab in der Seitenleiste wird die debug-`msg` dargestellt. +::: + diff --git a/doku/Crashkurs/images/bsp-licht-schalten/ccu-switch-node-props.png b/doku/Crashkurs/images/bsp-licht-schalten/ccu-switch-node-props.png new file mode 100644 index 00000000..f4a4e1a8 Binary files /dev/null and b/doku/Crashkurs/images/bsp-licht-schalten/ccu-switch-node-props.png differ diff --git a/doku/Crashkurs/images/bsp-licht-schalten/ccu-value-output-node-props.png b/doku/Crashkurs/images/bsp-licht-schalten/ccu-value-output-node-props.png new file mode 100644 index 00000000..867b53b1 Binary files /dev/null and b/doku/Crashkurs/images/bsp-licht-schalten/ccu-value-output-node-props.png differ diff --git a/doku/Crashkurs/images/bsp-licht-schalten/change-node-props.png b/doku/Crashkurs/images/bsp-licht-schalten/change-node-props.png new file mode 100644 index 00000000..c1e4fd2b Binary files /dev/null and b/doku/Crashkurs/images/bsp-licht-schalten/change-node-props.png differ diff --git a/doku/Crashkurs/images/bsp-licht-schalten/edit-value-node-props.png b/doku/Crashkurs/images/bsp-licht-schalten/edit-value-node-props.png new file mode 100644 index 00000000..4fac9470 Binary files /dev/null and b/doku/Crashkurs/images/bsp-licht-schalten/edit-value-node-props.png differ diff --git a/doku/Crashkurs/images/bsp-licht-schalten/flow-toggle-light.png b/doku/Crashkurs/images/bsp-licht-schalten/flow-toggle-light.png new file mode 100644 index 00000000..6d129df5 Binary files /dev/null and b/doku/Crashkurs/images/bsp-licht-schalten/flow-toggle-light.png differ diff --git a/doku/Crashkurs/images/crash-2.mov.gif b/doku/Crashkurs/images/crash-2.mov.gif new file mode 100644 index 00000000..7953c457 Binary files /dev/null and b/doku/Crashkurs/images/crash-2.mov.gif differ diff --git a/doku/Crashkurs/images/flow.png b/doku/Crashkurs/images/flow.png new file mode 100644 index 00000000..4cd6e12c Binary files /dev/null and b/doku/Crashkurs/images/flow.png differ diff --git a/doku/Crashkurs/images/node-settings.png b/doku/Crashkurs/images/node-settings.png new file mode 100644 index 00000000..a05f21a9 Binary files /dev/null and b/doku/Crashkurs/images/node-settings.png differ diff --git a/doku/Crashkurs/images/prop-types.png b/doku/Crashkurs/images/prop-types.png new file mode 100644 index 00000000..0f3725a5 Binary files /dev/null and b/doku/Crashkurs/images/prop-types.png differ diff --git a/doku/Crashkurs/images/redmatic-1.png b/doku/Crashkurs/images/redmatic-1.png new file mode 100644 index 00000000..07c29131 Binary files /dev/null and b/doku/Crashkurs/images/redmatic-1.png differ diff --git a/doku/Crashkurs/images/redmatic-1.xcf b/doku/Crashkurs/images/redmatic-1.xcf new file mode 100644 index 00000000..5610b6d3 Binary files /dev/null and b/doku/Crashkurs/images/redmatic-1.xcf differ diff --git a/doku/RedMatic/02_crashkurs.md b/doku/RedMatic/02_crashkurs.md deleted file mode 100644 index 2b3b8d4c..00000000 --- a/doku/RedMatic/02_crashkurs.md +++ /dev/null @@ -1,22 +0,0 @@ -# Crashkurs - - -![](/wiki/images/crash-1.png) -* Aus der _Palette_ im linken Bildschirmbereich können _Nodes_ per Drag&Drop im _Flow_ platziert werden -* _Nodes_ können über einen Eingang auf der linken Seite und/oder einen Ausgang auf der rechten Seite mit anderen Nodes verbunden werden -* Nachdem ein _Flow_ verändert wurde müssen die Änderungen per klick auf _Deploy_ übernommen werden -* Der _Inject Node_ erzeugt bei klick auf den Button an seiner linken Seite eine _Message_ -* Der _Debug Node_ zeigt eingehende _Messages_ im Debug Fenster an -* Das Debug Fenster befindet sich in der _Sidebar_, diese kann im Menü oben rechts unter "View" durch klick auf "Show Sidebar" angezeigt werden - - -![](/wiki/images/crash-2.mov.gif) - -## Editieren von Nodes, Verbindungen und Layout -* Ein Node oder eine Verbindung kann durch Anklicken selektiert werden (oranger Rahmen) -* Mehrere Nodes können durch aufziehen eines Selektionsrahmen (Maustaste halten und ziehen) ausgewählt werden. -* Selektierte Nodes können im Paket bewegt werden. -* Selektierte Nodes (auch mehrere) und deren Verbindungen könne mit der Entf-Taste gelöscht werden. -* **Einzelne** Verbindungen können mit der Entf-Taste gelöscht werden. -* Mit Strg-z kann man eine Änderung/Löschung rückgängig machen. (Wenn noch nicht deployed wurde!) -