francescopace/espectreESPectre - Sistema di rilevamento del movimento basato sull'analisi dello spettro Wi-Fi (CSI), con integrazione con Home Assistant.
Sistema di rilevamento del movimento basato sull'analisi dello spettro Wi-Fi (CSI), con integrazione nativa con Home Assistant tramite ESPHome.
[!TIP] Nuovo rilevatore ML: rilevamento del movimento basato su rete neurale. Nessuna calibrazione richiesta, eseguito sul dispositivo. Questa è una funzionalità sperimentale e i feedback sono benvenuti nella discussione dedicata al rilevatore ML. È disponibile anche una build snapshot con le ultime modifiche (usa gli asset
-mlper il rilevatore basato su machine learning), oppure segui la guida alla configurazione per una configurazione personalizzata.
ESP32-S3 DevKit con antenne esterne
Tempo di configurazione: ~10-15 minuti
Difficoltà: Facile (solo configurazione YAML)
Dashboard di Home Assistant con rilevamento del movimento in tempo reale, controllo della soglia e sensori di debug
Quando qualcuno si muove in una stanza, "disturba" le onde Wi-Fi che viaggiano tra il router e il sensore. È come quando muovi la mano davanti a una torcia e vedi l'ombra cambiare.
Il dispositivo ESP32 "ascolta" questi cambiamenti e capisce se c'è movimento.
Vuoi capire i dettagli tecnici? Vedi ALGORITHMS.md per la spiegazione del CSI e la documentazione sull'elaborazione del segnale.
Il posizionamento ottimale del sensore è fondamentale per un rilevamento affidabile del movimento.
Intervallo ottimale: 3-8 metri
Da fare:
Da non fare:
ESPectre utilizza una pipeline di elaborazione mirata per il rilevamento del movimento:``` ┌─────────────┐ │ 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 └─────────────┘
### Sensore singolo o multiplo```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
Ogni sensore viene rilevato automaticamente da Home Assistant con:
ESPectre implementa NBVI (Normalized Band Variance Index) per la selezione automatica delle sottoportanti, ottenendo prestazioni quasi ottimali (F1>96%) con zero configurazione manuale. L'algoritmo seleziona 12 sottoportanti non consecutive in base a metriche di stabilità e diversità spettrale.
⚠️ IMPORTANTE (modalità MVS): Mantieni la stanza silenziosa e ferma per 10 secondi dopo l'avvio del dispositivo. L'auto-calibrazione viene eseguita in questo periodo e il movimento influirà sull'accuratezza del rilevamento. La modalità ML salta la calibrazione.
Per i dettagli dell'algoritmo, vedere ALGORITHMS.md.
D: Ho bisogno di conoscenze di programmazione per usarlo?
R: No! ESPectre utilizza file di configurazione YAML. Basta scaricare l'esempio, flasharlo e configurare il WiFi tramite l'app ESPHome o l'interfaccia web.
D: Funziona con il mio router?
R: Sì, se il tuo router ha Wi-Fi a 2.4GHz (praticamente tutti i router moderni ce l'hanno).
D: Quanto costa in totale?
R: Hardware: ~€10 per un dispositivo ESP32 (S3/C6 consigliati, anche altre varianti funzionano). Software: tutto gratuito e open source. Avrai anche bisogno di Home Assistant in esecuzione da qualche parte (Raspberry Pi ~€35-50, o qualsiasi PC/NAS esistente).
D: Devo modificare qualcosa sul router?
R: No! Il router funziona normalmente. Il sensore "ascolta" i segnali Wi-Fi senza modificare nulla.
D: Funziona attraverso i muri?
R: Sì, il segnale Wi-Fi a 2.4GHz penetra il cartongesso. I muri in cemento armato riducono la sensibilità, ma il rilevamento rimane possibile a distanze ridotte.
D: Quanti sensori servono per una casa?
R: Dipende dalle dimensioni. Un sensore può monitorare ~50 m². Per case più grandi, usa più sensori (1 sensore ogni 50-70 m² per una copertura ottimale).
D: Può distinguere tra persone e animali domestici?
R: Il sistema utilizza un modello di segmentazione a 2 stati (IDLE/MOTION) che identifica il movimento generico senza distinguere tra persone, animali domestici o altri oggetti in movimento. Per una classificazione più sofisticata (persone vs animali, riconoscimento delle attività, rilevamento dei gesti), sarebbero necessari modelli AI/ML addestrati (vedi sezione Evoluzione Futura).
D: Funziona con reti Wi-Fi mesh?
R: Sì, funziona normalmente. Assicurati che l'ESP32 si connetta alla banda a 2.4 GHz.
D: Quanto è accurato il rilevamento?
R: L'accuratezza del rilevamento dipende fortemente dall'ambiente e richiede una corretta regolazione. I fattori che influenzano le prestazioni includono: disposizione della stanza, materiali delle pareti, posizione dei mobili, distanza dal router (ottimale: 3-8m) e livelli di interferenza. In condizioni ottimali con una regolazione adeguata, il sistema fornisce un rilevamento affidabile del movimento. Regola il parametro segmentation_threshold per tarare la sensibilità in base al tuo ambiente specifico.
D: Qual è il consumo energetico?
R: ~500mW tipici durante il funzionamento continuo. Il firmware include il supporto per l'ottimizzazione energetica e le modalità di deep sleep possono essere implementate per implementazioni a batteria, anche se ciò richiederebbe modifiche personalizzate al codice.
Il sistema raccoglie dati anonimi relativi alle caratteristiche fisiche del canale radio Wi-Fi:
I dati CSI rappresentano solo le proprietà del mezzo di trasmissione e non contengono informazioni identificative dirette.
AVVERTENZA: Nonostante l'intrinseco anonimato dei dati CSI, questo sistema può essere utilizzato per:
L'utente è l'unico responsabile dell'utilizzo di questo sistema e deve:
Per i dettagli degli algoritmi (MVS, calibrazione NBVI, filtro di Hampel), vedere ALGORITHMS.md.
Per le metriche di prestazione (matrice di confusione, F1-score, benchmark), vedere PERFORMANCE.md.
Questo progetto segue un approccio a doppia piattaforma per bilanciare la velocità di innovazione con la stabilità produttiva:
Destinatari: Utenti finali, appassionati di smart home, utenti Home Assistant
Destinatari: Ricercatori, sviluppatori, applicazioni accademiche/industriali
Micro-ESPectre ti fornisce le basi per:
┌─────────────────────┐ 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 │ └─────────────────────┘ └──────────────────────┘
**Ciclo di innovazione**: le nuove funzionalità e i nuovi algoritmi vengono prima sviluppati e validati in Micro-ESPectre (Python), poi portati in ESPectre (C++) una volta dimostratisi efficaci.
---
## Evoluzione futura
Mentre ESPectre v2.x si concentra sul **rilevamento del movimento** (MVS + selezione automatica della sottoportante), il progetto sta esplorando capacità di machine learning per applicazioni avanzate:
| Capacità | Stato | Descrizione |
|------------|--------|-------------|
| **Rilevatore ML** | Sperimentale | Rete neurale (MLP 9→32→16→1) |
| **Riconoscimento gesti** | Pianificato | Rileva gesti della mano (scorrimento, spinta, cerchio) per il controllo della casa intelligente |
| **Riconoscimento attività umane** | Pianificato | Identifica attività (seduto, camminare, cadere) |
| **Conteggio persone** | Pianificato | Stima il numero di persone in una stanza |
| **Localizzazione 3D** | Ricerca | Posizionamento indoor (precisione 30-50 cm) tramite array di antenne coerenti in fase |
Il rilevatore ML è già disponibile con `detection_algorithm: ml` nella tua configurazione YAML. Per i dettagli sull'algoritmo, vedi [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector) e `PERFORMANCE.md` per le metriche attuali.
L'infrastruttura di raccolta dati e addestramento ML è documentata in [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md).
Vedi [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) per piani dettagliati, tempistiche e come contribuire.
---
## Documentazione
### ESPectre (Produzione)
| Documento | Descrizione |
|----------|-------------|
| [Intro](https://github.com/francescopace/espectre/blob/HEAD/README.md) | (Questo file) Panoramica del progetto, avvio rapido, FAQ |
| [Guida all'installazione](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | Installazione e configurazione con ESPHome |
| [Guida alla regolazione](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | Regolazione dei parametri per un rilevamento ottimale |
| [Prestazioni](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | Benchmark, matrice di confusione, punteggio F1 |
| [Il Gioco](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | Gioco browser, API di streaming USB, regolazione interattiva della soglia |
| [Suite di test](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | Documentazione dei test PlatformIO Unity |
### Micro-ESPectre (R&S)
| Documento | Descrizione |
|----------|-------------|
| [Intro](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | Panoramica della piattaforma R&S, CLI, MQTT, Web Monitor |
| [Algoritmi](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | Documentazione scientifica di MVS, calibrazione NBVI, filtro di Hampel |
| [Strumenti di analisi](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | Script di analisi e ottimizzazione CSI |
| [Raccolta dati ML](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | Creazione di dataset etichettati per il machine learning |
| [Riferimenti](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | Articoli accademici e risorse di ricerca |
### Progetto
| Documento | Descrizione |
|----------|-------------|
| [Roadmap](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | Visione del progetto e piani ML |
| [Contribuire](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | Come contribuire (codice, dati, documentazione) |
| [Changelog](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | Cronologia versioni e note di rilascio |
| [Sicurezza](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | Policy di sicurezza e segnalazione di vulnerabilità |
| [Codice di condotta](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | Linee guida della community |
---
## Media
| Articoli | Titolo |
|-------------|-------|
| Medium | [Come ho trasformato il mio Wi-Fi in un sensore di movimento - Parte 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 | [Come ho trasformato il mio Wi-Fi in un sensore di movimento - Parte 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 | [Come ho trasformato il mio Wi-Fi in un sensore di movimento](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [Crea il tuo sensore di presenza basato su ESP32, senza hardware speciale](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [Rilevatore di presenza umana ESPectre per Feather](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [Distribuire Espectre su Seeed Studio XIAO ESP32 Series con ESPHome](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| Blog | Discussione |
|----------|------------|
| Home Assistant | [ESPectre - Rilevamento del movimento Wi-Fi per Home Assistant](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| Video | Video |
|---------|-------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| Podcast | Episodio |
|-------------|---------|
| Hackaday | [Episodio del podcast 355: Rilevatori di persone, walkie-talkie, smartphone open source...](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## Progetti correlati
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner): progetto complementare per il rilevamento di presenza focalizzato sulle osservazioni radio BLE dai dispositivi host (Python), con dashboard HTTP opzionale.
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi): fork MicroPython personalizzato che espone le API CSI di ESP32, usato come base firmware per il prototipaggio rapido di CSI nel flusso di lavoro Micro-ESPectre.
---
## Riconoscimenti
ESPectre sfrutta le capacità CSI Wi-Fi native dei chip ESP32. Grazie a [Espressif](https://www.espressif.com/) per aver reso accessibile la CSI nel framework ESP-IDF e per aver riconosciuto ESPectre come [progetto della community](https://github.com/espressif/esp-csi#6-related-resources) nel loro repository [esp-csi](https://github.com/espressif/esp-csi).
---
## Licenza
Questo progetto è rilasciato sotto la **GNU General Public License v3.0 (GPLv3)**.
GPLv3 garantisce che:
- Il software rimane libero e open source
- Chiunque può usarlo, studiarlo, modificarlo e distribuirlo
- Le modifiche devono essere condivise sotto la stessa licenza
- Protegge i diritti degli utenti finali e la libertà del software
Vedi [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE) per il testo completo della licenza.
I contributi sono inviati sotto GPLv3 e devono includere un trailer DCO
`Signed-off-by` su ogni commit (`git commit -s`).
## Autore
**Francesco Pace**
Email: [[email protected]](mailto:[email protected])
LinkedIn: [linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
Se trovi ESPectre utile e vuoi sostenere il suo sviluppo, puoi offrirmi un caffè. È del tutto facoltativo.
Lavoro a questo progetto perché ne sono appassionato. I contributi mi aiutano ad acquistare nuovo hardware per ampliare l'elenco dei dispositivi testati e supportati, e a dedicare più tempo alle nuove funzionalità.
<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>
| Distanza | Segnale | Percorsi multipli | Sensibilità | Rumore | Raccomandazione |
|---|
| < 2m | Troppo forte | Minimo | Bassa | Basso | ❌ Troppo vicino |
| 3-8m | Forte | Buono | Alta | Basso | ✅ Ottimale |
| > 10-15m | Debole | Variabile | Bassa | Alto | ❌ Troppo lontano |
D: Se non funziona, posso ricevere aiuto?
R: Sì, apri un Issue su GitHub o contattami via email.