Docu rework and added help to dwd.html

README.md

@@ -6,48 +6,261 @@
 [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
 [![License][mit-badge]][mit-url]
 
-> Node-RED Nodes zum abfragen von Wetterwarnungen des Deutschen Wetterdienstes (DWD)
 
-__These Nodes are only useful if you're interested in weather warnings for Germany, can't be used in other countries.__
+Node-RED Node zum Abfragen von Wetterwarnungen des Deutschen Wetterdienstes (DWD).
 
 
-#### `msg` Attribute
+![node-appearance](images/node-appearance.png "Node appearance")  
+**Fig. 1:** Darstellung des Nodes
 
-* `payload` - Maximale Warnstufe aktueller Warnungen
-* `count` -  Anzahl der Warnungen
-* `events` - Kommagetrennte Aufzählungen der Warnungs-Kategorien
+---
+
+__Remark:__ This Node is only useful if you're interested in weather warnings for **Germany**, it can't be used for other countries.
+
+---
+
+
+Die Wetterdaten werden vom DWD (Deutscher Wetterdienst, Frankfurter Straße 135, 63067 Offenbach) bereitgestellt.  
+Sie können folgende Wetterwarnungen beinhalten:
+- Wind (Böen, Sturm, Orkan)
+- Gewitter
+- Starkregen, Dauerregen
+- Schneefall, Schneeverwehungen
+- Glatteis, Glätte, Frost
+- Nebel
+- Tauwetter
+- Hitze
+- UV-Strahlung
+
+
+
+<a name="installation"></a>
+## Installation
+
+<a name="installation_in_node-red"></a>
+### In Node-RED (bevorzugt)
+* Über *Manage palette* -> Nach "node-red-contrib-dwd" suchen und installieren
+
+<a name="installation_in_a_shell"></a>
+### Über eine Shell
+* Ins Node-RED Installationsverzeichnis gehen, z.B.: `~/.node-red`
+* Ausführen von `npm install node-red-contrib-dwd`
+
+<a name="usage"></a>
+## Verwendung
+Die Verwendung des Nodes ist wie folgt:
+
+![basic-usage](images/basic-usage.png "Node usage")  
+
+**Fig. 2:** Grundsätzliche Verwendung des Nodes
+
+Der Node wird über eine Eingangs-Message getriggert und gibt an seinem Ausgang die Wetterdaten aus.
+
+
+<a name="node_configuration"></a>
+### Node Configuration
+In den Eigenschaften des Nodes ist lediglich die Einstellung der *Region* notwendig.  
+
+![node-settings](images/node-settings.png "Node Eigenschaften")  
+
+**Fig. 3:** Node Eigenschaftendialog
+
+Die auswählbaren Regionen bzw. Städte können durch Klicken in das Feld und Drücken z.B. der Leertaste dargestellt werden. Es öffnet sich dann ein Pulldown-Menü mit einer Auflistung:
+
+![node-settings-region](images/node-settings-region.png "Einstellbare Regionen")  
+
+**Fig. 4:** Pulldown-Menü mit einstellbaren Regionen/Städte
+
+
+
+### Node-Eingang
+Der Node wird über jede Eingangs-Message `msg` mit beliebigem Inhalt getriggert.
+
+
+### Node-Ausgang
+Der Node gibt eine `msg` an seinem Ausgang aus, sobald er über den Eingang getriggert wird.
+
+#### Ausgangselemente
+Die Elemente der `msg` sind:
+* `payload` - Maximale Warnstufe aktueller Warnungen (*level* im Array *warnings*)
+* `count` -  Anzahl der Warnungen (im Array *warnings*)
+* `events` - Kommagetrennte Aufzählungen der Warnungskategorien (z.B. "BÖEN","STARKWIND","NEBEL")
 * `warnings` - Array mit den detaillierten Daten der Warnungen
-* `html` - HTML zur Anzeige im Dashboard
+* `html` - HTML-Output zur Anzeige im Dashboard
+
+
+#### Ausgangsarray *warnings*
+Das Array beinhaltet alle Warnungen, die für die selektierte Region/Stadt aktiv sind. Oftmals ist dies maximal eine einzige Warnung, in diesem Falle enthält das Array nur ein Element (array[1] wie i Fig. 5 dargestellt).
+Das Array besitzt die folgende Elementstruktur:
+
+![example-output-message](images/DWD-Beispiel-msg_warnings-Struktur.png "Struktur der Ausgangsmessage")  
 
+**Fig. 5:** Beispielinhalt des Ausgangsarray *warnings*
 
-#### Dashboard Template
+Zu den Details der Strukturelemente siehe auch unten die ***Informationen zu den DWD-Wetterdaten***.
+
+Hervorzuheben sind folgende Strukturelemente:
+- ***type***: Dies beinhaltet die Warnungskategorie (siehe auch Element *typeName* und *event*). Inhalte sind:
+  - 0: Gewitter
+  - 1: Sturm
+  - 2: Regen
+  - 3: Schnee
+  - 4: Nebel
+  - 5: Frost
+  - 6: Glatteis
+  - 7: Tauwetter
+  - 8: Hitze
+  - 9: UV-Strahlung
+  - 10: Warnungen der Küstenbereiche
+  - 11: Warnungen der Binnenseen
+- ***start*** bzw. ***end***: Start- und Endezeit der Wetterwarnung
+- ***level***: Dies ist die Warnstufe der Warnung
+- ***instructions***: Hinweise zum eigenen Verhalten gegenüber der Wetterwarnung
+- ***description***: Dies ist die textuelle Darstellung der Inhalte von *type* bzw. *typeName* bzw. *event* in Kombination mit *level*
+- ***icon*** und ***frame***: Verlinkung auf Images, die kombiniert ein Warnungssymbol ergeben
+
+
+Ein Beispiel für die Kombination aus Icon (Wind) und Warnstufe (Warnstufe 1, gelber Rand) sieht wie folgt aus:  
+![example-icon](images/DWD-Beispiel-WindIcon.png "Wind-Icon")  
+
+**Fig. 6:** Beispiel eines Warnungs-Icons (Quelle: Deutscher Wetterdienst DWD)
+
+
+#### Ausgangsdatenelement *html*
+Dieses Element gibt einen HTML-String mit einigen Warnungsdaten aus. Dieser String wird u.a. vom Wetterwarnungs-Dashboard-Template verwendet.
+
+Das Ausgabeformat von *html* sieht wie folgt aus:
 
 ```html
-<style>
-    .dwd-icon-container {
-        display: inline-block;    
-    }
-    .dwd-event {
-        display: inline-block;
-        vertical-align: 60px;
-        font-weight: bold;
-        padding-left: 20px;
-    }
-    .dwd-icon, .dwd-icon-frame {
-        position: absolute;
-    }
-    .dwd-icon-container, .dwd-icon, .dwd-icon-frame {
-        width: 100px;
-        height: 100px;
-    }
-    .dwd-time {
-        color: grey;
-    }
-
-</style>
-<div ng-bind-html="msg.html"></div>
+<div class="dwd-warning-container">
+    <div class="dwd-icon-container">
+        <img class="dwd-icon" src="${warnings[i].icon}">   
+        <img class="dwd-icon-frame" src="${warnings[i].frame}">
+    </div>
+    <div class="dwd-event">${warning.event}</div>
+    <div class="dwd-time">${warning.time}</div>
+    <div class="dwd-description">${warning.description}</div>
+    <div class="dwd-instruction">${warning.instruction}</div>
+</div>                             
 ```
 
+Diese HTML-Code-Generierung befindet sich in *dwd.js* und kann ggfs. persönlichen Bedürfnissen angepasst werden. In solch einem Falle muss Node-RED neu gestartet werden, um die Änderungen wirksam werden zu lassen.  
+Zu beachten ist jedoch, dass Änderungen ggfs. auch zum Inhalt des *Wetterwarnungs-Dashboard-Template* passen müssen, wenn dieses verwendet werden soll.
+
+
+### Wetterwarnungs-Dashboard-Template
+Das *Wetterwarnungs-Dashboard-Template* wird in einem *template*-Node des Node-RED Dashboards verwendet. Hierfür ist die Bibliothek ***node-red-dashboard*** nötig.   
+Das Template nutzt die Ausgangsdaten des Nodes inclusive eines Icons und eines Rahmens von der DWD-Website und generiert die Wettermeldung.
+
+Zur Nutzung des Templates wird einfach der folgende Code-Snippet in einen *template*-Node kopiert (z.B. via copy&paste) und das Template dann einer Dashboard UI Gruppe hinzugefügt.  
+Hiermit ergibt sich eine Dashboard-Ausgabe wie folgt:
+
+![dashboard-template](images/DWD-Beispiel-Wetterwarnung-Dashboard.png "Dashboard-Template")  
+**Fig. 7:** Beispiel im Dashboard unter Verwendung des Wetterwarnungs-Dashboard-Templates
+
+
+<details>
+  <summary>Klicken, um den Code Snippet für das Dashboard Template zu expandieren</summary>
+
+  ```html
+  <style>
+      .dwd-icon-container {
+          display: inline-block;    
+      }
+      .dwd-event {
+          display: inline-block;
+          vertical-align: 60px;
+          font-weight: bold;
+          padding-left: 20px;
+      }
+      .dwd-icon, .dwd-icon-frame {
+          position: absolute;
+      }
+      .dwd-icon-container, .dwd-icon, .dwd-icon-frame {
+          width: 100px;
+          height: 100px;
+      }
+      .dwd-time {
+          color: grey;
+      }
+
+  </style>
+  <div ng-bind-html="msg.html"></div>
+  ```
+</details>
+
+
+
+
+## Beispiele
+
+***
+**Hinweis:** Die Beispiel-Flows liegen im Unterverzeichnis 'examples'. In Node-RED können sie einfach importiert werden, indem sie über das Menü der Importfunktion und dort im vertikalen Tab-Reiter *Examples* selektiert werden können.   
+Alle Beispiel-Flows können somit im 'example'-Verzeichnis der jeweiligen Bibliothek gefunden werden.
+***
+
+### Einfaches Beispiel
+Dieses Beispiel zeigt wie die Ausgangsdaten `msg.payload` zu interpretieren sind.
+
+![basic-example](images/DWD-Beispiel-basic-example-flow.png "Einfaches Beispiel")  
+[**basic flow**](examples/flow-basic.json)  
+**Fig. 8:** Flow des einfachen Beispiels
+
+
+### Beispiel mit Auswertung der Ausgangsdatenelemente
+Dieses Beispiel gibt die einzelnen Elemente der Ausgangs-`msg` aus:
+
+![outputdata-example](images/DWD-Beispiel-outputdata-example-flow.png "Beispiel mit mehreren Ausgangsdatenelementen")  
+[**output data flow**](examples/flow-outputdata.json)  
+**Fig. 9:** Flow mit mehreren Ausgangsdatenelementen
+
+
+### Beispiel mit dem Dashboard-Template
+Der folgende Flow zeigt die Verwendung des Wetterwarnungs-Dashboard-Templates:
+
+![dashboard-template-example](images/DWD-Beispiel-dashboard-template-example-flow.png "Beispiel mit dem Wetterwarnungs-Dashboard-Template")  
+[**dashboard template flow**](examples/flow-dashboard-template.json)  
+**Fig. 10:** Flow mit dem Wetterwarnungs-Dashboard-Template
+
+
+
+## Informationen zu den DWD-Wetterdaten
+
+[Warnkarte des DWD](https://www.dwd.de/DE/wetter/warnungen_landkreise/warnWetter_node.html)
+
+#### Warnkriterien
+https://www.dwd.de/DE/wetter/warnungen_aktuell/kriterien/warnkriterien.html  
+https://www.dwd.de/DE/wetter/warnungen_aktuell/kriterien/uv_hitze_warnungen.html  
+https://www.dwd.de/DE/wetter/warnungen_aktuell/kriterien/seewarnungen.html  
+
+
+#### Warnstufen und farbliche Kennzeichnung
+Details zu den 4 Warnstufen und deren farblicher Darstellung findet sich dort:   
+https://www.dwd.de/DE/wetter/warnungen_aktuell/kriterien/warnstufen.html
+
+
+
+
+### Erweiterungsmöglichkeiten der angezeigten Orte
+Alle vom DWD bereitgestellten Orte sind in dieser Tabelle dargestellt:  
+https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv
+
+Es sind jedoch nicht alle in dieser Tabelle vorhandenen Orte im Node-Konfigurations-Dialog auswählbar.  
+Der Grund dafür ist, dass diese Liste ständigen Änderungen unterworfen ist.
+
+Es kann jedoch die .html-Datei recht einfach um eigene benötigte Orte erweitert werden. Dazu ist der entsprechende, neue Ort mit seiner WARNCELLID eingetragen und Node-RED neu gestartet werden. Danach ist der hinzugefügte Ort in der Auswahlliste enthalten.  
+Die .html-Datei befindet sich im Unterverzeichnis der Bibliothek *node-red-contrib-dwd*. Zur Änderung sind meist root-Rechte notwendig.
+
+In der folgenden Fig. 11 ist dargestellt, wie beispielsweise der Ort Rheda-Wiedenbrück in die Tabelle mit aufgenommen wurde:
+
+![add-region](images/add-region.png "Erweiterung der Liste der Regionen/Städte")  
+**Fig. 11:** Erweiterung der Liste der Regionen/Städte (Beispiel Rheda-Wiedenbrück)
+
+
+## Credits
+- **Sebastian Raff**: Programming, maintaining, releasing
+- **StephanStS**: Documentation, node help
+
 
 ## License
 

examples/DWD-Beispiel-JSON-format.md

@@ -0,0 +1,31 @@
+Beispiel für Ausgabe des DWD (JSON-Format)
+
+
+```json
+warnWetter.loadWarnings
+({
+  "time":1599726250000,
+  "warnings":
+    {"501000008":
+      [{
+        "regionName":"Östlich Rügen",
+        "end":null,
+        "start":1599725700000,
+        "type":1,
+        "state":"Schleswig-Holstein",
+        "level":2,
+        "description":"Böen von 7 Beaufort aus West bis Nordwest.",
+        "event":"BÖEN",
+        "headline":"Amtliche Warnung des Seewetterdienstes Hamburg vor BÖEN",
+        "instruction":"",
+        "stateShort":"SH",
+        "altitudeStart":null,
+        "altitudeEnd":null
+      }]
+    },
+
+    "vorabInformation":{},
+    "copyright":"Copyright Deutscher Wetterdienst"
+
+});
+```

examples/flow-basic.json

@@ -0,0 +1 @@
+[{"id":"1f024d9.d120cb2","type":"inject","z":"6ef2b186.f1f8c","name":"","props":[{"p":"payload"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"str","x":190,"y":1620,"wires":[["7937eea9.33a89"]]},{"id":"7937eea9.33a89","type":"dwd","z":"6ef2b186.f1f8c","region":"109377000 Kreis Tirschenreuth (TIR)","name":"","gewitter":true,"sturm":true,"regen":true,"schnee":true,"nebel":true,"frost":true,"glatteis":true,"tauwetter":false,"hitze":true,"uv":true,"kueste":false,"binnensee":false,"x":350,"y":1620,"wires":[["47e899a.8d612e8"]]},{"id":"47e899a.8d612e8","type":"debug","z":"6ef2b186.f1f8c","name":"Max. Warnstufe","active":true,"tosidebar":false,"console":false,"tostatus":true,"complete":"payload","targetType":"msg","statusVal":"payload.windspeed","statusType":"auto","x":550,"y":1620,"wires":[]}]

examples/flow-dashboard-template.json

@@ -0,0 +1 @@
+[{"id":"febee273.defce","type":"ui_template","z":"6ef2b186.f1f8c","group":"f87cc085.bd171","name":"","order":3,"width":"6","height":"4","format":"<style>\n    .dwd-icon-container {\n        display: inline-block;    \n    }\n    .dwd-event {\n        display: inline-block;\n        vertical-align: 60px;\n        font-weight: bold;\n        padding-left: 20px;\n    }\n    .dwd-icon, .dwd-icon-frame {\n        position: absolute;\n    }\n    .dwd-icon-container, .dwd-icon, .dwd-icon-frame {\n        width: 100px;\n        height: 100px;\n    }\n    .dwd-time {\n        color: grey;\n    }\n\n</style>\n<div ng-bind-html=\"msg.html\"></div>\n","storeOutMessages":true,"fwdInMessages":true,"resendOnRefresh":true,"templateScope":"local","x":530,"y":2140,"wires":[[]]},{"id":"92586727.97f41","type":"dwd","z":"6ef2b186.f1f8c","region":"109377000 Kreis Tirschenreuth (TIR)","name":"","gewitter":true,"sturm":true,"regen":true,"schnee":true,"nebel":true,"frost":true,"glatteis":true,"tauwetter":false,"hitze":true,"uv":true,"kueste":false,"binnensee":false,"x":350,"y":2140,"wires":[["febee273.defce"]]},{"id":"89a0c98a.0f41b8","type":"comment","z":"6ef2b186.f1f8c","name":"109377000 Kreis Tirschenreuth (TIR)","info":"","x":280,"y":2220,"wires":[]},{"id":"3bf4be59.ea2762","type":"inject","z":"6ef2b186.f1f8c","name":"","props":[{"p":"payload"}],"repeat":"900","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"str","x":180,"y":2140,"wires":[["92586727.97f41"]]},{"id":"f87cc085.bd171","type":"ui_group","z":"","name":"DWD Wetterwarnungen","tab":"ad63674.88ef398","order":1,"disp":true,"width":"6","collapse":false},{"id":"ad63674.88ef398","type":"ui_tab","z":"","name":"DWD","icon":"dashboard","disabled":false,"hidden":false}]

examples/flow-outputdata.json

@@ -0,0 +1 @@
+[{"id":"ed88003.5c3188","type":"dwd","z":"6ef2b186.f1f8c","region":"105370000 Kreis Heinsberg (HS)","name":"","gewitter":true,"sturm":true,"regen":true,"schnee":true,"nebel":true,"frost":true,"glatteis":true,"tauwetter":false,"hitze":true,"uv":true,"kueste":false,"binnensee":false,"x":350,"y":1820,"wires":[["50d5d09b.9d9098","42ae8f2a.159e1","1e51f615.9516f2","856fd239.13b12","6f842317.f3e154"]]},{"id":"50d5d09b.9d9098","type":"debug","z":"6ef2b186.f1f8c","name":"","active":false,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","statusVal":"","statusType":"auto","x":610,"y":1780,"wires":[]},{"id":"42ae8f2a.159e1","type":"debug","z":"6ef2b186.f1f8c","name":"Anzahl Warnungen","active":true,"tosidebar":false,"console":false,"tostatus":true,"complete":"count","targetType":"msg","statusVal":"payload.windspeed","statusType":"auto","x":660,"y":1820,"wires":[]},{"id":"1e51f615.9516f2","type":"debug","z":"6ef2b186.f1f8c","name":"Max. Warnstufe","active":true,"tosidebar":false,"console":false,"tostatus":true,"complete":"payload","targetType":"msg","statusVal":"payload.windspeed","statusType":"auto","x":650,"y":1880,"wires":[]},{"id":"856fd239.13b12","type":"debug","z":"6ef2b186.f1f8c","name":"Warnkategorien","active":true,"tosidebar":false,"console":false,"tostatus":true,"complete":"events","targetType":"msg","statusVal":"payload.windspeed","statusType":"auto","x":650,"y":1940,"wires":[]},{"id":"6f842317.f3e154","type":"debug","z":"6ef2b186.f1f8c","name":"Warnungen","active":true,"tosidebar":false,"console":false,"tostatus":true,"complete":"warnings","targetType":"msg","statusVal":"payload.windspeed","statusType":"auto","x":630,"y":2000,"wires":[]},{"id":"fa07d49b.c2c418","type":"comment","z":"6ef2b186.f1f8c","name":"105370000 Kreis Heinsberg (HS)","info":"","x":290,"y":1900,"wires":[]},{"id":"fd73a21c.baf988","type":"inject","z":"6ef2b186.f1f8c","name":"","props":[{"p":"payload"}],"repeat":"900","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"str","x":200,"y":1820,"wires":[["ed88003.5c3188"]]}]