Home Assistant → Gladys-Migrationswerkzeug: Vorstellung, Spezifikationen und Änderungen am Kern

Hallo zusammen,

Im Anschluss an die Diskussion https://community.gladysassistant.com/t/rebond-sur-le-sujet-transfert-zigbee2mqtt-ha-vers-gladys beginne ich mit einem Migrationswerkzeug von Home Assistant zu Gladys. Dieser Thread dient dazu, das Projekt vorzustellen, die wenigen Änderungen am Kern zu erklären und zu diskutieren, die es erfordert, und eure Meinungen einzuholen, bevor ich die erste Codezeile schreibe.

Warum

Home Assistant für Gladys zu verlassen, bedeutet heute, alles von Hand neu zu machen: Geräte, Räume, Benutzer, Szenen… und den Verlauf zu verlieren. Diese Exit-Kosten halten viele Neugierige zurück. Das Ziel ist, dass ein „standardmäßiger“ HA-Benutzer in weniger als einer Viertelstunde migrieren kann und genau weiß, was nicht migriert werden kann und warum.

Was das Tool macht

Ein in Gladys integrierter Service, zugänglich:

  • ab dem ersten Start, neben „Gladys Plus-Sicherung wiederherstellen“;
  • dann unter Einstellungen → Migration.

Version 1

  • Analyse der HA-Installation mit einem Kompatibilitätsbericht pro Gerät: migrierbar, teilweise, über eine Alternative, nicht migrierbar, ignoriert.
  • Installation der notwendigen Integrationen aus dem Store, durch Ankreuzen von Kästchen.
  • Geräte (mit ihrem Namen und ihrem Raum), Räume, Benutzer und Dienstintegrationen (Wetter, Kalender, Benachrichtigungen…).
  • HA-Eingaben (Urlaubsmodus, einstellbare Vorgaben, Zähler) werden in virtuelle Geräte umgewandelt.
  • Anwesenheit: Netzwerk- und Bluetooth-Tracker werden Benutzern, Zonen, Ankünften und Abfahrten zugeordnet.
  • HA-Zusatzmodule (Mosquitto, Zigbee2MQTT, Node-RED, Frigate…) werden ihrer Gladys-Entsprechung zugeordnet: native Dienste oder Store-Integrationen.
  • Vollständige Verläufe: Langzeitstatistiken und aktuelle Zustände, einschließlich Energiezähler, mit einer Schätzung des benötigten Speicherplatzes.
  • HA-Szenen (die „Stimmungen“: Lampe auf 20 %, Rollläden geschlossen…) und einfache Skripte, die in Gladys-Szenen umgewandelt werden, die manuell gestartet werden können.
  • Einfache Automatisierungen: Zeitpläne, Sonnenauf- und -untergang, erkanntes Bewegung oder Öffnen, Temperaturschwellen… Die anderen werden in einer lesbaren Form präsentiert, mit einem vorgefüllten Szenenentwurf, damit der Benutzer sie selbst neu erstellt. Das ist auch eine gute Möglichkeit, den Gladys-Szeneneditor kennenzulernen.
  • Was es im Kern nicht gibt (die Sonne, Werktage…), kann auf einem Gerät basieren, das Sie bereits haben, auf einem virtuellen Gerät oder auf einer Integration: Das Tool fragt Sie einfach, welches Sie verwenden möchten.
  • Dashboards: Ein Dashboard „Startseite“ wird aus dem Migrierten generiert (Räume, Stimmungen, Wetter, Kameras, Energie), um nie auf einer leeren Seite zu landen. Ihre HA-Dashboards werden im Anschluss in annähernder Form übernommen.

Version 2

  • Ein Assistent zur Migration komplexerer Automatisierungen und Skripte mit Parametern, der sich mit dem Gladys-Szenenmotor weiterentwickelt.

Einige Prinzipien

  • Nur-Lesen auf HA-Seite: Das Tool ändert dort streng genommen nichts.
  • Zwei Modi: Koexistenz (man probiert Gladys aus, ohne HA zu stoppen) oder Umstellung. Man wechselt zwischen ihnen, indem man das Tool neu startet.
  • Garantierte Abbruchmöglichkeit: Das Tool macht nur rückgängig, was es gemacht hat, und setzt Gladys genau in den vorherigen Zustand zurück.
  • Nichts verlässt die Instanz. Der Token und die HA-Passwörter bleiben im Speicher, solange es nötig ist.
  • Wiederholbar: Man startet das Tool neu, um das zu übernehmen, was sich in HA geändert hat, ohne Dopplungen zu erzeugen.

