WiFi DensePose

🚀 Key Features

ESP32-S3 Hardware Pipeline (ADR-018)

ESP32-S3 (STA + promiscuous) UDP/5005 Rust aggregator
┌─────────────────────────┐ ──────────> ┌──────────────────┐
│ WiFi CSI callback 20 Hz │ ADR-018 │ Esp32CsiParser │
│ ADR-018 binary frames │ binary │ CsiFrame output │
│ stream_sender (UDP) │ │ presence detect │
└─────────────────────────┘ └──────────────────┘

# 1. Download binaries from GitHub release
# https://github.com/ruvnet/wifi-densepose/releases/tag/v0.1.0-esp32
# 2. Flash to ESP32-S3 (pip install esptool)
python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
 write-flash --flash-mode dio --flash-size 4MB \
 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 esp32-csi-node.bin
# 3. Provision WiFi (no recompile needed)
python scripts/provision.py --port COM7 \
 --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20
# 4. Run aggregator
cargo run -p wifi-densepose-hardware --bin aggregator -- --bind 0.0.0.0:5005 --verbose

🦀 Rust Implementation (v2)

Performance Benchmarks (Validated)

Throughput Metrics

Resource Comparison

cd rust-port/wifi-densepose-rs
cargo build --release
cargo test --workspace
cargo bench --package wifi-densepose-signal

Validation Tests

SOTA Signal Processing (ADR-014)

🚨 WiFi-Mat: Disaster Response Module

Key Capabilities

Use Cases

Quick Example

use wifi_densepose_mat::{DisasterResponse, DisasterConfig, DisasterType, ScanZone, ZoneBounds};
let config = DisasterConfig::builder()
 .disaster_type(DisasterType::Earthquake)
 .sensitivity(0.85)
 .max_depth(5.0)
 .build();
let mut response = DisasterResponse::new(config);
response.initialize_event(location, "Building collapse")?;
response.add_zone(ScanZone::new("North Wing", ZoneBounds::rectangle(0.0, 0.0, 30.0, 20.0)))?;
response.start_scanning().await?;
// Get survivors prioritized by triage status
let immediate = response.survivors_by_triage(TriageStatus::Immediate);
println!("{} survivors require immediate rescue", immediate.len());

Documentation

cd rust-port/wifi-densepose-rs
cargo build --release --package wifi-densepose-mat
cargo test --package wifi-densepose-mat

📋 Table of Contents

🏗️ System Architecture

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ WiFi Router │ │ WiFi Router │ │ WiFi Router │
│ (CSI Source) │ │ (CSI Source) │ │ (CSI Source) │
└─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘
 │ │ │
 └──────────────────────┼──────────────────────┘
 │
 ┌─────────────▼─────────────┐
 │ CSI Data Collector │
 │ (Hardware Interface) │
 └─────────────┬─────────────┘
 │
 ┌─────────────▼─────────────┐
 │ Signal Processor │
 │ (Phase Sanitization) │
 └─────────────┬─────────────┘
 │
 ┌─────────────▼─────────────┐
 │ Neural Network Model │
 │ (DensePose Head) │
 └─────────────┬─────────────┘
 │
 ┌─────────────▼─────────────┐
 │ Person Tracker │
 │ (Multi-Object Tracking) │
 └─────────────┬─────────────┘
 │
 ┌───────────────────────┼───────────────────────┐
 │ │ │
┌─────────▼─────────┐ ┌─────────▼─────────┐ ┌─────────▼─────────┐
│ REST API │ │ WebSocket API │ │ Analytics │
│ (CRUD Operations)│ │ (Real-time Stream)│ │ (Fall Detection) │
└───────────────────┘ └───────────────────┘ └───────────────────┘

Core Components

📦 Installation

Guided Installer (Recommended)

./install.sh

Install Profiles

Non-Interactive Install

# Install a specific profile without prompts
./install.sh --profile rust --yes
# Just run hardware detection (no install)
./install.sh --check-only
# Or use make targets
make install # Interactive
make install-verify # Verification only
make install-python # Python pipeline
make install-rust # Rust pipeline
make install-browser # WASM browser build
make install-docker # Docker deployment
make install-field # Disaster response kit
make install-full # Everything
make check # Hardware check only

