francescopace/espectreESPectre - Sistema de detecção de movimento baseado na análise do espectro Wi-Fi (CSI), com integração com o Home Assistant.
Sistema de detecção de movimento baseado em análise de espectro Wi-Fi (CSI), com integração nativa ao Home Assistant via ESPHome.
[!TIP] Novo Detector ML: Detecção de movimento baseada em rede neural. Sem calibração necessária, executa no dispositivo. Este é um recurso experimental, e feedback é bem-vindo na discussão do detector ML dedicada. Um build snapshot com as últimas alterações também está disponível (use assets
-mlpara o detector baseado em aprendizado de máquina), ou siga o Guia de configuração para configuração personalizada.
ESP32-S3 DevKit com antenas externas
Tempo de configuração: ~10-15 minutos
Dificuldade: Fácil (apenas configuração YAML)
Painel do Home Assistant com detecção de movimento em tempo real, controle de limiar e sensores de depuração
Quando alguém se move em um cômodo, "perturba" as ondas Wi-Fi que viajam entre o roteador e o sensor. É como quando você move sua mão na frente de uma lanterna e vê a sombra mudar.
O dispositivo ESP32 "escuta" essas mudanças e entende se há movimento.
Quer entender os detalhes técnicos? Veja ALGORITHMS.md para explicação sobre CSI e documentação de processamento de sinais.
O posicionamento ideal do sensor é crucial para uma detecção de movimento confiável.
Faixa ideal: 3-8 metros
Faça:
Não faça:
O ESPectre usa um pipeline de processamento focado para detecção de 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 └─────────────┘
### Sensor Único ou Múltiplos Sensores```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
Cada sensor é descoberto automaticamente pelo Home Assistant com:
O ESPectre implementa o NBVI (Normalized Band Variance Index) para seleção automática de subportadoras, alcançando desempenho quase ótimo (F1>96%) com zero configuração manual. O algoritmo seleciona 12 subportadoras não consecutivas com base em métricas de estabilidade e diversidade espetral.
⚠️ IMPORTANTE (modo MVS): Mantenha a sala quieta e imóvel por 10 segundos após a inicialização do dispositivo. A calibração automática é executada durante este período e o movimento afetará a precisão da deteção. O modo ML ignora a calibração.
Para detalhes do algoritmo, veja ALGORITHMS.md.
P: Preciso de conhecimentos de programação para usar?
R: Não! O ESPectre usa ficheiros de configuração YAML. Basta descarregar o exemplo, gravá-lo e configurar o WiFi através da aplicação ESPHome ou interface web.
P: Funciona com o meu router?
R: Sim, se o seu router tiver Wi-Fi 2.4GHz (praticamente todos os routers modernos têm).
P: Quanto custa no total?
R: Hardware: ~€10 por um dispositivo ESP32 (S3/C6 recomendado, outras variantes também funcionam). Software: Totalmente gratuito e de código aberto. Também precisará do Home Assistant a funcionar nalgum local (Raspberry Pi ~€35-50, ou qualquer PC/NAS existente).
P: Preciso de modificar algo no router?
R: Não! O router funciona normalmente. O sensor "escuta" os sinais Wi-Fi sem modificar nada.
P: Funciona através de paredes?
R: Sim, o sinal Wi-Fi 2.4GHz penetra em paredes de gesso cartonado. Paredes de betão armado reduzem a sensibilidade, mas a deteção continua possível a distâncias reduzidas.
P: Quantos sensores são necessários para uma casa?
R: Depende do tamanho. Um sensor pode monitorizar ~50 m². Para casas maiores, use vários sensores (1 sensor a cada 50-70 m² para cobertura ideal).
P: Consegue distinguir entre pessoas e animais de estimação?
R: O sistema usa um modelo de segmentação de 2 estados (IDLE/MOTION) que identifica movimento genérico sem distinguir entre pessoas, animais de estimação ou outros objetos em movimento. Para classificação mais sofisticada (pessoas vs animais, reconhecimento de atividades, deteção de gestos), seriam necessários modelos de IA/ML treinados (veja a secção Evolução Futura).
P: Funciona com redes Wi-Fi mesh?
R: Sim, funciona normalmente. Certifique-se de que o ESP32 se liga à banda de 2.4 GHz.
P: Qual é a precisão da deteção?
R: A precisão da deteção é altamente dependente do ambiente e requer ajustes adequados. Os fatores que afetam o desempenho incluem: disposição da sala, materiais das paredes, colocação de mobiliário, distância do router (ideal: 3-8m) e níveis de interferência. Em condições ideais com ajuste adequado, o sistema fornece deteção de movimento fiável. Ajuste o parâmetro segmentation_threshold para sintonizar a sensibilidade para o seu ambiente específico.
P: Qual é o consumo de energia?
R: ~500mW típico durante operação contínua. O firmware inclui suporte para otimização de energia, e modos de suspensão profunda podem ser implementados para implantações com bateria, embora isso exija modificações personalizadas no código.
O sistema recolhe dados anónimos relacionados com as características físicas do canal de rádio Wi-Fi:
Os dados CSI representam apenas as propriedades do meio de transmissão e não contêm informações de identificação direta.
AVISO: Apesar da anonimidade intrínseca dos dados CSI, este sistema pode ser usado para:
O utilizador é o único responsável pelo uso deste sistema e deve:
Para detalhes do algoritmo (MVS, calibração NBVI, filtro Hampel), veja ALGORITHMS.md.
Para métricas de desempenho (matriz de confusão, F1-score, benchmarks), veja PERFORMANCE.md.
Este projeto segue uma abordagem de plataforma dupla para equilibrar a velocidade de inovação com a estabilidade de produção:
Alvo: Utilizadores finais, entusiastas de smart home, utilizadores do Home Assistant
Alvo: Investigadores, programadores, aplicações académicas/industriais
O Micro-ESPectre fornece os fundamentos para:
┌─────────────────────┐ 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 de inovação**: Novos recursos e algoritmos são primeiro desenvolvidos e validados no Micro-ESPectre (Python), depois portados para o ESPectre (C++) assim que se mostram eficazes.
---
## Evolução Futura
Enquanto o ESPectre v2.x foca na **detecção de movimento** (MVS + seleção automática de subportadora), o projeto está explorando capacidades de aprendizado de máquina para aplicações avançadas:
| Capacidade | Status | Descrição |
|------------|--------|-------------|
| **Detector ML** | Experimental | Rede neural (MLP 9→32→16→1) |
| **Reconhecimento de Gestos** | Planejado | Detectar gestos manuais (deslizar, empurrar, círculo) para controle de casa inteligente |
| **Reconhecimento de Atividades Humanas** | Planejado | Identificar atividades (sentar, andar, cair) |
| **Contagem de Pessoas** | Planejado | Estimar o número de pessoas em um cômodo |
| **Localização 3D** | Pesquisa | Posicionamento interno (precisão de 30-50cm) via arranjo de antenas com coerência de fase |
O Detector ML já está disponível com `detection_algorithm: ml` na sua configuração YAML. Para detalhes do algoritmo, veja [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector) e `PERFORMANCE.md` para métricas atuais.
A infraestrutura de coleta e treinamento de dados ML está documentada em [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md).
Veja [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) para planos detalhados, cronogramas e como contribuir.
---
## Documentação
### ESPectre (Produção)
| Documento | Descrição |
|----------|-------------|
| [Introdução](https://github.com/francescopace/espectre/blob/HEAD/README.md) | (Este arquivo) Visão geral do projeto, início rápido, FAQ |
| [Guia de Configuração](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | Instalação e configuração com ESPHome |
| [Guia de Ajuste](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | Ajuste de parâmetros para detecção ideal |
| [Desempenho](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | Benchmarks, matriz de confusão, pontuação F1 |
| [O Jogo](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | Jogo de navegador, API de streaming USB, ajuste interativo de limiares |
| [Suite de Testes](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | Documentação de testes PlatformIO Unity |
### Micro-ESPectre (P&D)
| Documento | Descrição |
|----------|-------------|
| [Introdução](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | Visão geral da plataforma de P&D, CLI, MQTT, Monitor Web |
| [Algoritmos](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | Documentação científica do MVS, calibração NBVI, filtro Hampel |
| [Ferramentas de Análise](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | Scripts de análise e otimização de CSI |
| [Coleta de Dados ML](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | Construção de conjuntos de dados rotulados para aprendizado de máquina |
| [Referências](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | Artigos acadêmicos e recursos de pesquisa |
### Projeto
| Documento | Descrição |
|----------|-------------|
| [Roadmap](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | Visão do projeto e planos de ML |
| [Contribuindo](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | Como contribuir (código, dados, documentos) |
| [Changelog](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | Histórico de versões e notas de lançamento |
| [Segurança](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | Política de segurança e relato de vulnerabilidades |
| [Código de Conduta](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | Diretrizes da comunidade |
---
## Mídia
| Artigos | Título |
|-------------|-------|
| Medium | [How I Turned My Wi-Fi Into a Motion Sensor - Part 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 | [How I Turned My Wi-Fi Into a Motion Sensor - Part 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 | [How I Turned My Wi-Fi Into a Motion Sensor](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [Make Your Own ESP32-Based Person Sensor, No Special Hardware Needed](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [ESPectre Human Detector for Feather](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [Deploying Espectre on Seeed Studio XIAO ESP32 Series with ESPHome](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| Blog | Discussão |
|----------|------------|
| Home Assistant | [ESPectre - Wi-Fi Motion Detection for Home Assistant](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| Vídeos | Vídeo |
|---------|-------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| Podcasts | Episódio |
|-------------|---------|
| Hackaday | [Podcast Episode 355: Person Detectors, Walkie Talkies, Open Smartphones...](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## Projetos Relacionados
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner): projeto complementar de detecção de presença focado em observações de rádio BLE de dispositivos hospedeiros (Python), com painel HTTP opcional.
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi): fork MicroPython personalizado expondo APIs CSI do ESP32, usado como base de firmware para prototipagem rápida de CSI no fluxo de trabalho Micro-ESPectre.
---
## Agradecimentos
O ESPectre aproveita as capacidades nativas de CSI Wi-Fi dos chips ESP32. Agradecimentos à [Espressif](https://www.espressif.com/) por tornar o CSI acessível no framework ESP-IDF e por reconhecer o ESPectre como um [projeto da comunidade](https://github.com/espressif/esp-csi#6-related-resources) em seu repositório [esp-csi](https://github.com/espressif/esp-csi).
---
## Licença
Este projeto é distribuído sob a **Licença Pública Geral GNU v3.0 (GPLv3)**.
A GPLv3 garante que:
- O software permaneça livre e de código aberto
- Qualquer pessoa possa usar, estudar, modificar e distribuir
- Modificações devem ser compartilhadas sob a mesma licença
- Protege os direitos dos usuários finais e a liberdade do software
Consulte [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE) para o texto completo da licença.
Contribuições são enviadas sob GPLv3 e devem incluir um trailer DCO
`Signed-off-by` em cada commit (`git commit -s`).
## Autor
**Francesco Pace**
Email: [[email protected]](mailto:[email protected])
LinkedIn: [linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
Se você acha o ESPectre útil e quer apoiar seu desenvolvimento, pode me comprar um café. É completamente opcional.
Eu trabalho neste projeto porque sou apaixonado por ele. Contribuições me ajudam a comprar novo hardware para expandir a lista de dispositivos testados e suportados, e dedicar mais tempo a novos recursos.
<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>
| Distância | Sinal | Multipath | Sensibilidade | Ruído | Recomendação |
|---|
| < 2m | Muito forte | Mínimo | Baixa | Baixo | ❌ Muito perto |
| 3-8m | Forte | Bom | Alta | Baixo | ✅ Ideal |
| > 10-15m | Fraco | Variável | Baixa | Alto | ❌ Muito longe |
P: Se não funcionar, posso obter ajuda?
R: Sim, abra uma Issue no GitHub ou contacte-me por e-mail.