WiFi-Radar is a Python research system for WiFi-based human pose estimation, tracking, fall detection, gait analytics, and headless monitoring. It consumes Channel State Information from commodity WiFi hardware or the built-in simulation pipeline, transforms it into learned embeddings, and emits 17-keypoint 3-D pose outputs in real time.

WiFi-Radar is a camera-free sensing system that uses normal WiFi signal reflections to infer human movement. Instead of images, it reads CSI (Channel State Information), which captures how radio waves change when people move, stand, walk, or fall in a room. That means the system can monitor activity without recording visual identity data.

At runtime, the pipeline works in five steps:

1. Collect CSI frames from a router or simulator.
2. Clean and normalize amplitude and phase signals.
3. Encode temporal signal patterns into pose features.
4. Decode features into 3-D human keypoints and stable person IDs.
5. Run behavior modules to produce fall, gait, anomaly, and activity outputs.

What the system finds in practice:

• Who is present and where: multi-person tracking with stable IDs.
• How each person is moving: stationary, walking, transition, high-motion.
• Whether motion resembles a fall pattern: state-machine and hybrid fall risk.
• How gait is changing over time: cadence, stride proxy, symmetry, speed.
• Whether behavior is unusual: rolling anomaly detection on gait trends.

This repository is designed for readable, explainable behavior analytics. The algorithms were selected so operators can inspect why a decision was made, tune thresholds per environment, and deploy on resource-constrained edge hardware.

This repository is aimed at researchers, embedded/edge developers, and privacy-first sensing prototypes that need room-scale awareness without cameras.

The images below are repository hosted visuals that demonstrate what the system looks like during runtime. They are intentionally placed in docs/images/ so they render correctly on GitHub, in forks, and in pull request previews. You can replace these SVG assets with real screenshots from your environment while keeping the same file names.

This view represents spatial motion energy around the antenna array. It helps explain where strong reflections are coming from and gives operators an immediate sense of movement intensity in the monitored room.

This panel style mirrors the live monitor experience, where 3-D skeleton estimation, confidence trends, and CSI traces are observed together to validate model health in real time.

This event-centric view demonstrates how fall and gait signals are surfaced as actionable timeline events rather than raw numerical output.

This point-cloud style visual approximates what WiFi-radar reflections and tracked keypoints look like in room coordinates. It is useful for communicating the distinction between raw RF reflection clusters and final pose estimates.

This chart illustrates typical CSI amplitude and phase trajectories over time, which are the core signals used by tracking, gait, anomaly, and fusion modules.

• Overview
• What WiFi-Radar Is, How It Works, and What It Finds
• Visual Gallery
• Key Features
• Architecture Overview
• Algorithms and Formula Summary
• Research Background
• Technology Stack
• Requirements
• Quick Start
• Usage
• Multi-Person Tracking
• Fall Detection
• Gait Analysis
• Gait Anomaly Detection
• Hybrid Activity Fusion
• REST API and Headless Mode
• Transfer Learning on Real CSI
• ONNX Export
• TensorRT Deployment
• Docker Deployment
• Project Structure
• Development
• Roadmap
• Contributing
• License

flowchart TD
    A[WiFi Router or Simulator] --> B[CSICollector]
    B --> C[SignalProcessor]
    C --> D[DualBranchEncoder]
    D --> E[PoseEstimator]
    E --> F[MultiPersonTracker]
    F --> G[FallDetector]
    F --> H[GaitAnalyzer]
    H --> I[GaitAnomalyDetector]
    F --> J[Dashboard]
    F --> K[REST API]
    J --> L[RTMPStreamer]

The runtime pipeline is organised around a single orchestration entry point in main.py. CSI is collected, denoised, encoded, decoded into pose keypoints, and then routed into tracking, fall analysis, gait analytics, optional anomaly flagging, dashboard visualisation, RTMP streaming, and the optional REST API.