Für Geräte ohne Gladys-Integration ermutigt das Tool den Benutzer zunächst, sie selbst zu erstellen, dank des offiziellen Integrationsmodells. Andernfalls schlägt es vor, eine Anfrage in „Funktionsanfragen“ zu veröffentlichen, mit einer bereits verfassten Nachricht.

Wie es funktioniert, kurz gesagt

Das Tool „erstellt“ keine Geräte. Es installiert die passende Gladys-Integration, lässt sie die Geräte entdecken, und ordnet dann jedes HA-Gerät dem entdeckten Gerät über einen Hardware-Schlüssel zu: MAC-Adresse, Zigbee-Adresse (IEEE), Seriennummer… Es wendet dann den Namen und den Raum aus HA an. Diese Funktionsweise funktioniert sowohl mit den nativen Integrationen als auch mit denen aus dem Store.

Die Untersuchung des Codes der 12 am häufigsten verwendeten HA-Integrationen zeigt, dass für 8 davon diese Zuordnung sicher ist: Zigbee (Zigbee2MQTT und ZHA), Shelly, Tuya, Google Cast, UPnP, DLNA… Keine davon ist vollständig manuell.

Was ich vom Kern verlange (zur Diskussion)

Ich habe versucht, das Herz so wenig wie möglich zu berühren. Die notwendigen Bibliotheken (Archivlesen, YAML, Entschlüsselung der letzten HA-Sicherungen) bleiben dienstspezifisch, wie yaml für zigbee2mqtt.

# Änderung Warum
1 Drei neue Tabellen t_migration_run, t_migration_item und t_migration_history_cursor Verfolgen, was importiert wurde: Neustart ohne Duplikate, Wiederaufnahme nach Unterbrechung, exakte Stornierung. Kein vorhandenes Modell wird geändert. Die Tabellen haben eine Spalte source, um eines Tages anderen Systemen (Jeedom, Domoticz…) zu dienen.
2 Eine Seite Einstellungen → Migration und eine Zeile auf dem Startbildschirm Eingabepunkte des Tools
3 Reservierte Parameter GLADYS_HW_* (GLADYS_HW_MAC, GLADYS_HW_IEEE, GLADYS_HW_SERIAL, GLADYS_HW_UDN…), nach dem Vorbild von GLADYS_TRANSPORT Jede Integration veröffentlicht die Hardware-Identität ihrer Geräte in einer standardisierten Form. Die Zuordnung wird dann generisch, ohne Regeln, die pro Integration geschrieben werden müssen. Vorteil über die Migration hinaus: Erkennen eines Geräts, das von zwei Integrationen gesehen wird, und Vorschlag von device.migrate. :warning: Ein alter Kern lehnt unbekannte GLADYS_* ab: Es ist das SDK, das sie nur an Versionen sendet, die sie akzeptieren.
4 (Optional) Eine Route zum Hochladen von HA-Sicherungen im Stream Nur nützlich, wenn HA nicht verfügbar ist. Im normalen Fall lädt Gladys die Sicherung selbst von HA herunter (wie bei Gladys Plus), bereits von HA entschlüsselt. Der Körper der JSON-Anfragen ist heute auf 100 KB begrenzt.

Ein weiterer Punkt der Aufmerksamkeit: Die tägliche Löschung der Zustände (standardmäßig 90 Tage) würde den importierten Verlauf löschen. Das Tool wird daher vorschlagen, die Aufbewahrung auf „unbegrenzt“ zu setzen, eine Einstellung, die der Benutzer später ändern kann. Dies erfordert keine Änderung des Kerns, aber ich möchte, dass es gesagt wird.

Entwicklungsmöglichkeiten des Kerns (für V2 und darüber hinaus)

Bei der Untersuchung des Szenarienmotors für die Umwandlung von HA-Automatisierungen habe ich Lücken festgestellt. Diese zu schließen würde direkt erhöhen, was das Tool konvertieren kann. Sie sind nicht für V1 notwendig: Es sind Vorschläge zur Diskussion.

