francescopace/espectreESPectre - Wi-Fi 스펙트럼 분석(CSI) 기반의 동작 감지 시스템, Home Assistant 통합 기능 포함.
Wi-Fi 스펙트럼 분석(CSI) 기반 움직임 감지 시스템, ESPHome을 통한 기본 Home Assistant 통합 지원.
[!TIP] 신규 ML 감지기: 신경망 기반 움직임 감지. 보정 불필요, 기기에서 실행. 이는 실험적 기능이며, 전용 ML 감지기 토론에서 피드백을 환영합니다. 최신 변경사항이 포함된 스냅샷 빌드도 사용 가능합니다 (기계 학습 기반 감지기의 경우
-ml자산 사용). 또는 사용자 설정은 설정 가이드를 따르세요.
외장 안테나가 있는 ESP32-S3 DevKit
설정 시간: 약 10-15분
난이도: 쉬움 (YAML 설정만 필요)
실시간 움직임 감지, 임계값 제어 및 디버그 센서가 포함된 Home Assistant 대시보드
누군가 방 안에서 움직이면, 라우터와 센서 사이를 이동하는 Wi-Fi 파동을 "교란"합니다. 이는 손전등 앞에서 손을 움직여 그림자가 변하는 것과 비슷합니다.
ESP32 기기는 이러한 변화를 "듣고" 움직임이 있는지 파악합니다.
기술적 세부 사항을 이해하려면 ALGORITHMS.md 참조 (CSI 설명 및 신호 처리 문서).
안정적인 움직임 감지를 위해서는 최적의 센서 배치가 중요합니다.
최적 범위: 3-8미터
권장 사항:
주의 사항:
ESPectre는 움직임 감지를 위해 집중된 처리 파이프라인을 사용합니다:``` ┌─────────────┐ │ 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 └─────────────┘
### 단일 또는 다중 센서```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
각 센서는 Home Assistant에 의해 자동으로 발견되며, 다음을 제공합니다:
ESPectre는 자동 서브캐리어 선택을 위해 NBVI(정규화된 대역 분산 지수, Normalized Band Variance Index)를 구현하여 수동 구성 없이 거의 최적의 성능(F1>96%)을 달성합니다. 이 알고리즘은 안정성 지표와 스펙트럼 다양성을 기반으로 12개의 비연속 서브캐리어를 선택합니다.
⚠️ 중요 (MVS 모드): 장치 부팅 후 10초 동안 방을 조용하고 정지된 상태로 유지하세요. 이 시간 동안 자동 보정이 실행되며 움직임이 감지 정확도에 영향을 미칩니다. ML 모드는 보정을 건너뜁니다.
알고리즘 세부 사항은 ALGORITHMS.md를 참조하세요.
Q: 사용하기 위해 프로그래밍 지식이 필요한가요?
A: 아니요! ESPectre는 YAML 설정 파일을 사용합니다. 예제를 다운로드하고, 플래시한 다음, ESPHome 앱이나 웹 인터페이스를 통해 WiFi를 구성하기만 하면 됩니다.
Q: 제 라우터에서 작동하나요?
A: 네, 라우터에 2.4GHz Wi-Fi가 있다면 작동합니다 (거의 모든 최신 라우터가 지원합니다).
Q: 총 비용은 얼마인가요?
A: 하드웨어: ESP32 장치(권장: S3/C6, 다른 변형도 작동) 약 €10. 소프트웨어: 모두 무료 및 오픈 소스입니다. 또한 Home Assistant가 실행 중인 환경(라즈베리 파이 약 €35-50, 또는 기존 PC/NAS)이 필요합니다.
Q: 라우터에서 어떤 것을 수정해야 하나요?
A: 아니요! 라우터는 정상적으로 작동합니다. 센서는 아무것도 수정하지 않고 Wi-Fi 신호를 "듣기"만 합니다.
Q: 벽을 통과하여 작동하나요?
A: 네, 2.4GHz Wi-Fi 신호는 석고보드를 통과합니다. 철근 콘크리트 벽은 감도를 낮추지만, 감소된 거리에서도 감지는 가능합니다.
Q: 집에 몇 개의 센서가 필요한가요?
A: 크기에 따라 다릅니다. 하나의 센서는 약 50m²를 모니터링할 수 있습니다. 더 큰 주택의 경우 여러 센서를 사용하세요 (최적의 커버리지를 위해 50-70m²마다 1개의 센서).
Q: 사람과 애완동물을 구분할 수 있나요?
A: 시스템은 사람, 애완동물 또는 기타 움직이는 물체를 구분하지 않고 일반적인 움직임을 식별하는 2-상태 분할 모델(IDLE/MOTION)을 사용합니다. 보다 정교한 분류(사람 vs 애완동물, 활동 인식, 제스처 감지)를 위해서는 훈련된 AI/ML 모델이 필요합니다 (향후 발전 섹션 참조).
Q: 메시 Wi-Fi 네트워크에서 작동하나요?
A: 네, 정상적으로 작동합니다. ESP32가 2.4GHz 대역에 연결되어 있는지 확인하세요.
Q: 감지 정확도는 얼마나 되나요?
A: 감지 정확도는 환경에 크게 의존하며 적절한 조정이 필요합니다. 성능에 영향을 미치는 요소: 방 구조, 벽 재질, 가구 배치, 라우터와의 거리(최적: 3-8m), 간섭 수준. 적절한 조정을 통해 최적 조건에서 시스템은 신뢰할 수 있는 움직임 감지를 제공합니다. segmentation_threshold 매개변수를 조정하여 특정 환경에 맞게 감도를 설정하세요.
Q: 전력 소비는 얼마인가요?
A: 연속 작동 시 일반적으로 약 500mW입니다. 펌웨어는 전력 최적화를 지원하며, 배터리 구동 배포를 위해 딥 슬립 모드를 구현할 수 있지만, 이를 위해서는 코드에 대한 사용자 정의 수정이 필요합니다.
Q: 작동하지 않으면 도움을 받을 수 있나요?
A: 네, GitHub에 이슈를 열거나 이메일로 연락해 주세요.
시스템은 Wi-Fi 무선 채널의 물리적 특성과 관련된 익명 데이터를 수집합니다:
CSI 데이터는 전송 매체의 속성만을 나타내며 직접적인 식별 정보를 포함하지 않습니다.
경고: CSI 데이터의 본질적 익명성에도 불구하고, 이 시스템은 다음 용도로 사용될 수 있습니다:
사용자는 이 시스템을 사용하는 데 전적으로 책임이 있으며, 다음을 준수해야 합니다:
알고리즘 세부 사항 (MVS, NBVI 보정, Hampel 필터)은 ALGORITHMS.md를 참조하세요.
성능 지표 (혼동 행렬, F1 점수, 벤치마크)는 PERFORMANCE.md를 참조하세요.
이 프로젝트는 혁신 속도와 프로덕션 안정성의 균형을 맞추기 위해 이중 플랫폼 접근 방식을 따릅니다:
대상: 최종 사용자, 스마트 홈 애호가, Home Assistant 사용자
대상: 연구자, 개발자, 학술/산업 응용
Micro-ESPectre는 다음을 위한 기본 기능을 제공합니다:
┌─────────────────────┐ 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 │ └─────────────────────┘ └──────────────────────┘
**혁신 주기**: 새로운 기능과 알고리즘은 먼저 Micro-ESPectre(Python)에서 개발 및 검증된 후, 효과가 입증되면 ESPectre(C++)로 포팅됩니다.
---
## 향후 발전
ESPectre v2.x는 **동작 감지**(MVS + 자동 부반송파 선택)에 중점을 두고 있지만, 이 프로젝트는 고급 응용을 위한 머신러닝 기능을 탐색하고 있습니다:
| Capability | 상태 | 설명 |
|------------|--------|-------------|
| **ML 감지기** | 실험적 | 신경망 (MLP 9→32→16→1)|
| **제스처 인식** | 계획됨 | 스마트 홈 제어를 위한 손 제스처(밀기, 누르기, 원 그리기) 감지 |
| **인간 활동 인식** | 계획됨 | 활동(앉기, 걷기, 넘어짐) 식별 |
| **인원 카운팅** | 계획됨 | 방에 있는 사람 수 추정 |
| **3D 위치 추정** | 연구 중 | 위상 일치 안테나 배열을 통한 실내 위치 측정 (30-50cm 정확도) |
ML 감지기는 이미 YAML 설정에서 `detection_algorithm: ml`로 사용할 수 있습니다. 알고리즘 세부 사항은 [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector)와 `PERFORMANCE.md`(현재 지표)를 참조하세요.
ML 데이터 수집 및 훈련 인프라는 [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md)에 문서화되어 있습니다.
자세한 계획, 일정 및 기여 방법은 [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md)를 참조하세요.
---
## 문서
### ESPectre (프로덕션)
| 문서 | 설명 |
|----------|-------------|
| [소개](https://github.com/francescopace/espectre/blob/HEAD/README.md) | (이 파일) 프로젝트 개요, 빠른 시작, FAQ |
| [설정 가이드](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | ESPHome을 사용한 설치 및 설정 |
| [튜닝 가이드](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | 최적 감지를 위한 매개변수 튜닝 |
| [성능](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | 벤치마크, 혼동 행렬, F1 점수 |
| [게임](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | 브라우저 게임, USB 스트리밍 API, 대화형 임계값 튜닝 |
| [테스트 스위트](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | PlatformIO Unity 테스트 문서 |
### Micro-ESPectre (R&D)
| 문서 | 설명 |
|----------|-------------|
| [소개](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | R&D 플랫폼 개요, CLI, MQTT, 웹 모니터 |
| [알고리즘](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | MVS, NBVI 캘리브레이션, Hampel 필터의 과학적 문서 |
| [분석 도구](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | CSI 분석 및 최적화 스크립트 |
| [ML 데이터 수집](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | 머신러닝을 위한 레이블이 지정된 데이터셋 구축 |
| [참고 자료](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | 학술 논문 및 연구 자료 |
### 프로젝트
| 문서 | 설명 |
|----------|-------------|
| [로드맵](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | 프로젝트 비전 및 ML 계획 |
| [기여하기](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | 기여 방법 (코드, 데이터, 문서) |
| [변경 로그](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | 버전 히스토리 및 릴리스 노트 |
| [보안](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | 보안 정책 및 취약점 신고 |
| [행동 강령](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | 커뮤니티 가이드라인 |
---
## 미디어
| 기사 | 제목 |
|-------------|-------|
| Medium | [내 Wi-Fi를 모션 센서로 바꾼 방법 - 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 | [내 Wi-Fi를 모션 센서로 바꾼 방법 - 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 | [내 Wi-Fi를 모션 센서로 바꾼 방법](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [특별한 하드웨어 없이 ESP32 기반 사람 감지기 직접 만들기](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [Feather용 ESPectre 사람 감지기](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [ESPHome으로 Seeed Studio XIAO ESP32 시리즈에 ESPectre 배포하기](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| 블로그 | 토론 |
|----------|------------|
| Home Assistant | [ESPectre - Home Assistant용 Wi-Fi 동작 감지](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| 동영상 | 동영상 |
|---------|-------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| 팟캐스트 | 에피소드 |
|-------------|---------|
| Hackaday | [팟캐스트 에피소드 355: 사람 감지기, 워키토키, 개방형 스마트폰 및 Wi-Fi 신호등](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## 관련 프로젝트
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner): 호스트 장치의 BLE 무선 관찰에 초점을 맞춘 보완적인 존재 감지 프로젝트(Python)로, 선택적 HTTP 대시보드를 제공합니다.
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi): ESP32 CSI API를 노출하는 맞춤형 MicroPython 포크로, Micro-ESPectre 워크플로에서 빠른 CSI 프로토타이핑을 위한 펌웨어 기반으로 사용됩니다.
---
## 감사의 말
ESPectre는 ESP32 칩의 네이티브 Wi-Fi CSI 기능을 활용합니다. CSI를 ESP-IDF 프레임워크에서 접근 가능하게 해주고, [esp-csi](https://github.com/espressif/esp-csi) 저장소에서 ESPectre를 [커뮤니티 프로젝트](https://github.com/espressif/esp-csi#6-related-resources)로 인정해준 [Espressif](https://www.espressif.com/)에 감사드립니다.
---
## 라이선스
이 프로젝트는 **GNU General Public License v3.0 (GPLv3)** 하에 출시되었습니다.
GPLv3는 다음을 보장합니다:
- 소프트웨어가 자유롭고 오픈 소스로 유지됨
- 누구나 사용, 연구, 수정 및 배포할 수 있음
- 수정 사항은 동일한 라이선스로 공유되어야 함
- 최종 사용자의 권리와 소프트웨어 자유를 보호함
전체 라이선스 텍스트는 [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE)를 참조하세요.
기여는 GPLv3 하에 제출되며 각 커밋에 DCO `Signed-off-by` 트레일러(`git commit -s`)를 포함해야 합니다.
## 저자
**Francesco Pace**
이메일: [[email protected]](mailto:[email protected])
LinkedIn: [linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
ESPectre가 유용하다고 생각하시고 개발을 지원하고 싶으시다면, 커피 한 잔 사주실 수 있습니다. 완전히 선택 사항입니다.
저는 이 프로젝트에 열정을 가지고 작업하고 있습니다. 기여는 제가 테스트되고 지원되는 장치 목록을 확장하기 위해 새 하드웨어를 구매하고, 새로운 기능에 더 많은 시간을 할애하는 데 도움이 됩니다.
<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>
| 거리 | 신호 | 다중경로 | 감도 | 잡음 | 권장 |
|---|
| < 2m | 너무 강함 | 미미 | 낮음 | 낮음 | ❌ 너무 가까움 |
| 3-8m | 강함 | 좋음 | 높음 | 낮음 | ✅ 최적 |
| > 10-15m | 약함 | 가변적 | 낮음 | 높음 | ❌ 너무 멂 |