This section gives an at-a-glance technical summary of the core algorithms used in the behavior modules. The project favors methods that are easy to interpret, easy to tune in live deployments, and computationally efficient for edge systems. For each module, the chosen approach is paired with the primary equation and a short rationale versus common alternatives.

WiFi-Radar builds on the research thread around RF sensing, CSI-based human activity understanding, and privacy-preserving pose estimation.

Those newer results point in a consistent direction: hybrid, layout-aware, and lightweight WiFi sensing pipelines generalise better in real deployments. That is why this repository now emphasizes:

• live CSI validation and replay,
• hybrid CSI plus pose fusion,
• stronger headless and edge deployment paths.

For the longer bibliography and notes, see docs/reference.md and docs/recent_research_2026.md.

• Python 3.9 – 3.11 (Docker image uses python:3.11-slim)
• Docker + Docker Compose (optional — for the full stack deployment)
• FFmpeg on the host system (for RTMP push without Docker)
• CUDA-capable GPU recommended; CPU-only works fine in simulation

• 802.11n/ac access point with CSI extraction firmware
  • Atheros routers running OpenWrt + ath9k CSI patch
  • Intel 5300 NIC with linux-80211n-csitool
  • 3×3 MIMO configuration (3 TX × 3 RX antennas)
• Linux host with a compatible wireless adapter

Tip: Start with --simulation — no router, no GPU needed.

# 1. Clone
git clone https://github.com/hkevin01/wifi-radar.git
cd wifi-radar

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 3. Install runtime dependencies
pip install -r requirements.txt

# 4. Install the package in editable mode (recommended with the src layout)
pip install -e .

# 5. (Optional) Train simulation-baseline weights
python scripts/train_simulation_baseline.py

# 6. Run the dashboard pipeline
python main.py --simulation

docker compose -f docker/docker-compose.yml up --build

HLS stream: http://localhost:8080/hls/wifi_radar.m3u8

python main.py --simulation
python main.py --simulation --num-people 2 --api --headless
python main.py --router-ip 192.168.1.1 --rtmp-url rtmp://localhost/live/wifi_radar

# Simulation with two virtual people
python main.py --simulation --num-people 2

# Headless embedded mode with REST API only
python main.py --simulation --api --api-port 8081 --headless

# Export ONNX models for edge deployment
python main.py --export-onnx --weights weights/simulation_baseline.pth

# Start the full dashboard + RTMP pipeline
python main.py --simulation --rtmp-url rtmp://localhost/live/wifi_radar

# ~/.wifi_radar/config.yaml  (also editable live from the Configuration tab)
router:
  ip: <YOUR_ROUTER_IP>
  port: 5500
  interface: wlan0
  csi_format: atheros        # "atheros" | "intel"

system:
  simulation_mode: true
  debug: false
  max_people: 4
  confidence_threshold: 0.30
  data_dir: ~/.wifi_radar/data

dashboard:
  port: 8050
  update_interval_ms: 100
  max_history: 100

streaming:
  rtmp_url: rtmp://localhost/live/wifi_radar
  fps: 30
  bitrate: "1000k"

fall_detection:
  enabled: true
  velocity_threshold: -0.20   # normalised units / second  (negative = downward)
  angle_threshold_deg: 40.0   # body-from-vertical angle to trigger possible-fall
  alert_timeout_s: 5.0        # seconds without recovery before escalating to ALERT

A simulation-baseline checkpoint can be generated in ~2 minutes on CPU:

python scripts/train_simulation_baseline.py
# → writes weights/simulation_baseline.pth

Advanced options:

python scripts/train_simulation_baseline.py \
  --epochs 200 \
  --n-samples 20000 \
  --batch-size 128 \
  --lr 5e-4 \
  --output-dir weights

main.py loads weights/simulation_baseline.pth automatically on startup if it exists.

The runtime maintains stable person identities across frames so the monitoring stack can follow multiple occupants and associate alerts with the correct person. This is critical because every downstream module is person-scoped. If identity switches occur, the fall detector, gait history, and anomaly history become mixed across people and produce incorrect alerts.

