WifiVision 📡👁️

World-Class Hardware-Agnostic Wi-Fi Spatial Intelligence, Contactless Vitals, Deterministic Safety & 3D Pose Engine

Transform standard commodity Wi-Fi radio reflections into real-time 3D spatial awareness, camera-free human pose tracking, and contactless cardiopulmonary vital signs.

Quickstart • Interactive Dashboard • Architecture • Hardware Tiers • Safety Engine • Documentation

---

🌟 Key Highlights & Capabilities

WifiVision is an open-source, hardware-agnostic spatial computing and RF sensing engine. By extracting and processing high-frequency Channel State Information (CSI) and subcarrier dynamics from ambient Wi-Fi transmissions, WifiVision delivers:

• 🚪 Through-the-Wall Non-Line-of-Sight (NLOS) Sensing: Detect static and moving human occupants behind walls, doors, and furniture with zero optical cameras, safeguarding 100% privacy (HIPAA / GDPR compliant).
• 🫁 Contactless Vital Signs Monitoring: Real-time extraction of respiration rate ($\pm 1 \text{ breath/min}$) and cardiac pulse rhythms without wearables or physical sensors.
• 🧍 21-Joint 3D Human Pose Estimation: Neural reconstruction of full-body skeletons via WiFiPoseNet multi-scale temporal convolutions and self-supervised cross-modal distillation.
• 🛡️ Deterministic Safety Action Engine: Sub-millisecond, auditable automated rules for fall detection (HLTH-002), unauthorized spatial intrusions (SEC-001), and respiration anomalies (HLTH-003).
• 🤖 AI Operator Copilot & Triage Service: REST endpoint (/api/triage) providing automated incident summaries and grounded operational playbook recommendations.
• 📡 Zero-Cost Hardware Agnosticism: Operates out of the box on any standard laptop or PC Wi-Fi card (Intel, Realtek, Broadcom, MediaTek) connected to your local router without purchasing extra hardware.
• ⚡ Real-Time 60 FPS WebGL 3D Dashboard: High-density glassmorphism UI with full-width navbar, active BSSID router scanner, 4-tab control drawer, "Myself" avatar origin, expanding RF wave spheres, and sub-30ms streaming latency.

---

🖥️ Interactive WebGL 3D Dashboard

High-density glassmorphism dashboard featuring real-time 3D spatial viewport, expanding router RF waves, scanned BSSID data table, and live cardiopulmonary vitals HUD.

Dashboard Interface Architecture:

1. 100% Full-Width Top Navbar: Fixed header with brand badge, real-time data provenance pill (ESP32-CSI (REAL) / PICOSCENES (REAL) / SYNTHETIC CSI), active target router BSSID, 60 FPS render meter, and sub-30ms latency badge.
2. Interactive BSSID Network Table: Live scanner discovering all nearby 802.11 access points with instant one-click targeting and channel metrics.
3. 4-Tab Control Drawer:
   • 📡 Networks: Target access point selector and signal metrics.
   • 🎛️ RF Tuning: Sliders for Sensitivity Multiplier, Bearing Angle ($-180^\circ$ to $+180^\circ$), Noise Floor Cutoff, and Doppler Gain.
   • 👥 Entities: Spatial entity visibility toggles ("Myself" Client Avatar, "Others in Area", 3D Skeletons, RF Wave Spheres, Joint Labels).
   • 📊 Telemetry: Subcarrier phase metrics, packet loss indicators, and frame counters.
4. Spatial 3D Viewport: Three.js WebGL canvas featuring interactive orbit controls, room boundary grids, expanding translucent RF wave animations, and 3D joint coordinate tracking.

---

📐 System Architecture & Signal Processing

5-Stage Architectural Pipeline:

[Ambient Wi-Fi AP / Router] === (2.4 / 5 / 6 GHz RF Signals) ===> [Human Target] ===> [PC Wi-Fi Card / CSI Node]
                                                                                               │
                                                                                               ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 1: HARDWARE ABSTRACTION LAYER (HAL)                                                                        │
│ • Tier A: Windows Native `wlanapi.dll` C-Bindings (Zero-Cost)     • Tier B: Intel AX200/AX210 PicoScenes Driver │
│ • Tier C: ESP32-S3 Binary Serial / UDP CSI Stream Collector       • Tier D: Realtek RTL8812AU Monitor Mode NIC  │
└───────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┘
                                                        │
                                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 2: SIGNAL PROCESSING & SAN PHASE CALIBRATION (DSP)                                                        │
│ • SAN Phase Linear Fitting (CFO & PDD Cancellation)                • Widar / IndoTrack CSI-Ratio Coherence      │
│ • Hampel Outlier & PCA Static Clutter Filter                       • 4th-Order Butterworth Vitals Filter        │
│ • Short-Time Fourier Transform (STFT) Micro-Doppler Spectrum       • MUSIC 3D Angle of Arrival (AoA) Array      │
└───────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┘
                                                        │
                                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 3: NEURAL INFERENCE & 3D POSE DECODER (PyTorch)                                                           │
│ • WiFiPoseNet: Multi-Scale 1D-CNN Feature Extractor + Temporal Transformer Spatial Keypoint Regressor          │
│ • 21-Joint 3D Coordinate Decoder $(x_j, y_j, z_j)$                • Cross-Modal Distillation (Webcam → CSI)    │
└───────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┘
                                                        │
                                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 4: DETERMINISTIC SAFETY ACTION ENGINE & AI TRIAGE                                                         │
│ • Sub-millisecond rule evaluation (SEC-001 Intrusion, HLTH-002 Fall Risk, HLTH-003 Respiration Anomaly)        │
│ • AI Operator Copilot Triage Endpoint (`/api/triage`) with grounded playbook action retrieval                   │
└───────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┘
                                                        │
                                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 5: STREAMING SERVER & 3D WEBGL VISUALIZATION                                                              │
│ • FastAPI Async WebSockets Hub (`/ws/telemetry` @ 60 Hz)          • Three.js 3D Spatial Canvas                  │
│ • Full-Width Navbar, Scanned BSSID Data Table, Expanding RF Wave Spheres, Respiration & Heart Rate HUD          │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

---

🫁 Contactless Vitals & 3D Pose Analytics

Mathematical Foundations:

1. CSI Phase Sanitization (SAN): Eliminates Carrier Frequency Offset (CFO) and Packet Detection Delay (PDD) across subcarriers $k = 1, \dots, N$: $$\hat{\phi}k = \phi_k - a \cdot k - b, \quad a = \frac{\phi_N - \phi_1}{2\pi (N - 1)}, \quad b = \frac{1}{N}\sum{k=1}^N \phi_k$$

2. CSI Conjugate Ratio Phase Coherence: Cancels common-mode clock phase noise between primary antenna $i$ and reference antenna $r$: $$\tilde{H}_i(f, t) = \frac{H_i(f, t) \cdot \overline{H_r(f, t)}}{|H_r(f, t)|^2 + \epsilon}$$

3. Cardiopulmonary Micro-Motion Bandpass:

   • Respiration: $0.1 \text{ Hz} \le f \le 0.5 \text{ Hz}$ ($6 - 30 \text{ breaths/min}$)
   • Cardiac Pulse: $0.8 \text{ Hz} \le f \le 2.5 \text{ Hz}$ ($48 - 150 \text{ beats/min}$)

4. MUSIC 3D Angle of Arrival (AoA): $$P_{\text{MUSIC}}(\theta) = \frac{1}{\mathbf{a}^H(\theta) \mathbf{E}_n \mathbf{E}_n^H \mathbf{a}(\theta)}$$

---

🛠️ Hardware Compatibility & Sensing Tiers

Tier	Hardware / Network Adapter	Cost	Capabilities & Supported Drivers
Tier A (Zero-Cost OS Native)	Standard Built-in PC Wi-Fi Cards (Intel, Realtek 8821AE, Broadcom, MediaTek)	$0 (Zero Purchase)	Native OS wlanapi.dll / iw C-bindings, High-rate RSSI dynamics, Respiration extraction, Multi-BSSID scanning
Tier B (SOTA CSI Driver Hooks)	Intel AX200 / AX210 / AX211, Broadcom BCM43xx	$0 (Existing Card)	PicoScenes / FeitCSI / Nexmon subcarrier CSI matrix $H(f,t)$, 3D MUSIC AoA
Tier C (Microcontroller Collector)	ESP32-S3 / ESP32-WROOM-32	$5 - $9	Binary serial/UDP CSI capture, dedicated standalone RF probe node
Tier D (Monitor Mode SDR)	Realtek RTL8812AU / Intel 5300	$15 - $35	5 GHz monitor mode, full 3x3 MIMO spatial array sensing

---

🚀 Quickstart Guide

1. One-Click Windows Launch (Recommended)

Double-click run_wifivision.bat or run in terminal:

.\run_wifivision.bat

The launcher performs automated preflight checks (Python 3.10+, dependencies, module verification, port availability), starts the FastAPI server, and launches your browser to http://localhost:8000/.

2. Manual Command-Line Setup (Windows / Linux / macOS)

