轻量级 WiFi 空间智能感知引擎
通过分析 WiFi 信号变化实现人体存在检测、活动识别和空间感知,无需摄像头,保护隐私。
SpaceSense 是一个轻量级的 WiFi 空间智能感知引擎。它通过分析 WiFi 信号(RSSI)的细微变化来感知空间中的人体存在、活动状态和移动轨迹,完全不需要摄像头或其他视觉传感器,从根本上保护用户隐私。
项目灵感来源于 GitHub Trending 上的 RuView 项目,旨在提供一个更轻量、更易用的替代方案。SpaceSense 使用纯 Python 标准库实现,零外部依赖,开箱即用。
核心优势:
- 隐私优先 — 不使用摄像头,仅分析 WiFi 信号变化
- 零依赖 — 纯 Python 标准库实现,无需安装任何第三方包
- 开箱即用 — 克隆仓库即可运行,支持演示模式快速体验
- 功能完整 — 从信号采集到分析告警,提供全链路解决方案
| 模块 | 功能说明 |
|---|---|
| 📡 信号处理 | 滑动窗口平滑、Z-score 异常值过滤、信号归一化 |
| 👤 人体存在检测 | 方差分析、动态阈值自适应、多传感器融合 |
| 🏃 活动识别 | 7 种活动分类:静止 / 走动 / 跑步 / 坐下 / 接近 / 离开 / 跌倒 |
| 🗺️ 区域监控 | 多区域同时监控、区域间移动检测、停留时间统计 |
| 📊 数据分析 | 12 项统计指标、DTW 模式匹配、趋势检测 |
| 🔔 告警系统 | 多级告警(info/warning/critical)、规则引擎、控制台 / 文件 / 回调三种输出 |
| 💾 数据导出 | CSV / JSON 格式,支持信号数据 / 分析结果 / 告警记录 / 统计报告 / 综合报告 |
| 🖥️ TUI 仪表盘 | curses 实时可视化,不支持时自动降级为纯文本输出 |
- Python 3.8 或更高版本
- 无需安装任何外部依赖
# 克隆仓库
git clone https://github.com/your-username/spacesense.git
cd spacesense
# 无需 pip install,零依赖直接运行
python cli.py --version最快的方式是使用内置的演示模式,它会生成模拟 WiFi 信号数据来展示所有功能:
# 运行 30 秒混合场景演示
python cli.py demo --duration 30 --scenario mixed
# 运行 60 秒步行场景演示
python cli.py demo --duration 60 --scenario person_walking启动实时 WiFi 信号监控,附带 TUI 可视化仪表盘,显示信号波形、存在检测结果、活动识别、区域状态和告警信息。
# 基本用法
python cli.py monitor
# 指定配置文件
python cli.py monitor --config my_config.json
# 调整检测灵敏度(0.1 ~ 10.0)
python cli.py monitor --sensitivity 1.5
# 监控指定区域
python cli.py monitor --zones living_room,bedroom,kitchen| 参数 | 缩写 | 说明 | 默认值 |
|---|---|---|---|
--config |
-c |
JSON 配置文件路径 | 使用默认配置 |
--sensitivity |
-s |
检测灵敏度(0.1 ~ 10.0) | 配置文件中的值 |
--zones |
-z |
逗号分隔的区域名称 | 无区域监控 |
对已有的信号数据进行全面离线分析,包括统计指标计算、活动模式匹配、趋势检测和周期性分析。
# 分析 JSON 格式的信号数据
python cli.py analyze --input data.json
# 分析并导出结果
python cli.py analyze --input data.json --output analysis_report.json
# 分析 CSV 格式的信号数据
python cli.py analyze --input signal_data.csv| 参数 | 缩写 | 说明 | 默认值 |
|---|---|---|---|
--input |
-i |
输入数据文件(JSON 数组或 CSV) | 必填 |
--output |
-o |
分析结果输出文件路径 | 不导出 |
输入文件格式支持:
- JSON 数组:
[-55.0, -56.2, -54.8, ...] - JSON 对象数组:
[{"rssi": -55.0}, {"rssi": -56.2}, ...] - CSV(每行一个数值):
-55.0\n-56.2\n-54.8\n...
将信号数据和统计结果导出为 CSV 或 JSON 格式,方便后续处理和可视化。
# 导出为 CSV 格式(默认)
python cli.py export --input data.json --format csv
# 导出为 JSON 格式
python cli.py export --input data.json --format json
# 指定输出目录
python cli.py export --input data.json --format csv --output-dir ./my_exports| 参数 | 缩写 | 说明 | 默认值 |
|---|---|---|---|
--input |
-i |
输入数据文件(JSON 数组或 CSV) | 必填 |
--format |
-f |
导出格式:csv 或 json |
csv |
--output-dir |
-d |
输出目录路径 | ./exports |
使用模拟 WiFi 信号数据运行完整演示,无需真实硬件即可体验所有 SpaceSense 功能。
# 默认 30 秒混合场景
python cli.py demo
# 自定义时长和场景
python cli.py demo --duration 60 --scenario mixed
# 指定特定场景
python cli.py demo --scenario person_running --duration 20| 参数 | 缩写 | 说明 | 默认值 |
|---|---|---|---|
--duration |
-d |
演示时长(秒) | 30 |
--scenario |
— | 模拟场景:empty_room / person_still / person_walking / person_running / mixed |
mixed |
查看、保存或重置 SpaceSense 配置。配置使用 JSON 格式,支持与默认值深度合并。
# 查看当前配置
python cli.py config --show
# 从自定义配置文件查看
python cli.py config --show --config my_config.json
# 导出默认配置到文件
python cli.py config --reset --output default_config.json
# 保存当前配置
python cli.py config --config my_config.json --output saved_config.json| 参数 | 缩写 | 说明 | 默认值 |
|---|---|---|---|
--show |
— | 显示当前配置 | 默认行为 |
--reset |
— | 导出默认配置 | — |
--config |
-c |
要加载的配置文件路径 | — |
--output |
-o |
配置输出文件路径 | — |
设计哲学:
- 极简主义 — 代码精简,接口清晰,上手零门槛
- 隐私优先 — 从架构层面杜绝视觉数据采集
- 标准库优先 — 不引入任何外部依赖,确保最大兼容性
- 渐进增强 — 核心功能稳定可靠,高级特性按需启用
迭代规划:
- v1.0.0 — 核心引擎:信号处理、存在检测、活动识别、区域监控
- v1.1.0 — 增强分析:机器学习分类模型、自适应阈值优化
- v1.2.0 — 集成扩展:MQTT 推送、Home Assistant 插件、REST API
- v2.0.0 — 分布式架构:多节点协同感知、时序数据库支持
spacesense/
├── __init__.py # 包初始化,导出公共接口
├── core.py # 核心感知引擎(信号处理、存在检测、活动识别、区域监控)
├── analyzer.py # 数据分析模块(统计分析、模式匹配、趋势检测)
├── alert.py # 告警管理(多级告警、规则引擎、多通道输出)
├── export.py # 数据导出(CSV / JSON,多种报告类型)
├── tui.py # 终端 UI 仪表盘(curses 实时可视化)
├── config.py # 配置管理(JSON 配置、验证、深度合并)
└── utils.py # 工具函数(颜色输出、进度条等)
cli.py # 命令行接口
tests/
├── test_core.py # 核心模块测试
├── test_analyzer.py # 分析模块测试
└── test_export.py # 导出模块测试
我们欢迎任何形式的贡献!在参与之前,请阅读 贡献指南。
快速流程:
- Fork 本仓库
- 创建特性分支:
git checkout -b feature/my-feature - 提交更改:
git commit -m 'feat: add my feature' - 推送分支:
git push origin feature/my-feature - 提交 Pull Request
注意事项:
- 遵循 PEP 8 代码规范
- 为新功能编写测试用例
- 保持零外部依赖原则
- 使用 Conventional Commits 规范提交信息
本项目基于 MIT License 开源。
SpaceSense 是一個輕量級的 WiFi 空間智慧感知引擎。它透過分析 WiFi 訊號(RSSI)的細微變化來感知空間中的人體存在、活動狀態和移動軌跡,完全不需要攝影機或其他視覺感測器,從根本上保護使用者隱私。
專案靈感來自於 GitHub Trending 上的 RuView 專案,旨在提供一個更輕量、更容易上手的替代方案。SpaceSense 使用純 Python 標準函式庫實作,零外部依賴,開箱即用。
核心優勢:
- 隱私優先 — 不使用攝影機,僅分析 WiFi 訊號變化
- 零依賴 — 純 Python 標準函式庫實作,無需安裝任何第三方套件
- 開箱即用 — 複製儲存庫即可執行,支援演示模式快速體驗
- 功能完整 — 從訊號採集到分析告警,提供全鏈路解決方案
| 模組 | 功能說明 |
|---|---|
| 📡 訊號處理 | 滑動視窗平滑、Z-score 離群值過濾、訊號正規化 |
| 👤 人體存在偵測 | 變異數分析、動態閾值自適應、多感測器融合 |
| 🏃 活動識別 | 7 種活動分類:靜止 / 走動 / 跑步 / 坐下 / 接近 / 離開 / 跌倒 |
| 🗺️ 區域監控 | 多區域同時監控、區域間移動偵測、停留時間統計 |
| 📊 數據分析 | 12 項統計指標、DTW 模式比對、趨勢偵測 |
| 🔔 告警系統 | 多級告警(info/warning/critical)、規則引擎、主控台 / 檔案 / 回呼三種輸出 |
| 💾 數據匯出 | CSV / JSON 格式,支援訊號數據 / 分析結果 / 告警記錄 / 統計報告 / 綜合報告 |
| 🖥️ TUI 儀表板 | curses 即時視覺化,不支援時自動降級為純文字輸出 |
- Python 3.8 或更高版本
- 無需安裝任何外部依賴
# 複製儲存庫
git clone https://github.com/your-username/spacesense.git
cd spacesense
# 無需 pip install,零依賴直接執行
python cli.py --version最快的方式是使用內建的演示模式,它會產生模擬 WiFi 訊號資料來展示所有功能:
# 執行 30 秒混合場景演示
python cli.py demo --duration 30 --scenario mixed
# 執行 60 秒步行場景演示
python cli.py demo --duration 60 --scenario person_walking啟動即時 WiFi 訊號監控,附帶 TUI 視覺化儀表板,顯示訊號波形、存在偵測結果、活動識別、區域狀態和告警資訊。
# 基本用法
python cli.py monitor
# 指定設定檔
python cli.py monitor --config my_config.json
# 調整偵測靈敏度(0.1 ~ 10.0)
python cli.py monitor --sensitivity 1.5
# 監控指定區域
python cli.py monitor --zones living_room,bedroom,kitchen| 參數 | 縮寫 | 說明 | 預設值 |
|---|---|---|---|
--config |
-c |
JSON 設定檔路徑 | 使用預設設定 |
--sensitivity |
-s |
偵測靈敏度(0.1 ~ 10.0) | 設定檔中的值 |
--zones |
-z |
逗號分隔的區域名稱 | 無區域監控 |
對已有的訊號資料進行全面離線分析,包括統計指標計算、活動模式比對、趨勢偵測和週期性分析。
# 分析 JSON 格式的訊號資料
python cli.py analyze --input data.json
# 分析並匯出結果
python cli.py analyze --input data.json --output analysis_report.json
# 分析 CSV 格式的訊號資料
python cli.py analyze --input signal_data.csv| 參數 | 縮寫 | 說明 | 預設值 |
|---|---|---|---|
--input |
-i |
輸入資料檔案(JSON 陣列或 CSV) | 必填 |
--output |
-o |
分析結果輸出檔案路徑 | 不匯出 |
輸入檔案格式支援:
- JSON 陣列:
[-55.0, -56.2, -54.8, ...] - JSON 物件陣列:
[{"rssi": -55.0}, {"rssi": -56.2}, ...] - CSV(每行一個數值):
-55.0\n-56.2\n-54.8\n...
將訊號資料和統計結果匯出為 CSV 或 JSON 格式,方便後續處理和視覺化。
# 匯出為 CSV 格式(預設)
python cli.py export --input data.json --format csv
# 匯出為 JSON 格式
python cli.py export --input data.json --format json
# 指定輸出目錄
python cli.py export --input data.json --format csv --output-dir ./my_exports| 參數 | 縮寫 | 說明 | 預設值 |
|---|---|---|---|
--input |
-i |
輸入資料檔案(JSON 陣列或 CSV) | 必填 |
--format |
-f |
匯出格式:csv 或 json |
csv |
--output-dir |
-d |
輸出目錄路徑 | ./exports |
使用模擬 WiFi 訊號資料執行完整演示,無需真實硬體即可體驗所有 SpaceSense 功能。
# 預設 30 秒混合場景
python cli.py demo
# 自訂時長和場景
python cli.py demo --duration 60 --scenario mixed
# 指定特定場景
python cli.py demo --scenario person_running --duration 20| 參數 | 縮寫 | 說明 | 預設值 |
|---|---|---|---|
--duration |
-d |
演示時長(秒) | 30 |
--scenario |
— | 模擬場景:empty_room / person_still / person_walking / person_running / mixed |
mixed |
檢視、儲存或重設 SpaceSense 設定。設定使用 JSON 格式,支援與預設值深度合併。
# 檢視目前設定
python cli.py config --show
# 從自訂設定檔檢視
python cli.py config --show --config my_config.json
# 匯出預設設定到檔案
python cli.py config --reset --output default_config.json
# 儲存目前設定
python cli.py config --config my_config.json --output saved_config.json| 參數 | 縮寫 | 說明 | 預設值 |
|---|---|---|---|
--show |
— | 顯示目前設定 | 預設行為 |
--reset |
— | 匯出預設設定 | — |
--config |
-c |
要載入的設定檔路徑 | — |
--output |
-o |
設定輸出檔案路徑 | — |
設計理念:
- 極簡主義 — 程式碼精簡,介面清晰,上手零門檻
- 隱私優先 — 從架構層面杜絕視覺資料採集
- 標準函式庫優先 — 不引入任何外部依賴,確保最大相容性
- 漸進增強 — 核心功能穩定可靠,進階特性按需啟用
迭代規劃:
- v1.0.0 — 核心引擎:訊號處理、存在偵測、活動識別、區域監控
- v1.1.0 — 增強分析:機器學習分類模型、自適應閾值最佳化
- v1.2.0 — 整合擴充:MQTT 推送、Home Assistant 外掛、REST API
- v2.0.0 — 分散式架構:多節點協同感知、時序資料庫支援
spacesense/
├── __init__.py # 套件初始化,匯出公共介面
├── core.py # 核心感知引擎(訊號處理、存在偵測、活動識別、區域監控)
├── analyzer.py # 數據分析模組(統計分析、模式比對、趨勢偵測)
├── alert.py # 告警管理(多級告警、規則引擎、多通道輸出)
├── export.py # 數據匯出(CSV / JSON,多種報告類型)
├── tui.py # 終端 UI 儀表板(curses 即時視覺化)
├── config.py # 設定管理(JSON 設定、驗證、深度合併)
└── utils.py # 工具函式(顏色輸出、進度條等)
cli.py # 命令列介面
tests/
├── test_core.py # 核心模組測試
├── test_analyzer.py # 分析模組測試
└── test_export.py # 匯出模組測試
我們歡迎任何形式的貢獻!在參與之前,請閱讀 貢獻指南。
快速流程:
- Fork 本儲存庫
- 建立特性分支:
git checkout -b feature/my-feature - 提交變更:
git commit -m 'feat: add my feature' - 推送分支:
git push origin feature/my-feature - 提交 Pull Request
注意事項:
- 遵循 PEP 8 程式碼規範
- 為新功能撰寫測試案例
- 保持零外部依賴原則
- 使用 Conventional Commits 規範提交資訊
本專案基於 MIT License 開源。
SpaceSense is a lightweight WiFi spatial intelligence sensing engine. It detects human presence, recognizes activities, and tracks movement by analyzing subtle changes in WiFi signal (RSSI) patterns — no cameras or visual sensors required, ensuring privacy by design.
Inspired by the trending GitHub project RuView, SpaceSense aims to provide a more lightweight and accessible alternative. Built entirely with the Python standard library, it has zero external dependencies and is ready to run out of the box.
Key Advantages:
- Privacy-First — No cameras involved; analyzes only WiFi signal variations
- Zero Dependencies — Pure Python standard library, no third-party packages needed
- Ready to Run — Clone and go; includes a demo mode for quick exploration
- Full-Featured — End-to-end solution from signal acquisition to analysis and alerting
| Module | Description |
|---|---|
| 📡 Signal Processing | Sliding window smoothing, Z-score outlier filtering, signal normalization |
| 👤 Presence Detection | Variance analysis, dynamic threshold adaptation, multi-sensor fusion |
| 🏃 Activity Recognition | 7 activity types: still / walking / running / sitting / approaching / leaving / falling |
| 🗺️ Zone Monitoring | Multi-zone simultaneous monitoring, inter-zone movement detection, dwell time tracking |
| 📊 Data Analysis | 12 statistical metrics, DTW pattern matching, trend detection |
| 🔔 Alert System | Multi-level alerts (info/warning/critical), rule engine, console / file / callback outputs |
| 💾 Data Export | CSV / JSON formats: signal data / analysis results / alert logs / statistics / comprehensive reports |
| 🖥️ TUI Dashboard | curses real-time visualization with automatic fallback to plain text |
- Python 3.8 or later
- No external dependencies required
# Clone the repository
git clone https://github.com/your-username/spacesense.git
cd spacesense
# No pip install needed — zero dependencies
python cli.py --versionThe fastest way to get started is the built-in demo mode, which generates simulated WiFi signal data to showcase all features:
# Run a 30-second mixed scenario demo
python cli.py demo --duration 30 --scenario mixed
# Run a 60-second walking scenario demo
python cli.py demo --duration 60 --scenario person_walkingStart real-time WiFi signal monitoring with a TUI dashboard displaying signal waveforms, presence detection results, activity recognition, zone status, and alerts.
# Basic usage
python cli.py monitor
# With a custom configuration file
python cli.py monitor --config my_config.json
# Adjust detection sensitivity (0.1 ~ 10.0)
python cli.py monitor --sensitivity 1.5
# Monitor specific zones
python cli.py monitor --zones living_room,bedroom,kitchen| Parameter | Shorthand | Description | Default |
|---|---|---|---|
--config |
-c |
Path to JSON configuration file | Built-in defaults |
--sensitivity |
-s |
Detection sensitivity (0.1 ~ 10.0) | Value from config |
--zones |
-z |
Comma-separated zone names | No zone monitoring |
Perform comprehensive offline analysis on existing signal data, including statistical metric computation, activity pattern matching, trend detection, and periodicity analysis.
# Analyze JSON signal data
python cli.py analyze --input data.json
# Analyze and export results
python cli.py analyze --input data.json --output analysis_report.json
# Analyze CSV signal data
python cli.py analyze --input signal_data.csv| Parameter | Shorthand | Description | Default |
|---|---|---|---|
--input |
-i |
Input data file (JSON array or CSV) | Required |
--output |
-o |
Output file path for analysis results | No export |
Supported Input Formats:
- JSON array:
[-55.0, -56.2, -54.8, ...] - JSON object array:
[{"rssi": -55.0}, {"rssi": -56.2}, ...] - CSV (one value per line):
-55.0\n-56.2\n-54.8\n...
Export signal data and statistics to CSV or JSON format for further processing and visualization.
# Export as CSV (default)
python cli.py export --input data.json --format csv
# Export as JSON
python cli.py export --input data.json --format json
# Specify output directory
python cli.py export --input data.json --format csv --output-dir ./my_exports| Parameter | Shorthand | Description | Default |
|---|---|---|---|
--input |
-i |
Input data file (JSON array or CSV) | Required |
--format |
-f |
Export format: csv or json |
csv |
--output-dir |
-d |
Output directory path | ./exports |
Run a full demonstration using simulated WiFi signal data. No real hardware required to experience all SpaceSense capabilities.
# Default 30-second mixed scenario
python cli.py demo
# Custom duration and scenario
python cli.py demo --duration 60 --scenario mixed
# Specific scenario
python cli.py demo --scenario person_running --duration 20| Parameter | Shorthand | Description | Default |
|---|---|---|---|
--duration |
-d |
Demo duration in seconds | 30 |
--scenario |
— | Simulation scenario: empty_room / person_still / person_walking / person_running / mixed |
mixed |
View, save, or reset SpaceSense configuration. Configuration uses JSON format and supports deep merging with defaults.
# View current configuration
python cli.py config --show
# View from a custom config file
python cli.py config --show --config my_config.json
# Export default configuration
python cli.py config --reset --output default_config.json
# Save current configuration
python cli.py config --config my_config.json --output saved_config.json| Parameter | Shorthand | Description | Default |
|---|---|---|---|
--show |
— | Display current configuration | Default behavior |
--reset |
— | Export default configuration | — |
--config |
-c |
Path to configuration file to load | — |
--output |
-o |
Output file path for configuration | — |
Design Principles:
- Minimalism — Clean code, clear interfaces, zero learning curve
- Privacy by Design — No visual data collection at the architecture level
- Standard Library First — No external dependencies for maximum compatibility
- Progressive Enhancement — Stable core features with optional advanced capabilities
Roadmap:
- v1.0.0 — Core Engine: signal processing, presence detection, activity recognition, zone monitoring
- v1.1.0 — Enhanced Analysis: ML classification models, adaptive threshold optimization
- v1.2.0 — Integration: MQTT push, Home Assistant plugin, REST API
- v2.0.0 — Distributed Architecture: multi-node collaborative sensing, time-series database support
spacesense/
├── __init__.py # Package initialization and public API exports
├── core.py # Core sensing engine (signal processing, presence detection, activity recognition, zone monitoring)
├── analyzer.py # Data analysis module (statistical analysis, pattern matching, trend detection)
├── alert.py # Alert management (multi-level alerts, rule engine, multi-channel output)
├── export.py # Data export (CSV / JSON, multiple report types)
├── tui.py # Terminal UI dashboard (curses real-time visualization)
├── config.py # Configuration management (JSON config, validation, deep merge)
└── utils.py # Utilities (color output, progress bars, etc.)
cli.py # Command-line interface
tests/
├── test_core.py # Core module tests
├── test_analyzer.py # Analyzer module tests
└── test_export.py # Export module tests
Contributions of all kinds are welcome! Please read the Contributing Guide before participating.
Quick Workflow:
- Fork this repository
- Create a feature branch:
git checkout -b feature/my-feature - Commit your changes:
git commit -m 'feat: add my feature' - Push the branch:
git push origin feature/my-feature - Submit a Pull Request
Guidelines:
- Follow PEP 8 coding conventions
- Write test cases for new features
- Maintain the zero external dependency principle
- Use Conventional Commits for commit messages
This project is licensed under the MIT License.