Dieses Projekt „FaceID Home Assistant Zutritt“ hat meinen Alltag komplett verändert…

Wir sind ein Sechs-Personen-Haushalt – entsprechend oft fällt unsere Haustür hinter jemandem ins Schloss, wurde „nur mal kurz offen gelassen“ oder der Schlüssel blieb doch wieder drinnen liegen. Mit der Zeit hatte ich genug davon und wollte eine Lösung, die sowohl komfortabel als auch wirklich sicher ist. Ausgehend von einem smarten Schloss und einer UniFi G4 Doorbell Pro habe ich Schritt für Schritt ein Zutrittssystem aufgebaut, das heute FaceID, NFC, Fingerprint und klassische Klingelereignisse in Home Assistant bündelt – inklusive eigenem BLE-Sensorhub im Flur, Cloud-Fallback über die SwitchBot-Bridge, Push-Benachrichtigungen und sauberer Zugriffshistorie. In diesem Artikel zeige ich dir im Detail, wie das System funktioniert, welche Komponenten ich einsetze und wie du ein ähnliches Setup nachbauen kannst – inklusive vollständigem Home-Assistant-Package am Ende.

1. Einleitung – persönliche Story

Am Anfang stand kein „Hightech-Projekt“, sondern ein ganz banales Problem: Wir sind zu sechst im Haushalt, jeder kommt und geht zu anderen Zeiten, und die Haustür ist einer der meistgenutzten „Hotspots“ im Alltag. In der Praxis sah das oft so aus: mal eben ohne Schlüssel raus, Tür nur angelehnt, jemand vergisst abzuschließen – oder man steht selbst draußen und merkt, dass der Schlüssel natürlich drinnen liegt. Komfort und Sicherheit passten einfach nicht zusammen.

Ein erstes smartes Schloss war schnell gefunden, später habe ich dann auf das SwitchBot Smart Lock Pro gewechselt. Damit ließ sich die Tür zwar schon per App und Automationen steuern, aber so richtig „nahtlos“ fühlte sich der Zutritt noch nicht an. Spätestens mit der UniFi G4 Doorbell Pro war klar: Die Hardware kann viel mehr als nur klingeln und Video anzeigen – NFC und Fingerprint wollten genutzt werden. Das Problem: Es gibt keine wirkliche Plug-and-Play-Lösung, die all diese Funktionen sauber in Home Assistant integriert.

Also habe ich angefangen zu basteln. Zuerst wurden NFC und Fingerprint der Doorbell in Home Assistant gebracht und sauber ausgewertet. Dann kam meine technische Neugier dazu: Wenn ich schon eine Kamera an der Tür habe – warum nicht auch Zutritt per Gesichtserkennung? So ist die Idee für das FaceID-Projekt entstanden. Die Realität war am Anfang aber alles andere als perfekt: viele False Positives, unzuverlässige Erkennung und ein System, dem ich meine Haustür definitiv noch nicht anvertrauen wollte.

Nach vielen Iterationen, Feintuning in Frigate, Double-Take und CompreFace, besseren Trainingsbildern und einigen Anpassungen in den Automationen bin ich heute bei einer Confidence von 99 % und mehr gelandet. Bei mir selbst funktioniert der Zutritt per FaceID inzwischen in etwa 99 von 100 Fällen, bei den anderen Familienmitgliedern etwas seltener – nicht, weil das System schlecht wäre, sondern weil viele im Alltag schlicht nicht bewusst in die Kamera schauen. Schaust du beim Hochlaufen der sechs Stufen zur Haustür gezielt in die Linse, geht die Tür in der Regel schon auf, bevor du oben ankommst.

Technisch läuft alles über mehrere Ebenen:
Das SwitchBot-Schloss nutzt BLE zum selbstgebauten ESP32-Sensorhub im Flur, das System hat zusätzlich einen Cloud-Fallback über die SwitchBot-Bridge und Home Assistant verknüpft alle Zutrittswege miteinander.

Und genau das ist ein entscheidender Punkt:
Nicht nur FaceID, sondern jede Art von Zutritt – Klingel, NFC, Fingerprint und FaceID – wird automatisch

• mit einem Snapshot dokumentiert,
• sauber im Zutrittslog protokolliert,
• und per Push-Nachricht samt Bild aufs Smartphone geschickt (inkl. persönlichem Namen, Methode, Zeitstempel usw.).

Alles greift ineinander wie ein Baukasten, sorgt für Transparenz und erhöht gleichzeitig die Sicherheit. Heute ist das Zutrittssystem eines meiner zuverlässigsten Projekte überhaupt – und ganz nebenbei eines, das wir täglich dutzende Male nutzen, ohne darüber nachzudenken.

Im weiteren Verlauf des Artikels zeige ich dir Schritt für Schritt, wie dieses System aufgebaut ist – welche Komponenten nötig sind, wie FaceID in die Zutrittslogik eingebettet ist, wie die Push-Benachrichtigungen funktionieren und wie du das komplette Home-Assistant-Package an dein eigenes Setup anpassen kannst.

2. Systemüberblick & Architektur – Wie alles zusammenarbeitet

Um das Zutrittssystem zu verstehen, lohnt sich ein Blick auf die Architektur. Das System besteht nicht aus einem einzelnen Gerät oder einer „Magie-Automation“, sondern aus mehreren Diensten, die perfekt ineinandergreifen. Jeder Bestandteil übernimmt eine klar definierte Aufgabe und Home Assistant verknüpft diese Bausteine zu einem einzigen, stimmigen Gesamtprozess.

Ich zeige dir hier eine verständliche Übersicht, ohne unnötige Theorie – aber so detailliert, dass du die Logik jederzeit selbst nachbauen kannst.

2.1 UniFi G4 Doorbell Pro – die Sensor-Zentrale an der Haustür

Die Türstation liefert gleich vier Arten von Eintrittssignalen:

• Klingel → Auslösen eines „doorbell ring“-Events
• NFC → Auslesen der NFC-ID autorisierter Personen
• Fingerprint → Identifikation via Fingerprint-ID
• Kamera → Beste Bildbasis für FaceID und Snapshots

Wichtig: Die G4 Pro liefert nicht selbst die Gesichtserkennung. Dafür ist sie nur die Bildquelle. Die Kamera macht also das Bild – analysiert wird es später (siehe FaceID-Pipeline).

2.2 SwitchBot Smart Lock Pro – der smarte Türöffner

Das Smart Lock wird zweistufig angesprochen:

1. Primär: BLE über ESP32 („Sensorhub“)
   • extrem schnell
   • komplett lokal
   • unabhängig von Internet/Cloud
   • die schnellste Methode zum Öffnen
2. Fallback: SwitchBot Cloud (via Bridge)
   • wenn BLE mal nicht erreichbar ist
   • wenn der ESP32 neu startet
   • wenn Signalweg durch Wände blockiert ist

Die Automationen testen jedes Mal, ob BLE verfügbar ist. Falls nicht, wird automatisch auf Cloud gewechselt (kein händischer Eingriff nötig).

---

2.3 ESP32 Sensorhub – das lokale Gateway für schnelles BLE

Im Flur hängt ein selbstgebauter ESP32-Hub. Er hat mehrere Aufgaben:

• BLE-Steuerung für das SwitchBot Lock
• Umgebungssensoren (Temp, Helligkeit, ggf. Bewegungsmelder)
• zentrale Position → optimale BLE-Reichweite
• lokale Bridge zu Home Assistant

Du sparst dir damit unnötige Latenzen und das System bleibt lokal hoch performant.

---

2.4 Frigate – die Videoanalyse (Personenerkennung + Zonen)

Frigate erkennt:

• ob eine Person im Bereich der Haustür steht
• ob die Person korrekt in Zone „Haustuer“ erkannt wird
• liefert Frames in sehr guter Qualität

Das Ergebnis geht als Kamerabild weiter an Double-Take.

Zonen und Masken verhindern Fehlalarme (Straße, Hecke, Tiere, Reflexionen usw.).

---

2.5 Double-Take – die Vermittlungsstelle

Double-Take übernimmt drei Funktionen:

1. Bild abholen (aktuelles Frame aus Frigate)
2. Bild an CompreFace senden
3. Ergebnisse an Home Assistant publizieren
   → per MQTT unter double-take/matches/<name>

Jeder Treffer enthält:

• Name
• Confidence
• Kamera
• Match true/false
• Event-ID
• Zeitstempel

Home Assistant reagiert genau auf diese Payload.

---

2.6 CompreFace – der eigentliche FaceID-Server

CompreFace liefert:

• den erkannten Namen
• Confidence
• Matching result
• Metadaten wie Box Area / Bildausschnitt

Training erfolgt über Bilder pro Person. Je mehr hochwertige Bilder, desto besser die Trefferquote.

Meine alte GTX 750Ti unterstützt den Prozess – man sollte etwas neueres nehmen. Aber hatte ich noch liegen!

(Info: geht auch komplett ohne Grafikkarte!)

---

2.7 Home Assistant – die Logik-Schaltzentrale

HA verknüpft alle Signale:

Events → Snapshot → Log → Push → Tür öffnen

Egal ob FaceID, Fingerprint, NFC oder Klingel:

1. Ereignis tritt ein
2. Snapshot wird erstellt
3. Eintrag wird ins JSON-Zutrittslog geschrieben
4. Push aufs Smartphone inkl. Bild
5. Tür öffnen (außer Klingel)

Mit dedizierten Schutzmechanismen:

• 5-Sekunden-Cooldown
• Event-ID-Dedupe
• Türkontakt-Check (mind. 3 Sekunden geschlossen)
• Confidence ≥ 99 % bei FaceID
• Health-Checks aller FaceID-Dienste
• SMART Fallback BLE → Cloud

Alles vollständig in YAML vereint – sauber, wartbar und portable.

---

2.8 Zutrittslog – das Herzstück für Transparenz

Home Assistant speichert die letzten 20 Zutritte im MQTT-Log:

Jeder Eintrag enthält:

• Name
• Methode (face / fp / nfc / bell)
• Confidence (falls FaceID)
• Snapshot-URL
• Event-ID
• Zeitstempel
• Kamera

Das Log wird sowohl im Dashboard angezeigt als auch in Push-Nachrichten verwendet.

---

2.9 Push-Benachrichtigungen (mit Bild)

Jede Zutrittsart erzeugt eine mobile Notification:

• „Zutritt erkannt – Benny – 99 %“
• „Fingerprint – Lina“
• „NFC – Cheyenne“
• „Es hat geklingelt“ inkl. Snapshot
• Link direkt ins HA-Dashboard

Bei FaceID zusätzlich mit Confidence & Fallback-Info (BLE / Cloud).

---

2.10 Snapshots & Cleanup

Alle Bilder landen in:

/config/www/zugang/

Automatisch:

• täglicher Cleanup um 03:15
• Löschen von Dateien älter als 14 Tage
• Bericht per Push mit Anzahl der gelöschten Bilder

Damit wird der Speicher nie überfüllt.

3. Komponenten & Voraussetzungen – Was du für das Projekt brauchst

Damit Leser*innen dein Zutrittssystem erfolgreich nachbauen können, brauchen sie einen klaren Überblick über alle Hardware- und Software-Komponenten, inkl. Alternativen, Besonderheiten und Stolperfallen. Dieser Abschnitt ist bewusst praxisorientiert geschrieben – keine Werbung, kein unnötiger Ballast, sondern exakt das, was du wirklich brauchst.

