# DwdUnwetter Binding

Binding zur Abfrage von aktuellen Unwetterwarnungen des Deutschen Wetterdienstes via [DWD Geoserver](https://maps.dwd.de/geoserver/web/)

## Unterstütztes Thing

Das Binding unterstützt genau ein Thing - Unwetterwarnungen.
Ein Thing stellt dabei eine oder mehrere Warnungen für eine Gemeinde bereit.


## Thing Konfiguration

| Property     | Default | Required | Description                                                                                                                                                                                                                                                                       |
|--------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| cellId       | -       | Yes      | ID der abzufragenden Zelle. Siehe [cap_warncellids_csv.csv](https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv "cap_warncellids_csv.csv") Es kann auch mittels % eine Gesamtmenge abgefragt werden, z.B. 8111% alle Gemeinden die mit 8111 anfangen |
| refresh      | 30      | No       | Abfrageintervall in Minuten. Minimum 15 Minuten.                                                                                                                                                                                                                                  |
| warningCount | 1       | No       | Anzahl der Warnungen, die als Channels bereitgestellt werden sollen                                                                                                                                                                                                               |
Wählt man die Cell-ID mittels des %-Operators zu groß, so kann es passieren, das gar keine Warnungen kommen.
Das ist immer Fall, wenn die zurückgelieferte XML-Datei des DWD zu groß ist, dass sie nicht intern gebuffered werden kann.
Dies ist bei ca. 300+ Warnungen der Fall.


## Channels

Für jede bereitgestellte Warnung werden mehrere Channels bereitgestellt. 
Die Channels sind jeweils durchnummeriert, Channels die mit 1 enden sind für die erste Warnung, Channels die mit 2 enden für die zweite Warnung usw. 
Die vom DWD gelieferten Warnungen werden dabei nach Severity (Warnstufe) sortiert und innerhalb der Warnstufe nach Beginndatum. 
Dadurch ist sichergestellt, dass in den Channels für die erste Warnung (...1) immer die Warnung mit der höchsten Warnstufe steht. 
Werden mehr Warnungen vom DWD geliefert, als an Channels konfiguriert ist, werden dadurch die Warnungen mit der niedrigsten Warnstufe verworfen.

| Channel      | Type            | Beschreibung                                                                                           |
|--------------|-----------------|--------------------------------------------------------------------------------------------------------|
| warningN     | Switch          | Schalter, der auf ON steht, wenn eine Warnung vorliegt, OFF sonst.                                     |
| UpdatedN     | Trigger Channel | Sendet das Event "NEW", wenn diese Warnung das erste mal gesendet wird.                                |
| severityN    | String          | Warnstufe, von niedrig nach hoch: Minor, Moderate, Severe, Extreme.                                    |
| headlineN    | String          | Überschrift der Warnung, z.B. Amtliche WARNUNG vor STURMBÖEN                                           |
| descriptionN | String          | Klartext Beschreibung der Warnung.                                                                     |
| eventN       | String          | Art der Warnung, z.B. STURMBÖEN                                                                        |
| effectiveN   | DateTime        | Zeitpunkt, an dem die Warnung ausgegeben wurde.                                                        |
| onsetN       | DateTime        | Zeitpunkt, von dem an die Warnung gilt.                                                                |
| effectiveN   | DateTime        | Zeitpunkt, bis zu dem die Warnung gilt.                                                                |
| altitudeN    | Number:Length   | Höhe über dem Meerespiegel, ab dem die Warnung gilt.                                                   |
| ceilingN     | Number:Length   | Höhe über dem Meerespiegel, bis zu dem die Warnung gilt.                                               |
| urgencyN     | String          | Zeitrahmen der Meldung, Mögliche Werte sind Future (Vorabinformation) und Immediate (Konkrete Warnung) |
| instructionN | String          | Zusatztext zur Warnung (Instruktionen und Sicherheitshinweise)                                         |

Sämtliche Channels sind ReadOnly!  

Der Channel _warningN_ dient hauptsächlich dazu, um z.B. in Sitemaps dynamisch Warnungen ein- oder auszublenden, bzw. um in Regeln zu prüfen, ob überhaupt eine Warnung vorliegt. 
Er ist nicht geeignet um auf das Erscheinen einer Warnung zu prüfen. 
Denn wenn eine Warnung durch eine neue Warnung ersetzt wird, bleibt der Zustand ON, es gibt keinen Zustandswechsel. 
Um auf das erscheinen einer Warnung zu prüfen, sollte der Trigger-Channel _updatedN_ genutzt werden. 
Der feuert immer dann, wenn eine Warnung das erste mal gesendet wird. 
Das heißt, der feuert auch dann, wenn eine Warnung durch eine neue Warnung ersetzt wird. 

Weitere Erläuterungen der Bedeutungen finden sich in der Dokumentation des DWDs unter [CAP DWD Profile 1.2](https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_dwd_profile_de_pdf.pdf?__blob=publicationFile&v=7)  

## Vollständiges Beispiel

demo.things:

```
dwdunwetter:dwdwarnings:koeln "Warnungen Köln" [ cellId="105315000", refresh=15, warningCount=1 ]
```

demo.items:

```
Switch WarnungKoeln "Warnung vorhanden" { channel="dwdunwetter:dwdwarnings:koeln:warning1" }
String WarnungKoelnServerity "Warnstufe [%s]" { channel="dwdunwetter:dwdwarnings:koeln:severity1" }
String WarnungKoelnBeschreibung "[%s]" { channel="dwdunwetter:dwdwarnings:koeln:description1" }
String WarnungKoelnAusgabedatum "Ausgeben am [%s]" { channel="dwdunwetter:dwdwarnings:koeln:effective1" }
String WarnungKoelnGueltigAb "Warnung gültig ab [%s]" { channel="dwdunwetter:dwdwarnings:koeln:onset1" }
String WarnungKoelnGueltigBis "Warnung gültig bis [%s]" { channel="dwdunwetter:dwdwarnings:koeln:expires1" }
String WarnungKoelnTyp "Warnungstyp [%s]" { channel="dwdunwetter:dwdwarnings:koeln:event1" }
String WarnungKoelnTitel "[%s]" { channel="dwdunwetter:dwdwarnings:koeln:headline1" }
String WarnungKoelnHoeheAb "Höhe ab [%d m]" { channel="dwdunwetter:dwdwarnings:koeln:altitude1" }
String WarnungKoelnHoeheBis "Höhe bis [%d m]" { channel="dwdunwetter:dwdwarnings:koeln:ceiling1" }
String WarningCologneUrgency "[%s]" { channel="dwdunwetter:dwdwarnings:cologne:urgency1" }
String WarningCologneInstruction "Zusatzinformationen: [%s]" { channel="dwdunwetter:dwdwarnings:cologne:instruction1" }
```

demo.sitemap:

```
sitemap demo label="Main Menu"
{
    Frame {
        Text item=WarnungKoelnTitel visibility=[WarnungKoeln==ON]
        Text item=WarnungKoelnBeschreibung visibility=[WarnungKoeln==ON]
    }
}
```

demo.rules

```
rule "Neue Warnung"
when
     Channel 'dwdunwetter:dwdwarnings:koeln:updated1' triggered NEW
then
   // Neue Warnung, Informiere alle Bewohner
end 

```