WiFi Sense — Human Presence & Motion Detection via WiFi Signal

Based on DenseWiPose (CMU 2022): the human body absorbs and reflects WiFi RF energy, causing measurable signal perturbation.

Quick Start

# macOS / Linux
chmod +x start.sh
./start.sh

# Windows
start.bat

That's it. The script auto-detects your platform, installs dependencies, and runs.

---

What This Does

Detects human presence and motion by reading WiFi signal perturbation caused by bodies in the signal path. Works cross-platform with automatic sensor selection:

Platform	Sensor	Data	Capability
macOS	CoreWLAN RSSI	1 value @ 17Hz	Presence + motion detection
Windows	netsh RSSI	1 value @ 5Hz	Presence + motion detection
Windows + CSI tool	Intel/Atheros CSI	30-56 subcarriers @ 100Hz	Multi-person + activity
Linux	iw RSSI	1 value @ 10Hz	Presence + motion detection
Linux + Nexmon	Broadcom CSI	256 subcarriers @ 100Hz	Multi-person + activity
Linux + ESP32	Serial CSI	52 subcarriers @ 100Hz	Multi-person + activity

Ethics & Privacy

What we do	What we DON'T do
✅ Read our own WiFi signal strength	❌ No packet capture
✅ Same data as WiFi bars in menu bar	❌ No network traffic inspection
✅ Completely passive	❌ No other devices identified
✅ Works offline	❌ No BSSIDs/SSIDs collected (macOS blocks this)
✅ No special permissions needed	❌ No promiscuous mode
✅ All data stays local	❌ Nothing sent to any server

---

How It Works

[WiFi Router] ════ RF signal ════ [Your Computer]
                      ↑
                 Human body here
                 absorbs 3-15 dB

1. Calibration (3-5 sec): Records baseline signal with no movement
2. Detection: Compares real-time signal to baseline
   • High variance → Motion detected (someone walking through path)
   • Sustained shift → Presence detected (body stationary in path)
3. Signal smoothing: 5-sample moving average eliminates radio jitter (false positives)

RSSI vs CSI

	RSSI (default)	CSI (with hardware)
Data	1 number (signal strength)	30-256 complex values per sample
Analogy	"How loud is the room?"	"What does each instrument sound like?"
People	Total disruption only	Can separate multiple bodies
Accuracy	~70-80% presence	~90-95% presence + activity
Hardware	Any WiFi device	ESP32 ($10) or Nexmon (RPi)

---

Project Structure

denseWiPose/
├── start.sh              ← Run this (macOS/Linux)
├── start.bat             ← Run this (Windows)
├── run.sh                ← Legacy launcher
│
├── demo_quick.py         ← 15-sec console demo
├── wifi_sense.py         ← Full console dashboard + data recording
├── live_dashboard.py     ← Web dashboard backend (Flask + WebSocket)
├── visualize.py          ← Generate interactive 3D visualizations
├── train_model.py        ← Train ML model on collected data
│
├── sensors/              ← Platform-agnostic sensor layer
│   ├── __init__.py       ← Auto-detects best sensor for platform
│   ├── macos_rssi.py     ← macOS CoreWLAN
│   ├── windows_rssi.py   ← Windows netsh
│   ├── windows_csi.py    ← Windows CSI (Intel/Atheros/PicoScenes)
│   ├── linux_rssi.py     ← Linux iw/iwconfig
│   └── linux_csi.py      ← Linux Nexmon/Intel5300/ESP32
│
├── dashboard/
│   └── static/
│       └── index.html    ← Live 3D web dashboard (Three.js/Canvas)
│
├── data/                 ← Recorded sessions (auto-created)
├── viz/                  ← Generated visualizations (auto-created)
├── venv/                 ← Python environment (auto-created)
│
├── requirements.txt      ← Python dependencies
├── README.md             ← This file
├── CLAUDE.md             ← AI assistant context
│
└── *.pdf                 ← Research papers (DenseWiPose thesis)

---

Running Options

1. Quick Demo (console)

./start.sh  # choose 1

15-second test. Stay still for calibration, then move around. Shows detection in terminal.

2. Console Dashboard

./start.sh  # choose 2

Full real-time terminal UI with data recording. Press r to record, 1-4 to label states.

3. Live Web Dashboard

./start.sh  # choose 3

Opens browser at http://localhost:5050. Shows:

• Room layout with Router ↔ Mac signal path
• Real-time signal disruption visualization
• Motion/presence bars and RSSI graph
• Honest representation (shows disruption intensity, not fake people)

4. Visualizations

./start.sh  # choose 5

Generates interactive HTML files from collected data:

• 3D signal space (neon dots, rotatable)
• Animated timeline (press Play)
• Presence heatmap
• Radar sweep view

---

Limitations (Honest)

With RSSI only (no extra hardware):

• Cannot count individual people
• Cannot locate position precisely
• Cannot distinguish who is who
• Cannot detect falls reliably (need CSI for that)
• Environmental noise (doors, microwave) can cause false positives
• Best when body is directly in Router ↔ Computer path

Upgrade Path

Phase	Hardware	Cost	Capability
Current	Your Mac/PC only	$0	Presence + gross motion
Next	+ ESP32-S3 board	$10	CSI: multi-person, activity classification
Later	+ Raspberry Pi 4	$50	Nexmon CSI: 256 subcarriers, fall detection
Full	3TX × 3RX setup	$100	Dense pose estimation (thesis level)

---

Research Background

Based on two papers in this repo:

1. DensePose (Güler et al., Facebook AI) — Maps RGB pixels to 3D body surface UV coordinates
2. DenseWiPose (Geng, CMU 2022) — Achieves similar results using only WiFi CSI signals

Key insight: WiFi at 2.4/5GHz is absorbed by water in the human body. With enough signal diversity (multiple subcarriers × multiple antennas), a deep learning model can reconstruct body pose from signal perturbation alone.

---

License

Research/educational use. Based on publicly available academic work.