3.1 UniFi Protect – Türstation & Kamera

Benötigt:

• UniFi G4 Doorbell Pro (PoE oder Akku)

Warum genau diese?

• integrierter Fingerprint-Sensor
• integrierte NFC-Leseeinheit
• extrem gute Nachtsicht und WDR
• niedrige Latenz
• vollständige Event-API über UniFi Protect
• perfekte Bildqualität für Frigate & Double-Take

Achte darauf:

• Unifi Protect sollte auf einer UDM-Pro oder UNVR laufen
• Türstation muss im selben Netzwerk wie Home Assistant sein
• Fingerprint-/NFC-Daten sind nicht standardisiert – du benötigst genau diese Doorbell, sonst funktioniert der FP/NFC-Zweig nicht

---

3.2 SwitchBot Smart Lock Pro + Bridge (optional)

Benötigt:

• SwitchBot Lock Pro
• SwitchBot Bridge (Cloud-Fallback – optional, aber empfehlenswert)

Warum dieses Modell?

• zuverlässig
• super-schnelles BLE
• Home Assistant-fähig ohne Zusatzmodule
• Offen/geschlossen-Status einlesbar
• zusätzliche Überbrückung per Cloud, falls BLE kurz weg ist

Wichtig:

• Das Lock wird primär über BLE gesteuert
  → über deinen ESP32-Sensorhub im Flur
• Wenn BLE ausfällt, übernimmt die Bridge automatisch

---

3.3 ESP32 Sensorhub (BLE-Gateway & Sensoren)

Benötigt:

• ESP32 Dev Kit
• ESPHome Firmware
• ggf. zusätzliche Sensoren (Temp, Helligkeit, Bewegung)

Zweck:

• BLE-Kommandozentrale für das Smart Lock (ultra-schnell)
• zuverlässiger als Handy-Bluetooth
• arbeitet lokal, ohne Cloud
• optimale Reichweite, da im Flur platziert

Bonus:

Du kannst den Hub für weitere Sensorik nutzen –

---

3.4 Home Assistant (Core oder OS)

Benötigt:

• Home Assistant OS/Container/VM
• MQTT-Broker (Mosquitto)
• Add-ons / Docker:
  • Frigate NVR
  • Double-Take
  • CompreFace
  • ESPHome

Warum Home Assistant?

Alle Automationen, Logs, Snapshots, Health-Checks und Push-flows laufen zentral dort zusammen.
Es ist das „Gehirn“ des Zutrittssystems.

---

3.5 Frigate NVR (Videoanalyse)

Benötigt:

• Frigate in Docker oder Add-on
• Kamera-Stream der G4 Doorbell Pro
• korrekt definierte Zonen und Masken

Zweck:

• Erkennen, wann eine Person im relevanten Bereich steht
• Bereitstellen aktueller Frames (Snapshots)
• Minimierung von Fehlalarmen

Achte darauf:

Neustart nach Änderungen nicht vergessen

Zonen sehr präzise definieren

Bewegung (Hecke, Straße) maskieren

3.6 Double-Take (FaceID Orchestrierung)

Benötigt:

• Double-Take Docker + Integration zu HA via MQTT
• Config für:
  • Detectors (CompreFace)
  • Frigate
  • Min. confidence
  • Kamera-Zonen

Zweck:

• holt aktuelles Kamerabild
• sendet es an CompreFace
• meldet homeassistant:
  → „Name X mit Confidence Y erkannt“

---

3.7 CompreFace (Face Recognition Server)

Benötigt:

• CompreFace Docker
• API-Key
• Personen-Galerien mit mehreren Bildern pro Person
• ggf. GPU-Unterstützung
  → bei dir via GTX 750Ti

Achte darauf:

• Bilder sollten „realistisch“ sein:
  unterschiedliche Winkel, Beleuchtung, Tageszeiten
• keine Sonnenbrillen / zu starke Schatten
• keine Filterfotos

---

3.8 MQTT (Nachrichtenbus)

Benötigt:

• Mosquitto oder gleichwertiger MQTT-Broker

Zweck:

• Double-Take sendet FaceID-Ergebnisse
• HA verwaltet das Zutrittslog via MQTT (retain)
• Push-/Snapshot-Logik liest Events aus

---

3.9 Netzwerk & DNS

Benötigt:

• Stabile Netzwerkkonfiguration (UDM-Pro)
• Lokale DNS-Auflösung für:
  • Frigate
  • Double-Take
  • CompreFace
• Vermeidung externer DNS-Rewrites
• Optional: NPM + HTTPS für externe Zugänge

---

3.10 Smartphone Apps (Push-Benachrichtigungen)

Benötigt:

• Home Assistant App auf iOS/Android
• Für jede Person ein eigenes Mobile Device
• Kamera-Bild-Push über notify.mobile_app_*

Pushs werden bei jeder Zutrittsart verschickt:

• FaceID
• NFC
• Fingerprint
• Klingel
• inkl. Snapshot und Link ins Dashboard

---

3.11 Optional, aber sehr nützlich

Unraid

• Docker-Umgebung für Frigate, Double-Take, CompreFace
• GPU-Support, schnelle Ressourcen

SSD-Speicher

• für schnelle Snapshot-Speicherung
• Zugangs-Bilder liegen unter:
  /config/www/zugang/

Backup / Versionierung

• wichtig bei großen YAML-Projekten
• besonders wenn man Automationen CLT-basiert verschiebt

4. Installationsübersicht – Der komplette Grundaufbau

Viele Leser möchten wissen: „Was muss ich eigentlich installieren, bevor ich überhaupt an die Automationen denken kann?“
Dieses Kapitel fasst den gesamten technischen Grundaufbau kompakt zusammen, bevor es später tief in die Details geht.

Ich beschreibe hier den Gesamtprozess so, wie ich ihn selbst umgesetzt habe — klar, logisch, und mit Hinweisen zu typischen Stolperfallen.

---

4.1 Überblick: Die Architektur des Zutrittssystems

Das System besteht aus mehreren Schichten, die zusammenspielen:

1. Kamera & Zutrittshardware
   • Doorbell (mit Fingerprint/NFC)
   • Smart Lock (per BLE / Cloud)
2. Videoanalyse
   • Frigate → erkennt Personen
   • Double-Take → orchestriert FaceID
   • CompreFace → erkennt das Gesicht
3. Home Assistant
   • Automationen
   • Cooldown- und Deduplikationslogik
   • Snapshot-Verwaltung
   • Push-Benachrichtigungen
   • vollständiges Zutrittslog via MQTT
4. Speicher & Cleanup
   • lokale Speicherung aller Snapshots
   • tägliches automatisches Aufräumen
   • Dashboard-Integration

Die nächsten Unterpunkte erklären, wie man diese Komponenten installiert und korrekt miteinander verbindet.

---

4.2 UniFi Protect & Doorbell einrichten

Schritte:

1. Doorbell über Protect einrichten
2. Fingerprint-IDs und NFC-IDs aus Protect abrufen
   • Diese IDs verwende ich später in Home Assistant, um Personen eindeutig zuzuordnen
3. Türstation ins LAN einbinden
4. Events von Protect in Home Assistant sichtbar machen
   → über die UniFi Protect Integration

Wichtig:
Die Fingerprint- und NFC-Events kommen als event.* Entitäten in Home Assistant an.
Diese bilden das Fundament der NFC/Fingerprint-Automation.

---

4.3 Smart Lock einrichten

Egal ob SwitchBot, Nuki oder ein anderes smarthomefähiges Schloss:

1. Smart Lock installieren und kalibrieren
2. Verbindung zu Home Assistant herstellen
3. BLE-Gateway (z. B. ESP32 mit ESPHome) als primäre Verbindung nutzen
4. Cloud-Bridge als Fallback aktivieren

Tipp:
BLE ist extrem schnell. Genau deshalb öffnet sich die Tür oft schon, bevor man oben an der Treppe steht.

---

4.4 MQTT-Broker installieren

MQTT ist das Rückgrat des Systems.

Ich empfehle:

• Mosquitto Broker in Home Assistant (Add-on) oder
• Docker-Container, feste IP im LAN

Benötigt für:

• Double-Take → HA
• Zutrittslog (retain)
• FaceID-Matches
• Health-Checks

---

4.5 Frigate installieren & Kamera integrieren

Frigate ist für das Erkennen von „Personen“ zuständig — präzise, zuverlässig und komplett lokal.

Schritte:

1. Frigate installieren (Docker oder HA Add-on)
2. Kamera-Stream der Doorbell hinzufügen
3. Zone für den Eingangsbereich definieren
4. Masken setzen (Hecke, Straße, Autos)
5. Neustart nicht vergessen

Tipp:
Je besser die Zone gesetzt ist, desto weniger CPU/GPU-Verbrauch, und desto weniger Fehlalarme.

---

4.6 Double-Take installieren

Double-Take ist die Mittelschicht, die Frigate-Bilder einsammelt und an CompreFace sendet.

Vorgehen:

1. Docker-Container starten
2. CompreFace-API-Key hinterlegen
3. MQTT-Broker eintragen
4. Kamera „eingang“ konfigurieren
5. Confidence-Wert setzen (z. B. 0.90 global, 0.99 in HA)

Hinweis:
Double-Take sendet alle FaceID-Matches an Home Assistant unter
double-take/matches/<name>

---

4.7 CompreFace einrichten

CompreFace ist das eigentliche KI-System, das Gesichter erkennt.

Installationsschritte:

1. Docker-Container starten
2. Admin-Panel öffnen
3. API-Key kopieren
4. Für jede Person eine Galerie anlegen
5. Fotos hochladen (natürliche Fotos, verschiedene Winkel)

Wichtig:
Nicht übertreiben: 5–12 Bilder pro Person reichen und sind in der Praxis oft zuverlässiger als 50+ Bilder.

---

4.8 Home Assistant vorbereiten

Damit HA später zuverlässig automatisieren kann, müssen folgende Bausteine eingerichtet werden:

1) Entitäten

HA erzeugt automatisch:

• event.haustur_fingerabdruck
• event.haustur_nfc
• event.haustur_doorbell

MQTT erzeugt:

• sensor.zutritts_log

Das Paket erzeugt:

• Snapshot-Sensoren
• Health-Checks
• Statistiken
• Offline-Warnungen

2) Helfer

• Cooldown
• Event-ID Speicher
• Letzte Confidence
• Zeitstempel letzter Zutrittsaktionen

3) /packages/zutritt_system.yaml

Alle Automationen, Sensoren, Helfer & Shell-Commands liegen in einer Datei.
Das macht Updates, Backups und künftige Verbesserungen enorm einfach.

---

4.9 Snapshot-Direktories anlegen

Folgende Ordner müssen existieren:

/config/www/zugang
/config/www/snapshots   (optional)

Snapshots landen ausschließlich dort.

---

4.10 Push-Benachrichtigungen vorbereiten

Die HA-App registriert automatisch „notify“-Dienste wie:

notify.mobile_app_<dein_iphone>

Diese brauchst du für:

• FaceID-Zutritt
• NFC-Zutritt
• Fingerprint
• Klingel
• täglicher Cleanup-Report
• Health-Warnungen

---