# Clone the repository
git clone https://github.com/kirklasalle/WifiVision.git
cd WifiVision

# Create and activate virtual environment
python -m venv venv
# On Windows:
.\venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start WifiVision Server
python -m src.server.app --port 8000 --host 0.0.0.0

3. ESP32-S3 Hardware CSI Collector (Optional)

If using an ESP32-S3 node for physical subcarrier CSI capture:

cd firmware/esp32_csi_collector
idf.py set-target esp32s3
idf.py build
idf.py -p COM3 flash monitor

The server auto-detects connected ESP32-S3 devices on startup and streams genuine hardware CSI telemetry.

---

🛡️ Deterministic Safety Rules & AI Copilot

WifiVision incorporates a sub-millisecond deterministic safety evaluation engine (src/signal_processing/rules_engine.py):

Rule ID	Event Type	Trigger Criteria	Automated Action Dispatched
SEC-001	Spatial Intrusion	High-confidence motion perturbation when perimeter armed	dispatch_security_alert
HLTH-002	Fall Risk	Sudden elevation drop & rapid Doppler velocity deceleration	notify_care_team
HLTH-003	Respiration Anomaly	Respiration rate $< 8 \text{ bpm}$ or $> 32 \text{ bpm}$	trigger_clinical_alert
OPS-003	Telemetry Degradation	Wi-Fi frame drops $> 30%$ or SNR $< 10 \text{ dB}$	raise_telemetry_ticket

AI Operator Copilot Triage Endpoint (POST /api/triage):

{
  "event_id": "EVT-2026-004",
  "event_type": "fall_risk",
  "severity": "high",
  "evidence": {
    "confidence": 0.94,
    "metrics": {
      "respiration_bpm": 13.5,
      "fall_deceleration_g": 2.4
    }
  }
}

Response:

{
  "incident_summary": "High-confidence fall risk event detected at coordinate (1.4m, 2.1m). Respiration remains regular at 13.5 bpm.",
  "recommended_actions": [
    "Dispatch on-duty caregiver to Zone B immediately.",
    "Verify audio intercom in room.",
    "Acknowledge alert in care portal."
  ]
}

---

🔌 REST & WebSocket API Specification

Endpoint	Protocol	Description
GET /	HTTP	Serves the 3D WebGL Glassmorphism Dashboard
GET /api/status	HTTP	System health, active hardware adapter, and latency SLA
GET /api/wifi/scan	HTTP	Scans and returns all visible Wi-Fi access points in range
POST /api/wifi/select	HTTP	Dynamically targets a specific router BSSID at runtime
POST /api/triage	HTTP	AI Operator Copilot incident triage & playbook recommendations
WS /ws/telemetry	WebSocket	60 Hz real-time 3D pose, vitals, RF waves, and safety stream

---

📑 Structured Logtracing Architecture

Enterprise-grade multi-file asynchronous logtracing written to logs/:

• 📝 wifivision.log: System lifecycle, server startup, and REST API calls.
• 📡 rf_sensing_trace.log: Sub-millisecond physical layer subcarrier telemetry, RSSI readings, and processing latency.
• 🔌 hardware_events.log: NIC adapter detection, BSSID scan results, and target router selection events.

---

📚 Technical Documentation Suite

• 📋 Product Requirement Document (PRD): Functional & non-functional SLAs, personas, and privacy guarantees.
• 🏗️ System Architecture Document: Mathematical formulations, SAN algorithm, and neural network specs.
• 💻 Developer Guide: Code contribution guidelines, rules engine, and API schemas.
• 🔌 Hardware Setup Guide: Wi-Fi card setup, antenna geometry, and ESP32 flashing.
• 🔬 Research & Development Document: Zero-cost RF sensing mathematical blueprint.
• 🗺️ Engineering Roadmap: Multi-phase development roadmap.
• 📜 Changelog: Version release notes and features.
• ⚙️ Repository Settings Guide: GitHub topics, tags, metadata, and branch protection.
• 🕵️‍♂️ Audit Report: No-simulation mandate and physical hardware verification.

---

🎓 Citation & Research

If you use WifiVision in your research or product, please cite it:

@software{wifivision2026,
  author = {LaSalle, Kirk and Contributors},
  title = {WifiVision: Hardware-Agnostic Wi-Fi Spatial Intelligence, Contactless Vitals & 3D Pose Engine},
  url = {https://github.com/kirklasalle/WifiVision},
  version = {1.3.0},
  year = {2026}
}

---

📄 License

Distributed under the MIT License. See LICENSE for details.

_{Built with ❤️ for privacy-preserving spatial intelligence by Kirk LaSalle and the WifiVision Community.}