UniFi-Gast-WLAN automatisch wechseln und mit WELIQ anzeigen

Das Ergebnis:

• jeden Tag ein neues, zufälliges Gast-WLAN-Kennwort,
• automatische Übernahme in UniFi,
• Aktualisierung des QR-Codes und Klartextkennworts auf WELIQ,
• Gültigkeitsdatum auf dem WELIQ-Display,
• Status- und Klartextanzeige in einem Home-Assistant-Dashboard,
• manuelle Rotation über einen Dashboard-Knopf,
• Fehlermeldung in Home Assistant, wenn ein Schritt scheitert.

Sicherheitshinweis: Das Dashboard zeigt das Gastkennwort in diesem Beispiel bewusst im Klartext. Das Dashboard darf deshalb nur für vertrauenswürdige Home-Assistant-Benutzer zugänglich sein.

Getestet mit

Die lokalen UniFi-Schnittstellen sind nicht dauerhaft garantiert (siehe Abschnitt 12). Nach Updates den Funktionstest wiederholen.

Systemaufbau

                         täglich 00:30 Uhr
                                │
                                ▼
                       ┌─────────────────┐
                       │ Home Assistant  │
                       │ Zufallskennwort │
                       └────────┬────────┘
                                │
                 1. UniFi ändern│2. WELIQ aktualisieren
                                │
                 ┌──────────────┴──────────────┐
                 ▼                             ▼
        ┌─────────────────┐          ┌─────────────────┐
        │ UniFi Network   │          │ WELIQ Hub       │
        │ Gast-WLAN       │          │ E-Ink + QR-Code │
        └─────────────────┘          └─────────────────┘

Home Assistant ist die zentrale Steuerung. Es erzeugt das Kennwort, übergibt es zuerst an UniFi und sendet denselben Wert danach an die lokale WELIQ-API.

Die Reihenfolge ist wichtig: Das Display darf erst dann das neue Kennwort anzeigen, wenn UniFi die Änderung akzeptiert hat.

Voraussetzungen

Benötigt werden:

• eine laufende Home-Assistant-Installation,
• ein UniFi-Controller beziehungsweise eine UniFi-Konsole,
• ein eingerichtetes Gast-WLAN, im Beispiel <UNIFI-WLAN-NAME>,
• ein WELIQ Hub mit Firmware 0.72 oder neuer,
• WELIQ in der Betriebsart Local API,
• WELIQ und Home Assistant im Verwaltungs- oder IoT-Netz,
• Netzwerkzugriff von Home Assistant auf UniFi und WELIQ,
• ein lokales UniFi-Konto mit Schreibrechten für die Network-Anwendung.

Der WELIQ Hub gehört nicht in das rotierende Gastnetz. Sonst verliert er nach jeder Kennwortänderung seine eigene Verbindung.

WELIQ vorbereiten

Local API aktivieren

In der WELIQ-Weboberfläche:

1. Menü API öffnen.
2. Betriebsart Local API auswählen.
3. Einen API-Schlüssel erzeugen.
4. Den Schlüssel sofort sicher speichern. Er wird nur einmal vollständig angezeigt.

Der Schlüssel hat dieses Format:

weliq_<40 Hex-Zeichen>

In Home Assistant wird er nicht direkt in einer Automation hinterlegt, sondern in secrets.yaml:

weliq_bearer: "Bearer weliq_<API-SCHLUESSEL>"

Stromversorgung

Für eine tägliche automatische Aktualisierung ist USB-C am einfachsten. Der Hub ist damit dauerhaft erreichbar.

Im Akkubetrieb ist die API nur während des Aufwachfensters verfügbar. Dann müssen Rotation und WELIQ-Aufwachfenster zeitlich aufeinander abgestimmt oder über das Wake-Signal gekoppelt werden.

UniFi vorbereiten

Für die Automation sollte ein eigenes lokales UniFi-Konto verwendet werden.

Empfehlung:

• separates Konto nur für die Automation,
• Zugriff auf die Anwendung Network,
• Berechtigung zum Lesen und Ändern von WLAN-Konfigurationen,
• kein Cloud-Konto verwenden, wenn ein lokales Konto ausreicht,
• kein Konsolenbesitzer- oder Super-Admin-Recht vergeben, wenn eine eingeschränkte Network-Rolle verfügbar ist.

Die Rolle Hotspot Operator genügt nicht. Sie darf typischerweise Hotspot-Gäste oder Gutscheine verwalten, aber keine SSID- beziehungsweise WPA-Konfiguration ändern. Ein Änderungsversuch endet dann mit HTTP 403.

Kennwortregeln

