CSIPulse

WiFi CSI 信号智能分析与人体感知引擎
轻量级 · 零C依赖 · 隐私优先 · 开箱即用

简体中文 | 繁體中文 | English

---

简体中文

🎉 项目介绍

CSIPulse 是一款轻量级 WiFi CSI（信道状态信息）信号智能分析与人体感知引擎。它利用现有 WiFi 基础设施发射的物理层信号，实现非接触式人体检测、定位和活动识别——无需摄像头，无需额外传感器，天然保护用户隐私。

为什么需要 CSIPulse？

传统人体感知方案存在诸多痛点：

方案	成本	隐私风险	受光照影响	受遮挡影响
摄像头	高	极高	是	是
红外传感器	中	低	否	部分
超声波	中	低	否	是
CSIPulse（WiFi CSI）	零额外成本	极低	否	否

CSIPulse 直接复用你家中或办公室已有的 WiFi 设备，零额外硬件投入，即可实现全天候、全场景的人体感知。

自研差异化亮点

• 纯 Python 实现，零 C/C++ 依赖 —— pip install 即用，告别编译地狱
• 内置 Web 实时可视化仪表盘 —— 深色主题，开箱即看
• 模块化 Pipeline 架构 —— 像搭积木一样灵活组合处理步骤
• 内置 CSI 模拟数据生成器 —— 没有硬件？照样能跑通全流程
• 支持 3 种主流 CSI 数据格式 —— CSV / Intel 5300 / Nexmon PCAP
• 集成检测融合三种算法 —— 方差分析 + 子载波相关性 + 信号能量，取长补短

💡 本项目灵感来源于 GitHub Trending 热门项目 RuView，由作者独立自研，从信号解析到感知算法全部重新设计与实现。

---

✨ 核心特性

特性	说明
📡 多格式 CSI 数据解析	支持 CSV / Intel 5300 / Nexmon PCAP 三种格式，自动识别
🧹 专业信号预处理	带通滤波、Hampel 滤波、相位校准、异常值去除，一步到位
🕵️ 多算法人体检测	方差分析 / 子载波相关性 / 信号能量 / 集成融合，四种策略任选
📍 多策略人体定位	RSSI 差异 / 相位差 / 指纹库匹配，适应不同场景
🏃 智能活动分类	识别 6 种活动：无人、站立、坐下、行走、跑步、跌倒
🔧 模块化 Pipeline	配置驱动、流式处理、回调支持，灵活拼装你的感知流程
📊 实时 Web 仪表盘	Flask + Chart.js，深色主题，CSI 波形 / 热力图 / 检测时间线一目了然
🎮 CSI 模拟器	无硬件也能调试，生成逼真的静态 / 行走 / 混合信号模式
🖥️ 全功能 CLI	彩色输出，6 个子命令，终端党的福音
🧪 74 个单元测试	100% 通过率，代码质量有保障

---

🚀 快速开始

环境要求

• Python 3.8+
• numpy >= 1.20
• scipy >= 1.7
• flask >= 2.0（仅 Web 仪表盘需要）

安装

git clone https://github.com/gitstq/CSIPulse.git
cd CSIPulse
pip install -r requirements.txt

快速体验（使用模拟数据，无需硬件）

# 1. 生成模拟 CSI 数据（行走场景，10秒）
python -m csipulse simulate --type walking --duration 10 --output demo_data.csv

# 2. 运行人体检测
python -m csipulse detect --input demo_data.csv

# 3. 运行活动分类
python -m csipulse classify --input demo_data.csv

# 4. 启动 Web 可视化仪表盘
python -m csipulse dashboard --port 5000

# 5. 运行完整 Pipeline（预处理 → 检测 → 分类）
python -m csipulse pipeline --input demo_data.csv --steps preprocess,detect,classify

---

📖 详细使用指南

CLI 命令详解

命令	说明	常用参数
parse	解析 CSI 数据文件	--format (csv/intel5300/nexmon), --info
detect	运行人体检测	--method (variance/correlation/energy/ensemble), --sensitivity
classify	运行活动分类	--method (static/threshold)
simulate	生成模拟 CSI 数据	--type (static/walking/mixed), --duration, --fs
dashboard	启动 Web 可视化仪表盘	--port, --host, --demo
pipeline	运行完整处理 Pipeline	--sensitivity, --detection-method, --classification-method

