[Documentation] Markdown improvements for bindings a to e (#13859)
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
committed by
GitHub
GitHub
parent
72efc1cfed
commit
caf71f72e6
@@ -4,13 +4,11 @@ Binding to retrieve the Weather Warnings of the "Deutscher Wetterdienstes" from
|
||||
The DWD provides weather warnings for Germany.
|
||||
Regions outside of Germany are not supported.
|
||||
|
||||
|
||||
## Supported Things
|
||||
|
||||
This binding supports one thing, the Weather Warning.
|
||||
Each Thing provides one or more warnings for a city.
|
||||
|
||||
|
||||
## Thing Configuration
|
||||
|
||||
| Property | Default | Required | Description |
|
||||
@@ -19,13 +17,12 @@ Each Thing provides one or more warnings for a city.
|
||||
| refresh | 30 | No | Time between API requests in minutes. Minimum 15 minutes. |
|
||||
| warningCount | 1 | No | Number of warnings to provide. |
|
||||
|
||||
|
||||
### Cell ID
|
||||
<!-- See page 10-13 (in German) of https://www.dwd.de/DE/wetter/warnungen_aktuell/objekt_einbindung/einbindung_karten_geodienste.pdf?__blob=publicationFile&v=14 for Cell ID documentation. -->
|
||||
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.
|
||||
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).
|
||||
@@ -35,11 +32,10 @@ This can only happen if you select too many cell IDs (more than about 300) with
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
```java
|
||||
dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="805315000", refresh=15, warningCount=1 ]
|
||||
```
|
||||
|
||||
|
||||
## Channels
|
||||
|
||||
The are multiple channels for every weather warning.
|
||||
@@ -47,7 +43,7 @@ The channels are numbered, with channel names ending in 1 for the first warning,
|
||||
The warnings will be sorted first by `Severity` and then by the `Valid From` date.
|
||||
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 |
|
||||
@@ -67,21 +63,21 @@ If the API returns more warnings than the configured number in the Thing, the wa
|
||||
All channels are readonly.
|
||||
|
||||
The main purpose of the channel `warningN` is to be used for controlling visibility in sitemaps.
|
||||
The channel can also be used in rules to check if there is a warning present.
|
||||
It should not be used for rules that need to fire if a new warning shows up.
|
||||
If a warning is replaced by another warning, that channel stays at ON, and there will be no state change.
|
||||
For rules that need to fire if a new warning occurs, there is the trigger channel `updatedN`.
|
||||
The channel can also be used in rules to check if there is a warning present.
|
||||
It should not be used for rules that need to fire if a new warning shows up.
|
||||
If a warning is replaced by another warning, that channel stays at ON, and there will be no state change.
|
||||
For rules that need to fire if a new warning occurs, there is the trigger channel `updatedN`.
|
||||
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).
|
||||
Please note that this binding only supports *Gemeinden* (COMMUNE) for *WarncellID*.
|
||||
Please note that this binding only supports _Gemeinden_ (COMMUNE) for _WarncellID_.
|
||||
|
||||
## Full Example
|
||||
|
||||
dwdunwetter.things:
|
||||
|
||||
```
|
||||
```java
|
||||
dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="805315000", refresh=15, warningCount=1 ]
|
||||
```
|
||||
|
||||
@@ -89,13 +85,13 @@ e.g.
|
||||
|
||||
to get two warnings like in the item example, set `warningCount=2` in things file
|
||||
|
||||
```
|
||||
```java
|
||||
dwdunwetter:dwdwarnings:cologne "Warnings Cologne" [ cellId="805315000", refresh=15, warningCount=2 ]
|
||||
```
|
||||
|
||||
dwdunwetter.items:
|
||||
|
||||
```
|
||||
```java
|
||||
Switch WarningCologne_1 "Weather warning [MAP(dwdunwetter_de.map):%s]" { channel="dwdunwetter:dwdwarnings:cologne:warning1" }
|
||||
String WarningCologneServerity_1 "Severity [MAP(dwdunwetter_severity_de.map):%s]" { channel="dwdunwetter:dwdwarnings:cologne:severity1" }
|
||||
String WarningCologneBeschreibung_1 "[%s]" { channel="dwdunwetter:dwdwarnings:cologne:description1" }
|
||||
@@ -118,7 +114,7 @@ DateTime WarningCologneAusgabedatum_2 "Issued at [%s]"
|
||||
|
||||
demo.sitemap:
|
||||
|
||||
```
|
||||
```perl
|
||||
sitemap demo label="Main Menu" {
|
||||
Frame {
|
||||
Text item=WarningCologneTitel visibility=[WarningCologne==ON]
|
||||
@@ -129,7 +125,7 @@ sitemap demo label="Main Menu" {
|
||||
|
||||
dwdunwetter.rules
|
||||
|
||||
```
|
||||
```java
|
||||
rule "New Warnung"
|
||||
when
|
||||
Channel 'dwdunwetter:dwdwarnings:cologne:updated1' triggered NEW
|
||||
@@ -141,7 +137,7 @@ end
|
||||
|
||||
dwdunwetter_de.map
|
||||
|
||||
```
|
||||
```text
|
||||
ON=aktiv
|
||||
OFF=inaktiv
|
||||
NULL=undefiniert
|
||||
@@ -150,7 +146,7 @@ UNDEF=undefiniert
|
||||
|
||||
dwdunwetter_severity_de.map
|
||||
|
||||
```
|
||||
```text
|
||||
Minor=Wetterwarnung
|
||||
Moderate=Markante Wetterwarnung
|
||||
Severe=Unwetterwarnung
|
||||
@@ -161,11 +157,11 @@ UNDEF=undefiniert
|
||||
|
||||
dwdunwetter_urgency_de.map
|
||||
|
||||
```
|
||||
```text
|
||||
Immediate=Warnung
|
||||
Future=Vorabinformation
|
||||
NULL=undefiniert
|
||||
UNDEF=undefiniert
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
@@ -7,7 +7,6 @@ Binding zur Abfrage von aktuellen Unwetterwarnungen des Deutschen Wetterdienstes
|
||||
Das Binding unterstützt genau ein Thing - Unwetterwarnungen.
|
||||
Ein Thing stellt dabei eine oder mehrere Warnungen für eine Gemeinde bereit.
|
||||
|
||||
|
||||
## Thing Konfiguration
|
||||
|
||||
| Property | Standard | Erforderlich | Beschreibung |
|
||||
@@ -32,16 +31,16 @@ Dies ist bei ca. 300+ Warnungen der Fall.
|
||||
|
||||
Beispiel:
|
||||
|
||||
```
|
||||
```java
|
||||
dwdunwetter:dwdwarnings:koeln "Warnungen Köln" [ cellId="805315000", refresh=15, warningCount=1 ]
|
||||
```
|
||||
|
||||
## 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.
|
||||
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 |
|
||||
@@ -62,27 +61,27 @@ Werden mehr Warnungen vom DWD geliefert, als an Channels konfiguriert ist, werde
|
||||
|
||||
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.
|
||||
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).
|
||||
Bitte bedenke, dass dieses Binding nur *Gemeinden* unterstützt.
|
||||
Bitte bedenke, dass dieses Binding nur _Gemeinden_ unterstützt.
|
||||
|
||||
## Vollständiges Beispiel
|
||||
|
||||
demo.things:
|
||||
|
||||
```
|
||||
```java
|
||||
dwdunwetter:dwdwarnings:koeln "Warnungen Köln" [ cellId="805315000", refresh=15, warningCount=1 ]
|
||||
```
|
||||
|
||||
demo.items:
|
||||
|
||||
```
|
||||
```java
|
||||
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" }
|
||||
@@ -99,7 +98,7 @@ String WarningCologneInstruction "Zusatzinformationen: [%s]" { channel="dwdunwet
|
||||
|
||||
demo.sitemap:
|
||||
|
||||
```
|
||||
```perl
|
||||
sitemap demo label="Main Menu" {
|
||||
Frame {
|
||||
Text item=WarnungKoelnTitel visibility=[WarnungKoeln==ON]
|
||||
@@ -110,7 +109,7 @@ sitemap demo label="Main Menu" {
|
||||
|
||||
demo.rules
|
||||
|
||||
```
|
||||
```java
|
||||
rule "Neue Warnung"
|
||||
when
|
||||
Channel 'dwdunwetter:dwdwarnings:koeln:updated1' triggered NEW
|
||||
@@ -119,9 +118,10 @@ then
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
dwdunwetter_de.map
|
||||
|
||||
```
|
||||
```text
|
||||
ON=aktiv
|
||||
OFF=inaktiv
|
||||
NULL=undefiniert
|
||||
@@ -130,7 +130,7 @@ UNDEF=undefiniert
|
||||
|
||||
dwdunwetter_severity_de.map
|
||||
|
||||
```
|
||||
```text
|
||||
Minor=Wetterwarnung
|
||||
Moderate=Markante Wetterwarnung
|
||||
Severe=Unwetterwarnung
|
||||
@@ -141,11 +141,11 @@ UNDEF=undefiniert
|
||||
|
||||
dwdunwetter_urgency_de.map
|
||||
|
||||
```
|
||||
```text
|
||||
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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user