WELIQ Firmware 0.72 akzeptiert WLAN-Kennwörter mit 8 bis 20 Zeichen. Für eine problemlose Übergabe an QR-Code, UniFi und JSON empfiehlt sich ein reduzierter Zeichensatz.

Das Beispiel verwendet:

• 16 Zeichen,
• Großbuchstaben,
• Kleinbuchstaben,
• Ziffern,
• kryptografisch sichere Erzeugung mit Python secrets.choice().

import secrets
import string

alphabet = string.ascii_letters + string.digits
password = "".join(secrets.choice(alphabet) for _ in range(16))

Das Kennwort darf nicht in Protokolle, Fehlermeldungen oder Benachrichtigungen geschrieben werden.

Ablauf der Rotation

Die Rotation besteht aus fünf Schritten:

1. Home Assistant erzeugt ein neues Kennwort.
2. Das Skript meldet sich lokal am UniFi-Controller an.
3. Das WLAN wird anhand seines Namens gesucht und das Kennwort geändert.
4. Erst nach erfolgreicher UniFi-Antwort werden dieselben Daten an WELIQ gesendet.
5. Home Assistant aktualisiert Dashboard und Status.

Läuft die Rotation nicht (zum Beispiel weil Home Assistant nicht erreichbar ist), bleibt das Ablaufdatum auf dem Display stehen. Ein Hub am USB-C zeigt dann ab 00:00 Uhr „abgelaufen“. Das ist gewollt: Ein Ausfall wird sichtbar und nicht still hingenommen. Zwischen 00:00 und 00:30 Uhr zeigt ein USB-C-Hub deshalb kurz diese Meldung.

Der WELIQ-Aufruf verwendet:

POST https://<WELIQ-IP>/api/v1/wifi
Authorization: Bearer weliq_<API-SCHLUESSEL>
Content-Type: application/json; charset=utf-8

Beispielinhalt:

{
  "ssid": "<UNIFI-WLAN-NAME>",
  "password": "<NEUES-KENNWORT>",
  "valid_until": "2026-10-30",
  "hidden": false
}

valid_until gilt bei WELIQ einschließlich des angegebenen Tages. In dieser Umsetzung wird ausschließlich der aktuelle Tag als Ablaufdatum übertragen; valid_from wird nicht gesendet. Die Zeit zwischen 00:00 Uhr und der nächsten Rotation um 00:30 Uhr wird bewusst nicht zusätzlich überbrückt.

Eine erfolgreiche WELIQ-Antwort sieht beispielsweise so aus:

{
  "result": "applied",
  "active_from": "2026-10-30",
  "display_updated": true
}

Home-Assistant-Konfiguration

Die Umsetzung besteht aus einem Python-Skript und einem Home-Assistant-Paket.

Beispielpfade:

/config/scripts/weliq_guest_rotation.py
/config/packages/weliq.yaml

Das Skript und das Paket liegen als Dateien bei (weliq_guest_rotation.py, weliq_homeassistant_package_unifi_beispiel.yaml). Im Skript ist der Name des UniFi-WLANs oben als Konstante SSID einzutragen. Es liest die UniFi-Zugangsdaten aus der UniFi-Integration von Home Assistant, den WELIQ-Schlüssel aus secrets.yaml und die Hub-IP aus dem Wake-Signal. Für die UniFi-Integration sollte deshalb das eingeschränkte Automationskonto aus Abschnitt 4 verwendet werden.

Skriptaufrufe: rotate (Kennwort wechseln), sync [IP] (letzten Datensatz erneut senden), check (Konfiguration prüfen), dashboard (Daten für die Anzeige).

Shell-Befehle

shell_command:
  weliq_guest_wifi_rotate: >-
    python3 /config/scripts/weliq_guest_rotation.py rotate
    > /config/weliq_guest_rotation_last.json 2>&1

  weliq_guest_wifi_sync: "python3 /config/scripts/weliq_guest_rotation.py sync {{ ip }}"

Die IP stammt aus dem Wake-Signal des Hubs. Weil sie in einen Aufruf eingesetzt wird, lässt die Wake-Automation im Paket nur gültige IPv4-Adressen zu.

Die Statusdatei darf niemals das Kennwort oder andere Zugangsdaten enthalten.

Manueller Knopf

input_button:
  weliq_guest_wifi_rotate_now:
    name: Gast-WLAN Kennwort jetzt wechseln
    icon: mdi:key-refresh

Zeitautomation

