ESP-Kerberos

Warning

🚧 Work in Progress — ESP-Kerberos befindet sich noch mitten in der Entwicklungsphase und wird aktuell umgesetzt. Hier kann sich täglich etwas ändern!

Batteriebetriebener Öffnungsmelder auf ESP32-C6-Basis für Paketboxen mit integrierter Briefbox.

Wacht über bis zu 4 unabhängige Eingänge gleichzeitig — typisch Brief-Einwurf, Paket-Einwurf, Brief-Entnahme und Paket-Entnahme — funktioniert aber mit jedem potentialfreien Schalter für jede Art "etwas wurde geöffnet/ausgelöst"-Erkennung — siehe Sensor/Schalter. Die gesamte Konfiguration (WLAN, Eingänge, Meldekanal inkl. MQTT) läuft über ein WebUI im Access-Point-Modus — kein Neu-Kompilieren pro Gerät nötig, siehe Setup.

Kernidee: der ESP32 verbringt praktisch seine gesamte Lebenszeit im Deep Sleep (Verbrauch im niedrigen µA-Bereich) und wacht ausschließlich durch den externen Schalter auf. Nach dem Wecken verbindet er sich per WLAN, schickt eine Push-Nachricht und legt sich sofort wieder schlafen — die aktive Wachzeit pro Auslösung liegt im Sekundenbereich.

🔌 Web-Flasher — Firmware direkt aus dem Browser

Kein PlatformIO, kein Terminal, kein Compiler nötig: Firmware direkt aus dem Browser flashen, per ESP Web Tools.

👉 docbigs-lab.github.io/ESP-Kerberos — ein Klick auf „Install" reicht.

• Voraussetzung: Chrome oder Edge (Web Serial API), ESP32-C6 per USB angeschlossen.
• Danach direkt weiter mit Konfiguration über WebUI.
• Quelle des Installers: docs/index.html + docs/manifest.json, Firmware-Datei wird von merge_bin.py bei jedem pio run automatisch nach docs/ESP-Kerberos-merged.bin gebaut.

Funktionsprinzip

Deep Sleep ──(Schalter löst aus)──▶ Wake ──▶ WLAN verbinden ──▶ Benachrichtigung senden
     ▲                                                                  │
     │                                                                  ▼
     └──────────────── Cooldown-Sleep (nur Timer-Wakeup) ◀─────────────┘

1. Deep Sleep als Grundzustand, Aufwachen über EXT1-Wakeup an einem GPIO.
2. Entprellung: nach dem Wachwerden kurzer Delay + erneute Pin-Prüfung, um Kontaktprellen nicht als Auslösung zu werten.
3. WLAN-Verbindung (optional mit statischer IP statt DHCP, spart Verbindungszeit).
4. Push-Benachrichtigung per HTTPS an den konfigurierten Meldekanal (Telegram, Pushover, ntfy.sh oder MQTT — siehe MQTT / Home Assistant) — kein SMTP/E-Mail-Versand, das wäre auf dem Chip deutlich langsamer.
5. Cooldown-Sleep: nach dem Versand schläft der Chip für einige Sekunden mit ausschließlich Timer-Wakeup (Schalter-Wakeup ist in dieser Zeit deaktiviert), damit Nachschwingen/Prellen keine weiteren Nachrichten auslöst. Erst danach wird der Schalter wieder scharf geschaltet.
6. Bleibt ein Eingang lange ausgelöst (z. B. Klappe bleibt offen): Nach jedem Cooldown-Ablauf prüft der Chip kurz und ohne WLAN/Nachricht, ob der Kontakt noch aktiv ist. Ist das der Fall, schläft er einfach direkt für einen weiteren Cooldown-Zyklus weiter — ganz ohne erneuten Versand. Erst wenn der Kontakt wieder in Ruhe ist, wird der Trigger erneut scharf geschaltet; eine neue Auslösung löst dann wieder genau eine Nachricht aus. Pro Auslöse-Flanke gibt es also immer nur eine Nachricht, unabhängig davon, wie lange der Kontakt offen bleibt.

Konfiguration über WebUI (Access Point + Captive Portal)

Die gesamte Konfiguration (WLAN, Eingänge, Meldekanal) erfolgt zur Laufzeit über ein WebUI — keine Zugangsdaten-Datei, kein Neu-Kompilieren pro Gerät:

• Erststart: Ist noch keine Konfiguration im Flash gespeichert, öffnet das Gerät automatisch ein eigenes WLAN namens ESP-Kerberos-Setup-XXXX (XXXX = letzte zwei MAC-Adress-Bytes, zur Unterscheidung mehrerer Geräte).

• AP-Passwort: Das Setup-WLAN ist WPA2-geschützt. Solange kein eigenes Passwort gesetzt wurde, gilt der aus der MAC-Adresse abgeleitete Default kerberos-XXXX (dieselben vier Hex-Zeichen wie im WLAN-Namen) — pro Gerät unterschiedlich, kein für alle Geräte identisches Passwort. Im Formular unter "Zugriffsschutz (Setup-AP)" durch ein eigenes Passwort (mind. 8 Zeichen) ersetzbar; leeres Feld lässt das aktuelle/Standard-Passwort unverändert. Schützt sowohl die Konfigurationsseite (inkl. WLAN-/Meldekanal-Zugangsdaten) als auch das Firmware-Update vor jedem, der nur in Funkreichweite ist.

• Mit diesem WLAN verbinden — auf den meisten Smartphones öffnet sich automatisch ein Anmelde-Popup mit der Konfigseite (Captive Portal). Öffnet sich nichts von selbst, http://192.168.4.1 manuell im Browser aufrufen.

• Formular ausfüllen: Das SSID-Feld schlägt gefundene WLANs vor (nach Signalstärke sortiert, stärkstes zuerst — der Button "Netzwerke neu suchen" stößt einen erneuten Scan an, ohne bereits eingetragene Werte in anderen Feldern zu verwerfen), man kann aber auch jede beliebige SSID frei eintippen (z. B. bei versteckten Netzwerken). Bei aktivierter "Statische IP verwenden"-Checkbox zusätzlich IP-Adresse, Gateway, Subnetzmaske und DNS-Server eintragen (sonst bleibt es bei DHCP, Standardfall). Dazu gemeinsame Cooldown-Dauer und optionales Heartbeat-Intervall (siehe Heartbeat), sowie bis zu 4 unabhängige Eingänge (siehe Mehrere Eingänge) — standardmäßig sind alle 4 aktiv, vorbelegt mit den Paketbox-Rollen Brief-Einwurf/Paket-Einwurf/Brief-Entnahme/Paket-Entnahme, per Checkbox einzeln ab-/zuwählbar —, jeder mit eigenem GPIO-Pin, eigener Auslöse-Polarität und eigenem Nachrichtentext, gewünschter Meldekanal (gilt für alle Eingänge gemeinsam, inkl. MQTT — siehe MQTT / Home Assistant) mit dessen Zugangsdaten. Speichern → Gerät startet neu und verbindet sich mit dem konfigurierten WLAN.

  

• Rekonfiguration: Kurz nach einem echten Power-On/Reset (Batterie/USB neu anschließen oder EN-Taste drücken — nicht nach einem normalen Deep-Sleep-Aufwachen durch einen Trigger) öffnet sich ein 5-Sekunden-Fenster: Wird in dieser Zeit die BOOT-Taste des Boards gedrückt, öffnet das Gerät das Setup-WLAN erneut, unabhängig davon, ob schon eine Konfiguration existiert. Ohne Tastendruck läuft der Normalbetrieb einfach weiter. Bei einer bereits konfigurierten Rekonfiguration kehrt das Portal ohne Eingabe nach 10 Minuten Inaktivität automatisch in den Normalbetrieb mit der bisherigen Konfiguration zurück. Ablauf zum Rekonfigurieren: Reset-Taste drücken, loslassen, dann innerhalb von 5 Sekunden die BOOT-Taste drücken (nicht gleichzeitig mit dem Reset — der ROM-Bootloader prüft deren Pegel nur exakt im Reset-Moment für den Flash-Download-Modus, danach ist GPIO9 ein normaler Eingang).

Die Konfiguration wird im NVS-Flash (Preferences) gespeichert und übersteht Neustarts sowie Firmware-Updates über die OTA-Funktion (solange der Flash nicht komplett gelöscht wird).

• AP-Passwort vergessen? Es gibt bewusst keinen eigenen Software-Reset dafür — stattdessen über USB oder den Web-Flasher neu flashen. Das schreibt Bootloader, Partitionstabelle und Firmware auf einen Schlag neu; die Lücke im gemergten Image überschreibt dabei auch die NVS-Partition mit gelöschtem Flash-Inhalt. Das Gerät startet danach komplett zurückgesetzt — WLAN, Eingänge, Meldekanal und AP-Passwort sind weg, nicht nur Letzteres, und müssen über das Setup-Portal neu eingerichtet werden.

Firmware-Update (OTA)

Firmware-Updates lassen sich, ohne das Gerät per USB anzuschließen, direkt über das (durch das AP-Passwort geschützte) Setup-Portal einspielen:

1. Ins Setup-WLAN verbinden (Rekonfiguration öffnet das Portal auch bei bereits konfigurierten Geräten).
2. Auf der Konfigseite oben auf "Firmware-Update" klicken.
3. ESP-Kerberos-ota.bin aus docs/ im Projekt-Repository auswählen und hochladen — die Datei entsteht automatisch bei jedem pio run (via merge_bin.py), kein manuelles Suchen im PlatformIO-Build-Ordner nötig.
4. Nach erfolgreichem Upload startet das Gerät automatisch mit der neuen Firmware neu.

Wichtig — die richtige Datei: Hochgeladen wird ESP-Kerberos-ota.bin (reine App-Partition), nicht ESP-Kerberos-merged.bin aus demselben Ordner (die enthält zusätzlich Bootloader und Partitionstabelle für den USB-Erstflash und ist für OTA ungeeignet). Ein versehentlicher Upload der falschen Datei führt zu einem nicht startenden Gerät — Wiederherstellung dann nur per USB oder Web-Flasher (siehe AP-Passwort vergessen oben, Reflash setzt dabei die gesamte Konfiguration zurück).

Bewusst kein automatischer Versions-Check und kein Bezug einer Firmware-Datei von extern — der Upload passiert rein lokal im Setup-AP, ausgelöst durch den Nutzer selbst. Das hält den sonst auf minimale Wachzeit optimierten Normalbetrieb (Deep Sleep/Trigger-Wake) vollständig unberührt: OTA ist nur im ohnehin seltenen Rekonfigurations-Fenster verfügbar, nie im Hintergrund während des Batteriebetriebs.

Sensor / Schalter

Elektrisch ist jeder potentialfreie Schalter (dry contact) gleich verkabelt: eine Ader an den Trigger-Pin, die andere an GND. Der interne Pull-up hält den Pin im Ruhezustand HIGH; schließt der Schalter, geht der Pin auf LOW. Diese Verkabelung ist unabhängig vom Schaltertyp immer identisch:

 GPIOx (Trigger-Pin) ──┬── Schalter ── GND
                       │
                   (interner Pull-up, per Software aktiviert)

Funktioniert z. B. mit:

• Reedkontakt (Magnetkontakt) — klassisch für Klappen/Türen/Fenster
• Mikroschalter / Endschalter — z. B. an einer Klappe, die beim Öffnen einen Hebel drückt
• Taster — für "manueller Alarmknopf"-Anwendungsfälle
• Kipp-/Neigungsschalter — z. B. Kippt-Erkennung
• Jeder andere einfache mechanische Schalter mit zwei potentialfreien Anschlüssen

Welche Pin-Polarität als "Auslösung" gilt, hängt nur davon ab, ob der jeweilige Schalter beim auslösenden Ereignis öffnet oder schließt — das wird im WebUI pro Eingang eingestellt, die Verkabelung selbst ändert sich dabei nicht.

Wichtige Einschränkung (ESP32-C6): Nur die GPIOs 0–7 sind RTC/LP-fähig und damit grundsätzlich als Deep-Sleep-Wakeup-Quelle nutzbar. Jeder andere Pin kann den Chip nicht aus dem Deep Sleep wecken. Welche dieser acht Pins auf dem jeweiligen Board tatsächlich herausgeführt sind, hängt vom konkreten Modul ab (Pinout/Silkscreen prüfen). Auf dem Referenzboard (FireBeetle 2 ESP32-C6) ist GPIO0 zusätzlich fest mit dem eingebauten Akku-Spannungsteiler verdrahtet (siehe Batterieüberwachung) und daher als Trigger-Pin ungeeignet — die WebUI-Auswahl für Trigger-Eingänge ist deshalb auf GPIO1–7 begrenzt.

Die werkseitig vorbelegten Pins (GPIO1, 2, 3, 4) passen zum Referenzboard (FireBeetle 2 ESP32-C6, siehe Hardware) — dort ist GPIO0 fest mit dem eingebauten Akku-Spannungsteiler verdrahtet (siehe Batterieüberwachung) und daher als Trigger-Pin ungeeignet. Auf anderen Boards kann die sinnvolle Vorbelegung abweichen — die Zuordnung ist pro Eingang im Setup-Portal unter "GPIO-Pin" frei änderbar, ein Neuflashen ist dafür nicht nötig.

Mehrere Eingänge

ESP-Kerberos überwacht bis zu 4 unabhängige Eingänge gleichzeitig — namensgebender Regelfall ist eine Paketbox mit integrierter Briefbox (Brief-Einwurf, Paket-Einwurf, Brief-Entnahme, Paket-Entnahme), es funktioniert aber genauso für jede andere Kombination (z. B. Briefkasten + Gartentür + Garagentor). Jeder Eingang ist im WebUI einzeln:

• aktivierbar/deaktivierbar (nicht benötigte Eingänge einfach abwählen),
• einem eigenen GPIO-Pin (0–7) zugeordnet,
• mit eigener Auslöse-Polarität (öffnet/schließt) konfigurierbar — jeder Eingang kann anders verdrahtet sein, das ist unabhängig von den anderen,
• mit eigenem Nachrichtentext versehen, damit die Push-Nachricht (bzw. bei MQTT: der Home-Assistant-Entity-Name) erkennen lässt, welcher Kontakt ausgelöst hat.

Der Meldekanal (Telegram/Pushover/ntfy/MQTT) und die Cooldown-Dauer gelten geräteweit für alle Eingänge gemeinsam. Löst mehr als ein Eingang gleichzeitig aus, wird für jeden aktiven Eingang eine eigene Nachricht über dieselbe WLAN-Verbindung verschickt. Wird kein einziger Eingang aktiviert, bleibt Eingang 1 als Sicherheitsnetz automatisch aktiv — sonst hätte das Gerät keine Aufwach-Quelle mehr und würde nie wieder von selbst aus dem Deep Sleep zurückkehren.

Meldekanäle

Genau ein Kanal ist pro Gerät aktiv, umschaltbar im WebUI:

• Telegram — Bot über @BotFather anlegen, Token kopieren; eigene Chat-ID z. B. über @userinfobot ermitteln.
• Pushover — App-Token und User-Key aus dem eigenen Pushover-Konto.
• ntfy.sh — kein Konto nötig, einfach einen (möglichst schwer zu erratenden) Topic-Namen wählen; Server-URL ist im WebUI überschreibbar für selbstgehostete ntfy-Instanzen.
• MQTT — Anbindung an beliebige Smart-Home-Systeme, inkl. automatischer Home-Assistant- Discovery. Siehe MQTT / Home Assistant.

Heartbeat

Optionaler periodischer Wake unabhängig von echten Auslösungen (WebUI-Feld „Heartbeat-Intervall (Minuten)", 0 = deaktiviert, Default 60 min) — läuft als zusätzliche Deep-Sleep-Wakeup-Quelle parallel zum EXT1-Trigger, ohne dass der Chip dafür dauerhaft wach bleibt oder pollt.

• Bei MQTT-Kanal: hält Home-Assistant-Discovery- und State-Topics aktuell, falls der Broker zwischenzeitlich Retained Messages verloren hat (z. B. Neustart ohne Persistence) — sonst müsste man dafür auf den nächsten echten Power-On/Reset warten. Details siehe MQTT / Home Assistant weiter unten.
• Bei Push-Kanälen (Telegram/Pushover/ntfy): per Checkbox „Tägliches Lebenszeichen per Push" zuschaltbar, sendet dann unabhängig vom (ggf. kürzeren) technischen Heartbeat-Intervall höchstens 1x/Tag eine „ESP-Kerberos ist online"-Nachricht (inkl. Akkustand, falls Batterieüberwachung aktiv) — bewusst selten, um bei einer Briefkasten-App nicht zu nerven. Push-Kanäle kennen anders als Home Assistant kein „nicht verfügbar", das ist hier der einzige Weg, überhaupt mitzubekommen, dass das Gerät noch antwortet.
• Stromkosten: ein zusätzlicher Wake-Zyklus kostet laut Hardware ≈5,1 µAh. Beim Default von 60 Minuten macht das rechnerisch ≈122 µAh/Tag zusätzlich — bei einem 3000-mAh-Akku vernachlässigbar (die Selbstentladung der Zelle dominiert ohnehin, siehe Hardware-Abschnitt).

MQTT / Home Assistant

Anders als die drei Push-Kanäle (die pro Auslösung eine einmalige Nachricht schicken) bildet der MQTT-Kanal den aktuellen Zustand jedes Eingangs ab — genau wie ein handelsüblicher Tür-/Fenstersensor:

• Pro Eingang wird ein retained ON/OFF-Status auf <Basis-Topic>/input<N>/state veröffentlicht (N = 0–3). Öffnet ein Kontakt → ON, schließt er wieder → OFF. Das Basis-Topic ist im WebUI frei wählbar, leer gelassen wird automatisch kerberos/<Geräte-ID> verwendet (<Geräte-ID> = letzte zwei MAC-Adress-Bytes).
• Bei jeder Auslösung wird kurz vor dem ON immer zuerst ein OFF gepusht. Das erzwingt einen echten Zustandswechsel in Home Assistant, selbst wenn der dort zuletzt bekannte (retained) Zustand schon ON war — z. B. weil ein früheres OFF wegen eines WLAN-/Broker-Ausfalls nie ankam. Ohne diesen Puls würde ein erneutes ON mit identischem Payload keinen state_changed-Event auslösen, wodurch Automationen mit trigger: state, to: "on" die Auslösung verpassen würden.
• Home-Assistant-Autodiscovery (per Checkbox im WebUI an-/abschaltbar) legt für jeden aktivierten Eingang automatisch einen binary_sensor (device_class door) an, gruppiert unter einem gemeinsamen Gerät „ESP-Kerberos <Geräte-ID>“ — keine manuelle Konfiguration in Home Assistant nötig. Deaktivierte Eingänge bzw. abgeschaltete Discovery entfernen die zugehörige Entity automatisch wieder aus Home Assistant.
• Kein Dauerbetrieb, reiner Publish-Kanal: Das Gerät verbindet sich nur kurz zum Broker, wenn es ohnehin wach ist (Auslösung, Rückkehr in Ruhezustand, einmalig nach jedem Power-On/Reset für die Discovery-Configs, oder beim optionalen Heartbeat) — passend zum Kernprinzip minimaler Wachzeit. Es gibt bewusst kein eingehendes Command-Topic/Subscribe (kein "2-Weg" im engeren Sinn) und keine klassische MQTT-Availability/Last-Will-Verfolgung, da ein Gerät, das die meiste Zeit im Deep Sleep verbringt, damit fälschlich dauerhaft als "nicht verfügbar" erschiene. Als optionale Alternative dazu: Ist der Heartbeat aktiv, tragen alle Discovery-Configs ein expire_after (2x Heartbeat-Intervall) — Home Assistant markiert die Entities dann von sich aus als "nicht verfügbar", wenn tatsächlich zu lange nichts mehr ankam.
• Heartbeat-Sensor als "letzter Kontakt": Eine zusätzliche sensor-Entity zählt Wake-Zyklen (Trigger und Heartbeat) auf <Basis-Topic>/heartbeat/state. Der ESP32 kennt dabei keine Uhrzeit (keine NTP-Synchronisation) — Home Assistant trackt für jede Entity ohnehin automatisch einen last_updated-Zeitstempel, der genau diese Rolle übernimmt, direkt in der HA-UI bzw. per Template nutzbar.
• Publishes werden bewusst entzerrt, nicht als Burst gefeuert: Nach jedem einzelnen publish() folgt eine kurze Pause (mqttClient.loop() + ~20 ms), zusätzlich ~200 ms Einschwingzeit direkt nach dem WLAN-Connect, bevor überhaupt losgesendet wird. Ohne das gingen bei einem Direktstart aus dem Deep Sleep (kein vorher verbundener USB-Host, z. B. reiner Akku-/Netzteilbetrieb) vereinzelt einzelne der bis zu 14 Nachrichten (7 Discovery + 4 State + 2 Batterie + 1 Heartbeat) auf Funkebene verloren — via MQTT QoS 0 (PubSubClient-Standard) gibt es dafür weder Bestätigung noch Retry, sodass die Firmware den Verlust nie bemerkte (Log zeigte durchgehend "erfolgreich", am Broker kam aber nichts an). Betraf reproduzierbar den ersten Verbindungsversuch nach einem Kaltstart ohne angeschlossenen USB-Host; ein zweiter Versuch kurz danach funktionierte meist schon. Statische IP statt DHCP behob es NICHT (schließt DHCP-/ARP-Timing als Ursache aus) — die Entzerrung schon (3/3 Testläufe auf Akku bzw. Fremdnetzteil erfolgreich, 2026-07-19).
• Verbindung erfolgt unverschlüsselt (TCP, Standardport 1883) — gedacht für einen Broker im eigenen lokalen Netz (z. B. das Mosquitto-Add-on von Home Assistant). Nutzername/Passwort sind optional.

Batterieüberwachung

Optionale Akku-Spannungsmessung, per Default deaktiviert, im WebUI unter "Batterie" aktivierbar:

• Messzeitpunkt: bei einer echten Trigger-Auslösung (EXT1-Wakeup), nicht bei jedem Cooldown-/Poll-Wake. Es gibt bewusst keine eigene periodische Wakeup-Quelle nur für die Akkumessung — der optionale Heartbeat ist ein allgemeiner, für andere Zwecke gedachter Mechanismus, den die Batteriemeldung lediglich mitnutzt, sobald ohnehin gerade gewacht/verbunden wird: bei MQTT-Kanal bei jedem Heartbeat-Wake, bei Push-Kanälen nur innerhalb des täglichen Lebenszeichens (falls beides aktiviert ist). In der Praxis bedeutet das: der Akkustand wird bei jeder Auslösung mitgemeldet, ganz ohne zusätzliche WLAN-Verbindung, die nicht ohnehin schon aufgebaut würde.
• Messung: ADC-Spannungsteiler, Default-Werte (Pin GPIO0, Faktor ×2) passen zum eingebauten Teiler des Referenzboards (FireBeetle 2 ESP32-C6, siehe DFRobot-Wiki) und sind bei abweichender Hardware im WebUI anpassbar. Die Umrechnung in Prozent erfolgt über eine lineare Näherung (3,3 V = 0 %, 4,2 V = 100 %) — kein Fuel-Gauge-IC, keine Kalibrierung gegen Zellalterung, ausreichend für eine grobe Warnschwelle, nicht für eine präzise Restlaufzeitanzeige.
• Meldung je nach Meldekanal (siehe Meldekanäle):
  • MQTT: kontinuierlicher Zustand als zwei retained Sensor-Entities (.../battery/state in Prozent, .../battery_voltage/state in Volt), inkl. Home-Assistant-Autodiscovery (device_class battery/voltage) nach demselben Muster wie die Eingänge.
  • Push-Kanäle (Telegram/Pushover/ntfy): einmalige Warnmeldung beim Unterschreiten der im WebUI konfigurierten Warnschwelle (Default 15 %) — kein Dauer-Spam bei jeder weiteren Auslösung. Die Warnung wird erst wieder gelöscht (und kann erneut auslösen), sobald der Ladezustand die Schwelle um mehr als 10 Prozentpunkte übersteigt (Hysterese gegen Flattern knapp um die Schwelle).

Hardware

• Microcontroller: DFRobot FireBeetle 2 ESP32-C6 (DFR1075) — ESP32-C6-Modul (RISC-V, WLAN 6 + BLE 5.0), Referenz-/Empfehlungsboard für dieses Projekt. Der Code selbst bleibt board-agnostisch, solange GPIO0–7 (Trigger) zugänglich sind; auf dem FireBeetle 2 ist GPIO0 allerdings fest für die eingebaute Akku-Spannungsmessung reserviert (siehe Batterieüberwachung) und steht daher nicht als Trigger-Pin zur Verfügung. Die BOOT-Taste (GPIO9) wird von der Firmware für die Rekonfiguration genutzt (5-Sekunden-Fenster nach Power-On/Reset) — zusätzlich zu ihrer üblichen Rolle beim Flashen über esptool.

• Stromversorgung: Getesteter/empfohlener Akku: Meshnology-Akku (gleiche Baureihe, hier in der 3000-mAh-Variante statt der ursprünglich dokumentierten 5000-mAh-Zelle), 3,7 V nominal, PH-2.0-Steckverbinder (passend zum Akku-Anschluss des FireBeetle 2, mechanisch gesteckt statt gedrahtet), mit eingebauter Schutzplatine gegen Tiefentladung/Kurzschluss. Max. Ladestrom laut Datenblatt der 3000-mAh-Variante vor Inbetriebnahme gegenprüfen — bei der 5000-mAh-Variante lag er bei 2,5 A und damit weit über den ≈540 mA, mit denen der eingebaute Lade-IC des Boards (CN3165, USB-C) tatsächlich lädt (unkritisch, nur entsprechend lange Ladezeit); kleinere Zellen können einen geringeren zulässigen Ladestrom haben. Überlade-/ Überentladeschwellen (4,2 V / 3,0 V) und Ladetemperaturbereich (0–45 °C) decken sich mit den Werten, auf denen die Batterieüberwachung dieses Projekts aufbaut, siehe Batterieüberwachung. Bewusst kein 18650: runde Zellen sind ohne eigene Schutzplatine üblich und müssten separat abgesichert werden.

  

  ⚠️ Sicherheitshinweise:

  • Akku nicht im eingebauten/verschlossenen Zustand laden. Stattdessen den Akku aus der Paketbox entnehmen und über sein eigenes, mitgeliefertes USB-Ladekabel außerhalb laden (der Lade-IC des Boards bleibt dabei ungenutzt) — sowohl wegen des Thermal-Runaway-Risikos einer Lithium-Zelle in einem geschlossenen Gehäuse als auch weil ein USB-Kabel durch eine Paketbox ohnehin unpraktikabel ist.
  • Laden bei Kälte ist nicht vorgesehen und wird von der Firmware nicht abgesichert (kein Temperatur-Gate) — nur bei Zimmertemperatur laden (0–45 °C laut Akku-Datenblatt). Siehe auch Bekannte offene Punkte.

• Gemessener Ruhestrom & Akkulaufzeit (2026-07-16, PPK2-Messung): Deep-Sleep-Durchschnitt 37,88 µA, stabil über mehrere Minuten gemessen (kurze periodische Spikes bis ~490 µA alle ~23 ms sind normales Regler-/RTC-Refresh-Verhalten des Power-Managements, kein Firmware-Effekt — im Deep Sleep läuft kein Anwendungscode). Ein einzelner Meldezyklus (EXT1-Wake → WLAN verbinden → Nachricht senden → zurück in Sleep) kostet zusätzlich ≈ 5,1 µAh. Diese Messung stammt von vor der MQTT-Publish-Entzerrung (s. u.) — bei aktivem MQTT-Kanal kommen dadurch nochmal grob 0,3–0,7 s zusätzliche Wachzeit pro Zyklus dazu, bislang nicht neu gemessen. Beispielrechnung mit dem oben empfohlenen 3,7 V/3000-mAh-Akku:

  • Ruhestrom: 37,88 µA × 24 h ≈ 0,91 mAh/Tag
  • Selbst bei 20 Auslösungen/Tag: zusätzlich nur ≈ 0,10 mAh/Tag
  • Gesamt ≈ 1,01 mAh/Tag → 3000 mAh ÷ 1,01 mAh/Tag ≈ ~8 Jahre rechnerische Standby-Zeit

  In der Praxis begrenzt nicht der Stromverbrauch der Elektronik die Akkulaufzeit, sondern die Selbstentladung der Li-Ion-Zelle (typ. 2–5 %/Monat).

• Gehäuse: Elektronik möglichst außerhalb metallischer Gehäuse (Faraday-Käfig-Effekt) montieren, nur die dünne Schalter-Verkabelung nach innen führen.

Setup

1. Bauen und flashen (Konfiguration erfolgt anschließend über das WebUI):

   pio run --target upload
   

   Alternativ ohne Kommandozeile: siehe Web-Flasher oben.
2. Gerät startet, öffnet mangels Konfiguration automatisch das Setup-WLAN ESP-Kerberos-Setup-XXXX — siehe Konfiguration über WebUI.
3. Formular ausfüllen und speichern. Gerät startet neu und läuft im Normalbetrieb.

Projektstruktur

ESP-Kerberos/
├── platformio.ini
├── merge_bin.py         # Post-Build-Hook: erzeugt docs/ESP-Kerberos-merged.bin
├── README.md
├── LICENSE
├── docs/                # GitHub-Pages-Root: Web-Flasher
│   ├── index.html       # ESP Web Tools UI
│   ├── manifest.json    # Firmware-Manifest für den Flasher
│   ├── ESP-Kerberos-merged.bin  # von merge_bin.py generiert — USB-Erstflash, nicht für OTA
│   └── ESP-Kerberos-ota.bin     # von merge_bin.py generiert — Upload im Setup-Portal (/update)
└── src/
    ├── main.cpp            # Boot-Orchestrierung, Sleep/Wake, Entprellung
    ├── kerberos_config.h   # Config-Struct + Enums (header-only)
    ├── config_store.h/.cpp # NVS laden/speichern (Preferences)
    ├── portal.h/.cpp       # AP + Captive Portal + Webformular + OTA-Firmware-Upload
    ├── notify.h/.cpp       # Telegram/Pushover/ntfy-Versand
    ├── mqtt.h/.cpp         # MQTT-Zustands-Publish + Home-Assistant-Discovery
    ├── battery.h/.cpp      # Akku-ADC-Messung + Prozent-Näherung
    └── debug_log.h         # Serial-Debug-Logging, per Build-Flag abschaltbar

Debug-Logging über die serielle Konsole

Standardmäßig aktiv (KERBEROS_DEBUG=1), 115200 Baud (pio device monitor). Loggt Boot-/Wake-Ursache, WLAN-Verbindungsstatus, Portal-/Scan-Ereignisse und HTTP-Antwortcodes der Meldekanäle — bewusst ohne Passwörter/Tokens im Log. Für den späteren Batteriebetrieb abschaltbar (spart die minimale Restlaufzeit, die Serial.begin()/Prints kosten):

build_flags = -DKERBEROS_DEBUG=0

Bekannte offene Punkte

• Ruhestrom durch interne Pull-ups bei geschlossenem Ruhekontakt: Der interne Pull-up für den EXT1-Wakeup hält zusätzlich die RTC_PERIPH-Domäne während des Deep Sleep aktiv, was den Ruhestrom leicht erhöht. Relevanter ist der Fall triggerOnOpen = true (Default aller 4 Eingänge): Der Ruhezustand ist dabei "Kontakt geschlossen", der interne Pull-up (laut ESP32-C6-Datenblatt näherungsweise 45 kΩ) liegt dann dauerhaft über den geschlossenen Schalter an GND — rechnerisch rund 70 µA pro so beschaltetem Eingang (3,3 V ÷ 45 kΩ), bei allen 4 Eingängen im ungünstigsten Fall in Summe rund 280 µA zusätzlich, auch im Deep Sleep. Das ist eine Schätzung nach Datenblattwert, keine gemessene Zahl — eine PPK2-Verifikation der tatsächlichen internen Pull-up-Stromstärke des C6 im Deep Sleep steht noch aus. Zwei Möglichkeiten zur Entschärfung, falls relevant:
  • Kontakte/Schalter so montieren bzw. wählen, dass der Ruhezustand "offen" ist (triggerOnOpen = false) — dann fließt im Ruhezustand kein Pull-up-Strom über den Schalter, nur kurzzeitig während der Auslösung selbst.
  • Statt des internen Pull-ups einen externen ~1-MΩ-Pull-up je Eingang verwenden (reduziert den Ruhestrom um etwa den Faktor 20 gegenüber den internen ~45 kΩ) — dafür aktuell keine Firmware-Unterstützung, da die interne rtc_gpio_pullup_en()-Konfiguration fest verdrahtet ist.
• Akku-Sicherheit bei Außenmontage (z. B. Briefkasten): Li-Ion-Zellen dürfen laut den meisten Zellenherstellern nicht unter 0 °C geladen werden (Lithium-Plating-Risiko). Ob der TEMP-Pin des CN3165 an einen NTC im Akkupack angeschlossen ist oder nur fest verdrahtet (d. h. die Temperaturüberwachung faktisch deaktiviert), lässt sich aus dem Schaltplan allein nicht zuverlässig klären und muss an der realen Hardware nachgemessen bzw. im DFRobot-Wiki verifiziert werden. Bis dahin gilt uneingeschränkt: Akku nur kontrolliert bei Zimmertemperatur laden (siehe Hardware), nicht bei Wintermontage im Freien.
• Software-Reset für vergessenes AP-Passwort (erwogen, zurückgestellt): Aktuell nur per USB/Web-Flasher behebbar (AP-Passwort vergessen), was einen Computer/Browser voraussetzt. Eine BOOT-Taste-Geste (z. B. ~10s halten → Preferences::clear() + Neustart) wäre bequemer für ein bereits fest montiertes Gerät, wurde aber zurückgestellt — dupliziert technisch nur den bereits vorhandenen Reflash-Reset und würde die BOOT-Taste-Zeitfenster-Logik (main.cpp, aktuell reine Ja/Nein-Erkennung statt Haltedauer-Messung) nicht unerheblich verkomplizieren.