5.11 Test-Snapshot-Funktion einrichten

Das Paket enthält ein Testscript:

script.test_zutritt_snapshot

Damit kannst du jederzeit testen:

• Kamera snapshotfähig?
• MQTT funktioniert?
• Logging funktioniert?
• Push kommt an?

Damit testet man das System, ohne an der Tür stehen zu müssen.

5. Einrichtung Schritt-für-Schritt (mit Screenshots & Codebeispielen)

---

In diesem Kapitel führe ich alle Schritte detailliert durch – so, dass wirklich jeder das System nachbauen kann, egal ob Hobby-Smart-Homer oder fortgeschrittener Bastler.

5.1 Vorbereitung in Home Assistant – Packages aktivieren

Bevor ich irgendein System konfiguriere, sorge ich dafür, dass Home Assistant sauber strukturiert ist.
Mein Zutrittssystem liegt vollständig in einer Datei:

/config/packages/zutritt_system.yaml

Damit HA diesen Ordner überhaupt lädt, muss in der configuration.yaml folgendes stehen:

packages: !include_dir_named packages

Wichtig:
Die Datei muss im richtigen Format (Mapping) beginnen. Kein Listen-Prefix - am Anfang.

---

5.2 MQTT-Broker einrichten

Der MQTT-Broker ist die zentrale Datendrehscheibe zwischen Double-Take und Home Assistant.

Option A – Home Assistant Add-on (Mosquitto)
Einfach über den Add-on Store installieren.

Option B – Docker auf eigenem Server
Empfehlung, wenn viele Komponenten beteiligt sind.

Nach der Installation:

1. Benutzer anlegen
2. Feste IP vergeben
3. In Double-Take hinterlegen
4. In Home Assistant wird MQTT automatisch erkannt

Test:
Unter Entwicklerwerkzeuge → MQTT einen Testpublish absetzen:

topic: test/ha
payload: hello

Wenn HA im Log nichts meckert → läuft.

---

5.3 Frigate installieren und Kamera anbinden

Frigate

Ich nutze Frigate, weil es extrem zuverlässig Personen erkennt und den Ressourcenverbrauch niedrig hält.

Schritte:

1. Kamera-Stream in frigate.yml eintragen
2. Zone „Eingang“ erstellen
3. Masken setzen (Autos, Straße, Bewegungen außerhalb der Treppe)
4. Neustart durchführen

Beispiel einer Zone-Konfiguration:

motion:
  mask:
    - 0,0,1920,0,1920,200,0,200

detect:
  enabled: true
  width: 1280
  height: 720

zones:
  eingang:
    coordinates: 200,720, 400,450, 900,450, 1100,720
    objects:
      - person

Pro-Tipp:
Ich setze diese Zone bewusst klein. Dadurch wird nur ausgewertet, wenn eine Person wirklich auf die Haustür zuläuft.

---

5.4 Double-Take installieren & konfigurieren

Double-Take ist die Schaltzentrale, die Frigate-Snaps nimmt und CompreFace füttert.

Double Take GitHub

Nach der Installation (Docker oder HA-Add-on):

1. Webinterface aufrufen
2. CompreFace API-Key eintragen
3. MQTT-Broker eintragen
4. Kamera auswählen
5. min_confidence auf 0.90 setzen

(Die Feineinstellung mache ich später in HA.)

Minimal-Konfiguration:

mqtt:
  host: 192.168.0.xx
  port: 1883
  username: xxx
  password: xxx

frigate:
  url: http://192.168.0.xx:5000

detectors:
  compreface:
    url: http://192.168.0.xx:8800
    key: YOUR_API_KEY

recognize:
  type: latest
  match:
    min_confidence: 0.90

---

5.5 CompreFace einrichten – Gesichter trainieren

Compre Face

CompreFace ist das eigentliche KI-Modul, das die Personen erkennt.

1. Dashboard öffnen
2. Neue App erstellen
3. „Face Recognition“ auswählen
4. API-Key kopieren
5. Für jede Person eine Galerie anlegen
6. 6–12 natürliche Fotos hochladen
   • verschiedene Winkel
   • verschiedene Tageszeiten
   • Brille ja/nein (wenn relevant)

Hinweis:
Lieber weniger gute Bilder als viele schlechte.
Übertrainieren verschlechtert die Erkennung.

---

5.6 Snapshot-Ordner vorbereiten

Ich lege zwei Ordner an:

/config/www/zugang
/config/www/snapshots

Der erste ist für alle Zutrittssnapshots,
der zweite optional für weitere Bilder.

Prüfen, ob HA darauf schreiben darf → über Studio Code Server oder SSH.

---

5.7 Helfer in Home Assistant erstellen

Für das Zutrittssystem nutze ich mehrere Helfer:

• Cooldown
• Letzte Event-ID
• Letzte Face-Confidence
• Zeitstempel letzter Ereignisse

Diese werden automatisch durch die Package-Datei erzeugt — kein manuelles Anlegen notwendig.

---

5.8 Zutrittssystem-Package-Datei einfügen

Jetzt wird die komplette Datei eingefügt:

/config/packages/zutritt_system.yaml

Home Assistant → Neustart → Config Check: grün.

Falls jemand später eine vollständige Vorlage möchte, stelle ich den gesamten Code am Ende des Artikels bereit — bereits anonymisiert und sauber kommentiert.

---

5.9 Testlauf – Funktion prüfen, ohne vor der Tür zu stehen

Das Paket enthält eine Testfunktion:

script.test_zutritt_snapshot

Damit simuliere ich:

• FaceID-Zutritt (Random Name)
• Snapshot
• Push
• Logging

Das spart beim Debuggen enorm viel Zeit.

---

5.10 Smart Lock einbinden

Ich beschreibe das hier neutral – egal ob SwitchBot, Nuki oder andere Modelle:

1. Lock über Hersteller-App einrichten
2. In Home Assistant einbinden (SwitchBot- oder Nuki-Integration)
3. BLE-Gateway (ESP32) verwenden
4. Cloud als Backup aktivieren

Warum BLE?
Weil es das schnellste Protokoll für solche Aktionen ist.
Wenn FaceID matched, muss die Tür sofort aufgehen.

6. FaceID, NFC, Fingerprint & Klingel – Die komplette Logik erklärt

In diesem Kapitel zeige ich Schritt für Schritt, wie Home Assistant alle vier Zutrittsmethoden verarbeitet.
Mein Ziel war, dass jede Methode:

✔ zuverlässig erkennt
✔ korrekt im Zugriff-Log landet
✔ automatisch einen Snapshot speichert
✔ eine Push-Nachricht sendet
✔ (falls erlaubt) die Tür sofort öffnet
✔ Doppeltrigger zuverlässig vermeidet
✔ robust gegen Ausfälle ist

Das ganze System ist modular aufgebaut – jede Komponente kann einzeln ausfallen, ohne dass das Gesamtsystem unbrauchbar wird.

---

6.1 Wie FaceID-Technologie mit Double-Take funktioniert

Der FaceID-Ablauf besteht technisch aus fünf Schritten:

1) Frigate erkennt eine Person

Die G4 Doorbell sendet ein Livebild an Frigate.
Sobald Frigate eine Person in der definierten Zone erkennt, löst es ein Ereignis aus.

2) Double-Take holt sich das aktuelle Frame

In Double-Take ist eingestellt:

recognize:
  type: latest   # Immer das frischeste Bild
  attempts: 4
  best_image_timeout: 0.5

Damit greift Double-Take nicht auf alte Clips zurück, sondern immer auf das aktuellste Bild.

3) Double-Take sendet das Bild an CompreFace

CompreFace analysiert das Gesicht und liefert:

• Name (sluggified)
• Confidence (0–100 %)
• Match True/False
• Kamera
• Event-ID

4) Double-Take sendet das Ergebnis per MQTT an Home Assistant

Das passiert über Topics wie:

double-take/matches/benny
double-take/matches/lina

5) Home Assistant Automation verarbeitet das Ergebnis

Die Automationen prüfen:

• ob der Name erlaubt ist
• ob die Confidence hoch genug ist (z. B. ≥ 99 %)
• ob das letzte Ereignis nicht doppelt ist
• ob die Tür zu ist
• ob der Cooldown eingehalten wurde
• ob das Schloss erreichbar ist (BLE)

Erst dann wird die Tür geöffnet.

---

6.2 NFC-Zutritt – kontaktlos & sofort

Die Doorbell kann NFC-IDs auslesen.
Home Assistant empfängt diese über das event.haustur_nfc.

Der Ablauf:

1. NFC-Chip wird erkannt
2. Home Assistant prüft, ob die ID erlaubt ist
3. Snapshot wird erzeugt
4. Tür wird geöffnet
5. Push-Benachrichtigung wird gesendet
6. Ereignis wird ins Zutrittslog geschrieben

Das Ganze dauert im Schnitt unter einer Sekunde.

---

6.3 Fingerprint – blitzschnelle biometrische Erkennung

Der Fingerprint funktioniert exakt wie NFC – nur dass statt einer ID ein biometrischer Fingerabdruck gematcht wird.

Auch hier:

• Snapshot
• Zutrittslog
• Push
• Türöffnung
• Dedupe
• Cooldown

Alles identisch.

---

6.4 Klingel – ohne Türöffnung, aber mit Log & Bild

Beim Klingeln passiert fast das Gleiche wie bei Zutritt, nur ohne Türöffnung.

Der Ablauf:

1. Klingel löst Event aus
2. Snapshot wird erstellt
3. Logeintrag wird gespeichert
4. Push wird gesendet

Damit sehe ich jederzeit, wer geklingelt hat – auch wenn ich nicht zu Hause bin.

---

6.5 Warum ich alle fünf Methoden (FaceID, NFC, Finger, Klingel & App) kombinieren wollte

Ich wollte ein System, das den Alltag wirklich erleichtert:

• FaceID öffnet automatisch, wenn man zur Tür hochläuft
• Fingerprint als „Backup“ wenn man nicht sauber in eine Kamera schauen möchte
• NFC für Situationen ohne Kamera (z. B. nachts)
• Klingel trotzdem dokumentiert
• Smartphone-App als Notlösung

Jede dieser Methoden läuft über denselben einheitlichen Logics-Pfad, was das System extrem stabil macht.

---

6.6 Türöffnung: BLE bevorzugt, Cloud als Fallback

Das SmartLock öffnet standardmäßig über BLE (ESP32 im Flur).
Das ist der schnellste Weg und funktioniert auch ohne Internet.

Wenn BLE ausfällt:

1. Home Assistant versucht es dennoch ein paar Millisekunden
2. Falls kein „unlocking/unlocked“ erreicht wird → Cloud-Öffnung
3. Path wird geloggt (BLE oder CLOUD)

Das sorgt dafür, dass die Tür immer aufgeht, auch wenn:

• die Doorbell gerade reconnectet
• das Lock kurz unavailable ist
• die BLE-Verbindung kurz hängt

Die Automation entscheidet live den sinnvollsten Weg.

---

6.7 Snapshot-Verarbeitung – für jedes Ereignis eine eigene Datei

Ich speichere jeden Snapshot als individuelle Datei, z. B.:

zutritt_face_lina_2025-11-17_14-02-58_ab12cd.jpg
zutritt_fp_benny_2025-11-17_14-26-48_69172e.jpg
zutritt_bell_klingel_2025-11-17_15-19-59_691b2f.jpg