automation:
  - id: weliq_guest_wifi_nightly_rotation
    alias: WELIQ - Gast-WLAN nachts rotieren
    mode: single
    triggers:
      - trigger: time
        at: "00:30:00"
      - trigger: state
        entity_id: input_button.weliq_guest_wifi_rotate_now
    actions:
      - action: shell_command.weliq_guest_wifi_rotate
        continue_on_error: true
        response_variable: rotation

      - choose:
          - conditions:
              - condition: template
                value_template: >-
                  {{ rotation is defined and rotation.returncode == 0 }}
            sequence:
              - action: homeassistant.update_entity
                target:
                  entity_id: sensor.gast_wlan_kennwort
              - action: persistent_notification.dismiss
                data:
                  notification_id: weliq_guest_wifi_rotation_failed
        default:
          - action: persistent_notification.create
            data:
              notification_id: weliq_guest_wifi_rotation_failed
              title: Gast-WLAN/WELIQ Aktualisierung fehlgeschlagen
              message: >-
                Die automatische Rotation war nicht vollständig erfolgreich.
                Bitte UniFi, WELIQ und die Automation prüfen.

Kennwort im Dashboard anzeigen

Die Klartextanzeige ist optional. Wer sie verwendet, sollte den Zugriff auf das Dashboard einschränken.

Wichtig: Der Sensor trägt das Kennwort als Zustand. Home Assistant würde es sonst in Verlauf, Logbuch und Datenbank (und damit in Backups) speichern. Den Sensor deshalb vom Recorder und vom Logbuch ausnehmen:

recorder:
  exclude:
    entities:
      - sensor.gast_wlan_kennwort
logbook:
  exclude:
    entities:
      - sensor.gast_wlan_kennwort

Ein Command-Line-Sensor kann den zuletzt erfolgreich erzeugten Datensatz aus einer lokalen, nur für den Besitzer lesbaren Zustandsdatei übernehmen:

command_line:
  - sensor:
      name: Gast-WLAN Kennwort
      unique_id: gast_wlan_kennwort
      command: "python3 /config/scripts/weliq_guest_rotation.py dashboard"
      value_template: "{{ value_json.password }}"
      json_attributes:
        - ssid
        - valid_until
        - last_rotation
        - weliq_updated_at
        - weliq_result
      scan_interval: 60

Eine einfache Markdown-Karte:

type: markdown
title: Gast-WLAN
content: >-
  ## {{ state_attr('sensor.gast_wlan_kennwort', 'ssid') or '<UNIFI-WLAN-NAME>' }}

  **Kennwort:** `{{ states('sensor.gast_wlan_kennwort') }}`

  Gültig bis:
  **{{ state_attr('sensor.gast_wlan_kennwort', 'valid_until') or 'unbekannt' }}**

Ein Knopf für die manuelle Rotation:

type: button
name: Kennwort jetzt wechseln
icon: mdi:key-refresh
tap_action:
  action: call-service
  service: input_button.press
  target:
    entity_id: input_button.weliq_guest_wifi_rotate_now
  confirmation:
    text: >-
      Gast-WLAN-Kennwort wirklich sofort wechseln?
      Verbundene Gäste werden getrennt.

Zustandsdatei absichern

Damit ein WELIQ-Wake-Signal den zuletzt gültigen Datensatz erneut senden kann, muss das aktuelle Gastkennwort lokal gespeichert werden. Die Datei sollte atomar geschrieben und ausschließlich für den Besitzer lesbar sein:

/config/.weliq_guest_rotation.json
Dateirechte: 600

Sie darf nicht in öffentliche Backups, Git-Repositories oder Support-Protokolle gelangen.

Fehlerbehandlung

UniFi antwortet mit HTTP 403

Das Konto besitzt keine ausreichenden Network-Rechte. Hotspot Operator genügt nicht. Benötigt wird eine Rolle, die WLAN-Konfigurationen ändern darf.

WELIQ antwortet mit HTTP 401

Der API-Schlüssel fehlt, ist falsch oder wurde neu erzeugt. Nach einer Neuerzeugung wird der alte Schlüssel ungültig.

WELIQ antwortet mit HTTP 403

Der Hub befindet sich nicht in der Betriebsart Local API.

WELIQ antwortet mit HTTP 429

Das Rate-Limit wurde erreicht oder die Quell-IP wurde nach mehreren ungültigen Schlüsseln kurz gesperrt.

WELIQ antwortet mit HTTP 503

Das Display ist beschäftigt oder der Hub befindet sich im Safe Mode. Bei display_busy nach der angegebenen Wartezeit erneut senden.

WELIQ ist nicht erreichbar

Bei Akkubetrieb schläft der Hub möglicherweise. Das Aufwachfenster oder Wake-Signal verwenden. Bei USB-C zusätzlich IP-Adresse, WLAN-Signal und Verwaltungsnetz prüfen.

Das Dashboard zeigt unknown

Nach der ersten erfolgreichen Rotation bis zu 60 Sekunden warten und die Seite neu laden. Vor der ersten Rotation existiert noch kein gespeicherter Kennwortdatensatz.

TLS und Zertifikate

UniFi und WELIQ werden ausschließlich über HTTPS angesprochen. Lokale Geräte verwenden häufig selbstsignierte Zertifikate oder Zertifikate, die nicht zur verwendeten IP-Adresse passen.

In diesem Beispiel ist die Zertifikatsprüfung für UniFi und WELIQ abgeschaltet, weil beide Geräte selbstsignierte Zertifikate verwenden. Das betrifft auch den UniFi-Login. Der WELIQ Hub prüft beim Wake-Signal über https:// das Zertifikat der Gegenstelle erst ab Firmware 0.76 und nur, wenn ein CA-Zertifikat hinterlegt ist. Dieses Beispiel wurde mit Firmware 0.75 getestet. Betreiben Sie deshalb alle drei Systeme in einem vertrauenswürdigen Verwaltungsnetz.

Die beste Lösung ist eine eigene lokale Zertifizierungsstelle und ein korrekt ausgestelltes Zertifikat. Wird die Zertifikatsprüfung für ein lokales Gerät deaktiviert, sollte Folgendes gelten:

• ausschließlich Zugriff im vertrauenswürdigen Verwaltungsnetz,
• feste Ziel-IP,
• keine Weiterleitung über das Internet,
• Netzwerkzugriff per Firewall begrenzen.

UniFi-Schnittstelle und Kompatibilität

Die hier verwendeten lokalen UniFi-Endpunkte können sich mit UniFi-OS- oder Network-Versionen ändern. Sie gehören nicht zu den langfristig stabil garantierten Home-Assistant-Diensten.

Vor einem Update sollte deshalb geprüft werden:

1. lokale Anmeldung weiterhin erfolgreich,
2. WLAN-Liste weiterhin abrufbar,
3. Kennwortänderung mit einem Test-WLAN möglich,
4. Rückgabecode und Antwortformat unverändert,
5. WELIQ-Aktualisierung weiterhin erfolgreich.

Ein optionaler Auslöser über einen Webhook ermöglicht die Rotation von außen (zum Beispiel aus einer anderen Automation). Wer ihn anlegt, muss eine lange Zufalls-ID verwenden und local_only: true setzen. Jeder im lokalen Netz, der die ID kennt, kann sonst eine Rotation auslösen und Gäste trennen. Ohne Bedarf weglassen.

Für eine allgemeine Veröffentlichung sollten Controller-Adresse, Site-ID, WLAN-ID, Benutzernamen, Passwörter, API-Schlüssel und Webhook-IDs immer durch Platzhalter ersetzt werden.

Funktionstest

Ein vollständiger Test sollte ohne aktive Gäste durchgeführt werden:

1. Aktuelles Gast-WLAN auf einem Testgerät vergessen.
2. Manuelle Rotation im Dashboard auslösen.
3. Prüfen, ob Home Assistant Erfolg meldet.
4. WELIQ-Display auf SSID, QR-Code und Gültigkeit kontrollieren.
5. QR-Code mit dem Smartphone scannen.
6. Verbindung zum Gast-WLAN herstellen.
7. Internetzugriff und Gastnetz-Isolierung prüfen.
8. Kontrollieren, ob Datum und letzter Wechsel im Dashboard aktualisiert wurden.

Fazit

Home Assistant verbindet UniFi und WELIQ zu einer vollständig lokalen Gast-WLAN-Lösung. UniFi bleibt für den eigentlichen WLAN-Zugang zuständig, WELIQ zeigt den QR-Code und das Kennwort an, und Home Assistant übernimmt Zeitplan, Zufallserzeugung, Synchronisierung, Überwachung und Bedienung.

Die wichtigsten Punkte für einen zuverlässigen Betrieb sind:

• eigenes Verwaltungsnetz für HA und WELIQ,
• ausreichend berechtigtes, aber möglichst eingeschränktes UniFi-Konto,
• kryptografisch erzeugtes Kennwort,
• UniFi immer vor WELIQ aktualisieren,
• keine Zugangsdaten in Logs,
• sichtbare Fehlermeldung statt stiller Teilerfolge,
• regelmäßiger Funktionstest nach Updates.

Dateien zum Herunterladen

• weliq_guest_rotation.py (Skript)
• weliq_homeassistant_package_unifi_beispiel.yaml (Home-Assistant-Paket)

Alle Namen, Adressen, Schlüssel und Kennungen in dieser Anleitung sind Platzhalter. Prüfen Sie Skript und Paket vor dem Einsatz in einer Testumgebung. Es gilt keine Zusage für andere Versionen von UniFi oder Home Assistant. Zurück zur Übersicht der Anbindungen