espectre snapshot-dev
ESPectre - Sistema di rilevamento del movimento basato sull'analisi dello spettro Wi-Fi (CSI), con integrazione con Home Assistant.
ESPectre 
Trasforma un ESP32 in un sensore di movimento Wi-Fi privato e locale.
Quando qualcuno si muove in una stanza, cambia il modo in cui i segnali Wi-Fi la attraversano. ESPectre legge questi cambiamenti e segnala il movimento in tempo reale. Nessuna fotocamera, nessun microfono, nessun dispositivo indossabile e nessun hardware radar dedicato: basta un ESP32 supportato e la rete Wi-Fi già presente nella stanza.
ESPectre è una piattaforma open-source che riunisce firmware pronto da flasherare, un SDK C++ incorporabile, un'implementazione MicroPython, strumenti per browser, una CLI host, un dataset aperto, pesi di modelli aperti e il flusso di lavoro di ricerca utilizzato per costruire e validare i rilevatori.
Flash dal tuo browser · Vedi gli strumenti live · Leggi la documentazione · Esplora l'SDK
Applicazioni e integrazioni
ESPectre può accendere un display o le luci quando rileva movimento, regolare riscaldamento e raffreddamento in base all'attività nella stanza, attivare un allarme o una notifica quando si verifica un movimento in un'area che dovrebbe essere vuota e gestire altre automazioni domestiche. Si collega a Home Assistant tramite ESPHome o MQTT, espone un sensore di occupazione Matter standard e un'API HTTP diretta locale, e può essere incorporato in firmware ESP32 personalizzati tramite l'SDK C++.
ESPectre elabora il CSI sul dispositivo e riporta uno stato di movimento e un punteggio di attività. Le applicazioni possono reagire senza inviare dati di rilevamento grezzi a un servizio cloud. Una scheda copre un'area di rilevamento; la copertura a livello di stanza richiede normalmente una scheda per stanza.
ESPectre rileva i cambiamenti nell'ambiente radio. Non identifica le persone, non le conta, non dimostra che una stanza è vuota e non sostituisce un sistema di sicurezza, medico o di emergenza certificato.
Hardware supportato
- ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 e ESP32 classico
- una normale rete Wi-Fi 4 (802.11n) su 2.4 GHz
Scegli un percorso firmware
| Percorso | Ideale per | Inizia qui |
|---|---|---|
| Native | Sensori autonomi, integrazioni MQTT, inclusa Home Assistant MQTT Discovery, e applicazioni personalizzate | Frontend Native |
| ESPHome | Utenti Home Assistant che vogliono entità native, provisioning ESPHome e aggiornamenti Device Builder | Frontend ESPHome |
| Matter | Controller Matter con supporto sensore di occupazione; la validazione dei controller è ancora limitata | Frontend Matter |
| Micro-ESPectre | Rilevamento leggero in MicroPython con monitoraggio HTTP Direct locale di sola lettura | README Micro-ESPectre |
Native, ESPHome e Matter possono scegliere tra un rilevatore lightweight, che apprende una soglia specifica per la stanza all'avvio e lascia più risorse al resto dell'applicazione, e un rilevatore high_accuracy, che esegue il modello addestrato incluso nel repository. Il loro comportamento e i compromessi misurati sono documentati in SETUP.md, ALGORITHMS.md e nel report sulle prestazioni.
Avvio rapido
Il percorso più rapido utilizza il browser e non richiede un ambiente di build locale. Usa Chrome 151 o successivo su desktop per il flusso di lavoro host completo. Edge supporta il flashing dal browser, ma la compatibilità con Device settings e Monitor non è garantita:
- Apri Flash in Chrome o Edge su desktop.
- Collega un ESP32 supportato via USB, poi scegli un firmware e un canale di rilascio.
- Completa il provisioning Wi-Fi a schermo oppure commissiona Matter con un controller supportato.
- Facoltativamente, apri Device settings per fissare un punto di accesso preferito o configurare MQTT.
- Apri Monitor per osservare il movimento, regolare il rilevamento e ispezionare il dispositivo.
Stato Matter: Il frontend Matter è ancora in fase di validazione tra gli ecosistemi di controller. Un controller può supportare i sensori di occupazione Matter standard senza essere stato testato con il firmware attuale. Vedi Compatibilità controller Matter per la matrice attuale.
Configurazione locale
Per build locali, flashing da questo repository e il resto del percorso operatore, inizia con SETUP.md. Il wrapper del repository espone i flussi di lavoro disponibili tramite:
./espectre --help
Documentazione
| Argomento | Cosa copre | Guide |
|---|---|---|
| Installazione e utilizzo | Configurazione del dispositivo, flussi di lavoro CLI e regolazione del rilevatore | SETUP.md, CLI.md, TUNING.md |
| Comprensione e integrazione | Architettura runtime, API, discovery, algoritmi e SDK C++ | ARCHITECTURE.md, API.md, DISCOVERY.md, ALGORITHMS.md, SDK.md |
| Raccolta e addestramento | Raccolta CSI, addestramento dei modelli, cronologia delle feature, prestazioni e letteratura | ML_DATA_COLLECTION.md, ML_TRAINING.md, FEATURES.md, report sulle prestazioni, LITERATURE.md |
| Ricerca e direzione | Roadmap, decisioni architetturali e cronologia delle release | ROADMAP.md, indice ADR, CHANGELOG.md |
| Riferimento frontend | README dei percorsi firmware per ESPHome, Native, Matter e Micro-ESPectre | ESPHome, Native, Matter, Micro |
| Contribuire | Come contribuire e dove discutere il progetto | CONTRIBUTING.md, GitHub Discussions |
Dataset, modelli e validazione
ESPectre pubblica le risorse di ricerca e le evidenze di validazione alla base dei suoi rilevatori:
| Risorsa | Cosa ti offre | Inizia qui |
|---|---|---|
| Dataset CSI | Registrazioni reali per stanze vuote, presenza statica e movimento, con catalogo e provenienza in dataset_info.json | data/ |
| Pesi dei modelli | Pesi addestrati in C++ e Python, oltre al flusso di lavoro di addestramento, esportazione e validazione | ML_TRAINING.md |
| Registro delle feature | Feature testate, promosse o rifiutate, inclusi gli esperimenti non riusciti | FEATURES.md |
| Algoritmi e report | Comportamento del rilevatore, report sulle prestazioni generato e report sulla qualità del dataset | ALGORITHMS.md |
| Letteratura e direzione | Ricerca esterna, record di decisioni architetturali e roadmap pubblica | LITERATURE.md |
Sicurezza, privacy e trasparenza
Un sensore che può rivelare la presenza non dovrebbe essere una scatola nera. Il rilevamento Wi-Fi evita immagini e audio, ma i dati di movimento e occupazione possono comunque rivelare routine, sonno o assenza da casa. ESPectre tratta questo rischio come parte del lavoro di ingegneria:
- il rilevamento del movimento è locale e la connettività cloud non è richiesta;
- la raccolta CSI grezza è facoltativa e destinata a esigenze definite di ricerca e debug;
- la guida su sicurezza e uso responsabile documenta i confini di distribuzione, il consenso, la minimizzazione dei dati, la segnalazione di abusi e la segnalazione privata di vulnerabilità;
- le release del firmware includono SBOM specifici per build, avvisi e archivi di licenze così che i loro contenuti possano essere ispezionati;
- il sito web pubblico e ogni strumento per browser fanno parte di questo repository sotto docs/web, inclusi il loro codice sorgente, le regole sulla privacy, il contratto di analisi e le dipendenze del browser fissate;
- protocolli, algoritmi, evidenze sulle prestazioni, limitazioni, decisioni sulla roadmap e confini di validazione noti sono documentati pubblicamente.
Usa ESPectre solo in spazi e reti in cui hai il diritto di distribuirlo. Informa le persone interessate, ottieni il consenso dove richiesto, proteggi l'accesso al dispositivo e ai suoi dati e rispetta le leggi sulla privacy applicabili.
Ringraziamenti
- Grazie a Espressif per aver reso accessibile il CSI in ESP-IDF e per aver riconosciuto ESPectre come progetto della community in esp-csi.
- Grazie ai manutentori di MicroPython per aver revisionato, testato e integrato il contributo CSI di ESPectre, che ha aggiunto metodi CSI diretti a
network.WLANnel ramo principale.
Licenza
Il codice di prima parte di ESPectre è disponibile sotto GPLv3, e le parti idonee sono disponibili anche sotto un accordo commerciale separato:
- Scegli GPLv3 quando il tuo firmware o la tua applicazione può conformarsi alla GPLv3, inclusa la messa a disposizione del codice sorgente corrispondente. Vedi LICENSE.
- Se vuoi incorporare ESPectre in firmware proprietario o closed-source senza gli obblighi di divulgazione del codice sorgente della GPLv3, vedi LICENSING.md per la licenza commerciale. La licenza commerciale copre il materiale idoneo e non sostituisce i termini di terze parti; il frontend C++ ESPHome rimane solo GPLv3.
I termini di terze parti e gli artefatti di conformità specifici per build sono descritti in THIRD_PARTY_NOTICES.md.