espectre snapshot-dev
ESPectre - Système de détection de mouvement basé sur l'analyse du spectre Wi-Fi (CSI), avec intégration Home Assistant.
ESPectre 
Transformez un ESP32 en capteur de mouvement Wi-Fi privé et local.
Lorsqu'une personne se déplace dans une pièce, elle modifie la façon dont les signaux Wi-Fi la traversent. ESPectre lit ces changements et signale le mouvement en temps réel. Pas de caméra, pas de microphone, pas d'appareil portable et pas de matériel radar dédié : juste un ESP32 pris en charge et le réseau Wi-Fi déjà présent dans la pièce.
ESPectre est une plateforme open source qui réunit un firmware prêt à flasher, un SDK C++ embarquable, une implémentation MicroPython, des outils navigateur, un CLI hôte, un jeu de données ouvert, des poids de modèles ouverts et le flux de travail de recherche utilisé pour construire et valider les détecteurs.
Flasher depuis votre navigateur · Voir les outils en direct · Lire la documentation · Explorer le SDK
Applications et intégrations
ESPectre peut allumer un écran ou des lumières lorsqu'il détecte un mouvement, ajuster le chauffage et la climatisation en fonction de l'activité de la pièce, déclencher une alarme ou une notification lorsqu'un mouvement se produit dans une zone qui devrait être vide, et piloter d'autres automatisations de la pièce. Il se connecte à Home Assistant via ESPHome ou MQTT, expose un capteur d'occupation Matter standard et une API HTTP Direct locale, et peut être intégré dans un firmware ESP32 personnalisé via le SDK C++.
ESPectre traite le CSI sur l'appareil et signale un état de mouvement et un score de déplacement. Les applications peuvent réagir sans envoyer de données de détection brutes à un service cloud. Une carte couvre une zone de détection ; une couverture au niveau de la pièce nécessite normalement une carte par pièce.
ESPectre détecte les changements dans l'environnement radio. Il n'identifie pas les personnes, ne les compte pas, ne prouve pas qu'une pièce est vide et ne remplace pas un système de sécurité, médical ou d'urgence certifié.
Matériel pris en charge
- ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 et ESP32 classique
- un réseau Wi-Fi 4 (802.11n) normal sur 2,4 GHz
Choisissez un chemin de firmware
| Chemin | Idéal pour | Commencez ici |
|---|---|---|
| Natif | Capteurs autonomes, intégrations MQTT, y compris Home Assistant MQTT Discovery, et applications personnalisées | Frontend natif |
| ESPHome | Utilisateurs de Home Assistant qui souhaitent des entités natives, le provisionnement ESPHome et les mises à jour Device Builder | Frontend ESPHome |
| Matter | Contrôleurs Matter avec prise en charge du capteur d'occupation ; la validation des contrôleurs reste limitée | Frontend Matter |
| Micro-ESPectre | Détection légère en MicroPython avec surveillance HTTP Direct locale en lecture seule | README Micro-ESPectre |
Les chemins Natif, ESPHome et Matter peuvent choisir entre un détecteur lightweight, qui apprend un seuil spécifique à la pièce au démarrage et laisse plus de ressources au reste de l'application, et un détecteur high_accuracy, qui exécute le modèle entraîné inclus dans le dépôt. Leur comportement et leurs compromis mesurés sont documentés dans SETUP.md, ALGORITHMS.md et le rapport de performance.
Démarrage rapide
Le chemin le plus rapide utilise le navigateur et ne nécessite aucun environnement de compilation local. Utilisez Chrome 151 ou ultérieur sur ordinateur pour le flux hébergé complet. Edge prend en charge le flashage par navigateur, mais la compatibilité avec les paramètres de l'appareil et Monitor n'est pas garantie :
- Ouvrez Flash dans Chrome ou Edge sur ordinateur.
- Connectez un ESP32 pris en charge via USB, puis choisissez un firmware et un canal de version.
- Terminez le provisionnement Wi-Fi à l'écran, ou commissionnez Matter avec un contrôleur pris en charge.
- En option, ouvrez Paramètres de l'appareil pour épingler un point d'accès préféré ou configurer MQTT.
- Ouvrez Monitor pour observer le mouvement, régler la détection et inspecter l'appareil.
Statut Matter : Le frontend Matter est encore en cours de validation sur les écosystèmes de contrôleurs. Un contrôleur peut prendre en charge les capteurs d'occupation Matter standard sans avoir été testé avec le firmware actuel. Voir Compatibilité des contrôleurs Matter pour la matrice actuelle.
Configuration locale
Pour les compilations locales, le flashage depuis ce dépôt et le reste du parcours opérateur, commencez par SETUP.md. Le wrapper du dépôt expose les flux de travail disponibles via :
./espectre --help
Documentation
| Sujet | Ce qu'il couvre | Guides |
|---|---|---|
| Installer et exploiter | Configuration de l'appareil, flux de travail CLI et réglage du détecteur | SETUP.md, CLI.md, TUNING.md |
| Comprendre et intégrer | Architecture d'exécution, API, découverte, algorithmes et SDK C++ | ARCHITECTURE.md, API.md, DISCOVERY.md, ALGORITHMS.md, SDK.md |
| Collecter et entraîner | Collecte CSI, entraînement de modèles, historique des caractéristiques, performance et littérature | ML_DATA_COLLECTION.md, ML_TRAINING.md, FEATURES.md, rapport de performance, LITERATURE.md |
| Recherche et orientation | Feuille de route, décisions d'architecture et historique des versions | ROADMAP.md, index ADR, CHANGELOG.md |
| Référence des frontends | README des chemins de firmware pour ESPHome, Natif, Matter et Micro-ESPectre | ESPHome, Natif, Matter, Micro |
| Contribuer | Comment contribuer et où discuter du projet | CONTRIBUTING.md, Discussions GitHub |
Jeux de données, modèles et validation
ESPectre publie les ressources de recherche et les preuves de validation derrière ses détecteurs :
| Ressource | Ce qu'elle vous apporte | Commencez ici |
|---|---|---|
| Jeu de données CSI | Enregistrements réels pour pièces vides, présence statique et mouvement, avec catalogue et provenance dans dataset_info.json | data/ |
| Poids des modèles | Poids entraînés en C++ et Python, plus le flux de travail d'entraînement, d'export et de validation | ML_TRAINING.md |
| Registre des caractéristiques | Caractéristiques testées, promues ou rejetées, y compris les expériences infructueuses | FEATURES.md |
| Algorithmes et rapports | Comportement du détecteur, rapport de performance généré et rapport de qualité du jeu de données | ALGORITHMS.md |
| Littérature et orientation | Recherche externe, registres de décisions d'architecture et feuille de route publique | LITERATURE.md |
Sécurité, confidentialité et transparence
Un capteur capable de révéler une présence ne devrait pas être une boîte noire. La détection Wi-Fi évite les images et l'audio, mais les données de mouvement et d'occupation peuvent encore révéler des routines, le sommeil ou l'absence du domicile. ESPectre traite ce risque comme faisant partie du travail d'ingénierie :
- la détection de mouvement est locale et la connectivité cloud n'est pas requise ;
- la collecte de CSI brut est facultative et destinée à des besoins de recherche et de débogage définis ;
- le guide de sécurité et d'utilisation responsable documente les limites de déploiement, le consentement, la minimisation des données, le signalement des abus et le signalement privé des vulnérabilités ;
- les versions de firmware incluent des SBOM spécifiques à la compilation, des avis et des archives de licences afin que leur contenu puisse être inspecté ;
- le site web public et chaque outil navigateur font partie de ce dépôt sous docs/web, y compris leur source, leurs règles de confidentialité, leur contrat d'analyse et leurs dépendances navigateur épinglées ;
- les protocoles, algorithmes, preuves de performance, limites, décisions de feuille de route et limites de validation connues sont documentés publiquement.
Utilisez ESPectre uniquement dans des espaces et des réseaux où vous avez le droit de le déployer. Informez les personnes concernées, obtenez le consentement lorsque cela est requis, protégez l'accès à l'appareil et à ses données, et respectez les lois applicables sur la confidentialité.
Remerciements
- Merci à Espressif d'avoir rendu le CSI accessible dans ESP-IDF et d'avoir reconnu ESPectre comme un projet communautaire dans esp-csi.
- Merci aux mainteneurs de MicroPython d'avoir examiné, testé et fusionné la contribution CSI d'ESPectre, qui a ajouté des méthodes CSI directes à
network.WLANde la branche principale.
Licence
Le code propriétaire d'ESPectre est disponible sous GPLv3, et les parties éligibles sont également disponibles sous un accord commercial distinct :
- Choisissez GPLv3 lorsque votre firmware ou application peut se conformer à la GPLv3, y compris la mise à disposition du code source correspondant. Voir LICENSE.
- Si vous souhaitez intégrer ESPectre dans un firmware propriétaire ou à code source fermé sans les obligations de divulgation du code source de la GPLv3, voir LICENSING.md pour la licence commerciale. La licence commerciale couvre le matériel éligible et ne remplace pas les conditions des tiers ; le frontend C++ ESPHome reste exclusivement sous GPLv3.
Les conditions des tiers et les artefacts de conformité spécifiques à la compilation sont décrits dans THIRD_PARTY_NOTICES.md.