# Spur Interesse
P1 Ausführungsmodi von Szenen („ignorieren, wenn bereits aktiv“, „neustarten“, „in Warteschlange stellen“) Heute laufen alle Ausführungen einer Szene parallel. Eine Szene mit einer Wartezeit kann daher mehrere Male gleichzeitig starten. Das ist der größte Gewinn.
P2 Aktion „Szene stoppen“ Timer-basierte Motive
P3 Bedingung solar (es ist Tag oder Nacht, vor oder nach dem Sonnenuntergang) Beleuchtung, Rollläden. In der Praxis deckt ein „Tag/Nacht“-Gerät den Bedarf bereits ab. Eine kleine „Sonne“-Integration (Tag/Nacht-Zustand, Elevation, Azimut) wäre im Store willkommen.
P4 Bedingung der Dauer („in diesem Zustand seit N Minuten“) Warnungen
P5 Auslöser der Ursache der Szene, die in den Bedingungen verwendbar ist Szenen mit mehreren Auslösern und mehreren Verhaltensweisen
P6 Bedingung oder Auslöser „Gerät erreichbar / aktueller Wert“ (Gladys berechnet bereits „kein aktueller Wert“, aber nur für die Anzeige) Warnungen „dieser Sensor antwortet nicht mehr“, Verhalten ähnlich wie HA bei nicht verfügbaren Geräten

Dabei habe ich einen Bug gefunden: Ein Auslöser „MQTT-Nachricht empfangen“, dessen Topic ein Joker (+ oder #) enthält, wird nie ausgelöst. Ticket: Scene trigger "MQTT message received" never fires when the topic contains a wildcard (+ or #) · Issue #3400 · GladysAssistant/Gladys · GitHub. Ein Fix wird vorgeschlagen und wartet auf die Überprüfung durch einen Maintainer: fix: fire "MQTT message received" scene trigger on wildcard topics (#3400) by Pierre-Gilles · Pull Request #3401 · GladysAssistant/Gladys · GitHub.

Was ich von den Integrationsentwicklern verlangen werde

Nicht viel, und nur beim nächsten SDK-Update:

  1. die Hardware-Identität Ihrer Geräte mit Hilfe des SDK veröffentlichen (Punkt 3 oben);
  2. falls nötig, eine kleine Datei gladys-migration.json an die Wurzel Ihres Repositorys hinzufügen. Sie beschreibt die Ausnahmen (Funktionsnamen, die sich von HA unterscheiden, Einheitenumrechnungen) und die Einstellungen, die von HA übernommen werden sollen (Adresse eines Brokers, ESPHome-Verschlüsselungsschlüssel…). Das integration-template-js wird ein Beispiel enthalten.

Mit @Will_71 und seinem Tracker

Er schlug einen sogenannten Katalog der Korrespondenz HA → Gladys vor, der sich auf den Tracker der Integrationen von @Will_71 stützt. Er verbindet bereits die HA-Integrationen und Gladys vollständig automatisch. Es müsste nur noch die Sammlung der Dateien gladys-migration.json und eine Spalte „HA-Migration“ hinzugefügt werden. Sobald alle Integrationen erstellt sind, würde der Tracker weiterhin das Werkzeug sein, das die Abdeckung der Migration misst. William, was denkst du?

Stand der Dinge

Die Spezifikationen der V1 sind auf Französisch verfasst, bis ihre englische Version für den Pull Request zu Gladys fertig ist: GitHub - gboulvin/HA2Gladys-Migration-Tool · GitHub

Abschnitt Inhalt
00 — Vision Ziele, Umfang, Entscheidungen
01 — Architektur Kerndienst, Tabellen, Sicherheit, Stornierung
02 — HA-Lesevorgang API, Backups (einschließlich verschlüsselte), Historie
03 — Korrespondenzen Katalog, Abgleich, Räume, Personen, HA-Eingänge, Zusatzmodule
04 — Szenen HA-Szenen und Skripte, einfache Automatisierungen, Anwesenheit, Ersatz
05 — Abläufe Die Bildschirme des Assistenten
06 — Tests 100%ige Abdeckung, CI für HA-Versionen im Überwachungsmodus
07 — Historie Import, Energie, Löschung
08 — Dashboards Generiertes Startbildschirm, Übernahme der HA-Dashboards

Die gesamte Arbeit soll der Organisation GladysAssistant zur Verfügung gestellt werden, sobald sie gemerged wurde.

Wie Sie helfen können

  • Ihre Meinungen zu den Änderungen im Kern, insbesondere zu den Parametern GLADYS_HW_*.
  • Echte HA-Backups, die ich mit einem bereitgestellten Skript anonymisieren kann (Namen, Adressen, Seriennummern werden ersetzt, Geheimnisse gelöscht). Sie dienen zum Testen auf echten Installationen und zur Leistungsmessung. Sie werden niemals veröffentlicht.
  • Tester für das Test-Docker-Image, das hier vor dem finalen Pull Request angekündigt wird.

Keine Entwicklung wird ohne eine Prinzipienvalidierung vorgenommen. Ich appelliere daher an die Nutzer und Entwickler von Gladys und/oder HA, Kommentare zu hinterlassen (hier oder auf GitHub), Vorschläge zu machen…

Vielen Dank im Voraus für Ihr Feedback!