Python API 使用示例

from csipulse.core.parser import CSIParser
from csipulse.core.preprocessor import CSIPreprocessor
from csipulse.core.detector import PresenceDetector
from csipulse.core.classifier import ActivityClassifier
from csipulse.utils.simulator import CSISimulator

# 生成模拟数据
simulator = CSISimulator()
data = simulator.generate_walking(duration=10, fs=100, n_subcarriers=30)

# 信号预处理
preprocessor = CSIPreprocessor()
processed = preprocessor.default_pipeline(data)

# 人体检测
detector = PresenceDetector()
result = detector.detect_ensemble(processed)
print(f"人体存在: {result.is_present}, 置信度: {result.confidence:.2%}")

# 活动分类
classifier = ActivityClassifier()
activity = classifier.classify_static(processed)
print(f"活动类型: {activity.activity}, 置信度: {activity.confidence:.2%}")

Web 仪表盘

启动仪表盘后，访问 http://localhost:5000 即可查看：

• 📈 实时 CSI 波形图 —— 观察每个子载波的信号幅度变化
• 🌡️ 子载波热力图 —— 直观呈现多子载波信号的时空分布
• 📋 检测结果时间线 —— 人体存在与否的时间轴记录
• 🥧 活动分类饼图 —— 各类活动的占比一目了然

---

💡 设计思路与迭代规划

设计理念

• 模块化设计 —— 每个处理步骤独立封装，可灵活组合、按需替换
• 零依赖核心 —— 信号处理算法纯 Python + numpy 实现，不依赖任何 C 扩展
• 隐私优先 —— 所有数据本地处理，不上传云端，从架构层面保障隐私安全
• 开箱即用 —— 内置模拟器，无需专用硬件即可体验完整功能

技术选型

技术	选型理由
Python	科研领域主流语言，生态丰富，上手门槛低
numpy / scipy	成熟的科学计算库，性能与易用性兼顾
Flask	轻量级 Web 框架，适合嵌入式仪表盘场景
Chart.js	前端图表库，无需构建工具，即引即用

后续迭代计划

• 支持更多 CSI 数据格式（Atheros / PicoScenes）
• 增加机器学习分类器（SVM / 随机森林 / LSTM）
• 增加实时数据流处理（WebSocket 支持）
• 增加多房间 / 多人场景支持
• 增加 Docker 部署支持
• 增加 REST API 文档（Swagger）

---

📦 打包与部署

作为 Python 包安装

# 从源码安装
pip install .

# 或通过 pip 安装（发布后）
pip install csipulse

Docker 部署（规划中）

docker build -t csipulse .
docker run -p 5000:5000 csipulse dashboard

---

🤝 贡献指南

欢迎参与 CSIPulse 的开发！贡献流程如下：

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'feat: 添加某个特性'
4. 推送到分支：git push origin feature/amazing-feature
5. 创建 Pull Request

提交信息请遵循 Angular 提交规范：

前缀	用途
feat:	新功能
fix:	修复 Bug
docs:	文档更新
refactor:	代码重构

---

📄 开源协议

本项目基于 MIT License 开源，详见 LICENSE 文件。

---

繁體中文

🎉 專案介紹

CSIPulse 是一款輕量級 WiFi CSI（通道狀態資訊）訊號智慧分析與人體感知引擎。它利用現有 WiFi 基礎設施所發射的實體層訊號，實現非接觸式人體偵測、定位與活動辨識——無需攝影機，無需額外感測器，天然保護使用者隱私。

為什麼需要 CSIPulse？

傳統人體感知方案存在諸多痛點：

方案	成本	隱私風險	受光照影響	受遮擋影響
攝影機	高	極高	是	是
紅外線感測器	中	低	否	部分
超音波	中	低	否	是
CSIPulse（WiFi CSI）	零額外成本	極低	否	否

CSIPulse 直接複用家中或辦公室已有的 WiFi 設備，零額外硬體投入，即可實現全天候、全場景的人體感知。

自研差異化亮點

• 純 Python 實作，零 C/C++ 依賴 —— pip install 即用，告別編譯地獄
• 內建 Web 即時視覺化儀表板 —— 深色主題，開箱即看
• 模組化 Pipeline 架構 —— 像搭積木一樣靈活組合處理步驟
• 內建 CSI 模擬資料生成器 —— 沒有硬體？照樣能跑通全流程
• 支援 3 種主流 CSI 資料格式 —— CSV / Intel 5300 / Nexmon PCAP
• 整合偵測融合三種演算法 —— 變異數分析 + 子載波相關性 + 訊號能量，取長補短

