espectre snapshot-dev
ESPectre - Bewegungserkennungssystem basierend auf Wi-Fi-Spektralanalyse (CSI), mit Home-Assistant-Integration.
ESPectre 
Verwandle einen ESP32 in einen privaten, lokalen Wi-Fi-Bewegungssensor.
Wenn sich jemand durch einen Raum bewegt, verändert das die Art, wie Wi-Fi-Signale durch ihn hindurchlaufen. ESPectre liest diese Veränderungen und meldet Bewegungen in Echtzeit. Keine Kamera, kein Mikrofon, kein Wearable und keine dedizierte Radar-Hardware: nur ein unterstützter ESP32 und das bereits im Raum vorhandene Wi-Fi-Netzwerk.
ESPectre ist eine Open-Source-Plattform, die fertig flasbare Firmware, ein einbettbares C++-SDK, eine MicroPython-Implementierung, Browser-Tools, eine Host-CLI, einen offenen Datensatz, offene Modellgewichte und den Forschungs-Workflow zusammenbringt, der zum Erstellen und Validieren der Detektoren verwendet wurde.
Flash aus dem Browser · Live-Tools ansehen · Dokumentation lesen · SDK erkunden
Anwendungen und Integrationen
ESPectre kann ein Display oder Licht einschalten, wenn es Bewegungen erkennt, Heizung und Kühlung als Reaktion auf Raumaktivität anpassen, einen Alarm oder eine Benachrichtigung auslösen, wenn Bewegungen in einem Bereich auftreten, der leer sein sollte, und andere Raumautomationen steuern. Es verbindet sich über ESPHome oder MQTT mit Home Assistant, stellt einen standardmäßigen Matter-Occupancy-Sensor und eine lokale Direct-HTTP-API bereit und kann über das C++-SDK in benutzerdefinierte ESP32-Firmware eingebettet werden.
ESPectre verarbeitet CSI auf dem Gerät und meldet einen Bewegungszustand und einen Bewegungswert. Anwendungen können reagieren, ohne rohe Sensordaten an einen Cloud-Dienst zu senden. Eine Platine deckt einen Erfassungsbereich ab; eine Abdeckung auf Raumebene erfordert normalerweise eine Platine pro Raum.
ESPectre erkennt Veränderungen in der Funkumgebung. Es identifiziert keine Personen, zählt sie nicht, beweist nicht, dass ein Raum leer ist, und ersetzt kein sicherheitszertifiziertes Sicherheits-, medizinisches oder Notfallsystem.
Unterstützte Hardware
- ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 und klassischer ESP32
- ein normales Wi-Fi-4-Netzwerk (802.11n) auf 2,4 GHz
Firmware-Pfad wählen
| Pfad | Am besten geeignet für | Hier starten |
|---|---|---|
| Nativ | Eigenständige Sensoren, MQTT-Integrationen, einschließlich Home Assistant MQTT Discovery, und benutzerdefinierte Anwendungen | Native Frontend |
| ESPHome | Home-Assistant-Nutzer, die native Entitäten, ESPHome-Provisionierung und Device-Builder-Updates wünschen | ESPHome-Frontend |
| Matter | Matter-Controller mit Unterstützung für Occupancy-Sensoren; die Controller-Validierung ist noch begrenzt | Matter-Frontend |
| Micro-ESPectre | Leichtgewichtige Erfassung in MicroPython mit lokalem, schreibgeschütztem Direct-HTTP-Monitoring | Micro-ESPectre-README |
Native, ESPHome und Matter können zwischen einem lightweight-Detektor, der beim Start einen raumspezifischen Schwellenwert lernt und mehr Ressourcen für den Rest der Anwendung übrig lässt, und einem high_accuracy-Detektor, der das im Repository enthaltene trainierte Modell ausführt, wählen. Ihr Verhalten und die gemessenen Kompromisse sind in SETUP.md, ALGORITHMS.md und dem Leistungsbericht dokumentiert.
Schnellstart
Der schnellste Weg nutzt den Browser und erfordert keine lokale Build-Umgebung. Verwenden Sie Desktop-Chrome 151 oder neuer für den vollständigen gehosteten Workflow. Edge unterstützt Browser-Flashing, aber die Kompatibilität mit Geräteeinstellungen und Monitor ist nicht garantiert:
- Öffnen Sie Flash in Desktop-Chrome oder Edge.
- Verbinden Sie einen unterstützten ESP32 über USB und wählen Sie dann eine Firmware und einen Release-Kanal.
- Schließen Sie die Wi-Fi-Provisionierung auf dem Bildschirm ab oder beauftragen Sie Matter mit einem unterstützten Controller.
- Öffnen Sie optional Geräteeinstellungen, um einen bevorzugten Zugangspunkt festzulegen oder MQTT einzurichten.
- Öffnen Sie Monitor, um Bewegungen zu beobachten, die Erkennung abzustimmen und das Gerät zu inspizieren.
Matter-Status: Das Matter-Frontend wird noch über Controller-Ökosysteme hinweg validiert. Ein Controller kann standardmäßige Matter-Occupancy-Sensoren unterstützen, ohne mit der aktuellen Firmware getestet worden zu sein. Siehe Matter-Controller-Kompatibilität für die aktuelle Matrix.
Lokale Einrichtung
Für lokale Builds, das Flashen aus diesem Repository und den Rest des Betreiberpfads beginnen Sie mit SETUP.md. Der Repository-Wrapper stellt die verfügbaren Workflows bereit über:
./espectre --help
Dokumentation
| Thema | Was es abdeckt | Anleitungen |
|---|---|---|
| Installieren und betreiben | Geräteeinrichtung, CLI-Workflows und Detektor-Abstimmung | SETUP.md, CLI.md, TUNING.md |
| Verstehen und integrieren | Laufzeitarchitektur, API, Erkennung, Algorithmen und das C++-SDK | ARCHITECTURE.md, API.md, DISCOVERY.md, ALGORITHMS.md, SDK.md |
| Sammeln und trainieren | CSI-Erfassung, Modelltraining, Feature-Historie, Leistung und Literatur | ML_DATA_COLLECTION.md, ML_TRAINING.md, FEATURES.md, Leistungsbericht, LITERATURE.md |
| Forschung und Richtung | Roadmap, Architekturentscheidungen und Release-Historie | ROADMAP.md, ADR-Index, CHANGELOG.md |
| Frontend-Referenz | Firmware-Pfad-READMEs für ESPHome, Native, Matter und Micro-ESPectre | ESPHome, Native, Matter, Micro |
| Mitwirken | Wie man beiträgt und wo das Projekt diskutiert wird | CONTRIBUTING.md, GitHub Discussions |
Datensätze, Modelle und Validierung
ESPectre veröffentlicht die Forschungsressourcen und Validierungsnachweise hinter seinen Detektoren:
| Ressource | Was sie Ihnen bietet | Hier starten |
|---|---|---|
| CSI-Datensatz | Echte Aufnahmen für leere Räume, statische Präsenz und Bewegung, mit Katalog und Herkunft in dataset_info.json | data/ |
| Modellgewichte | Trainierte Gewichte in C++ und Python, plus den Trainings-, Export- und Validierungs-Workflow | ML_TRAINING.md |
| Feature-Ledger | Features, die getestet, übernommen oder abgelehnt wurden, einschließlich erfolgloser Experimente | FEATURES.md |
| Algorithmen und Berichte | Detektor-Verhalten, der generierte Leistungsbericht und der Datensatz-Qualitätsbericht | ALGORITHMS.md |
| Literatur und Richtung | Externe Forschung, Architekturentscheidungsprotokolle und die öffentliche Roadmap | LITERATURE.md |
Sicherheit, Datenschutz und Transparenz
Ein Sensor, der Präsenz offenbaren kann, sollte keine Blackbox sein. Wi-Fi-Erfassung vermeidet Bilder und Audio, aber Bewegungs- und Belegungsdaten können dennoch Routinen, Schlaf oder Abwesenheit von zu Hause offenbaren. ESPectre behandelt dieses Risiko als Teil der Ingenieursarbeit:
- Bewegungserkennung ist lokal, und Cloud-Konnektivität ist nicht erforderlich;
- die Erfassung roher CSI ist optional und für definierte Forschungs- und Debugging-Zwecke gedacht;
- der Leitfaden zu Sicherheit und verantwortungsvoller Nutzung dokumentiert Einsatzgrenzen, Einwilligung, Datenminimierung, Missbrauchsmeldung und private Schwachstellenmeldung;
- Firmware-Releases enthalten buildspezifische SBOMs, Hinweise und Lizenzarchive, damit ihr Inhalt geprüft werden kann;
- die öffentliche Website und jedes Browser-Tool sind Teil dieses Repositorys unter docs/web, einschließlich ihrer Quelle, Datenschutzregeln, Analysevertrag und festgelegten Browser-Abhängigkeiten;
- Protokolle, Algorithmen, Leistungsnachweise, Einschränkungen, Roadmap-Entscheidungen und bekannte Validierungsgrenzen sind öffentlich dokumentiert.
Verwenden Sie ESPectre nur in Räumen und Netzwerken, in denen Sie das Recht haben, es einzusetzen. Informieren Sie betroffene Personen, holen Sie die erforderliche Einwilligung ein, schützen Sie den Zugriff auf das Gerät und seine Daten und befolgen Sie die geltenden Datenschutzgesetze.
Danksagungen
- Dank an Espressif dafür, dass CSI in ESP-IDF zugänglich gemacht wurde und ESPectre als Community-Projekt in esp-csi anerkannt wurde.
- Dank an die MicroPython-Maintainer für die Überprüfung, das Testen und das Zusammenführen von ESPectres CSI-Beitrag, der direkte CSI-Methoden zum Hauptlinien-
network.WLANhinzugefügt hat.
Lizenz
ESPectre-Erstparteicode ist unter GPLv3 verfügbar, und berechtigte Teile sind auch unter einer separaten kommerziellen Vereinbarung verfügbar:
- Wählen Sie GPLv3, wenn Ihre Firmware oder Anwendung GPLv3 einhalten kann, einschließlich der Bereitstellung des entsprechenden Quellcodes. Siehe LICENSE.
- Wenn Sie ESPectre in proprietäre oder Closed-Source-Firmware einbetten möchten, ohne die GPLv3-Quelloffenlegungspflichten, siehe LICENSING.md für kommerzielle Lizenzierung. Die kommerzielle Lizenz deckt berechtigtes Material ab und ersetzt keine Drittanbieterbedingungen; das ESPHome-C++-Frontend bleibt ausschließlich GPLv3.
Drittanbieterbedingungen und buildspezifische Compliance-Artefakte sind in THIRD_PARTY_NOTICES.md beschrieben.