Wi-Fi 스펙트럼 분석 (CSI) 기반 동작 감지 시스템 및 ESPHome을 통한 Home Assistant 통합

Wi-Fi 스펙트럼 분석 (CSI) 기반의 동작 감지 시스템으로, ESPHome을 통해 Home Assistant와 네이티브로 통합됩니다.

팁

새로운 ML Detector: 신경망 (Neural network) 기반의 동작 감지입니다. 별도의 보정 (Calibration)이 필요 없으며, 기기 자체에서 실행됩니다. 이는 실험적인 기능이며, 전용 ML detector 토론에서 피드백을 환영합니다. 최신 변경 사항이 적용된 스냅샷 빌드도 사용 가능하며 (머신러닝 기반 디텍터를 위해 -ml 사용), 사용자 정의 설정을 위해 설정 가이드를 따를 수 있습니다.

• 3가지 핵심 포인트
• 필요한 준비물
• 빠른 시작 (Quick Start)
• 작동 원리
• 활용 방법
• 센서 배치 가이드
• 시스템 아키텍처
• FAQ
• 보안 및 개인정보 보호
• 기술적 심층 분석 (Technical Deep Dive)
• 투 플랫폼 전략
• 향후 발전 방향
• 문서 (Documentation)
• 미디어
• 관련 프로젝트
• 감사의 글
• 라이선스
• 저자

기능: Wi-Fi를 사용하여 움직임 감지 (카메라 및 마이크 미사용)필요한 준비물: 약 10유로 상당의 ESP32 장치 (S3 및 C6 권장, 기타 변형 모델 지원)설정 시간: 10-15분

2.4GHz Wi-Fi 라우터- 이미 가정에서 사용 중인 것도 문제없이 작동합니다
CSI를 지원하는 ESP32- ESP32-C6, ESP32-S3, ESP32-C3, ESP32 (오리지널) 또는 기타 변형 모델. 전체 플랫폼 비교표는 SETUP.md를 참조하세요.

외부 안테나가 장착된 ESP32-S3 DevKit

Home Assistant(Raspberry Pi, PC, NAS 또는 클라우드 상에 설치)
ESPHome(Home Assistant에 통합되거나 단독 실행)

기본적인 YAML 지식 (설정용)
Home Assistant 숙련도 (선택 사항이지만 권장됨)
프로그래밍 불필요
라우터 설정 불필요

설정 시간: 약 10-15분

난이도: 쉬움 (YAML 설정만 필요)

설정 및 설치: SETUP.md의 전체 가이드를 따르세요
튜닝: TUNING.md를 통해 사용자의 환경에 맞게 최적화하세요

실시간 동작 감지, 임계값 (Threshold) 제어 및 디버그 센서가 포함된 Home Assistant 대시보드

누군가 방 안에서 움직이면, 라우터(Router)와 센서 사이를 이동하는 Wi-Fi 파동을 "방해"하게 됩니다. 이는 손전등 앞에서 손을 움직일 때 그림자가 변하는 것을 보는 것과 같습니다.

ESP32 장치는 이러한 변화를 "경청"하여 움직임이 있는지 이해합니다.

카메라 없음(완전한 프라이버시)
웨어러블 불필요(착용할 팔찌나 센서가 필요 없음)
벽을 통과함(Wi-Fi는 벽을 통과함)
매우 저렴함(~총 €10)

기술적인 세부 사항을 알고 싶으신가요? CSI 설명 및 신호 처리(Signal Processing) 문서는 ALGORITHMS.md를 참조하세요.

홈 보안: 외출 중 누군가 침입하면 알림을 받음
노인 돌봄: 활동을 모니터링하여 낙상이나 장시간 비활동 감지
스마트 자동화: 사람이 있을 때만 조명/난방을 켬
에너지 절약: 빈 방의 장치를 자동으로 끔
아동 모니터링: 밤중에 방을 나갈 경우 알림
기후 제어: 사람이 있는 구역만 냉난방

신뢰할 수 있는 동작 감지를 위해서는 최적의 센서 배치가 매우 중요합니다.

최적 범위: 3-8미터

거리	신호	다중 경로 (Multipath)	민감도 (Sensitivity)	노이즈 (Noise)	권장 사항
< 2m	너무 강함	최소	낮음	낮음	❌ 너무 가까움
...
권장 사항 (Do):