From Source (Rust — Primary)

git clone https://github.com/ruvnet/wifi-densepose.git
cd wifi-densepose
# Install Rust pipeline (810x faster than Python)
./install.sh --profile rust --yes
# Or manually:
cd rust-port/wifi-densepose-rs
cargo build --release
cargo test --workspace

From Source (Python)

git clone https://github.com/ruvnet/wifi-densepose.git
cd wifi-densepose
pip install -r requirements.txt
pip install -e .

Using pip (Python only)

pip install wifi-densepose
# With optional dependencies
pip install wifi-densepose[gpu] # For GPU acceleration
pip install wifi-densepose[all] # All optional dependencies

Using Docker

docker pull ruvnet/wifi-densepose:latest
docker run -p 8000:8000 ruvnet/wifi-densepose:latest

System Requirements

🚀 Quick Start

1. Basic Setup

# Install the package (Rust — recommended)
./install.sh --profile rust --yes
# Or Python legacy
pip install wifi-densepose
# Copy example configuration
cp example.env .env
# Edit configuration (set your WiFi interface)
nano .env

2. Start the System

from wifi_densepose import WiFiDensePose
# Initialize with default configuration
system = WiFiDensePose()
# Start pose estimation
system.start()
# Get latest pose data
poses = system.get_latest_poses()
print(f"Detected {len(poses)} persons")
# Stop the system
system.stop()

3. Using the REST API

# Start the API server
wifi-densepose start
# Start with custom configuration
wifi-densepose -c /path/to/config.yaml start
# Start with verbose logging
wifi-densepose -v start
# Check server status
wifi-densepose status

4. Real-time Streaming

import asyncio
import websockets
import json
async def stream_poses():
 uri = "ws://localhost:8000/ws/pose/stream"
 async with websockets.connect(uri) as websocket:
 while True:
 data = await websocket.recv()
 poses = json.loads(data)
 print(f"Received poses: {len(poses['persons'])} persons detected")
# Run the streaming client
asyncio.run(stream_poses())

🖥️ CLI Usage

CLI Installation

# Install WiFi DensePose with CLI
pip install wifi-densepose
# Verify CLI installation
wifi-densepose --help
wifi-densepose version

Basic Commands

wifi-densepose [OPTIONS] COMMAND [ARGS]...
Options:
 -c, --config PATH Path to configuration file
 -v, --verbose Enable verbose logging
 --debug Enable debug mode
 --help Show this message and exit.
Commands:
 config Configuration management commands.
 db Database management commands.
 start Start the WiFi-DensePose API server.
 status Show the status of the WiFi-DensePose API server.
 stop Stop the WiFi-DensePose API server.
 tasks Background task management commands.
 version Show version information.

Server Management

# Start the WiFi-DensePose API server
wifi-densepose start
# Start with custom configuration
wifi-densepose -c /path/to/config.yaml start
# Start with verbose logging
wifi-densepose -v start
# Start with debug mode
wifi-densepose --debug start
# Check server status
wifi-densepose status
# Stop the server
wifi-densepose stop
# Show version information
wifi-densepose version

Configuration Commands

Configuration Management

# Configuration management commands
wifi-densepose config [SUBCOMMAND]
# Examples:
# Show current configuration
wifi-densepose config show
# Validate configuration file
wifi-densepose config validate
# Create default configuration
wifi-densepose config init
# Edit configuration
wifi-densepose config edit

Database Management

# Database management commands
wifi-densepose db [SUBCOMMAND]
# Examples:
# Initialize database
wifi-densepose db init
# Run database migrations
wifi-densepose db migrate
# Check database status
wifi-densepose db status
# Backup database
wifi-densepose db backup
# Restore database
wifi-densepose db restore

Background Tasks

# Background task management commands
wifi-densepose tasks [SUBCOMMAND]
# Examples:
# List running tasks
wifi-densepose tasks list
# Start background tasks
wifi-densepose tasks start
# Stop background tasks
wifi-densepose tasks stop
# Check task status
wifi-densepose tasks status

Command Examples

Complete CLI Reference

# Show help for main command
wifi-densepose --help
# Show help for specific command
wifi-densepose start --help
wifi-densepose config --help
wifi-densepose db --help
# Use global options with commands
wifi-densepose -v status # Verbose status check
wifi-densepose --debug start # Start with debug logging
wifi-densepose -c custom.yaml start # Start with custom config

Common Usage Patterns

# Basic server lifecycle
wifi-densepose start # Start the server
wifi-densepose status # Check if running
wifi-densepose stop # Stop the server
# Configuration management
wifi-densepose config show # View current config
wifi-densepose config validate # Check config validity
# Database operations
wifi-densepose db init # Initialize database
wifi-densepose db migrate # Run migrations
wifi-densepose db status # Check database health
# Task management
wifi-densepose tasks list # List background tasks
wifi-densepose tasks status # Check task status
# Version and help
wifi-densepose version # Show version info
wifi-densepose --help # Show help message

CLI Examples

Complete Setup Workflow

# 1. Check version and help
wifi-densepose version
wifi-densepose --help
# 2. Initialize configuration
wifi-densepose config init
# 3. Initialize database
wifi-densepose db init
# 4. Start the server
wifi-densepose start
# 5. Check status
wifi-densepose status

Development Workflow

# Start with debug logging
wifi-densepose --debug start
# Use custom configuration
wifi-densepose -c dev-config.yaml start
# Check database status
wifi-densepose db status
# Manage background tasks
wifi-densepose tasks start
wifi-densepose tasks list

Production Workflow

# Start with production config
wifi-densepose -c production.yaml start
# Check system status
wifi-densepose status
# Manage database
wifi-densepose db migrate
wifi-densepose db backup
# Monitor tasks
wifi-densepose tasks status

Troubleshooting

# Enable verbose logging
wifi-densepose -v status
# Check configuration
wifi-densepose config validate
# Check database health
wifi-densepose db status
# Restart services
wifi-densepose stop
wifi-densepose start

📚 Documentation

📖 Core Documentation

🚀 Quick Links

📋 API Overview

Key REST Endpoints

# Pose estimation
GET /api/v1/pose/latest # Get latest pose data
GET /api/v1/pose/history # Get historical data
GET /api/v1/pose/zones/{zone_id} # Get zone-specific data
# System management
GET /api/v1/system/status # System health and status
POST /api/v1/system/calibrate # Calibrate environment
GET /api/v1/analytics/summary # Analytics dashboard data

WebSocket Streaming

// Real-time pose data
ws://localhost:8000/ws/pose/stream
// Analytics events (falls, alerts)
ws://localhost:8000/ws/analytics/events
// System status updates
ws://localhost:8000/ws/system/status

Python SDK Quick Example

from wifi_densepose import WiFiDensePoseClient
# Initialize client
client = WiFiDensePoseClient(base_url="http://localhost:8000")
# Get latest poses with confidence filtering
poses = client.get_latest_poses(min_confidence=0.7)
print(f"Detected {len(poses)} persons")
# Get zone occupancy
occupancy = client.get_zone_occupancy("living_room")
print(f"Living room occupancy: {occupancy.person_count}")

🔧 Hardware Setup

Supported Hardware

Recommended Routers

CSI-Capable Devices

Physical Setup

Network Configuration

# Configure WiFi interface for CSI extraction
sudo iwconfig wlan0 mode monitor
sudo iwconfig wlan0 channel 6
# Set up CSI extraction (Intel 5300 example)
echo 0x4101 | sudo tee /sys/kernel/debug/ieee80211/phy0/iwlwifi/iwldvm/debug/monitor_tx_rate

Environment Calibration

from wifi_densepose import Calibrator
# Run environment calibration
calibrator = Calibrator()
calibrator.calibrate_environment(
 duration_minutes=10,
 environment_id="room_001"
)
# Apply calibration
calibrator.apply_calibration()

⚙️ Configuration

Environment Variables

# Application Settings
APP_NAME=WiFi-DensePose API
VERSION=1.0.0
ENVIRONMENT=production # development, staging, production
DEBUG=false
# Server Settings
HOST=0.0.0.0
PORT=8000
WORKERS=4
# Security Settings
SECRET_KEY=your-secure-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=24
# Hardware Settings
WIFI_INTERFACE=wlan0
CSI_BUFFER_SIZE=1000
HARDWARE_POLLING_INTERVAL=0.1
# Pose Estimation Settings
POSE_CONFIDENCE_THRESHOLD=0.7
POSE_PROCESSING_BATCH_SIZE=32
POSE_MAX_PERSONS=10
# Feature Flags
ENABLE_AUTHENTICATION=true
ENABLE_RATE_LIMITING=true
ENABLE_WEBSOCKETS=true
ENABLE_REAL_TIME_PROCESSING=true
ENABLE_HISTORICAL_DATA=true

Domain-Specific Configurations

Healthcare Configuration

config = {
 "domain": "healthcare",
 "detection": {
 "confidence_threshold": 0.8,
 "max_persons": 5,
 "enable_tracking": True
 },
 "analytics": {
 "enable_fall_detection": True,
 "enable_activity_recognition": True,
 "alert_thresholds": {
 "fall_confidence": 0.9,
 "inactivity_timeout": 300
 }
 },
 "privacy": {
 "data_retention_days": 30,
 "anonymize_data": True,
 "enable_encryption": True
 }
}

Fitness Configuration

config = {
 "domain": "fitness",
 "detection": {
 "confidence_threshold": 0.6,
 "max_persons": 20,
 "enable_tracking": True
 },
 "analytics": {
 "enable_activity_recognition": True,
 "enable_form_analysis": True,
 "metrics": ["rep_count", "form_score", "intensity"]
 }
}

Advanced Configuration

from wifi_densepose.config import Settings
# Load custom configuration
settings = Settings(
 pose_model_path="/path/to/custom/model.pth",
 neural_network={
 "batch_size": 64,
 "enable_gpu": True,
 "inference_timeout": 500
 },
 tracking={
 "max_age": 30,
 "min_hits": 3,
 "iou_threshold": 0.3
 }
)

🧪 Testing

Running Tests

# Run all tests
pytest
# Run with coverage report
pytest --cov=wifi_densepose --cov-report=html
# Run specific test categories
pytest tests/unit/ # Unit tests
pytest tests/integration/ # Integration tests
pytest tests/e2e/ # End-to-end tests
pytest tests/performance/ # Performance tests

Test Categories

Unit Tests (95% coverage)

Integration Tests

End-to-End Tests

Performance Tests

Testing Without Hardware

# Verify the full signal processing pipeline (no hardware needed)
./verify
# Run Rust tests (all use real signal processing, no mocks)
cd rust-port/wifi-densepose-rs && cargo test --workspace

Continuous Integration

# .github/workflows/test.yml
name: Test Suite
on: [push, pull_request]
jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v2
 - name: Set up Python
 uses: actions/setup-python@v2
 with:
 python-version: 3.8
 - name: Install dependencies
 run: |
 pip install -r requirements.txt
 pip install -e .
 - name: Run tests
 run: pytest --cov=wifi_densepose --cov-report=xml
 - name: Upload coverage
 uses: codecov/codecov-action@v1

🚀 Deployment

Production Deployment

Using Docker

# Build production image
docker build -t wifi-densepose:latest .
# Run with production configuration
docker run -d \
 --name wifi-densepose \
 -p 8000:8000 \
 -v /path/to/data:/app/data \
 -v /path/to/models:/app/models \
 -e ENVIRONMENT=production \
 -e SECRET_KEY=your-secure-key \
 wifi-densepose:latest

Using Docker Compose

# docker-compose.yml
version: '3.8'
services:
 wifi-densepose:
 image: wifi-densepose:latest
 ports:
 - "8000:8000"
 environment:
 - ENVIRONMENT=production
 - DATABASE_URL=postgresql://user:pass@db:5432/wifi_densepose
 - REDIS_URL=redis://redis:6379/0
 volumes:
 - ./data:/app/data
 - ./models:/app/models
 depends_on:
 - db
 - redis
 db:
 image: postgres:13
 environment:
 POSTGRES_DB: wifi_densepose
 POSTGRES_USER: user
 POSTGRES_PASSWORD: password
 volumes:
 - postgres_data:/var/lib/postgresql/data
 redis:
 image: redis:6-alpine
 volumes:
 - redis_data:/data
volumes:
 postgres_data:
 redis_data:

