Voltar às atualizações
New releaseAug 18, 2026

espectre snapshot-dev

ESPectre - Sistema de detecção de movimento baseado na análise do espectro Wi-Fi (CSI), com integração com o Home Assistant.

Compartilhar

License ESPHome Platform Release CI codecov

🛜 ESPectre 👻

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 -ml para o detector baseado em aprendizado de máquina), ou siga o Guia de configuração para configuração personalizada.

Índice

Em 3 Pontos

  1. O que faz: Detecta movimento usando Wi-Fi (sem câmeras, sem microfones)
  2. O que você precisa: Um dispositivo ESP32 de ~€10 (S3 e C6 recomendados, outras variantes suportadas)
  3. Tempo de configuração: 10-15 minutos

O Que Você Precisa

Hardware

  • Roteador Wi-Fi 2.4GHz - aquele que você já tem em casa funciona bem
  • ESP32 com suporte a CSI - ESP32-C6, ESP32-S3, ESP32-C3, ESP32 (original) ou outras variantes. Veja SETUP.md para a tabela completa de comparação de plataformas.

Pacote 3 x ESP32-S3 DevKit com antenas externas ESP32-S3 DevKit com antenas externas

Software (Todos Gratuitos)

  • Home Assistant (em Raspberry Pi, PC, NAS, ou nuvem)
  • ESPHome (integrado no Home Assistant ou autônomo)

Habilidades Necessárias

  • Conhecimento básico de YAML para configuração
  • Familiaridade com Home Assistant (opcional, mas recomendado)
  • NENHUMA programação necessária
  • NENHUMA configuração de roteador necessária

Início Rápido

Tempo de configuração: ~10-15 minutos
Dificuldade: Fácil (apenas configuração YAML)

  1. Configuração e Instalação: Siga o guia completo em SETUP.md
  2. Ajuste: Otimize para seu ambiente com TUNING.md

Painel do Home Assistant do ESPectre Painel do Home Assistant com detecção de movimento em tempo real, controle de limiar e sensores de depuração

Como Funciona

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.

Vantagens

  • Sem câmeras (privacidade total)
  • Sem necessidade de wearables (sem pulseiras ou sensores para usar)
  • Funciona através de paredes (Wi-Fi atravessa paredes)
  • Muito barato (~€10 total)

Quer entender os detalhes técnicos? Veja ALGORITHMS.md para explicação sobre CSI e documentação de processamento de sinais.

O Que Você Pode Fazer Com Isso

Exemplos Práticos

  • Segurança residencial: Receba um alerta se alguém entrar enquanto você estiver ausente
  • Cuidados com idosos: Monitore atividade para detectar quedas ou inatividade prolongada
  • Automação inteligente: Acenda luzes/aquecimento apenas quando alguém estiver presente
  • Economia de energia: Desligue dispositivos automaticamente em cômodos vazios
  • Monitoramento infantil: Alerta se saírem do quarto durante a noite
  • Controle climático: Aqueça/resfrie apenas zonas ocupadas

Onde Colocar o Sensor

O posicionamento ideal do sensor é crucial para uma detecção de movimento confiável.

Distância Recomendada do Roteador

Faixa ideal: 3-8 metros

DistânciaSinalMultipathSensibilidadeRuídoRecomendação
< 2mMuito forteMínimoBaixaBaixo❌ Muito perto
3-8mForteBomAltaBaixo✅ Ideal
> 10-15mFracoVariávelBaixaAlto❌ Muito longe

Dicas de Posicionamento

Faça:

  • Posicione o sensor na área a ser monitorada (não necessariamente em linha direta com o roteador)
  • Altura: 1-1,5 metros do chão (altura de mesa/estante)
  • Antena externa: Use conector IPEX para melhor recepção

Não faça:

  • Evite obstáculos metálicos entre roteador e sensor (geladeiras, armários de metal)
  • Evite cantos ou espaços fechados (reduz a diversidade de multipath)

Arquitetura do Sistema