💡 本專案靈感來源於 GitHub Trending 熱門專案 RuView，由作者獨立自研，從訊號解析到感知演算法全部重新設計與實作。

---

✨ 核心特性

特性	說明
📡 多格式 CSI 資料解析	支援 CSV / Intel 5300 / Nexmon PCAP 三種格式，自動識別
🧹 專業訊號預處理	帶通濾波、Hampel 濾波、相位校準、異常值去除，一步到位
🕵️ 多演算法人體偵測	變異數分析 / 子載波相關性 / 訊號能量 / 整合融合，四種策略任選
📍 多策略人體定位	RSSI 差異 / 相位差 / 指紋庫比對，適應不同場景
🏃 智慧活動分類	辨識 6 種活動：無人、站立、坐下、行走、跑步、跌倒
🔧 模組化 Pipeline	設定驅動、串流處理、回呼支援，靈活拼裝你的感知流程
📊 即時 Web 儀表板	Flask + Chart.js，深色主題，CSI 波形 / 熱力圖 / 偵測時間線一目了然
🎮 CSI 模擬器	無硬體也能除錯，生成逼真的靜態 / 行走 / 混合訊號模式
🖥️ 全功能 CLI	彩色輸出，6 個子命令，終端黨的福音
🧪 74 個單元測試	100% 通過率，程式碼品質有保障

---

🚀 快速開始

環境需求

• Python 3.8+
• numpy >= 1.20
• scipy >= 1.7
• flask >= 2.0（僅 Web 儀表板需要）

安裝

git clone https://github.com/gitstq/CSIPulse.git
cd CSIPulse
pip install -r requirements.txt

快速體驗（使用模擬資料，無需硬體）

# 1. 生成模擬 CSI 資料（行走場景，10秒）
python -m csipulse simulate --type walking --duration 10 --output demo_data.csv

# 2. 執行人體偵測
python -m csipulse detect --input demo_data.csv

# 3. 執行活動分類
python -m csipulse classify --input demo_data.csv

# 4. 啟動 Web 視覺化儀表板
python -m csipulse dashboard --port 5000

# 5. 執行完整 Pipeline（預處理 → 偵測 → 分類）
python -m csipulse pipeline --input demo_data.csv --steps preprocess,detect,classify

---

📖 詳細使用指南

CLI 命令詳解

命令	說明	常用參數
parse	解析 CSI 資料檔案	--format (csv/intel5300/nexmon), --info
detect	執行人體偵測	--method (variance/correlation/energy/ensemble), --sensitivity
classify	執行活動分類	--method (static/threshold)
simulate	生成模擬 CSI 資料	--type (static/walking/mixed), --duration, --fs
dashboard	啟動 Web 視覺化儀表板	--port, --host, --demo
pipeline	執行完整處理 Pipeline	--sensitivity, --detection-method, --classification-method

Python API 使用範例

from csipulse.core.parser import CSIParser
from csipulse.core.preprocessor import CSIPreprocessor
from csipulse.core.detector import PresenceDetector
from csipulse.core.classifier import ActivityClassifier
from csipulse.utils.simulator import CSISimulator

# 生成模擬資料
simulator = CSISimulator()
data = simulator.generate_walking(duration=10, fs=100, n_subcarriers=30)

# 訊號預處理
preprocessor = CSIPreprocessor()
processed = preprocessor.default_pipeline(data)

# 人體偵測
detector = PresenceDetector()
result = detector.detect_ensemble(processed)
print(f"人體存在: {result.is_present}, 置信度: {result.confidence:.2%}")

# 活動分類
classifier = ActivityClassifier()
activity = classifier.classify_static(processed)
print(f"活動類型: {activity.activity}, 置信度: {activity.confidence:.2%}")

Web 儀表板

啟動儀表板後，前往 http://localhost:5000 即可查看：

• 📈 即時 CSI 波形圖 —— 觀察每個子載波的訊號幅度變化
• 🌡️ 子載波熱力圖 —— 直觀呈現多子載波訊號的時空分佈
• 📋 偵測結果時間線 —— 人體存在與否的時間軸記錄
• 🥧 活動分類圓餅圖 —— 各類活動的佔比一目了然