• 모니터링할 구역에 센서를 배치 (반드시 라우터와 직선상에 있을 필요는 없음)
• 높이: 지면에서 1-1.5미터 (책상/테이블 높이)
• 외부 안테나: 더 나은 수신을 위해 IPEX 커넥터 사용

주의 사항 (Don't):

• 라우터와 센서 사이의 금속 장애물 피하기 (냉장고, 금속 캐비닛)
• 구석진 곳이나 밀폐된 공간 피하기 (다중 경로 다양성(Multipath diversity) 감소)

ESPectre는 동작 감지를 위해 집중된 처리 파이프라인(Processing Pipeline)을 사용합니다:

┌─────────────┐
│ CSI Data │ 가공되지 않은 Wi-Fi 채널 상태 정보 (Raw Wi-Fi Channel State Information)
└──────┬──────┘
...

┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└─────────┘ └─────────┘ └─────────┘
...

각 센서는 다음과 같이 Home Assistant에 의해 자동으로 발견됩니다:

• 동작 감지를 위한 이진 센서 (Binary sensor), 상태 변화 시 즉시 발행
• 움직임 점수 센서 (Movement score sensor), 주기적인 간격으로 발행
• 조절 가능한 임계값 (숫자 엔티티 (number entity))

ESPectre는 자동 부반송파 (subcarrier) 선택을 위해 NBVI (Normalized Band Variance Index)를 구현하여, 수동 설정 없이도 최적에 가까운 성능 (F1>96%)을 달성합니다. 이 알고리즘은 안정성 지표와 스펙트럼 다양성 (spectral diversity)을 기반으로 12개의 비연속적인 부반송파를 선택합니다.

⚠️ 중요 (MVS 모드): 장치 부팅 후 10초 동안 방을 조용하고 정지된 상태로 유지하십시오. 이 시간 동안 자동 보정 (auto-calibration)이 실행되며, 움직임은 감지 정확도에 영향을 줄 수 있습니다. ML 모드는 보정 과정을 건너뜁니다.

알고리즘에 대한 자세한 내용은 ALGORITHMS.md를 참조하십시오.

클릭하여 FAQ 확장

Q: 사용하려면 프로그래밍 지식이 필요한가요?

A: 아니요! ESPectre는 YAML 설정 파일을 사용합니다. 예제를 다운로드하여 플래싱(flash)한 후, ESPHome 앱 또는 웹 인터페이스를 통해 Wi-Fi를 설정하기만 하면 됩니다.

Q: 제 공유기에서도 작동하나요?

A: 네, 공유기가 2.4GHz Wi-Fi를 지원한다면 가능합니다 (사실상 거의 모든 현대적인 공유기가 이를 지원합니다).

Q: 총 비용은 얼마나 드나요?

A: 하드웨어: ESP32 장치 약 €10 (S3/C6 권장, 다른 변형 모델도 작동함). 소프트웨어: 모두 무료이며 오픈 소스입니다. 또한 어딘가에서 실행 중인 Home Assistant가 필요합니다 (Raspberry Pi 약 €35-50, 또는 기존의 PC/NAS).

Q: 공유기 설정을 변경해야 하나요?

A: 아니요! 공유기는 정상적으로 작동합니다. 센서는 아무것도 수정하지 않고 Wi-Fi 신호를 "듣기"만 합니다.

Q: 벽을 통과해서 작동하나요?

A: 네, 2.4GHz Wi-Fi 신호는 석고보드 벽을 통과합니다. 철근 콘크리트 벽은 감도를 낮추지만, 거리가 짧아지더라도 감지는 가능합니다.

Q: 집 한 채에 몇 개의 센서가 필요한가요?

A: 크기에 따라 다릅니다. 센서 하나는 약 50 m²를 모니터링할 수 있습니다. 더 큰 집의 경우 여러 개의 센서를 사용하십시오 (최적의 커버리지를 위해 50-70 m²마다 센서 1개 권장).

Q: 사람과 반려동물을 구분할 수 있나요?

A: 이 시스템은 사람, 반려동물 또는 기타 움직이는 물체를 구분하지 않고 일반적인 움직임을 식별하는 2단계 세그멘테이션 모델 (segmentation model, IDLE/MOTION)을 사용합니다. 더 정교한 분류(사람 vs 반려동물, 활동 인식, 제스처 감지)를 위해서는 학습된 AI/ML 모델이 필요합니다 (Future Evolution 섹션 참조).

Q: 메시 Wi-Fi (mesh Wi-Fi) 네트워크에서도 작동하나요?

A: 네, 정상적으로 작동합니다. ESP32가 2.4 GHz 대역에 연결되어 있는지 확인하십시오.

Q: 감지 정확도는 어느 정도인가요?

A: 감지 정확도는 환경에 따라 크게 달라지며 적절한 튜닝 (tuning)이 필요합니다. 성능에 영향을 미치는 요인으로는 방의 구조, 벽면 재질, 가구 배치, 라우터와의 거리 (최적: 3-8m) 및 간섭 수준이 있습니다. 적절한 튜닝이 이루어진 최적의 조건에서 시스템은 신뢰할 수 있는 움직임 감지를 제공합니다. 특정 환경에 맞춰 민감도를 조절하려면 segmentation_threshold 파라미터를 조정하십시오.

Q: 소비 전력은 얼마나 되나요?

A: 연속 작동 시 전형적으로 약 500mW입니다. 펌웨어에는 전력 최적화 지원이 포함되어 있으며, 배터리로 구동되는 배포를 위해 딥 슬립 (deep sleep) 모드를 구현할 수 있지만, 이를 위해서는 코드의 사용자 정의 수정이 필요합니다.

Q: 작동하지 않을 경우 도움을 받을 수 있나요?

A: 네, GitHub에 이슈 (Issue)를 생성하거나 이메일로 연락해 주십시오.

개인정보 보호, 보안 및 윤리적 고려 사항 (클릭하여 확장)

이 시스템은 Wi-Fi 무선 채널의 물리적 특성과 관련된 **익명 데이터 (anonymous data)**를 수집합니다:

• OFDM 부반송파 (subcarriers)의 진폭 (amplitude) 및 위상 (phase)
• 통계적 신호 분산 (statistical signal variances)
  수집되지 않는 항목: 개인 신원, 통신 내용, 이미지, 오디오

CSI 데이터는 전송 매체의 특성만을 나타내며 직접적인 식별 정보를 포함하지 않습니다.

카메라 없음: 시각적 프라이버시 존중
마이크 없음: 오디오 녹음 없음
웨어러블 기기 없음: 착용형 장치가 필요하지 않음
집계된 데이터: 원시 식별 데이터가 아닌 통계적 지표만 사용

경고: CSI 데이터의 본질적인 익명성에도 불구하고, 이 시스템은 다음과 같은 용도로 사용될 수 있습니다:

비동의 모니터링 (Non-consensual monitoring): 개인의 명시적 동의 없이 사람의 존재나 움직임을 감지
행동 프로파일링 (Behavioral profiling): 고급 AI 모델을 사용하여 일상생활 패턴을 추론
가정 내 사생활 침해 (Domestic privacy violation): 개인 주택 내부의 활동을 추적

사용자는 이 시스템의 사용에 대해 전적인 책임을 지며, 반드시 다음 사항을 준수해야 합니다:

명시적 동의 확보: 모니터링되는 모든 사람으로부터 동의를 얻어야 함
현지 규정 준수: (EU의 GDPR, 현지 개인정보 보호법 등)
명확한 고지: 감지 시스템이 존재함을 명확히 알려야 함
사용 제한: 정당한 목적(홈 보안, 개인용 홈 자동화)으로만 사용을 제한함
데이터 보호: 암호화 및 제어된 접근을 통해 데이터를 보호함
불법 감시, 스토킹 또는 타인의 사생활 침해를 위해 사용하지 말 것

알고리즘 상세 정보(MVS, NBVI 보정, Hampel 필터)는 ALGORITHMS.md를 참조하십시오.

성능 지표(혼동 행렬 (Confusion matrix), F1-score, 벤치마크)는 PERFORMANCE.md를 참조하십시오.

이 프로젝트는 혁신 속도와 운영 안정성 사이의 균형을 맞추기 위해 **이중 플랫폼 접근 방식 (dual-platform approach)**을 따릅니다:

대상: 최종 사용자, 스마트 홈 애호가, Home Assistant 사용자

ESPHome 구성 요소: Home Assistant와 네이티브 통합 지원
YAML 설정: 프로그래밍이 필요 없음
자동 검색 (Auto-discovery): Home Assistant에 장치가 자동으로 나타남
운영 준비 완료 (Production-ready): 안정적이고 테스트되었으며 배포가 용이함
시연용 (Demonstrative): 연구 결과를 사용자 친화적인 패키지로 보여줌

대상: 연구자, 개발자, 학술/산업용 애플리케이션

Python/MicroPython 구현: 빠른 프로토타이핑을 위함
MQTT 기반: 유연한 통합 (Home Assistant에 국한되지 않음)
빠른 반복 (Fast iteration): 새로운 알고리즘을 몇 분이 아닌 몇 초 만에 테스트
분석 도구: CSI 데이터 분석을 위한 종합적인 스위트 제공
사용 사례 (Use cases): 학술 연구, 산업용 센싱, 알고리즘 개발

Micro-ESPectre는 다음과 같은 기초를 제공합니다:

인원 계수 (People counting)
활동 인식 (Activity recognition) (걷기, 넘어짐, 앉기, 수면)
위치 파악 및 추적 (Localization and tracking)
제스처 인식 (Gesture recognition)

┌─────────────────────┐ Validated ┌──────────────────────┐
│ Micro-ESPectre │ ─────────────────► │ ESPectre │
│ (R&D Platform) │ algorithms │ (Production Platform)│
...

혁신 주기 (Innovation cycle): 새로운 기능과 알고리즘은 먼저 Micro-ESPectre (Python)에서 개발 및 검증된 후, 효과가 입증되면 ESPectre (C++)로 이식됩니다.

ESPectre v2.x가 동작 감지 (motion detection) (MVS + 자동 부반송파 선택)에 집중하는 동안, 이 프로젝트는 고급 애플리케이션을 위한 머신러닝 (Machine Learning) 기능을 탐색하고 있습니다:

기능	상태	설명
ML 탐지기 (ML Detector)	실험적 (Experimental)	신경망 (Neural network) (MLP 9→32→16→1)
제스처 인식 (Gesture Recognition)	계획됨 (Planned)	스마트 홈 제어를 위한 손 제스처 (스와이프, 밀기, 원 그리기) 감지
인간 활동 인식 (Human Activity Recognition)	계획됨 (Planned)	활동 식별 (앉기, 걷기, 넘어짐)
인원 계수 (People Counting)	계획됨 (Planned)	방 안의 인원수 추정
3D 위치 파악 (3D Localization)	연구 중 (Research)	위상 일관 안테나 어레이 (phase-coherent antenna array)를 통한 실내 측위 (30-50cm 정확도)

ML 탐지기는 YAML 설정에서 detection_algorithm: ml을 통해 이미 사용할 수 있습니다.

알고리즘에 대한 자세한 내용은 ALGORITHMS.md를 참조하고, 현재 성능 지표는 PERFORMANCE.md를 참조하십시오.

ML 데이터 수집 및 학습 인프라는 ML_DATA_COLLECTION.md에 문서화되어 있습니다.

상세 계획, 타임라인 및 기여 방법은 ROADMAP.md를 참조하십시오.

문서	설명
Intro	(이 파일) 프로젝트 개요, 빠른 시작, FAQ
...
문서	설명
---	---
Intro	R&D 플랫폼 개요, CLI, MQTT, Web Monitor
...
문서	설명
---	---
Roadmap	프로젝트 비전 및 ML 계획
...
기사 (Articles)	제목
---	---
Medium	How I Turned My Wi-Fi Into a Motion Sensor - Part 1
...
Blog	토론
---	---
Home Assistant	ESPectre - Home Assistant를 위한 Wi-Fi 동작 감지

Videos	비디오
@GithubAwesome	ESPectre

Podcasts	에피소드
Hackaday	Podcast Episode 355: Person Detectors, Walkie Talkies, Open Smartphones...

• radio-presence-presence-scanner: 호스트 장치의 BLE (Bluetooth Low Energy) 무선 관측에 집중한 상호 보완적인 재실 감지 (presence-sensing) 프로젝트 (Python), 선택 사항으로 HTTP 대시보드 제공.
• micropython-esp32-csi: ESP32 CSI API를 노출하는 커스텀 MicroPython 포크(fork), Micro-ESPectre 워크플로우 내에서 신속한 CSI 프로토타이핑을 위한 펌웨어 기반으로 사용됨.

ESPectre는 ESP32 칩의 네이티브 Wi-Fi CSI 기능을 활용합니다. CSI를 ESP-IDF 프레임워크에서 사용할 수 있게 해주고, ESPectre를 그들의 esp-csi 저장소에서 커뮤니티 프로젝트로 인정해 준 Espressif 측에 감사드립니다.

이 프로젝트는 GNU General Public License v3.0 (GPLv3) 라이선스 하에 배포됩니다.

GPLv3는 다음을 보장합니다: