Home Assistant

Buchungskalender, Belegungssensoren, Schlösser in beide Richtungen, Zutritts-Ereignisse, Zählerstände und Raum-Displays mit der Home-Assistant-Integration.

Mit der Integration inwendo ERP für Home Assistant steuert ihr Gebäude nach euren Buchungen in vynst (inwendo ERP): Heizung vor dem Training an, Licht nach dem Ende aus, Tür für die gebuchte Gruppe auf. Die Integration ist Open Source: github.com/inwendo/iw_erp_homeassistant.

Was ihr bekommt

Funktion	Standard	Schalter in vynst
Kalender je Raum oder Objekt, sofort aktualisiert per Webhook, sonst alle 15 Minuten	an	–
Schlösser aus vynst als Home-Assistant-Schlösser	aus	–
Schlösser aus Home Assistant in vynst öffnen, mit den Zugriffsregeln von vynst	aus	–
Belegungssensoren: belegt, Vorlauf, geöffnet, nächste Buchung, Teilnehmer	aus	`integration_occupancy_api_enabled`
Ereignisse `iw_erp_access` und `iw_erp_check_in`, Sensor „Letzter Zutritt“	aus	`integration_ha_access_events_enabled`
Dienst `check_access` für Karten-, QR- und Tastaturleser	–	`integration_ha_access_check_enabled`
Dienst `create_ticket`, zum Beispiel bei Wasseralarm	–	`integration_ha_ticket_enabled`
Zählerstände aus vynst als Sensoren, Home-Assistant-Zähler an vynst melden	aus	`integration_usage_counter_api_enabled`
Raum-Displays auf OpenDisplay-E-Paper-Schildern	aus	–

Die Schalter in vynst stehen unter Einstellungen → Smart Home & Automationen und sind ab Werk aus. Ist eine Funktion in vynst aus, lässt die Integration sie mit einer Info-Zeile im Log weg.

Installation

In Home Assistant HACS → Integrationen → ⋮ → Benutzerdefinierte Repositories öffnen.
https://github.com/inwendo/iw_erp_homeassistant als Integration hinzufügen, „inwendo ERP“ installieren und Home Assistant neu starten.
Einstellungen → Geräte & Dienste → Integration hinzufügen → inwendo ERP.
Adresse eurer Instanz (https://eure-instanz.iw-erp.de) und einen API-Token eintragen.

Voraussetzung ist Home Assistant 2025.1 oder neuer.

API-Token

Legt den Token in vynst in den Benutzereinstellungen unter API-Zugänge an. Er braucht diese Rechte:

Recht	Wofür
Orte (`location`) lesen	Räume und Objekte, Belegung, Raum-Displays, Zähler lesen
Orte (`location`) schreiben	Zählerstände melden
Buchungen (`event_booking`) lesen und schreiben	Kalender und Webhook-Anmeldung
Veranstaltungen (`event`) schreiben	Schlösser an vynst anbieten, `check_access`
Tickets schreiben	`create_ticket`

Beschränkt den Token zusätzlich auf den Pfad /api/homeassistant/.*. Das .* am Ende ist nötig, damit es als Präfix gilt.

Webhook

Die Integration meldet beim Einrichten selbst einen Webhook bei vynst an (POST /api/homeassistant/webhook). Ändert sich eine Buchung, schickt vynst sofort ein Update.

vynst nimmt nur https://-Adressen mit öffentlichem Hostnamen an. Home Assistant braucht also eine externe URL (Einstellungen → System → Netzwerk, oder Home Assistant Cloud). Ohne sie fragt die Integration regelmäßig ab und meldet das unter Reparaturen.
vynst schickt den bei der Anmeldung übergebenen Token als X-IW-Webhook-Token zurück. Nur dann kommen Ereignisse mit verified: true an. Prüft verified, bevor eine Automation etwas Sicherheitsrelevantes tut.

Schlösser in beide Richtungen

Schlösser aus vynst importieren: Für jedes Schloss, das der Benutzer des Tokens öffnen darf, entsteht ein Schloss in Home Assistant. Öffnen läuft über vynst, das die Rechte prüft und ins Schloss-Protokoll schreibt.

Home-Assistant-Schlösser an vynst anbieten: Ihr wählt Schlösser aus, die Integration meldet sie und jede Zustandsänderung an vynst. Dort erscheinen sie als Smartlock-Verbindung mit dem Namen eures Home Assistant. Erst wenn ein Administrator in vynst die Geräte synchronisiert und Rechte vergibt, kann jemand öffnen. Befehle von vynst sind signiert:

Header X-IW-Signature: HMAC-SHA256 über den Inhalt mit einem Schlüssel, den nur diese Installation und vynst kennen
Befehle älter als zwei Minuten oder doppelt gesendete werden abgelehnt
nur ausgewählte Schlösser werden angenommen; aus vynst importierte Schlösser lassen sich nicht zurück anbieten

Beispiele

Licht an mit dem ersten Check-in im Studio:

triggers:
  - trigger: event
    event_type: iw_erp_check_in
    event_data:
      attendance_list_name: Fitnessstudio
      checked_in: true
actions:
  - action: light.turn_on
    target:
      entity_id: light.studio

RFID-Leser prüft bei vynst und öffnet:

triggers:
  - trigger: event
    event_type: esphome.rfid_scanned
actions:
  - action: iw_erp_homeassistant.check_access
    data:
      credential: "{{ trigger.event.data.uid }}"
      credential_type: card
      lock: lock.haupteingang
    response_variable: access
  - if: "{{ access.granted }}"
    then:
      - action: lock.open
        target:
          entity_id: lock.haupteingang

Die Antwort enthält granted, reason (granted, unknown_credential, no_access, invalid_code, code_expired), person und opened.

Ticket bei Wasseralarm, ohne Dubletten:

actions:
  - action: iw_erp_homeassistant.create_ticket
    data:
      title: Wasseralarm Halle 1
      bookable_id: 7
      priority: urgent
      dedupe_key: water_leak_hall_1

Blueprints

Drei fertige Automationen arbeiten nur mit den Kalendern: Raum vor jeder Buchung vorheizen, Licht zur Buchung und Frostschutz außerhalb von Buchungen und Öffnungszeiten. Ihr importiert sie über den Link im README. Der Vorlauf eines Raums kommt aus seinem Feld automation_pre_start_minutes in vynst, sonst 30 Minuten.

Raum-Displays

Legt in vynst unter Räume & Ressourcen → Raum-Displays ein Display vom Typ OpenDisplay an. In Home Assistant ordnet ihr ihm ein E-Paper-Schild zu. Home Assistant holt das Bild von vynst (/api/homeassistant/displays/{id}/frame.png, mit ETag), überträgt es per Bluetooth und meldet Akkustand und letzten Kontakt zurück. Bei schwachem Akku oder Ausfall schreibt vynst der Raumverwaltung eine Mail.

API

Die Endpunkte unter /api/homeassistant/ stehen im Bereich Smart Home und Automationen. Gegen sie laufen in vynst eigene Vertragstests, damit die Integration bei Updates nicht bricht.