Warum nicht ein „letzter_snapshot.jpg“?

Weil:

• parallele Ereignisse sich dadurch nicht überschreiben
• ich immer Bilder pro Person/Ereignis habe
• das Log sauber bleibt
• das Dashboard Bilder korrekt cacht
• Push-Benachrichtigungen immer das richtige Bild zeigen

Später löscht Home Assistant Snapshots automatisch nach 14 Tagen.

---

6.8 Zutrittslog – die zentrale Quelle für alles

Das Zutrittslog basiert auf MQTT und speichert:

• Name
• Methode
• Zeitstempel
• Confidence
• Snapshot
• Kamera
• Extra-Infos (z. B. BLE vs CLOUD)

Beispiele:

face · Benny · 99% · eingang · BLE
fp   · Lynn  · —   · eingang
nfc  · Benny · —   · eingang
bell · Klingel

Ich begrenze das Log bewusst auf maximal 20 Einträge, weil:

• das Dashboard schneller rendert
• keine Riesenlisten entstehen
• die YAML-Templates besser arbeiten
• weniger RAM benötigt wird

Alles Alte wird einfach hinten abgeschnitten – automatisch.

---

6.9 Push-Benachrichtigungen – immer mit Bild

Jede Aktion löst eine Push aus:

• FaceID: „Zutritt per FaceID – Name, %“
• NFC: „Zutritt per NFC – Name“
• Finger: „Zutritt per Finger – Name“
• Klingel: „Es hat geklingelt“
• Cleanup: täglicher Bericht

Das Bild ist immer mit Timestamp, damit App-Caching kein Problem macht:

…jpg?t=1737141090

---

6.10 Deduping – warum es keine Doppeltrigger gibt

Doppeltrigger entstehen oft durch:

• mehrere Frames von Double-Take
• FaceID matcht mehrfach
• Frigate löst mehrere Events aus
• Fingerprint doppelt erkannt
• Klingel pre-event/post-event

Deshalb nutze ich:

• Event-ID Vergleich
• Confidence-Vergleich
• Zeitfilter (< 10 Sekunden alt)
• Hardware-Cooldown
• Software-Cooldown (5 Sekunden)
• Türzustandsfilter (Tür muss zu sein)

Damit habe ich ein 100 % zuverlässiges System, das praktisch nie doppelt öffnet.

7. Dashboard-Integration – Eine saubere, schnelle und elegante Oberfläche

Ich wollte das Zutrittssystem nicht nur funktional haben, sondern auch visuell sauber integriert.
Ziel war:

• klare Übersicht
• schnelle Erkennung der letzten Ereignisse
• schönes Bild-Preview
• strukturierte Zahlen (Face / Finger / NFC / Klingel)
• mobile-friendly für Smartphone & Tablet
• performante Darstellung, auch wenn viele Snaps gespeichert werden

Die Dashboard-Integration besteht aus drei Kern-Elementen:

1. Live-Vorschau der letzten Zutrittsereignisse
2. Kompakter Statistikblock
3. Ein separater Test-Button für manuelles Auslösen

---

7.1 Live-Snapshot-Card – das Herzstück

Für die Snapshot-Vorschau nutze ich eine custom:button-card, weil sie:

• schnell lädt
• CSS erlaubt
• extrem flexibel ist
• zuverlässig funktioniert

Der Vorteil:
Jeder Snapshot ist eine echte Bilddatei mit Timestamp, dadurch wird kein altes Bild gecached.

Die Card sucht sich automatisch das neueste Ereignis aus sensor.zutritts_log und zeigt:

• Snapshot
• Name
• Uhrzeit
• Methode (Face / FP / NFC / Klingel)
• Confidence (falls vorhanden)

Damit sieht man sofort, wer zuletzt an der Tür war.

---

7.2 Statistik-Block – kleine, schlanke Helfer

Vier Template-Sensoren liefern direkt:

• Anzahl FaceID-Zutritte
• Anzahl NFC
• Anzahl Finger
• Anzahl Klingel

Diese vier Werte aktualisieren sich automatisch und sind unabhängig vom großen Log.

Perfekt für:

• Badges oben im Dashboard
• kompakte Übersicht
• Mobile Ansicht

Beispiel:

Face: 104 · FP: 6 · NFC: 1 · Klingel: 33

Das macht das Ganze sehr zugänglich, auch für andere Personen im Haushalt.

---

7.3 Test-Button – zum Debuggen & Präsentieren

Ich wollte einen sauberen Test, der:

• keine echte Identifikation erfordert
• einen Snapshot macht
• Push schickt
• ins Log schreibt
• sofort sichtbar ist

Hier kommt das script.test_zutritt_snapshot ins Spiel.

Damit kann ich jederzeit testen:

• ob Frigate erreichbar ist
• ob das Lock läuft
• ob Push funktioniert
• ob das Dashboard korrekt aktualisiert
• ob das Log sauber arbeitet

Besonders wertvoll, wenn:

• Home Assistant neu gestartet wurde
• Double-Take ein Update hatte
• CompreFace neu trainiert wurde
• die Kamera ausgetauscht wurde
• es neue Familiemitglieder gibt 😉

---

7.4 Performance: Warum das Dashboard trotzdem schnell bleibt

Wichtig für Fans großer Dashboards:
Ich habe bewusst keine großen Listen, keine Repeats und keine Schleifen im Frontend.

Warum?

Je größer die Liste, desto öfter muss Home Assistant rendern.

Statt:

10–50 Snapshots anzeigen → sehr langsam

zeige ich nur:

1 aktuelles Bild
+ Zahlen per Sensor

Das reicht völlig aus, denn wenn jemand mehr wissen will, gibt es:

• die Bilder im /local/zugang
• die Log-Details im Sensor
• das Smartphone mit der Push-Historie
• den Verlauf der Doorbell in UniFi Protect

So bleibt das Dashboard:

• schnell
• stabil
• sehr hübsch
• extrem alltagstauglich

---

7.5 Mobile-Optimierung – das kleine Detail mit großem Effekt

Ich habe jede Card so gebaut, dass sie zu 100 % responsiv ist:

• Bilder skalieren sauber
• Text verschwindet nicht
• Buttons bleiben klickbar
• Meta-Infos umbrechen korrekt

Besonders wichtig:

👉 der Snapshot wird immer mit Querformat/Format-Fill angezeigt,
weil damit vor der Tür niemals schwarze Balken entstehen.

---

7.6 Warum das Dashboard so wichtig ist

Der eigentliche Nutzen eines Zutrittssystems zeigt sich nicht in der YAML, sondern jeden Tag beim Blick aufs Dashboard:

• „Ist die Tür offen?“
• „Wer war zuletzt da?“
• „Hat jemand geklingelt, als niemand zu Hause war?“
• „Läuft das System sauber?“
• „Hat die Erkennung gerade Aussetzer?“
• „Kommt ein Kind nach Hause?“

Und genau dieses Gefühl von Kontrolle & Komfort macht das Projekt so stark.

8. Push-Benachrichtigungen – sofort, zuverlässig und mit Bild

Ein Zutrittssystem ist nur dann wirklich alltagstauglich, wenn es kommuniziert.
Deshalb ist die Push-Benachrichtigung ein zentraler Teil des Projekts – egal, ob:

• jemand klingelt
• jemand per NFC öffnet
• jemand den Fingerabdruck nutzt
• oder die FaceID zuschlägt

Jeder Zutritt erzeugt eine sofortige Nachricht aufs Smartphone, inklusive:

• Name
• Zeit
• Methode (Face / FP / NFC / Klingel)
• Confidence (% bei FaceID)
• automatischem Snapshot
• Deep-Link zum Dashboard
  → damit ich per Klick direkt zur Zutrittskontrolle komme

Damit sehe ich immer sofort:

Wer war an der Tür – und warum wurde sie geöffnet?

---

8.1 Die drei Ziele des Push-Systems

Ich wollte drei Dinge erreichen:

1. Sicherheit

Direkt nach jedem Ereignis ein Bild – damit ich sofort sehe, ob alles stimmt.

2. Komfort

Im Alltag muss niemand rätseln:

• Wer ist gerade gekommen?
• War das ein Fehlalarm?
• Hat das System sauber gearbeitet?

3. Transparenz

Die Push-Historie auf dem Handy ist quasi ein zweites Zutrittslog.
Das ist extrem praktisch, wenn ich unterwegs bin.

---

8.2 Klingel, NFC und Finger – alle erhalten denselben Ablauf

Der Ablauf ist immer gleich:

1. Türereignis kommt rein
2. Snapshot wird erstellt
3. Eintrag ins Zutrittslog (MQTT)
4. Benachrichtigung mit Bild
5. Deep-Link „/smart-home/zutrittskontrolle“

Das fühlt sich unglaublich einheitlich und professionell an.

Beispiel:

Zutritt erkannt – Bastian
17.11.2025 · 18:12:44 · Finger

Oder:

Es hat geklingelt
Snapshot inklusive

---

8.3 FaceID – mit Confidence, Pfad & mehr Kontext

Bei FaceID nutze ich mehr Informationen, weil Double-Take/CompreFace diese liefern:

Beispiel:

Zutritt per FaceID – Cheyenne (99 %, BLE)
17.11.2025 · 18:48:23

Die Nachricht enthält:

• Name
• Uhrzeit
• erkannte Confidence
• Pfad (BLE oder Cloud)
• Snapshot mit Timestamp
• URL → direkt zum Zutritts-Dashboard

Gerade der Confidence-Wert ist Gold wert, wenn man die Erkennung optimiert.

---

8.4 Push-Benachrichtigungen als Debug-Tool

Ich nutze die Pushs auch bewusst zur Fehlerfindung:

• wenn die Confidence ungewöhnlich niedrig ist
• wenn ein Snapshot fehlt
• wenn CompreFace mal rumzickt
• wenn Double-Take ein Update hatte
• wenn das BLE-Lock nicht reagiert
• wenn das System nach einem Neustart falsche Events meldet

Die Pushs zeigen sofort, was genau passiert ist – inkl. Bild.

Das hilft enorm bei der Wartung.

---

8.5 Zwei Geräte? → beide bekommen Infos

Ich lasse die Nachrichten parallel an:

• mein iPhone
• und ein zweites Familiengerät

Damit bleibt alles transparent und nachvollziehbar.

---

8.6 Push mit Live-Bild – kleine technische Besonderheit

Damit das Bild niemals aus dem Cache kommt, hängt die Nachricht automatisch einen Timestamp an:

?t=1731862839

So wird wirklich jeder Push ein frisches Bild liefern.

Das macht die Pushs deutlich zuverlässiger als snapshots ohne Query-Parameter.

---

8.7 Warum Push-Nachrichten so wichtig für das Gesamtsystem sind

Ohne Push wäre alles nur „Automation im Hintergrund“.

Mit Push wird das System:

• spürbar
• nachvollziehbar
• vertrauenswürdig
• nachvollziehbar für alle
• und im Alltag absolut praktisch

Ich muss nie mehr fragen:

„Wer war gerade an der Tür?“
Ich sehe es direkt.

9. Sicherheit, Stabilität & Fehlertoleranz – der echte Gamechanger

