OpenSource-Hub

espectre

애플리케이션

francescopace/espectre

Wi-Fi CSI 기반 모션 감지 시스템으로, Home Assistant와 통합됩니다.

개요

ESPectre는 Wi-Fi 채널 상태 정보(CSI)를 분석하여 인체 움직임을 감지하며, 약 10유로의 ESP32 장치만으로 카메라나 마이크 없이 프라이버시를 보호합니다. Home Assistant와 네이티브로 통합되며, 신경망 기반 감지기를 포함한 다양한 감지 알고리즘을 지원합니다.

README 미리보기

[](https://github.com/francescopace/espectre/blob/main/LICENSE)\n[](https://esphome.io/)\n[](https://www.espressif.com/en/products/socs)\n[](https://github.com/francescopace/espectre/releases/latest)\n[](https://github.com/francescopace/espectre/actions/workflows/ci.yml?query=branch%3Amain)\n[](https://codecov.io/gh/francescopace/espectre)\n\n# 🛜 ESPectre 👻\n\n**Motion detection system based on Wi-Fi spectre analysis (CSI), with native Home Assistant integration via ESPHome.**\n\n> [!TIP]\n> **New ML Detector**: Neural network-based motion detection. No calibration required, runs on-device. This is an experimental feature, and feedback is welcome in the dedicated [ML detector discussion](https://github.com/francescopace/espectre/discussions/126). A [snapshot build](https://github.com/francescopace/espectre/releases/tag/snapshot) with the latest changes is also available (use `-ml` assets for the machine learning based detector), or follow [Setup guide](SETUP.md#choosing-detection-algorithm) for custom configuration.\n\n---\n\n## Table of Contents\n\n- [In 3 Points](#in-3-points)\n- [What You Need](#what-you-need)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works-simple-version)\n- [What You Can Do With It](#what-you-can-do-with-it)\n- [Sensor Placement Guide](#where-to-place-the-sensor)\n- [System Architecture](#system-architecture)\n- [FAQ](#faq-for-beginners)\n- [Security and Privacy](#security-and-privacy)\n- [Technical Deep Dive](#technical-deep-dive)\n- [Two-Platform Strategy](#two-platform-strategy)\n- [Future Evolution](#future-evolution)\n- [Documentation](#documentation)\n- [Media](#media)\n- [Related Projects](#related-projects)\n- [Acknowledgments](#acknowledgments)\n- [License](#license)\n- [Author](#author)\n\n---\n\n## In 3 Points\n\n1. **What it does**: Detects movement using Wi-Fi (no cameras, no microphones)\n2. **What you need**: A ~€10 ESP32 device (S3 and C6 recommended, other variants supported)\n3. **Setup time**: 10-15 minutes\n

FAQ (5)

문제 해결
왜 ESP32-S3는 ESPHome/ESPectre 부팅 후 오랫동안 calibration 상태에 머물러 있으며, 어떻게 해결할 수 있나요?

캘리브레이션 시간이 길다는 것은 일반적으로 실제 CSI 패킷 전송률이 설정된 traffic_generator_rate보다 훨씬 낮다는 의미입니다. 기본 DNS 기반 트래픽 생성기는 일부 라우터에서 무시되거나 속도 제한이 적용될 수 있습니다. YAML 설정에서 트래픽 생성기를 ping 모드로 변경한 후 다시 컴파일하고 플래시하세요:

espectre:
  traffic_generator_rate: 100
  traffic_generator_mode: ping

재부팅 후 CSI 패킷 전송률이 100 packets/s에 가까운지 확인하세요. 그러면 캘리브레이션이 훨씬 빠르게 완료될 것입니다.

원본 Issue #125
문제 해결
ESPHome에서 ESPectre를 NSPanel-Easy와 통합할 때 발생하는 -Wreorder 및 -Wformat= 컴파일러 경고를 어떻게 해결하나요?

생성자 초기화 순서와 %u/uint32_t 로깅 형식 경고를 수정한 ESPectre 3.0.0-rc1 이상 버전으로 업그레이드하세요. YAML에서 외부 컴포넌트를 릴리스 태그로 고정하세요. 예를 들면 다음과 같습니다:

external_components:
  - source:
      type: git
      url: https://github.com/francescopace/espectre
      ref: 3.0.0-rc1
    components: [ espectre ]
    refresh: 300s

그런 다음 ESPHome 펌웨어를 다시 설치하세요. 이러한 경고는 NSPanel-Easy가 아닌 ESPectre에서 발생하는 것입니다. 2.8.x에서는 치명적이지 않으며, 컴파일, OTA 설치 및 모션 감지가 여전히 정상적으로 작동할 수 있습니다.

원본 Issue #157
문제 해결
ESPHome/ESP-IDF에서 MQTT를 활성화한 후 발생하는 ESP32-S3 Task Watchdog loopTask 리셋은 어떻게 해결하나요?

리셋은 CSI 처리, BLE, 로깅이 함께 실행되는 동안 동기식 MQTT 전송이 ESPHome 메인 루프를 차단하면서 발생합니다. ESP-IDF에서는 비동기 MQTT 전송을 활성화하고 discovery와 MQTT 로그 전달을 비활성화하여 MQTT 오버헤드를 줄이세요:

mqtt:
  broker: broker.hivemq.com
  port: 1883
  idf_send_async: true
  discovery: false
  log_topic: None

다음 명령으로 다시 빌드하고 플래시하세요:

esphome run espectre-s3.yaml

idf_send_async: true는 MQTT 전송을 별도의 태스크로 이동시켜 더 이상 loopTask를 차단하지 않습니다. discovery와 log_topic을 비활성화하면 처리 부하와 네트워크 트래픽이 줄어듭니다. 이 구성은 Wi-Fi, CSI, 캘리브레이션, 모션 감지, 시리얼 로깅, Home Assistant API, MQTT 발행이 모두 정상적으로 동작하는 상태에서 워치독 리셋을 해결하는 것으로 확인되었습니다.

원본 Issue #147
문제 해결
플래싱 성공 후 ESP32-S3에서 Micro-ESPectre가 CSI 패킷을 0개 수신하는 문제를 해결하는 방법은?

인터넷 연결은 필요하지 않습니다. CSI 수집에는 동일한 LAN에 있는 디바이스 간의 로컬 Wi-Fi 트래픽이 필요합니다. ESP32-S3가 성공적으로 연결되지만 traffic-generator 재시도 후에도 CSI가 0으로 유지되므로, 동일한 네트워크에 있는 다른 PC나 휴대폰에서 보드를 향해 외부 트래픽을 생성하십시오. 로그에 표시된 IP를 사용하십시오. 예를 들면:

Linux/macOS:
ping 192.168.1.100

Windows:
ping -t 192.168.1.100

Micro-ESPectre가 시작되는 동안 30~60초간 실행하십시오. 또한 라우터가 HT20을 사용하는 802.11n/b/g와 같은 호환 모드를 사용 중인지 확인하십시오. ping을 보내는 동안 CSI 패킷이 나타나면, 문제는 AP/라우터가 내부 traffic-generation/CSI-trigger 경로를 처리하지 못하는 것일 가능성이 높습니다. 외부 LAN 트래픽을 계속 사용하거나 다른 라우터로 테스트하십시오. S3 칩이 감지되고 Wi-Fi가 성공적으로 연결되므로 펌웨어 호환성 문제일 가능성은 낮습니다.

원본 Issue #110
문제 해결
ESP32-S3에서 ESPectre의 movement_score 및 motion_detected가 "unknown" 상태로 유지되는 문제를 해결하는 방법은?

traffic-generator 속도를 낮추고 ping 모드에서 dns 모드로 전환한 후 캘리브레이션에 추가 시간을 주세요. 캘리브레이션은 초기에 로그나 센서 업데이트를 생성하지 않을 수 있습니다:

espectre:
  id: espectre_csi
  traffic_generator_mode: dns
  traffic_generator_rate: 50

기존 detection_algorithm 설정은 그대로 유지하세요. 다시 플래시한 후 sensor.movement_score와 binary_sensor.motion_detected를 확인하기 전에 평소 시작 시간보다 더 오래 기다리세요.

그래도 여전히 아무것도 발행하지 않는다면 AP 비호환성이 원인일 가능성이 큽니다. 라우터는 ESP32-S3에 사용 가능한 802.11n HT20 프레임을 반환해야 합니다. 라우터가 호환되지 않는 Wi-Fi 6/AX 또는 n-only 구성이 아닌, 호환 가능한 2.4 GHz 802.11n/b/g/n 모드로 설정되어 있는지 확인하고, 가능하다면 다른 액세스 포인트를 대상으로 테스트해 보세요.

원본 Issue #146