iobroker.waip-web 0.7.16 → 0.7.18

package/README.de.md

@@ -10,6 +10,21 @@ Verbindet sich per Socket.IO mit einem WAIP-Web-Wachalarm-Monitor und bildet
 Einsätze, Rückmeldungen, Routen und TTS-Ansagen als ioBroker-States ab –
 ohne dass ein Browser-Tab dauerhaft offen sein muss.
 
+## Inhaltsverzeichnis
+
+- [Über diesen Adapter](#über-diesen-adapter)
+- [Über WAIP-Web](#über-waip-web)
+- [Praktische Anwendungsfälle](#praktische-anwendungsfälle)
+- [Funktionen](#funktionen)
+  - [Warum ein Session-Cookie nötig ist](#warum-ein-session-cookie-nötig-ist)
+- [Konfiguration](#konfiguration)
+- [States (unter `waip-web.0.*`)](#states-unter-waip-web0)
+  - [info](#info) · [status](#status) · [einsatz](#einsatz) ·
+    [einsatz.json](#einsatzjson) · [einsatz.tts](#einsatztts) ·
+    [debug](#debug)
+- [Logging](#logging)
+- [Lizenz und Changelog](#lizenz-und-changelog)
+
 ## Über diesen Adapter
 
 Dieser Adapter ist ein **inoffizielles Community-Projekt** und steht in
@@ -53,10 +68,61 @@ lizenziert. Dieser Adapter enthält keinen Code aus dem WAIP-Web-Projekt,
 sondern implementiert eine eigenständige Anbindung an dessen Socket.IO-
 Schnittstelle.
 
+## Praktische Anwendungsfälle
+
+In diesem Abschnitt geht es darum, was sich mit den States dieses Adapters
+konkret **bauen** lässt – typischer Einsatz auf einer Feuerwehr-/
+Rettungsdienst-Wache:
+
+- **Wandmontierte Alarmanzeige.** `einsatz.json.current` an ein
+  VIS-Tabellen-Widget auf einem wandmontierten Tablet/TV im Aufenthalts-
+  raum oder in der Fahrzeughalle binden – Einsatzart, Stichwort, Adresse
+  und alarmierte Einsatzmittel erscheinen automatisch, ohne dass dort
+  dauerhaft ein Browser-Tab offen gehalten werden muss (genau dafür
+  existiert dieser Adapter).
+- **Automationen direkt bei Alarmeingang auslösen.** `einsatz.alarmAktiv`
+  (ggf. zusammen mit `info.connection`) in einem Script/einer Blockly-Regel
+  beobachten, um bei Alarm Licht in der Fahrzeughalle einzuschalten, ein
+  Tor/eine Tür zu öffnen, eine Push-Benachrichtigung (z. B. über einen
+  Telegram-/Pushover-Adapter) mit `einsatz.stichwort` + `einsatz.ort` zu
+  versenden oder eine Lichtszene auszulösen – wenige Sekunden nach der
+  eigentlichen Alarmierung, da ioBroker-State-Änderungen sofort feuern und
+  kein Polling nötig ist.
+- **Alarm laut ansagen.** `einsatz.tts.last` ist eine fertige, absolute
+  mp3-URL; eine `sonos`-/`snapcast`-/`text2speech`-Automation darauf
+  ansetzen (oder die URL direkt abspielen), um den Einsatz über
+  Gebäudelautsprecher anzusagen, sobald `io.playtts` feuert – hilfreich,
+  wenn nicht alle Mitglieder gerade auf einen Bildschirm schauen.
+- **Live-Übersicht der Rückmeldungen.** Die `einsatz.rueckmeldungAnzahl.*`
+  Zähler (pro Rolle: EK/GF/ZF/VF, pro Zusatzfunktion: AGT/FZF/MA/MED)
+  aktualisieren sich in Echtzeit, sobald Einsatzkräfte per App
+  zurückmelden – als Gauge- oder Zahlen-Widget gebunden ergibt das eine
+  Übersicht auf einen Blick, wer bereits kommt.
+- **Nachbereitung/Statistik.** `einsatz.json.history10` hält die letzten
+  10 abgeschlossenen Einsätze als flache Tabelle vor – an eine zweite
+  VIS-Ansicht binden oder periodisch exportieren (z. B. per Script, das
+  den State bei `io.standby` ausliest), um ein längerfristiges Log zu
+  führen oder Einsatzzahlen in ein Statistik-/Dashboard-Adapter
+  einzuspeisen.
+- **Routen-/Fahrzeugübersicht auf einer Karte.** `einsatz.json.routen`
+  enthält für jede alarmierte Wache `lat`/`lon` und `color` – an ein
+  VIS-Kartenwidget gebunden ergibt das auf einen Blick, wer unterwegs ist,
+  unabhängig von der WAIP-Web-eigenen Karte.
+- **Anbindung an weitere ioBroker-Automationen.** Da jedes Feld ein
+  gewöhnlicher ioBroker-State ist, lässt sich das Ganze mit allem
+  kombinieren, was ohnehin in der Instanz läuft – `einsatz.*` in eine
+  Smart-Home-Szenensteuerung einspeisen, eine Grafana-/InfluxDB-Historie
+  für Reaktionszeit-Auswertungen führen, oder per ioBroker-MQTT-Adapter
+  in einen Node-RED-artigen Flow einbinden, ganz ohne eigene Anbindung an
+  die WAIP-Web-API.
+
 ## Funktionen
 
 - Verbindung zum Namespace `/waip` per `socket.io-client`, Registrierung
-  über `emit('WAIP', monitorId)` (3-faches Emit für Robustheit)
+  über `emit('WAIP', monitorId)` einmalig (verlässt sich als Fallback
+  auf `REGISTRATION_TIMEOUT_MS` statt auf wiederholte Emits, da ein
+  redundanter Emit den Server nur erneut antworten lässt, ohne die
+  Zustellungssicherheit zu erhöhen)
 - Manuelles Reconnect-Handling (kein Auto-Reconnect der Bibliothek) mit
   konfigurierbarer Verzögerung
 - Registrierungs-Timeout mit Audit-Log (`debug.monitorAudit`)
@@ -90,6 +156,9 @@ Schnittstelle.
   ab, sobald seine `ablaufzeit` um mehr als eine Gnadenfrist (60
   Sekunden) überschritten ist, statt unbegrenzt veraltete "aktiv"-Daten
   stehen zu lassen.
+- Zeigt immer nur den zuletzt aktiven Einsatz; mehrere gleichzeitig
+  laufende Einsätze sind aktuell nur über das Dashboard der
+  WAIP-Web-Instanz selbst einsehbar
 
 ### Warum ein Session-Cookie nötig ist
 
@@ -157,6 +226,27 @@ damit ein verlässlicher Schalter dafür, ob hier gerade echte Live-Daten
 stehen. Der zuletzt abgeschlossene Einsatz bleibt trotzdem über
 `einsatz.json.history10` abrufbar:
 
+> **Hinweis:** Der Adapter bildet immer nur den zuletzt aktiv gemeldeten
+> Einsatz ab (`einsatz.*` bzw. `einsatz.json.current`) – analog zum
+> Alarmmonitor des offiziellen WAIP-Web-Frontends. Theoretisch können in
+> WAIP-Web mehrere Einsätze gleichzeitig aktiv sein (z. B. wenn kurz
+> hintereinander zwei Alarmierungen eingehen). Diese States sind **kein
+> Array mehrerer laufender Einsätze**, sondern werden bei jedem neuen
+> `io.new_waip`-Event überschrieben – ein zeitgleich zweiter laufender
+> Einsatz ist über den Adapter aktuell nicht sichtbar. Eine vollständige
+> Übersicht aller gerade aktiven Einsätze liefert derzeit nur das
+> Dashboard der angebundenen WAIP-Web-Instanz selbst.
+
+> **Hinweis:** WAIP-Web befüllt `einsatznummer`, `objekt`/`objektteil`,
+> `besonderheiten`, `strasse`/`hausnummer`, `einsatzdetails` sowie das
+> Berechtigungsflag serverseitig nur für **eingeloggte** Clients
+> (`db_user_check_permission_for_waip()` im server-eigenen
+> `server/waip.js`) – da dieser Adapter sich bewusst ohne Login
+> verbindet (siehe [Über diesen Adapter](#über-diesen-adapter)), sendet
+> der Server diese Felder immer leer bzw. `false`. Sie werden deshalb
+> gar nicht erst als States geführt, statt dauerhaft leere Werte
+> vorzuhalten.
+
 | State | Typ | Beschreibung |
 | --- | --- | --- |
 | `alarmAktiv` | boolean | `true` seit dem letzten `io.new_waip`, `false` seit dem letzten `io.standby` |
@@ -167,15 +257,9 @@ stehen. Der zuletzt abgeschlossene Einsatz bleibt trotzdem über
 | `stichwort` | string | Alarmstichwort |
 | `ort` | string | Ort |
 | `ortsteil` | string | Ortsteil (falls abweichend vom Ort) |
-| `strasse` / `hausnummer` | string | Adresse |
-| `objekt` / `objektteil` | string | Gebäude-/Objektname und -teil |
-| `einsatzdetails` | string | Zusatzdetails (nur bei Brand-/Hilfeleistungseinsätzen befüllt) |
-| `besonderheiten` | string | Freitext-Besonderheiten der Leitstelle |
 | `zeitstempel` | string (date) | Alarmzeit |
 | `ablaufzeit` | string (date) | Ende der Standby-Anzeigedauer, Basis für `restzeit` |
-| `einsatznummer` | string | Einsatznummer (sofern vom Server vergeben) |
 | `sondersignal` | number | `1` = Sondersignal, sonst kein Sondersignal |
-| `permissions` | string | Berechtigungsflag der Registrierung (Vollzugriff auf Detailkarte ja/nein); wird immer als String gespeichert (z.B. `"true"`), da der Server hier ein rohes Boolean sendet |
 | `latitude` / `longitude` | number | Position des Einsatzortes (normalisiert aus wgs84-Feldern oder GeoJSON-Mittelpunkt) |
 | `routenGesamt` | number | Anzahl Routen im aktuellen Einsatz |
 | `rueckmeldungGesamt` | number | Rückmeldungen gesamt im aktuellen Einsatz |
@@ -196,13 +280,13 @@ ein einfaches `{routen, rueckmeldungen, ...}`-Objekt werden von diesen
 Widgets in der Regel nicht dargestellt). `routen`/`rueckmeldungen`/
 `emAlarmiert`/`emWeitere` enthalten immer nur die Daten des **aktuellen**
 Einsatzes – sie werden bei `io.standby` geleert (`[]`) und sind **nicht**
-Teil der History. `permissions` innerhalb von `current`/`history10` wird
-genauso als String gespeichert wie im eigenständigen
-`einsatz.permissions`-State.
+Teil der History. Wie bei `einsatz.*` oben gilt auch hier: `current`
+enthält immer nur den zuletzt aktiven Einsatz – siehe Hinweis im
+Abschnitt [`einsatz`](#einsatz).
 
 | State | Typ | Beschreibung |
 | --- | --- | --- |
-| `current` | string (JSON-Array) | Flache Daten des aktuellen Einsatzes: dieselben 19 Felder wie die einzelnen `einsatz.*`-States oben (`id` … `permissions`, plus `lat`/`lon`), gebündelt als ein Objekt innerhalb eines Arrays mit einem Element (`[]` falls kein Einsatz aktiv) – der Array-Wrapper ist nötig, weil die meisten Tabellen-Widgets am Root ein Array statt eines nackten Objekts erwarten |
+| `current` | string (JSON-Array) | Flache Daten des aktuellen Einsatzes: dieselben 11 Felder wie die einzelnen `einsatz.*`-States oben (`id` … `zeitstempel`, plus `lat`/`lon`), zusätzlich `registeredMonitor`/`registeredMonitorName` (der Monitor, auf den der Adapter zu diesem Zeitpunkt registriert war), gebündelt als ein Objekt innerhalb eines Arrays mit einem Element (`[]` falls kein Einsatz aktiv) – der Array-Wrapper ist nötig, weil die meisten Tabellen-Widgets am Root ein Array statt eines nackten Objekts erwarten |
 | `history10` | string (JSON-Array) | Letzte 10 abgeschlossenen Einsätze, gleiches Schema wie `current`, ein Array-Eintrag pro Einsatz, geschrieben bei `io.standby` |
 | `routen` | string (JSON-Array) | Routen des aktuellen Einsatzes; jeder Eintrag hat `nr_wache`, `name_wache`, `color`, `lat`, `lon` (`position` zu flachem `lat`/`lon` aufgelöst) |
 | `rueckmeldungen` | string (JSON-Array) | Rückmeldungen des aktuellen Einsatzes, wie vom Server empfangen |
@@ -225,8 +309,8 @@ relevant, deshalb wird nur die jeweils letzte vorgehalten.
 
 | State | Typ | Beschreibung |
 | --- | --- | --- |
-| `lastEvent` | string (JSON) | Letztes empfangenes Socket-Event (Name + Zeitstempel), zur Verbindungsdiagnose |
-| `normalizedPosition` | string (JSON) | Ergebnis der Geodaten-Normalisierung für das letzte `io.new_waip`-Event, als flaches `{lat, lon}`-Objekt (beide `null`, falls keine gültige Position ermittelt werden konnte) |
+| `lastEvent` | string (JSON-Array) | Letztes empfangenes Socket-Event (Name + Zeitstempel), zur Verbindungsdiagnose; einelementiges Array (`[]` falls noch keins), für VIS-Tabellen-Kompatibilität |
+| `normalizedPosition` | string (JSON-Array) | Ergebnis der Geodaten-Normalisierung für das letzte `io.new_waip`-Event, als flaches einelementiges `[{lat, lon}]`-Array (beide `null`, falls keine gültige Position ermittelt werden konnte; `[]` falls noch kein Event), für VIS-Tabellen-Kompatibilität |
 | `rawPayloadShort` | string | Vorschau (500 Zeichen) der rohen, unnormalisierten `io.new_waip`-Nutzlast |
 | `ignoredCount` | number | Anzahl verworfener Events (Payload nannte explizit eine andere Monitor-ID) |
 | `monitorAudit` | string (JSON-Array) | Chronologisches Log von Connect-/Registrierungs-/Reconnect-Ereignissen (200 Einträge) |
@@ -234,8 +318,22 @@ relevant, deshalb wird nur die jeweils letzte vorgehalten.
 | `lastError` | string | Letzte vom Server gemeldete Fehlermeldung (`io.error`); reiner Text, kein JSON, da der Server hier einen bloßen String sendet |
 | `serverVersion` | string | Zuletzt gemeldete Server-Instanz-ID (`io.version`); Änderung deutet auf Server-Neustart hin |
 
+## Logging
+
+Sämtliche Log-Texte sind auf Englisch, unabhängig von der ioBroker-
+Systemsprache (nur UI-Texte wie Admin-Beschriftungen werden übersetzt).
+Wiederkehrbare Fehlerzustände (Session-Cookie-Erneuerung,
+WAIP-Registrierung, die Socket.IO-Verbindung, eine Flut von
+Falscher-Monitor-Events) werden beim ersten Auftreten einmalig auf `warn`
+geloggt, danach solange sie bestehen nur noch auf `debug`, und bei
+Erholung einmalig auf `info` – entsprechend der
+[offiziellen ioBroker-Logging-Richtlinie](https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/adapterdev.md#logging).
+
+Eine vollständige Referenz aller Log-Meldungen (gruppiert nach Level, mit
+Ursache und Beispieltext) gibt es in **[LOGGING.md](LOGGING.md)** (auf
+Englisch, wie auch der Quelltext des Adapters selbst).
 
----
+## Lizenz und Changelog
 
 Lizenz und vollständiges Changelog stehen in der
 [englischen README](README.md#license) (`## License`, `## Changelog`).

package/README.md

@@ -19,6 +19,22 @@ Connects via Socket.IO to a WAIP-Web dispatch monitor and mirrors incidents
 announcements into ioBroker states – without needing a browser tab to stay
 open.
 
+## Table of contents
+
+- [About this adapter](#about-this-adapter)
+- [About WAIP-Web](#about-waip-web)
+- [Practical use cases](#practical-use-cases)
+- [Features](#features)
+  - [Why a session cookie is needed](#why-a-session-cookie-is-needed)
+- [Configuration](#configuration)
+- [States (under `waip-web.0.*`)](#states-under-waip-web0)
+  - [info](#info) · [status](#status) · [einsatz](#einsatz) ·
+    [einsatz.json](#einsatzjson) · [einsatz.tts](#einsatztts) ·
+    [debug](#debug)
+- [Logging](#logging)
+- [Changelog](#changelog)
+- [License](#license)
+
 ## About this adapter
 
 This adapter is an **unofficial community project** and has no connection
@@ -61,10 +77,56 @@ WAIP-Web itself is licensed under
 This adapter contains no code from the WAIP-Web project; it implements an
 independent client for its Socket.IO interface.
 
+## Practical use cases
+
+This section is about what you can actually *build* with the states this
+adapter provides – typical use in a fire station/EMS environment:
+
+- **Wall-mounted alarm display.** Bind `einsatz.json.current` to a VIS
+  table widget on a wall-mounted tablet or TV in the day room/vehicle
+  hall – incident type, keyword, address and alerted resources appear
+  automatically, without anyone having to keep a browser tab open on that
+  screen (which is the whole reason this adapter exists in the first
+  place).
+- **Trigger automations the instant an alarm comes in.** Watch
+  `einsatz.alarmAktiv` (or `info.connection` together with it) in a
+  script/blockly rule to switch on lights in the vehicle hall, open a
+  gate/door, send a push notification (e.g. via a Telegram/Pushover
+  adapter) with `einsatz.stichwort` + `einsatz.ort`, or flash a
+  smart-light scene – all a few seconds after the actual pager alert,
+  no polling required since ioBroker state changes fire instantly.
+- **Announce the alarm out loud.** `einsatz.tts.last` is a ready-to-play
+  absolute mp3 URL; point a `sonos`/`snapcast`/`text2speech`-style
+  automation at it (or just play the URL directly) to have the incident
+  announced over building speakers the moment `io.playtts` fires –
+  useful where members aren't all looking at a screen.
+- **Live headcount / feedback board.** The `einsatz.rueckmeldungAnzahl.*`
+  counters (per role: EK/GF/ZF/VF, per qualification: AGT/FZF/MA/MED)
+  update in real time as responders confirm via the app – bind them to
+  gauge or number widgets for an at-a-glance "who's coming" overview
+  during the response.
+- **Post-incident review / statistics.** `einsatz.json.history10` keeps
+  the last 10 completed incidents as a flat table – bind it to a second
+  VIS view or export it periodically (e.g. via a script reading the
+  state on `io.standby`) to keep a longer-running log or feed incident
+  counts into a dashboard/statistics adapter.
+- **Route/vehicle overview on a map.** `einsatz.json.routen` carries
+  each responding station's `lat`/`lon` and `color` – bind it to a VIS
+  map widget for a quick visual of who is en route, independent of the
+  WAIP-Web map itself.
+- **Bridge into other ioBroker automations.** Because every field is a
+  plain ioBroker state, it composes with anything else already running
+  in the instance – forward `einsatz.*` into a smart-home scene engine,
+  a Grafana/InfluxDB history for response-time analysis, or a
+  Node-RED-style flow via the ioBroker MQTT adapter, without writing a
+  single line against the WAIP-Web API.
+
 ## Features
 
 - Connects to the `/waip` namespace via `socket.io-client`, registers via
-  `emit('WAIP', monitorId)` (emitted 3× for robustness)
+  `emit('WAIP', monitorId)` once (relies on `REGISTRATION_TIMEOUT_MS`
+  as a fallback rather than repeated emits, since a redundant emit only
+  makes the server reply again without improving delivery reliability)
 - Manual reconnect handling (the library's own auto-reconnect is
   disabled) with a configurable delay
 - Registration timeout with an audit log (`debug.monitorAudit`)
@@ -97,6 +159,9 @@ independent client for its Socket.IO interface.
   at the wrong moment), a watchdog automatically finalizes the incident
   once its `ablaufzeit` has passed by more than a grace period
   (60 seconds), instead of leaving stale "active" data indefinitely.
+- Only ever shows the single most recently active incident; multiple
+  concurrently active incidents can currently only be viewed via the
+  WAIP-Web instance's own dashboard
 
 ### Why a session cookie is needed
 
@@ -164,6 +229,26 @@ a reliable switch for whether these fields currently hold real live data.
 The most recently finished incident remains available via
 `einsatz.json.history10`:
 
+> **Note:** The adapter always reflects only the single most recently
+> active incident (`einsatz.*` / `einsatz.json.current`) – matching the
+> official WAIP-Web frontend's alarm monitor. WAIP-Web can, in principle,
+> have several incidents active at the same time (e.g. two alerts coming
+> in close together). These states are **not an array of concurrently
+> running incidents** – they get overwritten by each new `io.new_waip`
+> event, so a second incident running in parallel is currently not
+> visible through this adapter. A complete overview of all currently
+> active incidents is, for now, only available via the connected
+> WAIP-Web instance's own dashboard.
+
+> **Note:** WAIP-Web's server only fills `einsatznummer`, `objekt`/
+> `objektteil`, `besonderheiten`, `strasse`/`hausnummer`,
+> `einsatzdetails` and the permission flag for **logged-in** clients
+> (`db_user_check_permission_for_waip()` in the server's own
+> `server/waip.js`) - since this adapter connects without a login by
+> design (see [About this adapter](#about-this-adapter)), the server
+> always sends these blank/`false`. They are therefore not exposed as
+> states at all rather than permanently carrying dead values.
+
 | State | Type | Description |
 | --- | --- | --- |
 | `alarmAktiv` | boolean | `true` since the last `io.new_waip`, `false` since the last `io.standby` |
@@ -174,15 +259,9 @@ The most recently finished incident remains available via
 | `stichwort` | string | Alarm keyword |
 | `ort` | string | Location/town |
 | `ortsteil` | string | District (if different from `ort`) |
-| `strasse` / `hausnummer` | string | Address |
-| `objekt` / `objektteil` | string | Building name and part |
-| `einsatzdetails` | string | Extra details (only populated for fire/technical-assistance incidents) |
-| `besonderheiten` | string | Free-text remarks from the dispatch center |
 | `zeitstempel` | string (date) | Alarm time |
 | `ablaufzeit` | string (date) | End of the standby display duration, basis for `restzeit` |
-| `einsatznummer` | string | Incident number (if assigned by the server) |
 | `sondersignal` | number | `1` = special signal (lights & siren), otherwise none |
-| `permissions` | string | The registration's permission flag (full access to the detail map yes/no); always stringified (e.g. `"true"`), since the server sends it as a raw boolean |
 | `latitude` / `longitude` | number | Incident location (normalized from wgs84 fields or GeoJSON centroid) |
 | `routenGesamt` | number | Number of routes in the current incident |
 | `rueckmeldungGesamt` | number | Total feedback count for the current incident |
@@ -202,13 +281,13 @@ directly to VIS table widgets (nested structures like a plain
 `{routen, rueckmeldungen, ...}` object generally aren't rendered by
 those widgets). `routen`/`rueckmeldungen`/`emAlarmiert`/`emWeitere` only
 ever hold the *current* incident's data – they are cleared (`[]`) on
-`io.standby` and are **not** part of the history. `permissions` inside
-`current`/`history10` is stringified the same way as the standalone
-`einsatz.permissions` state.
+`io.standby` and are **not** part of the history. As with `einsatz.*`
+above, `current` only ever holds the single most recently active
+incident – see the note in the [`einsatz`](#einsatz) section.
 
 | State | Type | Description |
 | --- | --- | --- |
-| `current` | string (JSON array) | Current incident's flat data: the same 19 fields as the individual `einsatz.*` states above (`id` … `permissions`, plus `lat`/`lon`), bundled as one object inside a single-element array (`[]` if no incident is active) – the array wrapper is needed because most table widgets require an array at the root, not a bare object |
+| `current` | string (JSON array) | Current incident's flat data: the same 11 fields as the individual `einsatz.*` states above (`id` … `zeitstempel`, plus `lat`/`lon`), plus `registeredMonitor`/`registeredMonitorName` (the monitor the adapter was registered to at the time), bundled as one object inside a single-element array (`[]` if no incident is active) – the array wrapper is needed because most table widgets require an array at the root, not a bare object |
 | `history10` | string (JSON array) | Last 10 completed incidents, same shape as `current`, one array entry per incident, written on `io.standby` |
 | `routen` | string (JSON array) | Routes of the current incident; each entry has `nr_wache`, `name_wache`, `color`, `lat`, `lon` (`position` resolved to flat `lat`/`lon`) |
 | `rueckmeldungen` | string (JSON array) | Feedback entries of the current incident, as received from the server |
@@ -231,8 +310,8 @@ matters in the moment, so only the most recent one is kept.
 
 | State | Type | Description |
 | --- | --- | --- |
-| `lastEvent` | string (JSON) | Last received socket event (name + timestamp), for connection diagnostics |
-| `normalizedPosition` | string (JSON) | Result of the geodata normalization for the last `io.new_waip` event, as a flat `{lat, lon}` object (both `null` if no valid position could be derived) |
+| `lastEvent` | string (JSON array) | Last received socket event (name + timestamp), for connection diagnostics; single-element array (`[]` if none yet), for VIS table-widget compatibility |
+| `normalizedPosition` | string (JSON array) | Result of the geodata normalization for the last `io.new_waip` event, as a flat single-element `[{lat, lon}]` array (both `null` if no valid position could be derived; `[]` if no event yet), for VIS table-widget compatibility |
 | `rawPayloadShort` | string | Preview (500 characters) of the raw, unnormalized `io.new_waip` payload |
 | `ignoredCount` | number | Count of discarded events (payload explicitly named a different monitor ID) |
 | `monitorAudit` | string (JSON array) | Chronological log of connect/registration/reconnect events (200 entries) |
@@ -240,8 +319,72 @@ matters in the moment, so only the most recent one is kept.
 | `lastError` | string | Last error message reported by the server (`io.error`); plain text, not JSON, as the server sends this as a bare string |
 | `serverVersion` | string | Last reported server instance ID (`io.version`); a change suggests a server restart |
 
+## Logging
+
+All log text is in English. Repeatable failure conditions (session-cookie
+renewal, WAIP registration, the Socket.IO connection, a wrong-monitor
+event flood) are logged once at `warn` on first occurrence, then at
+`debug` while they persist, and once at `info` on recovery – matching the
+[official ioBroker logging guideline](https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/adapterdev.md#logging).
+
+See **[LOGGING.md](LOGGING.md)** for the full reference of every log
+message the adapter can produce, grouped by level, with its cause and an
+example.
+
 ## Changelog
 
+### 0.7.18 (2026-08-22)
+
+- Fixed `debug.lastEvent`/`debug.normalizedPosition` to hold a
+  single-element JSON array instead of a bare object (matching
+  `einsatz.json.current`), for direct VIS table-widget compatibility,
+  and to correctly initialize to `[]` instead of `null` on a fresh
+  install/restart.
+- Removed `einsatz.einsatznummer`/`.objekt`/`.objektteil`/
+  `.besonderheiten`/`.strasse`/`.hausnummer`/`.einsatzdetails`/
+  `.permissions` (and the corresponding fields in
+  `einsatz.json.current`/`.history10`): confirmed via the WAIP-Web
+  server source (`server/waip.js`,
+  `db_user_check_permission_for_waip()`) that these fields are only
+  ever populated for logged-in clients - since this adapter connects
+  anonymously by design, they were always empty/`false`. Removed
+  instead of permanently carrying dead states - see the note in the
+  [`einsatz`](#einsatz) section.
+
+### 0.7.17 (2026-08-22)
+
+- Fixed `cleanupObsoleteObjects()` incorrectly deleting and recreating
+  the `einsatz.json` channel on every restart (it wasn't checking
+  `obj.type`, so the current channel object was mistaken for a leftover
+  state from before the 0.7.15 migration).
+- Fixed a spurious `status.registrationPending` "no existing object"
+  warning that could occur if the adapter was stopped before object
+  initialization had finished.
+- Reduced WAIP registration from three emits to a single emit - Socket.IO
+  already delivers reliably once connected, and the existing registration
+  timeout remains as the safety net for the rare case it doesn't confirm.
+- `permissions` inside `einsatz.json.current`/`.history10` is now always
+  stringified consistently with the standalone `einsatz.permissions`
+  state, and `einsatz.json.current` is wrapped in a single-element array
+  (VIS table widgets require an array at the root, not a bare object).
+- Fixed `einsatz.json.history10`/`debug.monitorAudit` staying `null`
+  instead of `[]` on a fresh install (they're excluded from the
+  per-restart reset to preserve history, which previously also meant
+  they were never initialized at all on first install).
+- Added `registeredMonitor`/`registeredMonitorName` fields to
+  `einsatz.json.current`/`.history10`.
+- Reworked logging: translated all remaining German log text to
+  English; implemented the official first-occurrence-`warn`/
+  repeat-`debug`/recovery-`info` pattern for recurring failures (session
+  cookie, registration, connection); capped noisy Socket.IO ping/pong
+  debug logging; a sustained flood of wrong-monitor events now escalates
+  to `warn` instead of staying at `info` indefinitely. See
+  [LOGGING.md](LOGGING.md) for the full reference.
+- Documentation: added a table of contents, a practical-use-cases
+  section, a known-limitation note (only the single most recently active
+  incident is shown - see [`einsatz`](#einsatz)), and enforced the
+  changelog's own 5-entry limit.
+
 ### 0.7.16 (2026-08-22)
 
 - Fixed two stale-data gaps around incident transitions:
@@ -289,83 +432,6 @@ matters in the moment, so only the most recent one is kept.
   minor only for security fixes; development: minor allowed too).
 - No runtime changes.
 
-### 0.7.13 (2026-08-22)
-
-- Addressed all remaining `ioBroker.repositories` checker suggestions:
-  - **[S0065]**/**[S0085]**/**[S0087]**: added devDependencies
-    `@types/node` and `@tsconfig/node22`, plus a `tsconfig.json` for
-    editor tooling (no `checkJs`, so this doesn't introduce any new
-    type-check warnings).
-  - **[S4036]**: added `.vscode/settings.json` with JSON schemas for
-    `io-package.json`/`admin/jsonConfig.json`.
-  - **[S5026]**: added the `release-script-plugin-manual-review`
-    plugin (adds a confirm-before-commit step to interactive
-    `npm run release` runs only).
-  - **[S8913]**: added a Dependabot auto-merge workflow for
-    patch/minor updates; major version bumps still require manual
-    review.
-  - No runtime changes.
-
-### 0.7.12 (2026-08-21)
-
-- Fixed **[E3005]**: `einsatz.permissions` is declared as
-  `common.type: "string"`, but `setField()` passed raw
-  booleans/numbers through unchanged (the WAIP server sends this
-  field as a raw boolean flag), so the stored `val` didn't match the
-  declared type. `setField()` now looks up the declared type and
-  always stringifies values for string-typed states, regardless of
-  the incoming JS type - found by the `ioBroker.repositories` object
-  structure check.
-
-### 0.7.11 (2026-08-21)
-
-- Fixed **[E3009]** (57 findings): added the missing channel/folder
-  objects (`status`, `einsatz`, `einsatz.rueckmeldungAnzahl`, `debug`,
-  `tts`) that ioBroker requires for every state path segment - found
-  by the `ioBroker.repositories` object structure check.
-- Fixed **[E3005]**/**[E1009]**: replaced the unsupported
-  `common.type: "mixed"` on `einsatz.permissions` (now `string`) and
-  `status.registrationAccepted` (now split into two booleans:
-  `registrationAccepted` and the new `registrationPending`).
-
-### 0.7.10 (2026-08-21)
-
-- Fixed **[S9508]**: excluded `CHANGELOG_OLD.md` from the npm package
-  (removed from `package.json`'s `files` allowlist) - ioBroker shows
-  the README via a GitHub link, not from the installed npm package, so
-  the file remains fully readable on GitHub without needing to ship
-  inside the tarball.
-
-### 0.7.9 (2026-08-21)
-
-- Fixed **[E5025]**/**[E5036]**: installed the missing
-  `@alcalzone/release-script-plugin-license` dev dependency required
-  for the `"license"` plugin referenced in `.releaseconfig.json`.
-
-### 0.7.8 (2026-08-21)
-
-- Fixed **[E5018]**: added the missing `.releaseconfig.json` (`plugins:
-  iobroker, license`) required now that `@alcalzone/release-script` is
-  a dev dependency - caught by the `ioBroker.repositories` "ADD TO
-  LATEST" submission check.
-
-### 0.7.7 (2026-08-21)
-
-- Fixed **[E254]**: removed the orphaned `0.7.5` entry from
-  `common.news` - like `0.7.0` and `0.7.3` before it, that version was
-  never actually tagged/published to npm (`0.7.4` was followed directly
-  by `0.7.6`, which is now confirmed live under `latest`).
-
-### 0.7.6 (2026-08-21)
-
-- Fixed **[W6019]** and **[W0062]**: added `@alcalzone/release-script`
-  and `@alcalzone/release-script-plugin-iobroker` as dev dependencies
-  (with an `npm run release` script), and split this changelog - the 5
-  most recent entries stay here, everything older moved to
-  [CHANGELOG_OLD.md](CHANGELOG_OLD.md). Our existing manual
-  version-bump/tag workflow (see below) is unchanged; the tool is
-  available but not actively used for releasing yet.
-
 Older entries have moved to [CHANGELOG_OLD.md](CHANGELOG_OLD.md).
 
 ## License