francescopace/espectreESPectre - Système de détection de mouvement basé sur l'analyse du spectre Wi-Fi (CSI), avec intégration Home Assistant.
Système de détection de mouvement basé sur l'analyse du spectre Wi-Fi (CSI), avec intégration native à Home Assistant via ESPHome.
[!TIP] Nouveau détecteur ML : détection de mouvement par réseau de neurones. Aucun calibrage nécessaire, s'exécute sur l'appareil. Il s'agit d'une fonctionnalité expérimentale, et les retours sont bienvenus dans la discussion dédiée au détecteur ML. Une version snapshot avec les derniers changements est également disponible (utilisez les artefacts
-mlpour le détecteur basé sur l'apprentissage automatique), ou suivez le guide de configuration pour une configuration personnalisée.
DevKit ESP32-S3 avec antennes externes
Temps d'installation : ~10-15 minutes
Difficulté : Facile (configuration YAML uniquement)
Tableau de bord Home Assistant avec détection de mouvement en temps réel, contrôle du seuil et capteurs de débogage
Lorsqu'une personne bouge dans une pièce, elle « perturbe » les ondes Wi-Fi qui circulent entre le routeur et le capteur. C'est comme lorsque vous passez la main devant une lampe de poche et que vous voyez l'ombre changer.
L'appareil ESP32 « écoute » ces changements et détecte s'il y a un mouvement.
Vous voulez comprendre les détails techniques ? Consultez ALGORITHMS.md pour une explication du CSI et la documentation sur le traitement du signal.
Un emplacement optimal du capteur est crucial pour une détection de mouvement fiable.
Plage optimale : 3-8 mètres
À faire :
À éviter :
ESPectre utilise un pipeline de traitement ciblé pour la détection de mouvement :``` ┌─────────────┐ │ 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 └─────────────┘
### Capteur unique ou multiple```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
Chaque capteur est automatiquement découvert par Home Assistant avec :
ESPectre implémente NBVI (Normalized Band Variance Index) pour la sélection automatique des sous-porteuses, atteignant des performances quasi optimales (F1>96 %) avec zéro configuration manuelle. L'algorithme sélectionne 12 sous-porteuses non consécutives en fonction de métriques de stabilité et de diversité spectrale.
⚠️ IMPORTANT (mode MVS) : Gardez la pièce calme et immobile pendant 10 secondes après le démarrage de l'appareil. L'étalonnage automatique s'exécute pendant cette période et tout mouvement affectera la précision de détection. Le mode ML ignore l'étalonnage.
Pour plus de détails sur l'algorithme, voir ALGORITHMS.md.
Q : Avez-vous besoin de connaissances en programmation pour l'utiliser ?
R : Non ! ESPectre utilise des fichiers de configuration YAML. Téléchargez simplement l'exemple, flashez-le et configurez le WiFi via l'application ESPHome ou l'interface web.
Q : Fonctionne-t-il avec mon routeur ?
R : Oui, si votre routeur dispose du Wi-Fi 2,4 GHz (quasi tous les routeurs modernes en sont équipés).
Q : Combien cela coûte-t-il au total ?
R : Matériel : ~€10 pour un appareil ESP32 (S3/C6 recommandés, d'autres variantes fonctionnent aussi). Logiciel : tout est gratuit et open source. Vous aurez également besoin de Home Assistant quelque part (Raspberry Pi ~€35-50, ou n'importe quel PC/NAS existant).
Q : Dois-je modifier quelque chose sur le routeur ?
R : Non ! Le routeur fonctionne normalement. Le capteur « écoute » les signaux Wi-Fi sans rien modifier.
Q : Fonctionne-t-il à travers les murs ?
R : Oui, le signal Wi-Fi 2,4 GHz traverse les cloisons sèches. Le béton armé réduit la sensibilité, mais la détection reste possible à des distances réduites.
Q : Combien de capteurs sont nécessaires pour une maison ?
R : Cela dépend de la taille. Un capteur peut surveiller ~50 m². Pour les grandes maisons, utilisez plusieurs capteurs (1 capteur tous les 50-70 m² pour une couverture optimale).
Q : Peut-il faire la distinction entre les personnes et les animaux domestiques ?
R : Le système utilise un modèle de segmentation à 2 états (IDLE/MOTION) qui identifie un mouvement générique sans distinguer les personnes, les animaux ou d'autres objets en mouvement. Pour une classification plus sophistiquée (personnes vs animaux, reconnaissance d'activité, détection de gestes), des modèles d'IA/ML entraînés seraient nécessaires (voir section Évolution future).
Q : Fonctionne-t-il avec les réseaux Wi-Fi maillés ?
R : Oui, il fonctionne normalement. Assurez-vous que l'ESP32 se connecte à la bande 2,4 GHz.
Q : Quelle est la précision de la détection ?
R : La précision de la détection dépend fortement de l'environnement et nécessite un réglage approprié. Les facteurs affectant les performances incluent : l'agencement de la pièce, les matériaux des murs, le placement des meubles, la distance par rapport au routeur (optimal : 3-8 m) et les niveaux d'interférence. Dans des conditions optimales avec un réglage approprié, le système fournit une détection de mouvement fiable. Ajustez le paramètre segmentation_threshold pour régler la sensibilité à votre environnement spécifique.
Le système collecte des données anonymes liées aux caractéristiques physiques du canal radio Wi-Fi :
Les données CSI ne représentent que les propriétés du support de transmission et ne contiennent pas d'informations d'identification directes.
ATTENTION : Malgré l'anonymat intrinsèque des données CSI, ce système peut être utilisé pour :
L'utilisateur est seul responsable de l'utilisation de ce système et doit :
Pour les détails des algorithmes (MVS, étalonnage NBVI, filtre de Hampel), voir ALGORITHMS.md.
Pour les métriques de performance (matrice de confusion, score F1, benchmarks), voir PERFORMANCE.md.
Ce projet suit une approche à deux plateformes pour équilibrer la vitesse d'innovation et la stabilité de production :
Cible : utilisateurs finaux, passionnés de maison intelligente, utilisateurs de Home Assistant
Cible : chercheurs, développeurs, applications académiques/industrielles
Micro-ESPectre vous fournit les bases pour :
┌─────────────────────┐ 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 │ └─────────────────────┘ └──────────────────────┘
**Cycle d'innovation** : les nouvelles fonctionnalités et algorithmes sont d'abord développés et validés dans Micro-ESPectre (Python), puis portés vers ESPectre (C++) une fois leur efficacité prouvée.
---
## Évolution future
Alors qu'ESPectre v2.x se concentre sur la **détection de mouvement** (MVS + sélection automatique de sous-porteuse), le projet explore des capacités d'apprentissage automatique pour des applications avancées :
| Capacité | Statut | Description |
|------------|--------|-------------|
| **Détecteur ML** | Expérimental | Réseau de neurones (MLP 9→32→16→1)|
| **Reconnaissance de gestes** | Planifié | Détecter les gestes de la main (balayage, poussée, cercle) pour le contrôle de la maison intelligente |
| **Reconnaissance d'activités humaines** | Planifié | Identifier les activités (assis, marche, chute) |
| **Comptage de personnes** | Planifié | Estimer le nombre de personnes dans une pièce |
| **Localisation 3D** | Recherche | Positionnement intérieur (précision 30-50cm) via un réseau d'antennes cohérent en phase |
Le détecteur ML est déjà disponible avec `detection_algorithm: ml` dans votre configuration YAML. Pour plus de détails sur l'algorithme, consultez [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector) et `PERFORMANCE.md` pour les métriques actuelles
L'infrastructure de collecte de données et d'entraînement ML est documentée dans [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md).
Consultez [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) pour les plans détaillés, les échéanciers et la manière de contribuer.
---
## Documentation
### ESPectre (Production)
| Document | Description |
|----------|-------------|
| [Intro](https://github.com/francescopace/espectre/blob/HEAD/README.md) | (Ce fichier) Vue d'ensemble du projet, démarrage rapide, FAQ |
| [Guide d'installation](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | Installation et configuration avec ESPHome |
| [Guide de réglage](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | Réglage des paramètres pour une détection optimale |
| [Performances](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | Benchmarks, matrice de confusion, score F1 |
| [Le Jeu](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | Jeu navigateur, API de streaming USB, réglage interactif du seuil |
| [Suite de tests](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | Documentation des tests PlatformIO Unity |
### Micro-ESPectre (R&D)
| Document | Description |
|----------|-------------|
| [Intro](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | Vue d'ensemble de la plateforme R&D, CLI, MQTT, Web Monitor |
| [Algorithmes](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | Documentation scientifique du MVS, de la calibration NBVI, du filtre de Hampel |
| [Outils d'analyse](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | Scripts d'analyse et d'optimisation CSI |
| [Collecte de données ML](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | Construction de jeux de données étiquetés pour l'apprentissage automatique |
| [Références](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | Articles académiques et ressources de recherche |
### Projet
| Document | Description |
|----------|-------------|
| [Feuille de route](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | Vision du projet et plans ML |
| [Contribuer](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | Comment contribuer (code, données, documentation) |
| [Journal des modifications](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | Historique des versions et notes de version |
| [Sécurité](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | Politique de sécurité et signalement des vulnérabilités |
| [Code de conduite](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | Règles de la communauté |
---
## Médias
| Articles | Titre |
|-------------|-------|
| Medium | [Comment j'ai transformé mon Wi-Fi en détecteur de mouvement - Partie 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 | [Comment j'ai transformé mon Wi-Fi en détecteur de mouvement - Partie 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 | [Comment j'ai transformé mon Wi-Fi en détecteur de mouvement](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [Fabriquez votre propre capteur de présence basé sur ESP32, aucun matériel spécial requis](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [Détecteur de présence ESPectre pour Feather](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [Déployer Espectre sur la série Seeed Studio XIAO ESP32 avec ESPHome](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| Blog | Discussion |
|----------|------------|
| Home Assistant | [ESPectre - Détection de mouvement Wi-Fi pour Home Assistant](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| Vidéos | Vidéo |
|---------|-------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| Podcasts | Épisode |
|-------------|---------|
| Hackaday | [Épisode 355 du podcast : Détecteurs de présence, talkies-walkies, smartphones ouverts...](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## Projets connexes
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner) : projet complémentaire de détection de présence axé sur les observations radio BLE à partir d'appareils hôtes (Python), avec tableau de bord HTTP facultatif.
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi) : fork MicroPython personnalisé exposant les API CSI ESP32, utilisé comme base de firmware pour le prototypage rapide du CSI dans le flux de travail Micro-ESPectre.
---
## Remerciements
ESPectre exploite les capacités CSI Wi-Fi natives des puces ESP32. Merci à [Espressif](https://www.espressif.com/) d'avoir rendu le CSI accessible dans le framework ESP-IDF et d'avoir reconnu ESPectre comme [projet communautaire](https://github.com/espressif/esp-csi#6-related-resources) dans leur dépôt [esp-csi](https://github.com/espressif/esp-csi).
---
## Licence
Ce projet est publié sous la **GNU General Public License v3.0 (GPLv3)**.
La GPLv3 garantit que :
- Le logiciel reste libre et open source
- Toute personne peut l'utiliser, l'étudier, le modifier et le distribuer
- Les modifications doivent être partagées sous la même licence
- Protège les droits des utilisateurs finaux et la liberté du logiciel
Voir [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE) pour le texte intégral de la licence.
Les contributions sont soumises sous GPLv3 et doivent inclure un DCO
avec la mention `Signed-off-by` sur chaque commit (`git commit -s`).
## Auteur
**Francesco Pace**
Email : [[email protected]](mailto:[email protected])
LinkedIn : [linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
Si vous trouvez ESPectre utile et souhaitez soutenir son développement, vous pouvez m'offrir un café. C'est totalement facultatif.
Je travaille sur ce projet parce que je suis passionné. Les contributions m'aident à acheter du nouveau matériel pour élargir la liste des appareils testés et pris en charge, et à consacrer plus de temps aux nouvelles fonctionnalités.
<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>
| Distance | Signal | Multipath | Sensibilité | Bruit | Recommandation |
|---|
| < 2m | Trop fort | Minimal | Faible | Faible | ❌ Trop près |
| 3-8m | Fort | Bon | Élevée | Faible | ✅ Optimal |
| > 10-15m | Faible | Variable | Faible | Élevé | ❌ Trop loin |
Q : Quelle est la consommation électrique ?
R : ~500 mW en fonctionnement continu typique. Le firmware inclut un support d'optimisation de la consommation, et des modes de veille profonde peuvent être implémentés pour les déploiements sur batterie, bien que cela nécessite des modifications personnalisées du code.
Q : Si cela ne fonctionne pas, puis-je obtenir de l'aide ?
R : Oui, ouvrez un problème sur GitHub ou contactez-moi par e-mail.