Kubernetes Deployment

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: wifi-densepose
spec:
 replicas: 3
 selector:
 matchLabels:
 app: wifi-densepose
 template:
 metadata:
 labels:
 app: wifi-densepose
 spec:
 containers:
 - name: wifi-densepose
 image: wifi-densepose:latest
 ports:
 - containerPort: 8000
 env:
 - name: ENVIRONMENT
 value: "production"
 - name: DATABASE_URL
 valueFrom:
 secretKeyRef:
 name: wifi-densepose-secrets
 key: database-url
 resources:
 requests:
 memory: "2Gi"
 cpu: "1000m"
 limits:
 memory: "4Gi"
 cpu: "2000m"

Infrastructure as Code

Terraform (AWS)

# terraform/main.tf
resource "aws_ecs_cluster" "wifi_densepose" {
 name = "wifi-densepose"
}
resource "aws_ecs_service" "wifi_densepose" {
 name = "wifi-densepose"
 cluster = aws_ecs_cluster.wifi_densepose.id
 task_definition = aws_ecs_task_definition.wifi_densepose.arn
 desired_count = 3
 load_balancer {
 target_group_arn = aws_lb_target_group.wifi_densepose.arn
 container_name = "wifi-densepose"
 container_port = 8000
 }
}

Ansible Playbook

# ansible/playbook.yml
- hosts: servers
 become: yes
 tasks:
 - name: Install Docker
 apt:
 name: docker.io
 state: present
 - name: Deploy WiFi DensePose
 docker_container:
 name: wifi-densepose
 image: wifi-densepose:latest
 ports:
 - "8000:8000"
 env:
 ENVIRONMENT: production
 DATABASE_URL: "{{ database_url }}"
 restart_policy: always

Monitoring and Logging

Prometheus Metrics

# monitoring/prometheus.yml
global:
 scrape_interval: 15s
scrape_configs:
 - job_name: 'wifi-densepose'
 static_configs:
 - targets: ['localhost:8000']
 metrics_path: '/metrics'

Grafana Dashboard

{
 "dashboard": {
 "title": "WiFi DensePose Monitoring",
 "panels": [
 {
 "title": "Pose Detection Rate",
 "type": "graph",
 "targets": [
 {
 "expr": "rate(pose_detections_total[5m])"
 }
 ]
 },
 {
 "title": "Processing Latency",
 "type": "graph",
 "targets": [
 {
 "expr": "histogram_quantile(0.95, pose_processing_duration_seconds_bucket)"
 }
 ]
 }
 ]
 }
}

📊 Performance Metrics

Benchmark Results

Latency Performance

Accuracy Metrics

Resource Usage

Scalability

Performance Optimization

Hardware Optimization

# Enable GPU acceleration
config = {
 "neural_network": {
 "enable_gpu": True,
 "batch_size": 64,
 "mixed_precision": True
 },
 "processing": {
 "num_workers": 4,
 "prefetch_factor": 2
 }
}

Software Optimization

# Enable performance optimizations
config = {
 "caching": {
 "enable_redis": True,
 "cache_ttl": 300
 },
 "database": {
 "connection_pool_size": 20,
 "enable_query_cache": True
 }
}

Load Testing

# API load testing with Apache Bench
ab -n 10000 -c 100 http://localhost:8000/api/v1/pose/latest
# WebSocket load testing
python scripts/websocket_load_test.py --connections 1000 --duration 300

🤝 Contributing

Development Setup

# Clone the repository
git clone https://github.com/ruvnet/wifi-densepose.git
cd wifi-densepose
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .
# Install pre-commit hooks
pre-commit install

Code Standards

Contribution Process

Code Review Checklist

Issue Templates

Bug Report

**Describe the bug**
A clear description of the bug.
**To Reproduce**
Steps to reproduce the behavior.
**Expected behavior**
What you expected to happen.
**Environment**
- OS: [e.g., Ubuntu 20.04]
- Python version: [e.g., 3.8.10]
- WiFi DensePose version: [e.g., 1.0.0]

Feature Request

**Feature Description**
A clear description of the feature.
**Use Case**
Describe the use case and benefits.
**Implementation Ideas**
Any ideas on how to implement this feature.

📄 License

MIT License
Copyright (c) 2025 WiFi DensePose Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Changelog

v2.2.0 — 2026年02月28日

v2.1.0 — 2026年02月28日

🙏 Acknowledgments

📞 Support