From 33ce468dab6e7b2bef81cbba2530f37a02f6300c Mon Sep 17 00:00:00 2001 From: Florian Hotze Date: Mon, 25 Apr 2022 14:34:05 +0200 Subject: [PATCH] [dwdunwetter] Update docs to clarify CellID selection (#12588) * [dwdunwetter] Improve docs for CellID * [dwdunwetter] Update Thing config for README changes * [dwdunwetter] Update German README Signed-off-by: Florian Hotze --- .../org.openhab.binding.dwdunwetter/README.md | 69 ++++++++++--------- .../README_de.md | 68 +++++++++++++++--- .../OH-INF/i18n/dwdunwetter.properties | 2 +- .../resources/OH-INF/thing/thing-types.xml | 26 ++++--- 4 files changed, 113 insertions(+), 52 deletions(-) diff --git a/bundles/org.openhab.binding.dwdunwetter/README.md b/bundles/org.openhab.binding.dwdunwetter/README.md index 75e0f0e5cc9..2ff90d8fe1f 100644 --- a/bundles/org.openhab.binding.dwdunwetter/README.md +++ b/bundles/org.openhab.binding.dwdunwetter/README.md @@ -13,11 +13,22 @@ Each Thing provides one or more warnings for a city. ## Thing Configuration -| Property | Default | Required | Description | -|--------------|---------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| cellId | - | Yes | ID of the area to retrieve weather warnings. See [this list](https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv) of valid IDs. Using the percent sign (%) as a wildcard, it is possible to query multiple cells. For example, the value `8111%` retrieves all cell IDs that start with `8111`. | -| refresh | 30 | No | Time between API requests in minutes. Minimum 15 minutes. | -| warningCount | 1 | No | Number of warnings to provide. | +| Property | Default | Required | Description | +|--------------|---------|----------|--------------------------------------------------------------------------------------------------------------------------------------------| +| cellId | - | Yes | ID of the area to retrieve weather warnings, only IDs starting with an 8 (exception for Berlin: 7) are supported. See [Cell ID](#cell-id). | +| refresh | 30 | No | Time between API requests in minutes. Minimum 15 minutes. | +| warningCount | 1 | No | Number of warnings to provide. | + + +### Cell ID + +Use [this list](https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv) of valid IDs, please notice that **only IDs starting with an eight (8) and nine digits are supported** by this binding. +Exeception for Berlin, where the ID of the city's districts are used. Those start with a seven (7). + +Using the percent sign (%) as a wildcard, it is possible to query multiple cells. +For example, the value `8111%` retrieves all cell IDs that start with `8111`. + +More explanation (in German) for CellID can be found on page 10-13 of [PDF: DWD-Geoserver: Nutzung von WMS-Diensten für eigene Websites](https://www.dwd.de/DE/wetter/warnungen_aktuell/objekt_einbindung/einbindung_karten_geodienste.pdf?__blob=publicationFile&v=14). The binding will deliver no warnings if the number of retrieved warnings for one Thing is too big. This can only happen if you select too many cell IDs (more than about 300) with the percent wildcard. @@ -25,7 +36,7 @@ This can only happen if you select too many cell IDs (more than about 300) with Example: ``` -dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="105315000", refresh=15, warningCount=1 ] +dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="805315000", refresh=15, warningCount=1 ] ``` @@ -37,21 +48,21 @@ The warnings will be sorted first by `Severity` and then by the `Valid From` dat This ensures that the channels for the first warning will always be the highest Severity. If the API returns more warnings than the configured number in the Thing, the warnings with the lowest Severity will be dropped. -| Channel | Type | Description | -|--------------|-----------------|----------------------------------------------------------------------------------| -| warningN | Switch | ON if a warning is present | -| UpdatedN | Trigger Channel | Triggers NEW when a warning is sent the first time | -| severityN | String | Severity of the warning. Possible values are Minor, Moderate, Severe, and Extreme| -| headlineN | String | Headline of the warning (e.g. "Amtliche Warnung vor FROST") | -| descriptionN | String | Textual description of the warning | -| eventN | String | Type of the warning (e.g. FROST) | -| effectiveN | DateTime | Issued Date and Time | -| onsetN | DateTime | Start Date and Time for which the warning is valid | -| expiresN | DateTime | End Date and Time for which the warning is valid | -| altitudeN | Number:Length | Lower Height above sea level for which the warning is valid | -| ceilingN | Number:Length | Upper Height above sea level for which the warning is valid | -| urgencyN | String | Urgency of the warning. Possible values are Future and Immediate | -| instructionN | String | Additional instructions and safety information | +| Channel | Type | Description | +|--------------|-----------------|-----------------------------------------------------------------------------------| +| warningN | Switch | ON if a warning is present | +| UpdatedN | Trigger Channel | Triggers NEW when a warning is sent the first time | +| severityN | String | Severity of the warning. Possible values are Minor, Moderate, Severe, and Extreme | +| headlineN | String | Headline of the warning (e.g. "Amtliche Warnung vor FROST") | +| descriptionN | String | Textual description of the warning | +| eventN | String | Type of the warning (e.g. FROST) | +| effectiveN | DateTime | Issued Date and Time | +| onsetN | DateTime | Start Date and Time for which the warning is valid | +| expiresN | DateTime | End Date and Time for which the warning is valid | +| altitudeN | Number:Length | Lower Height above sea level for which the warning is valid | +| ceilingN | Number:Length | Upper Height above sea level for which the warning is valid | +| urgencyN | String | Urgency of the warning. Possible values are Future and Immediate | +| instructionN | String | Additional instructions and safety information | All channels are readonly. @@ -63,14 +74,15 @@ For rules that need to fire if a new warning occurs, there is the trigger channe That trigger channel fires an event whenever a warning is sent for the first time. It also triggers if a warning is replaced by another. -More explanations about the specific values of the channels can be found in the PDF documentation of the DWD at: [CAP DWD Profile 1.2](https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_dwd_profile_en_pdf_1_12.html) +More explanations about the specific values of the channels can be found in the PDF documentation of the DWD at: [CAP DWD Profile 1.2](https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_dwd_profile_en_pdf_1_12.html). +Please note that this binding only supports *Gemeinden* (COMMUNE) for *WarncellID*. ## Full Example dwdunwetter.things: ``` -dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="105315000", refresh=15, warningCount=1 ] +dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="805315000", refresh=15, warningCount=1 ] ``` e.g. @@ -78,7 +90,7 @@ e.g. to get two warnings like in the item example, set `warningCount=2` in things file ``` -dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="105315000", refresh=15, warningCount=2 +dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="805315000", refresh=15, warningCount=2 ] ``` dwdunwetter.items: @@ -107,8 +119,7 @@ DateTime WarningCologneAusgabedatum_2 "Issued at [%s]" demo.sitemap: ``` -sitemap demo label="Main Menu" -{ +sitemap demo label="Main Menu" { Frame { Text item=WarningCologneTitel visibility=[WarningCologne==ON] Text item=WarningCologneBeschreibung visibility=[WarningCologne==ON] @@ -157,8 +168,4 @@ NULL=undefiniert UNDEF=undefiniert ``` -If you're unsure if the binding is working correctly, you can access the json directly with curl or any browser [json](https://www.dwd.de/DWD/warnungen/warnapp/json/warnings.json) and have a look for an active ID to test your setup. - -``` -curl https://www.dwd.de/DWD/warnungen/warnapp/json/warnings.json | less -``` +If you're unsure if the binding is working correctly, you can access the data directly by visiting https://maps.dwd.de/geoserver/dwd/ows?service=WFS&version=2.0.0&request=GetFeature&typeName=dwd:Warnungen_Gemeinden&CQL_FILTER=WARNCELLID%20LIKE%20%27CELL_ID%27 (replace `CELL_ID` with your Cell ID), allowing the download and opening the downloaded `.xml` file. diff --git a/bundles/org.openhab.binding.dwdunwetter/README_de.md b/bundles/org.openhab.binding.dwdunwetter/README_de.md index 0da5fefd755..6d86f919109 100644 --- a/bundles/org.openhab.binding.dwdunwetter/README_de.md +++ b/bundles/org.openhab.binding.dwdunwetter/README_de.md @@ -1,6 +1,6 @@ -# DwdUnwetter Binding +# DWD Unwetter Binding -Binding zur Abfrage von aktuellen Unwetterwarnungen des Deutschen Wetterdienstes via [DWD Geoserver](https://maps.dwd.de/geoserver/web/) +Binding zur Abfrage von aktuellen Unwetterwarnungen des Deutschen Wetterdienstes via [DWD Geoserver](https://maps.dwd.de/geoserver/web/). ## Unterstütztes Thing @@ -10,15 +10,31 @@ 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 | +| Property | Standard | Erforderlich | Beschreibung | +|--------------|----------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| cellId | - | Ja | 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"), nur IDs die mit einer 8 (Ausnahme für Berlin: 7) beginnen werden unterstützt. Es kann auch mittels % eine Gesamtmenge abgefragt werden, z.B. 8111% alle Gemeinden die mit 8111 anfangen. | +| refresh | 30 | Nein | Abfrageintervall in Minuten. Minimum 15 Minuten. | +| warningCount | 1 | Nein | Anzahl der Warnungen, die als Channels bereitgestellt werden sollen | + +### Cell ID + +Verwende [diese Liste](https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv) für gültige IDs, bitte bedenke dass **nur IDs die mit einer "8" beginnen und neun Ziffern haben unterstützt werden**. +Ausnahme für Berlin, wo die ID der Stadtbezirke genutzt wird. Diese beginnt mit "7". + +Unter Verwendung des Prozent-Zeichens (%) als wildcard, kann man mehrere Zellen abfragen. +Zum Beispiel werden mit dem Wert `8111%` alle Zellen abgefragt, die mit `8111` beginnen. + +Weitere Erläuterungen der CellID können auf Seite 10-13 von [PDF: DWD-Geoserver: Nutzung von WMS-Diensten für eigene Websites](https://www.dwd.de/DE/wetter/warnungen_aktuell/objekt_einbindung/einbindung_karten_geodienste.pdf?__blob=publicationFile&v=14) gefunden werden. + 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. +Beispiel: + +``` +dwdunwetter:dwdwarnings:koeln "Warnungen Köln" [ cellId="805315000", refresh=15, warningCount=1 ] +``` ## Channels @@ -53,14 +69,15 @@ Um auf das erscheinen einer Warnung zu prüfen, sollte der Trigger-Channel _upda 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) +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). +Bitte bedenke, dass dieses Binding nur *Gemeinden* unterstützt. ## Vollständiges Beispiel demo.things: ``` -dwdunwetter:dwdwarnings:koeln "Warnungen Köln" [ cellId="105315000", refresh=15, warningCount=1 ] +dwdunwetter:dwdwarnings:koeln "Warnungen Köln" [ cellId="805315000", refresh=15, warningCount=1 ] ``` demo.items: @@ -83,8 +100,7 @@ String WarningCologneInstruction "Zusatzinformationen: [%s]" { channel="dwdunwet demo.sitemap: ``` -sitemap demo label="Main Menu" -{ +sitemap demo label="Main Menu" { Frame { Text item=WarnungKoelnTitel visibility=[WarnungKoeln==ON] Text item=WarnungKoelnBeschreibung visibility=[WarnungKoeln==ON] @@ -103,3 +119,33 @@ then end ``` +dwdunwetter_de.map + +``` +ON=aktiv +OFF=inaktiv +NULL=undefiniert +UNDEF=undefiniert +``` + +dwdunwetter_severity_de.map + +``` +Minor=Wetterwarnung +Moderate=Markante Wetterwarnung +Severe=Unwetterwarnung +Extreme=Extreme Unwetterwarnung +NULL=undefiniert +UNDEF=undefiniert +``` + +dwdunwetter_urgency_de.map + +``` +Immediate=Warnung +Future=Vorabinformation +NULL=undefiniert +UNDEF=undefiniert +``` + +Wenn du unsicher bist, ob das Binding korrekt funktioniert, kannst du die Wetterdaten direkt mit deinem Browser abrufen, indem du https://maps.dwd.de/geoserver/dwd/ows?service=WFS&version=2.0.0&request=GetFeature&typeName=dwd:Warnungen_Gemeinden&CQL_FILTER=WARNCELLID%20LIKE%20%27CELL_ID%27 (ersetze `CELL_ID` mit deiner Cell ID) besuchst, den Datei Download zulässt und die heruntergeladene `.xml` Datei öffnest. diff --git a/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/i18n/dwdunwetter.properties b/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/i18n/dwdunwetter.properties index fae0439068d..955db3e14fe 100644 --- a/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/i18n/dwdunwetter.properties +++ b/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/i18n/dwdunwetter.properties @@ -11,7 +11,7 @@ thing-type.dwdunwetter.dwdwarnings.description = Weather Warnings for an area. # thing types config thing-type.config.dwdunwetter.dwdwarnings.cellId.label = Cell-ID -thing-type.config.dwdunwetter.dwdwarnings.cellId.description = ID of the area to retrieve weather warnings. For a list of valid IDs look at https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv. With the % sign at the end it is possible to query multiple cells at once. For example with 8111% are cells retrieved that starts with 8111. +thing-type.config.dwdunwetter.dwdwarnings.cellId.description = ID of the area to retrieve weather warnings. For a list of valid IDs look at https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv, only IDs starting with an 8 (exception for Berlin: 7) are supported. With the % sign at the end it is possible to query multiple cells at once. For example with 8111% are cells retrieved that starts with 8111. thing-type.config.dwdunwetter.dwdwarnings.refresh.label = Refresh in Minutes thing-type.config.dwdunwetter.dwdwarnings.refresh.description = Time between to API requests in minutes. Minimum 15 minutes. thing-type.config.dwdunwetter.dwdwarnings.warningCount.label = Number of Provided Warnings diff --git a/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/thing/thing-types.xml b/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/thing/thing-types.xml index d454aa57c17..fc7dc3bc76a 100644 --- a/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/thing/thing-types.xml +++ b/bundles/org.openhab.binding.dwdunwetter/src/main/resources/OH-INF/thing/thing-types.xml @@ -13,9 +13,14 @@ - + ID of the area to retrieve weather warnings. + For a list of valid IDs look at + https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv, only + IDs starting with an 8 + (exception for Berlin: 7) are supported. + With the % sign at the end it is possible to query multiple cells at once. + For example with 8111% are cells retrieved + that starts with 8111. 30 @@ -25,9 +30,11 @@ With the % sign at the end it is possible to query multiple cells at once. For e 1 - + Number of warnings to provide. + For each warning there will multiple channels. + The warnings are sorted by + severity first and begin second so the first warning is always the one with the highest + severity. @@ -42,9 +49,10 @@ The warnings are sorted by severity first and begin second so the first warning Switch - + ON if a warning is present, OFF else. + While be switched to ON only after all other channels - except the + trigger channel - are updated. + Will be switched to OFF before all other channels are updated to UNDEF.