Zum Hauptinhalt springen

NWPS River Floods Smart-Home-Integration, kostenlos und Open Source

NWPS River Floods-Integration für Gladys Assistant

Pegelstände, Hochwasserkategorien und Scheitelprognosen des NOAA-Wetterdienstes für US-Flüsse.

Bringt die Pegelstände der Flüsse in den USA, ihre Hochwasserkategorie und die offizielle Scheitelprognose des National Weather Service der NOAA nach Gladys, aus der öffentlichen API des National Water Prediction Service (NWPS, Nachfolger von AHPS). Kein Konto, kein Schlüssel.

Dies ist eine Ergänzung, kein Sicherheitswarnsystem. Daten können verspätet, lückenhaft oder falsch sein, und die Integration hängt von deinem Gladys, deinem Internetzugang und einem öffentlichen Dienst ab. Bei Hochwasser folge den offiziellen Warnungen (weather.gov, dein lokaler Katastrophenschutz, 911). Diese Integration ist nicht mit NOAA oder dem National Weather Service verbunden. Gegen die echte NWPS-API getestet, noch nicht auf einer echten Gladys-Installation: Rückmeldungen sind willkommen.

Was du bekommst​

  • Ein Gerät pro Pegel, dem du folgst: der Wasserstand in Fuß oder Metern, der Abfluss, wenn der Pegel einen misst, die Hochwasserkategorie des NWS (kein Hochwasser, Aktionspegel, leichtes, mittleres, großes Hochwasser) als Risikostufe und in Worten, und die Zeit der letzten Messung.
  • An den Pegeln, die der NWS vorhersagt (Prognosepunkte), der prognostizierte Scheitel: der höchste Wert der aktuellen Prognose, seine Zeit und seine Hochwasserkategorie.
  • Was die USGS-Pegel im Store nicht liefern: die Hochwasserstufen des NWS und seine Prognosen. Die Messwerte stammen oft vom USGS: der NWPS gibt sie weiter.
  • Ein Szenen-Auslöser „Hochwasserkategorie steigt“, für einen gemessenen oder vorhergesagten Anstieg.
  • Ein Dashboard-Widget: deine Pegel mit Wasserstand und Kategorie, oder ein Pegel mit seiner Scheitelprognose.
  • Eine Schaltfläche „Pegel suchen“, die die Pegel rund um dein Haus auflistet.

Voraussetzungen​

  • Gladys Assistant 5.3.2 oder neuer (die Einheit m³/s des Abflusses in metrischen Einheiten).
  • Internetzugang von Gladys: Die Integration liest api.water.noaa.gov.
  • Für „Rund um mein Haus“ und „Pegel suchen“: der Standort deines Hauses in Gladys (Einstellungen, Häuser). Bei mehreren Häusern wähle deins in der Einstellung Haus. Die Integration fragt bei der Installation danach (Berechtigung „Standort“); er dient nur dazu, die nächsten Pegel zu finden, wird auf etwa 5 km gerundet, bevor er Gladys verlässt, und wird nie gespeichert oder protokolliert.
  • Die Vereinigten Staaten (und die wenigen NWS-Pegel in Puerto Rico und an den Grenzen).

Konfiguration​

Einstellungen​

EinstellungWirkung
PegelcodesNWS-Codes (vier Buchstaben und eine Ziffer) durch Kommas getrennt, BRKM2, ARCF1, oder die Adressen ihrer Seiten, https://water.noaa.gov/gauges/brkm2.
HausDas Haus, dessen Standort „Rund um mein Haus“ und „Pegel suchen“ verwenden. Leer: das erste Haus in Gladys mit einem Standort.
Rund um mein HausVerfolgt auch die 3 nächsten Pegel in Betrieb, im Umkreis von 5, 10 oder 25 Meilen um dein Haus. Standardmäßig aus.
EinheitenFuß, cfs (Standard, die Einheiten des NWS) oder Meter, m³/s, für neue Geräte.
Aktualisierungsintervall15 (Standard), 20 oder 30 Minuten.
Sprache der FunktionsnamenNamen der Funktionen neuer Geräte, Sprache ihrer Texte und der Szenenvariablen. Standardmäßig Französisch.

Höchstens 20 Pegel werden verfolgt. Speichere, öffne dann den Tab Entdecken und lege die gewünschten Geräte an. Ein Pegel, dessen Gerät du angelegt hast, bleibt verfolgt, auch wenn du seinen Code aus den Einstellungen entfernst: Lösche das Gerät, um ihn zu beenden.

Das Ändern der Einheiten ändert die bereits angelegten Geräte nicht: deren Funktionen behalten die Einheit ihrer Erstellung, und die Werte folgen ihr. Klicke im Tab „Entdecken“ bei einem Gerät auf Aktualisieren, um es umzustellen (sein Verlauf mischt dann beide Einheiten).

Deine Pegel finden​

Die Schaltfläche Pegel suchen listet die Pegel in Betrieb rund um das in den Einstellungen gewählte Haus (25 Meilen, oder die gewählte Entfernung), den nächsten zuerst, mit Code, Entfernung, aktueller Kategorie und „Prognose“, wenn der NWS sie vorhersagt. Kopiere die gewünschten Codes in Pegelcodes und speichere. Der Code eines Pegels steht auch auf seiner Seite bei water.noaa.gov.

Geräte​

Ein Gerät pro Pegel, benannt wie beim NWS („Potomac River near Washington DC (Little Falls)“), mit dem Code als NWS_LID und dem Bundesstaat als STATE in seinen Parametern. Seine Funktionen sind schreibgeschützt:

FunktionTyp (Gladys)Wert
WasserstandFlüssigkeitstiefeWasserstand am Pegel, in Fuß oder Metern, über dem Pegelnullpunkt (an manchen Seen und Dämmen eine Höhe über NN).
Abfluss (cfs) / AbflussWasserdurchflussWenn der Pegel einen misst: in Kubikfuß pro Sekunde (eine Einheit, die Gladys nicht hat: der Name nennt sie) oder m³/s.
HochwasserstufeRisikoWenn der Pegel Hochwasserstufen hat: 0 kein Hochwasser (Aktionspegel inbegriffen), 1 leicht, 2 mittel, 3 groß.
HochwasserkategorieTextDie Kategorie in Worten: Kein Hochwasser, Aktionspegel, Leichtes Hochwasser… oder warum es keine gibt.
Letzte MessungTextZeit der letzten Messung, in der Zeitzone von Gladys.
Prognostizierter ScheitelFlüssigkeitstiefe oder AbflussNur Prognosepunkte: der höchste Wert der aktuellen Prognose (ein Abfluss an den wenigen per Abfluss vorhergesagten Pegeln).
Zeit des ScheitelsTextSeine Zeit, oder „Keine aktuelle Prognose“.
Prognostizierte HochwasserstufeRisikoDie Hochwasserstufe des Scheitels, 0 ohne aktuelle Prognose.
Prognostizierte KategorieTextDie Kategorie des Scheitels in Worten.

Eine Messung, die älter als 24 Stunden ist, wird nicht erneut gesendet: Der Wasserstand zeigt dann in Gladys „kein aktueller Wert“, und die Kategorie „Keine aktuelle Messung“.

Wird eine Prognose zurückgezogen, behält der prognostizierte Scheitel seinen letzten Wert: Seine Zeit und Kategorie zeigen dann „Keine aktuelle Prognose“, seine Hochwasserstufe 0.

Hochwasserkategorien​

