From c00a3a86519e802f88126adb003e472d3d546a2d Mon Sep 17 00:00:00 2001 From: MaPaLo76 <72209721+MaPaLo76@users.noreply.github.com> Date: Wed, 4 Mar 2026 19:44:51 +0100 Subject: [PATCH] docs(readme): v1.5.0 HA Discovery, Topics, LWT, status-JSON aktualisiert --- README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 55 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 61567f0..48741fd 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,8 @@ Das Bild zeigt die physische Anordnung der 8 GYMAX7219-Module im 4×2-Format mit └──────┘ └──────┘ └──────┘ └──────┘ ``` -> **Hinweis:** Die untere Reihe läuft im Schaltbild von rechts nach links, weil DOUT von Modul 4 -> direkt zu DIN von Modul 5 geführt wird. MD_Parola berücksichtigt das automatisch. +> **Hinweis:** Die untere Reihe läuft im Schaltbild von ebenfalls von links nach rechts, weil DOUT von Modul 4 +> zu DIN von Modul 5 geführt wird. --- @@ -252,11 +252,13 @@ Der ESP32 verbindet sich mit einem MQTT-Broker (konfigurierbar über Webinterfac ### Topics -| Richtung | Topic | Format | Beschreibung | -|------------|---------------------------|------------------------------|-----------------------------------------| -| Publish | `lasercutter/session` | JSON | Wird beim **Ende eines Laser-Bursts** oder nach **Session-Reset** gesendet | -| Publish | `lasercutter/status` | JSON (retained) | Heartbeat alle 60 Sekunden + LWT (online/offline) | -| Subscribe | `lasercutter/cmd` | JSON | Steuerkommandos: Reset, Display, Reboot | +| Richtung | Topic | Format | Beschreibung | +|------------|---------------------------------|------------------------------|-----------------------------------------| +| Publish | `lasercutter/session` | JSON | Wird beim **Ende eines Laser-Bursts** oder nach **Session-Reset** gesendet | +| Publish | `lasercutter/status` | JSON (retained) | Heartbeat alle 60 Sekunden | +| Publish | `lasercutter/availability` | `online` / `offline` | Verbindungsstatus (retained, LWT) | +| Subscribe | `lasercutter/cmd` | JSON | Steuerkommandos: Reset, Display, Reboot | +| Publish | `homeassistant/…/config` | JSON (retained) | HA MQTT Discovery – nach jedem Connect | ### JSON-Format `lasercutter/session` ```json @@ -278,16 +280,23 @@ Der ESP32 verbindet sich mit einem MQTT-Broker (konfigurierbar über Webinterfac ```json { "online": true, + "laser_active": false, "session_sum": "42.50", + "session_minutes_sum": 42, + "session_seconds": 30, "machine_running_time_min": "1234.75", + "total_minutes": 1234, "display_on": true, "ip": "192.168.1.100", "uptime_s": 3600, - "firmware_version": "1.2.1 (Mar 1 2026)", + "firmware_version": "1.5.0 (Mar 4 2026)", "reset_reason": "POWERON" } ``` +> `laser_active` – `true` wenn der Laser gerade ein aktives Burst meldet. +> `session_minutes_sum` / `session_seconds` sind Integer-Felder für HA-`value_template`. +> `total_minutes` entspricht `machine_running_time_min` als Integer-Minuten. > `reset_reason` mögliche Werte: `POWERON`, `SOFTWARE`, `PANIC`, `TASK_WDT`, `INT_WDT`, `WDT`, `BROWNOUT`, `EXT_PIN`, `DEEPSLEEP`, `SDIO`, `UNKNOWN`. Der Wert wird einmalig beim Start gespeichert und bleibt für die gesamte Laufzeit konstant. ### JSON-Format `lasercutter/cmd` @@ -304,10 +313,14 @@ Alle Steuerkommandos werden als JSON an `lasercutter/cmd` gesendet: > Mehrere Kommandos können in einem JSON kombiniert werden, z. B. `{"reset_session_ram":true, "display":false}`. -### LWT (Last Will and Testament) -Bei Verbindungsabbruch sendet der Broker automatisch auf `lasercutter/status`: -```json -{"online": false} +### LWT (Last Will and Testament) & Availability +Der Client setzt beim Connect ein LWT auf `lasercutter/availability` mit Payload `offline`. +Nach erfolgreichem Connect publiziert er sofort `online` (retained) auf dasselbe Topic. +Bei Verbindungsabbruch sendet der Broker automatisch `offline`. + +``` +lasercutter/availability → "online" (nach Connect, retained) +lasercutter/availability → "offline" (LWT bei Verbindungsabbruch) ``` ### Verhalten @@ -318,6 +331,36 @@ Bei Verbindungsabbruch sendet der Broker automatisch auf `lasercutter/status`: --- +## Home Assistant MQTT Discovery + +Ab **v1.5.0** meldet sich der ESP32 automatisch als vollständiges HA-Device an, ohne manuelle Einträge in `configuration.yaml`. + +### Funktionsweise + +Nach jedem (Re-)Connect publiziert der Client 8 retained JSON-Nachrichten an +`homeassistant//lasercutter-display//config`. +Home Assistant erkennt das Device daraufhin automatisch und zeigt alle Entities gruppiert an. + +### Entities + +| HA-Typ | Name im HA | Quelle (`lasercutter/status`) | +|-----------------|-------------------------|---------------------------------------| +| `binary_sensor` | Laser aktiv | `laser_active` | +| `sensor` | Laserzeit Summe | `session_minutes_sum` (min) | +| `sensor` | Laserzeit aktuell (s) | `session_seconds` (s) | +| `sensor` | Gesamtlaufzeit | `total_minutes` → Jinja2 `hh:mm` | +| `sensor` | Firmware | `firmware_version` (Diagnose) | +| `switch` | Display | `display_on` → `ON`/`OFF` | +| `button` | Session zurücksetzen | → `lasercutter/cmd` `{"reset_session_ram":true}` | +| `button` | Neustart | → `lasercutter/cmd` `{"reboot":true}` | + +### Voraussetzungen + +- MQTT-Integration in HA aktiviert und mit demselben Broker verbunden. +- Discovery-Prefix bleibt auf Standard `homeassistant` (konfigurierbar in `config.h`). + +--- + ## Webinterface Das Webinterface ist über die IP-Adresse des ESP32 im Browser erreichbar.