SDP: Sensing Data Protocol for Scalable Wireless Sensing

📖 Citation

If you use SDP in your research, please cite:

@ARTICLE{11652923,
  author={Zhang, Di and Huang, Jiawei and Cui, Yuanhao and Cao, Xiaowen and Han, Tony Xiao and Jing, Xiaojun},
  journal={IEEE Transactions on Mobile Computing},
  title={SDP: A Unified Protocol and Benchmarking Framework for Reproducible Wi-Fi Sensing},
  year={2026},
  volume={},
  number={},
  pages={1-14},
  keywords={Wireless fidelity;Modeling;Frequency;Protocols;Training;Streams;Accuracy;Measurement;Tensors;Antennas;Benchmark;canonical representation;channel state information (CSI);integrated sensing and communications (ISAC);reproducibility;wireless sensing},
  doi={10.1109/TMC.2026.3723025}}

🆕 What's New in v0.5.2

• Modular algorithm pipeline -- freely compose preprocessing steps with AlgorithmStep and execute_algorithm_steps()
• Pluggable readers -- bring your own file-format reader via register_reader() and pipeline(..., reader=) (CLI --reader)
• Per-dataset pipeline presets -- widar, gait, xrf55, elderAL, zte via --algorithm-preset
• Compatibility & stability fixes -- clearer errors when an algorithm doesn't support a dataset, checkpoint always saved, Python 3.9 fix, XRF55 subset split fix

🎯 What is SDP?

SDP is a protocol-level abstraction and unified benchmark for reproducible wireless sensing.

⚠️ SDP is not a new neural network, but a standardized protocol that unifies CSI representations for fair comparison.

🆚 Why Choose WSDP?

Verified from official GitHub repos on 2026-03-17.

🧠 Model Zoo (19 Models, Baseline → SOTA)

from wsdp.models import create_model, list_models
model = create_model("ResNet1D", num_classes=10, input_shape=(20, 30, 3))

⚠️ Baseline Model Architecture Note

Baseline models (MLP, CNN1D, CNN2D, LSTM) use a Spatial Encoder (Conv2d-based) to compress the (F, A) antenna dimension before temporal processing. This prevents parameter explosion from direct (T, F, A) flattening. See CHANGELOG.md for details.

🧪 Algorithm Library (26+ Algorithms in 7 Categories)

from wsdp.algorithms import denoise, calibrate, normalize
denoised = denoise(csi, method='butterworth', order=5, cutoff=0.3)
calibrated = calibrate(csi, method='stc')

See Model Guide and Algorithm Guide.

🎯 What is SDP? (Cont.)

The Problem

Wireless sensing research often suffers from:

• ❌ Hardware-specific CSI formats
• ❌ Inconsistent preprocessing pipelines
• ❌ Unstable training results
• ❌ Large performance variance across random seeds

Result: Models cannot be fairly compared.

The Solution

SDP solves this at the protocol level, not the model level:

SDP projects raw CSI into a fixed canonical frequency grid (K=30), ensuring cross-hardware comparability.

Performance Highlights

🚀 Quick Start (3 Steps, 5 Minutes)

Step 1: Install (30 seconds)

pip install wsdp

Verify installation:

wsdp --version

Step 2: Download Dataset (2 minutes)

🔑 Required: Create a free account at SDP8.org — your account credentials are needed for dataset downloads.

🌐 VPN is recommended for downloading datasets.

Option A: From CLI (Recommended for testing)

All datasets hosted on SDP8.org:

# elderAL = smallest dataset, fastest for testing
# Use your SDP8.org email/password:
wsdp download elderAL ./data --email you@example.com --password yourpassword

# Or use a JWT token (from SDP8.org dashboard):
wsdp download elderAL ./data --token YOUR_JWT_TOKEN

# Download larger datasets:
# wsdp download widar ./data
# wsdp download gait ./data
# wsdp download xrf55 ./data
# wsdp download zte ./data --email you@example.com --password yourpassword
# ⚠️ zte requires applying for access on the SDP platform first

