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

[dwdunwetter] Update docs to clarify CellID selection (#12588)

Browse Source 
* [dwdunwetter] Improve docs for CellID
* [dwdunwetter] Update Thing config for README changes
* [dwdunwetter] Update German README

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>
This commit is contained in:
Florian Hotze
2022-04-25 14:34:05 +02:00
committed by GitHub
parent 8e28ef0c58
commit 33ce468dab
4 changed files with 113 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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