Ein Zutrittssystem, das zuverlässig funktionieren soll, braucht drei Dinge:
Sicherheit, Stabilität und Fehlertoleranz.
Gerade wenn es regelmäßig die Haustür öffnet, ist das absolut entscheidend.

Ich habe deshalb ein System gebaut, das nicht nur funktioniert, sondern auch mitdenkt und Fehler souverän auffängt.

---

9.1 Ein Fehlalarm darf nie zur Türöffnung führen

Egal ob FaceID, NFC oder Fingerprint — das System trifft klare Entscheidungen:

• Keine Türöffnung bei unklaren Events
• Keine Türöffnung, wenn die Tür gerade geöffnet oder nicht stabil geschlossen ist
• Keine Türöffnung bei fehlender Confidence (FaceID)
• Keine Türöffnung bei nicht erlaubten Personen
• Keine Türöffnung bei wiederholten / alten Events

Das verhindert zuverlässig:

• Doppel-Auslöser
• wiederholte Events aus dem Cache
• schleichende Fehler durch Netzwerkabbrüche
• dumme „Tür geht mehrmals auf“-Situationen

Das Ganze basiert auf:

• Event-ID-Dedupe
• Cooldown
• letzten Erkennungswerten
• Türkontakt-Status
• Confidence-Grenzen
• Health-Status der gesamten Pipeline

---

9.2 Das Cooldown-System – der Schutzschild

Eine der wichtigsten Komponenten ist der 5-Sekunden-Cooldown.

Warum?
Weil viele Ereignisse kurz hintereinander auftreten können:

• Frigate liefert mehrere Frames
• Double-Take matcht mehrfach
• die Klingel schickt ein Event pro Ruf
• Fingerabdruck-Sensor liefert mehrere Updates
• NFC wird manchmal doppelt gesendet

Der Cooldown sorgt dafür, dass nur ein einziges Ereignis zählt.

Zusätzlich gibt es noch:

Türkontakt-Cooldown

Die Tür muss min. 3 Sekunden lang geschlossen sein, sonst:

• keine neue Öffnung
• keine Annahme eines neuen FaceIDs
• keine Snapshot-Kette

Beide Cooldowns zusammen machen das System extrem stabil.

---

9.3 Dedupe über Event-IDs – falsche Wiederholungen vermeiden

Gerade Gesichtserkennung sendet manchmal 2–3 nahezu identische Events mit derselben ID.

Deshalb wird bei jedem Event geprüft:

Ist diese Event-ID neu?

Falls nein, wird sie nur genutzt, wenn:

• die Confidence höher ist als vorher
  (um z. B. einen besseren Frame zu nutzen)

Das verhindert Wiederholungen und verbessert gleichzeitig die Qualität.

---

9.4 Health-Checks – die Pipeline permanent überwacht

Ich wollte, dass das System selbst merkt, wenn etwas nicht stimmt.

Deshalb wird jede Komponente im Sekundentakt überwacht:

• MQTT Broker
• Double-Take
• Frigate
• CompreFace

Daraus wird abgeleitet:

• FaceID Any Offline (ein „alles-oder-nichts“-Status)
• Offline-Liste mit Namen
• Online-Recovery-Nachricht
• Offline-Alarm nach 60 Sekunden

So bekomme ich sofort:

„Face-Health: Double-Take offline (>=1 min).“

oder später:

„Alle FaceID-Dienste wieder online.“

Das schafft ein Gefühl von Kontrolle — und verhindert Überraschungen.

---

9.5 Ein SmartLock muss mehrere Wege kennen

Mir war wichtig, dass das SmartLock nicht einfach „Unlock“ macht und fertig.

Es muss intelligent entscheiden:

1️⃣ BLE-Pfad (lokal, schnell, bevorzugt)

Wenn der ESP32 im Flur erreichbar ist:

• Öffnung erfolgt sofort per BLE
• schnell
• offlinefähig
• sehr zuverlässig

2️⃣ Fallback: Cloud-Öffnung

Wenn BLE nicht verfügbar ist (mal ist das Gerät im Deep Sleep, mal blockiert die BT-Queue):

• wird automatisch die Cloud-Route verwendet
• das smart_lock_pro wird über die Cloud geöffnet
• so bleibt das System ausfallsicher

Ich sehe den Pfad sogar in der Push:

FaceID – 99 % (BLE)
oder
FaceID – 100 % (CLOUD)

---

9.6 Snapshot-Handling – robust, sauber und aufgeräumt

Snapshots können schnell hunderte Dateien erzeugen.
Damit kein Chaos entsteht:

• alle Bilder werden unter /config/www/zugang/ gespeichert
• jedes Bild hat eindeutige Struktur:
  zutritt_face_benny_2025-11-07_06-49-32_176249.jpg
• Backups bleiben 14 Tage
• Cleanup läuft täglich 03:15 Uhr
• danach erhält man eine Übersicht:

„Heute gelöscht: 17 Snapshots (Zugang: 14, Latest: 3). Verbleibend: 12 / 1.“

Das ist extrem hilfreich bei Wartung und Fehleranalyse.

---

9.7 Warum das System so stabil läuft

Drei Dinge machen den Unterschied:

1. Single Source of Truth

Der MQTT-Log home/access/log ist der zentrale Baustein.
Dieser eine Stream hält 20 Einträge und wird von ALLEN Unterkomponenten genutzt.

2. Kein „letzter Snapshot“ mehr

Statt einer Datei, die sich ständig überschreibt (und Cache-Probleme macht),
wird jeder Snapshot als eigene Datei abgelegt.

3. Alles arbeitet Parametrisiert und deterministisch

Keine dynamischen Rates, kein Zufall:

• feste Confidence
• feste Cooldowns
• saubere Ordnungen
• alle Entitäten klar strukturiert
• jede Entscheidung nachvollziehbar

Gerade bei einem sicherheitsrelevanten System ist das extrem wichtig.

---

9.8 Das System ist stabil… aber auch erweiterbar

Wenn später dazukommen soll:

• Mehrere Kameras
• „Kinder klingeln“-Modus
• Video-Previews
• Besucherprotokoll
• Haustier-Modus
• Gäste-Codes
• Automatische Ansage („Hallo, ich erkenne dich“)
• LED-Signale im Flur

…kann ich das alles sauber anschließen.

Denn das Grundgerüst ist modular aufgebaut.

10. Das Zutrittslog – das Herzstück des gesamten Systems

Ein modernes Zutrittssystem braucht Transparenz.
Ich wollte jederzeit nachvollziehen können:

• Wer kam rein?
• Womit (FaceID, NFC, Fingerabdruck, Klingel)?
• Wann genau?
• Mit welchem Confidence-Wert?
• Welcher Snapshot gehört dazu?

Deshalb habe ich ein zentrales Zutrittslog entwickelt, das als Dreh- und Angelpunkt zwischen allen Automationen dient.

Es basiert komplett auf MQTT und ist dadurch:

• blitzschnell
• extrem zuverlässig
• integrationsfreundlich
• 100 % lokal
• unabhängig von externen Diensten

---

10.1 Einheitliches Format – alle Methoden, eine Datenstruktur

Egal ob die Tür über:

• FaceID
• Fingerabdruck
• NFC
• Klingel
• manuellen Test
• oder Health-Check-Workflow

ausgelöst wird — alles landet im selben Format im Log:

{
  "ts": "2025-11-17T18:48:11.365770+01:00",
  "name": "Cheyenne",
  "method": "face",
  "camera": "eingang",
  "confidence": 0.99,
  "snapshot": "https://home.itsweber.net/local/zugang/...jpg",
  "extra": "event=xyz123;path=BLE"
}

So lässt sich jede Aktion lückenlos nachvollziehen.

---

10.2 Begrenzung auf 20 Einträge – bewusst entschieden

Warum nicht 100, 500 oder 1000 Einträge?

Weil das Dashboard schnell sein soll.
Weil die Pushs direkt auf die Daten zugreifen.
Weil Home Assistant große JSON-Attribute nicht mag.

Deshalb:

• max_items = 20
• alte Einträge werden automatisch entfernt
• kein Recorder-Spamming
• extrem performanter Zugriff

Mehr braucht eine Live-Zutrittsanzeige nicht.

---

10.3 Das Log wird permanent genutzt – nicht nur für Anzeige

Das Log dient nicht nur zur Übersicht, sondern auch:

✔ zur Push-Benachrichtigung

Die Karten lesen den letzten Snapshot aus dem Log.

✔ im Dashboard (Aureon-View)

Für visuelle Darstellungen von:

• letztem Zutritt
• Methoden-Statistik
• Confidence-Werten
• Nutzerfrequenz nach Tagen

✔ zur Fehleranalyse

Wenn z. B. eine NFC-Karte doppelt auslöst oder eine Confidence ungewöhnlich niedrig ist.

✔ für das Snapshot-Handling

Auch hier wird das Log genutzt, um die richtigen Bilder zuzuordnen.

---

10.4 Die vier Statistik-Sensoren – perfekt für Dashboards

Aus dem Log erzeugt das System automatisch:

• FaceID-Anzahl
• Fingerprint-Anzahl
• NFC-Anzahl
• Klingel-Anzahl

Diese Zähler ermöglichen schöne statistische Auswertungen:

• Wie oft wurde FaceID heute genutzt?
• Wer kommt am meisten rein?
• Wie viele Ereignisse gab es während meines Urlaubs?
• Welche Methoden werden in der Familie bevorzugt?

Gerade für Smarthome-Dashboards ist das Gold wert.

---

10.5 Snapshot-Integration – immer der richtige Frame

Der Snapshot wird direkt aus dem Log gelesen, NICHT aus einer separaten Datei.

Das ergibt riesige Vorteile:

• Karten zeigen immer den richtigen Snapshot
• kein Race Condition Problem mehr
• Test-Snapshots und echte Zutritte werden identisch behandelt
• keine „latest.jpg“-Probleme
• die Push-Benachrichtigung lädt stets das richtige Bild nach

---

10.6 Warum MQTT perfekt für das Log ist (und HA-Recorder nicht)

Viele versuchen, so etwas über:

• Home Assistant Historie
• Recorder
• Logbook
• oder input_text-Datenbanken

zu lösen.
Aber das funktioniert schlecht.

MQTT ist ideal, weil:

• Ein JSON-Objekt mit 20 Einträgen ist winzig
• Das Publish/Retain-System speichert es stabil
• HA lädt das Log sofort beim Start
• Es ist unabhängig von Integrationen
• Keine Datenbank-Probleme
• Keine Verzögerungen
• Keine 5-Minuten-Updates

Das Log ist verfügbar, bevor die Automationen beginnen — perfekt für Sicherheitssysteme.

---

10.7 Das Dashboard-Modul (Aureon View)

Ich wollte ein Widget, das auf einen Blick zeigt:

• Wer war zuletzt da?
• Welche Methode wurde genutzt?
• Mit welchem Confidence-Wert?
• Snapshot in groß?
• Statistiken rechts daneben?

Dafür gibt es den Sensor:

sensor.aureon_dashboard_zutrittslog

Er ist eine Aggregation des Logs:

• letzter Name
• letzte Methode
• Confidence
• Snapshot
• verschiedene Counter

Damit lassen sich grafisch schöne Frontend-Darstellungen bauen — egal ob:

• Button-Card
• Grid-Card
• Popups
• Wallpanel
• Lovelace-Tabs

---

10.8 Warum das Zutrittslog das „Single Source of Truth“ ist

Alle Teile des Systems verlassen sich auf das Log:

• Pushs
• Dashboard
• Statistik
• Snapshot-Handling
• Health-Monitoring
• Debugging
• Backups
• Analyse

Es ist die zentrale Wahrheit, an der das gesamte System hängt.

Wenn irgendwas schief geht, schaue ich immer zuerst ins Log, nie in die Automationen.

11. Der komplette Ablauf eines FaceID-Zutritts – Schritt für Schritt erklärt

Damit du das System wirklich nachvollziehen und ggf. nachbauen kannst, zeige ich dir hier einen übersichtlichen, aber technisch vollständigen Ablauf eines realen FaceID-Zutritts — genau so, wie er in meinem Setup stattfindet.

Das klingt komplex, läuft aber in der Praxis in unter einer Sekunde ab.

---

11.1 Schritt 1 – Frigate erkennt eine Person in der Haustür-Zone

Die UniFi G4 Doorbell Pro liefert den Kamerastream.

Frigate arbeitet mit einer exakt definierten Zone:

• Masken gegen Straße, Hecke, Treppe
• Zone „Haustuer“ exakt auf Treppenbereich und Portal begrenzt

Wenn Frigate dort eine Person erkennt, wird ein Event erzeugt:

• frigate/events via MQTT
• oder per REST an Double-Take (depending on config)

Wichtig:
Die Kamera muss dein Gesicht frontal oder halbfrontal erfassen – also wirklich in die Linse schauen.

---

11.2 Schritt 2 – Double-Take zieht das beste Frame aus Frigate

Double-Take bekommt das Event und:

• zieht das beste Frame innerhalb sehr kurzer Zeit
• nimmt das aktuellste Bild („type: latest“)
• bereitet es für die Erkennungs-Pipeline vor

Die Parameter, die sich bewährt haben:

• attempts: 4
• best_image_timeout: 0.5
• min_area: 8000

Das stellt sicher:

✔ gute Bildqualität
✔ kein Rauschen
✔ kein zu kleiner Bildausschnitt
✔ möglichst wenig False Positives

---

11.3 Schritt 3 – CompreFace erkennt das Gesicht

Jetzt übernimmt CompreFace.

Deine GPU (z. B. alte GTX 750 Ti) hilft massiv bei der Geschwindigkeit.
Die Erkennung läuft lokal, privat und extrem schnell.

CompreFace liefert zurück:

• name (wenn erkannt)
• similarity/confidence
• match = true/false
• Event-ID
• Pfad des analysierten Bildes

---

11.4 Schritt 4 – Double-Take sendet das fertige Match an MQTT

Wenn CompreFace eine der hinterlegten Personen erkannt hat, publiziert Double-Take:

double-take/matches/<name>

mit folgendem Payload:

{
  "camera": "eingang",
  "id": "1763399505.62945-o5fomm",
  "match": true,
  "confidence": 0.9978,
  "name": "bastian",
  "snapshot": "http://.../matchfile.jpg"
}

Wichtig:
Hier findet der erste „Filter“ statt:
Nur Double-Take publiziert Match = true, wenn die eingestellte globale Confidence-Schwelle erreicht wurde.

---

11.5 Schritt 5 – Home Assistant empfängt das Match

Home Assistant lauscht auf diesem MQTT Topic.

Die FaceID-Automation prüft sofort:

• Ist die erkannte Person erlaubt?
• Stimmt die Kamera?
• Ist der Match gültig?
• Ist die Confidence ≥ 99 % (lokal definierter Wert)?
• Ist die Tür geschlossen (Türkontakt)?
• Ist das Event neu (Hash-Dedupe)?
• Ist der Cooldown nicht aktiv?

Nur wenn alle Bedingungen erfüllt sind, geht es weiter.

---

11.6 Schritt 6 – Snapshot wird erzeugt (lokal, eindeutig)

Die Automation erstellt einen eigenen Snapshot:

• mit Timestamp
• Name
• Methode
• Event-ID
• Zufalls-Suffix
• gespeichert unter /config/www/zugang/...jpg

Warum extra Snapshot?

➡ weil ich nie wieder Ärger mit „latest.jpg“ haben wollte
➡ weil jede Push ein individuelles Bild braucht
➡ weil das Log exakt dieses Bild referenziert

---

11.7 Schritt 7 – Das Zutrittslog wird aktualisiert

Jetzt ruft die Automation:

script.access_log_append

Dieses Script macht folgendes:

• holt das bestehende Log (Liste)
• fügt den neuen Eintrag vorne hinzu
• kürzt die Liste auf max 20 Einträge
• schreibt alles zurück in MQTT (home/access/log)
• erzeugt sofort aktualisierte Dashboard-Daten

Damit ist das Ereignis:

✔ im Dashboard sichtbar
✔ für Push-Benachrichtigungen nutzbar
✔ im Log langfristig nachvollziehbar
✔ immer sauber strukturiert

---

11.8 Schritt 8 – Türöffnung (mit BLE + Cloud-Fallback)

Jetzt kommt der spannende Teil.

Home Assistant versucht zuerst:

Primärpfad: BLE → ESP32 „Sensorhub“ → SwitchBot SmartLock Pro

• extrem schnell
• zuverlässig
• lokal
• kein Internet notwendig

Wenn BLE nicht erreichbar ist (selten):

Fallback: SwitchBot Cloud über Bridge

• minimal langsamer
• aber zu 100 % zuverlässig

Beide Wege sind implementiert, und das System entscheidet selbständig.

---

11.9 Schritt 9 – Push-Benachrichtigungen (mit Foto)

Sobald das Log und der Snapshot fertig sind, sendet HA:

Push an die Smartphones

• mit Snapshot
• mit Confidence
• Methode
• Name
• Zeitpunkt
• Link zur Zutrittsseite im Dashboard

Bei Klingel, Fingerprint und NFC läuft dieser Push genau identisch ab.
Dadurch spürt man keinen Unterschied in der Nutzung.

---

11.10 Schritt 10 – Cooldown + Event-ID-Sperre

Um Mehrfachöffnungen zu verhindern, prüft das System:

• Event-ID (Hash-Abgleich)
• Confidence-Vergleich (wenn gleiche ID)
• Cooldown per Zeitstempel (5 Sekunden)
• Türkontakt muss mindestens 3 Sekunden geschlossen sein

So werden Fehlauslösungen praktisch komplett verhindert.

12. Der Ablauf bei Fingerprint, NFC und Klingel – Gemeinsamkeiten & Unterschiede

Damit du das komplette Zutrittssystem verstehst, schauen wir uns jetzt die drei anderen Wege an, auf denen jemand die Tür öffnen bzw. ein Ereignis auslösen kann:

• Fingerprint (FP)
• NFC
• Klingel (Doorbell)

Alle drei laufen technisch über dieselbe Zutritts-Automation, haben aber unterschiedliche Regeln, Prioritäten und Öffnungsbedingungen. Dadurch wirkt das gesamte System einheitlich — egal welche Methode verwendet wird.

---

12.1 Die Grundlage: UniFi G4 Doorbell Pro als „Sensor-Hub“

Die UniFi G4 Doorbell Pro ist der zentrale Ausgangspunkt für:

• Klingel-Events
• Fingerprint-Events
• NFC-Events

Sie löst diese Ereignisse als Home Assistant Events aus:

• event.haustur_fingerabdruck
• event.haustur_nfc
• event.haustur_doorbell

Wichtig dabei:
Alle drei Events liefern eindeutig identifizierbare Daten — z. B. Finger-ID, Name, NFC-ID, Event-ID, Zeitstempel.

Das ermöglicht saubere Logik, Wiedererkennung und Deduplizierung.

---

12.2 Ablauf Fingerprint-Zutritt (FP)

Fingerabdrücke sind im Smart-Home-Kontext extrem zuverlässig.

Der Ablauf:

1. G4 Doorbell erkennt Fingerprint
   • Finger-ID + Full-Name wird an HA übermittelt
2. Event wird ausgelöst
   • event.haustur_fingerabdruck
   • mit Daten wie full_name, event_type=identified, event_id
3. Home Assistant prüft:
   • Ist die Person erlaubt?
   • Ist das Event frisch (<10 Sekunden)?
   • Dedupe Event-ID?
   • Türkontakt > 3 Sekunden geschlossen?
   • Cooldown aktiv?
4. Snapshot wird erstellt
   • Live-Foto über die Kamera (immer frontal)
5. Zutrittslog wird erweitert
   • Methode = „fp“
   • Confidence = nicht relevant (FP ist binär)
   • Name wird sauber Mapped („Galina Kaschmirek“ → „Lina“)
6. Tür wird geöffnet
   • wieder erst BLE, dann Cloud-Fallback
   • exakt identischer Ablauf wie bei FaceID
7. Push-Benachrichtigung
   • inklusive Snapshot
   • inkl. Name + Methode (Finger)
   • verlinkt direkt zum Dashboard

Fingerprint ist damit die schnellste und robusteste Methode neben BLE-FaceID.

---

12.3 Ablauf NFC-Zutritt

Den NFC-Zutritt nutze ich z. B. für Keyring-Tags.

Der Ablauf:

1. NFC-Chip wird an die UniFi Doorbell gehalten
2. Die G4 Doorbell erkennt die NFC-ID.
3. Sie liefert ein Event:
   event.haustur_nfc
   inkl. nfc_id, event_id, timestamp.
4. Home Assistant prüft:
   • Ist die NFC-ID in der Whitelist?
   • Ist das Event frisch?
   • Ist Türkontakt geschlossen?
5. Snapshot wird erstellt.
6. Log wird aktualisiert (method=nfc).
7. Tür wird geöffnet (BLE → Cloud-Fallback).
8. Push kommt an.

Wichtig:
Personenabgleich anhand NFC-ID → nicht anhand Full Name.
Die Mapping-Tabelle ist dafür fest hinterlegt.

---

12.4 Klingel-Events („bell“) – ohne Türöffnung, aber mit Snapshot & Log

Bei der Klingel gilt ein ganz anderer Ablauf:

Die Tür öffnet NIE automatisch.

Aber trotzdem laufen folgende Schritte:

1. Klingel wird gedrückt → Event event.haustur_doorbell.
2. Home Assistant markiert das Ereignis.
3. Snapshot wird sofort erzeugt.
4. Eintrag im Zutrittslog:
   • name = „Klingel“
   • method = „bell“
   • confidence = null
5. Push-Benachrichtigung mit Foto:
   „Es hat geklingelt“ + Bild

Das sorgt dafür, dass man immer weiß:

• Wer hat geklingelt?
• Wann?
• Welches Bild gibt es dazu?

Und auch bei Klingel gilt:

✔ Log-Eintrag
✔ Snapshot
✔ Dashboard-Update
✔ identisches Datenmodell wie FP, NFC und FaceID

Großer Vorteil:
Man sieht die Klingel-Ereignisse im gleichen Log wie alles andere.

---

12.5 Was die drei Methoden gemeinsam haben

Alle Methoden führen durch dieselbe Pipeline:

1. Home Assistant Event → Zutritts-Automation

→ dieselbe Datei, dieselben Schutzmechanismen

2. eigener Snapshot