Der NWS legt für jeden Prognosepunkt und viele andere Pegel einen Aktionspegel fest (Zeit zur Vorbereitung, noch keine Überflutung) sowie die Stufen für leichtes, mittleres und großes Hochwasser, nach den Schäden vergangener Hochwasser. Die Integration veröffentlicht die Kategorie, die der NWS berechnet, und vergleicht die Wasserstände nicht selbst. Ein Pegel ohne Hochwasserstufen („Keine Hochwasserstufen“) hat keine Funktion für die Hochwasserstufe. Viele Prognosepunkte werden nur bei Hochwasser vorhergesagt: Zwischen zwei Ereignissen zeigt ihre Prognose „Keine aktuelle Prognose“.

Dashboard-Widget​

Füge das Widget Flusspegel zu einem Dashboard hinzu:

  • ohne gewählten Pegel: eine Zeile pro Pegel mit Wasserstand und Kategorie, grün (kein Hochwasser), gelb (Aktionspegel, leicht) oder rot (mittel, groß), und eine Überschrift, wenn ein Pegel im Hochwasser ist oder Hochwasser vorhergesagt wird;
  • mit gewähltem Pegel: seine Kacheln für Wasserstand und Abfluss, seine Kategorie, der prognostizierte Scheitel mit Zeit und Kategorie, seine Hochwassermarke und seine letzte Messung.

Die Wasserstände der Zeilen folgen den Einheiten deines Gladys-Profils; die Kacheln zeigen die Einheit der Funktionen. Die Schaltfläche water.noaa.gov öffnet die Seite des Pegels; eine Einstellung blendet sie aus.

Szenen-Auslöser​

Hochwasserkategorie steigt löst aus, wenn die Kategorie eines angelegten Pegels auf Aktionspegel, leichtes, mittleres oder großes Hochwasser steigt, gemessen oder vorhergesagt. Filter: der Pegel, gemessen oder vorhergesagt, die neue Kategorie. Variablen für deine Nachrichten: gauge_name, category_name, source_name (gemessen oder vorhergesagt), value (der Wert mit Einheit) und time (der Messung oder des Scheitels), in der Sprache der Konfiguration.

Er löst einmal pro Anstieg aus: erneut erst, nachdem die Kategorie gesunken ist oder die Prognose zurückgezogen wurde. Die letzten Kategorien werden in /data gespeichert: Ein Anstieg während eines Neustarts löst einmal aus, und die erste Messung eines neuen Pegels löst nichts aus.

Für eine eigene Schwelle nutze den eingebauten Auslöser von Gladys auf einen Gerätewert: „Hochwasserstufe größer oder gleich 1“ (leichtes Hochwasser), oder „Prognostizierter Scheitel über 9 ft“.

Szenenbeispiele​

  • Hochwasser vorhergesagt: Auslöser „Hochwasserkategorie steigt“, vorhergesagt, leicht, mittel oder groß → die Nachricht „{{gauge_name}}: {{category_name}} vorhergesagt, Scheitel {{value}} um {{time}}“ senden.
  • Leichtes Hochwasser gemessen: Auslöser auf den Gerätewert „Hochwasserstufe ≥ 1“ → benachrichtigen und eine Warnleuchte einschalten.
  • Zurück zur Normalität: Auslöser auf den Gerätewert „Hochwasserstufe = 0“ → „Der Fluss ist wieder unter der Hochwassermarke“ senden.

Datenquelle, Kontingente und Lizenz​

  • Quelle: der National Water Prediction Service des National Weather Service der NOAA, https://api.water.noaa.gov/nwps/v1/ (/gauges/{lid} für jeden Pegel, /gauges?bbox… für die Pegel rund um das Haus). Daten der US-Regierung, gemeinfrei; Nennung: NOAA / NWS.
  • Kein Konto, kein Schlüssel, kein veröffentlichtes Kontingent. Die Integration fragt jeden verfolgten Pegel einmal pro Aktualisierung ab (standardmäßig alle 15 Minuten, höchstens 20 Pegel), einen nach dem anderen, mit einem User-Agent, der die Integration nennt, und sucht die Pegel rund um das Haus einmal am Tag.
  • Die Messwerte vieler Pegel stammen vom USGS und anderen Partnern, weitergegeben vom NWPS.

