ESP-ion

Batteriebetriebener Öffnungsmelder auf ESP32-C6-Basis.

Ursprünglich für einen Briefkasten gedacht ("Post ist da"), 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) 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-ion — 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-ion-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 oder ntfy.sh) — 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-ion-Setup-XXXX (offen, ohne Passwort; XXXX = letzte zwei MAC-Adress-Bytes, zur Unterscheidung mehrerer Geräte).

• 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, sowie bis zu 3 unabhängige Eingänge (siehe Mehrere Eingänge) — Eingang 1 ist standardmäßig aktiv, Eingang 2 und 3 sind per Checkbox einzeln zu aktivieren —, jeder mit eigenem GPIO-Pin, eigener Auslöse-Polarität und eigenem Nachrichtentext, gewünschter Meldekanal (gilt für alle Eingänge gemeinsam) 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 (solange der Flash nicht komplett gelöscht wird).

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 als Deep-Sleep-Wakeup-Quelle nutzbar (im WebUI ist die Auswahl entsprechend auf GPIO0–7 begrenzt). 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).

Mehrere Eingänge

ESP-ion überwacht bis zu 3 unabhängige Eingänge gleichzeitig, z. B. Briefkastenklappe + Gartentür + Garagentor an einem einzigen Gerät. 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 erkennen lässt, welcher Kontakt ausgelöst hat.

Der Meldekanal (Telegram/Pushover/ntfy) 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.

Hardware

• Microcontroller: ESP32-C6-Mini-Modul (RISC-V, WLAN 6 + BLE 5.0). Board-unabhängig, solange GPIO0–7 (Trigger) zugänglich sind. Die BOOT-Taste wird von der Firmware nicht benötigt (nur zum Flashen über esptool relevant).
• Stromversorgung: Li-Ion-Akku (z. B. 18650, 3,7 V nominal), angeschlossen an die BAT+/BAT−-Pads des Moduls. Laden erfolgt über den eingebauten Lade-IC via USB-C. ⚠️ Sicherheitshinweis: Nach Möglichkeit eine protected cell (mit eingebauter Schutzschaltung gegen Tiefentladung/Kurzschluss) verwenden — viele einfache Lade-ICs auf Clone-Modulen schützen nur beim Laden, nicht beim Entladen. Vor Dauerbetrieb den Lade-IC des jeweiligen Moduls identifizieren und dessen Datenblatt (Ladestrom, Abschaltspannung) prüfen. BAT+/BAT−-Verbindung mechanisch sicher und verpolungssicher ausführen (kein loses Gedrahte). Siehe auch Bekannte offene Punkte.
• 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-ion-Setup-XXXX — siehe Konfiguration über WebUI.
3. Formular ausfüllen und speichern. Gerät startet neu und läuft im Normalbetrieb.

Projektstruktur

ESP-ion/
├── platformio.ini
├── merge_bin.py         # Post-Build-Hook: erzeugt docs/ESP-ion-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-ion-merged.bin  # von merge_bin.py generiert, nicht manuell pflegen
└── src/
    ├── main.cpp            # Boot-Orchestrierung, Sleep/Wake, Entprellung
    ├── espion_config.h     # Config-Struct + Enums (header-only)
    ├── config_store.h/.cpp # NVS laden/speichern (Preferences)
    ├── portal.h/.cpp       # AP + Captive Portal + Webformular
    ├── notify.h/.cpp       # Telegram/Pushover/ntfy-Versand
    └── debug_log.h         # Serial-Debug-Logging, per Build-Flag abschaltbar

Debug-Logging über die serielle Konsole

Standardmäßig aktiv (ESPION_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 = -DESPION_DEBUG=0

Bekannte offene Punkte

• Ruhestrom des eingebauten Lade-/Regel-ICs im Deep Sleep ist bei generischen Clone-Modulen oft nicht dokumentiert und sollte nach Erhalt der Hardware gemessen werden.
• Der interne Pull-up für den EXT1-Wakeup hält die RTC_PERIPH-Domäne während des Deep Sleep aktiv, was den Ruhestrom leicht erhöht. Ein externer Pull-Widerstand könnte das minimieren.
• 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). Der eingebaute Lade-IC generischer Module hat i. d. R. keine Temperaturüberwachung — bei Wintermontage ohne beheizten/gedämmten Aufbau bzw. ohne Ladeunterbrechung bei Kälte ist das ein reales Risiko, nicht nur ein theoretisches. Ebenso unklar bei Clone-Modulen: ob der Lade-IC einen Überstrom-/Kurzschlussschutz besitzt.