WiFi CSI Activity Recognition · Vital Signs via WiFi · Through-Wall Pose Estimation · Phase-Coherent Localization · UAV Detection via CSI
5G/mmWave Sensing · BLE Device Tracking · BLE MAC Randomization Bypass · Research-backed Methodologies · Local AI & ML
// crafted for the network security & intelligence communities — funding keeps it maintained
Important
Educational & Research Use Only
This repository is a software research project exploring the theory and algorithmic implementation of defensive counter-measures against passive radio-frequency sensing attacks. All code, diagrams, and documentation are provided strictly for:
- Academic study of published WiFi CSI / mmWave sensing techniques
- Designing and validating privacy-protective counter-measures
- Understanding attack surfaces in order to build better defenses
- Reproducible research aligned with the peer-reviewed literature cited in
docs/REFERENCES.md
No component of this codebase is intended, designed, or suitable for surveillance, harassment, or any offensive application. The project deliberately inverts the sensing pipeline — the goal is to break detection, not enable it. See docs/THREAT_MODEL.md for the full ethical framework and docs/REFERENCES.md for the academic grounding.
- Overview
- Research Context
- Architecture
- Key Features
- Hardware & Technology Stack
- Recommended Hardware & Shopping List
- Project Structure
- Quick Start
- AI / Machine Learning
- Documentation
- Academic References
- Ethical Use & Contributing
Modern WiFi chipsets, mmWave sensors, and software-defined radios can be repurposed — often without physical access or consent — to monitor human activity, extract vital signs, and track precise locations through walls. A growing body of peer-reviewed research demonstrates these capabilities in production hardware.
This project takes the defender's perspective:
- Deconstruct published attack pipelines at the algorithmic level.
- Develop software counter-measures that disrupt feature extraction and deep-learning stages on which attacks depend.
- Coordinate distributed defensive nodes (ESP32 + RTL-SDR V4) for real-time, network-wide threat detection and response.
The result is an open, reproducible research platform for privacy engineers, security researchers, and wireless-systems academics.
Pictured: Screenshot of the device spatial mapping user interface shown upon initial setup
The sensing attacks addressed here are real, published, and peer-reviewed:
| Attack Vector | Representative Work | Claimed Accuracy |
|---|---|---|
| WiFi CSI Activity Recognition | SenseFi (ACM MobiCom 2024) | 97.5% |
| Vital Signs via WiFi | Nature Scientific Reports 2024 | ±1–2 bpm heart rate |
| Through-Wall Pose Estimation | WiFi DensePose (Meta AI, 2023) | 17-keypoint skeleton |
| Phase-Coherent Localization | ESPARGOS (Univ. Stuttgart, 2026) | cm-scale precision |
| UAV Detection via CSI | IEEE Trans. Veh. Tech. 2018 | >90% detection |
| 5G/mmWave Sensing | IEEE 802.11bf / OCUDU NextG | clinical-grade |
| BLE Device Tracking | IEEE S&P 2022 / PoPETs 2019 | MAC identity re-link |
| BLE MAC Randomization Bypass | ACM TOPS 2025 / USENIX 2024 | Physical-layer fingerprint |
Understanding these attack surfaces in depth is a prerequisite for building effective defenses — which is precisely what this codebase does.
┌──────────────────────────────────────────────────────────────────┐
│ DISTRIBUTED DEFENSIVE NETWORK │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ ESP32-S3 │ │ ESP32-S3 │ │ RTL-SDR V4 │ │
│ │ CSI Node │ │ CSI Node │ │ Spectrum Node │ │
│ │ (WiFi mon) │ │ (obfusc.) │ │ 24 MHz–1.7 GHz │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
│ │ │ │ │
│ └─────────────────┴─────────────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ MQTT Broker │ (Eclipse Mosquitto) │
│ └──────┬──────┘ │
│ │ │
│ ┌────────────▼────────────┐ │
│ │ Threat Aggregator │ │
│ │ + Scoring Engine │ │
│ └───────────────┬─────────┘ │
│ │ │
│ ┌────────────────────────┼─────────────────────┐ │
│ │ │ │ │
│ ┌──▼───────┐ ┌──────▼──────┐ ┌──────▼──────┐ │
│ │ CSI/WiFi │ │ mmWave/5G │ │ UAV / RF │ │
│ │ Defender │ │ Defender │ │ Detector │ │
│ └──────────┘ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────────────┘
See docs/ARCHITECTURE.md for complete attack-flow diagrams and defense pipelines.
- CSI Extraction Detection — identify ESP-CSI / ESPARGOS probing attempts via statistical anomaly analysis of WiFi frame patterns
- RF Anomaly Detection — wideband spectrum scanning (24 MHz–1.7 GHz) with an RTL-SDR receiver to flag suspicious emitters
- UAV / Drone Detection — classify airborne threats from rotor-blade RF signatures; detection range is estimated per-event from a free-space path-loss model (
estimated_range_m) rather than a fixed maximum - BLE Device Tracking Detection — passive monitoring of Bluetooth Low Energy traffic to detect device tracking risks; AoA/AoD and CFO-based fingerprinting require IQ/CTE-capable capture data, while GATT entropy analysis and MAC randomization audits can be performed from higher-level observations (IEEE S&P 2022, PoPETs 2019, USENIX 2024)
Implemented in src/core/detection/activity_classifier.py (no camera required):
- Human Activity Classification — lightweight, real-time feature-based classifier (threshold + feature matching) over WiFi CSI amplitude/phase time series for 10 activities (standing, walking, sitting, lying down, falling, waving, running, jumping, crouching, empty room); architecture is inspired by CNN+GRU pipelines (e.g., SenseFi) but this repo currently runs without a trained neural model.
- 17-Keypoint COCO Skeleton Estimation — pose regression head outputs full-body joint positions (nose through ankles) with per-keypoint confidence scores and estimated depth, streamed live via
GET /api/poses - DensePose UV Surface Mapping — surface head predicts body-part index and (U, V) coordinates for each keypoint, enabling volumetric body surface reconstruction from WiFi signal alone (inspired by DensePose From WiFi, 2022)
- Multi-Person Support — person-ID tracking across frames with configurable confidence thresholds
- CSI Coherence Disruption — randomize amplitude and phase per subcarrier to make ML feature extraction fail
- Vital-Signs Masking — overlay synthetic frequency components to break breathing/heart-rate extraction
- Phase Decorrelation — destroy phase relationships across antennas, preventing TDOA/AoA localization
- Adversarial Perturbation — learned noise patterns that specifically target deep-learning sensing architectures
- MQTT Threat Bus — low-latency threat-intelligence sharing across defensive nodes
- Synchronized Obfuscation — facility-wide coordinated defensive activation
- Forensic Logging — attacker hardware fingerprinting, threat timelines, and RF evidence capture
- Multi-Domain Correlation — fuse WiFi CSI + mmWave + RF spectrum threat scores into a unified picture
- Sensitive signal processing remains on-device rather than streaming raw CSI or RF data off-network
- Aggregated summary-only analytics can be exposed opportunistically without raw-signal export
| Layer | Component | Role |
|---|---|---|
| Sensor | ESP32-S3 / ESP32 family (1–2 antenna) | WiFi CSI monitor / obfuscation node |
| Sensor | RTL-SDR V4 or RTL2832U-based SDR (24 MHz–1.7 GHz) | Wideband RF spectrum analysis |
| Sensor | ESPARGOS array | Phase-coherent multi-antenna research |
| Sensor | USB Bluetooth 5.0 dongle (e.g., ASUS USB-BT500) | BLE advertisement sniffing, AoA/AoD direction finding, device fingerprinting |
| Compute | Python 3.11 + NumPy/SciPy | Signal processing pipeline |
| ML | PyTorch / ONNX Runtime (optional) | Neural inference for activity classification & pose estimation when a checkpoint is registered via ModelManager; heuristic fallback runs without either |
| API | FastAPI + WebSocket | Real-time streaming dashboard |
| Messaging | Eclipse Mosquitto (MQTT) | Distributed node coordination |
| Cache | Redis (optional) | Provisioned in docker-compose.yml for future CSI frame buffering across processes; not yet wired into the Python pipeline |
| Container | Docker Compose | Reproducible deployment |
| Frontend | Three.js + WebSocket (no build step) | Live 3-D threat visualization |
This repository is authentic to the current implementation: the codebase expects ESP32-family devices for CSI ingestion and RTL-SDR-based receivers for spectrum analysis. The hardware selection below reflects those actual integration points rather than a generic list of every possible sensor.
Amazon links in this section may be affiliate links. If you use them to make a purchase, the project may receive a small commission at no extra cost to you.
| Use case | Recommendation | Why it matches the repo | Amazon |
|---|---|---|---|
| Required RF receiver | RTL-SDR V4 | Covers the wideband spectrum pipeline used throughout the project | RTL-SDR |
| Required WiFi CSI node | ESP32 / ESP32-S3 development board | Matches the CSI ingestion and distributed node architecture in this repo | ESP32 chips |
| Required BLE sensor | USB Bluetooth 5.0 dongle (ASUS USB-BT500) | Powers the ble_tracker module — BLE advertisement sniffing, AoA/AoD direction finding, CFO fingerprinting, and MAC randomization audit |
ASUS USB-BT500 |
| Recommended protection | ESP32 enclosure / project case | Useful for lab or field deployments and stable mounting | ESP32 cases |
| Recommended programming | CP2102 / CH340 USB-TTL serial adapter | Helpful for flashing ESP32 boards and serial debugging | USB-TTL serial adapter |
| Optional range boost | U.FL/SMA external antenna kit | Improves signal quality for CSI capture and antenna placement | U.FL/SMA antenna kit |
| Optional RF capture | SDR dipole / antenna kit | Helpful for wideband sweeps and drone and emitter monitoring | SDR antenna kit |
For a minimal working setup, start with 1–2 ESP32-S3 devices and 1 RTL-SDR V4 dongle. For a larger defensive mesh, add more ESP32 nodes to the same MQTT-backed architecture described in
docs/ARCHITECTURE.md.
.
├── src/
│ ├── api/ # FastAPI server + WebSocket endpoints
│ ├── core/
│ │ ├── defense/ # CSI obfuscation, null steering, RIS controller, ISAC security, shielding advisor
│ │ ├── detection/ # UAV detector, DSP engine, activity classifier + pose estimator,
│ │ │ # BLE tracker, LoRa detector, passive radar, GNSS monitor,
│ │ │ # UWB monitor, EM side-channel, ISAC threat, RF dosimetry
│ │ ├── fusion/ # mmWave ISAC, distributed coordinator
│ │ ├── ml/ # Foundation model adapter, model manager (PyTorch)
│ │ ├── positioning/ # CSI engine, CSI pipeline, Kalman tracker, Nexmon parser
│ │ └── scene/ # Scene graph and sensor correlation
│ └── satellite/ # AIS, Copernicus, EarthData, geo-fusion
├── frontend/ # Browser-based live threat dashboard
├── infra/
│ └── mosquitto.conf # MQTT broker configuration
├── assets/
│ ├── header.svg # Repository header graphic
│ └── donate/ # Sponsor / donation button SVGs
├── docs/
│ ├── 3D_SPATIAL_MAPPING.md # 3-D sensor-fusion reference
│ ├── ADVANSENSE.md # Internal research integration notes
│ ├── ARCHITECTURE.md # Attack flow diagrams & defense pipelines
│ ├── CLAUDE.md # Guidance for Claude Code when working on this project
│ ├── NETWORKED_DEFENSE.md # Distributed node deployment guide
│ ├── REFERENCES.md # Full academic bibliography
│ ├── SETUP.md # Environment & hardware setup
│ ├── THREAT_MODEL.md # Ethical framework & attack scenario analysis
│ ├── UAV_DETECTION.md # RTL-SDR V4 & drone detection guide
│ ├── nze-whitepapers/ # NZE research source CSVs & whitepaper draft
│ ├── skills-for-agents/ # Skill routing guides for coding agents
│ └── skills-from-agents/ # Agent environment & capability documentation
├── .env.example # Runtime environment template
├── CHANGELOG.md # Version history
├── config.py # Central configuration
├── Dockerfile # Container build definition
├── docker-compose.yml # One-command deployment
├── LICENSE # Open-source license
├── requirements.txt # Python dependencies
├── README.md # Project overview & quick start
└── tests/ # Pytest coverage (CSI pipeline, DSP engine, ML pipeline, coordinator, device gateway, RF/IQ endpoints)
- Python ≥ 3.11
- Docker & Docker Compose (recommended)
- 1× RTL-SDR V4 or RTL2832U-based SDR receiver (recommended for RF sensing nodes)
- 1–2× ESP32 or ESP32-S3 development boards (recommended for CSI monitor nodes)
- 1× USB Bluetooth 5.0 dongle (required for BLE tracking features; e.g., ASUS USB-BT500)
- Optional: USB-TTL serial adapter, external WiFi antenna, and enclosure
git clone https://github.com/VRIL-LABS/vril-sense.git
cd vril-sense
cp .env.example .env # edit as needed
docker compose up -dThe REST API and live dashboard will be available at http://localhost:8000.
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
uvicorn src.api.server:app --reloadSee docs/SETUP.md for full hardware wiring, ESP32 flashing, RTL-SDR installation, and MQTT broker configuration.
The platform ships with two operating modes that switch automatically based on whether a model checkpoint is registered:
| Mode | When it activates | What runs |
|---|---|---|
| Heuristic (default) | No model checkpoint registered/present | Pure NumPy/SciPy — statistical feature matching (threshold + Gaussian scoring) for activity classification and a kinematic body model for pose estimation. No GPU, no PyTorch required. |
| Neural model | A checkpoint file is registered and loaded via ModelManager (or POST /api/ml/register) |
PyTorch (.pt / TorchScript) or ONNX Runtime (.onnx) inference on a user-supplied model. The default activity/pose pipeline in WiFiSensingEngine automatically delegates to the neural model — no other code changes needed. |
PyTorch is not installed by default. The
requirements.txtlists it as a commented-out optional dependency. Everything works out of the box without it.
# PyTorch — CPU-only (lightest footprint)
pip install torch --index-url https://download.pytorch.org/whl/cpu
# PyTorch — GPU (CUDA 12.1)
pip install torch --index-url https://download.pytorch.org/whl/cu121
# ONNX Runtime — CPU (recommended for exported models)
pip install onnxruntime
# ONNX Runtime — GPU
pip install onnxruntime-gpuThe ModelManager in src/core/ml/model_manager.py is the single entry point for loading and running any neural model. It supports:
- TorchScript (
.pt) — exported withtorch.jit.save() - Full PyTorch module (
.ptpickle) — saved withtorch.save() - ONNX (
.onnx) — framework-agnostic, works without PyTorch
The repo does not ship pre-trained weights. You can:
- Download a compatible checkpoint from the SenseFi benchmark (activity recognition, PyTorch).
- Export any compatible HAR or pose model to ONNX via
torch.onnx.export(). - Train your own model — see the SenseFi or MoWA repositories for training pipelines that produce compatible checkpoint formats.
from src.core.ml.model_manager import ModelManager, ModelConfig
mm = ModelManager()
mm.register_model(ModelConfig(
model_id="my-har-model",
model_type="csi_har", # "csi_har" | "csi_pose" | "rf_classify" | "foundation"
checkpoint_path="/path/to/model.pt", # or model.onnx
framework="pytorch", # "pytorch" | "onnx"
input_shape=(1, 100, 52), # (batch, time_steps, subcarriers)
output_classes=10, # number of activity labels
device="cpu", # "cpu" | "cuda"
description="SenseFi HAR CNN-GRU",
))
# Load weights into memory (lazy — also triggered automatically on first predict())
mm.load_model("my-har-model")
# Run inference
import numpy as np
csi_window = np.random.rand(1, 100, 52).astype(np.float32) # replace with real data
predictions = mm.predict("my-har-model", csi_window)
print(predictions) # shape: (1, num_classes) — class probabilitiesfor info in mm.list_models():
print(info)
# {'model_id': 'my-har-model', 'type': 'csi_har', 'framework': 'pytorch',
# 'loaded': True, 'inference_count': 1, 'avg_inference_ms': 4.2, ...}You can also register a model at runtime without writing Python code. The
server's WiFiSensingEngine shares the same ModelManager instance, so
registering via the API immediately activates neural inference:
curl -X POST http://localhost:8000/api/ml/register \
-H "Content-Type: application/json" \
-d '{
"model_id": "my-har-model",
"model_type": "csi_har",
"checkpoint_path": "/path/to/model.onnx",
"framework": "onnx",
"input_shape": [1, 100, 52],
"output_classes": 10
}'
# Check registered models
curl http://localhost:8000/api/ml/modelsAll models receive a float32 NumPy array. The canonical CSI input shape used throughout this codebase is:
(batch_size, time_steps, num_subcarriers)
└─ batch_size: 1 (single inference) or N
└─ time_steps: 100 frames (configurable via CSIFeatureExtractor.window_size)
└─ num_subcarriers: 52 (standard 802.11n/ac, configurable)
For both ONNX and PyTorch models the batch dimension is optional — the ModelManager will automatically add it if the input is 1-D or 2-D (i.e., missing the batch axis). If you already pass a 3-D array with a batch dimension it is used as-is.
src/core/ml/foundation_adapter.py registers four research foundation models that are not trained by this repo but can be dropped in as .pt / .onnx checkpoints when available:
| Model ID | Source | Task |
|---|---|---|
sensefi-har |
SenseFi (Patterns 2023) | Activity recognition (98.11%) |
am-fm |
AM-FM (arXiv 2026) | Multi-task ambient intelligence |
x-fi |
X-Fi (ICLR 2025) | Cross-modal sensing fusion |
lwm |
Large Wireless Model (arXiv 2024) | Channel estimation |
from src.core.ml.foundation_adapter import FoundationModelAdapter
adapter = FoundationModelAdapter()
# Load a checkpoint for a registered model ID using the public API
adapter.load_model("sensefi-har", "/path/to/sensefi_checkpoint.pt")
# Zero-shot activity recognition — uses a loaded neural model when available,
# otherwise falls back to feature-based zero-shot classification
result = adapter.zero_shot_har(csi_features_dict)
print(result) # {'activity': 'walking', 'confidence': 0.87, 'method': 'neural', ...}| Document | Description |
|---|---|
docs/ARCHITECTURE.md |
End-to-end attack and defense flow diagrams |
docs/THREAT_MODEL.md |
Ethical framework, attack scenarios, and scope |
docs/NETWORKED_DEFENSE.md |
Distributed node deployment and MQTT protocol |
docs/UAV_DETECTION.md |
RTL-SDR V4 drone detection pipeline |
docs/SETUP.md |
Hardware setup and environment configuration |
docs/REFERENCES.md |
Complete academic bibliography |
docs/ADVANSENSE.md |
Research integration notes |
docs/3D_SPATIAL_MAPPING.md |
3-D sensor-fusion reference |
This project is grounded in peer-reviewed research. A selection of key works:
- SenseFi — Yang et al., "SenseFi: A Library and Benchmark on Deep-Learning-Empowered WiFi Human Sensing", ACM MobiCom 2024.
- WiFi DensePose — Li et al., "Wifi-Based Human Pose Estimation Revisited", IEEE CVPR 2023.
- DensePose From WiFi — Geng et al., "DensePose From WiFi", arXiv 2022 — CSI-to-UV body surface mapping without a camera.
- ESPARGOS — Stephan et al., "ESPARGOS: An Ultra Low-Cost, Realtime-Capable Multi-Antenna WiFi Channel Sounder", Univ. Stuttgart, 2026.
- UAV CSI Detection — Ezuma et al., "Unmanned Aerial Vehicle Detection based on Channel State Information", IEEE Trans. Veh. Tech. 2018.
- BLE Location Tracking — Becker et al., "Evaluating Physical-Layer BLE Location Tracking Attacks on Mobile Devices", IEEE S&P 2022.
- BLE MAC Randomization — Martin et al., "Tracking Anonymized Bluetooth Devices", PoPETs 2019; Zuniga et al., "Breaking BLE MAC Randomization", ACM TOPS 2025.
- CSI-Bench — AI-IoT Sensing Group, 2025. https://ai-iot-sensing.github.io
- IEEE 802.11bf — IEEE standard for WLAN sensing.
- Halperin et al. — "Tool release: Gathering 802.11n traces with channel state information", ACM SIGCOMM CCR 2011.
See docs/REFERENCES.md for the complete bibliography of papers, datasets, and open-source tools.
This codebase exists to protect privacy, not violate it. Every algorithm here is oriented toward defeating sensing — not enabling it. Contributions that add offensive sensing capability, target real individuals, or circumvent legal protections will not be accepted.
If you discover a component that could be misused in ways not addressed by the current threat model, please open a GitHub Issue labeled ethics-review before submitting a pull request.
Pull requests are welcome for:
- Improved defense algorithms and effectiveness benchmarks
- Additional attack-model coverage (new datasets, architectures)
- Hardware support (new ESP32 variants, SDR dongles)
- Documentation and test coverage
Please read docs/THREAT_MODEL.md before contributing to ensure your changes align with the project's defensive mission.
An educational application for privacy engineers, wireless-systems researchers, intelligence specialists, and academic network security communities.
Copyright (c) 2026 VLABS, LLC. All rights reserved.
VRIL LABS Open Source License v1.0 — https://vril
71D1
.li/license.