The tracker uses a greedy centroid matching policy between frame $t-1$ and frame $t$. For each current detection centroid $c_t^{(i)}$, the nearest previous centroid is selected under a match distance threshold:

$$ j^* = \arg\min_j ||c_t^{(i)} - c_{t-1}^{(j)}||_2 $$

Only matches that satisfy $||c_t^{(i)} - c_{t-1}^{(j^*)}||2 < d{max}$ are accepted. Unmatched tracks age out, and unmatched detections create new IDs.

flowchart LR
  A[Detections at frame t] --> B[Compute centroids]
  B --> C[Nearest match to active tracks]
  C --> D{Distance < d_max?}
  D -->|Yes| E[Assign existing ID]
  D -->|No| F[Create new ID]
  E --> G[Update track state]
  F --> G
  G --> H[Retire stale tracks]

Falls are detected from motion, posture change, and recovery state, then surfaced in both the dashboard and REST API event stream. The detector is a finite state machine (FSM), which was chosen because it is interpretable and easy to calibrate for different environments.

The detector combines three criteria:

$$ v_z < \tau_v, \quad \theta > \tau_\theta, \quad \frac{\Delta h}{h_0} > \tau_h $$

• $v_z$ is vertical centroid velocity.
• $\theta$ is torso angle from vertical.
• $\Delta h/h_0$ is normalized height drop from the standing baseline.

stateDiagram-v2
  [*] --> NORMAL
  NORMAL --> POSSIBLE_FALL : vz < tau_v and theta > tau_theta
  POSSIBLE_FALL --> FALL_DETECTED : height drop > tau_h
  POSSIBLE_FALL --> NORMAL : upright recovery
  FALL_DETECTED --> ALERT : timeout without recovery
  FALL_DETECTED --> NORMAL : recovery observed
  ALERT --> NORMAL : reset or recovery

The system estimates cadence, stride, symmetry, and walking-speed proxies from the rolling pose stream for continuous mobility monitoring. It uses ankle trajectory minima as step events because foot strike naturally appears as a local minimum in ankle height.

Cadence is computed as:

$$ ext{cadence}_{spm} = \frac{N_{steps}}{\Delta t} \times 60 $$

Symmetry is computed as a ratio between left and right step intervals:

$$ ext{symmetry} = \frac{\overline{T}_{left}}{\overline{T}_{right}} $$

Unusual gait changes are flagged using rolling statistics and lightweight outlier detection to provide an early warning signal. The detector combines robust z-score checks with an optional IsolationForest model for multi-feature anomalies.

For each gait feature $x_k$:

$$ z_k = \frac{x_k - \mu_k}{\sigma_k + \epsilon} $$

If $|z_k| &gt; z_{thr}$ for key metrics, an anomaly reason is recorded. IsolationForest adds a multivariate perspective for gradual combined drifts that single thresholds may miss.

A recent addition combines CSI motion evidence, pose confidence, and gait signals into a more robust live activity estimate for walking, stationary, high-motion, transition, and possible-fall states. This module improves stability when one modality briefly drops in quality.

Motion is scored across multiple windows and fused with weighted coefficients:

$$ s = \sum_{w \in W} \alpha_w m_w, \qquad \sum_{w \in W} \alpha_w = 1 $$

Final risk is produced from fused motion, pose reliability, gait context, and geometry factor:

$$ r = f(s, p, g, q) $$

where $p$ is pose reliability, $g$ is gait context, and $q$ is layout quality metadata.

flowchart TD
  A[CSI amplitude and phase deltas] --> B[Windowed motion scores]
  C[Pose confidence] --> D[Pose reliability]
  E[Gait metrics] --> F[Gait context score]
  G[Layout metadata] --> H[Geometry scaling]
  B --> I[Fusion heuristic]
  D --> I
  F --> I
  H --> I
  I --> J[Activity label]
  I --> K[Fall risk]