→ immer mit eindeutigem Dateinamen
→ keine Überschreibungen
→ perfekt für spätere Log-Analyse

3. Log-Schreiben über access_log_append

→ einheitliches Format
→ alle Methoden sehen gleich aus
→ einheitliches Dashboard

4. Push-Benachrichtigung

→ immer mit Bild
→ identischer Aufbau
→ direkt zum Dashboard verlinkt

5. Türkontakt-Logik

→ verhindert Fehlöffnungen

6. Dedupe + Cooldown

→ event_id-basierte Sicherheit

Dadurch fühlt sich das System aus einem Guss an.

---

12.6 Wesentlicher Unterschied zu FaceID

Bei FP und NFC gilt:

✔ Tür öffnet sofort, wenn Person/ID erlaubt
✔ keine Confidence-Bewertung
✔ keine ML-Erkennung

Bei Klingel gilt:

✔ NIE automatische Türöffnung
✔ immer Snapshot + Push

Bei FaceID gilt:

✔ Tür öffnet nur bei hoher Sicherheit (≥99 % Confidence)
✔ mehrere Filter hintereinander
✔ Bildanalyse statt direkter Hardware-Identifikation
✔ zusätzliche Schutzmechanismen

13. Systemhärtung & Schutzmechanismen – Warum das System so stabil läuft

Ein Zutrittssystem darf nie unsauber arbeiten.
Fehlerhafte Türöffnungen sind absolut inakzeptabel – ganz gleich, ob sie durch Hardwarefehler, schlechte Bilder, Netzwerkprobleme oder doppelte Events entstehen.

Darum besteht dieses Projekt nicht nur aus den Zutritts-Aktionen selbst, sondern aus einem ganzen Set an Sicherheitsmechanismen, die im Hintergrund arbeiten und dafür sorgen, dass die Tür nur dann öffnet, wenn alles passt.

Hier zeige ich dir die wichtigsten Schutzmaßnahmen – und warum sie so entscheidend sind.

---

13.1 Event-Deduplizierung (Event-ID) – der wichtigste Schutz überhaupt

Jedes Ereignis (Fingerprint, NFC, FaceID, Klingel) besitzt eine eindeutige event_id.

Diese ID wird gespeichert und bei jedem neuen Event geprüft:

• Gleich -> wird ignoriert
• Neu -> darf verarbeitet werden (sofern weitere Checks bestehen)

Warum das wichtig ist:

• Manche Geräte schicken Events mehrfach (z. B. Doorbell reconnects)
• Einige Integrationen wiederholen Events bei Netzwerkproblemen
• Double-Take sendet Matches in Bursts (bis zu 4 Versuche)
• Manchmal kommen nacheinander identische „Match“-Events mit abnehmender/steigender Confidence

Ohne Event-ID-Dedupe würdest du:

❌ mehrfach die Tür öffnen
❌ mehrfach Pushs bekommen
❌ mehrere Snapshots im Log haben
❌ Chaos in deinem Zutrittslog erzeugen

Mit Event-ID:

✔ jedes reale Zutrittsevent wird genau einmal verarbeitet

---

14.2 Zeitbasierte Freshness-Prüfung (<10s / <5s)

Ein Event muss frisch sein.

Beim Zutritt checke ich:

• Beim Eingangsevent: < 10 Sekunden alt?
• Beim Cooldown: < 5 Sekunden Pause seit letzter Türöffnung?

Das filtert sofort raus:

• verspätete Events nach HA-Neustart
• alte MQTT-Nachrichten vom Broker
• rekonstruierte Zustände nach Doorbell-Reconnect
• Replay-Effekte bei Kamera-Lags
• mehrfach erkannte Finger/NFC-Tags innerhalb einer Sekunde

Alles, was älter ist als 10s, ist unzuverlässig → wird verworfen.

---

13.3 Türkontaktlogik (binary_sensor.tk_haustur_contact)

Die Tür darf nur dann geöffnet werden, wenn:

• der Türkontakt „geschlossen“ meldet
• und das seit mindestens 3 Sekunden stabil

Warum das wichtig ist:

• Verhindert erneutes Öffnen während die Tür gerade offen ist
• Verhindert Fehlöffnungen während der Türbewegung
• Verhindert Endlos-Schleifen bei schlecht sitzendem Magnetkontakt
• Macht das System robuster bei Reconnects und Restart-Situationen

Beispiel:
Jemand macht die Tür auf, geht durch, schließt sie – direkt dahinter kommt ein altes Event rein → würde ohne Logik erneut öffnen → nicht gut.

Mit Logik → stabil geschützt.

---

13.4 Protect-Cooldown bei Doorbell-Reconnect

Die UniFi Doorbell ist sehr zuverlässig – aber sie führt bei Updates, Reboots oder WiFi-Störungen folgendes Verhalten aus:

Sie meldet mehrfach ihre internen Sensoren als „unavailable → available“.

Das löst mehrere Home Assistant Events aus.
Genau hier schützt die Automation:

• Nach jedem Doorbell-Reconnect wird input_boolean.protect_cooldown auf on gesetzt.
• Für 2 Minuten werden alle Zutrittsaktionen blockiert.
• Danach wird sie automatisch wieder entsperrt.

Effekt:

✔ keine falschen Türöffnungen durch Reconnects
✔ keine Snapshot-Flut
✔ keine ungewollten Logeinträge

---

13.5 Snapshots pro Event – niemals „last_snapshot.jpg“

Viele HA-Konfigurationen nutzen einen einzigen Datei-Namen wie:

latest.jpg

Das führt aber zu:

• Überschreibungen
• falschen Bildern
• inkonsistenten Logs
• Race Conditions bei parallelen Prozessen

Genau deshalb nutzt dieses Projekt immer:

zutritt_<methode>_<name>_<timestamp>_<eventid>.jpg

Vorteile:

✔ jedes Ereignis hat sein eigenes Bild
✔ Log + Push zeigen immer das korrekte Bild
✔ keine Konflikte bei parallelen Events
✔ keine Verzögerungen durch Locks oder I/O-Kollisionen

---

13.6 Kategorie-getrennte Sicherheit: FP / NFC / FaceID / Klingel

Jede Methode hat ihre eigenen Sicherheitsregeln:

Fingerprint

• Person muss erlaubt sein
• Event muss „identified“ sein
• Event muss frisch sein

NFC

• NFC-ID muss in Whitelist stehen
• Event muss frisch sein

Klingel

• niemals Türöffnung
• trotzdem Snapshot + Push + Log
• identische Dedupe-Logik

FaceID

• Confidence ≥ 99 %
• Person muss erlaubt sein
• Kamera muss „eingang“ sein
• Cooldown + Event-Dedupe
• Türkontakt muss geschlossen sein

FaceID ist die am strengsten kontrollierte Methode – weil sie die größte Fehlerquelle darstellen könnte.

---

13.7 BLE → Cloud Fallback – Redundante Türöffnung

Das SmartLock wird immer zuerst per BLE geöffnet.
Nur wenn BLE nicht verfügbar oder gestört ist, folgt:

Cloud-Fallback → „lock_pro_a7“

Vorteile:

✔ extrem schnelle Türöffnung
✔ funktioniert auch bei lokalem Gateway-Ausfall
✔ flüssige Bedienung im Alltag
✔ robust gegen Paketverlust oder Bluetooth-Aussetzer

---

13.8 Snapshot-Cleanup + tägliche Status-Push

Damit /config/www/zugang/ und /config/www/snapshots/ NICHT volllaufen:

• alle Dateien älter als 14 Tage werden automatisch gelöscht
• täglich um 03:15 Uhr
• danach wird der Bestand neu gezählt
• und als Push an zwei Geräte gesendet

Du weißt also immer:

• wie viele Dateien gelöscht wurden
• wie viele übrig sind
• wie sauber dein System ist

---

13.9 Health-Monitoring der vier Kernsysteme

Das komplette Zutrittssystem hängt an vier Diensten:

1. MQTT-Broker
2. Double-Take
3. Frigate
4. CompreFace

Jeder davon wird jede Minute geprüft:

• TCP-Port / HTTP-Check
• Timeout 3 Sekunden
• ON/OFF-Binärstatus

Wenn ein Dienst offline ist:

✔ Push „FaceID-Health – Ausfall“
✔ nach 1 Minute stabil „offline“
✔ listet exakt welche Dienste weg sind

Wenn alle Dienste wieder da sind:

✔ Push „Recovery – alles online“

Das macht das System extrem wartbar.

14. Snapshot-Dateien & Logstrukturen – wie jeder Zutritt sauber dokumentiert wird

Ein Zutrittssystem ist nur so gut wie seine Dokumentation.
Wenn du später nachschauen willst, wer wann wie ins Haus gekommen ist, brauchst du:

• eindeutige Dateien
• saubere Benennung
• konsistente Logeinträge
• abrufbare Historie
• reproduzierbares Verhalten

Genau das leistet die Snapshot- & Loglogik in diesem Projekt.

---

14.1 Jede Datei ist eindeutig – dank Timestamp + Event-ID

Der Dateiname folgt immer diesem Schema:

zutritt_<methode>_<name>_<timestamp>_<eventid>.jpg

Beispiele:

zutritt_face_benny_2025-11-19_20-45-31_ab12cd.jpg  
zutritt_fp_lina_2025-11-19_17-03-10_ef98aa.jpg
zutritt_nfc_zoe_2025-11-19_14-22-49_884421.jpg
zutritt_bell_klingel_2025-11-19_08-14-01_000000.jpg

Die Elemente im Detail:

Teil	Bedeutung
methode	face / fp / nfc / bell
name	der erkannte bzw. zugeordnete Name
timestamp	sekundengenau – für Sortierung & Debugging
eventid	6 Zeichen aus der echten Event-ID – verhindert Dubletten

Vorteile:

✔ jede Datei ist 100 % eindeutig
✔ kein Überschreiben
✔ Logs zeigen immer zum richtigen Bild
✔ vollständig parallelisierbar ohne Konflikte
✔ Debugging jederzeit möglich

---

14.2 Dateipfade – klare Trennung, klare Ordnung

Alle Zutritts-Snapshots landen hier:

/config/www/zugang/

Alle „Latest“-Bilder aus Tests oder Kamera-Widgets landen hier:

/config/www/snapshots/

Warum zwei Ordner?

• /zugang → echte Zutrittsereignisse
• /snapshots → Testsnaps, UI-Widgets, Diagnosebilder

Ergebnis:

✔ echte Zutrittsbilder bleiben sauber getrennt
✔ Daily-Cleanup pro Ordner möglich
✔ richtiges Verhalten bei Backups
✔ keine Vermischung von Testdaten und Echtbetrieb

---

14.3 Das Zutrittslog – Herzstück der gesamten Dokumentation

Das Log liegt als MQTT-Objekt unter:

home/access/log

Das bedeutet:

• es ist extrem schnell
• es ist systemübergreifend kompatibel
• es überlebt HA-Neustarts zuverlässig
• es ist sofort verfügbar in Dashboard, Automationen & Widgets
• es wird von allen Zutrittsarten (Face, FP, NFC, Klingel) geschrieben

Aufbau des Logs:

{
  "count": 12,
  "entries": [
    {
      "ts": "2025-11-19T20:45:31.000Z",
      "name": "Benny",
      "method": "face",
      "camera": "eingang",
      "confidence": 0.99,
      "snapshot": "/local/zugang/zutritt_face_benny_2025-11-19_20-45-31_ab12cd.jpg",
      "extra": "event=ab12cd;path=BLE"
    },
    ...
  ]
}

Jeder Eintrag enthält:

Feld	Bedeutung
ts	Zeitstempel
name	bereinigter, finaler Name
method	face / fp / nfc / bell
camera	immer „eingang“ (oder was du nutzt)
confidence	nur bei Face relevant
snapshot	lokaler URL-Pfad zum Bild
extra	Zusatzinfos wie event-ID, Öffnungspfad

---

14.4 „Zutritts-Log Letzter Eintrag“ – immer das neueste Event

Der Template-Sensor extrahiert nur den ersten Eintrag aus der Liste.
Genau dieser Sensor versorgt:

• Dashboard-Karten
• Widgets
• Schnellansicht
• Automationen, die nur auf das jüngste Event reagieren sollen

Damit hast du immer garantierten Zugriff auf:

• letzter Snapshot
• letzte Methode
• letzter Name
• letzter Erfolg
• letzte Confidence (bei FaceID)

Vorteile:

✔ sofortiges Refresh im Dashboard
✔ keine zusätzliche Logik nötig
✔ immer synchron mit dem echten Log

---

14.5 Dashboard-Optimierung – „Aureon Dashboard Zutrittslog“

Dieser Sensor wurde speziell gebaut, um Dashboards extrem schnell zu machen.

Er liefert:

• das neueste Event (ts + Name + Methode + Bild)
• fertige Zähler: face / fp / nfc / bell / total
• optimierte Darstellung für Widgets

Ein normaler Lovelace-Card Zugriff auf das Hauptlog wäre teurer.
Dieser Sensor liefert alle wichtigen Infos aus einer einzigen Datenquelle – perfekt für Performance.

---

14.6 Warum das Log auf 20 Einträge begrenzt ist

Ursprünglich war das Log unendlich lang.
Problem:

❌ Dashboard wurde mit der Zeit schwerfällig
❌ MQTT-Payload wurde groß
❌ Karten mussten sehr viel JSON parsen
❌ mobile Darstellung wurde langsamer

Die Begrenzung auf max 20 Einträge sorgt für:

✔ konstante gute Performance
✔ saubere Darstellung ohne Scrollmarathon
✔ schnelle MQTT-Updates
✔ ideale Mischung aus Historie & Übersichtlichkeit

Wenn du mehr Langzeit-Historie willst:

💡 Die Bilder liegen ja ohnehin 14 Tage gespeichert – du kannst komplette Ordner archivieren, ohne dass das Log riesig wird.

---

14.7 Snapshot-Benachrichtigungen – immer mit direktem Bild

Das System versendet bei allen Zutrittsarten:

• FaceID
• Fingerprint
• NFC
• Klingel

eine Push-Benachrichtigung mit Bild, z. B.:

• „Zutritt per FaceID · Benny · 99 % · BLE“
• „Zutritt erkannt · NFC · Zoe“
• „Es hat geklingelt“

Das Snapshot kommt immer als voller HTTPS-URL:

https://home.itsweber.net/local/zugang/DATEINAME.jpg?t=UNIXSTAMP

Das ?t= sorgt dafür, dass das Smartphone kein altes Bild cached.

---

14.8 Warum die Snapshot-Logik ein eigenes Script nutzt

script.access_log_append macht:

• JSON erzeugen
• Liste kürzen
• neue Liste veröffentlichen
• Snapshot-URL zuordnen
• Confidence (falls vorhanden) speichern
• Metadaten sauber einpflegen

Damit hast du:

✔ einheitliche Logstruktur
✔ saubere JSON-Syntax
✔ Übersichtlichkeit in der Historie
✔ perfekte Integration in alle Dashboards

Es läuft zuverlässig — unabhängig von der Zugriffsart.

15. Dashboard-Integration – so baust du eine saubere, praxisnahe Zutrittskarte

Ein Zutrittssystem ist nur dann alltagstauglich, wenn man die wichtigsten Infos sofort sieht, ohne lange suchen zu müssen.
Das Dashboard ist deshalb ein zentraler Bestandteil des Projekts – und wurde so aufgebaut, dass es:

• intuitiv
• übersichtlich
• schnell
• touchoptimiert
• mobilfähig

ist.

Im Folgenden zeige ich, wie die wichtigsten Karten funktionieren, wie sie aufgebaut sind und wie du sie selbst nachbauen kannst.

---

15.1 Die Hauptkarte: „Letzter Zutritt“ mit Vorschaubild

Diese Karte ist das Herzstück des Zutrittsdashboards.

Sie zeigt:

• das aktuellste Ereignis,
• Snapshot-Bild (live mit Cache-Break),
• Name,
• Methode,
• Zeitstempel,
• Confidence (nur FaceID),
• sowie einen Button zum Test-Snapshot.

Basis-Entität

Die Karte lebt von:

sensor.zutritts_log

und verwendet aus dessen attributes.entries[0]:

• snapshot
• ts
• name
• method
• confidence

Alle diese Felder kommen direkt aus dem Access-Log.

---

15.2 Die fertige Zutrittskarte (Button-Card)

Hier die Karte, wie sie bei dir bereits erfolgreich läuft:

type: custom:button-card
entity: sensor.zutritts_log
name: Letzter Zutritt
icon: mdi:door
show_icon: true
show_name: true
show_state: false

styles:
  card:
    - padding: 12px
    - border-radius: 18px
    - box-shadow: 0 6px 20px rgba(0,0,0,.18)
    - border: 2px solid
    - background: var(--card-background-color)

  name:
    - justify-self: start
    - font-weight: 700
    - font-size: 1.05rem
    - color: var(--primary-text-color)

  icon:
    - color: "#22c55e"
    - width: 28px
    - height: 28px

custom_fields:
  thumb: |
    [[[
      const entries = (hass.states['sensor.zutritts_log']?.attributes?.entries || []);
      const last = entries[0] || null;
      const url = last ? (last.snapshot || '') : '';
      const t = Date.now();

      if (url) {
        return `<img src="${url}?t=${t}" 
                     style="width:100%;height:150px;object-fit:cover;
                     border-radius:14px;" />`;
      }
      return `<div style="height:150px;border-radius:14px;
                          background:rgba(34,197,94,.12);
                          display:flex;align-items:center;
                          justify-content:center;color:#22c55e;">
                Keine Snapshot-Vorschau
              </div>`;
    ]]]

  meta: |
    [[[
      const entries = (hass.states['sensor.zutritts_log']?.attributes?.entries || []);
      const last = entries[0] || null;

      if (!last) 
        return `<div style="opacity:.7">— Kein Eintrag —</div>`;

      const ts = new Date(last.ts);
      const p = n => String(n).padStart(2,'0');
      const tsStr = `${p(ts.getDate())}.${p(ts.getMonth()+1)}.${ts.getFullYear()} `
                   +`${p(ts.getHours())}:${p(ts.getMinutes())}:${p(ts.getSeconds())}`;

      const name = last.name || 'Unbekannt';
      const method = String(last.method||'').toUpperCase();
      const conf = (last.confidence!=null)
                   ? ` · ${(parseFloat(last.confidence)*100).toFixed(0)}%` 
                   : '';

      return `<div style="display:flex;flex-direction:column;gap:4px;">
                <div style="font-weight:600;color:var(--primary-text-color)">${name}
                  <span style="margin-left:8px;padding:2px 8px;border-radius:9999px;
                               border:1px solid #22c55e;color:#22c55e;font-size:.75em;">
                    ${method}
                  </span>
                </div>
                <div style="opacity:.75;color:var(--secondary-text-color)">
                  ${tsStr}${conf}
                </div>
              </div>`;
    ]]]

✔ extrem performant
✔ zeigt immer das aktuellste Event
✔ robust, selbst bei leerem Log
✔ schönes UI
✔ automatisch aktualisiert

---

15.3 Vier Zähler für Face/NFC/Finger/Klingel

Diese vier Template-Sensoren:

sensor.zutritts_log_count_face
sensor.zutritts_log_count_fp
sensor.zutritts_log_count_nfc
sensor.zutritts_log_count_bell

lassen sich hervorragend darstellen durch:

• Mushroom Chips
• Badge-Style-Buttons
• Minimalistic Chars
• kleine Zähler oberhalb der Zutrittskarte

Beispiel mit Mushroom-Chips:

type: custom:mushroom-chips-card
chips:
  - type: entity
    entity: sensor.zutritts_log_count_face
    icon: mdi:face-recognition
    color: green
  - type: entity
    entity: sensor.zutritts_log_count_fp
    icon: mdi:fingerprint
  - type: entity
    entity: sensor.zutritts_log_count_nfc
    icon: mdi:nfc
  - type: entity
    entity: sensor.zutritts_log_count_bell
    icon: mdi:bell-ring

---

15.4 „FaceID Offline“-Status: Pipeline auf einen Blick

Die Pipeline besteht aus:

• MQTT
• Double-Take
• Frigate
• CompreFace

Damit du sofort siehst, ob etwas hängt, gibt es:

binary_sensor.faceid_any_offline
sensor.faceid_offline_list

Die Anzeige eignet sich perfekt für:

• Badge oben rechts
• rote Warnkarte
• Pop-up
• Alert-Section am Seitenanfang

Beispiel (roter Hinweis):

type: alert
entity: binary_sensor.faceid_any_offline
name: FaceID Pipeline offline

---

15.5 Vollbild-Karte: Zutritts-Historie (20 Events)

Da das Log bewusst auf 20 Einträge limitiert ist, kann man diese Historie perfekt darstellen.

Beispiel:

type: custom:auto-entities
card:
  type: custom:fold-entity-row
  head:
    type: section
    label: Letzte 20 Zutritte
filter:
  include:
    - entity_id: sensor.zutritts_log
sort:
  method: attribute
  attribute: ts
  reverse: true

Oder besser: eine eigene History-Liste mit HTML-Template (wenn du willst, baue ich die dir später).

---

15.6 Testbereich: „Test-Zutritt auslösen“

Mit

script.test_zutritt_snapshot

hast du eine perfekte Testlösung.
Eine Karte dazu:

type: custom:button-card
name: Test-Zutritt
icon: mdi:camera
tap_action:
  action: call-service
  service: script.test_zutritt_snapshot
confirmation:
  text: Test-Snapshot auslösen?
styles:
  card:
    - border-radius: 12px
    - padding: 12px

---

15.7 Optional: Kamerafeed der Doorbell

Viele Nutzer wollen den Live-Feed oben anzeigen.
Nutze einfach:

camera.eingang

Mit einer picture-glance:

type: picture-glance
entities: []
camera_image: camera.eingang

---

15.8 Das fertige Dashboard – Empfehlung für die komplette View

Empfohlener Aufbau:

1. FaceID-Pipeline-Status
   (sonst alles andere wertlos)
2. Letzter Zutritt (mit Bild)
   → Herzstück der Seite
3. Zähler der Kategorien
4. Historie (Letzte 20)
   außerhalb des Fold-Blocks oder in einem Fold
5. Test-Snapshot
   (nur für Admins oder versteckt im Entwicklermenü)
6. Optional: Live-Feed der Kamera
   ganz unten oder als kleines Widget oben rechts