Option B: From SDP8.org Web Interface

Log in at sdp8.org and download datasets manually.

Required Dataset Structure:

data/
├── elderAL/                    # Dataset name
│   ├── action0_static_new/     # Activity folder
│   │   ├── user0_position1_activity0/  # Sample folder
│   │   │   ├── sample1.csv
│   │   │   └── ...
│   │   └── ...
│   ├── action1_walk_new/
│   └── ...
├── widar/
│
├── gait/
│
├── xrf55/
│   └── WIFI/
│       └── sample.npy
└── zte/

Step 3: Train & Evaluate (2 minutes)

🐍 Python API (Recommended for research):

Create train.py:

from wsdp import pipeline

# Minimal call - uses default hyperparameters
pipeline("./data/elderAL", "./output", "elderAL")

# Or with custom hyperparameters
pipeline(
    input_path="./data/elderAL",
    output_folder="./output",
    dataset="elderAL",
    learning_rate=1e-3,
    num_epochs=50,
    batch_size=64,
)

Run:

python train.py

💻 CLI (Quick & Simple):

# Basic training
wsdp run ./data/elderAL ./output elderAL

# With hyperparameter override
wsdp run ./data/elderAL ./output elderAL --lr 0.001 --epochs 50 --batch-size 64

# With hyperparameter config file (YAML, top-level key = dataset name)
wsdp run ./data/elderAL ./output elderAL --config my_config.yaml

# Swap the model: a registered model name, or your own .py file
wsdp run ./data/elderAL ./output elderAL --model THAT
wsdp run ./data/elderAL ./output elderAL -m custom_model.py

# Custom preprocessing: algorithm config (YAML/JSON) or a preset
wsdp run ./data/elderAL ./output elderAL --algorithm-config my_algorithms.yaml
wsdp run ./data/elderAL ./output elderAL --algorithm-preset high_quality

📊 What You Get:

After training, check ./output/ (one set of files per random seed, 5 seeds by default):

output/
├── best_checkpoint_<seed>.pth    # Best model checkpoint for each seed
├── training_history_<seed>.csv   # Per-epoch loss & accuracy for each seed
└── cm_rs_<seed>.png              # Confusion matrix for each seed

Mean and variance of Top-1 accuracy across seeds are printed to the console at the end.

✅ If you see these files, SDP is working correctly!

📊 Supported Datasets

More datasets coming soon!

🔬 Research & Customization

🧠 Plug in Your Own Model

Step 1: Create custom_model.py:

import torch
import torch.nn as nn

class YourCustomModel(nn.Module):
    def __init__(self, num_classes=6):
        super().__init__()
        # Your architecture here
        # Input shape: (Batch, Timestamp, Frequency, Antenna)
        
    def forward(self, x):
        # Your forward pass
        return output

# Required: expose model class
model = YourCustomModel

Step 2: Run with your model:

wsdp run ./data/elderAL ./output elderAL -m custom_model.py

📁 Use Your Own Dataset

Labels and split groups are parsed from filenames, so name your files after one of the built-in dataset conventions (e.g. XRF55 user_action_trial) and pass that dataset name. If your files use a custom format, register a reader for it:

from wsdp import pipeline
from wsdp.readers import BaseReader, register_reader

class MyReader(BaseReader):
    def sniff(self, file_path): return file_path.endswith(".myfmt")
    def read_file(self, file_path): ...  # parse the file into CSIData

register_reader("my_format", MyReader)
# Filenames follow the XRF55 convention -> dataset="xrf55" + custom reader for the format
pipeline("./data/my_dataset", "./output", "xrf55", reader="my_format")

End-to-end example: examples/scripts/custom_reader_algorithm.py.

🗺️ Codebase Map

Want to go deeper? Here's where to modify:

🔌 Pluggable Algorithm Architecture

WSDP features a Registry Pattern that makes algorithms pluggable:

from wsdp.algorithms import denoise, calibrate, register_algorithm

# Unified API — switch methods with one parameter
denoised = denoise(csi, method='butterworth', order=5)
calibrated = calibrate(csi, method='stc')

# Register your own algorithm
def my_denoise(csi, **kwargs):
    return my_custom_filter(csi)

register_algorithm('denoise', 'my_method', my_denoise)
result = denoise(csi, method='my_method')  # Works like built-in!

You can try this in examples/getting_started.ipynb or just in your custom pipeline!

Configuration file support:

# examples/configs/algorithms_config.yaml
denoise:
  method: butterworth
  params:
    order: 5
    cutoff: 0.3
calibrate:
  method: stc
normalize:
  method: z-score

from wsdp.algorithms import load_config, execute_pipeline
config = load_config('examples/configs/algorithms_config.yaml')
processed = execute_pipeline(csi, config)

Or:

pipeline(
    "./data/elderAL",
    "./output",
    "elderAL",
    algorithm_config_file='./examples/configs/algorithms_config.yaml',
)

Pipeline presets:

from wsdp.algorithms import apply_preset, execute_pipeline

# Choose a preset for your use case
steps = apply_preset('high_quality')  # or 'fast', 'robust', etc.
processed = execute_pipeline(csi, steps)

Modular pipeline (compose or skip steps freely):

from wsdp.algorithms import AlgorithmStep
from wsdp.processors import ModularProcessor

steps = [
    AlgorithmStep(category="denoise", method="wavelet", params={"level": 2}),
    AlgorithmStep(category="normalize", method="z-score"),  # calibration skipped
]
data, labels, groups = ModularProcessor(steps).process(csi_data_list, dataset="xrf55")

Config-file form: examples/configs/modular_pipeline.yaml.

📊 Algorithm Library

Built-in Presets:

Per-dataset presets (widar, gait, xrf55, elderAL, zte) are also available; they currently mirror the legacy default chain (linear calibration

• wavelet denoise).

🧪 Understanding SDP (10-Min Deep Dive)

The SDP Pipeline

Raw CSI
  ↓
[Deterministic Sanitization]
  - Phase calibration
  - Wavelet denoising
  ↓
[Canonical Tensor Construction]
  - K=30 frequency grid
  - Standardized shape
  ↓
[Deep Learning Model]
  ↓
Prediction

Canonical Tensor Format

After sanitization, SDP constructs a Canonical CSI Tensor:

$$X \in \mathbb{C}^{A \times K \times T}$$

Where:

• $A$ = Number of antennas
• $K$ = 30 (fixed frequency grid)
• $T$ = Time samples

This ensures cross-hardware comparability.

Why Deterministic?

Raw CSI contains hardware distortions:

• Phase offsets
• Sampling time offsets
• Noise fluctuations

SDP enforces deterministic calibration and denoising, guaranteeing:

• ✅ Same raw CSI → Same cleaned tensor
• ✅ Reproducibility is enforced, not optional

📚 Documentation & Resources

🎓 Tutorials (Recommended Order)

#	Resource	What You'll Learn
1	Quickstart Notebook	5-min intro — registry exploration & processor customization
2	Getting Started Notebook	Algorithm deep-dive — phase calibration & denoising with step-by-step visualizations
3	Full Tutorial Notebook	End-to-end workflow — install → preprocess → train → evaluate → CLI

📘 User Guide

📊 Reference

🗺️ Roadmap

• v0.1 - Initial protocol design
• v0.2 - 5 datasets support, CLI tool
• v0.3 - More datasets (WiFi-HAR, CSI-HAR, etc.)
• v0.4 - 19 models, 26+ algorithms, leaderboard, CI/CD, scientific bug fixes
• v0.5 - PyPI official release, online demo platform
• v1.0 - Full protocol standardization

Want a specific dataset? Open an issue and let us know!

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup
• Coding guidelines
• Pull request process

📄 License

MIT License - see LICENSE file.