WiFi-Radar can now run without the dashboard for embedded or service-style integrations. In headless mode, the processing pipeline continues to ingest CSI, run inference, and publish events and metrics to FastAPI. This pattern is useful for integrations such as smart-home controllers, backend analytics pipelines, and edge gateways where a browser dashboard is not required.

sequenceDiagram
    participant User
    participant App as main.py
    participant API as FastAPI
    participant Pipeline as Pose Pipeline
    User->>App: start with --api --headless
    App->>Pipeline: process CSI frames
    Pipeline->>API: publish status, events, gait metrics
    User->>API: GET /status
    API-->>User: JSON health and state snapshot

Example:

python main.py --simulation --api --headless
curl http://localhost:8081/health

For real-world adaptation, the repository now includes a transfer-learning workflow that fine-tunes the simulation baseline on NPZ datasets containing:

• amplitude
• phase
• keypoints
• optional confidence

python scripts/train_transfer_learning.py data/real_world/*.npz \
  --weights weights/simulation_baseline.pth \
  --epochs 40 \
  --output weights/realworld_transfer.pth

The script starts with the simulation checkpoint, freezes the encoder for an initial warm-up phase, then unfreezes the backbone for full fine-tuning.

Export both models for edge deployment with a single command:

# Export (requires onnx + onnxruntime)
python scripts/export_onnx.py --weights weights/simulation_baseline.pth

# Validates with onnxruntime automatically (max diff < 1e-4)
# → weights/encoder.onnx
# → weights/pose_estimator.onnx

Or via the main entry point:

python main.py --export-onnx --weights weights/simulation_baseline.pth

The exported models use opset 17 and include dynamic batch axes, making them suitable for Jetson Nano, Raspberry Pi 4 with ONNX Runtime, or any ONNX-compatible inference engine.

import onnxruntime as ort
import numpy as np

sess = ort.InferenceSession("weights/encoder.onnx", providers=["CPUExecutionProvider"])
features = sess.run(["features"], {"amplitude": amp_np, "phase": phase_np})[0]

For Jetson-class hardware, WiFi-Radar now includes a helper script that builds TensorRT engine plans from the exported ONNX models using trtexec.

python scripts/export_tensorrt.py \
  --precision fp16 \
  --output-dir weights/tensorrt

This path is best suited to Jetson Nano / Xavier / Orin systems where the TensorRT runtime is already installed.

The full stack (WiFi-Radar + nginx-rtmp RTMP server) runs with one command:

docker compose -f docker/docker-compose.yml up --build

Services:

Watch the stream in a browser:

http://localhost:8080/hls/wifi_radar.m3u8

Check nginx-rtmp stats:

http://localhost:8080/stat

Weights and config are persisted in named Docker volumes (wifi_radar_weights, wifi_radar_config).

The Dash dashboard at http://localhost:8050 has three tabs:

• Real-time 3-D skeleton (Plotly Scatter3d)
• Confidence history and people-count chart
• CSI amplitude + phase signal (TX0·RX0)
• System status indicator

• Fall alert feed with severity badge and timestamp
• Gait metrics table (cadence, stride, symmetry, speed, step count)
• Updates every 2 seconds

• Live-editable settings: router IP, simulation toggle, confidence threshold, max people, RTMP URL, stream FPS, fall-detection thresholds
• Save writes ~/.wifi_radar/config.yaml and notifies the running system
• No restart required for most settings

wifi-radar/
├── main.py
├── src/
│   └── wifi_radar/
│       ├── analysis/
│       │   ├── fall_detector.py
│       │   ├── gait_analyzer.py
│       │   └── gait_anomaly_detector.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── app.py
│       ├── data/
│       │   └── csi_collector.py
│       ├── models/
│       │   ├── encoder.py
│       │   ├── multi_person_tracker.py
│       │   └── pose_estimator.py
│       ├── processing/
│       │   └── signal_processor.py
│       ├── streaming/
│       │   └── rtmp_streamer.py
│       ├── utils/
│       │   ├── code_quality.py
│       │   └── model_io.py
│       └── visualization/
│           ├── dashboard.py
│           └── house_visualizer.py
├── scripts/
│   ├── export_onnx.py
│   ├── export_tensorrt.py
│   ├── train_simulation_baseline.py
│   └── train_transfer_learning.py
├── tests/
│   ├── test_api.py
│   ├── test_csi_parser.py
│   └── test_gait_anomaly_detector.py
├── docker/
├── docs/
├── requirements.txt
├── requirements-dev.txt
├── pyproject.toml
└── setup.cfg

For deeper implementation notes and technical reference material, use docs/system_overview.md and docs/reference.md.

# Install runtime + dev tooling
pip install -r requirements.txt
pip install -r requirements-dev.txt
pip install -e .

# Install pre-commit hooks
pre-commit install

# Lint and format
./scripts/check_code.sh
black . && isort .

# Focused tests
pytest tests/ -v

# Coverage report
pytest --cov=src/wifi_radar --cov-report=term-missing

# Train the simulation baseline
python scripts/train_simulation_baseline.py

# Fine-tune on real CSI datasets
python scripts/train_transfer_learning.py data/real_world/*.npz

# Export for edge deployment
python scripts/export_onnx.py --weights weights/simulation_baseline.pth
python scripts/export_tensorrt.py --precision fp16

See the setup guide in docs/# WiFi-Radar Setup Guide.md for:

• Flashing OpenWrt firmware with CSI extraction patches
• Configuring ath9k or Intel 5300 CSI tools
• Streaming CSI frames to the collection host
• Antenna placement guidelines

Security note: The CSI streaming port (default 5500) and the RTMP port (1935) should be firewall-restricted to your local network only.

• Initial release: CSI collection, simulation mode, signal processing, dual-branch CNN encoder
• LSTM pose estimator (17 keypoints, 3-D) with multi-person tracking
• Fall detection (4-state FSM) and gait analysis (cadence, stride, symmetry, speed)
• 3-tab Dash dashboard — Monitor, Events, Configuration
• RTMP streaming via FFmpeg subprocess
• ONNX export with onnxruntime validation
• Docker stack with nginx-rtmp + HLS playback
• Simulation-baseline training script

• REST API for headless and embedded deployment
• Gait anomaly detection using rolling metrics and unsupervised outlier scoring
• Transfer-learning script for real-world CSI datasets
• TensorRT export helper for Jetson-class devices
• Focused automated tests with coverage reporting
• src-based package layout cleanup

gantt
    title WiFi-Radar Delivery Status
    dateFormat  YYYY-MM-DD
    section Completed
    Simulation baseline           :done, a1, 2026-01-01, 2026-01-20
    Dashboard and RTMP            :done, a2, 2026-01-21, 2026-02-10
    API and anomaly detection     :done, a3, 2026-02-11, 2026-03-05
    section Next
    Real hardware validation      :active, a4, 2026-04-01, 2026-06-01
    Edge deployment hardening     :a5, 2026-06-02, 2026-07-15

• Pre-trained model weights (simulation baseline)
• Multi-person pose clustering
• Fall detection and gait analysis
• ONNX export for edge deployment
• Docker container with RTMP server included
• Web UI configuration panel
• Transfer learning from real-world CSI datasets
• TensorRT optimisation for Jetson Nano deployment
• REST API for headless / embedded integration
• Automated test suite with coverage reporting
• Anomaly detection for unusual gait patterns
• Extended real-hardware validation against live CSI captures
• Broader end-to-end regression coverage across the dashboard and streaming stack

Pull requests are welcome! Please read .github/CONTRIBUTING.md first. For major changes, open an issue to discuss what you'd like to change.

This project is licensed under the MIT License — see LICENSE for details.