ESPectre

Transforme um ESP32 num sensor de movimento Wi-Fi privado e local.

Quando alguém se move por uma sala, altera a forma como os sinais Wi-Fi a atravessam. O ESPectre lê essas alterações e reporta movimento em tempo real. Sem câmara, sem microfone, sem wearable e sem hardware de radar dedicado: apenas um ESP32 suportado e a rede Wi-Fi já existente na sala.

ESPectre é uma plataforma de código aberto que reúne firmware pronto a gravar, um SDK C++ incorporável, uma implementação em MicroPython, ferramentas de browser, um CLI de anfitrião, um conjunto de dados aberto, pesos de modelo abertos e o fluxo de trabalho de investigação utilizado para construir e validar os detetores.

Grave a partir do browser · Veja as ferramentas ao vivo · Leia a documentação · Explore o SDK

Aplicações e integrações

O ESPectre pode ligar um ecrã ou luzes quando deteta movimento, ajustar aquecimento e arrefecimento em resposta à atividade na sala, acionar um alarme ou notificação quando ocorre movimento numa área que deveria estar vazia, e conduzir outras automações de sala. Liga-se ao Home Assistant através de ESPHome ou MQTT, expõe um sensor de ocupação Matter padrão e uma API HTTP Direta local, e pode ser incorporado em firmware ESP32 personalizado através do SDK C++.

O ESPectre processa CSI no dispositivo e reporta um estado de movimento e uma pontuação de movimento. As aplicações podem reagir sem enviar dados brutos de deteção para um serviço na nuvem. Uma placa cobre uma área de deteção; a cobertura ao nível da sala normalmente requer uma placa por sala.

O ESPectre deteta alterações no ambiente de rádio. Não identifica pessoas, não as conta, não prova que uma sala está vazia, nem substitui um sistema de segurança, médico ou de emergência certificado.

Hardware suportado

• ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 e ESP32 clássico
• uma rede Wi-Fi 4 (802.11n) normal em 2.4 GHz

Escolha um caminho de firmware

Nativo, ESPHome e Matter podem escolher entre um detetor lightweight, que aprende um limiar específico da sala no arranque e deixa mais recursos para o resto da aplicação, e um detetor high_accuracy, que executa o modelo treinado incluído no repositório. O seu comportamento e os compromissos medidos estão documentados em SETUP.md, ALGORITHMS.md e no relatório de desempenho.

Início rápido

O caminho mais rápido usa o browser e não requer ambiente de compilação local. Use Chrome 151 ou posterior no desktop para o fluxo de trabalho hospedado completo. O Edge suporta gravação via browser, mas a compatibilidade com Device settings e Monitor não é garantida:

1. Abra Flash no Chrome ou Edge de desktop.
2. Ligue um ESP32 suportado via USB e escolha um firmware e canal de lançamento.
3. Complete o aprovisionamento Wi-Fi no ecrã ou faça a comissão Matter com um controlador suportado.
4. Opcionalmente, abra Device settings para fixar um ponto de acesso preferido ou configurar MQTT.
5. Abra Monitor para observar movimento, ajustar a deteção e inspecionar o dispositivo.

Estado do Matter: O frontend Matter ainda está a ser validado em ecossistemas de controladores. Um controlador pode suportar sensores de ocupação Matter padrão sem ter sido testado com o firmware atual. Consulte Compatibilidade de controladores Matter para a matriz atual.

Configuração local

Para compilações locais, gravação a partir deste repositório e o resto do caminho de operador, comece com SETUP.md. O wrapper do repositório expõe os fluxos de trabalho disponíveis através de:

./espectre --help

Documentação

Conjuntos de dados, modelos e validação

O ESPectre publica os ativos de investigação e as evidências de validação por detrás dos seus detetores:

Segurança, privacidade e transparência

Um sensor que pode revelar presença não deveria ser uma caixa negra. A deteção Wi-Fi evita imagens e áudio, mas os dados de movimento e ocupação podem ainda assim revelar rotinas, sono ou ausência de casa. O ESPectre trata esse risco como parte do trabalho de engenharia:

• a deteção de movimento é local e a conectividade à nuvem não é necessária;
• a recolha de CSI bruto é opcional e destinada a necessidades definidas de investigação e depuração;
• o guia de segurança e utilização responsável documenta limites de implantação, consentimento, minimização de dados, reporte de abuso e reporte privado de vulnerabilidades;
• os lançamentos de firmware incluem SBOMs específicos da compilação, avisos e arquivos de licença para que o seu conteúdo possa ser inspecionado;
• o site público e todas as ferramentas de browser fazem parte deste repositório em docs/web, incluindo o seu código-fonte, regras de privacidade, contrato de análise e dependências de browser fixadas;
• protocolos, algoritmos, evidências de desempenho, limitações, decisões de roadmap e limites de validação conhecidos estão documentados publicamente.

Use o ESPectre apenas em espaços e redes onde tenha o direito de o implantar. Informe as pessoas afetadas, obtenha consentimento quando exigido, proteja o acesso ao dispositivo e aos seus dados e cumpra as leis de privacidade aplicáveis.

Agradecimentos

• Obrigado à Espressif por tornar o CSI acessível no ESP-IDF e por reconhecer o ESPectre como um projeto comunitário no esp-csi.
• Obrigado aos mantenedores do MicroPython por reverem, testarem e integrarem a contribuição CSI do ESPectre, que adicionou métodos CSI diretos ao network.WLAN principal.

Licença

O código de primeira parte do ESPectre está disponível sob GPLv3, e partes elegíveis também estão disponíveis sob um acordo comercial separado:

• Escolha GPLv3 quando o seu firmware ou aplicação puder cumprir a GPLv3, incluindo disponibilizar o código-fonte correspondente. Consulte LICENSE.
• Se pretender incorporar o ESPectre em firmware proprietário ou de código fechado sem as obrigações de divulgação de código-fonte da GPLv3, consulte LICENSING.md para licenciamento comercial. A licença comercial cobre material elegível e não substitui termos de terceiros; o frontend C++ ESPHome permanece exclusivamente GPLv3.

Os termos de terceiros e os artefactos de conformidade específicos da compilação estão descritos em THIRD_PARTY_NOTICES.md.