Pipeline de Processamento

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:

  • Sensor binário para deteção de movimento, publicado imediatamente nas bordas de estado
  • Sensor de pontuação de movimento, publicado no ritmo periódico
  • Limiar ajustável (entidade numérica)

Seleção Automática de Subportadoras

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.

FAQ para Iniciantes

Clique para expandir FAQ

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.

P: Se não funcionar, posso obter ajuda?
R: Sim, abra uma Issue no GitHub ou contacte-me por e-mail.

Segurança e Privacidade

Privacidade, Segurança e Considerações Éticas (clique para expandir)

Natureza dos Dados Recolhidos

O sistema recolhe dados anónimos relacionados com as características físicas do canal de rádio Wi-Fi:

  • Amplitudes e fases das subportadoras OFDM
  • Variâncias estatísticas do sinal
  • NÃO recolhidos: identidades pessoais, conteúdos de comunicação, imagens, áudio

Os dados CSI representam apenas as propriedades do meio de transmissão e não contêm informações de identificação direta.

Vantagens de Privacidade

  • Sem câmaras: Respeito pela privacidade visual
  • Sem microfones: Sem gravação de áudio
  • Sem dispositivos vestíveis: Não requer dispositivos vestíveis
  • Dados agregados: Apenas métricas estatísticas, não dados identificadores brutos

⚠️ Aviso e Considerações Éticas

AVISO: Apesar da anonimidade intrínseca dos dados CSI, este sistema pode ser usado para:

  • Monitorização não consensual: Detetar presença/movimento de pessoas sem o seu consentimento explícito
  • Perfil comportamental: Com modelos avançados de IA, inferir padrões de vida diária
  • Violação de privacidade doméstica: Rastrear atividades dentro de casas particulares

Responsabilidade de Uso

O utilizador é o único responsável pelo uso deste sistema e deve:

  1. Obter consentimento explícito de todas as pessoas monitorizadas
  2. Respeitar os regulamentos locais (RGPD na UE, leis de privacidade locais)
  3. Informar claramente sobre a presença do sistema de deteção
  4. Limitar o uso a fins legítimos (segurança doméstica, automação residencial pessoal)
  5. Proteger os dados com encriptação e controlo de acesso
  6. NÃO usar para vigilância ilegal, perseguição ou violação da privacidade de outros

Mergulho Técnico

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.

Estratégia de Duas Plataformas

Este projeto segue uma abordagem de plataforma dupla para equilibrar a velocidade de inovação com a estabilidade de produção:

ESPectre (Este Repositório) - Plataforma de Produção

Alvo: Utilizadores finais, entusiastas de smart home, utilizadores do Home Assistant

  • Componente ESPHome com integração nativa no Home Assistant
  • Configuração YAML - sem necessidade de programação
  • Descoberta automática - os dispositivos aparecem automaticamente no Home Assistant
  • Pronto para produção - estável, testado, fácil de implantar
  • Demonstrativo - mostra resultados de investigação num pacote fácil de usar

Micro-ESPectre - Plataforma de I&D

Alvo: Investigadores, programadores, aplicações académicas/industriais

  • Implementação Python/MicroPython para prototipagem rápida
  • Baseado em MQTT - integração flexível (não limitado ao Home Assistant)
  • Iteração rápida - testar novos algoritmos em segundos, não minutos
  • Ferramentas de análise - conjunto abrangente para análise de dados CSI
  • Casos de uso: Investigação académica, deteção industrial, desenvolvimento de algoritmos

O Micro-ESPectre fornece os fundamentos para:

  • Contagem de pessoas
  • Reconhecimento de atividades (caminhar, cair, sentar, dormir)
  • Localização e rastreamento
  • Reconhecimento de gestos

Fluxo de Desenvolvimento```

┌─────────────────────┐ 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>
Ler mais

Categorias

Segurança IoTSegurança Sem FioPrivacidadeSegurança de Hardware e IoTAprendizado de MáquinaAprendizado e EducaçãoDetecção de Anomalias