Skip to content

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

简体中文 | 繁體中文 | English


SpaceSense

轻量级 WiFi 空间智能感知引擎

通过分析 WiFi 信号变化实现人体存在检测、活动识别和空间感知,无需摄像头,保护隐私。

Python 3.8+ MIT License Zero Dependencies Tests Passing


简体中文

🎉 项目介绍

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

📖 详细使用指南

monitor — 实时监控模式

启动实时 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 逗号分隔的区域名称 无区域监控

analyze — 离线分析

对已有的信号数据进行全面离线分析,包括统计指标计算、活动模式匹配、趋势检测和周期性分析。

# 分析 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...

export — 数据导出

将信号数据和统计结果导出为 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 导出格式:csvjson csv
--output-dir -d 输出目录路径 ./exports

demo — 演示模式

使用模拟 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

config — 配置管理

查看、保存或重置 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   # 导出模块测试

🤝 贡献指南

我们欢迎任何形式的贡献!在参与之前,请阅读 贡献指南

快速流程:

  1. Fork 本仓库
  2. 创建特性分支:git checkout -b feature/my-feature
  3. 提交更改:git commit -m 'feat: add my feature'
  4. 推送分支:git push origin feature/my-feature
  5. 提交 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

📖 詳細使用指南

monitor — 即時監控模式

啟動即時 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 逗號分隔的區域名稱 無區域監控

analyze — 離線分析

對已有的訊號資料進行全面離線分析,包括統計指標計算、活動模式比對、趨勢偵測和週期性分析。

# 分析 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...

export — 數據匯出

將訊號資料和統計結果匯出為 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 匯出格式:csvjson csv
--output-dir -d 輸出目錄路徑 ./exports

demo — 演示模式

使用模擬 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

config — 設定管理

檢視、儲存或重設 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   # 匯出模組測試

🤝 貢獻指南

我們歡迎任何形式的貢獻!在參與之前,請閱讀 貢獻指南

快速流程:

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

注意事項:

  • 遵循 PEP 8 程式碼規範
  • 為新功能撰寫測試案例
  • 保持零外部依賴原則
  • 使用 Conventional Commits 規範提交資訊

📄 開源協議

本專案基於 MIT License 開源。


English

🎉 Introduction

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

✨ Core Features

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

🚀 Quick Start

Requirements

  • Python 3.8 or later
  • No external dependencies required

Installation

# Clone the repository
git clone https://github.com/your-username/spacesense.git
cd spacesense

# No pip install needed — zero dependencies
python cli.py --version

Run the Demo

The 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_walking

📖 Detailed Usage Guide

monitor — Real-Time Monitoring Mode

Start 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

analyze — Offline Analysis

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 — Data Export

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

demo — Demo Mode

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

config — Configuration Management

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 Philosophy & Roadmap

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

📦 Project Architecture

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

🤝 Contributing

Contributions of all kinds are welcome! Please read the Contributing Guide before participating.

Quick Workflow:

  1. Fork this repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Commit your changes: git commit -m 'feat: add my feature'
  4. Push the branch: git push origin feature/my-feature
  5. 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

📄 License

This project is licensed under the MIT License.

About

📡 SpaceSense - Lightweight WiFi Spatial Intelligence Sensing Engine | 轻量级WiFi空间智能感知引擎 - Presence Detection, Activity Recognition, Zone Monitoring, Zero Dependencies

Topics

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages