francescopace/espectreESPectre - Bewegungserkennungssystem basierend auf Wi-Fi-Spektralanalyse (CSI), mit Home-Assistant-Integration.
Bewegungserkennungssystem basierend auf Wi-Fi-Spektrumanalyse (CSI), mit nativer Home-Assistant-Integration über ESPHome.
[!TIP] Neuer ML-Detektor: Bewegungserkennung auf Basis neuronaler Netze. Keine Kalibrierung erforderlich, läuft auf dem Gerät. Dies ist eine experimentelle Funktion; Feedback ist in der dedizierten ML-Detektor-Diskussion willkommen. Ein Snapshot-Build mit den neuesten Änderungen ist ebenfalls verfügbar (verwenden Sie die
-ml-Assets für den auf maschinellem Lernen basierenden Detektor), oder folgen Sie der Einrichtungsanleitung für eine individuelle Konfiguration.
ESP32-S3 DevKit mit externen Antennen
Einrichtungszeit: ~10-15 Minuten
Schwierigkeitsgrad: Einfach (nur YAML-Konfiguration)
Home-Assistant-Dashboard mit Echtzeit-Bewegungserkennung, Schwellenwertsteuerung und Debug-Sensoren
Wenn sich jemand in einem Raum bewegt, "stört" er die Wi-Fi-Wellen, die zwischen Router und Sensor wandern. Es ist, als ob du deine Hand vor eine Taschenlampe hältst und siehst, wie sich der Schatten verändert.
Das ESP32-Gerät "hört" auf diese Veränderungen und erkennt, ob Bewegung vorhanden ist.
Möchtest du die technischen Details verstehen? Siehe ALGORITHMS.md für die Erklärung von CSI und die Dokumentation zur Signalverarbeitung.
Eine optimale Sensorplatzierung ist entscheidend für eine zuverlässige Bewegungserkennung.
Optimaler Bereich: 3-8 Meter
Richtig:
Falsch:
ESPectre verwendet eine fokussierte Verarbeitungspipeline für die Bewegungserkennung:``` ┌─────────────┐ │ CSI Data │ Raw Wi-Fi Channel State Information └──────┬──────┘ │ ▼ ┌─────────────┐ │ Gain Lock │ AGC/FFT stabilization (~3 seconds) │ │ Locks hardware gain for stable measurements └──────┬──────┘ │ ▼ ┌─────────────┐ │ Auto │ Automatic subcarrier selection (once at boot) │ Calibration │ Selects optimal 12 subcarriers (NBVI) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Adaptive │ auto: P95 × 1.1 | min: P100 │ Threshold │ or fixed manual value └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hampel │ Turbulence outlier removal │ Filter │ (enabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Low-pass │ Noise reduction (smoothing) │ Filter │ (optional, disabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Detection │ MVS or ML score │ Evaluation │ every evaluation_interval packets └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hit Filter │ motion_on_hits / motion_off_hits │ │ edge-driven IDLE ↔ MOTION └──────┬──────┘ │ ▼ ┌─────────────┐ │ Home │ Edge-driven motion binary + │ Assistant │ periodic Movement Score / Threshold └─────────────┘
### Einzelner oder mehrere Sensoren```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
Jeder Sensor wird automatisch von Home Assistant erkannt mit:
ESPectre implementiert NBVI (Normalized Band Variance Index) für die automatische Subcarrier-Auswahl und erreicht nahezu optimale Leistung (F1>96%) mit null manueller Konfiguration. Der Algorithmus wählt 12 nicht aufeinanderfolgende Subcarrier basierend auf Stabilitätskennzahlen und spektraler Diversität aus.
⚠️ WICHTIG (MVS-Modus): Halten Sie den Raum nach dem Gerätestart 10 Sekunden lang ruhig und still. Die automatische Kalibrierung läuft während dieser Zeit und Bewegung beeinträchtigt die Erkennungsgenauigkeit. Der ML-Modus überspringt die Kalibrierung.
Details zum Algorithmus finden Sie unter ALGORITHMS.md.
F: Benötige ich Programmierkenntnisse, um es zu nutzen?
A: Nein! ESPectre verwendet YAML-Konfigurationsdateien. Laden Sie einfach das Beispiel herunter, flashen Sie es und konfigurieren Sie WLAN über die ESPHome-App oder die Webschnittstelle.
F: Funktioniert es mit meinem Router?
A: Ja, wenn Ihr Router über 2,4-GHz-WLAN verfügt (praktisch alle modernen Router haben das).
F: Wie viel kostet das insgesamt?
A: Hardware: ~10 € für ein ESP32-Gerät (S3/C6 empfohlen, andere Varianten funktionieren ebenfalls). Software: Alles kostenlos und Open Source. Sie benötigen außerdem eine laufende Home-Assistant-Instanz (Raspberry Pi ~35–50 € oder ein beliebiger vorhandener PC/NAS).
F: Muss ich am Router etwas ändern?
A: Nein! Der Router arbeitet normal. Der Sensor „hört“ WLAN-Signale ab, ohne etwas zu verändern.
F: Funktioniert es durch Wände?
A: Ja, das 2,4-GHz-WLAN-Signal durchdringt Trockenbauwände. Stahlbetonwände verringern die Empfindlichkeit, aber die Erkennung bleibt bei reduzierten Entfernungen möglich.
F: Wie viele Sensoren werden für ein Haus benötigt?
A: Das hängt von der Größe ab. Ein Sensor kann ~50 m² überwachen. Für größere Häuser verwenden Sie mehrere Sensoren (1 Sensor pro 50–70 m² für optimale Abdeckung).
F: Kann es zwischen Menschen und Haustieren unterscheiden?
A: Das System verwendet ein 2-Zustands-Segmentierungsmodell (IDLE/MOTION), das generische Bewegungen erkennt, ohne zwischen Menschen, Haustieren oder anderen sich bewegenden Objekten zu unterscheiden. Für eine anspruchsvollere Klassifizierung (Menschen vs. Haustiere, Aktivitätserkennung, Gestenerkennung) wären trainierte KI-/ML-Modelle erforderlich (siehe Abschnitt Zukünftige Entwicklung).
F: Funktioniert es mit Mesh-WLAN-Netzwerken?
A: Ja, es funktioniert normal. Stellen Sie sicher, dass der ESP32 mit dem 2,4-GHz-Band verbunden ist.
F: Wie genau ist die Erkennung?
A: Die Erkennungsgenauigkeit ist stark umgebungsabhängig und erfordert eine ordnungsgemäße Abstimmung. Zu den Faktoren, die die Leistung beeinflussen, gehören: Raumaufteilung, Wandmaterialien, Möbelplatzierung, Entfernung zum Router (optimal: 3–8 m) und Störungspegel. Unter optimalen Bedingungen mit richtiger Abstimmung bietet das System eine zuverlässige Bewegungserkennung. Passen Sie den Parameter segmentation_threshold an, um die Empfindlichkeit für Ihre spezifische Umgebung einzustellen.
Das System sammelt anonyme Daten zu den physikalischen Eigenschaften des WLAN-Funkkanals:
CSI-Daten repräsentieren nur die Eigenschaften des Übertragungsmediums und enthalten keine direkten Identifikationsinformationen.
WARNUNG: Trotz der inhärenten Anonymität der CSI-Daten kann dieses System verwendet werden für:
Der Nutzer ist allein verantwortlich für die Nutzung dieses Systems und muss:
Details zu den Algorithmen (MVS, NBVI-Kalibrierung, Hampel-Filter) finden Sie unter ALGORITHMS.md.
Leistungskennzahlen (Konfusionsmatrix, F1-Score, Benchmarks) finden Sie unter PERFORMANCE.md.
Dieses Projekt verfolgt einen Zwei-Plattform-Ansatz, um Innovationsgeschwindigkeit mit Produktionsstabilität auszugleichen:
Zielgruppe: Endnutzer, Smart-Home-Enthusiasten, Home-Assistant-Nutzer
Zielgruppe: Forscher, Entwickler, akademische/industrielle Anwendungen
Micro-ESPectre liefert die Grundlagen für:
┌─────────────────────┐ Validated ┌──────────────────────┐ │ Micro-ESPectre │ ─────────────────► │ ESPectre │ │ (R&D Platform) │ algorithms │ (Production Platform)│ │ │ │ │ │ • Fast prototyping │ │ • ESPHome component │ │ • Algorithm testing │ │ • Home Assistant │ │ • Data analysis │ │ • End-user ready │ │ • MQTT flexibility │ │ • Native API │ └─────────────────────┘ └──────────────────────┘
**Innovationszyklus**: Neue Funktionen und Algorithmen werden zunächst in Micro-ESPectre (Python) entwickelt und validiert und anschließend in ESPectre (C++) portiert, sobald sie sich als wirksam erwiesen haben.
---
## Zukünftige Entwicklung
Während sich ESPectre v2.x auf die **Bewegungserkennung** (MVS + automatische Subträgerauswahl) konzentriert, untersucht das Projekt derzeit die Möglichkeiten des maschinellen Lernens für erweiterte Anwendungen:
| Capability | Status | Description |
|------------|--------|-------------|
| **ML-Detektor** | Experimentell | Neuronales Netz (MLP 9→32→16→1)|
| **Gestenerkennung** | Geplant | Handgesten erkennen (Wischen, Drücken, Kreisen) für die Smart-Home-Steuerung |
| **Erkennung menschlicher Aktivitäten** | Geplant | Aktivitäten identifizieren (Sitzen, Gehen, Stürzen) |
| **Personenzählung** | Geplant | Anzahl der Personen in einem Raum schätzen |
| **3D-Lokalisierung** | Forschung | Innenraumpositionierung (30-50cm Genauigkeit) über phasenkohärentes Antennenarray |
Der ML-Detektor ist bereits mit `detection_algorithm: ml` in Ihrer YAML-Konfiguration verfügbar. Details zum Algorithmus finden Sie in [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector) und in `PERFORMANCE.md` für aktuelle Metriken
Die Infrastruktur für ML-Datenerfassung und -training ist in [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) dokumentiert.
Siehe [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) für detaillierte Pläne, Zeitpläne und Informationen zur Mitarbeit.
---
## Dokumentation
### ESPectre (Produktion)
| Dokument | Beschreibung |
|----------|-------------|
| [Einführung](https://github.com/francescopace/espectre/blob/HEAD/README.md) | (Diese Datei) Projektübersicht, Schnellstart, FAQ |
| [Setup-Anleitung](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | Installation und Konfiguration mit ESPHome |
| [Tuning-Anleitung](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | Parametereinstellung für optimale Erkennung |
| [Leistung](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | Benchmarks, Konfusionsmatrix, F1-Score |
| [Das Spiel](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | Browserspiel, USB-Streaming-API, interaktive Schwellenwert-Einstellung |
| [Test-Suite](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | PlatformIO-Unity-Testdokumentation |
### Micro-ESPectre (F&E)
| Dokument | Beschreibung |
|----------|-------------|
| [Einführung](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | Überblick über die F&E-Plattform, CLI, MQTT, Web-Monitor |
| [Algorithmen](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | Wissenschaftliche Dokumentation von MVS, NBVI-Kalibrierung, Hampel-Filter |
| [Analysewerkzeuge](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | CSI-Analyse- und Optimierungsskripte |
| [ML-Datenerfassung](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | Erstellung gelabelter Datensätze für maschinelles Lernen |
| [Referenzen](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | Wissenschaftliche Arbeiten und Forschungsressourcen |
### Projekt
| Dokument | Beschreibung |
|----------|-------------|
| [Roadmap](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | Projektvision und ML-Pläne |
| [Mitwirken](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | So können Sie beitragen (Code, Daten, Doku) |
| [Changelog](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | Versionshistorie und Versionshinweise |
| [Sicherheit](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | Sicherheitsrichtlinie und Meldung von Schwachstellen |
| [Verhaltenskodex](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | Community-Richtlinien |
---
## Medien
| Artikel | Titel |
|-------------|-------|
| Medium | [Wie ich mein Wi-Fi in einen Bewegungssensor verwandelt habe - Teil 1](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-61a631a9b4ec?sk=c7f79130d78b0545fce4a228a6a79af3&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| Medium | [Wie ich mein Wi-Fi in einen Bewegungssensor verwandelt habe - Teil 2](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-part-2-62038130e530?sk=7c8b6f11cf3fcb8d279648016ebff72a&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| IoT For All | [Wie ich mein Wi-Fi in einen Bewegungssensor verwandelt habe](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [Bauen Sie Ihren eigenen ESP32-basierten Personensensor, ganz ohne spezielle Hardware](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [ESPectre-Personendetektor für Feather](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [Espectre auf der Seeed-Studio-XIAO-ESP32-Serie mit ESPHome bereitstellen](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| Blog | Diskussion |
|----------|------------|
| Home Assistant | [ESPectre - Wi-Fi-Bewegungserkennung für Home Assistant](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| Videos | Video |
|---------|-------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| Podcasts | Folge |
|-------------|---------|
| Hackaday | [Podcast-Folge 355: Personendetektoren, Walkie-Talkies, offene Smartphones...](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## Verwandte Projekte
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner): ergänzendes Projekt zur Präsenzerkennung, das sich auf BLE-Funkbeobachtungen von Host-Geräten (Python) konzentriert, mit optionalem HTTP-Dashboard.
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi): benutzerdefinierter MicroPython-Fork, der die ESP32-CSI-APIs bereitstellt und als Firmware-Grundlage für schnelles CSI-Prototyping im Micro-ESPectre-Workflow dient.
---
## Danksagungen
ESPectre nutzt die nativen Wi-Fi-CSI-Fähigkeiten von ESP32-Chips. Dank an [Espressif](https://www.espressif.com/) dafür, dass CSI im ESP-IDF-Framework zugänglich gemacht wurde und ESPectre als [Community-Projekt](https://github.com/espressif/esp-csi#6-related-resources) in ihrem [esp-csi](https://github.com/espressif/esp-csi)-Repository anerkannt ist.
---
## Lizenz
Dieses Projekt wird unter der **GNU General Public License v3.0 (GPLv3)** veröffentlicht.
GPLv3 stellt sicher, dass:
- Die Software frei und Open Source bleibt
- Jeder sie verwenden, untersuchen, modifizieren und weiterverbreiten kann
- Änderungen unter derselben Lizenz weitergegeben werden müssen
- Die Rechte der Endnutzer und die Freiheit der Software geschützt werden
Vollständigen Lizenztext finden Sie unter [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE).
Beiträge werden unter GPLv3 eingereicht und müssen einen DCO
`Signed-off-by`-Trailer auf jedem Commit enthalten (`git commit -s`).
## Autor
**Francesco Pace**
E-Mail: [[email protected]](mailto:[email protected])
LinkedIn: [linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
Wenn Sie ESPectre nützlich finden und seine Entwicklung unterstützen möchten, können Sie mir einen Kaffee kaufen. Das ist völlig optional.
Ich arbeite an diesem Projekt, weil ich leidenschaftlich daran interessiert bin. Beiträge helfen mir, neue Hardware zu kaufen, um die Liste der getesteten und unterstützten Geräte zu erweitern und mehr Zeit für neue Funktionen aufzuwenden.
<a href="https://www.buymeacoffee.com/espectre" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/9574/a7e8174c892355a24fbaec083cbef385d097a0b488fd4823dbbb0061643bb5e2.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
| Entfernung | Signal | Mehrwege | Empfindlichkeit | Rauschen | Empfehlung |
|---|
| < 2m | Zu stark | Minimal | Niedrig | Niedrig | ❌ Zu nah |
| 3-8m | Stark | Gut | Hoch | Niedrig | ✅ Optimal |
| > 10-15m | Schwach | Variabel | Niedrig | Hoch | ❌ Zu weit |
F: Wie hoch ist der Stromverbrauch?
A: Typisch ~500 mW im Dauerbetrieb. Die Firmware unterstützt Leistungsoptimierung, und Deep-Sleep-Modi können für batteriebetriebene Einsätze implementiert werden, was jedoch individuelle Änderungen am Code erfordern würde.
F: Wenn es nicht funktioniert, kann ich Hilfe bekommen?
A: Ja, eröffnen Sie ein Issue auf GitHub oder kontaktieren Sie mich per E-Mail.