---

💡 設計思路與迭代規劃

設計理念

• 模組化設計 —— 每個處理步驟獨立封裝，可靈活組合、按需替換
• 零依賴核心 —— 訊號處理演算法純 Python + numpy 實作，不依賴任何 C 擴充套件
• 隱私優先 —— 所有資料本地處理，不上傳雲端，從架構層面保障隱私安全
• 開箱即用 —— 內建模擬器，無需專用硬體即可體驗完整功能

技術選型

技術	選型理由
Python	科研領域主流語言，生態豐富，上手門檻低
numpy / scipy	成熟的科學計算函式庫，效能與易用性兼顧
Flask	輕量級 Web 框架，適合嵌入式儀表板場景
Chart.js	前端圖表函式庫，無需建置工具，即引即用

後續迭代計畫

• 支援更多 CSI 資料格式（Atheros / PicoScenes）
• 增加機器學習分類器（SVM / 隨機森林 / LSTM）
• 增加即時資料串流處理（WebSocket 支援）
• 增加多房間 / 多人場景支援
• 增加 Docker 部署支援
• 增加 REST API 文件（Swagger）

---

📦 打包與部署

作為 Python 套件安裝

# 從原始碼安裝
pip install .

# 或透過 pip 安裝（發佈後）
pip install csipulse

Docker 部署（規劃中）

docker build -t csipulse .
docker run -p 5000:5000 csipulse dashboard

---

🤝 貢獻指南

歡迎參與 CSIPulse 的開發！貢獻流程如下：

1. Fork 本儲存庫
2. 建立特性分支：git checkout -b feature/amazing-feature
3. 提交變更：git commit -m 'feat: 新增某個特性'
4. 推送至分支：git push origin feature/amazing-feature
5. 建立 Pull Request

提交訊息請遵循 Angular 提交規範：

前綴	用途
feat:	新功能
fix:	修復 Bug
docs:	文件更新
refactor:	程式碼重構

---

📄 開源協議

本專案基於 MIT License 開源，詳見 LICENSE 檔案。

---

English

🎉 About CSIPulse

CSIPulse is a lightweight WiFi CSI (Channel State Information) signal analysis and human sensing engine. It leverages the physical-layer signals from your existing WiFi infrastructure to enable non-contact human detection, localization, and activity recognition -- no cameras, no extra sensors, privacy by design.

Why CSIPulse?

Traditional human sensing solutions come with significant trade-offs:

Approach	Cost	Privacy Risk	Affected by Light	Affected by Obstacles
Camera	High	Critical	Yes	Yes
Infrared Sensor	Medium	Low	No	Partially
Ultrasonic	Medium	Low	No	Yes
CSIPulse (WiFi CSI)	Zero extra cost	Minimal	No	No

CSIPulse works with the WiFi equipment you already have -- no additional hardware needed. Just deploy and start sensing.

Key Differentiators

• Pure Python, zero C/C++ dependencies -- pip install and go, no compilation headaches
• Built-in real-time Web dashboard -- dark theme, ready out of the box
• Modular Pipeline architecture -- mix and match processing steps like building blocks
• Built-in CSI data simulator -- develop and debug without any specialized hardware
• 3 CSI data format support -- CSV / Intel 5300 / Nexmon PCAP
• Ensemble detection with 3 algorithms -- variance analysis + subcarrier correlation + signal energy, best of all worlds

💡 Inspired by the GitHub Trending project RuView. Independently designed and implemented from scratch -- from signal parsing to sensing algorithms.

---

✨ Core Features

Feature	Description
📡 Multi-format CSI parsing	CSV / Intel 5300 / Nexmon PCAP with automatic format detection
🧹 Professional signal preprocessing	Bandpass filtering, Hampel filtering, phase calibration, outlier removal
🕵️ Multi-algorithm human detection	Variance / Subcarrier correlation / Signal energy / Ensemble fusion
📍 Multi-strategy human localization	RSSI differential / Phase difference / Fingerprint matching
🏃 Intelligent activity classification	6 activity types: empty, standing, sitting, walking, running, falling
🔧 Modular Pipeline	Config-driven, streaming, callback support -- build your own sensing flow
📊 Real-time Web dashboard	Flask + Chart.js, dark theme -- waveforms, heatmaps, timelines at a glance
🎮 CSI Simulator	Generate realistic static / walking / mixed signal patterns without hardware
🖥️ Full-featured CLI	Colorized output, 6 subcommands, a joy for terminal users
🧪 74 unit tests	100% pass rate, quality you can count on

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• numpy >= 1.20
• scipy >= 1.7
• flask >= 2.0 (only needed for the Web dashboard)

Installation

git clone https://github.com/gitstq/CSIPulse.git
cd CSIPulse
pip install -r requirements.txt

Try It Out (with simulated data, no hardware required)

# 1. Generate simulated CSI data (walking scenario, 10 seconds)
python -m csipulse simulate --type walking --duration 10 --output demo_data.csv

# 2. Run human detection
python -m csipulse detect --input demo_data.csv

# 3. Run activity classification
python -m csipulse classify --input demo_data.csv

# 4. Launch the Web dashboard
python -m csipulse dashboard --port 5000

# 5. Run the full Pipeline (preprocess → detect → classify)
python -m csipulse pipeline --input demo_data.csv --steps preprocess,detect,classify

---

📖 Detailed Usage Guide

CLI Reference

Command	Description	Key Flags
parse	Parse CSI data files	--format (csv/intel5300/nexmon), --info
detect	Run human presence detection	--method (variance/correlation/energy/ensemble), --sensitivity
classify	Run activity classification	--method (static/threshold)
simulate	Generate simulated CSI data	--type (static/walking/mixed), --duration, --fs
dashboard	Launch the Web dashboard	--port, --host, --demo
pipeline	Run the full processing pipeline	--sensitivity, --detection-method, --classification-method

Python API Example

from csipulse.core.parser import CSIParser
from csipulse.core.preprocessor import CSIPreprocessor
from csipulse.core.detector import PresenceDetector
from csipulse.core.classifier import ActivityClassifier
from csipulse.utils.simulator import CSISimulator

# Generate simulated data
simulator = CSISimulator()
data = simulator.generate_walking(duration=10, fs=100, n_subcarriers=30)

# Signal preprocessing
preprocessor = CSIPreprocessor()
processed = preprocessor.default_pipeline(data)

# Human detection
detector = PresenceDetector()
result = detector.detect_ensemble(processed)
print(f"Human present: {result.is_present}, Confidence: {result.confidence:.2%}")

# Activity classification
classifier = ActivityClassifier()
activity = classifier.classify_static(processed)
print(f"Activity: {activity.activity}, Confidence: {activity.confidence:.2%}")

Web Dashboard

Once launched, visit http://localhost:5000 to explore:

• 📈 Real-time CSI waveform -- monitor amplitude changes across subcarriers
• 🌡️ Subcarrier heatmap -- visualize spatiotemporal signal distribution
• 📋 Detection timeline -- track human presence over time
• 🥧 Activity pie chart -- see the breakdown of detected activities

---

💡 Design Philosophy & Roadmap

Design Principles

• Modular architecture -- each processing step is independently encapsulated, composable and replaceable
• Zero-dependency core -- signal processing algorithms built with pure Python + numpy, no C extensions
• Privacy first -- all data processed locally, nothing sent to the cloud, privacy guaranteed by design
• Ready to use -- built-in simulator lets you experience the full workflow without specialized hardware

Tech Stack

Technology	Why
Python	Dominant language in research, rich ecosystem, low barrier to entry
numpy / scipy	Mature scientific computing libraries, performance meets usability
Flask	Lightweight web framework, ideal for embedded dashboards
Chart.js	Frontend charting library, no build tools required

Roadmap

• Support additional CSI data formats (Atheros / PicoScenes)
• Add ML-based classifiers (SVM / Random Forest / LSTM)
• Real-time data stream processing (WebSocket support)
• Multi-room / multi-person scenario support
• Docker deployment support
• REST API documentation (Swagger)

---

📦 Packaging & Deployment

Install as a Python Package

# Install from source
pip install .

# Or via pip (after publication)
pip install csipulse

Docker Deployment (Planned)

docker build -t csipulse .
docker run -p 5000:5000 csipulse dashboard

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork this repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add some feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please follow the Angular Commit Convention:

Prefix	Purpose
feat:	New feature
fix:	Bug fix
docs:	Documentation update
refactor:	Code refactoring

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.