Fehlerbehebung​

  • „Unbekannte Pegelcodes“: Ein Code der Einstellungen ist kein NWS-Pegel. Prüfe ihn auf water.noaa.gov, oder nutze Pegel suchen. Eine USGS-Stationsnummer (8 Ziffern) ist kein NWS-Code.
  • „Die NWPS-API antwortet nicht“: Gladys erreicht api.water.noaa.gov nicht, oder der Dienst ist ausgefallen. Die Integration versucht es bei jeder Aktualisierung erneut, und der Status kommt von selbst zurück.
  • „Kein Haus in Gladys hat einen Standort“: Lege den Standort deines Hauses unter Einstellungen, Häuser fest, oder schalte „Rund um mein Haus“ aus.
  • Kein prognostizierter Scheitel: Der Pegel ist kein Prognosepunkt, oder der NWS hat keine aktuelle Prognose für ihn (außerhalb von Hochwasser üblich).
  • Alte Werte: Die letzte Messung steht in „Letzte Messung“. Ein Pegel, der nicht mehr misst, zeigt „Keine aktuelle Messung“.
  • Protokolle: Integrationen → NWPS River Floods → Protokolle; LOG_LEVEL=debug zeigt jede Aktualisierung.

Grenzen​

  • Eine Ergänzung, kein Sicherheitswarnsystem: Die Warnungen des NWS und deine lokalen Behörden haben Vorrang.
  • Der NWPS liefert den Scheitel der Prognose, nicht die ganze Prognosekurve und nicht ihre Unsicherheit.
  • Hochwasserkategorien gibt es nur, wo der NWS Hochwasserstufen festgelegt hat.
  • Der Abfluss in cfs hat in Gladys keine Einheit (der Name sagt „cfs“); in metrischen Einheiten ist er in m³/s.
  • Gegen die echte NWPS-API entwickelt und getestet, ohne echte Gladys-Installation: Rückmeldungen sind willkommen.

Konfigurationseinstellungen​

Diese Einstellungen fragt NWPS River Floods in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Deine PegelsectionNeinVerfolge die Flusspegel des National Weather Service: per Code oder die nächsten zu deinem Haus. „Pegel suchen“ unten listet sie auf. Speichere und lege dann die Geräte im Tab „Entdecken“ an.
Quellen und GrenzensectionNeinDaten des National Weather Service der NOAA (gemeinfrei), ohne Konto gelesen. Eine Ergänzung, kein Sicherheitswarnsystem: Die offiziellen Warnungen haben Vorrang. Nicht mit NOAA oder NWS verbunden.
PegelcodesstringNeinNWS-Codes durch Kommas getrennt, oder die Adressen ihrer Seiten auf water.noaa.gov.
HausselectNeinDas Haus, dessen Standort „Rund um mein Haus“ und „Pegel suchen“ verwenden. Leer: das erste Haus in Gladys mit einem Standort.
Rund um mein HausselectNeinVerfolge auch die 3 nächsten Pegel in Betrieb in dieser Entfernung von deinem Haus.
EinheitenselectNeinEinheiten der neuen Geräte. Zum Ändern: die Geräte im Tab „Entdecken“ „Aktualisieren“.
AktualisierungsintervallselectNeinPegel melden alle 5 bis 60 Minuten, Prognosen erscheinen einige Male am Tag.
Sprache der FunktionsnamenselectNeinNamen der Funktionen neuer Geräte und Sprache ihrer Texte (Kategorie, Zeiten) und der Szenenvariablen.

So installierst du NWPS River Floods in Gladys​

  1. Öffne in Gladys Integrationen: NWPS River Floods erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/guim31/gladys-nwps:1.0.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-nwps.

NWPS River Floods benötigt Gladys >=5.3.2. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

NWPS River Floods ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