public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Documentation] Markdown improvements for bindings a to e (#13859)

Browse Source 
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
2022-12-07 21:09:32 +01:00
committed by GitHub
parent 72efc1cfed
commit caf71f72e6
86 changed files with 1740 additions and 1822 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
bundles/org.openhab.binding.dwdunwetter/README.md
View File

@@ -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.